@tradik/xslt-processor 1.0.3 → 1.3.0

package/src/xslt/engine/templateInvocation.js

@@ -0,0 +1,253 @@
+/**
+ * Template invocation: xsl:apply-templates, xsl:apply-imports,
+ * xsl:call-template, the built-in template rules and template parameters.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { childAxis } from "../../xpath/axes.js";
+import { requireExpandedName } from "../declarationNames.js";
+import { selectNodes } from "./controlFlow.js";
+import { LoopFrame, SequenceFrame } from "./workStack.js";
+
+export const templateInvocationMethods = {
+  /**
+   * Apply templates to a node list. The nodes are processed one at a time
+   * from the work stack (see workStack.js).
+   *
+   * @param {Node|Node[]} nodes - The nodes to process, in order
+   * @param {string|null} mode - The mode
+   * @param {XsltContext} context - Context of the invoking instruction
+   * @param {Node} output - The result node receiving the output
+   * @param {Object<string, *>|null} [params] - Values of xsl:with-param by name
+   * @param {boolean} [builtin] - Whether a built-in template rule applies
+   *   them, which counts as a template instantiation (as in libxslt)
+   * @returns {void}
+   */
+  applyTemplates(nodes, mode, context, output, params = null, builtin = false) {
+    const nodeList = Array.isArray(nodes) ? nodes : [nodes];
+    if (nodeList.length === 0) return;
+
+    const frame = new LoopFrame(nodeList.length, (index) =>
+      this.applyTemplateRule(nodeList, index, mode, context, output, params),
+    );
+    frame.template = builtin;
+    this.continueWith(frame);
+  },
+
+  /**
+   * Apply the best template rule to one node of a list, else the built-in
+   * rule.
+   *
+   * @param {Node[]} nodeList - The current node list
+   * @param {number} index - Index of the node in the list
+   * @param {string|null} mode - The mode
+   * @param {XsltContext} context - Context of the invoking instruction
+   * @param {Node} output - The result node receiving the output
+   * @param {Object<string, *>|null} params - Values of xsl:with-param by name
+   * @returns {void}
+   */
+  applyTemplateRule(nodeList, index, mode, context, output, params) {
+    const node = nodeList[index];
+    const template = this.findMatchingTemplate(node, mode, context);
+
+    if (template) {
+      const newContext = this.invocationContext(context, template, {
+        currentNode: node,
+        currentNodeList: nodeList,
+        position: index + 1,
+        currentMode: mode,
+      });
+
+      this.processTemplate(template.node, newContext, output, params);
+    } else {
+      this.applyBuiltinTemplate(node, mode, context, output, params);
+    }
+  },
+
+  /**
+   * Context of a template invocation: no local bindings, the template as
+   * current template and the prefixes in scope on the xsl:template element.
+   *
+   * @param {XsltContext} context - Context of the invoking instruction
+   * @param {object} template - The template record
+   * @param {object} [overrides] - Further properties to change
+   * @returns {XsltContext} The invocation context
+   */
+  invocationContext(context, template, overrides = {}) {
+    const invocation = context.clone({
+      currentTemplate: template,
+      ...overrides,
+      fresh: true,
+    });
+    invocation.namespaces = template.namespaces ?? context.namespaces;
+    return invocation;
+  },
+
+  /**
+   * Apply the built-in template rules (XSLT 1.0 section 5.8). Parameters are
+   * passed on to the templates applied to the children, as libxslt does.
+   *
+   * @param {Node} node - The node without a matching template
+   * @param {string|null} mode - The mode
+   * @param {XsltContext} context - Context of the invoking instruction
+   * @param {Node} output - The result node receiving the output
+   * @param {Object<string, *>|null} [params] - Values of xsl:with-param by name
+   * @returns {void}
+   */
+  applyBuiltinTemplate(node, mode, context, output, params = null) {
+    switch (node.nodeType) {
+      case 1: // Element
+      case 9: // Document
+      case 11: // Document Fragment
+        this.applyTemplates(
+          childAxis(node),
+          mode,
+          context,
+          output,
+          params,
+          true,
+        );
+        break;
+
+      case 2: // Attribute
+      case 3: // Text
+      case 4: // CDATA
+        // Copy the string value; a text node stands for its whole text run
+        output.appendChild(
+          context.outputDocument.createTextNode(
+            this.xpathEvaluator.getStringValue(node),
+          ),
+        );
+        break;
+
+      // Comments and PIs have no built-in template
+    }
+  },
+
+  /**
+   * Instantiate a template. Each `xsl:param` takes the value of the
+   * `xsl:with-param` of the same name, else its default, evaluated after the
+   * preceding parameters were bound (XSLT 1.0 section 11.6). The body runs
+   * from the work stack once the invoking instruction returns.
+   *
+   * @param {Element|object} templateNode - The xsl:template element
+   * @param {XsltContext} context - A fresh invocation context
+   * @param {Node} output - The result node receiving the output
+   * @param {Object<string, *>|null} [params] - Values of xsl:with-param by name
+   * @returns {void}
+   */
+  processTemplate(templateNode, context, output, params = null) {
+    for (
+      let child = templateNode.firstChild;
+      child;
+      child = child.nextSibling
+    ) {
+      if (child.nodeType !== 1 || !this.isXsltElement(child, "param")) continue;
+
+      const name = child.getAttribute("name");
+      context.parameters[name] =
+        params && Object.hasOwn(params, name)
+          ? params[name]
+          : this.evaluateVariable(
+              { node: child, select: child.getAttribute("select") },
+              context,
+            );
+    }
+
+    const frame = new SequenceFrame(this, templateNode, context, output);
+    frame.template = true;
+    this.continueWith(frame);
+  },
+
+  /**
+   * Instantiate `xsl:apply-templates`: the selected nodes (default the
+   * children), sorted by the xsl:sort children, with the xsl:with-param
+   * values.
+   *
+   * @param {Element} node - The xsl:apply-templates instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @returns {void}
+   */
+  xslApplyTemplates(node, context, output) {
+    const select = node.getAttribute("select") || "node()";
+    const mode = node.getAttribute("mode") || null;
+    const nodes = this.sortNodes(
+      selectNodes(this, select, context),
+      this.sortElementsOf(node),
+      context,
+    );
+    const params = this.withParams(node, context);
+    this.applyTemplates(nodes, mode, context, output, params);
+  },
+
+  /**
+   * Instantiate `xsl:apply-imports`.
+   *
+   * Only templates with a lower import precedence than the template being
+   * instantiated are considered; when none matches, the built-in template rules
+   * apply, exactly as for `xsl:apply-templates`.
+   *
+   * @param {Element} node - The `xsl:apply-imports` element
+   * @param {XsltContext} context - The current XSLT context
+   * @param {Node} output - The result tree node receiving the output
+   * @returns {void}
+   */
+  xslApplyImports(node, context, output) {
+    const currentNode = context.currentNode;
+    const mode = context.currentMode ?? null;
+    const precedence = context.currentTemplate
+      ? context.currentTemplate.importPrecedence || 0
+      : 0;
+
+    const template = this.findMatchingTemplate(
+      currentNode,
+      mode,
+      context,
+      precedence,
+    );
+
+    if (!template) {
+      this.applyBuiltinTemplate(currentNode, mode, context, output);
+      return;
+    }
+
+    // xsl:apply-imports passes no parameters (XSLT 1.0 section 5.6)
+    this.processTemplate(
+      template.node,
+      this.invocationContext(context, template),
+      output,
+    );
+  },
+
+  /**
+   * Instantiate `xsl:call-template` with its xsl:with-param values.
+   *
+   * @param {Element} node - The xsl:call-template instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @returns {void}
+   * @throws {Error} When no template has that name
+   */
+  xslCallTemplate(node, context, output) {
+    const name = node.getAttribute("name");
+    const template = this.findNamedTemplate(
+      requireExpandedName(name ?? "", node, "xsl:call-template name"),
+    );
+    if (!template) {
+      throw new Error(`Template not found: ${name}`);
+    }
+
+    // A named template does not become the current template rule
+    const invocation = this.invocationContext(context, template, {
+      currentTemplate: context.currentTemplate,
+    });
+    this.processTemplate(
+      template.node,
+      invocation,
+      output,
+      this.withParams(node, context),
+    );
+  },
+};

