@tradik/xslt-processor 1.1.1 → 1.3.0

package/src/xslt/engine/declarations.js

@@ -0,0 +1,233 @@
+/**
+ * Top-level declarations other than templates and xsl:output: global
+ * variables and parameters, keys, decimal formats, namespace aliases,
+ * attribute sets and whitespace stripping.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { inScopeNamespaces } from "../stylesheetNamespaces.js";
+import { compileSpaceNameTests } from "../spaceNameTests.js";
+import { registerAttributeSet } from "../attributeSets.js";
+import { expandName } from "../declarationNames.js";
+import {
+  checkGlobalDuplicate,
+  checkLocalBindings,
+  checkPattern,
+  xsltLocalName,
+} from "../stylesheetChecks.js";
+
+/**
+ * The properties of an xsl:decimal-format declaration, with their defaults
+ * (XSLT 1.0 section 12.3).
+ *
+ * @param {Element} node - The xsl:decimal-format element
+ * @param {number} importPrecedence - Its import precedence
+ * @returns {object} The decimal format
+ */
+function readDecimalFormat(node, importPrecedence) {
+  return {
+    importPrecedence,
+    decimalSeparator: node.getAttribute("decimal-separator") || ".",
+    groupingSeparator: node.getAttribute("grouping-separator") || ",",
+    percent: node.getAttribute("percent") || "%",
+    perMille: node.getAttribute("per-mille") || "‰",
+    zeroDigit: node.getAttribute("zero-digit") || "0",
+    digit: node.getAttribute("digit") || "#",
+    patternSeparator: node.getAttribute("pattern-separator") || ";",
+    infinity: node.getAttribute("infinity") || "Infinity",
+    nan: node.getAttribute("NaN") || "NaN",
+    minusSign: node.getAttribute("minus-sign") || "-",
+  };
+}
+
+export const declarationMethods = {
+  /**
+   * Register an `xsl:variable` top level declaration.
+   *
+   * @param {Element} node - The `xsl:variable` element
+   * @returns {void}
+   */
+  processGlobalVariable(node) {
+    const name = node.getAttribute("name");
+    this.checkGlobalBinding(name, node);
+    this.globalVariables[name] = {
+      node,
+      select: node.getAttribute("select"),
+      importPrecedence: this.currentImportPrecedence,
+    };
+  },
+
+  /**
+   * Warn about a global variable or parameter declared twice at the same
+   * import precedence (an error in XSLT 1.0 section 11.4 that libxslt
+   * reports) and about duplicate local bindings in its content. The later
+   * declaration is used, or the xsl:variable when a parameter has the same
+   * name and import precedence.
+   *
+   * @param {string} name - The declared name
+   * @param {Element} node - The xsl:variable or xsl:param element
+   * @returns {void}
+   */
+  checkGlobalBinding(name, node) {
+    const warn = (message) => this.warnOnce(message);
+    checkLocalBindings(node, warn);
+    checkGlobalDuplicate(
+      {
+        name,
+        kind: xsltLocalName(node),
+        precedence: this.currentImportPrecedence,
+      },
+      {
+        variable: this.globalVariables[name],
+        param: this.globalParameters[name],
+      },
+      warn,
+    );
+  },
+
+  /**
+   * Register an `xsl:param` top level declaration.
+   *
+   * A value supplied from outside (through `setParameter`) has precedence over
+   * the declared default, so it survives compilation of the stylesheet.
+   *
+   * @param {Element} node - The `xsl:param` element
+   * @returns {void}
+   */
+  processGlobalParam(node) {
+    const name = node.getAttribute("name");
+    this.checkGlobalBinding(name, node);
+    const existing = this.globalParameters[name];
+    const definition = {
+      node,
+      select: node.getAttribute("select"),
+      importPrecedence: this.currentImportPrecedence,
+    };
+
+    if (existing && "value" in existing) {
+      definition.value = existing.value;
+    }
+
+    this.globalParameters[name] = definition;
+  },
+
+  /**
+   * Register an xsl:key declaration. Declarations sharing a name all
+   * contribute to the same key (XSLT 1.0 section 12.2); a declaration seen
+   * again through another import branch is only kept once.
+   *
+   * @param {Element} node - The xsl:key element
+   * @returns {void}
+   */
+  processKey(node) {
+    const name = node.getAttribute("name");
+    const match = node.getAttribute("match");
+    const use = node.getAttribute("use");
+    if (match !== null) {
+      checkPattern(this.patternMatcher, match, "xsl:key match");
+    }
+    const definitions = (this.keys[name] ??= []);
+
+    if (!definitions.some((d) => d.match === match && d.use === use)) {
+      definitions.push({ match, use, namespaces: inScopeNamespaces(node) });
+    }
+    this.keyRegistry.clear();
+  },
+
+  /**
+   * Register an xsl:decimal-format declaration under the expanded name of
+   * its `name` (XSLT 1.0 section 12.3). Like libxslt, an invalid name or an
+   * undeclared prefix is reported and the declaration ignored, and a second
+   * declaration of the same name and import precedence is reported and
+   * ignored; one of a higher import precedence replaces an imported one.
+   *
+   * @param {Element} node - The xsl:decimal-format element
+   * @returns {void}
+   */
+  processDecimalFormat(node) {
+    const name = node.getAttribute("name");
+    let key = "";
+    if (name !== null) {
+      const expanded = expandName(name, node);
+      if (expanded.error) {
+        this.warnOnce(
+          `xsl:decimal-format: ${expanded.error}; the declaration is ignored`,
+        );
+        return;
+      }
+      key = expanded.key;
+      const existing = this.decimalFormats[key];
+      if (existing?.importPrecedence === this.currentImportPrecedence) {
+        this.warnOnce(
+          `xsl:decimal-format: "${name}" is already declared; the first declaration is used`,
+        );
+        return;
+      }
+    }
+
+    this.decimalFormats[key] = readDecimalFormat(
+      node,
+      this.currentImportPrecedence,
+    );
+  },
+
+  /**
+   * Register an xsl:namespace-alias declaration.
+   *
+   * @param {Element} node - The xsl:namespace-alias element
+   * @returns {void}
+   */
+  processNamespaceAlias(node) {
+    this.namespaceAliases.add(node);
+  },
+
+  /**
+   * Register an xsl:attribute-set declaration; declarations of the same
+   * expanded name are merged (see attributeSets.js).
+   *
+   * @param {Element} node - The xsl:attribute-set element
+   * @returns {void}
+   */
+  processAttributeSet(node) {
+    checkLocalBindings(node, (message) => this.warnOnce(message));
+    registerAttributeSet(
+      this.attributeSets,
+      node,
+      this.currentImportPrecedence,
+    );
+  },
+
+  /**
+   * Register the name tests of an xsl:strip-space element, expanded with
+   * its namespace declarations (see spaceNameTests.js).
+   *
+   * @param {Element} node - The xsl:strip-space element
+   * @returns {void}
+   */
+  processStripSpace(node) {
+    this.stripSpace.push(...this.spaceNameTests(node));
+  },
+
+  /**
+   * Register the name tests of an xsl:preserve-space element.
+   *
+   * @param {Element} node - The xsl:preserve-space element
+   * @returns {void}
+   */
+  processPreserveSpace(node) {
+    this.preserveSpace.push(...this.spaceNameTests(node));
+  },
+
+  /**
+   * Expand the `elements` name tests of xsl:strip-space/preserve-space.
+   *
+   * @param {Element} node - The declaring element
+   * @returns {object[]} The expanded name tests
+   */
+  spaceNameTests(node) {
+    return compileSpaceNameTests(node.getAttribute("elements"), node, (m) =>
+      this.warnOnce(m),
+    );
+  },
+};

