@tradik/xslt-processor 1.0.3 → 1.3.0

package/src/xslt/serializer/baseWriter.js

@@ -0,0 +1,390 @@
+/**
+ * Result Tree Writer
+ *
+ * Walks a result tree and turns it into markup. Everything that differs
+ * between the xml, xhtml and html output methods of XSLT 1.0 section 16 is
+ * delegated to the dialect hooks implemented by the concrete writers.
+ *
+ * The walk is iterative: the elements whose children are being written are
+ * frames on an explicit stack (see frames.js), so a result tree nested
+ * deeper than the JavaScript call stack allows (tens of thousands of
+ * levels, as deep template recursion builds) is written like any other.
+ */
+
+import { NODE_TYPE, TEXT_MODE, XMLNS_NAMESPACE } from "./constants.js";
+import { wrapCdata } from "./escape.js";
+import {
+  getOutputEncoding,
+  replaceUnencodable,
+  splitUnencodable,
+} from "./encoding.js";
+import {
+  collectNamespaceDeclarations,
+  createNamespaceScope,
+} from "./namespaces.js";
+import { getIndentableChildren } from "./indent.js";
+import { isRawText } from "./rawText.js";
+import { findRootElement } from "./settings.js";
+import { ChunkBuffer } from "./chunks.js";
+import { ContentFrame, IndentFrame, TopLevelFrame } from "./frames.js";
+
+/**
+ * Make comment text well-formed: XSLT 1.0 section 7.4 recovery inserts a
+ * space after any `-` followed by another `-` or ending the comment.
+ *
+ * @param {string} text - The comment text
+ * @returns {string} Text without `--` and without a trailing `-`
+ *
+ * @example
+ * safeCommentText("a--b-"); // "a- -b- "
+ */
+export function safeCommentText(text) {
+  return text.replace(/-(?=-|$)/g, "- ");
+}
+
+export class BaseWriter {
+  /**
+   * @param {object} settings - Normalized output settings
+   * @param {{xhtml?: boolean}} [options] - Dialect options
+   */
+  constructor(settings, options = {}) {
+    this.settings = settings;
+    this.xhtml = options.xhtml === true;
+    this.buffer = new ChunkBuffer();
+    this.encoding = getOutputEncoding(settings.encoding);
+    this.reference = (codePoint) => this.characterReference(codePoint);
+  }
+
+  /**
+   * Replace the characters the output encoding cannot represent with
+   * references (XSLT 1.0 section 16.1). Only escaped character data and
+   * attribute values go through here: comments, processing instructions and
+   * unescaped text cannot hold references and are written unchanged.
+   *
+   * @param {string} text - Escaped text or attribute value
+   * @returns {string} Text holding only representable characters
+   */
+  encodeReferences(text) {
+    return replaceUnencodable(text, this.encoding, this.reference);
+  }
+
+  /**
+   * Write text as CDATA sections. A character the output encoding cannot
+   * represent ends the section and is written as a reference between two
+   * sections, since a CDATA section cannot hold references.
+   *
+   * @param {string} value - Text content
+   * @returns {string} CDATA sections and references
+   */
+  cdataMarkup(value) {
+    return splitUnencodable(value, this.encoding)
+      .map(({ text, representable }) =>
+        representable ? wrapCdata(text) : this.reference(text.codePointAt(0)),
+      )
+      .join("");
+  }
+
+  /**
+   * Serialize a result tree node.
+   *
+   * @param {Node} node - Document, fragment or element to serialize
+   * @returns {string} Serialized output
+   */
+  serialize(node) {
+    let output = "";
+    for (const chunk of this.chunks(node, Infinity)) output += chunk;
+    return output;
+  }
+
+  /**
+   * Serialize a result tree node incrementally: a chunk is yielded as soon
+   * as `chunkSize` code units are written, so the first bytes are available
+   * before the whole tree has been written and the output is never held as
+   * one string.
+   *
+   * @param {Node} node - Document, fragment or element to serialize
+   * @param {number} [chunkSize] - Chunk size in UTF-16 code units (see
+   *   chunks.js); Infinity yields the whole output as one chunk
+   * @yields {string} Non-empty chunks of at most `chunkSize` code units (one
+   *   more when a surrogate pair straddles the boundary)
+   * @returns {Generator<string, void, void>} The chunks, in order
+   */
+  *chunks(node, chunkSize) {
+    this.buffer = new ChunkBuffer(chunkSize);
+    this.writeProlog(node);
+
+    const open = [];
+    const root = this.openNode(
+      node,
+      createNamespaceScope(),
+      0,
+      TEXT_MODE.ESCAPE,
+    );
+    if (root) open.push(root);
+
+    while (open.length > 0) {
+      const frame = open[open.length - 1];
+      const child = frame.nextChild(this);
+      if (child) {
+        const opened = this.openNode(
+          child,
+          frame.scope,
+          frame.depth,
+          frame.textMode,
+        );
+        if (opened) open.push(opened);
+      } else {
+        open.pop();
+        this.write(frame.end);
+      }
+      if (this.buffer.full) yield* this.buffer.take();
+    }
+    yield* this.buffer.take(true);
+  }
+
+  /**
+   * Append markup to the output.
+   *
+   * @param {string} text - Markup
+   * @returns {void}
+   */
+  write(text) {
+    this.buffer.write(text);
+  }
+
+  /**
+   * Write the XML declaration and the document type declaration.
+   *
+   * @param {Node} node - Result tree root
+   * @returns {void}
+   */
+  writeProlog(node) {
+    if (this.emitsXmlDeclaration) {
+      const { version, encoding, standalone } = this.settings;
+      const standalonePart = standalone ? ` standalone="${standalone}"` : "";
+      this.write(
+        `<?xml version="${version}" encoding="${encoding}"${standalonePart}?>\n`,
+      );
+    }
+
+    const doctype = this.doctypeMarkup(findRootElement(node));
+    if (doctype) {
+      this.write(`${doctype}\n`);
+    }
+  }
+
+  /**
+   * Start writing any result tree node. Leaves (character data, comments,
+   * processing instructions) are written at once; for an element with
+   * children or a result root, the start is written and the frame of its
+   * children is returned for the walk in {@link BaseWriter#chunks}.
+   *
+   * @param {Node} node - Node to write
+   * @param {Map<string, string>} scope - Namespace scope in effect
+   * @param {number} depth - Current indentation depth
+   * @param {string} textMode - {@link TEXT_MODE} for character data children
+   * @returns {object|null} The frame of the children (see frames.js), or
+   *   null when the node is written completely
+   */
+  openNode(node, scope, depth, textMode) {
+    switch (node.nodeType) {
+      case NODE_TYPE.ELEMENT:
+        return this.openElement(node, scope, depth);
+      case NODE_TYPE.TEXT:
+      case NODE_TYPE.CDATA_SECTION:
+        this.writeText(node, textMode);
+        break;
+      case NODE_TYPE.COMMENT:
+        this.write(`<!--${safeCommentText(node.nodeValue)}-->`);
+        break;
+      case NODE_TYPE.PROCESSING_INSTRUCTION:
+        this.writeProcessingInstruction(node);
+        break;
+      case NODE_TYPE.DOCUMENT:
+      case NODE_TYPE.DOCUMENT_FRAGMENT:
+        return new TopLevelFrame(
+          node,
+          scope,
+          depth,
+          textMode,
+          this.topLevelLineBreaks === true,
+        );
+      default:
+        break;
+    }
+    return null;
+  }
+
+  /**
+   * Write the start tag of an element with its namespaces and attributes,
+   * or the whole element when it is empty.
+   *
+   * @param {Element} element - Element to write
+   * @param {Map<string, string>} scope - Namespace scope inherited from the parent
+   * @param {number} depth - Current indentation depth
+   * @returns {object|null} The frame of its children, null when empty
+   */
+  openElement(element, scope, depth) {
+    const namespaces = collectNamespaceDeclarations(element, scope);
+    const name = element.nodeName;
+
+    this.write(
+      `<${name}${this.namespaceMarkup(namespaces.declarations, element)}` +
+        this.attributesMarkup(element),
+    );
+
+    const leading = this.leadingChildMarkup(element);
+    if (!element.firstChild && !leading) {
+      this.write(this.emptyElementMarkup(element, name));
+      return null;
+    }
+
+    this.write(">");
+    return this.childrenFrame(
+      element,
+      namespaces.scope,
+      depth,
+      leading,
+      `</${name}>`,
+    );
+  }
+
+  /**
+   * Frame of the children of an element, indenting element-only content.
+   *
+   * @param {Element} element - Parent element
+   * @param {Map<string, string>} scope - Namespace scope in effect
+   * @param {number} depth - Depth of the parent element
+   * @param {string} leading - Markup the serializer adds before the
+   *   children, indented like a child (see leadingChildMarkup)
+   * @param {string} endTag - End tag of the element
+   * @returns {ContentFrame|IndentFrame} The frame
+   */
+  childrenFrame(element, scope, depth, leading, endTag) {
+    const textMode = this.childTextMode(element);
+    const indentable = this.indentableChildren(element, textMode);
+
+    if (!indentable) {
+      this.write(leading);
+      return new ContentFrame(element, scope, depth, textMode, endTag);
+    }
+
+    const frame = new IndentFrame(indentable, scope, depth, textMode, endTag);
+    if (leading) this.write(frame.lineStart + leading);
+    return frame;
+  }
+
+  /**
+   * Determine the children to indent inside an element.
+   *
+   * @param {Element} element - Parent element
+   * @param {string} textMode - {@link TEXT_MODE} for character data children
+   * @returns {Node[]|null} Children to indent, or null when indenting is off
+   */
+  indentableChildren(element, textMode) {
+    if (!this.settings.indent || textMode !== TEXT_MODE.ESCAPE) {
+      return null;
+    }
+    if (!this.allowsIndentInside(element)) {
+      return null;
+    }
+    return getIndentableChildren(element);
+  }
+
+  /**
+   * Build the namespace declaration markup of an element.
+   *
+   * @param {Array<{prefix: string, uri: string}>} declarations - Declarations
+   * @param {Element} [_element] - The element they are written on
+   * @returns {string} Attribute markup, starting with a space when non-empty
+   */
+  namespaceMarkup(declarations, _element) {
+    return declarations
+      .map(({ prefix, uri }) => {
+        const name = prefix ? `xmlns:${prefix}` : "xmlns";
+        return ` ${name}="${this.escapeAttribute(uri)}"`;
+      })
+      .join("");
+  }
+
+  /**
+   * Build the attribute markup of an element, skipping namespace declarations.
+   *
+   * @param {Element} element - Element being written
+   * @returns {string} Attribute markup, starting with a space when non-empty
+   */
+  attributesMarkup(element) {
+    let markup = "";
+    for (const attribute of Array.from(element.attributes || [])) {
+      if (attribute.namespaceURI !== XMLNS_NAMESPACE) {
+        markup += this.attributeMarkup(attribute);
+      }
+    }
+    return markup;
+  }
+
+  /**
+   * Build the markup of a single attribute.
+   *
+   * @param {Attr} attribute - Attribute to write
+   * @returns {string} Attribute markup, starting with a space
+   */
+  attributeMarkup(attribute) {
+    return ` ${attribute.name}="${this.escapeAttribute(attribute.value)}"`;
+  }
+
+  /**
+   * Write a character data node.
+   *
+   * Nodes produced with `disable-output-escaping="yes"` are written verbatim.
+   *
+   * @param {Node} node - Text or CDATA section node
+   * @param {string} textMode - {@link TEXT_MODE} requested by the parent
+   * @returns {void}
+   */
+  writeText(node, textMode) {
+    const value = node.nodeValue || "";
+
+    if (isRawText(node)) {
+      this.write(value);
+      return;
+    }
+
+    const mode = this.resolveTextMode(node, textMode);
+    if (mode === TEXT_MODE.CDATA) {
+      this.write(this.cdataMarkup(value));
+    } else if (mode === TEXT_MODE.RAW) {
+      this.write(value);
+    } else {
+      this.write(this.escapeText(value));
+    }
+  }
+
+  /**
+   * Resolve the effective text mode of a character data node.
+   *
+   * @param {Node} node - Text or CDATA section node
+   * @param {string} textMode - {@link TEXT_MODE} requested by the parent
+   * @returns {string} A {@link TEXT_MODE} value
+   */
+  resolveTextMode(node, textMode) {
+    if (textMode !== TEXT_MODE.ESCAPE) {
+      return textMode;
+    }
+    return node.nodeType === NODE_TYPE.CDATA_SECTION
+      ? this.cdataNodeMode
+      : TEXT_MODE.ESCAPE;
+  }
+
+  /**
+   * Write a processing instruction node.
+   *
+   * @param {ProcessingInstruction} node - Node to write
+   * @returns {void}
+   */
+  writeProcessingInstruction(node) {
+    const data = node.nodeValue || "";
+    const separator = data ? " " : "";
+    this.write(`<?${node.target}${separator}${data}${this.piTerminator}`);
+  }
+}

