@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/xslt/runtime/keys.js

@@ -0,0 +1,141 @@
+/**
+ * Keys (XSLT 3.0 section 20.2): for each xsl:key name and document, an
+ * index from key values to the nodes that match the key's pattern, built
+ * on the first key() call for that document.
+ *
+ * @module @tradik/xslt3/xslt/runtime/keys
+ */
+
+import { getCollation } from "../../functions/collations.js";
+import { stringItem } from "../../xpath/eval/atomics.js";
+import { attributesOf } from "../../xpath/eval/domNodes.js";
+import { namespaceNodesOf } from "../../xpath/eval/namespaceNodes.js";
+import { atomize } from "../../xdm/nodes.js";
+import { canonicalString } from "../../xdm/lexical.js";
+import { xsltError } from "../names.js";
+import { patternMatches } from "../patterns/compile.js";
+import { comparisonKey, NAN_KEY } from "./atomicKeys.js";
+import { derive, evaluate } from "./context.js";
+import { bodySequence } from "./values.js";
+
+/**
+ * The index string of a key value.
+ * @param {*} value - Atomic value
+ * @param {object} definition - Key definition (collation, compatible)
+ * @returns {string}
+ */
+export function keyValueString(value, definition) {
+  const atomic = definition.compatible
+    ? stringItem(canonicalString(value))
+    : value;
+  const collation = definition.collation
+    ? getCollation(definition.collation)
+    : null;
+  return comparisonKey(atomic, collation);
+}
+
+/**
+ * The index strings of the key values of a node, or of the values sought:
+ * one per value, or one for the whole sequence of a composite key (XSLT
+ * 3.0 section 20.2.2), which matches only an equal sequence.
+ * @param {Array} values - Atomic values
+ * @param {object} definition - Key definition
+ * @returns {string[]}
+ */
+function indexKeys(values, definition) {
+  const keys = values.map((value) => keyValueString(value, definition));
+  if (!definition.composite) return keys;
+  return keys.includes(NAN_KEY) ? [NAN_KEY] : [JSON.stringify(keys)];
+}
+
+/**
+ * All nodes of a tree in document order (elements, attributes, text...).
+ * @param {Node} root
+ * @param {boolean} namespaces - Include the namespace nodes
+ * @returns {Node[]}
+ */
+function treeNodes(root, namespaces) {
+  const nodes = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    nodes.push(node);
+    if (node.nodeType === 1) {
+      if (namespaces) nodes.push(...namespaceNodesOf(node));
+      nodes.push(...attributesOf(node));
+    }
+    const children = node.childNodes ?? [];
+    for (let i = children.length - 1; i >= 0; i--) {
+      if (children[i].nodeType !== 10) stack.push(children[i]);
+    }
+  }
+  return nodes;
+}
+
+/**
+ * Builds the index of a key for a tree.
+ * @param {object[]} definitions - The xsl:key declarations of the name
+ * @param {Node} root
+ * @param {object} xc
+ * @returns {Map<string, Node[]>}
+ */
+function buildIndex(definitions, root, xc) {
+  const index = new Map();
+  const machine = xc.tx.machine;
+  const namespaces = definitions.some((definition) => definition.namespaces);
+  for (const node of treeNodes(root, namespaces)) {
+    for (const definition of definitions) {
+      const nodeXc = derive(xc, { item: node, position: 1, size: 1 });
+      if (!patternMatches(definition.match, node, nodeXc)) continue;
+      const values = definition.use
+        ? evaluate(definition.use, nodeXc)
+        : bodySequence(definition.body, nodeXc, machine);
+      for (const key of indexKeys(atomize(values), definition)) {
+        // NaN is not equal to itself: it finds nothing
+        if (key === NAN_KEY) continue;
+        let list = index.get(key);
+        if (!list) index.set(key, (list = []));
+        if (list.at(-1) !== node) list.push(node);
+      }
+    }
+  }
+  return index;
+}
+
+/**
+ * Looks up nodes by key.
+ * @param {object} xc - Context of the call
+ * @param {string} name - Clark name of the key
+ * @param {Array} values - Atomic values sought
+ * @param {Node} root - Root of the tree searched
+ * @param {object} [owner] - Package compiler of the call (default: the
+ *   top-level package)
+ * @returns {Node[]} nodes in document order
+ */
+export function keyLookup(xc, name, values, root, owner) {
+  const { tx } = xc;
+  // keys are local to the package of the call (XSLT 3.0 section 3.5.5)
+  const definitions = (owner ?? tx.stylesheet).keys.get(name);
+  if (!definitions) throw xsltError("XTDE1260", `No key named ${name}`);
+  let byRoot = tx.keyIndexes.get(definitions);
+  if (!byRoot) tx.keyIndexes.set(definitions, (byRoot = new Map()));
+  let index = byRoot.get(root);
+  if (index === "building") {
+    throw xsltError("XTDE0640", `The key ${name} depends on itself`);
+  }
+  if (!index) {
+    byRoot.set(root, "building");
+    const base = derive(xc, { env: tx.globalEnv, rule: null, temporary: true });
+    try {
+      index = buildIndex(definitions, root, base);
+    } finally {
+      byRoot.delete(root);
+    }
+    byRoot.set(root, index);
+  }
+  const found = new Set();
+  for (const key of indexKeys(values, definitions[0])) {
+    for (const node of index.get(key) ?? []) found.add(node);
+  }
+  return tx.dyn.order.sort([...found]);
+}