package/src/xslt/engine/functionSupport.js

@@ -0,0 +1,103 @@
+/**
+ * Engine services behind the XSLT functions: document(), generate-id()
+ * and key() (see functions.js).
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { resolveUri, stripFragment } from "../uri.js";
+
+export const functionSupportMethods = {
+  /**
+   * Set the loader used by the XSLT `document()` function.
+   *
+   * The loader is synchronous and must return a `Document`, an XML string or
+   * null. Returning null (or configuring no loader at all) makes `document()`
+   * evaluate to an empty node-set instead of failing the transformation.
+   *
+   * @param {((uri: string, baseUri?: string) => (Document|string|null))|null} loader - The loader, or null to remove it
+   * @returns {XsltEngine} This engine, to allow chaining
+   *
+   * @example
+   * engine.setDocumentLoader((uri) => readFileSync(uri, 'utf8'));
+   */
+  setDocumentLoader(loader) {
+    this.documentLoader = loader ?? null;
+    this.loadedDocuments.clear();
+    return this;
+  },
+
+  /**
+   * Load an external document for the `document()` function.
+   *
+   * Results are cached per resolved URI for the life of the engine, so the same
+   * URI always yields the identical node-set.
+   *
+   * @param {string} uri - The requested URI, fragment identifiers are ignored
+   * @param {string} [baseUri] - Base URI used to resolve relative references
+   * @returns {Document|null} The loaded document, or null when unavailable
+   *
+   * @example
+   * engine.loadDocument('data.xml', '/styles/main.xsl');
+   */
+  loadDocument(uri, baseUri) {
+    const target = stripFragment(uri);
+
+    if (target === "") return this.stylesheetDoc;
+    if (!this.documentLoader) return null;
+
+    const resolved = resolveUri(target, baseUri);
+    if (this.loadedDocuments.has(resolved)) {
+      return this.loadedDocuments.get(resolved);
+    }
+
+    const loaded = this.documentLoader(resolved, baseUri);
+    const doc =
+      typeof loaded === "string" ? this.parseXmlString(loaded) : loaded || null;
+
+    this.loadedDocuments.set(resolved, doc);
+    return doc;
+  },
+
+  /**
+   * Return the stable identifier of a node for `generate-id()`.
+   *
+   * @param {Node} node - The node to identify
+   * @returns {string} An identifier starting with a letter
+   *
+   * @example
+   * engine.generateId(element); // 'N1'
+   */
+  generateId(node) {
+    let id = this.generatedIds.get(node);
+    if (!id) {
+      this.generatedIdCount++;
+      id = `N${this.generatedIdCount}`;
+      this.generatedIds.set(node, id);
+    }
+    return id;
+  },
+
+  /**
+   * Evaluate the `use` expression of an `xsl:key` for one node.
+   *
+   * @param {Node} node - The node being indexed
+   * @param {string} expression - The `use` expression
+   * @param {Object<string, string>} [namespaces] - Prefixes in scope on the xsl:key
+   * @returns {string[]} The key values contributed by the node
+   */
+  evaluateKeyValues(node, expression, namespaces) {
+    const context = this.rootContext.clone({
+      currentNode: node,
+      currentNodeList: [node],
+      position: 1,
+    });
+    if (namespaces) context.namespaces = namespaces;
+    const value = this.evaluateXPath(expression, context);
+
+    if (Array.isArray(value)) {
+      return value.map((item) => this.xpathEvaluator.getStringValue(item));
+    }
+    return [this.xpathEvaluator.toString(value)];
+  },
+};