package/src/xslt/serializer/chunks.js

@@ -0,0 +1,120 @@
+/**
+ * Output Chunking
+ *
+ * The serializers write markup into a {@link ChunkBuffer}, which hands it out
+ * in chunks of a bounded size: the streaming API (`serializeChunks`,
+ * `transformToStream`) yields each chunk as soon as it is full, while
+ * `serializeResult` uses an unbounded buffer and joins everything once. One
+ * writer implementation serves both.
+ *
+ * @module xslt/serializer/chunks
+ */
+
+/** Default chunk size, in UTF-16 code units (16 KiB of ASCII). */
+export const DEFAULT_CHUNK_SIZE = 16384;
+
+/**
+ * Validate a chunk size.
+ *
+ * @param {number} [size] - Requested size, {@link DEFAULT_CHUNK_SIZE} when absent
+ * @returns {number} A positive integer, or Infinity (one chunk)
+ * @throws {RangeError} For anything else
+ *
+ * @example
+ * toChunkSize(undefined); // 16384
+ */
+export function toChunkSize(size) {
+  if (size === undefined) return DEFAULT_CHUNK_SIZE;
+  if (size === Infinity || (Number.isInteger(size) && size > 0)) return size;
+  throw new RangeError(
+    `chunkSize must be a positive integer or Infinity, got ${size}`,
+  );
+}
+
+/**
+ * Whether a UTF-16 code unit is a high (leading) surrogate.
+ *
+ * @param {number} unit - The code unit
+ * @returns {boolean} True for U+D800..U+DBFF
+ */
+function isHighSurrogate(unit) {
+  return unit >= 0xd800 && unit <= 0xdbff;
+}
+
+/**
+ * End of the next chunk of `text` starting at `start`, moved so that a
+ * surrogate pair is never split (a chunk encoded on its own, e.g. with
+ * TextEncoder, would otherwise turn each half into U+FFFD).
+ *
+ * @param {string} text - The buffered text
+ * @param {number} start - Start of the chunk
+ * @param {number} size - Chunk size
+ * @returns {number} End of the chunk (exclusive)
+ */
+function chunkEnd(text, start, size) {
+  const end = start + size;
+  if (!isHighSurrogate(text.charCodeAt(end - 1))) return end;
+  return end - 1 > start ? end - 1 : end + 1;
+}
+
+export class ChunkBuffer {
+  /**
+   * @param {number} [chunkSize] - Chunk size in code units; Infinity keeps
+   *   everything for one final chunk
+   */
+  constructor(chunkSize = Infinity) {
+    this.chunkSize = toChunkSize(chunkSize);
+    this.parts = [];
+    this.length = 0;
+  }
+
+  /**
+   * Append text.
+   *
+   * @param {string} text - Markup or character data
+   * @returns {void}
+   */
+  write(text) {
+    this.parts.push(text);
+    this.length += text.length;
+  }
+
+  /**
+   * Whether at least one full chunk is buffered.
+   *
+   * @returns {boolean} True when {@link ChunkBuffer#take} would yield
+   */
+  get full() {
+    return this.length >= this.chunkSize;
+  }
+
+  /**
+   * Yield the buffered text as chunks of `chunkSize` code units (one more
+   * when a surrogate pair straddles the boundary). The last partial chunk is
+   * kept for later unless `final` is set.
+   *
+   * @param {boolean} [final] - Also yield the partial last chunk
+   * @yields {string} Non-empty chunks
+   * @returns {Generator<string, void, void>} The chunks
+   *
+   * @example
+   * const buffer = new ChunkBuffer(2);
+   * buffer.write("abcde");
+   * [...buffer.take(true)]; // ["ab", "cd", "e"]
+   */
+  *take(final = false) {
+    const text = this.parts.length === 1 ? this.parts[0] : this.parts.join("");
+    this.parts = [];
+    this.length = 0;
+    let start = 0;
+    while (text.length - start >= this.chunkSize) {
+      const end = chunkEnd(text, start, this.chunkSize);
+      yield text.slice(start, end);
+      start = end;
+    }
+    const rest = text.slice(start);
+    if (!rest) return;
+    if (final) yield rest;
+    else this.write(rest);
+  }
+}