package/src/xslt/runtime/lazy.js

@@ -0,0 +1,97 @@
+/**
+ * Variables evaluated on first use: an entry of the variable environment
+ * (see xpath/eval/scope.js) whose `value` is computed when it is first
+ * read, so that a variable that is never used never fails, and a
+ * circular definition is reported (XTDE0640).
+ *
+ * An xsl:try does not catch the errors of variables declared outside it
+ * (XSLT 3.0 section 8.3), although they are computed when first read
+ * inside: each xsl:try marks the pending entries of its environment, and
+ * the error of a marked entry names the xsl:try instances it escapes.
+ *
+ * @module @tradik/xslt3/xslt/runtime/lazy
+ */
+
+import { displayName, xsltError } from "../names.js";
+
+const PENDING = 0;
+const RUNNING = 1;
+const DONE = 2;
+
+/** Marker of the global variables: outside every xsl:try. */
+export const EVERY_TRY = Symbol("every xsl:try");
+
+/** The marks of every global variable. */
+const GLOBAL = Object.freeze(new Set([EVERY_TRY]));
+
+/**
+ * Marks the variables of an environment that are not computed yet as
+ * declared outside an xsl:try about to run.
+ * @param {object|null} env - The environment of the xsl:try
+ * @param {object|null} globalEnv - Where the global variables start
+ * @param {object} marker - Identifies this run of the xsl:try
+ */
+export function markOutside(env, globalEnv, marker) {
+  for (let entry = env; entry && entry !== globalEnv; entry = entry.next) {
+    if (entry instanceof LazyEntry && entry.state !== DONE) {
+      entry.outside ??= new Set();
+      entry.outside.add(marker);
+    }
+  }
+}
+
+/**
+ * Whether an error escapes a run of xsl:try (raised by a variable
+ * declared outside it).
+ * @param {*} error
+ * @param {object} marker - The run of the xsl:try
+ * @returns {boolean}
+ */
+export const escapesTry = (error, marker) =>
+  Boolean(error?.outsideTry?.has(EVERY_TRY) || error?.outsideTry?.has(marker));
+
+/** An environment entry computed on first use. */
+export class LazyEntry {
+  /**
+   * @param {object|null} next - The enclosing entries
+   * @param {() => Array} compute - Computes the value
+   * @param {string} name - Variable name, for the circularity error
+   * @param {boolean} [global] - A global variable (outside every xsl:try)
+   */
+  constructor(next, compute, name, global = false) {
+    this.next = next;
+    this.compute = compute;
+    this.name = name;
+    /** @type {Set<object|symbol>|null} the xsl:try runs it is outside of */
+    this.outside = global ? GLOBAL : null;
+    this.state = PENDING;
+    this.cached = undefined;
+  }
+
+  /** @returns {Array} the value, computed once */
+  get value() {
+    if (this.state === DONE) return this.cached;
+    if (this.state === RUNNING) {
+      throw xsltError(
+        "XTDE0640",
+        `Circular definition of $${displayName(this.name)}`,
+      );
+    }
+    this.state = RUNNING;
+    try {
+      this.cached = this.compute();
+    } catch (error) {
+      this.state = PENDING;
+      if (this.outside && error instanceof Error) {
+        error.outsideTry = new Set([
+          ...(error.outsideTry ?? []),
+          ...this.outside,
+        ]);
+      }
+      throw error;
+    }
+    this.state = DONE;
+    this.compute = null;
+    return this.cached;
+  }
+}

