{ } qjs-modules

xml

Source: quickjs-xml.c — module exports XMLParser, XMLPushParser, XMLTreeSerializer, XMLWriter and a function list.

An XML/HTML reader and writer. Parses markup into a tree (or flat list) of plain JS objects and serializes such a tree back to text. Element objects are {tagName, attributes, children}-shaped.

Module functions

FunctionArgsDescription
read(input, inputName?, options?)1–3Parses XML/HTML text into an array/tree of element objects. input is a string or buffer. inputName is an optional filename for error messages. options is either a boolean (flat mode) or an object with flat, tolerant, location, and selfClosingTags (array of void-element tag names). When location is true, returns [tree, locationMap] instead of just the tree.
write(value, maxDepth?)1–2Serializes a parsed tree (or flat list) back into XML/HTML text. maxDepth limits traversal depth (default: unlimited). See "Layout of write()" below.

Both are also reachable through the module's default export object.

read() is built on the event parser of src/xml.c (the one behind XMLParser), so the three agree:

BehaviourRule
tolerant modea stray closing tag is ignored (the > after it stays text); an open <li>, <dt>, <dd>, <p>, <option>, <tr>, <td>, <th>, <tbody>... is closed when a sibling starts, and <p>, <li>, <dt>, <dd> also when a block element starts
flat: trueno element stack and no implied ends: every closing tag, matched or not, is an entry {tagName: '/name'}
texta run of only whitespace is dropped; otherwise just the writer's structural newlines around the content are stripped
<style>, <script>, <textarea>, <title>content is raw text, one string per line
</>closes nothing
input ending inside a tagthe tag is dropped (an unterminated comment or declaration keeps the rest as its tagName)

Layout of write()

write() pumps the element-tree walker (include/xml/xwalk.h) into an XmlWriter with XW_PRETTY (indent 2, no trailing newline, text-only and mixed content stay on one line). An element cut by maxDepth is written empty (<b />). Both shapes of read() are accepted; a list whose last entry has no children array is a flat list.

ruletreeflat list
indent2 spaces per level; the children of a root element are at level 0the level moves after a dt start tag and back at a /x marker
self-closing <a />children missing or emptythe next entry is its own /a marker (dropped), or a is the last entry
textmultiline (own line) when its list has more than one entry; otherwise it follows the tag directly and trailing whitespace before it is droppedmultiline when it contains a newline
maxDepthan element cut off is written with > and no close tagnot used
comment <!-- -->, <!x>, <?x?>raw name, no attributes; ? names never get a close tagsame
final newlinetrimmedkept

