@tradik/xslt-processor 1.0.3 → 1.3.0

package/src/xslt/forwardsCompatible.js

@@ -0,0 +1,75 @@
+/**
+ * Forwards-compatible processing and xsl:fallback (XSLT 1.0 sections 2.5
+ * and 15).
+ *
+ * An element is processed in forwards-compatible mode when the nearest
+ * enclosing `version` declaration (the `version` attribute of
+ * `xsl:stylesheet`/`xsl:transform`, or the `xsl:version` attribute of a
+ * literal result element) is not "1.0". In that mode unknown top-level XSLT
+ * elements are ignored. An unknown XSLT instruction is replaced by its
+ * `xsl:fallback` children when it has some (in any mode); otherwise it is an
+ * error only if it is actually instantiated.
+ *
+ * @module xslt/forwardsCompatible
+ */
+
+"use strict";
+
+import { XSLT_NAMESPACE } from "./elements.js";
+import { xsltLocalName } from "./stylesheetChecks.js";
+
+const modes = new WeakMap();
+
+/**
+ * The version declared on one stylesheet element, if any.
+ *
+ * @param {Element} element - A stylesheet element
+ * @returns {string|null} The declared version, null when none
+ */
+export function declaredVersion(element) {
+  const localName = xsltLocalName(element);
+  if (localName === "stylesheet" || localName === "transform") {
+    return element.getAttribute("version");
+  }
+  if (localName !== null) return null;
+  return element.getAttributeNS?.(XSLT_NAMESPACE, "version") ?? null;
+}
+
+/**
+ * Whether a stylesheet element is processed in forwards-compatible mode.
+ * Cached per element.
+ *
+ * @param {Node|null} node - A stylesheet node
+ * @returns {boolean} True when the version in effect is not "1.0"
+ *
+ * @example
+ * isForwardsCompatible(instruction); // true under version="2.0"
+ */
+export function isForwardsCompatible(node) {
+  if (node?.nodeType !== 1) return false;
+
+  let forwards = modes.get(node);
+  if (forwards === undefined) {
+    const version = declaredVersion(node);
+    forwards =
+      version === null || version === ""
+        ? isForwardsCompatible(node.parentNode)
+        : version.trim() !== "1.0";
+    modes.set(node, forwards);
+  }
+  return forwards;
+}
+
+/**
+ * The `xsl:fallback` children of an instruction, in document order.
+ *
+ * @param {Element} instruction - An XSLT instruction
+ * @returns {Element[]} The fallback elements
+ */
+export function fallbackChildren(instruction) {
+  const fallbacks = [];
+  for (let child = instruction.firstChild; child; child = child.nextSibling) {
+    if (xsltLocalName(child) === "fallback") fallbacks.push(child);
+  }
+  return fallbacks;
+}

package/src/xslt/functions.js