package/src/xslt/runtime/locations.js

@@ -0,0 +1,86 @@
+/**
+ * Where an error of a stylesheet comes from: the module URI and, when the
+ * DOM records them (@xmldom/xmldom does, jsdom does not), the line and
+ * column of the stylesheet element. Compiled steps are mapped to their
+ * element at compile time; the location is worked out only when an error
+ * is raised, so running instructions costs nothing more.
+ *
+ * @module @tradik/xslt3/xslt/runtime/locations
+ */
+
+import { XPathError } from "../../errors.js";
+import { moduleUriOf } from "../compiler/elementInfo.js";
+
+/**
+ * Location of an error.
+ * @typedef {object} ErrorLocation
+ * @property {string} [module] - URI of the stylesheet module
+ * @property {number} [line] - 1-based line of the element
+ * @property {number} [column] - 1-based column of the element
+ */
+
+/** @type {WeakMap<object, Node>} compiled steps to stylesheet nodes */
+const stepNodes = new WeakMap();
+
+/**
+ * Records the stylesheet node a compiled step comes from.
+ * @param {Function|object|null} step
+ * @param {Node} node
+ */
+export function recordStep(step, node) {
+  if (step) stepNodes.set(step, node);
+}
+
+/**
+ * The location of a stylesheet node.
+ * @param {Node} node - Element, or a text node (its parent is used)
+ * @returns {ErrorLocation}
+ */
+export function locationOf(node) {
+  const element = node.nodeType === 1 ? node : node.parentNode;
+  const location = {};
+  const module = element ? moduleUriOf(element) : undefined;
+  if (module !== undefined) location.module = module;
+  if (Number.isInteger(node.lineNumber)) location.line = node.lineNumber;
+  if (Number.isInteger(node.columnNumber)) location.column = node.columnNumber;
+  return location;
+}
+
+/**
+ * Adds the location of a stylesheet node to an error that has none: the
+ * `location` property, and "(line N of URI)" in the message when the
+ * line is known.
+ * @param {*} error
+ * @param {Node|undefined} node
+ * @returns {*} the error
+ */
+export function locate(error, node) {
+  if (!(error instanceof XPathError) || error.location || !node) return error;
+  const location = locationOf(node);
+  error.location = location;
+  if (location.line !== undefined) {
+    const where = location.module ? ` of ${location.module}` : "";
+    // the message without location, for err:description in xsl:catch
+    error.plainMessage = error.message;
+    error.message += ` (line ${location.line}${where})`;
+  }
+  return error;
+}
+
+/**
+ * Adds to an error the location of the step that was running: the last
+ * step started by the innermost body frame.
+ * @param {*} error
+ * @param {object[]} frames - The work stack (see machine.js)
+ * @param {number} base - Frames below it belong to an outer driver
+ * @returns {*} the error
+ */
+export function locateInFrames(error, frames, base) {
+  if (!(error instanceof XPathError) || error.location) return error;
+  for (let i = frames.length - 1; i >= base; i--) {
+    const { body, index } = frames[i];
+    const node = body && index > 0 ? stepNodes.get(body[index - 1]) : null;
+    if (node) return locate(error, node);
+  }
+  return error;
+}

package/src/xslt/runtime/machine.js