package/src/xslt/engine/templateRules.js

@@ -0,0 +1,243 @@
+/**
+ * The template registry: registration of xsl:template, default priorities,
+ * and the choice of the template rule or named template to instantiate.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { calculatePriority } from "../templatePriority.js";
+import { inScopeNamespaces } from "../stylesheetNamespaces.js";
+import { requireExpandedName } from "../declarationNames.js";
+import { checkLocalBindings, checkPattern } from "../stylesheetChecks.js";
+
+/**
+ * Split a pattern on the `|` operators that are not inside a predicate or a
+ * string literal.
+ *
+ * @param {string} pattern - The match pattern
+ * @returns {string[]} The alternatives, untrimmed; a trailing empty one is
+ *   dropped
+ */
+export function splitUnionPattern(pattern) {
+  const parts = [];
+  let start = 0;
+  let depth = 0;
+  let quote = "";
+
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i];
+    if (quote) {
+      if (char === quote) quote = "";
+    } else if (char === '"' || char === "'") {
+      quote = char;
+    } else if (char === "[") {
+      depth++;
+    } else if (char === "]") {
+      depth--;
+    } else if (char === "|" && depth === 0) {
+      parts.push(pattern.slice(start, i));
+      start = i + 1;
+    }
+  }
+
+  if (start < pattern.length) parts.push(pattern.slice(start));
+  return parts;
+}
+
+/**
+ * Whether a template rule may be chosen for a mode below an import
+ * precedence limit.
+ *
+ * @param {object} template - The template record
+ * @param {string|null} mode - The mode
+ * @param {number} maxImportPrecedence - Exclusive import precedence limit
+ * @returns {boolean} True when the template is a candidate
+ */
+function isCandidateRule(template, mode, maxImportPrecedence) {
+  return (
+    template.mode === mode &&
+    Boolean(template.match) &&
+    (template.importPrecedence || 0) < maxImportPrecedence
+  );
+}
+
+/**
+ * Whether a matching template rule wins over the best one so far: a higher
+ * import precedence wins; on equal precedence a priority that is not lower
+ * wins, so the last template in stylesheet order wins ties (the XSLT 1.0
+ * section 5.5 recovery, as in libxslt).
+ *
+ * @param {object} template - The matching template
+ * @param {object|null} best - The best template so far
+ * @returns {boolean} True when `template` becomes the best one
+ */
+function outranks(template, best) {
+  if (!best) return true;
+  const precedence = template.importPrecedence || 0;
+  const bestPrecedence = best.importPrecedence || 0;
+  return (
+    precedence > bestPrecedence ||
+    (precedence === bestPrecedence && template.priority >= best.priority)
+  );
+}
+
+export const templateRuleMethods = {
+  /**
+   * Register a template rule.
+   *
+   * A union match pattern is equivalent to a set of template rules, one per
+   * alternative (XSLT 1.0 section 5.5), so each alternative is registered
+   * separately with its own default priority.
+   *
+   * @param {Element} node - The xsl:template element
+   * @returns {void}
+   */
+  registerTemplate(node) {
+    const match = node.getAttribute("match");
+    if (match !== null) {
+      checkPattern(this.patternMatcher, match, "xsl:template match");
+    }
+    checkLocalBindings(node, (message) => this.warnOnce(message));
+    const name = node.getAttribute("name");
+    const nameKey = name === null ? null : this.namedTemplateKey(node, name);
+    const mode = node.getAttribute("mode") || null;
+    const priorityAttr = node.getAttribute("priority");
+    const alternatives = match
+      ? this.splitUnionPattern(match).map((p) => p.trim())
+      : [null];
+
+    const namespaces = inScopeNamespaces(node);
+    for (const alternative of alternatives) {
+      this.templates.push({
+        match: alternative,
+        name,
+        nameKey,
+        mode,
+        namespaces,
+        priority: priorityAttr
+          ? parseFloat(priorityAttr)
+          : this.calculatePriority(alternative),
+        importPrecedence: this.currentImportPrecedence,
+        node,
+      });
+    }
+  },
+
+  /**
+   * Expand the name of a named template, rejecting a second template of the
+   * same expanded name and import precedence (XSLT 1.0 section 6), as
+   * libxslt does.
+   *
+   * @param {Element} node - The xsl:template element
+   * @param {string} name - Its name attribute
+   * @returns {string} The expanded name key
+   * @throws {Error} When the name is invalid or already used
+   */
+  namedTemplateKey(node, name) {
+    const key = requireExpandedName(name, node, "xsl:template name");
+    const duplicate = this.templates.some(
+      (template) =>
+        template.nameKey === key &&
+        template.importPrecedence === this.currentImportPrecedence,
+    );
+    if (duplicate) {
+      throw new Error(
+        `xsl:template: duplicate template name "${name}" at the same import precedence (XSLT 1.0 section 6)`,
+      );
+    }
+    return key;
+  },
+
+  /**
+   * Default priority of a single match pattern (see templatePriority.js).
+   *
+   * @param {string|null} matchPattern - The match pattern
+   * @returns {number} The default priority
+   */
+  calculatePriority(matchPattern) {
+    return calculatePriority(matchPattern ? matchPattern.trim() : matchPattern);
+  },
+
+  /**
+   * Split a union pattern into its alternatives (see splitUnionPattern).
+   *
+   * @param {string} pattern - The match pattern
+   * @returns {string[]} The alternatives
+   */
+  splitUnionPattern(pattern) {
+    return splitUnionPattern(pattern);
+  },
+
+  /**
+   * Find the best matching template rule for a node (XSLT 1.0 section 5.5).
+   * Every candidate's pattern is tested, in stylesheet order.
+   *
+   * @param {Node} node - The node to process
+   * @param {string|null} mode - The mode
+   * @param {XsltContext} context - Context supplying variables
+   * @param {number} [maxImportPrecedence] - Only templates of a lower import
+   *   precedence are considered (xsl:apply-imports)
+   * @returns {object|null} The template, or null for the built-in rules
+   */
+  findMatchingTemplate(node, mode, context, maxImportPrecedence = Infinity) {
+    let best = null;
+    for (const template of this.templates) {
+      if (
+        isCandidateRule(template, mode, maxImportPrecedence) &&
+        this.matchesPattern(
+          node,
+          template.match,
+          context,
+          template.namespaces,
+        ) &&
+        outranks(template, best)
+      ) {
+        best = template;
+      }
+    }
+    return best;
+  },
+
+  /**
+   * Find the named template with the highest import precedence; among equal
+   * precedences the last one in stylesheet order wins.
+   *
+   * @param {string} key - Expanded name of the template (see
+   *   declarationNames.js)
+   * @returns {object|null} The template, or null when none has that name
+   */
+  findNamedTemplate(key) {
+    let best = null;
+    for (const template of this.templates) {
+      if (
+        template.nameKey === key &&
+        (!best ||
+          (template.importPrecedence || 0) >= (best.importPrecedence || 0))
+      ) {
+        best = template;
+      }
+    }
+    return best;
+  },
+
+  /**
+   * Check whether a node matches an XSLT pattern (see patterns.js).
+   *
+   * Errors raised while evaluating a predicate make the pattern not match,
+   * as before the compiled matcher existed.
+   *
+   * @param {Node} node - The candidate node
+   * @param {string} pattern - The XSLT pattern
+   * @param {XsltContext|null} context - Context supplying variables and namespaces
+   * @param {Object<string, string>} [namespaces] - Prefixes in scope on the
+   *   element holding the pattern, when they differ from the context's
+   * @returns {boolean} Whether the node matches
+   */
+  matchesPattern(node, pattern, context, namespaces) {
+    try {
+      return this.patternMatcher.matches(node, pattern, context, namespaces);
+    } catch {
+      return false;
+    }
+  },
+};

