@tradik/xslt-processor 1.0.3 → 1.3.0

package/src/xslt/serializer/encoding.js

@@ -0,0 +1,327 @@
+/**
+ * Output Encodings
+ *
+ * The `encoding` attribute of `xsl:output` names the character encoding of the
+ * serialized result. A character the encoding cannot represent is written as
+ * a character reference (XSLT 1.0 section 16.1: `€` in ISO-8859-1), so
+ * the serialized string only holds characters the declared encoding has, and
+ * turning it into bytes (see {@link encodeOutput}, used by the CLI) is
+ * lossless.
+ *
+ * Supported encodings:
+ * - UTF-8 and UTF-16 (every label TextDecoder maps to them) represent every
+ *   character; UTF-16 output starts with a byte order mark;
+ * - ISO-8859-1 / latin1 (up to U+00FF) and US-ASCII (up to U+007F), handled
+ *   here because the WHATWG Encoding Standard aliases both to windows-1252;
+ * - every other single-byte encoding known to TextDecoder (windows-125x,
+ *   ISO-8859-x, KOI8-R/U, IBM866, macintosh, ...): its repertoire is read
+ *   lazily by decoding the 256 byte values once;
+ * - multi-byte encodings other than UTF (Shift_JIS, EUC-JP, GBK, Big5, ...) and
+ *   unknown labels are treated as able to represent every character: no
+ *   character reference is written, and {@link encodeOutput} falls back to
+ *   UTF-8 bytes (`isExact` is false so callers can warn).
+ *
+ * @module xslt/serializer/encoding
+ */
+
+/** Labels of US-ASCII (IANA names and aliases). */
+const ASCII_LABELS = new Set([
+  "ascii",
+  "us-ascii",
+  "ansi_x3.4-1968",
+  "iso646-us",
+  "iso-ir-6",
+  "csascii",
+  "us",
+]);
+
+/** Labels of ISO-8859-1 (IANA names and aliases). */
+const LATIN1_LABELS = new Set([
+  "iso-8859-1",
+  "iso8859-1",
+  "iso88591",
+  "iso_8859-1",
+  "iso_8859-1:1987",
+  "latin1",
+  "l1",
+  "cp819",
+  "ibm819",
+  "csisolatin1",
+  "iso-ir-100",
+]);
+
+/** Canonical WHATWG names of the single-byte encodings. */
+const SINGLE_BYTE_ENCODINGS = new Set([
+  "ibm866",
+  "iso-8859-2",
+  "iso-8859-3",
+  "iso-8859-4",
+  "iso-8859-5",
+  "iso-8859-6",
+  "iso-8859-7",
+  "iso-8859-8",
+  "iso-8859-8-i",
+  "iso-8859-10",
+  "iso-8859-13",
+  "iso-8859-14",
+  "iso-8859-15",
+  "iso-8859-16",
+  "koi8-r",
+  "koi8-u",
+  "macintosh",
+  "windows-874",
+  "windows-1250",
+  "windows-1251",
+  "windows-1252",
+  "windows-1253",
+  "windows-1254",
+  "windows-1255",
+  "windows-1256",
+  "windows-1257",
+  "windows-1258",
+  "x-mac-cyrillic",
+]);
+
+/**
+ * @typedef {Object} OutputEncoding
+ * @property {string} name - Canonical name ("utf-8", "utf-16le", "iso-8859-1"...)
+ * @property {boolean} isUnicode - True when every character is representable
+ * @property {boolean} isExact - False when bytes fall back to UTF-8
+ * @property {Map<number, number>|null} bytes - Byte of every representable
+ *   code point, for single-byte encodings
+ */
+
+/** Encodings already resolved, by lower-cased label. */
+const cache = new Map();
+
+/**
+ * Build a single-byte encoding whose bytes map to the same code points.
+ *
+ * @param {string} name - Canonical name
+ * @param {number} last - Highest byte value (0x7F or 0xFF)
+ * @returns {OutputEncoding} The encoding
+ */
+function identityEncoding(name, last) {
+  const bytes = new Map();
+  for (let byte = 0; byte <= last; byte++) bytes.set(byte, byte);
+  return { name, isUnicode: false, isExact: true, bytes };
+}
+
+/**
+ * Build a single-byte encoding from the repertoire TextDecoder reports.
+ *
+ * @param {TextDecoder} decoder - Decoder of the encoding
+ * @returns {OutputEncoding} The encoding
+ */
+function tableEncoding(decoder) {
+  const bytes = new Map();
+  for (let byte = 0; byte <= 0xff; byte++) {
+    const codePoint = decoder.decode(Uint8Array.of(byte)).codePointAt(0);
+    if (codePoint !== 0xfffd && !bytes.has(codePoint)) {
+      bytes.set(codePoint, byte);
+    }
+  }
+  return { name: decoder.encoding, isUnicode: false, isExact: true, bytes };
+}
+
+/**
+ * Resolve an encoding label that is not ASCII or ISO-8859-1.
+ *
+ * @param {string} label - Lower-cased, trimmed label
+ * @returns {OutputEncoding} The encoding
+ */
+function resolveWithDecoder(label) {
+  let decoder;
+  try {
+    decoder = new globalThis.TextDecoder(label);
+  } catch {
+    return { name: label, isUnicode: true, isExact: false, bytes: null };
+  }
+  const name = decoder.encoding;
+  if (SINGLE_BYTE_ENCODINGS.has(name)) return tableEncoding(decoder);
+  const isExact = name === "utf-8" || name.startsWith("utf-16");
+  return { name, isUnicode: true, isExact, bytes: null };
+}
+
+/**
+ * Resolve the `encoding` of `xsl:output`.
+ *
+ * @param {string} [label] - Encoding label, UTF-8 when absent
+ * @returns {OutputEncoding} The encoding
+ *
+ * @example
+ * getOutputEncoding("ISO-8859-1").bytes.has(0x20ac); // false
+ */
+export function getOutputEncoding(label = "UTF-8") {
+  const key = String(label).trim().toLowerCase();
+  let encoding = cache.get(key);
+  if (!encoding) {
+    if (ASCII_LABELS.has(key)) encoding = identityEncoding("us-ascii", 0x7f);
+    else if (LATIN1_LABELS.has(key)) {
+      encoding = identityEncoding("iso-8859-1", 0xff);
+    } else encoding = resolveWithDecoder(key);
+    cache.set(key, encoding);
+  }
+  return encoding;
+}
+
+/**
+ * Numeric character reference of a code point.
+ *
+ * @param {number} codePoint - The code point
+ * @returns {string} `&#N;`
+ */
+export function characterReference(codePoint) {
+  return `&#${codePoint};`;
+}
+
+/** Characters outside ASCII, as whole code points. */
+const NON_ASCII = /[\u{80}-\u{10FFFF}]/gu;
+
+/**
+ * Replace every character an encoding cannot represent.
+ *
+ * Every supported encoding is a superset of ASCII, so only non-ASCII
+ * characters are checked.
+ *
+ * @param {string} text - Text to write
+ * @param {OutputEncoding} encoding - The output encoding
+ * @param {(codePoint: number) => string} [reference] - Replacement of an
+ *   unrepresentable code point; a numeric character reference by default
+ * @returns {string} Text holding only representable characters
+ *
+ * @example
+ * replaceUnencodable("€é", getOutputEncoding("latin1")); // "&#8364;é"
+ */
+export function replaceUnencodable(
+  text,
+  encoding,
+  reference = characterReference,
+) {
+  if (encoding.isUnicode) return text;
+  return text.replace(NON_ASCII, (character) => {
+    const codePoint = character.codePointAt(0);
+    return encoding.bytes.has(codePoint) ? character : reference(codePoint);
+  });
+}
+
+/**
+ * Split text into runs an encoding can and cannot represent, as needed to
+ * write a CDATA section, which cannot hold character references.
+ *
+ * @param {string} text - Text to write
+ * @param {OutputEncoding} encoding - The output encoding
+ * @returns {Array<{text: string, representable: boolean}>} The runs, in order;
+ *   an unrepresentable run holds one code point
+ */
+export function splitUnencodable(text, encoding) {
+  if (encoding.isUnicode) return [{ text, representable: true }];
+  const runs = [];
+  let start = 0;
+  for (const match of text.matchAll(NON_ASCII)) {
+    if (encoding.bytes.has(match[0].codePointAt(0))) continue;
+    if (match.index > start) {
+      runs.push({ text: text.slice(start, match.index), representable: true });
+    }
+    runs.push({ text: match[0], representable: false });
+    start = match.index + match[0].length;
+  }
+  if (start < text.length || runs.length === 0) {
+    runs.push({ text: text.slice(start), representable: true });
+  }
+  return runs;
+}
+
+/**
+ * Encode UTF-16 code units, after a byte order mark when requested.
+ *
+ * @param {string} text - Text to encode
+ * @param {boolean} bigEndian - Byte order
+ * @param {boolean} bom - Whether to start with a byte order mark
+ * @returns {Uint8Array} The bytes
+ */
+function encodeUtf16(text, bigEndian, bom) {
+  const offset = bom ? 2 : 0;
+  const bytes = new Uint8Array(offset + text.length * 2);
+  const view = new DataView(bytes.buffer);
+  if (bom) view.setUint16(0, 0xfeff, !bigEndian);
+  for (let i = 0; i < text.length; i++) {
+    view.setUint16(offset + i * 2, text.charCodeAt(i), !bigEndian);
+  }
+  return bytes;
+}
+
+/**
+ * Encode text with a single-byte encoding; a character without a byte
+ * (possible only in comments and processing instructions, which cannot hold
+ * references) becomes a character reference, as libxml2 does.
+ *
+ * @param {string} text - Text to encode
+ * @param {Map<number, number>} table - Byte of every representable code point
+ * @returns {Uint8Array} The bytes
+ */
+function encodeSingleByte(text, table) {
+  const bytes = [];
+  for (const character of text) {
+    const codePoint = character.codePointAt(0);
+    const byte = table.get(codePoint);
+    if (byte === undefined) {
+      for (const unit of characterReference(codePoint)) {
+        bytes.push(unit.charCodeAt(0));
+      }
+    } else {
+      bytes.push(byte);
+    }
+  }
+  return Uint8Array.from(bytes);
+}
+
+/**
+ * Create an encoder turning serialized output, chunk after chunk, into the
+ * bytes of its declared encoding: the concatenated bytes equal
+ * {@link encodeOutput} of the concatenated text, since only the first chunk
+ * gets the UTF-16 byte order mark (chunks never split a surrogate pair, see
+ * chunks.js).
+ *
+ * @param {string} [label] - The `xsl:output` encoding, UTF-8 when absent
+ * @returns {(text: string) => Uint8Array} The stateful encoder
+ *
+ * @example
+ * const encode = createOutputEncoder("UTF-16");
+ * encode("a"); // Uint8Array [0xff, 0xfe, 0x61, 0x00]
+ * encode("b"); // Uint8Array [0x62, 0x00]
+ */
+export function createOutputEncoder(label) {
+  const encoding = getOutputEncoding(label);
+  if (encoding.bytes) return (text) => encodeSingleByte(text, encoding.bytes);
+  if (encoding.name.startsWith("utf-16")) {
+    const bigEndian = encoding.name === "utf-16be";
+    let bom = true;
+    return (text) => {
+      const bytes = encodeUtf16(text, bigEndian, bom);
+      bom = false;
+      return bytes;
+    };
+  }
+  const encoder = new globalThis.TextEncoder();
+  return (text) => encoder.encode(text);
+}
+
+/**
+ * Turn serialized output into the bytes of its declared encoding.
+ *
+ * UTF-8 is written without a byte order mark, UTF-16 with one. Encodings
+ * without an encoder here (multi-byte encodings other than UTF, unknown
+ * labels) are written as UTF-8; `getOutputEncoding(label).isExact` is false
+ * for them.
+ *
+ * @param {string} text - Serialized output
+ * @param {string} [label] - The `xsl:output` encoding, UTF-8 when absent
+ * @returns {Uint8Array} The encoded bytes
+ *
+ * @example
+ * encodeOutput("é", "ISO-8859-1"); // Uint8Array [0xe9]
+ */
+export function encodeOutput(text, label) {
+  return createOutputEncoder(label)(text);
+}

