@tradik/xslt-processor 1.0.3 → 1.3.0

package/src/xslt/engine/numbering.js

@@ -0,0 +1,104 @@
+/**
+ * xsl:number (XSLT 1.0 section 7.7) and the number formatting helpers.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { countXsltNumber, isMemoizable } from "../number.js";
+import { formatXsltNumber, toRoman } from "../numberFormat.js";
+
+/**
+ * The numbers an xsl:number instruction formats: its rounded `value`, else
+ * the position of the current node counted by level, count and from.
+ *
+ * @param {object} engine - The engine
+ * @param {Element} node - The xsl:number instruction
+ * @param {XsltContext} context - The current context
+ * @returns {number[]} The numbers
+ */
+function numberValues(engine, node, context) {
+  const value = node.getAttribute("value");
+  if (value) {
+    const number = Math.round(
+      engine.xpathEvaluator.toNumber(engine.evaluateXPath(value, context)),
+    );
+    // An error that libxslt reports and recovers from by numbering 0
+    if (number < 0) {
+      engine.warnOnce("xsl:number: negative value, 0 is used");
+    }
+    return [number];
+  }
+
+  const count = node.getAttribute("count");
+  const from = node.getAttribute("from");
+  return countXsltNumber(
+    context.currentNode,
+    { level: node.getAttribute("level") || "single", count, from },
+    (candidate, pattern) => engine.matchesPattern(candidate, pattern, context),
+    isMemoizable(count, from) ? engine.numberMemo(node) : null,
+  );
+}
+
+export const numberingMethods = {
+  /**
+   * Instantiate `xsl:number` (XSLT 1.0 section 7.7). The formatting
+   * attributes format, grouping-separator and grouping-size are attribute
+   * value templates; lang and letter-value have no effect.
+   *
+   * @param {Element} node - The xsl:number instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the number
+   * @returns {void}
+   */
+  xslNumber(node, context, output) {
+    const format = this.optionalAvt(node, "format", context) || "1";
+    const grouping = {
+      separator: this.optionalAvt(node, "grouping-separator", context),
+      size: Number(this.optionalAvt(node, "grouping-size", context)),
+    };
+    const numbers = numberValues(this, node, context);
+
+    const text = context.outputDocument.createTextNode(
+      formatXsltNumber(numbers, format, grouping),
+    );
+    output.appendChild(text);
+  },
+
+  /**
+   * The memo of an xsl:number instruction for the current transformation
+   * (see number.js), so numbering a long list stays linear.
+   *
+   * @param {Element} node - The xsl:number instruction
+   * @returns {Map} The instruction's memo
+   */
+  numberMemo(node) {
+    this.numberMemos ??= new WeakMap();
+    let memo = this.numberMemos.get(node);
+    if (!memo) {
+      memo = new Map();
+      this.numberMemos.set(node, memo);
+    }
+    return memo;
+  },
+
+  /**
+   * Format a single number with an `xsl:number` format token.
+   *
+   * @param {number} number - The number to format
+   * @param {string} format - The format token, e.g. `1`, `01`, `a`, `I`
+   * @returns {string} The formatted number
+   */
+  formatNumber(number, format) {
+    return formatXsltNumber([number], format);
+  },
+
+  /**
+   * Convert a number to an upper case Roman numeral.
+   *
+   * @param {number} num - The number to convert
+   * @returns {string} The Roman numeral
+   */
+  toRoman(num) {
+    return toRoman(num);
+  },
+};

package/src/xslt/engine/outputDeclaration.js