Text and attribute values are escaped (& < >, and " in attributes); an attribute value true is written bare.

XMLParser.next() and for..of

next() returns the next event as { type, name?, value?, loc: { line, column } } and the parser is iterable. Markup arrives typed: COMMENT (5), DECLARATION (6), INSTRUCTION (7) and CDATA (8) carry their text in value. A mismatched closing tag throws the SyntaxError.

Parser options

xml.read(text, name, options) and new XMLParser(input, options) share one option reader: { flat, tolerant, selfClosingTags, filename }, and location for read(). XMLParser has no default self-closing tags (read() uses the HTML ones). strict and entities are not implemented, they wait for the engine.

Connecting engines: pump(), connect(), tee, XmlBuilder

Every source runs into every sink in C. A sink is an XMLWriter, an XmlBuilder, a tee(...) or any object with the sink methods (elementStart, attribute, elementEnd, text, comment, declaration, instruction, cdata, error).

import { XMLParser, XMLPushParser, XmlBuilder, XMLWriter, tee } from 'xml';

const b = new XmlBuilder({ flat: false, plain: true });
new XMLParser('<a><b/></a>').pump(b);                 // 0 = ended, 1 = the reader has no data now
b.finish().root;                                      // [{tagName: 'a', attributes: {}, children: [...]}]

new XMLPushParser().connect(tee(b, new XMLWriter(sink))).write('<a/>');
MemberDoes
parser.pump(sink)runs the pull parser into the sink; markup arrives typed. Throws the SyntaxError of a mismatched tag
pushParser.connect(sink) / .sinkwrite() and close() drive the sink; returns the parser
tee(a, b, ...)a sink that sends every event to each, in order
new XmlBuilder({flat, plain})root, path, finish(), the sink methods
[Symbol.for('qjs.xmlsink')]()handshake of the native sinks, as in json

The sink interface has no self-closing flag, so a tree built through a sink gives <b/> an empty children like <b></b>; read() keeps the difference.

XMLParser

An incremental pull parser. next() and the iterator give the events above, pump(sink) runs it into a sink in C.

new XMLParser(input, options?)   // input is a buffer/string or a reader; options: see Parser options

input may be:

  • a buffer (string, ArrayBuffer, or typed array) holding the whole document, or
  • a pull function (buf, len) => bytesRead, called as needed to fill buf, or
  • an object exposing such a function as its read method.

The iteration ends when the document is complete or the reader has no data now (call next() again once it might). The type of an event is one of these constants, static properties of the constructor:

ConstantValuenamevalue
XMLParser.ELEMENT_START1tag name
XMLParser.ATTRIBUTE2attribute namethe value, undefined for a boolean attribute
XMLParser.ELEMENT_END3tag name
XMLParser.TEXT4the text run
XMLParser.COMMENT5the text
XMLParser.DECLARATION6the text
XMLParser.INSTRUCTION7the text
XMLParser.CDATA8the text
MemberArgsKindDescription
next()0methodThe next event { type, name?, value?, loc }, as an iterator result.
pump(sink)1methodRuns the parser into a sink, returns 0 when the input ended, 1 when the reader has no data now.
depth—getterCurrent element nesting depth (enumerable).
location—getterA Location reflecting the current input position (line/column/byte offset/filename), live (enumerable).
tolerant—getter/setterWhen true, mismatched closing tags are silently skipped instead of throwing.
import { XMLParser } from 'xml';

for(const { type, name, value } of new XMLParser('<root attr="val"><child>text</child></root>')) console.log(type, name, value);
// 1 root  2 attr val  1 child  4 undefined text  3 child  3 root

XMLPushParser

A "push" XML parser: instead of pulling from an input, data is fed to it via .write() at any byte boundary. It can operate in two modes:

  • Callback mode: when the constructor options define any of attribute, elementStart, elementEnd, text, or error as functions, those callbacks are invoked for each event.
  • Builder mode (default): when no callbacks are given, it builds a `{tagName, attributes, children}tree internally, retrievable via.root`.
new XMLPushParser(options?)   // options may define callbacks; also serves as `this` for callback invocations
MemberArgsKindDescription
write(chunk)1methodFeeds a chunk of XML input (string or buffer). In builder mode, throws a SyntaxError on malformed input. In callback mode, the error callback is invoked instead.
close()0methodSignals end of input. In builder mode, throws if the document is incomplete (unclosed elements).
root—getterThe {tagName, attributes, children} tree built so far (builder mode only).
path—getterArray of tagName strings from the document root down to the currently-open element, root-first (builder mode only).
import { XMLPushParser } from 'xml';

let p = new XMLPushParser();

p.write('<root><child attr="v');
p.write('alue">text</child></root>');
p.close();

console.log(p.root);
// [{ tagName: "root", attributes: {}, children: [{ tagName: "child", attributes: { attr: "value" }, children: ["text"] }] }]

XMLTreeSerializer

A "pull" serializer: it traverses a parsed tree lazily, producing only as much text as requested per .read() call, rather than building the whole string up front. Modeled on JsonSerializer (quickjs-json.c).

new XMLTreeSerializer(root)   // root is a tree array or a single element object
MemberArgsKindDescription
read(n)1methodReturns a string of up to n characters of serialized XML, '' once exhausted.
read(buffer, offset?, length?)1–3methodWrites serialized bytes directly into the given ArrayBuffer/TypedArray (zero-copy), starting at offset for up to length bytes — or the whole buffer if omitted. Returns the number of bytes written, 0 once exhausted.
root—getterThe root value being serialized.
finished—gettertrue once all output has been produced.
import { XMLTreeSerializer } from 'xml';

let tree = xml.read('<root><child attr="val">text</child></root>');
let s = new XMLTreeSerializer(tree);
let out = '';
let chunk;

while((chunk = s.read(32)) !== '') out += chunk;

console.log(out); // <root><child attr="val">text</child></root>
// Zero-copy: write straight into a fixed-size buffer.
let s = new XMLTreeSerializer(bigTree);
let buf = new Uint8Array(4096);
let n;

while((n = s.read(buf)) > 0) socket.send(buf.subarray(0, n));

XMLWriter

An event-driven XML writer: instead of serializing a tree, the caller drives output by calling elementStart(), attribute(), text(), and elementEnd() in document order. Output goes to a Writer (from stream-utils.h) — a buffer, fd, or any writable sink. Handles indentation automatically.

The methods are the XmlEventSink interface (include/xml/xsink.h, the twin of the walk interface), so the same object can be handed to anything that drives an XmlEventSink; failures carry a stable err.code (mismatched-end-tag, unmatched-end-tag, attribute-outside-tag, write-failed).

new XMLWriter(output, options?)   // output is a buffer or writer; options may be a number (indent) or {indent}

output may be:

  • a writable buffer (ArrayBuffer, typed array), or
  • an object exposing a write(buf, offset, length) method, or
  • omitted, in which case an internal buffer is used.

options is either a number (the indent width, default 2) or an object with an indent property.

MemberArgsKindDescription
elementStart(name)1methodWrites <name. Increments the nesting level. Returns bytes written.
attribute(name, value?)1–2methodWrites name="value". If value is omitted or true, writes a boolean/valueless attribute (name only). Returns bytes written.
elementEnd(name?)0–1methodIf called right after elementStart()/attribute() (no text or child elements in between), writes /> (self-closing). Otherwise writes </name>. Decrements the nesting level. Returns bytes written.
text(content)1methodWrites text content. Returns bytes written.
comment(str)1methodWrites <!--str-->.
cdata(str)1methodWrites <![CDATA[str]]>.
instruction(str)1methodWrites <?str?>.
declaration(str)1methodWrites <!str>.
error(str)1methodWrites nothing (the output has no form for an error); returns 0.
state—getterThe event type of the last method call (an XmlEventType integer).
written—getterTotal number of bytes written so far.
indent—getter/setterThe indentation width (number of spaces per level).
import { XMLWriter } from 'xml';

let buf = new Uint8Array(1024);
let w = new XMLWriter(buf);

w.elementStart('root');
  w.elementStart('child');
    w.attribute('attr', 'val');
    w.text('hello');
  w.elementEnd('child');
w.elementEnd('root');

let text = new TextDecoder().decode(buf.subarray(0, w.written));
console.log(text);
// <root>
//   <child attr="val">hello</child>
// </root>

Export list

Generated by utilities/doc-api.js from the xml dump of utilities/api-surface.sh: 71 members. Edit the text above this block, not the block.

Functions: read(), tee(), write()

XMLParser

class, constructible

  • static values: ATTRIBUTE = 2, CDATA = 8, COMMENT = 5, DECLARATION = 6, ELEMENT_END = 3, ELEMENT_START = 1, INSTRUCTION = 7, TEXT = 4
  • methods: next(), pump(), [Symbol.iterator]()
  • properties: depth (get), location (get), tolerant (get/set), [Symbol.toStringTag]

XMLPushParser

class, constructible

  • methods: close(), connect(), write()
  • properties: error (get), path (get), root (get), sink (get), [Symbol.toStringTag]

XMLTreeSerializer

class, constructible

  • methods: read()
  • properties: finished (get), root (get), [Symbol.toStringTag]

XMLWriter

class, constructible

  • methods: attribute(), cdata(), comment(), declaration(), elementEnd(), elementStart(), error(), instruction(), text(), [Symbol.for('qjs.xmlsink')]()
  • properties: indent (get/set), state (get), written (get), [Symbol.toStringTag]

XmlBuilder

class, constructible

  • methods: attribute(), cdata(), comment(), declaration(), elementEnd(), elementStart(), error(), finish(), instruction(), text(), [Symbol.for('qjs.xmlsink')]()
  • properties: path (get), root (get), [Symbol.toStringTag]

default

object

  • static methods: read(), write()