@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/xslt/runtime/functionCache.js

@@ -0,0 +1,65 @@
+/**
+ * Memoized stylesheet functions (XSLT 3.0 section 10.3.2, cache="yes" and
+ * new-each-time="no"): a call with the same arguments as an earlier one
+ * of the transformation returns the earlier result. Atomic values are
+ * compared by type and value, nodes and other items by identity.
+ *
+ * @module @tradik/xslt3/xslt/runtime/functionCache
+ */
+
+import { isAtomic } from "../../xdm/atomic.js";
+import { canonicalString } from "../../xdm/lexical.js";
+
+/**
+ * The value of an atomic item as a string: canonical, except for QNames
+ * (their namespace, not their prefix).
+ * @param {import("../../xdm/atomic.js").AtomicValue} item
+ * @returns {string}
+ */
+function valueKey(item) {
+  const { namespaceURI, localName } = item.value ?? {};
+  return localName === undefined
+    ? canonicalString(item)
+    : `{${namespaceURI}}${localName}`;
+}
+
+/**
+ * The key of a list of arguments.
+ * @param {Array<Array>} args - Converted argument values
+ * @param {object} tx - The transformation (numbers the other items)
+ * @returns {string}
+ */
+function argumentsKey(args, tx) {
+  tx.itemIds ??= { ids: new WeakMap(), next: 0 };
+  const { ids } = tx.itemIds;
+  const idOf = (item) => {
+    if (!ids.has(item)) ids.set(item, tx.itemIds.next++);
+    return ids.get(item);
+  };
+  return JSON.stringify(
+    args.map((value) =>
+      value.map((item) =>
+        isAtomic(item) ? [item.type.name, valueKey(item)] : idOf(item),
+      ),
+    ),
+  );
+}
+
+/**
+ * Calls a function through its cache.
+ * @param {object} compiled - The compiled function (its cache key)
+ * @param {Array<Array>} args - Converted argument values
+ * @param {object} tx - The transformation
+ * @param {() => Array} call - Computes the result
+ * @returns {Array}
+ */
+export function cachedCall(compiled, args, tx, call) {
+  tx.functionCaches ??= new Map();
+  let cache = tx.functionCaches.get(compiled);
+  if (!cache) tx.functionCaches.set(compiled, (cache = new Map()));
+  const key = argumentsKey(args, tx);
+  if (cache.has(key)) return cache.get(key);
+  const result = call();
+  cache.set(key, result);
+  return result;
+}

package/src/xslt/runtime/functionCall.js

@@ -0,0 +1,57 @@
+/**
+ * Calls of stylesheet functions (xsl:function) from XPath: the arguments
+ * converted to the parameter types and bound, the body run with an
+ * absent focus, the result converted to the declared type.
+ *
+ * @module @tradik/xslt3/xslt/runtime/functionCall
+ */
+
+import { cachedCall } from "./functionCache.js";
+import { SequenceReceiver } from "./sequenceReceiver.js";
+
+/**
+ * Calls a compiled stylesheet function.
+ * @param {{params: object[], body: Array, convert: Function,
+ *   memo?: boolean}} compiled
+ * @param {Array<Array>} args - Argument values
+ * @param {object} context - XPath dynamic context of the call
+ * @returns {Array} the result
+ */
+export function callFunction(compiled, args, context) {
+  const { tx } = context.xc;
+  const values = compiled.params.map((param, i) => param.convert(args[i]));
+  if (compiled.memo) {
+    return cachedCall(compiled, values, tx, () => run(compiled, values, tx));
+  }
+  return run(compiled, values, tx);
+}
+
+/**
+ * Runs the body of a stylesheet function.
+ * @param {object} compiled
+ * @param {Array<Array>} values - Converted argument values
+ * @param {object} tx - The transformation
+ * @returns {Array} the result
+ */
+function run(compiled, values, tx) {
+  let env = tx.globalEnv;
+  for (const value of values) env = { value, next: env };
+  const xc = {
+    tx,
+    item: undefined,
+    position: 0,
+    size: 0,
+    env,
+    mode: tx.defaultMode,
+    rule: null,
+    group: undefined,
+    groupKey: undefined,
+    regex: undefined,
+    tunnel: null,
+    temporary: true,
+    dyn: null,
+  };
+  const out = new SequenceReceiver(tx.scratch);
+  tx.machine.runBody(compiled.body, xc, out);
+  return compiled.convert(out.items);
+}