@@ -0,0 +1,270 @@
+/**
+ * XSLT-defined XPath functions.
+ *
+ * XSLT 1.0 section 12 adds functions to the XPath function library, and the
+ * EXSLT `node-set()` extension (also under the msxsl namespace) is registered
+ * by expanded name next to them, together with the other EXSLT functions of
+ * `./exslt/index.js`. They live here rather than in `src/xpath` so
+ * that module stays a pure XPath 1.0 implementation; the engine registers this
+ * map on its evaluator through
+ * {@link XPathEvaluator#registerFunctions}.
+ */
+
+"use strict";
+
+import { formatNumber, DEFAULT_DECIMAL_FORMAT } from "./formatNumber.js";
+import { isXsltElementAvailable, XSLT_NAMESPACE } from "./elements.js";
+import {
+  expandedFunctionName,
+  resolveNamespacePrefix,
+} from "../xpath/evaluator.js";
+import { rootNodeOf } from "../xpath/axes.js";
+import { EXSLT_COMMON, createExsltFunctions } from "./exslt/index.js";
+
+/** Namespace of the EXSLT common module (`exsl:node-set()`). */
+export const EXSLT_COMMON_NAMESPACE = EXSLT_COMMON;
+
+/** Namespace of the MSXML extension functions (`msxsl:node-set()`). */
+export const MSXSL_NAMESPACE = "urn:schemas-microsoft-com:xslt";
+
+/** Vendor identification reported by `system-property()`. */
+export const VENDOR = "@tradik/xslt-processor";
+
+/** Vendor URL reported by `system-property()`. */
+export const VENDOR_URL = "https://github.com/spagu/XSLT-Processor";
+
+/**
+ * Values reported by `system-property()`, keyed by property name.
+ *
+ * The XSLT version is reported as the string `"1"`; XPath 1.0 converts it to
+ * the number 1 wherever a numeric comparison or arithmetic is used.
+ */
+const SYSTEM_PROPERTIES = Object.freeze({
+  "xsl:version": "1",
+  "xsl:vendor": VENDOR,
+  "xsl:vendor-url": VENDOR_URL,
+});
+
+/**
+ * Get the document that owns a node.
+ *
+ * @param {Node} node - Any node
+ * @returns {Document} The owning document, or the node when it is a document
+ */
+function ownerDocumentOf(node) {
+  return node.ownerDocument || node;
+}
+
+/**
+ * Convert an evaluated argument to the list of strings it denotes.
+ *
+ * Node-sets yield the string value of every node, other types yield one string.
+ *
+ * @param {XPathEvaluator} evaluator - The evaluator providing the conversions
+ * @param {(value: *) => string} stringify - The XPath `string()` conversion
+ * @param {*} value - An evaluated XPath value
+ * @returns {string[]} The string values
+ */
+function toStringList(evaluator, stringify, value) {
+  if (Array.isArray(value)) {
+    return value.map((node) => evaluator.getStringValue(node));
+  }
+  return [stringify(value)];
+}
+
+/**
+ * Split a QName into its prefix and local part.
+ *
+ * @param {string} qname - A possibly prefixed name
+ * @returns {{prefix: (string|null), localName: string}} The parts of the name
+ */
+function splitQName(qname) {
+  const colon = qname.indexOf(":");
+  if (colon === -1) return { prefix: null, localName: qname };
+  return {
+    prefix: qname.substring(0, colon),
+    localName: qname.substring(colon + 1),
+  };
+}
+
+/**
+ * Expanded name key of the decimal format named by the third argument of
+ * `format-number()`, with the prefix resolved in the expression's scope
+ * (XSLT 1.0 section 12.3); the table is keyed the same way (see
+ * declarationNames.js).
+ *
+ * @param {string} qname - The decimal format QName
+ * @param {{namespaces: Object<string, string>}} ctx - The XPath context
+ * @returns {string} `{uri}local`, or the local name in no namespace
+ * @throws {Error} When the prefix is not declared
+ */
+function decimalFormatKey(qname, ctx) {
+  const { prefix, localName } = splitQName(qname);
+  if (prefix === null) return localName;
+  const namespaceUri = resolveNamespacePrefix(prefix, ctx.namespaces);
+  if (!namespaceUri) {
+    throw new Error(
+      `format-number(): undeclared namespace prefix "${prefix}" in "${qname}"`,
+    );
+  }
+  return `{${namespaceUri}}${localName}`;
+}
+
+/**
+ * Build the XSLT function map for an engine.
+ *
+ * @param {import('./engine.js').XsltEngine} engine - The engine providing loaders, keys and formats
+ * @returns {Object<string, Function>} Functions ready for `registerFunctions`
+ *
+ * @example
+ * evaluator.registerFunctions(createXsltFunctions(engine));
+ */
+export function createXsltFunctions(engine) {
+  const evaluator = engine.xpathEvaluator;
+
+  /**
+   * The XPath `string()` conversion of the evaluator.
+   *
+   * `XPathEvaluator#toString` shadows `Object#toString` and takes the value to
+   * convert as its argument, so it is bound once under an unambiguous name.
+   *
+   * @type {(value: *) => string}
+   */
+  const stringify = evaluator.toString.bind(evaluator);
+  const evaluate = (arg, ctx) => evaluator.evaluate(arg, ctx);
+  const asString = (arg, ctx) => stringify(evaluate(arg, ctx));
+
+  /**
+   * `exsl:node-set(object)` - EXSLT common, also known as `msxsl:node-set()`.
+   *
+   * A result tree fragment (a DocumentFragment in this engine) becomes a
+   * node-set holding its root node, so `exsl:node-set($rtf)/item` selects the
+   * fragment's top-level `item` elements. A node-set is returned unchanged; any
+   * other value becomes a node-set holding one text node with its string value.
+   *
+   * @param {Array} args - Argument expressions
+   * @param {import('../xpath/evaluator.js').XPathContext} ctx - Evaluation context
+   * @returns {Node[]} The node-set
+   */
+  const nodeSet = (args, ctx) => {
+    const value = evaluate(args[0], ctx);
+    if (Array.isArray(value)) return value;
+    if (value?.nodeType) return [value];
+    return [ownerDocumentOf(ctx.node).createTextNode(stringify(value))];
+  };
+
+  return {
+    ...createExsltFunctions(engine),
+    [expandedFunctionName(EXSLT_COMMON_NAMESPACE, "node-set")]: nodeSet,
+    [expandedFunctionName(MSXSL_NAMESPACE, "node-set")]: nodeSet,
+
+    /**
+     * `document(object, base?)` - load external XML documents.
+     *
+     * An empty URI denotes the stylesheet itself. Without a document loader, or
+     * when the loader returns null, the result is an empty node-set. The
+     * optional second argument is read as a base URI string.
+     */
+    document: (args, ctx) => {
+      const baseUri = args.length > 1 ? asString(args[1], ctx) : engine.baseUri;
+      const uris = toStringList(evaluator, stringify, evaluate(args[0], ctx));
+      const result = [];
+
+      for (const uri of uris) {
+        const doc = engine.loadDocument(uri, baseUri || engine.baseUri);
+        if (doc && !result.includes(doc)) result.push(doc);
+      }
+
+      return result;
+    },
+
+    /**
+     * `key(name, value)` - look up nodes through an `xsl:key` index of the
+     * tree containing the context node: its document, or the fragment of a
+     * result tree fragment converted with `exsl:node-set()`.
+     */
+    key: (args, ctx) => {
+      const name = asString(args[0], ctx);
+      const values = toStringList(evaluator, stringify, evaluate(args[1], ctx));
+      return engine.keyRegistry.lookup(name, values, rootNodeOf(ctx.node));
+    },
+
+    /** `format-number(number, pattern, decimalFormat?)`. */
+    "format-number": (args, ctx) => {
+      const value = evaluator.toNumber(evaluate(args[0], ctx));
+      const pattern = asString(args[1], ctx);
+      const formatName =
+        args.length > 2 ? decimalFormatKey(asString(args[2], ctx), ctx) : "";
+      const format =
+        engine.decimalFormats[formatName] || DEFAULT_DECIMAL_FORMAT;
+      return formatNumber(value, pattern, format);
+    },
+
+    /** `current()` - the XSLT current node, not the XPath context node. */
+    current: (args, ctx) => {
+      const currentNode = ctx.hostContext?.currentNode;
+      return currentNode ? [currentNode] : [ctx.node];
+    },
+
+    /** `generate-id(node-set?)` - a stable id for the life of the transform. */
+    "generate-id": (args, ctx) => {
+      let node = ctx.node;
+
+      if (args.length > 0) {
+        const nodeSet = evaluate(args[0], ctx);
+        node = Array.isArray(nodeSet) ? nodeSet[0] : nodeSet;
+      }
+
+      return node ? engine.generateId(node) : "";
+    },
+
+    /** `system-property(name)` - XSLT version and vendor information. */
+    "system-property": (args, ctx) => {
+      const name = asString(args[0], ctx);
+      return Object.hasOwn(SYSTEM_PROPERTIES, name)
+        ? SYSTEM_PROPERTIES[name]
+        : "";
+    },
+
+    /**
+     * `function-available(name)` - reflects the evaluator function table. A
+     * prefixed name is resolved through the stylesheet's namespace bindings,
+     * just as a call of that function would be. A function can report itself
+     * unavailable through an `isAvailable()` property (`dyn:evaluate()` does
+     * until the engine enables it).
+     */
+    "function-available": (args, ctx) => {
+      const { prefix, localName } = splitQName(asString(args[0], ctx));
+      const fn = evaluator.resolveFunction(localName, prefix, ctx.namespaces);
+      return fn !== null && fn.isAvailable?.() !== false;
+    },
+
+    /** `element-available(name)` - reflects the XSLT elements the engine runs. */
+    "element-available": (args, ctx) => {
+      const { prefix, localName } = splitQName(asString(args[0], ctx));
+      // An unprefixed name is in the default namespace (XSLT 1.0 section
+      // 15), which may be the XSLT namespace itself (libxslt bug-200)
+      const namespaceUri = prefix
+        ? (ctx.namespaces[prefix] ?? (prefix === "xsl" ? XSLT_NAMESPACE : null))
+        : ctx.namespaces[""] || null;
+      if (!namespaceUri) return false;
+
+      if (namespaceUri === XSLT_NAMESPACE) {
+        return isXsltElementAvailable(localName);
+      }
+      // Extension elements with an implementation (registerExtensionElement)
+      return Boolean(
+        engine.extensionElements?.has(`{${namespaceUri}}${localName}`),
+      );
+    },
+
+    /**
+     * `unparsed-entity-uri(name)` - always empty.
+     *
+     * Unparsed entity declarations are not exposed by the DOM, so this
+     * processor cannot resolve them; returning the empty string keeps
+     * stylesheets that call the function working.
+     */
+    "unparsed-entity-uri": () => "",
+  };
+}