package/src/xslt/engine/methods.js

@@ -0,0 +1,33 @@
+/**
+ * Installation of the XsltEngine method groups.
+ *
+ * The engine is split by concern into modules that each export a plain
+ * object of methods (`this` is the engine). They are installed on
+ * `XsltEngine.prototype`, so every method stays callable on the engine under
+ * its old name and the instruction dispatch (`this[method](...)`) costs no
+ * extra stack frame per recursion level.
+ */
+
+/**
+ * Define the methods (and accessors) of each group on a prototype, as
+ * non-enumerable properties like class methods.
+ *
+ * @param {object} prototype - The class prototype receiving the methods
+ * @param {...object} groups - Objects of methods, getters included
+ * @returns {void}
+ * @throws {Error} When two groups define the same name
+ */
+export function installMethods(prototype, ...groups) {
+  for (const group of groups) {
+    const descriptors = Object.getOwnPropertyDescriptors(group);
+    for (const [name, descriptor] of Object.entries(descriptors)) {
+      if (Object.hasOwn(prototype, name)) {
+        throw new Error(`Engine method defined twice: ${name}`);
+      }
+      Object.defineProperty(prototype, name, {
+        ...descriptor,
+        enumerable: false,
+      });
+    }
+  }
+}

package/src/xslt/engine/nodeConstruction.js

