#html API reference

Build an HTML element tree and render it to a correctly escaped HTML5 string. Pure Jennifer over strings and lists - a writer, not a parser, so it has no dependency on an XML parser: serialization is a handful of string operations. The shared output layer any HTML-emitting consumer reuses (a Markdown renderer, a documentation generator, a view layer). Text nodes are escaped on render (& < >); attribute values also escape "; a raw node passes through verbatim for already-trusted markup. Void elements (br, img, ...) render without a closing tag and drop children.

Import with import "html.j" as html;. See the html guide for prose and examples.

#Functions

#html.attr(name as string, value as string)

Build one name/value attribute for an element.

Parameters

• name {string} - the attribute name
• value {string} - the attribute value

Returns {Attr} - the attribute

#html.attrOf(node as Node, name as string)

The value of an element's attribute by name, or "" if it has no such attribute. (Read .attrs directly for the full list.)

Parameters

• node {Node} - the element node
• name {string} - the attribute name

Returns {string} - the attribute value, or ""

#html.boolAttr(name as string)

Build a boolean (valueless) HTML attribute - disabled, checked, selected, required, readonly, multiple, autofocus, and the like. It renders as the bare name (<input disabled>), not name="". The name is validated exactly as attr validates it.

Parameters

• name {string} - the attribute name

Returns {Attr} - the boolean attribute

#html.element(tag as string, attrs as list of Attr, children as list of Node)

Build an element node from a tag, its attributes, and its children. Pass [] for either when there are none.

Parameters

• tag {string} - the element tag name
• attrs {list of Attr} - the element's attributes
• children {list of Node} - the element's child nodes

Returns {Node} - the element node

#html.escape(s as string)

Return s with the text-context HTML metacharacters replaced by entities (& first, so an escaped entity is not re-escaped). Public because escaping a bare string for HTML text is useful without building a node.

Parameters

• s {string} - the string to escape

Returns {string} - the escaped string

#html.findAll(node as Node, selector as string)

Every element matching an XPath-ish selector relative to node: /-separated steps, each a tag name, * (any element), or name[k] (the k-th such child, 1-based). Steps match direct element children; text nodes are skipped.

Parameters

• node {Node} - the node to search under
• selector {string} - the selector path (e.g. "body/ul/li")

Returns {list of Node} - the matching element nodes (empty if none)

#html.get(node as Node, selector as string)

The first element matching selector (see findAll), or an empty element node (.tag == "") if there is no match.

Parameters

• node {Node} - the node to search under
• selector {string} - the selector path

Returns {Node} - the first match, or an empty element node

#html.has(node as Node, selector as string)

Whether any element matches selector (see findAll).

Parameters

• node {Node} - the node to search under
• selector {string} - the selector path

Returns {bool} - true if at least one element matches

#html.hasAttr(node as Node, name as string)

Whether an element has an attribute by name (including a valueless boolean one).

Parameters

• node {Node} - the element node
• name {string} - the attribute name

Returns {bool} - true if present

#html.parse(src as string)

Parse an HTML string into a Node tree. The result is a synthetic #root element whose children are the document's top-level nodes; walk it with .children / get / findAll, and re-serialize any node with render. Tolerant of real-world HTML (void / self-closing tags, unquoted attributes, mismatched nesting, comments, DOCTYPE, script / style raw text).

Parameters

• src {string} - the HTML source

Returns {Node} - the #root element containing the parsed top-level nodes

Throws

• {Error} - kind "html" if the document exceeds the depth or node budget

#html.raw(s as string)

Build a node whose content is emitted verbatim - for already-trusted markup only, since it is not escaped.

Parameters

• s {string} - the verbatim markup

Returns {Node} - the raw node

#html.render(node as Node)

Serialize a node and its subtree to an HTML5 string.

Parameters

• node {Node} - the node to render

Returns {string} - the rendered HTML

#html.renderAll(nodes as list of Node)

Serialize a list of sibling nodes (a fragment) in order.

Parameters

• nodes {list of Node} - the sibling nodes

Returns {string} - the rendered HTML fragment

#html.safeUrl(url as string)

Return a URL safe to place in an href / src attribute, or "#" if its scheme is not one of http / https / mailto. Whitespace and control characters are ignored while reading the scheme (so "java\tscript:..." is still caught), and a relative reference (no scheme) is returned unchanged. This is the anti-XSS gate for building links from untrusted input.

Parameters

• url {string} - the URL to check

Returns {string} - the URL if its scheme is allowed, else "#"

#html.text(s as string)

Build a text node; its content is HTML-escaped on render.

Parameters

• s {string} - the text content

Returns {Node} - the text node

#html.unescape(s as string)

Decode the common HTML entities in a string - < / > / " / ' / ' / & to their characters - the inverse of escape. & is decoded last, so < yields the literal <, not <. A string with no & is returned unchanged.

Scope is deliberately the metacharacter entities only: the ones any standard text-context escaper (including this module's escape / escapeAttr) emits, so a round-trip is exact. It is not a general HTML5 entity decoder - the ~2000 named references for authoring (  / © / — / ...) and numeric refs (—) are out of scope, since decoding those means shipping the full named table plus numeric parsing, not the metacharacter round-trip this serves.

Parameters

• s {string} - the text to decode

Returns {string} - the decoded text

#Structs

#html.Attr

One HTML attribute. A normal attribute has a name and a value and renders as name="value"; a boolean attribute (boolean: true, built by boolAttr) carries no value and renders as the bare name (disabled, checked, ...).

#html.Node

A node is one of three kinds, tagged by kind: "element" (tag + attrs + children), "text" (escaped content), or "raw" (verbatim content). The constructors below are the intended way to build one.

#Enums

#html.NodeKind

The kind of an HTML node: Element (a tag with attributes and children), Text (escaped text content), or Raw (verbatim, already-trusted markup).