package/src/xslt/index.js

@@ -3,4 +3,41 @@
  * Based on W3C XSLT 1.0 Specification: http://www.w3.org/TR/1999/REC-xslt-19991116
  */
 
-export { XsltContext, XsltEngine } from "./engine.js";
+export {
+  XSLT_MAX_EXPRESSION_DEPTH,
+  XSLT_MAX_RESULT_SIZE,
+  XSLT_MAX_TEMPLATE_DEPTH,
+  XsltContext,
+  XsltEngine,
+} from "./engine.js";
+
+// XSLT vocabulary and function library (advanced usage)
+export {
+  XSLT_ELEMENTS,
+  XSLT_NAMESPACE,
+  isXsltElementAvailable,
+} from "./elements.js";
+export { VENDOR, VENDOR_URL, createXsltFunctions } from "./functions.js";
+export { KeyIndexRegistry } from "./keys.js";
+export { DEFAULT_DECIMAL_FORMAT, formatNumber } from "./formatNumber.js";
+export { countXsltNumber } from "./number.js";
+export { formatXsltNumber, toRoman } from "./numberFormat.js";
+export { WhitespaceFilter, stripWhitespaceNodes } from "./whitespace.js";
+export {
+  NamespaceAliasMap,
+  getXsltAttribute,
+  lookupNamespaceUri,
+  shouldCopyAttribute,
+} from "./literalResult.js";
+export {
+  createResultDocument,
+  importResultFragment,
+  importResultNode,
+} from "./resultTree.js";
+export { isAbsoluteUri, resolveUri, stripFragment } from "./uri.js";
+export {
+  serializeResult,
+  markRawText,
+  isRawText,
+  resolveOutputSettings,
+} from "./serializer.js";

