Whatxml NPM | npm.io

whatxml

XML/HTML templating with LiveScript's cascade syntax.

"What XML?" None, ever again.

x = whatxml \html
  .. \head
    .. \title ._ "My page"
    ..self-closing \link rel : \stylesheet type : \text/css href : \main.css
  .. \body
    .. \p ._ (.content)

console.log x.to-string { content : "Here's a paragraph." }

→

<html><head><title>My page</title><link rel="stylesheet" type="text/css" href="main.css" /></head><body><p>Here&#x27;s a paragraph.</p></body></html>

API summary

.. <string> [<attr-object>] adds a tag (with optional attributes)
..self-closing <string> [<attr-object>] same, but a self-closing tag
.. <object> sets attributes
.._ <string> adds text
..raw <string> adds text (without escaping it)
..comment <string> adds a comment

to-string recursively renders that tag's tree.

Any of the setters can also take a function parameter which is called with the value passed to to-string. It is expected to return the value that should be inserted at that point. (See § Templating.)

API tutorial

Basics

Create a root tag, call it with a string to create child tags, with an object to add attributes or call _ to add text between the tags.

gandalf = whatxml \person      # Create a root tag.
  .. { profession : \wizard }  # Set an attribute.
  .. \name                     # Add a child node.
    .._ "Gandalf"              # Put text in it.
console.log gandalf.to-string!

<person profession="wizard"><name>Gandalf</name></person>

Handy shortcut: When creating a tag, pass attributes as an object.

t = whatxml \tower lean : "3.99"
  .. \place city : "Pisa", country : "Italy"
console.log t.to-string!

<tower lean="3.99"><place city="Pisa" country="Italy"></place></tower>

Add self-closing tags and comments.

x = whatxml \a
  ..self-closing \b
  ..comment "what"
console.log x.to-string!

<a><b /><!--what--></a>

You can have stand-alone attributes without a value by setting them to true. (It's invalid XML, but fine in HTML.)

whatxml \input { +selected }
  ..to-string! |> console.log

<input selected></input>

Setting an attribute to another value overwrites the previous value. Setting attributes to false, null or undefined removes that attribute, if present.

Text is escaped automatically, but you can bypass that with raw if you have ready-escaped text (e.g. from marked).

greeting = whatxml \p
  .._ "What's up <3"
console.log greeting.to-string!

x = whatxml \p
  ..raw "<em>I know this is &gt; properly escaped already</em>"
console.log x.to-string!

<p>What&#x27;s up &#x3C;3</p>
<p><em>I know this is &gt; properly escaped already</em></p>

You can also have multiple top-level tags:

x = whatxml!
  .. \a
  .. \b
console.log x.to-string!

<a></a><b></b>

Templating

To generate content based on data, you can pass a function to any setter call. When a tag's to-string is called, the functions passed to its setters before are called with its arguments to produce the final value.

link = whatxml \a href : (.href)
  .._ (.name.to-upper-case!)

console.log link.to-string name : \google    href : "https://google.com"
console.log link.to-string name : \runescape href : "http://runescape.com"

<a href="https://google.com">GOOGLE</a>
<a href="http://runescape.com">RUNESCAPE</a>

Limitations

Check your XML comments are valid by the XML spec: They may not contain two consecutive hyphens (--). Whatxml doesn't check for you.

CDATA-sections and XML declarations (<?xml version="1.0"?> and such) aren't explicitly supported, but you can happily add them using raw.

Related libraries

Whatxml aims to be a serious general-purpose XML/HTML templating engine for LiveScript's syntax.

Existing attempts have their flaws:

live-templ came closest to my goals, but objects in nested arrays cannot represent comments, raw text data or self-closing tags. It also has no templating.
create-xml-ls is based on nested objects, so it can't represent two tags with the same name on the same level of nesting…
htmls supports only the base HTML tag set. Templating code is stringly typed and compiled separately.