#xml

Source: quickjs-xml.c — module exports XMLParser, XMLNodeParser, XMLPushParser, XMLSerializer, 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

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

#XMLParser

An incremental pull parser built on Reader/Location from stream-utils.h and include/xml.h's xml_parser_run(). Each call to .parse() advances just far enough to produce one event (or a status code) and also feeds every element/attribute/text event into an internal XMLBuilder, so .root gives the tree built so far without the caller having to do that bookkeeping.

new XMLParser(input, options?)   // input is a buffer/string or a reader; options may carry callbacks and filename

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.

options is an object. If it defines any of the callback properties (elementStart, elementEnd, attribute, text, error), events are forwarded to those callbacks instead of being fed into the builder. It may also carry a filename string for .location.

.parse() returns one of the following integer constants (exposed as static properties on the constructor):

import { XMLParser } from 'xml';

let p = new XMLParser('<root attr="val"><child>text</child></root>');
let ev;

while((ev = p.parse()) > 0) {
  if(ev === XMLParser.ELEMENT_START) console.log('start', p.eventName);
  if(ev === XMLParser.ATTRIBUTE)     console.log('attr', p.eventName, '=', p.eventValue);
  if(ev === XMLParser.TEXT)          console.log('text', p.eventValue);
  if(ev === XMLParser.ELEMENT_END)   console.log('end', p.eventName);
}
// start root  attr attr = val  start child  text text  end child  end root

#XMLNodeParser

A pull parser that yields one "flat list" node per .parse() call. Returns JS strings for text content, and JS objects {tagName, attributes} for start tags (end tags have a tagName prefixed with /). Unlike XMLParser, each call returns a complete node rather than individual events — attributes are collected internally and attached to the start-tag object before it is returned.

new XMLNodeParser(input, options?)   // input is a buffer/string or a reader; options may carry filename

input and the reader conventions are the same as XMLParser. options is an object that may carry a filename string for .location.

.parse() returns:

• A JS string for text content.
• A JS object {tagName, attributes} for a start tag (attributes are collected before returning).
• A JS object {tagName} with tagName prefixed by / for an end tag.
• An integer status code (PARSE_AGAIN, PARSE_ERROR, PARSE_OK) — same constants as XMLParser.

import { XMLNodeParser } from 'xml';

let p = new XMLNodeParser('<ul><li>hello</li></ul>');
let node;

while((node = p.parse()) > 0) {
  if(typeof node === 'string')       console.log('text:', node);
  else if(node.tagName[0] === '/')   console.log('close:', node.tagName);
  else                               console.log('open:', node.tagName, node.attributes);
}
// open: ul {}  open: li {}  text: hello  close: /li  close: /ul

#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

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"] }] }]

#XMLSerializer

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 XMLSerializer(root)   // root is a tree array or a single element object

import { XMLSerializer } from 'xml';

let tree = xml.read('<root><child attr="val">text</child></root>');
let s = new XMLSerializer(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 XMLSerializer(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.

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.

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>