package/src/xslt/runtime/functions.js

@@ -0,0 +1,191 @@
+/**
+ * The functions XSLT adds to XPath (XSLT 3.0 section 20): current(),
+ * current-group(), current-grouping-key(), regex-group(), key(),
+ * document() and the unparsed entity functions, with the availability
+ * functions (availability.js) and copy-of()/snapshot() (copyFunctions.js).
+ * They read the XSLT context from the XPath dynamic context
+ * (`context.xc`, see context.js).
+ *
+ * @module @tradik/xslt3/xslt/runtime/functions
+ */
+
+import { stringItem } from "../../xpath/eval/atomics.js";
+import { rootOf } from "../../xpath/eval/domNodes.js";
+import { resolveUri } from "../../xpath/eval/uris.js";
+import { AtomicValue, isNode } from "../../xdm/atomic.js";
+import { types } from "../../xdm/types.js";
+import { stringValue } from "../../xdm/nodes.js";
+import { xsltError } from "../names.js";
+import { accumulatorFunctions } from "./accumulatorFunctions.js";
+import { availabilityFunctions, nameArgument } from "./availability.js";
+import { copyFunctions } from "./copyFunctions.js";
+import { keyLookup } from "./keys.js";
+import { mergeFunctions } from "./merging.js";
+import { streamAvailableFunctions } from "./streamAvailable.js";
+import { transformFunctions } from "./transformFunction.js";
+
+/**
+ * Whether a node is a node of the subtree rooted at another.
+ * @param {Node} node
+ * @param {Node} top
+ * @returns {boolean}
+ */
+function within(node, top) {
+  for (let a = node; a; a = a.parentNode ?? a.ownerElement) {
+    if (a === top) return true;
+  }
+  return false;
+}
+
+/**
+ * key().
+ * @param {Array} args
+ * @param {object} context
+ * @returns {Array}
+ */
+function key([[name], values, top], context) {
+  const { uri, local } = nameArgument(name.value, context, "XTDE1260");
+  let root = top?.[0];
+  if (!top) {
+    if (!isNode(context.contextItem)) {
+      throw xsltError("XTDE1270", "key() needs a context node");
+    }
+    root = rootOf(context.contextItem);
+    if (root.nodeType !== 9 && root.nodeType !== 11) {
+      throw xsltError("XTDE1270", "key() needs a node in a document");
+    }
+  }
+  const nodes = keyLookup(
+    context.xc,
+    `{${uri}}${local}`,
+    values,
+    rootOf(root),
+    context.sc?.owner,
+  );
+  return root === rootOf(root) ? nodes : nodes.filter((n) => within(n, root));
+}
+
+/**
+ * document().
+ * @param {Array} args
+ * @param {object} context
+ * @returns {Array}
+ */
+function documentFunction([items, base], context) {
+  const results = [];
+  for (const item of items) {
+    const fixedBase = base?.length
+      ? (rootOf(base[0]).documentURI ?? context.staticBaseUri)
+      : null;
+    const baseUri =
+      fixedBase ??
+      (isNode(item)
+        ? (rootOf(item).documentURI ?? context.staticBaseUri)
+        : context.staticBaseUri);
+    const uri = resolveUri(stringValue(item).replace(/#.*$/, ""), baseUri);
+    const own = context.xc.tx.stylesheet.moduleDocuments.get(uri);
+    results.push(own ?? context.loadDocument(uri));
+  }
+  return context.order.sort(results);
+}
+
+/** XSLT functions, as function library definitions. */
+export const xsltFunctions = [
+  ...availabilityFunctions,
+  ...copyFunctions,
+  {
+    local: "current",
+    params: [],
+    returns: "item()",
+    impl: (_, context) => {
+      if (context.xc.item === undefined) {
+        throw xsltError("XPDY0002", "current() has no current item");
+      }
+      return [context.xc.item];
+    },
+  },
+  {
+    local: "current-group",
+    params: [],
+    returns: "item()*",
+    impl: (_, context) => {
+      // absent in dynamic function calls (XSLT 3.0)
+      if (context.xc.group === undefined || context.dynamicCall) {
+        throw xsltError(
+          "XTDE1061",
+          "current-group(): there is no current group",
+        );
+      }
+      return context.xc.group;
+    },
+  },
+  {
+    local: "current-grouping-key",
+    params: [],
+    returns: "xs:anyAtomicType*",
+    impl: (_, context) => {
+      if (context.xc.groupKey === undefined || context.dynamicCall) {
+        throw xsltError("XTDE1071", "current-grouping-key(): there is no key");
+      }
+      return context.xc.groupKey;
+    },
+  },
+  {
+    local: "regex-group",
+    params: ["xs:integer"],
+    returns: "xs:string",
+    impl: ([[n]], context) => [
+      stringItem(context.xc.regex?.[Number(n.value)] ?? ""),
+    ],
+  },
+  {
+    local: "key",
+    params: ["xs:string", "xs:anyAtomicType*"],
+    returns: "node()*",
+    focus: true,
+    impl: key,
+  },
+  {
+    local: "key",
+    params: ["xs:string", "xs:anyAtomicType*", "node()"],
+    returns: "node()*",
+    impl: key,
+  },
+  {
+    local: "document",
+    params: ["item()*"],
+    returns: "node()*",
+    impl: documentFunction,
+  },
+  {
+    local: "document",
+    params: ["item()*", "node()"],
+    returns: "node()*",
+    impl: documentFunction,
+  },
+  {
+    local: "current-output-uri",
+    params: [],
+    returns: "xs:anyURI?",
+    impl: (_, context) => {
+      // absent in temporary output state, patterns and dynamic calls
+      const { temporary, outputUri } = context.xc;
+      return temporary || context.dynamicCall || outputUri === undefined
+        ? []
+        : [new AtomicValue(types.anyURI, outputUri)];
+    },
+  },
+  // the DOM gives no unparsed entities: their URI and public id are ""
+  ...["unparsed-entity-uri", "unparsed-entity-public-id"].flatMap((local) =>
+    [["xs:string"], ["xs:string", "node()"]].map((params) => ({
+      local,
+      params,
+      returns: "xs:string",
+      impl: () => [stringItem("")],
+    })),
+  ),
+  ...accumulatorFunctions,
+  ...mergeFunctions,
+  ...streamAvailableFunctions,
+  ...transformFunctions,
+];

package/src/xslt/runtime/groups.js

@@ -0,0 +1,108 @@
+/**
+ * The groups of xsl:for-each-group (XSLT 3.0 section 14): by grouping
+ * keys (group-by, group-adjacent, single or composite keys) and by
+ * patterns (group-starting-with, group-ending-with).
+ *
+ * @module @tradik/xslt3/xslt/runtime/groups
+ */
+
+import { atomize } from "../../xdm/nodes.js";
+import { xsltError } from "../names.js";
+import { patternMatches } from "../patterns/compile.js";
+import { comparisonKey } from "./atomicKeys.js";
+import { withFocus } from "./context.js";
+
+/**
+ * A group in the making.
+ * @typedef {object} Group
+ * @property {Array} items - Its population, in order
+ * @property {Array|undefined} key - Its grouping key
+ * @property {string} [keyString] - The key compared
+ */
+
+/**
+ * The grouping keys of an item, each with the string it is compared by:
+ * one per value, or one for the whole sequence of a composite key.
+ * @param {Array} values - Atomized key values
+ * @param {object} collation
+ * @param {boolean} composite
+ * @returns {Array<{key: Array, keyString: string}>}
+ */
+function keysOf(values, collation, composite) {
+  const strings = values.map((value) => comparisonKey(value, collation));
+  if (composite) return [{ key: values, keyString: JSON.stringify(strings) }];
+  return values.map((value, i) => ({ key: [value], keyString: strings[i] }));
+}
+
+/**
+ * Groups by keys (group-by, group-adjacent).
+ * @param {Array} items
+ * @param {(xc: object) => Array} evaluateKey - Evaluates the key expression
+ * @param {object} xc
+ * @param {{adjacent: boolean, collation: object, composite: boolean}} how
+ * @returns {Group[]}
+ * @throws {import("../../errors.js").XPathError} XTTE1100 for an
+ *   adjacent key that is not a single value
+ */
+export function groupByKeys(items, evaluateKey, xc, how) {
+  const { adjacent, collation, composite } = how;
+  const groups = [];
+  const byKey = new Map();
+  items.forEach((item, i) => {
+    const values = atomize(
+      evaluateKey(withFocus(xc, item, i + 1, items.length)),
+    );
+    if (adjacent && !composite && values.length !== 1) {
+      throw xsltError("XTTE1100", "A grouping key must be a single value");
+    }
+    const keys = keysOf(values, collation, composite);
+    if (adjacent) {
+      const [{ key, keyString }] = keys;
+      const last = groups.at(-1);
+      if (last && last.keyString === keyString) last.items.push(item);
+      else groups.push({ items: [item], key, keyString });
+      return;
+    }
+    const seen = new Set();
+    for (const { key, keyString } of keys) {
+      if (seen.has(keyString)) continue;
+      seen.add(keyString);
+      let group = byKey.get(keyString);
+      if (!group) {
+        group = { items: [], key };
+        byKey.set(keyString, group);
+        groups.push(group);
+      }
+      group.items.push(item);
+    }
+  });
+  return groups;
+}
+
+/**
+ * Groups by patterns (group-starting-with, group-ending-with); in XSLT 3.0
+ * the population may hold any items.
+ * @param {Array} items
+ * @param {object} pattern - Compiled pattern
+ * @param {object} xc
+ * @param {boolean} starting - group-starting-with
+ * @returns {Group[]}
+ */
+export function groupByPattern(items, pattern, xc, starting) {
+  const groups = [];
+  let current = null;
+  items.forEach((item, i) => {
+    const matches = patternMatches(
+      pattern,
+      item,
+      withFocus(xc, item, i + 1, items.length),
+    );
+    if (!current || (starting && matches && current.items.length > 0)) {
+      current = { items: [], key: undefined };
+      groups.push(current);
+    }
+    current.items.push(item);
+    if (!starting && matches) current = null;
+  });
+  return groups;
+}

package/src/xslt/runtime/invocation.js

@@ -0,0 +1,156 @@
+/**
+ * The invocation of a stylesheet (XSLT 3.0 section 2.3): an initial
+ * named template, an initial mode applied to the initial match selection,
+ * or an initial function; then the principal result as a document (a
+ * sequence when build-tree is "no", see rawResults.js).
+ *
+ * @module @tradik/xslt3/xslt/runtime/invocation
+ */
+
+import { toSequence } from "../../xpath/eval/values.js";
+import { isEntryPoint } from "../compiler/packageChecks.js";
+import { xsltError } from "../names.js";
+import { applyTemplates, invokeTemplate, NO_ARGS } from "./apply.js";
+import { callFunction } from "./functionCall.js";
+import { clarkName, normalizeParams } from "./params.js";
+import { resultReceiver } from "./rawResults.js";
+
+/** The default initial template of XSLT 3.0. */
+const INITIAL_TEMPLATE =
+  "{http://www.w3.org/1999/XSL/Transform}initial-template";
+
+/**
+ * A result tree as a Document when it is well-formed (one element, no
+ * text at the top), else the document fragment that holds it.
+ * @param {DocumentFragment} fragment
+ * @param {() => Document} createDocument
+ * @returns {Document|DocumentFragment}
+ */
+export function finishTree(fragment, createDocument) {
+  const children = [...fragment.childNodes];
+  const elements = children.filter((child) => child.nodeType === 1).length;
+  if (elements !== 1 || children.some((child) => child.nodeType === 3)) {
+    return fragment;
+  }
+  const document = createDocument();
+  for (const child of children) {
+    document.appendChild(document.importNode(child, true));
+  }
+  return document;
+}
+
+/**
+ * The principal result tree: the document that owns the fragment when
+ * the tree is well-formed (one element, no text at the top), else the
+ * fragment.
+ * @param {DocumentFragment} fragment
+ * @param {Document} document - Its owner, still empty
+ * @returns {Document|DocumentFragment}
+ */
+function asDocument(fragment, document) {
+  const children = [...fragment.childNodes];
+  const wellFormed =
+    children.filter((child) => child.nodeType === 1).length === 1 &&
+    !children.some((child) => child.nodeType === 3);
+  if (!wellFormed) return fragment;
+  document.appendChild(fragment);
+  return document;
+}
+
+/**
+ * The first step of a transformation: the initial template or mode.
+ * @param {object} tx - The transformation
+ * @param {object} options - See CompiledStylesheet.transform
+ * @param {Node|undefined} source
+ * @returns {Function} a step (see machine.js)
+ */
+function initialStep(tx, options, source) {
+  const { stylesheet } = tx;
+  const args = {
+    params: normalizeParams(options.templateParams),
+    tunnel: normalizeParams(options.tunnelParams),
+  };
+  let name = options.initialTemplate;
+  const fromItems =
+    options.initialMode !== undefined ||
+    source !== undefined ||
+    options.initialMatchSelection !== undefined;
+  if (name === undefined && !fromItems) name = INITIAL_TEMPLATE;
+  if (name !== undefined) {
+    const key = clarkName(name);
+    const template = stylesheet.namedTemplates.get(key);
+    if (!template || !isEntryPoint(stylesheet, "template", key)) {
+      throw xsltError("XTDE0040", `No public template named ${name}`);
+    }
+    const supplied = args.params.size || args.tunnel.size ? args : NO_ARGS;
+    return (xc, out, machine) =>
+      invokeTemplate(template, xc, out, machine, supplied);
+  }
+  const selection =
+    options.initialMatchSelection ?? (source === undefined ? [] : [source]);
+  if (source === undefined && options.initialMatchSelection === undefined) {
+    throw xsltError("XTDE0044", "No source document and no initial template");
+  }
+  return (xc, out, machine) =>
+    applyTemplates(
+      toSequence(selection),
+      tx.defaultMode,
+      xc,
+      out,
+      machine,
+      args,
+    );
+}
+
+/**
+ * Calls the initial function.
+ * @param {object} tx
+ * @param {{name: string, args: Array}} entry
+ * @returns {Array} its result
+ */
+function callInitialFunction(tx, { name, args }) {
+  const key = `${clarkName(name)}#${args.length}`;
+  const compiled = tx.stylesheet.functionBodies.get(key);
+  if (!compiled || !isEntryPoint(tx.stylesheet, "function", key)) {
+    throw xsltError("XTDE0041", `No public function ${key}`);
+  }
+  return callFunction(compiled, args.map(toSequence), { xc: tx.globalContext });
+}
+
+/**
+ * Runs the initial template, mode or function.
+ * @param {object} tx
+ * @param {object} options
+ * @param {Node|undefined} source
+ * @param {() => Document} createDocument
+ * @returns {{principal: *, principalOutput: object|null, secondary: Map,
+ *   messages: Array}} principalOutput: the parameters of an
+ *   xsl:result-document that wrote the principal result
+ */
+export function invoke(tx, options, source, createDocument) {
+  const result = { secondary: tx.secondary, messages: tx.messages };
+  if (options.initialFunction) {
+    return {
+      principal: callInitialFunction(tx, options.initialFunction),
+      ...result,
+    };
+  }
+  const step = initialStep(tx, options, source);
+  const document = createDocument();
+  const { receiver, value } = resultReceiver(
+    tx.stylesheet.outputFor(null),
+    () => document,
+    tx.options.buildTree,
+  );
+  tx.machine.runBody([step], tx.globalContext, receiver);
+  const raw = value();
+  const written = Array.isArray(raw) ? raw.length > 0 : raw.hasChildNodes();
+  if (tx.principalOverride && written) {
+    throw xsltError("XTDE1490", "The principal result is written twice");
+  }
+  let principal = tx.principalOverride ?? raw;
+  if (principal === raw && !Array.isArray(raw)) {
+    principal = asDocument(raw, document);
+  }
+  return { principal, principalOutput: tx.principalOutput, ...result };
+}

package/src/xslt/runtime/iteration.js

@@ -0,0 +1,107 @@
+/**
+ * The frame that runs xsl:iterate on the work stack (XSLT 3.0 section
+ * 7.2): one body per item, pushed after the previous one is done, so a
+ * long input sequence costs no JavaScript recursion. Each body sees the
+ * iteration state in `xc.iteration`, where xsl:next-iteration leaves the
+ * new parameter values and xsl:break marks the end.
+ *
+ * @module @tradik/xslt3/xslt/runtime/iteration
+ */
+
+import { derive } from "./context.js";
+import { BodyFrame } from "./machine.js";
+
+/** Runs the iterations of an xsl:iterate, then its xsl:on-completion. */
+export class IterateFrame {
+  /**
+   * @param {object} spec
+   * @param {Array} spec.items - The input sequence
+   * @param {object[]} spec.params - Compiled xsl:param children
+   * @param {import("./machine.js").Body} spec.steps - The body
+   * @param {import("./machine.js").Body} spec.completion - xsl:on-completion
+   * @param {object} spec.xc - Context of the instruction
+   * @param {object} spec.out - Receiver
+   */
+  constructor({ items, params, steps, completion, xc, out }) {
+    this.items = items;
+    this.params = params;
+    this.steps = steps;
+    this.completion = completion;
+    this.xc = xc;
+    this.out = out;
+    this.index = 0;
+    /** @type {Array[]|null} the parameter values, computed on the first advance */
+    this.values = null;
+    this.state = { next: null, broken: false };
+    this.done = false;
+  }
+
+  /**
+   * The initial values of the parameters, each seeing the ones before.
+   * @param {import("./machine.js").Machine} machine
+   * @returns {Array[]}
+   */
+  initialValues(machine) {
+    const values = [];
+    let ctx = this.xc;
+    for (const param of this.params) {
+      const value = param.value(ctx, machine);
+      values.push(value);
+      ctx = derive(ctx, { env: { value, next: ctx.env } });
+    }
+    return values;
+  }
+
+  /** Applies the values given by xsl:next-iteration. */
+  applyNext() {
+    const next = this.state.next;
+    if (!next) return;
+    this.state.next = null;
+    this.params.forEach((param, i) => {
+      if (next.has(param.key)) {
+        this.values[i] = param.convert(next.get(param.key));
+      }
+    });
+  }
+
+  /**
+   * The context of a body: the parameters bound, a focus or none.
+   * @param {object} focus - `{item, position, size}`
+   * @returns {object}
+   */
+  context(focus) {
+    let env = this.xc.env;
+    for (const value of this.values) env = { value, next: env };
+    return derive(this.xc, {
+      ...focus,
+      env,
+      rule: null,
+      iteration: this.state,
+    });
+  }
+
+  /**
+   * Pushes the next body, or the completion.
+   * @param {import("./machine.js").Machine} machine
+   * @returns {boolean} false when the iteration is over
+   */
+  advance(machine) {
+    if (this.done || this.state.broken) return false;
+    if (this.values === null) this.values = this.initialValues(machine);
+    else this.applyNext();
+    const size = this.items.length;
+    if (this.index < size) {
+      const item = this.items[this.index++];
+      const xc = this.context({ item, position: this.index, size });
+      if (this.steps.length > 0) {
+        machine.push(new BodyFrame(this.steps, xc, this.out));
+      }
+      return true;
+    }
+    this.done = true;
+    if (this.completion.length === 0) return false;
+    const xc = this.context({ item: undefined, position: 0, size: 0 });
+    machine.push(new BodyFrame(this.completion, xc, this.out));
+    return true;
+  }
+}