@tradik/xslt-processor 1.0.2 → 1.1.1

package/src/xslt/formatNumber.js

@@ -0,0 +1,220 @@
+/**
+ * XSLT 1.0 `format-number()` picture string formatting.
+ *
+ * Implements the subset of the JDK `DecimalFormat` picture syntax that XSLT 1.0
+ * requires: grouping separator, decimal separator, minimum/maximum fraction
+ * digits, minimum integer digits, percent and per-mille scaling and an optional
+ * negative subpattern. All symbols are taken from an `xsl:decimal-format`
+ * declaration so alternative digits and separators are honoured.
+ */
+
+"use strict";
+
+/** Symbols of the unnamed, default `xsl:decimal-format`. */
+export const DEFAULT_DECIMAL_FORMAT = Object.freeze({
+  decimalSeparator: ".",
+  groupingSeparator: ",",
+  percent: "%",
+  perMille: "‰",
+  zeroDigit: "0",
+  digit: "#",
+  patternSeparator: ";",
+  infinity: "Infinity",
+  nan: "NaN",
+  minusSign: "-",
+});
+
+/**
+ * Split a picture string into its positive and optional negative subpattern.
+ *
+ * @param {string} pattern - The picture string
+ * @param {Object} format - Decimal format symbols
+ * @returns {{positive: string, negative: (string|null)}} The subpatterns
+ */
+function splitSubPatterns(pattern, format) {
+  const index = pattern.indexOf(format.patternSeparator);
+  if (index === -1) return { positive: pattern, negative: null };
+  return {
+    positive: pattern.substring(0, index),
+    negative: pattern.substring(index + format.patternSeparator.length),
+  };
+}
+
+/**
+ * Parse a single subpattern into a formatting description.
+ *
+ * @param {string} subPattern - One subpattern of a picture string
+ * @param {Object} format - Decimal format symbols
+ * @returns {Object} Prefix, suffix, digit counts, grouping size and multiplier
+ */
+function parseSubPattern(subPattern, format) {
+  const special = new Set([
+    format.digit,
+    format.zeroDigit,
+    format.groupingSeparator,
+    format.decimalSeparator,
+  ]);
+
+  let start = 0;
+  while (start < subPattern.length && !special.has(subPattern[start])) start++;
+
+  let end = start;
+  while (end < subPattern.length && special.has(subPattern[end])) end++;
+
+  const prefix = subPattern.substring(0, start);
+  const numeric = subPattern.substring(start, end);
+  const suffix = subPattern.substring(end);
+
+  const decimalIndex = numeric.indexOf(format.decimalSeparator);
+  const integerPart =
+    decimalIndex === -1 ? numeric : numeric.substring(0, decimalIndex);
+  const fractionPart =
+    decimalIndex === -1 ? "" : numeric.substring(decimalIndex + 1);
+
+  const groupingIndex = integerPart.lastIndexOf(format.groupingSeparator);
+  const affixes = prefix + suffix;
+
+  let multiplier = 1;
+  if (affixes.includes(format.percent)) multiplier = 100;
+  else if (affixes.includes(format.perMille)) multiplier = 1000;
+
+  return {
+    prefix,
+    suffix,
+    multiplier,
+    minInteger: countOccurrences(integerPart, format.zeroDigit),
+    minFraction: countOccurrences(fractionPart, format.zeroDigit),
+    maxFraction: Math.min(fractionPart.length, 100),
+    groupingSize:
+      groupingIndex === -1 ? 0 : integerPart.length - groupingIndex - 1,
+  };
+}
+
+/**
+ * Count occurrences of a character inside a string.
+ *
+ * @param {string} text - The text to scan
+ * @param {string} char - The character to count
+ * @returns {number} Number of occurrences
+ */
+function countOccurrences(text, char) {
+  let total = 0;
+  for (const current of text) {
+    if (current === char) total++;
+  }
+  return total;
+}
+
+/**
+ * Insert grouping separators into a run of integer digits.
+ *
+ * @param {string} digits - Integer digits, most significant first
+ * @param {number} size - Grouping size, 0 disables grouping
+ * @param {string} separator - The grouping separator
+ * @returns {string} The grouped digits
+ */
+function applyGrouping(digits, size, separator) {
+  if (size <= 0 || digits.length <= size) return digits;
+
+  let result = "";
+  for (let i = 0; i < digits.length; i++) {
+    const fromEnd = digits.length - i;
+    if (i > 0 && fromEnd % size === 0) result += separator;
+    result += digits[i];
+  }
+  return result;
+}
+
+/**
+ * Translate ASCII digits to the digits of the decimal format.
+ *
+ * @param {string} text - Text containing ASCII digits
+ * @param {string} zeroDigit - The format's zero digit
+ * @returns {string} Text using the format's digit family
+ */
+function translateDigits(text, zeroDigit) {
+  const offset = zeroDigit.codePointAt(0) - 48;
+  if (offset === 0) return text;
+  return text.replaceAll(/\d/g, (digit) =>
+    String.fromCodePoint(digit.codePointAt(0) + offset),
+  );
+}
+
+/**
+ * Format the magnitude of a finite number according to a parsed subpattern.
+ *
+ * @param {number} magnitude - Absolute, already scaled value
+ * @param {Object} spec - Parsed subpattern
+ * @param {Object} format - Decimal format symbols
+ * @returns {string} The formatted number without prefix or suffix
+ */
+function formatMagnitude(magnitude, spec, format) {
+  const fixed = magnitude.toFixed(spec.maxFraction);
+  const [rawInteger, rawFraction = ""] = fixed.split(".");
+
+  let fraction = rawFraction;
+  while (fraction.length > spec.minFraction && fraction.endsWith("0")) {
+    fraction = fraction.slice(0, -1);
+  }
+
+  let integer = rawInteger.padStart(spec.minInteger, "0");
+  if (spec.minInteger === 0 && integer === "0" && fraction.length > 0) {
+    integer = "";
+  }
+
+  integer = applyGrouping(integer, spec.groupingSize, format.groupingSeparator);
+
+  const body =
+    fraction.length > 0
+      ? integer + format.decimalSeparator + fraction
+      : integer;
+
+  return translateDigits(body, format.zeroDigit);
+}
+
+/**
+ * Format a number using an XSLT 1.0 picture string.
+ *
+ * @param {number} value - The number to format
+ * @param {string} pattern - The picture string, e.g. `#,##0.00`
+ * @param {Object} [decimalFormat] - `xsl:decimal-format` symbols
+ * @returns {string} The formatted number
+ *
+ * @example
+ * formatNumber(1234.5, '#,##0.00'); // '1,234.50'
+ * formatNumber(-1234, '#,##0;(#,##0)'); // '(1,234)'
+ */
+export function formatNumber(
+  value,
+  pattern,
+  decimalFormat = DEFAULT_DECIMAL_FORMAT,
+) {
+  const format = { ...DEFAULT_DECIMAL_FORMAT, ...decimalFormat };
+
+  if (typeof value !== "number" || Number.isNaN(value)) return format.nan;
+
+  const subPatterns = splitSubPatterns(pattern, format);
+  const positive = parseSubPattern(subPatterns.positive, format);
+  const isNegative = value < 0;
+
+  let spec = positive;
+  let prefix = positive.prefix;
+  let suffix = positive.suffix;
+
+  if (isNegative) {
+    if (subPatterns.negative !== null) {
+      spec = parseSubPattern(subPatterns.negative, format);
+      prefix = spec.prefix;
+      suffix = spec.suffix;
+    } else {
+      prefix = format.minusSign + positive.prefix;
+    }
+  }
+
+  const magnitude = Math.abs(value) * spec.multiplier;
+  const body = Number.isFinite(magnitude)
+    ? formatMagnitude(magnitude, spec, format)
+    : format.infinity;
+
+  return prefix + body + suffix;
+}