@@ -0,0 +1,137 @@
+/**
+ * The explicit work stack that runs sequence constructors.
+ *
+ * Template rules nest as deep as the documents and recursions they
+ * process. Instantiating each level with JavaScript recursion costs
+ * several native frames per level and exhausts the call stack long before
+ * 10,000 levels, so instructions whose content comes last (the content of
+ * literal result elements, xsl:if, xsl:choose, template invocations, the
+ * iterations of xsl:for-each and xsl:apply-templates) push a frame and
+ * return; the driver runs the frame before the next instruction of the
+ * frame below. Instructions that need a result at once (variables,
+ * attributes, parameters, function calls) run a nested driver.
+ *
+ * @module @tradik/xslt3/xslt/runtime/machine
+ */
+
+import { xsltError } from "../names.js";
+import { locateInFrames } from "./locations.js";
+
+/**
+ * A compiled sequence constructor: steps that are instructions
+ * `(xc, out, machine) => void` or variable bindings `{binding}`.
+ * @typedef {Array<Function|{binding: Function}>} Body
+ */
+
+/** Runs the steps of a body with a context and a receiver. */
+export class BodyFrame {
+  /**
+   * @param {Body} body
+   * @param {object} xc - XSLT context
+   * @param {object} out - Receiver
+   */
+  constructor(body, xc, out) {
+    this.body = body;
+    this.index = 0;
+    this.xc = xc;
+    this.out = out;
+  }
+
+  /**
+   * Runs steps until one pushes a frame or none is left.
+   * @param {Machine} machine
+   * @returns {boolean} false when the body is done
+   */
+  advance(machine) {
+    const body = this.body;
+    const frames = machine.frames;
+    const height = frames.length;
+    while (this.index < body.length) {
+      const step = body[this.index++];
+      if (step.binding) this.xc = step.binding(this.xc, machine);
+      else step(this.xc, this.out, machine);
+      if (frames.length !== height) return true;
+    }
+    return false;
+  }
+}
+
+/** Visits the items of a sequence one after the other. */
+export class LoopFrame {
+  /**
+   * @param {number} count
+   * @param {(index: number, machine: Machine) => void} visit - May push
+   *   frames, which run before the next visit
+   */
+  constructor(count, visit) {
+    this.count = count;
+    this.index = 0;
+    this.visit = visit;
+  }
+
+  /**
+   * @param {Machine} machine
+   * @returns {boolean} false when every item is visited
+   */
+  advance(machine) {
+    const frames = machine.frames;
+    const height = frames.length;
+    while (this.index < this.count) {
+      this.visit(this.index++, machine);
+      if (frames.length !== height) return true;
+    }
+    return false;
+  }
+}
+
+/** The work stack of a transformation. */
+export class Machine {
+  /** @param {number} [maxDepth] - Deepest stack allowed */
+  constructor(maxDepth = 1e6) {
+    this.frames = [];
+    this.maxDepth = maxDepth;
+  }
+
+  /**
+   * Schedules a frame: it runs before the next step of the current one.
+   * @param {BodyFrame|LoopFrame} frame
+   */
+  push(frame) {
+    if (this.frames.length >= this.maxDepth) {
+      throw xsltError(
+        "XTDE0000",
+        "Too deep recursion: the stylesheet probably loops",
+      );
+    }
+    this.frames.push(frame);
+  }
+
+  /**
+   * Runs a frame and everything it schedules to completion.
+   * @param {BodyFrame|LoopFrame} frame
+   */
+  run(frame) {
+    const frames = this.frames;
+    const base = frames.length;
+    this.push(frame);
+    try {
+      while (frames.length > base) {
+        if (!frames[frames.length - 1].advance(this)) frames.pop();
+      }
+    } catch (error) {
+      locateInFrames(error, frames, base);
+      frames.length = base;
+      throw error;
+    }
+  }
+
+  /**
+   * Runs a body to completion.
+   * @param {Body} body
+   * @param {object} xc
+   * @param {object} out
+   */
+  runBody(body, xc, out) {
+    if (body.length > 0) this.run(new BodyFrame(body, xc, out));
+  }
+}

package/src/xslt/runtime/merging.js

