(lispkit sxml)
Library (lispkit sxml) provides utility procedures for rendering SXML as XML, HTML, or plain text. SXML is a representation of XML/HTML documents (and, more generally, of markup-oriented tree structures) as plain S-expressions. Libraries (lispkit sxml xml) and (lispkit sxml html) provide parsers that turn XML respectively HTML source text into SXML; this library provides the inverse direction as well as a few text-rendering and escaping utilities that are shared between the two parser libraries.
SXML representation
An SXML node is one of the following:
An element: a list whose first element (the head) is a symbol denoting the tag name, optionally followed by an attribute list as the first child, followed by zero or more child nodes. An attribute list is a list headed by the symbol
@, containing(name value)(or, more generally,(name . value)) pairs, e.g.(a (@ (href "https://example.org")) "Example")represents<a href="https://example.org">Example</a>.An element without an attribute list and without children, e.g.
(br), is rendered as a self-closing tag, e.g.<br/>. An element with an attribute list but no further children, e.g.(img (@ (src "logo.png"))), is rendered with a separate closing tag, e.g.<img src="logo.png"></img>.A text node: typically a string, but any LispKit object for which a textual representation exists can be used as a leaf of an SXML tree (see below).
A
@rawnode, e.g.(@raw "<b>already escaped</b>"), whose single string child is inserted verbatim into the output without any escaping. This is useful for embedding pre-rendered or externally sanitized markup.A sequence of SXML nodes represented as a list not starting with a symbol; the elements of the list are processed in order as if they were siblings.
Besides strings, the following LispKit objects can be used as SXML text nodes and are converted into their textual representation automatically: #f (rendered as the empty string), characters, symbols, numbers, styled text objects (see (lispkit styled-text)), date/time objects (see (lispkit date-time)), vectors, as well as Markdown blocks, block sequences and inline text objects (see (lispkit markdown)), which get rendered via the corresponding Markdown-to-HTML conversion. A full markdown document object embedded into an SXML tree is likewise converted to HTML.
Parsers such as xml->sxml (from (lispkit sxml xml)) and html->sxml (from (lispkit sxml html)) wrap the parsed document in a top-level *TOP* element, i.e. (*TOP* node ...).
Rendering SXML
(display-sxml sxml) [procedure] (display-sxml sxml port)
Renders the (valid, expanded) SXML tree sxml as XML/HTML markup to output port port. If port is not provided, display-sxml writes to the current output port (as defined by current-output-port of library (lispkit port)). An element without an attribute list and without children is rendered as a self-closing tag; an element with an attribute list but no further children is rendered with a separate closing tag. A @raw node is considered to already be safe markup; its content is written to port without any escaping. All other text is HTML-escaped before it is written to port.
(display-sxml-text sxml) [procedure] (display-sxml-text sxml port)
Renders the SXML tree sxml as plain text suitable for display in a terminal, writing the result to output port port (or to the current output port if port is not provided). All markup is stripped. head, style, and script elements are skipped entirely (together with their content). A newline is inserted after p, li, br, and h1 to h6 elements to preserve some of the visual structure of the original document.
(sxml->xml sxml) [procedure]
Returns a string containing the XML markup for the SXML tree sxml, as generated by display-sxml.
(sxml->html sxml) [procedure]
Returns a string containing the HTML markup for the SXML tree sxml, as generated by display-sxml.
(sxml->text sxml) [procedure]
Returns a string containing a plain-text rendering of the SXML tree sxml, as generated by display-sxml-text.
(sxml-strip sxml) [procedure]
Returns a string consisting of the concatenation of all string-valued leaves contained in the SXML tree sxml, with all tags and non-string leaves (such as numbers or symbols) removed. Unlike sxml->text, sxml-strip performs no formatting; it simply concatenates the string content of the tree in document order. Note that sxml-strip does not special-case @ attribute lists, so string-valued attribute values contribute to the result as well.
Escaping utilities
(html-escape obj) [procedure]
Returns a string containing the HTML-escaped textual representation of obj. obj can be a string or any other object that can be used as an SXML text node (see above). All characters requiring an HTML entity encoding (such as <, >, &, or non-ASCII characters with a named HTML entity) are replaced by their corresponding named character references.
(html-tag->string tag attrs) [procedure]
Returns a string with the opening tag for element name tag (a symbol) with attribute list attrs. attrs is a list of (name value) pairs, matching the representation used for the @ attribute list of an SXML element. If an attribute is given as an improper pair (name . #f), it is rendered as a boolean attribute, i.e. just its name is written without a value. Attribute values are HTML-escaped.
Last updated