package/src/xslt/functions.js

@@ -0,0 +1,191 @@
+/**
+ * XSLT-defined XPath functions.
+ *
+ * XSLT 1.0 section 12 adds functions to the XPath function library. 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";
+
+/** 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),
+  };
+}
+
+/**
+ * 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));
+
+  return {
+    /**
+     * `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. */
+    key: (args, ctx) => {
+      const name = asString(args[0], ctx);
+      const values = toStringList(evaluator, stringify, evaluate(args[1], ctx));
+      return engine.keyRegistry.lookup(name, values, ownerDocumentOf(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 ? asString(args[2], 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. */
+    "function-available": (args, ctx) => {
+      const name = asString(args[0], ctx);
+      return Object.hasOwn(evaluator.functions, name);
+    },
+
+    /** `element-available(name)` - reflects the XSLT elements the engine runs. */
+    "element-available": (args, ctx) => {
+      const { prefix, localName } = splitQName(asString(args[0], ctx));
+      if (!prefix) return false;
+
+      const namespaceUri =
+        ctx.namespaces[prefix] ?? (prefix === "xsl" ? XSLT_NAMESPACE : null);
+
+      return (
+        namespaceUri === XSLT_NAMESPACE && isXsltElementAvailable(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

@@ -4,3 +4,34 @@
  */
 
 export { 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,141 @@
+/**
+ * `xsl:key` indexing for the XSLT `key()` function.
+ *
+ * Indexes are built lazily, once per (document, key name) pair, and cached in a
+ * `WeakMap` so source documents stay garbage collectable. The registry is
+ * deliberately decoupled from the engine: pattern matching and `use` evaluation
+ * are injected as callbacks.
+ */
+
+"use strict";
+
+/**
+ * Lazily built, per-document indexes for all declared keys.
+ */
+export class KeyIndexRegistry {
+  /**
+   * @param {Object} options - Registry configuration
+   * @param {Object<string, {match: string, use: string}>} options.keys - Declared keys by name
+   * @param {(node: Node, pattern: string) => boolean} options.matchesPattern - XSLT pattern matcher
+   * @param {(node: Node, expression: string) => 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 {Document} doc - The document to search
+   * @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 index = this.getIndex(name, doc);
+    const wanted = Array.isArray(values) ? values : [values];
+    const result = [];
+
+    for (const value of wanted) {
+      for (const node of index.get(value) || []) {
+        if (!result.includes(node)) result.push(node);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Get (building if needed) the index of one key for one document.
+   *
+   * @param {string} name - The key name
+   * @param {Document} doc - The document being indexed
+   * @returns {Map<string, Node[]>} Key value to nodes
+   */
+  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.
+   *
+   * @param {string} name - The key name
+   * @param {Document} doc - The document being indexed
+   * @returns {Map<string, Node[]>} Key value to nodes
+   */
+  buildIndex(name, doc) {
+    const { match, use } = this.keys[name];
+    const index = new Map();
+
+    for (const node of documentOrderNodes(doc)) {
+      if (!this.matchesPattern(node, match)) continue;
+
+      for (const value of this.evaluateUse(node, use)) {
+        const bucket = index.get(value);
+        if (bucket) bucket.push(node);
+        else index.set(value, [node]);
+      }
+    }
+
+    return index;
+  }
+}
+
+/**
+ * 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]);
+    }
+  }
+}