@@ -0,0 +1,167 @@
+/**
+ * xsl:merge at run time (XSLT 3.0 sections 15.3 to 15.6): the merge
+ * input sequences with their merge key values, checked to be sorted (or
+ * sorted first), merged in a stable order, and partitioned into groups
+ * of equal composite keys; and the functions current-merge-group() and
+ * current-merge-key().
+ *
+ * @module @tradik/xslt3/xslt/runtime/merging
+ */
+
+import { xsltError } from "../names.js";
+import { withFocus } from "./context.js";
+import { compareValues, keyValue, settingsOf } from "./sortKeys.js";
+
+/**
+ * Compares two composite merge keys.
+ * @param {Array} a
+ * @param {Array} b
+ * @param {object[]} settings - Settings of each key component
+ * @param {object} xc
+ * @returns {number}
+ * @throws {import("../../errors.js").XPathError} XTTE2230 for values that
+ *   cannot be compared
+ */
+export function compareKeys(a, b, settings, xc) {
+  for (let k = 0; k < settings.length; k++) {
+    let result;
+    try {
+      result = compareValues(a[k], b[k], settings[k], xc);
+    } catch (error) {
+      if (error.code !== "XTDE1030") throw error;
+      throw xsltError("XTTE2230", "Merge key values are not comparable");
+    }
+    if (result !== 0) return settings[k].descending ? -result : result;
+  }
+  return 0;
+}
+
+/**
+ * The effective values of the attributes of the merge keys of a source,
+ * which must be the same for every source (XTDE2210).
+ * @param {object[]} keys - Compiled xsl:merge-key elements
+ * @param {object} xc
+ * @returns {string[]}
+ */
+function effectiveAttributes(keys, xc) {
+  const names = ["order", "lang", "collation", "caseOrder", "dataType"];
+  return keys.map((key) =>
+    names
+      .map((name) => (key[name] ? `=${key[name](xc).trim()}` : ""))
+      .join("|"),
+  );
+}
+
+/**
+ * The entries of one merge input sequence: items with their keys, sorted
+ * or checked.
+ * @param {Array} items
+ * @param {object} source - Compiled xsl:merge-source
+ * @param {object[]} settings
+ * @param {object} xc
+ * @param {object} machine
+ * @returns {Array<{item: *, keys: Array}>}
+ */
+function inputEntries(items, source, settings, xc, machine) {
+  const entries = items.map((item) => ({
+    item,
+    keys: source.keys.map((key, k) =>
+      keyValue(key, settings[k], withFocus(xc, item, 1, 1), machine),
+    ),
+  }));
+  if (source.sortBeforeMerge) {
+    return entries.sort((a, b) => compareKeys(a.keys, b.keys, settings, xc));
+  }
+  for (let i = 1; i < entries.length; i++) {
+    if (compareKeys(entries[i - 1].keys, entries[i].keys, settings, xc) > 0) {
+      throw xsltError("XTDE2220", "A merge input sequence is not sorted");
+    }
+  }
+  return entries;
+}
+
+/**
+ * Computes the groups of an xsl:merge.
+ * @param {object[]} sources - Compiled xsl:merge-source elements
+ * @param {object} xc - Context of the instruction
+ * @param {object} machine
+ * @returns {Array<{entries: object[], keys: Array}>} groups in order
+ */
+export function mergeGroups(sources, xc, machine) {
+  const attributes = sources.map((s) => effectiveAttributes(s.keys, xc).join());
+  if (attributes.some((text) => text !== attributes[0])) {
+    throw xsltError("XTDE2210", "The merge keys of the sources differ");
+  }
+  const all = [];
+  let settings = null;
+  for (const source of sources) {
+    const sourceSettings = source.keys.map((key) => settingsOf(key, xc));
+    settings ??= sourceSettings;
+    for (const items of source.inputs(xc, machine)) {
+      for (const entry of inputEntries(
+        items,
+        source,
+        sourceSettings,
+        xc,
+        machine,
+      )) {
+        all.push({ ...entry, source: source.name });
+      }
+    }
+  }
+  if (all.length === 0) return [];
+  all.sort((a, b) => compareKeys(a.keys, b.keys, settings, xc));
+  const groups = [];
+  for (const entry of all) {
+    const last = groups.at(-1);
+    if (last && compareKeys(last.keys, entry.keys, settings, xc) === 0) {
+      last.entries.push(entry);
+    } else groups.push({ entries: [entry], keys: entry.keys });
+  }
+  return groups;
+}
+
+/**
+ * The current merge group, items of all sources or of one.
+ * @param {Array} args
+ * @param {object} context
+ * @returns {Array}
+ */
+function currentMergeGroup(args, context) {
+  const merge = context.xc.merge;
+  if (!merge) throw xsltError("XTDE3480", "There is no current merge group");
+  if (args.length === 0) return merge.group.entries.map((e) => e.item);
+  const name = args[0][0].value;
+  if (!merge.names.includes(name)) {
+    throw xsltError("XTDE3490", `No merge source is named ${name}`);
+  }
+  return merge.group.entries
+    .filter((entry) => entry.source === name)
+    .map((entry) => entry.item);
+}
+
+/** Function definitions. */
+export const mergeFunctions = [
+  {
+    local: "current-merge-group",
+    params: [],
+    returns: "item()*",
+    impl: currentMergeGroup,
+  },
+  {
+    local: "current-merge-group",
+    params: ["xs:string"],
+    returns: "item()*",
+    impl: currentMergeGroup,
+  },
+  {
+    local: "current-merge-key",
+    params: [],
+    returns: "xs:anyAtomicType*",
+    impl: (_, context) => {
+      const merge = context.xc.merge;
+      if (!merge) throw xsltError("XTDE3510", "There is no current merge key");
+      return merge.group.keys.filter((key) => key !== null);
+    },
+  },
+];