package/src/xslt/serializer/constants.js

@@ -0,0 +1,92 @@
+/**
+ * Serializer Constants
+ *
+ * Shared node type codes, namespace URIs and HTML element tables used by the
+ * XSLT 1.0 output serializers (XSLT 1.0 section 16).
+ */
+
+/**
+ * DOM node type codes used by the serializers.
+ */
+export const NODE_TYPE = {
+  ELEMENT: 1,
+  TEXT: 3,
+  CDATA_SECTION: 4,
+  PROCESSING_INSTRUCTION: 7,
+  COMMENT: 8,
+  DOCUMENT: 9,
+  DOCUMENT_FRAGMENT: 11,
+};
+
+/**
+ * Namespace URI reserved for namespace declaration attributes.
+ */
+export const XMLNS_NAMESPACE = "http://www.w3.org/2000/xmlns/";
+
+/**
+ * Namespace URI bound to the reserved `xml` prefix.
+ */
+export const XML_NAMESPACE = "http://www.w3.org/XML/1998/namespace";
+
+/**
+ * How the text children of an element have to be written out.
+ */
+export const TEXT_MODE = {
+  ESCAPE: "escape",
+  CDATA: "cdata",
+  RAW: "raw",
+};
+
+/** Namespace of XHTML elements. */
+export const XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+
+/**
+ * HTML elements that never have an end tag.
+ */
+export const VOID_ELEMENTS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+
+/**
+ * HTML attributes holding URIs, which the html output method %-escapes
+ * (XSLT 1.0 section 16.2): the attributes libxml2 (and so Chrome) escapes,
+ * on any element. `name` is a URI attribute on `a` only (see
+ * {@link URI_ATTRIBUTES_OF_A}).
+ */
+export const URI_ATTRIBUTES = new Set(["action", "href", "src"]);
+
+/** Further URI attributes of the `a` element (libxml2). */
+export const URI_ATTRIBUTES_OF_A = new Set(["name"]);
+
+/**
+ * HTML elements whose character data must not be escaped.
+ */
+export const RAW_TEXT_ELEMENTS = new Set(["script", "style"]);
+
+/**
+ * HTML elements whose content must never be re-indented.
+ */
+export const PRESERVE_SPACE_ELEMENTS = new Set([
+  "pre",
+  "script",
+  "style",
+  "textarea",
+]);
+
+/**
+ * Indentation unit used when `indent="yes"` is requested.
+ */
+export const INDENT_UNIT = "  ";