whatxml
v1.4.0
Published
Construct XML (or (X)HTML) with LiveScript function calls
Downloads
11
Maintainers
Readme
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'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 > properly escaped already</em>"
console.log x.to-string!
<p>What's up <3</p>
<p><em>I know this is > 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.