package/src/xslt/keys.js

@@ -0,0 +1,164 @@
+/**
+ * `xsl:key` indexing for the XSLT `key()` function.
+ *
+ * Indexes are built lazily, once per (root node, key name) pair, and cached in
+ * a `WeakMap` so source documents stay garbage collectable. The root node is
+ * the document of the context node, or the DocumentFragment of a result tree
+ * fragment converted with `exsl:node-set()` (see `rootNodeOf` in xpath/axes). The registry is
+ * deliberately decoupled from the engine: pattern matching and `use` evaluation
+ * are injected as callbacks.
+ */
+
+"use strict";
+
+/**
+ * @typedef {Object} KeyDefinition
+ * @property {string} match - Pattern of the nodes to index
+ * @property {string} use - Expression computing the key values
+ * @property {Object<string, string>} [namespaces] - Prefixes in scope on the xsl:key element
+ */
+
+/**
+ * @typedef {Object} KeyIndex
+ * @property {Map<string, Node[]>} buckets - Key value to nodes, in document order
+ * @property {Map<Node, number>} order - Document order position of every node
+ */
+
+/**
+ * Lazily built, per-tree indexes for all declared keys.
+ */
+export class KeyIndexRegistry {
+  /**
+   * @param {Object} options - Registry configuration
+   * @param {Object<string, (KeyDefinition|KeyDefinition[])>} options.keys - Declared keys by name; several xsl:key elements may share a name
+   * @param {(node: Node, pattern: string, definition: KeyDefinition) => boolean} options.matchesPattern - XSLT pattern matcher
+   * @param {(node: Node, expression: string, definition: KeyDefinition) => string[]} options.evaluateUse - `use` evaluator returning key values
+   */
+  constructor({ keys, matchesPattern, evaluateUse }) {
+    this.keys = keys;
+    this.matchesPattern = matchesPattern;
+    this.evaluateUse = evaluateUse;
+    this.cache = new WeakMap();
+  }
+
+  /**
+   * Drop every cached index, for example after the key declarations changed.
+   *
+   * @returns {void}
+   *
+   * @example
+   * registry.clear();
+   */
+  clear() {
+    this.cache = new WeakMap();
+  }
+
+  /**
+   * Look up the nodes indexed under one or more key values.
+   *
+   * @param {string} name - The key name
+   * @param {string|string[]} values - One key value, or several to union
+   * @param {Node} doc - Root of the tree to search (Document or DocumentFragment)
+   * @returns {Node[]} Matching nodes in document order, without duplicates
+   * @throws {Error} When the key name was never declared
+   *
+   * @example
+   * registry.lookup('byId', 'a1', xmlDoc);
+   */
+  lookup(name, values, doc) {
+    if (!Object.hasOwn(this.keys, name)) {
+      throw new Error(`Undefined key: ${name}`);
+    }
+
+    const { buckets, order } = this.getIndex(name, doc);
+    const wanted = Array.isArray(values) ? values : [values];
+    if (wanted.length === 1) return [...(buckets.get(wanted[0]) || [])];
+
+    const found = new Set();
+    for (const value of wanted) {
+      for (const node of buckets.get(value) || []) found.add(node);
+    }
+    return [...found].sort((a, b) => order.get(a) - order.get(b));
+  }
+
+  /**
+   * Get (building if needed) the index of one key for one document.
+   *
+   * @param {string} name - The key name
+   * @param {Node} doc - Root of the tree being indexed
+   * @returns {KeyIndex} The index
+   */
+  getIndex(name, doc) {
+    let byName = this.cache.get(doc);
+    if (!byName) {
+      byName = new Map();
+      this.cache.set(doc, byName);
+    }
+
+    let index = byName.get(name);
+    if (!index) {
+      index = this.buildIndex(name, doc);
+      byName.set(name, index);
+    }
+
+    return index;
+  }
+
+  /**
+   * Build the index of one key for one document, merging every declaration
+   * of that key name.
+   *
+   * @param {string} name - The key name
+   * @param {Node} doc - Root of the tree being indexed
+   * @returns {KeyIndex} The index
+   */
+  buildIndex(name, doc) {
+    const definitions = [this.keys[name]].flat();
+    const buckets = new Map();
+    const order = new Map();
+
+    for (const node of documentOrderNodes(doc)) {
+      order.set(node, order.size);
+
+      for (const definition of definitions) {
+        if (!this.matchesPattern(node, definition.match, definition)) continue;
+
+        for (const value of this.evaluateUse(
+          node,
+          definition.use,
+          definition,
+        )) {
+          const bucket = buckets.get(value);
+          if (!bucket) buckets.set(value, [node]);
+          else if (bucket[bucket.length - 1] !== node) bucket.push(node);
+        }
+      }
+    }
+
+    return { buckets, order };
+  }
+}
+
+/**
+ * Walk a document in document order, including attribute nodes.
+ *
+ * @param {Node} root - The document or subtree root
+ * @yields {Node} Every node of the subtree
+ */
+function* documentOrderNodes(root) {
+  const stack = [root];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    yield current;
+
+    if (current.nodeType === 1 && current.attributes) {
+      for (const attribute of current.attributes) yield attribute;
+    }
+
+    const children = current.childNodes;
+    if (children) {
+      for (let i = children.length - 1; i >= 0; i--) stack.push(children[i]);
+    }
+  }
+}