@@ -0,0 +1,77 @@
+/**
+ * The xsl:output declaration and the engine's output settings
+ * (XSLT 1.0 section 16).
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { cdataSectionNames } from "../outputNames.js";
+import { inScopeNamespaces } from "../stylesheetNamespaces.js";
+
+/**
+ * The xsl:output attributes copied as they are, with their setting names.
+ * A later non-empty attribute replaces the setting.
+ */
+const OUTPUT_ATTRIBUTES = Object.freeze([
+  ["method", "method"],
+  ["version", "version"],
+  ["encoding", "encoding"],
+  ["standalone", "standalone"],
+  ["indent", "indent"],
+  ["omit-xml-declaration", "omitXmlDeclaration"],
+  ["doctype-public", "doctypePublic"],
+  ["doctype-system", "doctypeSystem"],
+  ["media-type", "mediaType"],
+]);
+
+/**
+ * The output settings of a stylesheet without xsl:output.
+ *
+ * A null method means "not declared": the serializer then picks html or xml
+ * from the result tree (XSLT 1.0 section 16). An undefined indent is "no"
+ * too, except for the line breaks libxslt writes between comments and the
+ * document element (see serializer/settings.js).
+ *
+ * @returns {object} New default output settings
+ */
+export function createOutputSettings() {
+  return {
+    method: null,
+    version: "1.0",
+    encoding: "UTF-8",
+    standalone: null,
+    indent: undefined,
+    omitXmlDeclaration: "no",
+    doctypePublic: null,
+    doctypeSystem: null,
+    mediaType: null,
+    cdataSectionElements: [],
+  };
+}
+
+export const outputDeclarationMethods = {
+  /**
+   * Merge an xsl:output element into the output settings (XSLT 1.0
+   * section 16): a later attribute wins, except cdata-section-elements whose
+   * expanded names are united.
+   *
+   * @param {Element} node - The xsl:output element
+   * @returns {void}
+   */
+  processOutput(node) {
+    for (const [attribute, setting] of OUTPUT_ATTRIBUTES) {
+      const value = node.getAttribute(attribute);
+      if (value) this.outputSettings[setting] = value;
+    }
+
+    const cdataElements = node.getAttribute("cdata-section-elements");
+    if (cdataElements) {
+      this.outputSettings.cdataSectionElements = cdataSectionNames(
+        cdataElements,
+        inScopeNamespaces(node),
+        this.outputSettings.cdataSectionElements,
+        (message) => this.warnOnce(message),
+      );
+    }
+  },
+};

package/src/xslt/engine/sequenceConstructor.js