package/src/xslt/serializer/escape.js

@@ -0,0 +1,135 @@
+/**
+ * Output Escaping Helpers
+ *
+ * Character escaping rules for the xml, xhtml and html output methods
+ * (XSLT 1.0 section 16).
+ */
+
+const XML_TEXT_ESCAPES = { "&": "&amp;", "<": "&lt;", "\r": "&#13;" };
+
+const HTML_TEXT_ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;" };
+
+const XML_ATTRIBUTE_ESCAPES = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "\t": "&#9;",
+  "\n": "&#10;",
+  "\r": "&#13;",
+};
+
+const HTML_ATTRIBUTE_ESCAPES = { "&": "&amp;", '"': "&quot;" };
+
+/**
+ * Replace every character matched by a pattern using a lookup table.
+ *
+ * @param {string} value - Text to escape
+ * @param {RegExp} pattern - Global pattern selecting the characters to replace
+ * @param {Record<string, string>} escapes - Character to replacement mapping
+ * @returns {string} Escaped text
+ */
+function escapeWith(value, pattern, escapes) {
+  return String(value).replaceAll(pattern, (character) => escapes[character]);
+}
+
+/**
+ * Escape character data for the xml output method.
+ *
+ * `>` is only escaped where it would close a CDATA section, matching the
+ * "minimal escaping" rule of XSLT 1.0 section 16.1. A carriage return is
+ * written as `&#13;`, as libxml2 does, since an XML parser would turn a
+ * literal one into a line feed.
+ *
+ * @param {string} value - Text content
+ * @returns {string} Escaped text
+ *
+ * @example
+ * escapeXmlText("a<b\r"); // "a&lt;b&#13;"
+ */
+export function escapeXmlText(value) {
+  return escapeWith(value, /[&<\r]/g, XML_TEXT_ESCAPES).replaceAll(
+    "]]>",
+    "]]&gt;",
+  );
+}
+
+/**
+ * Escape an attribute value for the xml output method.
+ *
+ * @param {string} value - Attribute value
+ * @returns {string} Escaped value
+ */
+export function escapeXmlAttribute(value) {
+  return escapeWith(value, /[&<>"\t\n\r]/g, XML_ATTRIBUTE_ESCAPES);
+}
+
+/**
+ * Escape character data for the html output method.
+ *
+ * @param {string} value - Text content
+ * @returns {string} Escaped text
+ */
+export function escapeHtmlText(value) {
+  return escapeWith(value, /[&<>]/g, HTML_TEXT_ESCAPES);
+}
+
+/**
+ * Escape an attribute value for the html output method.
+ *
+ * Only `&` and `"` are escaped: XSLT 1.0 section 16.2 keeps `<` unescaped
+ * and `&` unescaped before `{` (HTML 4.0 script macros), as libxslt does.
+ *
+ * @param {string} value - Attribute value
+ * @returns {string} Escaped value
+ *
+ * @example
+ * escapeHtmlAttribute('&{x} & <b> "'); // '&{x} &amp; <b> &quot;'
+ */
+export function escapeHtmlAttribute(value) {
+  return escapeWith(value, /&(?!\{)|"/g, HTML_ATTRIBUTE_ESCAPES);
+}
+
+/** Leading HTML whitespace, which libxml2 writes unescaped. */
+const LEADING_HTML_SPACE = /^[ \t\n\f\r]*/;
+
+/** Runs of spaces, control characters, DEL and characters outside ASCII. */
+const URI_UNSAFE_RUN = /[^!-~]+/gu;
+
+/**
+ * %-escape a URI attribute value as libxml2's HTML serializer does (and so
+ * Chrome's XSLTProcessor): after any leading HTML whitespace, which is kept,
+ * spaces, control characters, DEL and non-ASCII characters become the
+ * %-escaped bytes of their UTF-8 encoding (XSLT 1.0 section 16.2, HTML 4.01
+ * appendix B.2.1). Printable ASCII, `%` included, is kept as it is.
+ *
+ * @param {string} value - Attribute value
+ * @returns {string} The escaped value
+ *
+ * @example
+ * escapeUriAttribute("/café?q=a b"); // "/caf%C3%A9?q=a%20b"
+ */
+export function escapeUriAttribute(value) {
+  const text = String(value);
+  const leading = LEADING_HTML_SPACE.exec(text)[0];
+  const encoder = new globalThis.TextEncoder();
+  const rest = text
+    .slice(leading.length)
+    .replaceAll(URI_UNSAFE_RUN, (run) =>
+      Array.from(
+        encoder.encode(run),
+        (byte) => `%${byte.toString(16).toUpperCase().padStart(2, "0")}`,
+      ).join(""),
+    );
+  return leading + rest;
+}
+
+/**
+ * Wrap text in a CDATA section, splitting it around any `]]>` terminator.
+ *
+ * @param {string} value - Text content
+ * @returns {string} One or more CDATA sections
+ */
+export function wrapCdata(value) {
+  return `<![CDATA[${String(value).replaceAll("]]>", "]]]]><![CDATA[>")}]]>`;
+}

package/src/xslt/serializer/frames.js

@@ -0,0 +1,168 @@
+/**
+ * Open Node Frames
+ *
+ * The writer walks the result tree without recursion: every element (and
+ * the result root) whose children are being written is a frame on an
+ * explicit stack, so the depth of the tree is bounded by memory, not by the
+ * JavaScript call stack. A frame hands out its children one at a time
+ * ({@link ContentFrame#nextChild}) and knows the markup that closes it
+ * (`end`), written when it has no child left.
+ *
+ * Three kinds of content exist, as in XSLT 1.0 section 16 output:
+ * - {@link ContentFrame}: children written as they are, adjacent character
+ *   data joined into one CDATA section in `cdata-section-elements`;
+ * - {@link TopLevelFrame}: the children of the result root (document or
+ *   fragment), with libxslt's line break after a top-level comment;
+ * - {@link IndentFrame}: element-only content, each child on its own
+ *   indented line (`indent="yes"`).
+ *
+ * @module xslt/serializer/frames
+ */
+
+import { INDENT_UNIT, NODE_TYPE, TEXT_MODE } from "./constants.js";
+import { isRawText } from "./rawText.js";
+
+/**
+ * Children of a node written without adding whitespace.
+ *
+ * In CDATA mode (`cdata-section-elements`), adjacent character data nodes
+ * are one text node of the XPath data model, so they are written as one
+ * CDATA section, as libxslt does, not one section per DOM node; text
+ * written with `disable-output-escaping` ends the run.
+ */
+export class ContentFrame {
+  /**
+   * @param {Node} parent - Node whose children are written
+   * @param {Map<string, string>} scope - Namespace scope for the children
+   * @param {number} depth - Indentation depth of the children
+   * @param {string} textMode - {@link TEXT_MODE} for character data children
+   * @param {string} end - Markup written once every child is written
+   */
+  constructor(parent, scope, depth, textMode, end) {
+    this.scope = scope;
+    this.depth = depth;
+    this.textMode = textMode;
+    this.end = end;
+    this.next = parent.firstChild;
+    this.joinsText = textMode === TEXT_MODE.CDATA;
+  }
+
+  /**
+   * Whether a child joins the pending CDATA run instead of being written.
+   *
+   * @param {Node} child - Child node
+   * @returns {boolean} True for escaped character data in CDATA mode
+   */
+  joins(child) {
+    const type = child.nodeType;
+    return (
+      (type === NODE_TYPE.TEXT || type === NODE_TYPE.CDATA_SECTION) &&
+      !isRawText(child)
+    );
+  }
+
+  /**
+   * The next child to write. In CDATA mode the character data before it is
+   * written first, as one CDATA section.
+   *
+   * @param {import('./baseWriter.js').BaseWriter} writer - The writer
+   * @returns {Node|null} The child, or null when every child is written
+   */
+  nextChild(writer) {
+    let child = this.next;
+    if (this.joinsText) {
+      let run = "";
+      while (child && this.joins(child)) {
+        run += child.nodeValue;
+        child = child.nextSibling;
+      }
+      if (run) writer.write(writer.cdataMarkup(run));
+    }
+    this.next = child ? child.nextSibling : null;
+    return child;
+  }
+}
+
+/**
+ * Children of the result root (document or fragment). A line break follows
+ * a comment that another node follows when the dialect asks for it
+ * (`topLevelLineBreaks`); comments are leaves, so the break is written just
+ * before that next node.
+ */
+export class TopLevelFrame extends ContentFrame {
+  /**
+   * @param {Node} parent - The result root
+   * @param {Map<string, string>} scope - Namespace scope for the children
+   * @param {number} depth - Indentation depth of the children
+   * @param {string} textMode - {@link TEXT_MODE} for character data children
+   * @param {boolean} lineBreaks - Whether a top-level comment ends a line
+   */
+  constructor(parent, scope, depth, textMode, lineBreaks) {
+    super(parent, scope, depth, textMode, "");
+    this.lineBreaks = lineBreaks;
+    this.afterComment = false;
+  }
+
+  /**
+   * The next top-level node, preceded by a line break after a comment.
+   *
+   * @param {import('./baseWriter.js').BaseWriter} writer - The writer
+   * @returns {Node|null} The child, or null when every child is written
+   */
+  nextChild(writer) {
+    const child = super.nextChild(writer);
+    if (child && this.afterComment) writer.write("\n");
+    this.afterComment =
+      this.lineBreaks && child?.nodeType === NODE_TYPE.COMMENT;
+    return child;
+  }
+}
+
+/**
+ * Element-only content written with `indent="yes"`: each child starts a new
+ * line indented one level deeper than the parent, and the end tag of the
+ * parent starts a line at the parent's own indentation.
+ */
+export class IndentFrame {
+  /**
+   * @param {Node[]} children - Children to indent (see indent.js)
+   * @param {Map<string, string>} scope - Namespace scope for the children
+   * @param {number} depth - Indentation depth of the parent element
+   * @param {string} textMode - {@link TEXT_MODE} for character data children
+   * @param {string} endTag - End tag of the parent element
+   */
+  constructor(children, scope, depth, textMode, endTag) {
+    this.children = children;
+    this.index = 0;
+    this.scope = scope;
+    this.depth = depth + 1;
+    this.textMode = textMode;
+    this.lineStart = IndentFrame.lineStart(this.depth);
+    this.end = IndentFrame.lineStart(depth) + endTag;
+  }
+
+  /**
+   * A line break followed by the indentation of a depth.
+   *
+   * @param {number} depth - Indentation depth
+   * @returns {string} The line start
+   *
+   * @example
+   * IndentFrame.lineStart(2); // "\n    "
+   */
+  static lineStart(depth) {
+    return `\n${INDENT_UNIT.repeat(depth)}`;
+  }
+
+  /**
+   * The next child to write, on a new indented line.
+   *
+   * @param {import('./baseWriter.js').BaseWriter} writer - The writer
+   * @returns {Node|null} The child, or null when every child is written
+   */
+  nextChild(writer) {
+    if (this.index === this.children.length) return null;
+    writer.write(this.lineStart);
+    return this.children[this.index++];
+  }
+}