@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/xslt/runtime/transformation.js

@@ -0,0 +1,168 @@
+/**
+ * A transformation (XSLT 3.0 section 2.3): the dynamic context shared by
+ * every instruction, whitespace stripping of the source documents, the
+ * global variables evaluated on first use, and the results collected.
+ *
+ * @module @tradik/xslt3/xslt/runtime/transformation
+ */
+
+import { withinLimits } from "../../xpath/eval/compiler.js";
+import { isEligibleMode } from "../compiler/packageChecks.js";
+import { displayName, xsltError } from "../names.js";
+import {
+  checkLibraryContextItems,
+  globalContextItem,
+} from "../compiler/globalContextItem.js";
+import { setInitialAccumulators } from "./accumulators.js";
+import { withDefaultMethod } from "./defaultMethod.js";
+import { finishTree, invoke } from "./invocation.js";
+import { LazyEntry } from "./lazy.js";
+import { Machine } from "./machine.js";
+import { normalizeParams } from "./params.js";
+import { isStrippedText } from "./strip.js";
+import {
+  documentStripper,
+  transformationContext,
+} from "./transformationContext.js";
+
+/**
+ * The lazily evaluated entries of the global variables.
+ * @param {object} tx
+ * @param {Map<string, Array>} params - Supplied stylesheet parameters
+ * @returns {object|null} the environment (see xpath/eval/scope.js)
+ */
+function globalEnvironment(tx, params) {
+  let env = null;
+  for (const global of tx.stylesheet.globals) {
+    if (global.required && !params.has(global.key)) {
+      throw xsltError(
+        "XTDE0050",
+        `The parameter $${displayName(global.key)} is required`,
+      );
+    }
+    const compute =
+      global.isParam && params.has(global.key)
+        ? () => global.convert(params.get(global.key))
+        : () => global.value(tx.globalContext, tx.machine);
+    env = new LazyEntry(env, compute, global.key, true);
+  }
+  return env;
+}
+
+/**
+ * The document factory of a transformation: the option, else the DOM of
+ * the source, else the DOM of the stylesheet (a transformation without a
+ * source, from an initial template), else the global document.
+ * @param {object} options
+ * @param {object} stylesheet - Compiled stylesheet (its module tree)
+ * @returns {() => Document}
+ */
+function documentFactory(options, stylesheet) {
+  if (options.createDocument) return options.createDocument;
+  return () => {
+    const owner =
+      options.source?.ownerDocument ??
+      options.source ??
+      stylesheet.tree.root.ownerDocument;
+    const implementation =
+      owner?.implementation ?? globalThis.document?.implementation;
+    if (!implementation) {
+      throw xsltError(
+        "XPDY0130",
+        "No DOM to build results: pass createDocument",
+      );
+    }
+    return implementation.createDocument(null, null, null);
+  };
+}
+
+/**
+ * The initial mode: `#unnamed`, `#default` or a Clark name of a mode
+ * eligible as initial mode (XTDE0045).
+ * @param {object} stylesheet
+ * @param {string|undefined} requested - Option initialMode
+ * @returns {object} the mode
+ */
+function initialMode(stylesheet, requested) {
+  const token = requested?.replace(/^\{\}(?=#)/, "");
+  if (token === undefined || token === "#default") {
+    return stylesheet.mode(stylesheet.defaultModeName);
+  }
+  const name = token === "#unnamed" ? "" : token;
+  if (!isEligibleMode(stylesheet, name)) {
+    throw xsltError("XTDE0045", `The mode ${requested} is not eligible`);
+  }
+  return stylesheet.mode(name);
+}
+
+/**
+ * Runs a transformation.
+ * @param {object} stylesheet - Compiled stylesheet (StylesheetCompiler)
+ * @param {object} options - See CompiledStylesheet.transform
+ * @returns {{principal: Node|Array, secondary: Map<string, object>,
+ *   messages: Array}}
+ */
+export function runTransformation(stylesheet, options) {
+  checkLibraryContextItems(stylesheet);
+  const createDocument = documentFactory(options, stylesheet);
+  let scratchDocument = null;
+  const strip = documentStripper();
+  // a source text node that stripping removes is no source (XPDY0002)
+  const source = isStrippedText(options.source ?? {}, stylesheet.spaceRules)
+    ? undefined
+    : strip(options.source, stylesheet.spaceRules);
+  const tx = {
+    stylesheet,
+    options,
+    machine: new Machine(options.maxDepth),
+    scratch: () => (scratchDocument ??= createDocument()),
+    messages: [],
+    onMessage: options.onMessage,
+    resultUris: new Set(),
+    baseOutputUri: options.baseOutputUri,
+    secondary: new Map(),
+    keyIndexes: new Map(),
+    defaultMode: initialMode(stylesheet, options.initialMode),
+    principalOverride: null,
+    dynamicEvaluation: options.dynamicEvaluation !== false,
+    assertions: options.assertions !== false,
+    principalOutput: null,
+    dyn: transformationContext(stylesheet, options, strip, createDocument),
+  };
+  tx.addResult = (uri, fragment, output) => {
+    const tree = Array.isArray(fragment)
+      ? fragment
+      : finishTree(fragment, createDocument);
+    const params = withDefaultMethod(output, tree);
+    if (uri === "") {
+      tx.principalOverride = tree;
+      tx.principalOutput = params;
+    } else tx.secondary.set(uri, { document: tree, output: params });
+  };
+  tx.globalContext = {
+    tx,
+    item: globalContextItem(
+      stylesheet.globalContextItem,
+      options.globalContextItem ?? source,
+    ),
+    position: 1,
+    size: 1,
+    env: null,
+    mode: tx.defaultMode,
+    rule: null,
+    group: undefined,
+    groupKey: undefined,
+    regex: undefined,
+    tunnel: null,
+    temporary: false,
+    outputUri: options.baseOutputUri,
+    dyn: null,
+  };
+  setInitialAccumulators(tx, options, source);
+  tx.globalEnv = globalEnvironment(
+    tx,
+    normalizeParams(options.params, options.paramsAsUntyped),
+  );
+  tx.globalContext.env = tx.globalEnv;
+  return withinLimits(() => invoke(tx, options, source, createDocument));
+}

package/src/xslt/runtime/transformationContext.js

@@ -0,0 +1,85 @@
+/**
+ * The XPath dynamic context of a transformation: the resources it reads
+ * (documents, text, collections) with relative URIs resolved against the
+ * base URI of the calling expression, and the documents it loads stripped
+ * of whitespace by the xsl:strip-space rules of the package of that
+ * expression (XSLT 3.0 section 4.3).
+ *
+ * @module @tradik/xslt3/xslt/runtime/transformationContext
+ */
+
+import { createDynamicContext } from "../../xpath/eval/dynamicContext.js";
+import { resolveUri } from "../../xpath/eval/uris.js";
+import { stripDocument } from "./strip.js";
+
+/**
+ * Whitespace stripping of loaded documents, once per document and rule
+ * set, so that a document read twice by one package is one node.
+ * @returns {(document: Node, rules: object[]) => Node}
+ */
+export function documentStripper() {
+  const copies = new WeakMap();
+  return (document, rules) => {
+    if (document?.nodeType !== 9) return document;
+    let byRules = copies.get(document);
+    if (!byRules) copies.set(document, (byRules = new Map()));
+    let stripped = byRules.get(rules);
+    if (!stripped) {
+      stripped = stripDocument(document, rules);
+      byRules.set(rules, stripped);
+    }
+    return stripped;
+  };
+}
+
+/**
+ * Builds the dynamic context of a transformation.
+ * @param {object} stylesheet - The top-level package's compiler
+ * @param {object} options - See CompiledStylesheet.transform
+ * @param {(document: Node, rules: object[]) => Node} strip - From
+ *   {@link documentStripper}
+ * @param {() => Document} createDocument
+ * @returns {object}
+ */
+export function transformationContext(
+  stylesheet,
+  options,
+  strip,
+  createDocument,
+) {
+  const dyn = createDynamicContext(
+    stylesheet.sc,
+    {
+      documentLoader: options.documentLoader,
+      createDocument,
+      implicitTimezone: options.implicitTimezone,
+      currentDateTime: options.currentDateTime,
+      textLoader: options.textLoader,
+      xmlParser: options.xmlParser,
+      collections: options.collections,
+    },
+    options.source,
+  );
+  const { loadDocument, loadText, collection } = dyn;
+  /** @this {object} the dynamic context of the calling expression */
+  function rulesOf() {
+    return (this.sc?.owner ?? stylesheet).spaceRules ?? stylesheet.spaceRules;
+  }
+  // `this` is the dynamic context of the calling expression
+  dyn.loadDocument = function load(uri) {
+    const base = this.staticBaseUri;
+    const document = loadDocument(resolveUri(uri, base), base);
+    return strip(document, rulesOf.call(this));
+  };
+  dyn.loadText = function loadTextFrom(href, encoding) {
+    return loadText(href, encoding, this.staticBaseUri);
+  };
+  dyn.collection = function collectionFrom(href) {
+    const rules = rulesOf.call(this);
+    return collection(href, this.staticBaseUri).map((item) =>
+      strip(item, rules),
+    );
+  };
+  dyn.xc = null;
+  return dyn;
+}

package/src/xslt/runtime/treeReceiver.js

@@ -0,0 +1,194 @@
+/**
+ * The receiver that builds the content of a node in a result tree
+ * (XSLT 3.0 section 5.7.1, constructing complex content): adjacent
+ * atomic values become text separated by spaces, document nodes are
+ * replaced by their children, adjacent text is merged, attributes and
+ * namespaces must come before children, and namespace declarations are
+ * added where names need them.
+ *
+ * @module @tradik/xslt3/xslt/runtime/treeReceiver
+ */
+
+import { isArray, isAtomic, isFunctionItem } from "../../xdm/atomic.js";
+import { canonicalString } from "../../xdm/lexical.js";
+import { xsltError } from "../names.js";
+import { copyNode } from "./copy.js";
+import { DocumentContent } from "./documentContent.js";
+import { NamespaceScope, prefixOf } from "./namespaceScope.js";
+
+export { prefixOf };
+
+/** Builds the children (and attributes) of an element or document. */
+export class TreeReceiver extends NamespaceScope {
+  /**
+   * @param {Node} parent - Element, document or document fragment
+   * @param {Map<string, string>} namespaces - In scope at the parent
+   */
+  constructor(parent, namespaces) {
+    super(parent, namespaces);
+    this.doc = parent.nodeType === 9 ? parent : parent.ownerDocument;
+    this.hasChildren = false;
+    this.lastAtomic = false;
+    /** @type {boolean} the receiver of the top of a result tree */
+    this.resultTree = false;
+  }
+
+  /**
+   * Appends a child node.
+   * @param {Node} node
+   */
+  append(node) {
+    this.parent.appendChild(node);
+    this.hasChildren = true;
+    this.lastAtomic = false;
+  }
+
+  /**
+   * Starts an element child.
+   * @param {string} uri - Namespace URI, "" for none
+   * @param {string} qname - Lexical name
+   * @returns {TreeReceiver} the receiver of its content (`.parent` is it)
+   */
+  element(uri, qname) {
+    const element = this.doc.createElementNS(uri || null, qname);
+    this.append(element);
+    const content = new TreeReceiver(element, this.namespaces);
+    content.declare(prefixOf(qname), uri);
+    return content;
+  }
+
+  /**
+   * Checks that an attribute or namespace may be added now.
+   * @param {string} what
+   */
+  checkAttributePosition(what) {
+    if (this.parent.nodeType !== 1) {
+      throw xsltError("XTDE0420", `A ${what} cannot be added to a document`);
+    }
+    if (this.hasChildren) {
+      throw xsltError(
+        "XTDE0410",
+        `A ${what} cannot be added after the children of an element`,
+      );
+    }
+  }
+
+  /**
+   * Adds an attribute (replacing one of the same name); its prefix is
+   * changed when the element binds it to another namespace.
+   * @param {string} uri
+   * @param {string} qname
+   * @param {string} value
+   */
+  attribute(uri, qname, value) {
+    this.checkAttributePosition("attribute");
+    let name = qname;
+    if (uri) {
+      let prefix = prefixOf(qname);
+      const local = qname.slice(prefix.length ? prefix.length + 1 : 0);
+      if (prefix === "" || !this.declare(prefix, uri)) {
+        prefix = this.prefixFor(uri, prefix);
+      }
+      name = `${prefix}:${local}`;
+      const existing = this.parent.getAttributeNodeNS(uri, local);
+      if (existing) this.parent.removeAttributeNode(existing);
+    }
+    this.parent.setAttributeNS(uri || null, name, value);
+    this.lastAtomic = false;
+  }
+
+  /**
+   * Adds a namespace node.
+   * @param {string} prefix
+   * @param {string} uri
+   */
+  namespace(prefix, uri) {
+    this.checkAttributePosition("namespace node");
+    if (prefix === "" && this.parent.namespaceURI === null && uri !== "") {
+      throw xsltError(
+        "XTDE0440",
+        "A default namespace cannot be added to an element in no namespace",
+      );
+    }
+    if (
+      !this.declareExplicit(prefix, uri) &&
+      !(this.rebind(prefix, uri) && this.explicit.add(prefix))
+    ) {
+      throw xsltError(
+        "XTDE0430",
+        `The prefix "${prefix}" is already bound to another namespace`,
+      );
+    }
+    this.lastAtomic = false;
+  }
+
+  /**
+   * Adds text (merged with preceding text); zero-length text adds no node
+   * but separates atomic values.
+   * @param {string} text
+   */
+  text(text) {
+    if (text === "") {
+      this.lastAtomic = false;
+      return;
+    }
+    const last = this.parent.lastChild;
+    if (last && last.nodeType === 3) last.appendData(text);
+    else this.append(this.doc.createTextNode(text));
+    this.hasChildren = true;
+    this.lastAtomic = false;
+  }
+
+  /** @param {string} text */
+  comment(text) {
+    this.append(this.doc.createComment(text));
+  }
+
+  /**
+   * @param {string} target
+   * @param {string} data
+   */
+  pi(target, data) {
+    this.append(this.doc.createProcessingInstruction(target, data));
+  }
+
+  /** @param {import("../../xdm/atomic.js").AtomicValue} value */
+  atomic(value) {
+    const text = canonicalString(value);
+    this.text(this.lastAtomic ? ` ${text}` : text);
+    this.lastAtomic = true;
+  }
+
+  /**
+   * Adds an item of a sequence: nodes are copied, arrays flattened.
+   * @param {*} item
+   */
+  item(item) {
+    if (isAtomic(item)) this.atomic(item);
+    else if (isArray(item)) {
+      for (const member of item.members) for (const x of member) this.item(x);
+    } else if (isFunctionItem(item)) {
+      // the top of a result tree is built by sequence normalization
+      // (XSLT 3.0 section 2.3.6), whose error is SENR0001
+      throw xsltError(
+        this.resultTree ? "SENR0001" : "XTDE0450",
+        "A function item cannot be added to a tree",
+      );
+    } else this.copy(item, true);
+  }
+
+  /**
+   * Copies a node and its descendants.
+   * @param {Node} node
+   * @param {boolean} copyNamespaces
+   */
+  copy(node, copyNamespaces) {
+    copyNode(node, this, copyNamespaces);
+  }
+
+  /** @returns {DocumentContent} the receiver of a document node's content */
+  document() {
+    this.lastAtomic = false;
+    return new DocumentContent(this);
+  }
+}

package/src/xslt/runtime/values.js

@@ -0,0 +1,92 @@
+/**
+ * Values computed from sequence constructors at run time: the sequence a
+ * body produces, temporary trees, simple content (XSLT 3.0 section
+ * 5.7.2) and attribute value templates.
+ *
+ * @module @tradik/xslt3/xslt/runtime/values
+ */
+
+import { atomize } from "../../xdm/nodes.js";
+import { canonicalString } from "../../xdm/lexical.js";
+import { derive, evaluate } from "./context.js";
+import { SequenceReceiver } from "./sequenceReceiver.js";
+import { TreeReceiver } from "./treeReceiver.js";
+
+/**
+ * Runs a body and returns the sequence it produces.
+ * @param {import("./machine.js").Body} body
+ * @param {object} xc
+ * @param {import("./machine.js").Machine} machine
+ * @param {boolean} [temporary] - The body runs in temporary output state
+ *   (XSLT 3.0 section 25.2: variables, functions, keys, sort keys...),
+ *   not for the content of xsl:attribute, xsl:value-of, xsl:comment,
+ *   xsl:message and the like
+ * @returns {Array}
+ */
+export function bodySequence(body, xc, machine, temporary = true) {
+  const out = new SequenceReceiver(xc.tx.scratch);
+  const context = temporary ? derive(xc, { temporary: true }) : xc;
+  machine.runBody(body, context, out);
+  return out.items;
+}
+
+/**
+ * Runs a body to build a temporary tree.
+ * @param {import("./machine.js").Body} body
+ * @param {object} xc
+ * @param {import("./machine.js").Machine} machine
+ * @returns {Node} its document node (a document fragment)
+ */
+export function temporaryTree(body, xc, machine) {
+  const fragment = xc.tx.scratch().createDocumentFragment();
+  const out = new TreeReceiver(fragment, new Map());
+  machine.runBody(body, derive(xc, { temporary: true }), out);
+  return fragment;
+}
+
+/**
+ * The string of simple content: zero-length text nodes dropped, adjacent
+ * text nodes merged, then the items atomized and joined.
+ * @param {Array} items
+ * @param {string} separator
+ * @returns {string}
+ */
+export function simpleContent(items, separator) {
+  const parts = [];
+  let text = null;
+  for (const item of items) {
+    if (item?.nodeType === 3) {
+      if (item.nodeValue !== "") text = (text ?? "") + item.nodeValue;
+      continue;
+    }
+    if (text !== null) parts.push(text);
+    text = null;
+    for (const value of atomize([item])) parts.push(canonicalString(value));
+  }
+  if (text !== null) parts.push(text);
+  return parts.join(separator);
+}
+
+/**
+ * Evaluator of a compiled attribute value template.
+ * @param {Array<string|object>} parts - See ExpressionCompiler.avt
+ * @param {boolean} [compatible] - Backwards-compatible: first item only
+ * @returns {(xc: object) => string}
+ */
+export function avtEvaluator(parts, compatible = false) {
+  if (parts.length === 1 && typeof parts[0] === "string") {
+    const constant = parts[0];
+    return () => constant;
+  }
+  return (xc) => {
+    let result = "";
+    for (const part of parts) {
+      if (typeof part === "string") result += part;
+      else {
+        const value = evaluate(part, xc);
+        result += simpleContent(compatible ? value.slice(0, 1) : value, " ");
+      }
+    }
+    return result;
+  };
+}