@@ -0,0 +1,228 @@
+/**
+ * Instantiation of sequence constructors: the dispatch of each child of a
+ * template body to its instruction, stylesheet text, unknown XSLT elements,
+ * xsl:fallback and extension elements.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { isTextContinuation } from "../../xpath/axes.js";
+import { isXmlWhitespace } from "../whitespace.js";
+import { isExtensionElement } from "../stylesheetNamespaces.js";
+import { xsltLocalName } from "../stylesheetChecks.js";
+import { fallbackChildren } from "../forwardsCompatible.js";
+import { SequenceFrame } from "./workStack.js";
+
+/**
+ * Engine method instantiating each XSLT element that may occur in a sequence
+ * constructor; null marks elements that produce nothing there.
+ */
+const INSTRUCTION_METHODS = Object.freeze({
+  "apply-templates": "xslApplyTemplates",
+  "apply-imports": "xslApplyImports",
+  "call-template": "xslCallTemplate",
+  "value-of": "xslValueOf",
+  text: "xslText",
+  element: "xslElement",
+  attribute: "xslAttribute",
+  if: "xslIf",
+  choose: "xslChoose",
+  "for-each": "xslForEach",
+  copy: "xslCopy",
+  "copy-of": "xslCopyOf",
+  variable: "xslVariable",
+  comment: "xslComment",
+  "processing-instruction": "xslProcessingInstruction",
+  number: "xslNumber",
+  message: "xslMessage",
+  // Handled by their parent instruction, or at template start
+  param: null,
+  sort: null,
+  "with-param": null,
+  // Used for forward compatibility
+  fallback: null,
+});
+
+export const sequenceConstructorMethods = {
+  /**
+   * Instantiate the children of a stylesheet element (a sequence
+   * constructor) now, for instructions that use the result at once.
+   *
+   * @param {Element|object} node - The parent stylesheet element
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @returns {void}
+   */
+  processChildren(node, context, output) {
+    this.runFrame(new SequenceFrame(this, node, context, output));
+  },
+
+  /**
+   * Instantiate the children of a stylesheet element once the current
+   * instruction returns (see workStack.js), keeping the JavaScript stack flat
+   * in deep recursion. For content that comes last in an instruction.
+   *
+   * @param {Element|object} node - The parent stylesheet element
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @param {(() => void)|null} [then] - Called once the children are done
+   * @returns {void}
+   */
+  scheduleChildren(node, context, output, then = null) {
+    this.continueWith(new SequenceFrame(this, node, context, output, then));
+  },
+
+  /**
+   * Whether an element has an xsl:variable child. Cached per element.
+   *
+   * @param {Element|object} node - A stylesheet element
+   * @returns {boolean} True when a child declares a variable
+   */
+  declaresVariables(node) {
+    this.variableDeclarations ??= new WeakMap();
+    let declares = this.variableDeclarations.get(node);
+    if (declares === undefined) {
+      declares = false;
+      for (let child = node.firstChild; child; child = child.nextSibling) {
+        if (this.isXsltElement(child, "variable")) declares = true;
+      }
+      this.variableDeclarations.set(node, declares);
+    }
+    return declares;
+  },
+
+  /**
+   * Instantiate a stylesheet text node. Adjacent text and CDATA nodes form
+   * one text node, which is dropped when it only holds XML whitespace (unless
+   * xml:space="preserve" is in scope, XSLT 1.0 section 3.4).
+   *
+   * @param {Text} node - A text or CDATA node of the stylesheet
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @returns {void}
+   */
+  processText(node, context, output) {
+    if (isTextContinuation(node)) return;
+    const text = this.xpathEvaluator.getStringValue(node);
+    if (text && (!isXmlWhitespace(text) || this.shouldPreserveSpace(node))) {
+      output.appendChild(context.outputDocument.createTextNode(text));
+    }
+  },
+
+  /**
+   * Whether xml:space="preserve" is in scope on a stylesheet text node.
+   *
+   * @param {Node} node - The text node
+   * @returns {boolean} True when the nearest xml:space says preserve
+   */
+  shouldPreserveSpace(node) {
+    let current = node.parentNode;
+    while (current && current.nodeType === 1) {
+      const space = current.getAttribute("xml:space");
+      if (space === "preserve") return true;
+      if (space === "default") return false;
+      current = current.parentNode;
+    }
+    return false;
+  },
+
+  /**
+   * Name of the engine method instantiating a stylesheet element: the
+   * handler of an XSLT instruction, processLiteralResultElement, or
+   * instantiateUnknown for an XSLT element the engine does not implement.
+   * Returns null for elements that are not instructions (xsl:param,
+   * xsl:sort, xsl:with-param, xsl:fallback).
+   *
+   * @param {Element} node - A stylesheet element in a sequence constructor
+   * @returns {string|null} The method name
+   */
+  instructionMethod(node) {
+    if (!this.isXsltNamespace(node)) {
+      return isExtensionElement(node)
+        ? "instantiateExtension"
+        : "processLiteralResultElement";
+    }
+
+    const localName = node.localName || node.nodeName.replace(/^xsl:/, "");
+    if (Object.hasOwn(INSTRUCTION_METHODS, localName)) {
+      return INSTRUCTION_METHODS[localName];
+    }
+    return "instantiateUnknown";
+  },
+
+  /**
+   * Instantiate an XSLT element the engine does not implement (XSLT 1.0
+   * section 15): its xsl:fallback children are instantiated in order; without
+   * any, the error is reported and nothing is produced.
+   *
+   * @param {Element} node - The unknown XSLT element
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @returns {void}
+   */
+  instantiateUnknown(node, context, output) {
+    if (!this.instantiateFallbacks(node, context, output)) {
+      console.warn(`Unknown XSLT element: ${xsltLocalName(node)}`);
+    }
+  },
+
+  /**
+   * Instantiate the xsl:fallback children of an element in order.
+   *
+   * @param {Element} node - An unknown XSLT element or extension element
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @returns {boolean} Whether the element had any xsl:fallback child
+   */
+  instantiateFallbacks(node, context, output) {
+    const fallbacks = fallbackChildren(node);
+    for (const fallback of fallbacks) {
+      this.processChildren(fallback, context, output);
+    }
+    return fallbacks.length > 0;
+  },
+
+  /**
+   * Register the implementation of an extension element (XSLT 1.0 section
+   * 14.1). It is called as `handler(node, context, output, engine)` where
+   * an element of that name is instantiated in a namespace declared with
+   * `extension-element-prefixes`.
+   *
+   * @param {string} namespaceUri - The extension namespace
+   * @param {string} localName - The element's local name
+   * @param {(node: Element, context: XsltContext, output: Node, engine: XsltEngine) => void} handler - The implementation
+   * @returns {XsltEngine} This engine, to allow chaining
+   *
+   * @example
+   * engine.registerExtensionElement("urn:my", "log", (node) => console.log(node.textContent));
+   */
+  registerExtensionElement(namespaceUri, localName, handler) {
+    this.extensionElements.set(`{${namespaceUri}}${localName}`, handler);
+    return this;
+  },
+
+  /**
+   * Instantiate an extension element: its registered implementation, else
+   * its xsl:fallback children (XSLT 1.0 sections 14.1 and 15); without
+   * either, the error is reported once and nothing is produced, as libxslt
+   * does. An extension element is never copied to the result.
+   *
+   * @param {Element} node - The extension element
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @returns {void}
+   */
+  instantiateExtension(node, context, output) {
+    const name = `{${node.namespaceURI}}${node.localName}`;
+    const handler = this.extensionElements.get(name);
+    if (handler) {
+      handler(node, context, output, this);
+      return;
+    }
+    if (!this.instantiateFallbacks(node, context, output)) {
+      this.warnOnce(
+        `extension element ${node.nodeName} (${name}) is not supported and has no xsl:fallback`,
+      );
+    }
+  },
+};