package/src/xslt/engine/textInstructions.js

@@ -0,0 +1,171 @@
+/**
+ * Instructions producing text: xsl:value-of, xsl:text, xsl:comment,
+ * xsl:processing-instruction and xsl:message, and attribute value templates.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { evaluateAvt } from "../avt.js";
+
+/**
+ * Append a text node to the result unless the text is empty.
+ *
+ * @param {XsltContext} context - The current context
+ * @param {Node} output - The result node receiving the text
+ * @param {string} text - The text
+ * @param {boolean} disableOutputEscaping - Whether the serializer must write
+ *   the text without escaping
+ * @returns {void}
+ */
+function appendText(context, output, text, disableOutputEscaping) {
+  if (!text) return;
+  const textNode = context.outputDocument.createTextNode(text);
+  if (disableOutputEscaping) {
+    textNode._disableOutputEscaping = true;
+  }
+  output.appendChild(textNode);
+}
+
+/**
+ * Whether an instruction has disable-output-escaping="yes".
+ *
+ * @param {Element} node - xsl:value-of or xsl:text
+ * @returns {boolean} True when output escaping is disabled
+ */
+function disablesOutputEscaping(node) {
+  return node.getAttribute("disable-output-escaping") === "yes";
+}
+
+export const textInstructionMethods = {
+  /**
+   * Instantiate `xsl:value-of`: the string value of the expression.
+   *
+   * @param {Element} node - The xsl:value-of instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the text
+   * @returns {void}
+   */
+  xslValueOf(node, context, output) {
+    const result = this.evaluateXPath(node.getAttribute("select"), context);
+    appendText(
+      context,
+      output,
+      this.xpathEvaluator.toString(result),
+      disablesOutputEscaping(node),
+    );
+  },
+
+  /**
+   * Instantiate `xsl:text`: its text and CDATA children.
+   *
+   * @param {Element} node - The xsl:text instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the text
+   * @returns {void}
+   */
+  xslText(node, context, output) {
+    let text = "";
+    for (const child of node.childNodes) {
+      if (child.nodeType === 3 || child.nodeType === 4) {
+        text += child.nodeValue || "";
+      }
+    }
+    appendText(context, output, text, disablesOutputEscaping(node));
+  },
+
+  /**
+   * Instantiate the content of an instruction and return its string value,
+   * for instructions whose result is text (attribute, comment, PI, message).
+   *
+   * @param {Element} node - The instruction
+   * @param {XsltContext} context - The current context
+   * @returns {string} The text of the instantiated content
+   */
+  instantiateText(node, context) {
+    const fragment = context.outputDocument.createDocumentFragment();
+    this.processChildren(node, context, fragment);
+    return this.xpathEvaluator.getStringValue(fragment);
+  },
+
+  /**
+   * Instantiate `xsl:comment`. "--" and a trailing "-" are made safe by the
+   * serializer (XSLT 1.0 section 7.4).
+   *
+   * @param {Element} node - The xsl:comment instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the comment
+   * @returns {void}
+   */
+  xslComment(node, context, output) {
+    const text = this.instantiateText(node, context);
+    output.appendChild(context.outputDocument.createComment(text));
+  },
+
+  /**
+   * Instantiate `xsl:processing-instruction`, with the error recovery of
+   * XSLT 1.0 section 7.3: "?>" cannot end the data early.
+   *
+   * @param {Element} node - The xsl:processing-instruction instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the PI
+   * @returns {void}
+   */
+  xslProcessingInstruction(node, context, output) {
+    const name = this.processAttributeValueTemplate(
+      node.getAttribute("name"),
+      context,
+    );
+    const data = this.instantiateText(node, context).replaceAll("?>", "? >");
+    const pi = context.outputDocument.createProcessingInstruction(name, data);
+    output.appendChild(pi);
+  },
+
+  /**
+   * Instantiate `xsl:message`: log the text, and stop the transformation
+   * with terminate="yes".
+   *
+   * @param {Element} node - The xsl:message instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} _output - Unused: a message produces no output
+   * @returns {void}
+   * @throws {Error} With terminate="yes"
+   */
+  xslMessage(node, context, _output) {
+    const terminate = node.getAttribute("terminate") === "yes";
+    const text = this.instantiateText(node, context);
+
+    console.log("XSLT Message:", text);
+
+    if (terminate) {
+      throw new Error(`XSLT terminated: ${text}`);
+    }
+  },
+
+  /**
+   * Evaluate an attribute value template (see avt.js).
+   *
+   * @param {string} value - The attribute value
+   * @param {XsltContext} context - The current context
+   * @returns {string} The resulting text
+   */
+  processAttributeValueTemplate(value, context) {
+    return evaluateAvt(value, (expr) =>
+      this.xpathEvaluator.toString(this.evaluateXPath(expr, context)),
+    );
+  },
+
+  /**
+   * Evaluate an optional attribute value template attribute.
+   *
+   * @param {Element} node - The instruction
+   * @param {string} name - The attribute name
+   * @param {XsltContext} context - The current context
+   * @returns {string|null} The value, or null when the attribute is absent
+   */
+  optionalAvt(node, name, context) {
+    const raw = node.getAttribute(name);
+    return raw === null
+      ? null
+      : this.processAttributeValueTemplate(raw, context);
+  },
+};