@@ -0,0 +1,187 @@
+/**
+ * Creation of result elements and attributes: literal result elements,
+ * xsl:element, xsl:attribute and attribute sets.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { XSLT_NAMESPACE } from "../elements.js";
+import { getXsltAttribute, shouldCopyAttribute } from "../literalResult.js";
+import {
+  copyLiteralNamespaces,
+  setResultAttribute,
+} from "../resultNamespaces.js";
+import {
+  computedAttributeName,
+  computedElementName,
+} from "../computedNames.js";
+import { applyAttributeSets } from "../attributeSets.js";
+import { requireExpandedNames } from "../declarationNames.js";
+
+export const nodeConstructionMethods = {
+  /**
+   * Copy one attribute of a literal result element to the result, evaluating
+   * it as an attribute value template and applying xsl:namespace-alias.
+   *
+   * @param {Attr} attr - Attribute of the literal result element
+   * @param {XsltContext} context - The current XSLT context
+   * @param {Element} outputElement - The result element
+   * @returns {void}
+   */
+  copyLiteralAttribute(attr, context, outputElement) {
+    const value = this.processAttributeValueTemplate(attr.value, context);
+    const alias = this.namespaceAliases.resolveLiteral(attr);
+
+    if (alias) {
+      outputElement.setAttributeNS(alias.namespaceUri, alias.qname, value);
+    } else if (attr.namespaceURI) {
+      outputElement.setAttributeNS(attr.namespaceURI, attr.name, value);
+    } else {
+      outputElement.setAttribute(attr.name, value);
+    }
+  },
+
+  /**
+   * Process a literal result element (non-XSLT)
+   *
+   * Applies `xsl:namespace-alias` to the element and its attributes, honours
+   * `xsl:use-attribute-sets` and keeps XSLT-only attributes and namespace
+   * declarations out of the result tree.
+   *
+   * @param {Element} node - The literal result element in the stylesheet
+   * @param {XsltContext} context - The current XSLT context
+   * @param {Node} output - The result tree node receiving the element
+   * @returns {void}
+   */
+  processLiteralResultElement(node, context, output) {
+    const alias = this.namespaceAliases.resolveLiteral(node);
+    const namespaceUri = alias ? alias.namespaceUri : node.namespaceURI;
+    const qname = alias ? alias.qname : node.nodeName;
+
+    const outputElement =
+      namespaceUri && context.outputDocument.createElementNS
+        ? context.outputDocument.createElementNS(namespaceUri, qname)
+        : context.outputDocument.createElement(qname);
+    // Attached first, so namespace lookups see the result ancestors
+    output.appendChild(outputElement);
+    copyLiteralNamespaces(outputElement, node, output, (uri) =>
+      this.namespaceAliases.isAliased(uri),
+    );
+
+    // Attribute sets come first so literal attributes take precedence
+    const useAttributeSets = getXsltAttribute(
+      node,
+      "use-attribute-sets",
+      XSLT_NAMESPACE,
+    );
+    if (useAttributeSets) {
+      this.applyAttributeSets(useAttributeSets, context, outputElement, node);
+    }
+
+    for (const attr of node.attributes) {
+      if (shouldCopyAttribute(attr, XSLT_NAMESPACE)) {
+        this.copyLiteralAttribute(attr, context, outputElement);
+      }
+    }
+
+    this.scheduleChildren(node, context, outputElement);
+  },
+
+  /**
+   * Instantiate `xsl:element`. The name's prefix, or the default namespace
+   * for an unprefixed name, resolves against the namespaces in scope on the
+   * instruction; a `namespace` attribute wins (XSLT 1.0 section 7.1.2).
+   * An invalid name or an undeclared prefix is reported and, as in libxslt,
+   * neither the element nor its content is created.
+   *
+   * @param {Element} node - The xsl:element instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the element
+   * @returns {void}
+   */
+  xslElement(node, context, output) {
+    const { name, error } = computedElementName(
+      this.processAttributeValueTemplate(node.getAttribute("name"), context),
+      this.optionalAvt(node, "namespace", context),
+      context.namespaces,
+    );
+    if (error) {
+      this.warnOnce(error);
+      return;
+    }
+    const { namespaceUri, qname } = name;
+    const element = namespaceUri
+      ? context.outputDocument.createElementNS(namespaceUri, qname)
+      : context.outputDocument.createElement(qname);
+    output.appendChild(element);
+
+    const useAttributeSets = node.getAttribute("use-attribute-sets");
+    if (useAttributeSets) {
+      this.applyAttributeSets(useAttributeSets, context, element, node);
+    }
+
+    this.scheduleChildren(node, context, element);
+  },
+
+  /**
+   * Instantiate `xsl:attribute` (XSLT 1.0 section 7.1.3): a prefixed name
+   * uses the namespace bound in scope, `namespace` wins, and a namespaced
+   * attribute without a usable prefix gets a generated one. An invalid name,
+   * an undeclared prefix or `xmlns` is reported and the attribute skipped.
+   *
+   * @param {Element} node - The xsl:attribute instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result element receiving the attribute
+   * @returns {void}
+   */
+  xslAttribute(node, context, output) {
+    if (!this.canAddAttribute(output)) return;
+
+    const { name, error } = computedAttributeName(
+      this.processAttributeValueTemplate(node.getAttribute("name"), context),
+      this.optionalAvt(node, "namespace", context),
+      context.namespaces,
+    );
+    if (error) {
+      this.warnOnce(error);
+      return;
+    }
+    setResultAttribute(output, name, this.instantiateText(node, context));
+  },
+
+  /**
+   * Whether an attribute may still be added to a result node: it must be an
+   * element without children. Attributes added after children are ignored
+   * (as libxslt does), with a single warning per engine.
+   *
+   * @param {Node} target - The result node
+   * @returns {boolean} True when the attribute can be added
+   */
+  canAddAttribute(target) {
+    if (target.nodeType !== 1) return false;
+    if (!target.firstChild) return true;
+    this.warnOnce(
+      "an attribute created after the children of an element is ignored (XSLT 1.0 section 7.1.3)",
+    );
+    return false;
+  },
+
+  /**
+   * Apply the attribute sets named by a `use-attribute-sets` attribute (see
+   * attributeSets.js). The xsl:attribute children of each declaration are
+   * instantiated with the prefixes in scope there.
+   *
+   * @param {string} names - Whitespace separated QNames
+   * @param {XsltContext} context - Context of the instruction
+   * @param {Element} element - The result element receiving the attributes
+   * @param {Element} instruction - The element carrying the attribute, whose
+   *   namespace declarations expand the names
+   * @returns {void}
+   */
+  applyAttributeSets(names, context, element, instruction) {
+    const keys = requireExpandedNames(names, instruction, "use-attribute-sets");
+    applyAttributeSets(this.attributeSets, keys, (declaration) =>
+      this.processChildren(declaration, context, element),
+    );
+  },
+};

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);
+  },
+};