package/src/xslt/engine/stylesheetLoading.js

@@ -0,0 +1,208 @@
+/**
+ * Stylesheet loading: the main stylesheet and the xsl:import and
+ * xsl:include modules (the top-level elements are in topLevel.js).
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { resolveUri } from "../uri.js";
+import { parseXml, resolveDomParser } from "../domParsing.js";
+
+/**
+ * Whether an element is an xsl:stylesheet or xsl:transform element.
+ *
+ * @param {object} engine - The engine
+ * @param {Element} root - The document element of a stylesheet module
+ * @returns {boolean} True for a stylesheet element
+ */
+function isStylesheetElement(engine, root) {
+  return (
+    engine.isXsltElement(root, "stylesheet") ||
+    engine.isXsltElement(root, "transform")
+  );
+}
+
+export const stylesheetLoadingMethods = {
+  /**
+   * Set the loader used by xsl:import and xsl:include.
+   *
+   * @param {((href: string, baseUri?: string) => (Document|string))|null} loader - The loader, or null to remove it
+   * @returns {XsltEngine} This engine, to allow chaining
+   *
+   * @example
+   * engine.setStylesheetLoader((href) => readFileSync(href, 'utf8'));
+   */
+  setStylesheetLoader(loader) {
+    this.stylesheetLoader = loader ?? null;
+    return this;
+  },
+
+  /**
+   * Resolve a relative URI against a base URI
+   *
+   * @param {string} href - The URI to resolve
+   * @param {string} [baseUri] - The base URI
+   * @returns {string} The resolved URI
+   */
+  resolveUri(href, baseUri) {
+    return resolveUri(href, baseUri);
+  },
+
+  /**
+   * Load an external stylesheet document with the stylesheet loader.
+   *
+   * @param {string} href - The referenced URI
+   * @param {string} [baseUri] - Base URI of the referencing stylesheet
+   * @returns {{document: (Document|string), uri: string}} What the loader
+   *   returned (a string is parsed by the caller) and the resolved URI
+   * @throws {Error} When no stylesheet loader is configured
+   */
+  loadStylesheet(href, baseUri) {
+    if (!this.stylesheetLoader) {
+      throw new Error(
+        `Cannot load stylesheet "${href}": no stylesheetLoader configured. ` +
+          "Use engine.setStylesheetLoader(fn) to provide a loader function.",
+      );
+    }
+
+    const resolvedUri = this.resolveUri(href, baseUri);
+    const result = this.stylesheetLoader(resolvedUri, baseUri);
+    return { document: result, uri: resolvedUri };
+  },
+
+  /**
+   * Parse an XML string returned by a stylesheet or document loader, with
+   * the `domParser` option, else the global DOMParser, else the DOMParser of
+   * the stylesheet's window (see domParsing.js).
+   *
+   * @param {string} xmlString - The markup
+   * @returns {Document} The parsed document
+   * @throws {Error} When no parser is available or the markup is malformed
+   */
+  parseXmlString(xmlString) {
+    return parseXml(
+      xmlString,
+      resolveDomParser(this.domParser, this.stylesheetDoc),
+    );
+  },
+
+  /**
+   * Import and compile an XSLT stylesheet
+   * @param {Document|Element} stylesheetNode - The stylesheet document or root element
+   * @param {string} [stylesheetUri] - Optional URI of the stylesheet for resolving imports
+   */
+  importStylesheet(stylesheetNode, stylesheetUri) {
+    const isMainStylesheet = this.stylesheetDoc === null;
+
+    if (isMainStylesheet) {
+      this.stylesheetDoc = stylesheetNode.ownerDocument || stylesheetNode;
+      if (stylesheetUri) this.baseUri = stylesheetUri;
+      if (this.baseUri) this.stylesheetStack.push(this.baseUri);
+    }
+
+    const root = stylesheetNode.documentElement || stylesheetNode;
+
+    if (!isStylesheetElement(this, root)) {
+      // A literal result element as document element: simplified stylesheet
+      if (root.getAttribute && root.getAttribute("xsl:version")) {
+        this.processLiteralResultStylesheet(root);
+        return;
+      }
+      throw new Error(
+        "Invalid XSLT stylesheet: root element must be xsl:stylesheet or xsl:transform",
+      );
+    }
+
+    this.processTopLevelElements(root, stylesheetUri || this.baseUri);
+
+    // Increment import precedence after processing this stylesheet
+    if (isMainStylesheet) {
+      this.currentImportPrecedence++;
+    }
+  },
+
+  /**
+   * Process an xsl:include element: the included stylesheet is merged at the
+   * import precedence of the including stylesheet.
+   *
+   * @param {Element} node - The xsl:include element
+   * @param {string} baseUri - URI of the including stylesheet
+   * @returns {void}
+   */
+  processInclude(node, baseUri) {
+    const savedPrecedence = this.currentImportPrecedence;
+    this.loadStylesheetModule(node, baseUri, "include");
+    this.currentImportPrecedence = savedPrecedence;
+  },
+
+  /**
+   * Process an xsl:import element: the imported stylesheet gets a lower import
+   * precedence than everything processed after it.
+   *
+   * @param {Element} node - The xsl:import element
+   * @param {string} baseUri - URI of the importing stylesheet
+   * @returns {void}
+   */
+  processImport(node, baseUri) {
+    this.loadStylesheetModule(node, baseUri, "import");
+    this.currentImportPrecedence++;
+  },
+
+  /**
+   * Load and process the stylesheet referenced by xsl:import or xsl:include.
+   *
+   * Only a stylesheet that (directly or indirectly) references itself is an
+   * error; the same stylesheet may be reached through several branches of the
+   * import tree ("diamond" imports), as in libxslt.
+   *
+   * @param {Element} node - The xsl:import or xsl:include element
+   * @param {string} baseUri - URI of the referencing stylesheet
+   * @param {"import"|"include"} kind - The referencing instruction
+   * @returns {void}
+   * @throws {Error} When href is missing, loading fails or a cycle is found
+   */
+  loadStylesheetModule(node, baseUri, kind) {
+    const href = node.getAttribute("href");
+    if (!href) {
+      throw new Error(`xsl:${kind} requires an href attribute`);
+    }
+
+    const resolvedUri = this.resolveUri(href, baseUri);
+    if (this.stylesheetStack.includes(resolvedUri)) {
+      throw new Error(`Circular stylesheet reference detected: ${resolvedUri}`);
+    }
+
+    this.stylesheetStack.push(resolvedUri);
+    try {
+      const { document: loaded } = this.loadStylesheet(href, baseUri);
+      const doc =
+        typeof loaded === "string" ? this.parseXmlString(loaded) : loaded;
+      this.processIncludedStylesheet(doc, resolvedUri);
+    } catch (error) {
+      throw new Error(
+        `Failed to ${kind} stylesheet "${href}": ${error.message}`,
+        { cause: error },
+      );
+    } finally {
+      this.stylesheetStack.pop();
+    }
+  },
+
+  /**
+   * Process an included/imported stylesheet document.
+   *
+   * @param {Document|Element} stylesheetDoc - The loaded stylesheet module
+   * @param {string} stylesheetUri - Its resolved URI
+   * @returns {void}
+   * @throws {Error} When the document is not an XSLT stylesheet
+   */
+  processIncludedStylesheet(stylesheetDoc, stylesheetUri) {
+    const root = stylesheetDoc.documentElement || stylesheetDoc;
+    if (!isStylesheetElement(this, root)) {
+      throw new Error(
+        "Included/imported document is not a valid XSLT stylesheet",
+      );
+    }
+    this.processTopLevelElements(root, stylesheetUri);
+  },
+};