@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/xslt/compiler/body.js

@@ -0,0 +1,154 @@
+/**
+ * Compilation of sequence constructors (XSLT 3.0 section 5.7): each child
+ * of a template body, a literal result element or an instruction becomes
+ * a step of the body (see runtime/machine.js). Local variables extend the
+ * scope of their following siblings.
+ *
+ * @module @tradik/xslt3/xslt/compiler/body
+ */
+
+import { avtEvaluator } from "../runtime/values.js";
+import { isXsl, XSL_NS, xsltError } from "../names.js";
+import { infoOf } from "./elementInfo.js";
+import { instructionCompilers } from "../instructions/index.js";
+import { compileLiteralElement } from "../instructions/literal.js";
+import { compileLocalVariable } from "../instructions/variables.js";
+import { checkAttributes } from "./attributes.js";
+import { conditionalBody } from "../runtime/conditional.js";
+import { locate, recordStep } from "../runtime/locations.js";
+
+/**
+ * The scope of a compilation: the variables in scope (a linked list of
+ * Clark names, see xpath/eval/scope.js) and flags of the context.
+ * @typedef {object} Scope
+ * @property {{key: string, next: object}|null} vars
+ * @property {boolean} [inFunction] - In a stylesheet function
+ */
+
+/**
+ * Compiles a text child: literal text, or a text value template under
+ * expand-text="yes".
+ * @param {{nodeValue: string, parentNode: Element}} text
+ * @param {object} cx - Stylesheet compiler
+ * @param {Scope} scope
+ * @returns {Function} the step
+ */
+function compileText(text, cx, scope) {
+  const parent = text.parentNode;
+  const value = text.nodeValue;
+  if (infoOf(parent).expandText) {
+    const evaluator = avtEvaluator(cx.exprs.avt(value, parent, scope.vars));
+    return (xc, out) => out.text(evaluator(xc));
+  }
+  return (xc, out) => out.text(value);
+}
+
+/**
+ * Steps of an element whose instruction is not available: its
+ * xsl:fallback children, or a dynamic error when it has none.
+ * @param {Element} element
+ * @param {object} cx
+ * @param {Scope} scope
+ * @returns {Function|null}
+ */
+export function compileFallback(element, cx, scope) {
+  const fallbacks = cx
+    .children(element)
+    .filter((child) => child.nodeType === 1 && isXsl(child, "fallback"));
+  if (fallbacks.length === 0) {
+    const name = element.nodeName;
+    if (element.namespaceURI === XSL_NS) {
+      throw xsltError("XTSE0010", `Unknown XSLT element ${name}`);
+    }
+    return () => {
+      throw xsltError("XTDE1450", `The instruction ${name} is not available`);
+    };
+  }
+  const bodies = fallbacks.map((fallback) => compileBody(fallback, cx, scope));
+  return (xc, out, machine) => {
+    for (const body of bodies) machine.runBody(body, xc, out);
+  };
+}
+
+/**
+ * Compiles an XSLT instruction.
+ * @param {Element} element
+ * @param {object} cx
+ * @param {Scope} scope
+ * @returns {Function|null} the step, null for none
+ */
+function compileInstruction(element, cx, scope) {
+  const name = element.localName;
+  const compiler = instructionCompilers[name];
+  if (compiler) {
+    checkAttributes(element, cx);
+    return compiler(element, cx, scope);
+  }
+  if (name === "fallback") {
+    checkAttributes(element, cx);
+    return null;
+  }
+  if (infoOf(element).version > 3) return compileFallback(element, cx, scope);
+  if (name === "include" || name === "import") {
+    throw xsltError(
+      name === "include" ? "XTSE0170" : "XTSE0190",
+      `xsl:${name} is only allowed at the top level`,
+    );
+  }
+  throw xsltError(
+    "XTSE0010",
+    `xsl:${name} is not allowed in a sequence constructor`,
+  );
+}
+
+/**
+ * Compiles a child of a sequence constructor other than xsl:variable.
+ * @param {Node} child - Text or element
+ * @param {object} cx
+ * @param {Scope} scope
+ * @returns {Function|null} the step, null for none
+ */
+function compileChild(child, cx, scope) {
+  if (child.nodeType === 3) return compileText(child, cx, scope);
+  if (child.namespaceURI === XSL_NS) {
+    return compileInstruction(child, cx, scope);
+  }
+  if (infoOf(child).extension.has(child.namespaceURI)) {
+    return compileFallback(child, cx, scope);
+  }
+  return compileLiteralElement(child, cx, scope);
+}
+
+/**
+ * Compiles the children of a stylesheet element as a sequence
+ * constructor.
+ * @param {Element} parent
+ * @param {object} cx - Stylesheet compiler
+ * @param {Scope} scope
+ * @param {Node[]} [children] - The children to compile (default: all)
+ * @returns {import("../runtime/machine.js").Body}
+ */
+export function compileBody(parent, cx, scope, children) {
+  const body = [];
+  let current = scope;
+  for (const child of children ?? cx.children(parent)) {
+    try {
+      if (child.nodeType === 1 && isXsl(child, "variable")) {
+        checkAttributes(child, cx);
+        const compiled = compileLocalVariable(child, cx, current);
+        recordStep(compiled.step, child);
+        body.push(compiled.step);
+        current = compiled.scope;
+        continue;
+      }
+      const step = compileChild(child, cx, current);
+      recordStep(step, child);
+      if (step) body.push(step);
+    } catch (error) {
+      throw locate(error, child);
+    }
+  }
+  // xsl:on-empty and xsl:on-non-empty make the whole body conditional
+  const conditional = body.some((step) => step.conditional !== undefined);
+  return conditional ? [conditionalBody(body)] : body;
+}

package/src/xslt/compiler/children.js

@@ -0,0 +1,105 @@
+/**
+ * The children of a stylesheet element as the compiler sees them:
+ * comments and processing instructions dropped, adjacent text merged,
+ * whitespace-only text stripped (except in xsl:text and under
+ * xml:space="preserve"), and elements excluded by use-when left out
+ * (XSLT 3.0 sections 3.13.1 and 4.2).
+ *
+ * @module @tradik/xslt3/xslt/compiler/children
+ */
+
+import { isXsl, XML_NS, XSL_NS } from "../names.js";
+
+const WHITESPACE = /^[ \t\r\n]*$/;
+
+/** XSLT elements whose content has no text: whitespace there is ignored. */
+const ELEMENT_ONLY = new Set([
+  "stylesheet",
+  "transform",
+  "package",
+  "use-package",
+  "override",
+  "apply-templates",
+  "apply-imports",
+  "next-match",
+  "call-template",
+  "choose",
+  "attribute-set",
+  "character-map",
+  "analyze-string",
+]);
+
+/**
+ * @param {object} node
+ * @returns {boolean} whether a child is whitespace-only text
+ */
+export const isWhitespaceText = (node) =>
+  node.nodeType === 3 && WHITESPACE.test(node.nodeValue);
+
+/**
+ * Splits leading children of one XSLT kind (xsl:param, xsl:sort) from the
+ * rest, ignoring whitespace text between them.
+ * @param {Array<object>} children
+ * @param {string} local - Local name of the leading elements
+ * @returns {{leading: Element[], rest: Array<object>}}
+ */
+export function splitLeading(children, local) {
+  const leading = [];
+  let end = 0;
+  for (let i = 0; i < children.length; i++) {
+    if (isXsl(children[i], local)) {
+      leading.push(children[i]);
+      end = i + 1;
+    } else if (!isWhitespaceText(children[i])) break;
+  }
+  return { leading, rest: children.slice(end) };
+}
+
+/**
+ * @param {Element} element
+ * @returns {boolean} whether xml:space="preserve" applies to the children
+ */
+function preservesSpace(element) {
+  for (let e = element; e && e.nodeType === 1; e = e.parentNode) {
+    const space = e.getAttributeNS(XML_NS, "space");
+    if (space) return space === "preserve";
+  }
+  return false;
+}
+
+/**
+ * A text child of a stylesheet element: `{nodeType: 3, nodeValue}`.
+ * @typedef {{nodeType: 3, nodeValue: string, parentNode: Element}} TextChild
+ */
+
+/**
+ * The significant children of a stylesheet element.
+ * @param {Element} element
+ * @param {(element: Element) => boolean} included - Whether an element
+ *   passes its use-when condition
+ * @returns {Array<Element|TextChild>} elements and texts
+ */
+export function significantChildren(element, included) {
+  const elementOnly =
+    element.namespaceURI === XSL_NS && ELEMENT_ONLY.has(element.localName);
+  const keepSpace =
+    isXsl(element, "text") || (!elementOnly && preservesSpace(element));
+  const result = [];
+  let text = null;
+  const flush = () => {
+    if (text !== null && (keepSpace || !WHITESPACE.test(text))) {
+      result.push({ nodeType: 3, nodeValue: text, parentNode: element });
+    }
+    text = null;
+  };
+  for (let child = element.firstChild; child; child = child.nextSibling) {
+    const type = child.nodeType;
+    if (type === 3 || type === 4) text = (text ?? "") + child.nodeValue;
+    else if (type === 1) {
+      flush();
+      if (included(child)) result.push(child);
+    }
+  }
+  flush();
+  return result;
+}

package/src/xslt/compiler/compatibility.js

@@ -0,0 +1,130 @@
+/**
+ * Compatible signatures of an overriding and an overridden component
+ * (XSLT 3.0 section 3.5.3.3, XTSE3070): identical declared types of
+ * functions, variables and templates, and the template parameters an
+ * overriding template must keep.
+ *
+ * @module @tradik/xslt3/xslt/compiler/compatibility
+ */
+
+import { attr, clarkOf, isXsl, xsltError } from "../names.js";
+import { yesNo } from "./attributes.js";
+import { infoOf } from "./elementInfo.js";
+
+const QNAME = /([\p{L}_][\p{L}\p{N}_.-]*):([\p{L}_][\p{L}\p{N}_.-]*)/gu;
+
+/**
+ * A declared type in a form that compares equal for identical types
+ * written with different prefixes or spacing.
+ * @param {Element} element - Declaration with the `as` attribute
+ * @returns {string}
+ */
+function typeOf(element) {
+  const namespaces = infoOf(element).namespaces;
+  return (attr(element, "as") ?? "item()*")
+    .replace(/\s+/g, "")
+    .replace(QNAME, (name, prefix, local) =>
+      namespaces.has(prefix) ? `Q{${namespaces.get(prefix)}}${local}` : name,
+    );
+}
+
+/**
+ * The xsl:param children of a template or function.
+ * @param {Element} element
+ * @param {object} cx
+ * @returns {Array<{key: string, type: string, required: boolean, tunnel:
+ *   boolean}>}
+ */
+function paramsOf(element, cx) {
+  return cx
+    .children(element)
+    .filter((child) => isXsl(child, "param"))
+    .map((param) => ({
+      key: clarkOf(cx.exprs.qname(attr(param, "name"), param)),
+      type: typeOf(param),
+      required: yesNo(param, "required", false),
+      tunnel: yesNo(param, "tunnel", false),
+    }));
+}
+
+/**
+ * The xsl:context-item declaration of a template, as `use|type`.
+ * @param {Element} element
+ * @param {object} cx
+ * @returns {string}
+ */
+function contextItemOf(element, cx) {
+  const item = cx.children(element).find((c) => isXsl(c, "context-item"));
+  if (!item) return "optional|item()";
+  const type = attr(item, "as") === undefined ? "item()" : typeOf(item);
+  return `${attr(item, "use")?.trim() ?? "optional"}|${type}`;
+}
+
+/**
+ * Whether an overriding template keeps the interface of the overridden
+ * one.
+ * @param {Element} overriding
+ * @param {Element} overridden
+ * @param {object} cx
+ * @returns {boolean}
+ */
+function templatesCompatible(overriding, overridden, cx) {
+  const mine = new Map(paramsOf(overriding, cx).map((p) => [p.key, p]));
+  const theirs = paramsOf(overridden, cx);
+  for (const param of theirs) {
+    const other = mine.get(param.key);
+    if (param.tunnel) {
+      if (other && (!other.tunnel || other.type !== param.type)) return false;
+    } else if (
+      !other ||
+      other.tunnel ||
+      other.type !== param.type ||
+      other.required !== param.required
+    ) {
+      return false;
+    }
+  }
+  const known = new Set(theirs.map((p) => p.key));
+  return (
+    contextItemOf(overriding, cx) === contextItemOf(overridden, cx) &&
+    [...mine.values()].every((p) => known.has(p.key) || !p.required)
+  );
+}
+
+/**
+ * @param {Element} element - xsl:function
+ * @returns {string} its new-each-time value
+ */
+const newEachTime = (element) =>
+  ({ true: "yes", 1: "yes", false: "no", 0: "no" })[
+    attr(element, "new-each-time")?.trim()
+  ] ??
+  attr(element, "new-each-time")?.trim() ??
+  "maybe";
+
+/**
+ * XTSE3070: checks that an overriding declaration is compatible with the
+ * component it overrides.
+ * @param {Element} overriding
+ * @param {object} component - The overridden component (`kind`, `element`)
+ * @param {object} cx - The using package's compiler
+ */
+export function checkCompatible(overriding, component, cx) {
+  const overridden = component.element;
+  let compatible = typeOf(overriding) === typeOf(overridden);
+  if (component.kind === "function") {
+    const mine = paramsOf(overriding, cx).map((p) => p.type);
+    const theirs = paramsOf(overridden, cx).map((p) => p.type);
+    compatible &&=
+      mine.every((type, i) => type === theirs[i]) &&
+      newEachTime(overriding) === newEachTime(overridden);
+  } else if (component.kind === "template") {
+    compatible &&= templatesCompatible(overriding, overridden, cx);
+  }
+  if (!compatible) {
+    throw xsltError(
+      "XTSE3070",
+      `The override of ${component.local} is incompatible`,
+    );
+  }
+}

package/src/xslt/compiler/components.js

@@ -0,0 +1,179 @@
+/**
+ * The named components a package declares (XSLT 3.0 section 3.5.3):
+ * named templates, functions, global variables and parameters,
+ * attribute sets and named modes, with their visibility from the
+ * visibility attribute and the xsl:expose declarations.
+ *
+ * @module @tradik/xslt3/xslt/compiler/components
+ */
+
+import { attr, clarkOf, isXsl, xsltError } from "../names.js";
+import { required } from "./attributes.js";
+import { checkUnmatched, EXPLICIT, matchesOf } from "./visibility.js";
+
+const DECLARED = new Set(["public", "private", "final", "abstract"]);
+const MODE_DECLARED = new Set(["public", "private", "final"]);
+
+/** Declared visibilities each explicitly exposed visibility allows. */
+const EXPOSABLE = {
+  public: ["public"],
+  private: ["public", "private", "final"],
+  final: ["public", "final"],
+  abstract: ["abstract"],
+};
+
+/**
+ * The visibility attribute of a declaration.
+ * @param {Element} element
+ * @param {string} kind - Component kind
+ * @returns {string|null} null when absent
+ */
+export function declaredVisibility(element, kind) {
+  const text = attr(element, "visibility");
+  if (text === undefined) return null;
+  const value = text.trim();
+  if (!(kind === "mode" ? MODE_DECLARED : DECLARED).has(value)) {
+    throw xsltError("XTSE0020", `Invalid visibility ${text}`);
+  }
+  return value;
+}
+
+/**
+ * The visibility of a component declared in a package.
+ * @param {object} component - `{kind, uri, local, arity, declared, isParam}`
+ * @param {object[]} rules - Parsed xsl:expose rules
+ * @returns {string}
+ */
+function exposedVisibility(component, rules) {
+  if (component.isParam) return "public";
+  const [best] = matchesOf(rules, component);
+  const { declared } = component;
+  let visibility = declared ?? best?.rule.visibility ?? "private";
+  if (best?.precision === EXPLICIT) {
+    visibility = best.rule.visibility;
+    if (declared && !EXPOSABLE[visibility].includes(declared)) {
+      throw xsltError(
+        "XTSE3010",
+        `xsl:expose makes the ${declared} ${component.kind} ${component.local} ${visibility}`,
+      );
+    }
+  }
+  if (visibility === "abstract" && declared !== "abstract") {
+    throw xsltError(
+      "XTSE3025",
+      `xsl:expose cannot make ${component.local} abstract`,
+    );
+  }
+  return visibility;
+}
+
+/**
+ * A component descriptor.
+ * @param {string} kind
+ * @param {{uri: string, local: string}} name
+ * @param {Element} element - Declaration
+ * @param {object} [extra] - `arity`, `isParam`
+ * @returns {object}
+ */
+function component(kind, name, element, extra = {}) {
+  const key = clarkOf(name);
+  return {
+    kind,
+    uri: name.uri,
+    local: name.local,
+    arity: extra.arity ?? null,
+    isParam: extra.isParam ?? false,
+    key: extra.arity === undefined ? key : `${key}#${extra.arity}`,
+    element,
+    declared: extra.isParam ? null : declaredVisibility(element, kind),
+  };
+}
+
+/**
+ * The named components declared in a package (the declarations of
+ * highest import precedence).
+ * @param {(kind: string) => object[]} all - Declarations by kind
+ * @param {object} cx - Stylesheet compiler (after compileContext)
+ * @param {{signatures: Map, globals: Map}} context - From compileContext
+ * @returns {object[]} components `{kind, uri, local, arity, key, element,
+ *   declared, isParam}`
+ */
+export function declaredComponents(all, cx, { signatures, globals }) {
+  const qname = (element) => cx.exprs.qname(attr(element, "name"), element);
+  // the named templates of highest precedence (XTSE0660 is raised when
+  // they are compiled)
+  const named = (declarations) => {
+    const chosen = new Map();
+    for (const declaration of declarations) {
+      if (attr(declaration.element, "name") === undefined) continue;
+      const key = clarkOf(qname(declaration.element));
+      if (!(chosen.get(key)?.precedence > declaration.precedence)) {
+        chosen.set(key, declaration);
+      }
+    }
+    return chosen;
+  };
+  for (const { element } of all("template")) {
+    if (attr(element, "name") === undefined && attr(element, "visibility")) {
+      throw xsltError("XTSE0500", "A template rule has no visibility");
+    }
+  }
+  const list = [];
+  for (const { element } of named(all("template")).values()) {
+    list.push(component("template", qname(element), element));
+  }
+  for (const { signature } of signatures.values()) {
+    const { element } = signature.declaration;
+    list.push(
+      component("function", signature, element, { arity: signature.arity }),
+    );
+  }
+  for (const { element } of globals.values()) {
+    const isParam = isXsl(element, "param");
+    list.push(component("variable", qname(element), element, { isParam }));
+  }
+  // attribute sets and modes may be declared several times
+  const byName = new Map();
+  for (const { element } of all("attribute-set")) {
+    const name = cx.exprs.qname(required(element, "name"), element);
+    byName.set(`a${clarkOf(name)}`, component("attribute-set", name, element));
+  }
+  for (const { element } of all("mode")) {
+    if (attr(element, "name") === undefined) {
+      if (
+        !["private", undefined].includes(attr(element, "visibility")?.trim())
+      ) {
+        throw xsltError("XTSE0020", "The unnamed mode is always private");
+      }
+      continue;
+    }
+    const name = qname(element);
+    const mode = component("mode", name, element);
+    // several xsl:mode declarations: the one with a visibility counts
+    if (mode.declared || !byName.has(`m${clarkOf(name)}`)) {
+      byName.set(`m${clarkOf(name)}`, mode);
+    }
+  }
+  return [...list, ...byName.values()];
+}
+
+/**
+ * Gives the declared components their visibility.
+ * @param {object[]} components - From {@link declaredComponents}
+ * @param {object[]} rules - Parsed xsl:expose rules
+ * @param {boolean} implicit - An implicit package (xsl:stylesheet): its
+ *   named templates and modes are public unless declared otherwise
+ */
+export function exposeComponents(components, rules, implicit) {
+  for (const item of components) {
+    item.visibility = exposedVisibility(item, rules);
+    if (
+      implicit &&
+      !item.declared &&
+      ["template", "mode"].includes(item.kind)
+    ) {
+      item.visibility = "public";
+    }
+  }
+  checkUnmatched(rules, "XTSE3020");
+}

package/src/xslt/compiler/contextItem.js

@@ -0,0 +1,95 @@
+/**
+ * xsl:context-item (XSLT 3.0 section 10.1.1): the context item a
+ * template requires (use="required", XTTE3090 when absent), accepts
+ * (optional) or ignores (absent: the template runs with an absent
+ * focus), and its type (XTTE0590 when it does not match; no conversion).
+ *
+ * @module @tradik/xslt3/xslt/compiler/contextItem
+ */
+
+import { matchesSequenceType } from "../../xpath/eval/sequenceType.js";
+import { derive } from "../runtime/context.js";
+import { attr, isXsl, xsltError } from "../names.js";
+import { checkAttributes } from "./attributes.js";
+import { isWhitespaceText } from "./children.js";
+
+/** Values of the use attribute. */
+const USES = new Set(["required", "optional", "absent"]);
+
+/**
+ * Compiles the type of an `as` attribute that must be an item type.
+ * @param {Element} element
+ * @param {object} cx
+ * @returns {object|null} a sequence type of exactly one item
+ */
+function itemType(element, cx) {
+  const text = attr(element, "as");
+  if (text === undefined) return null;
+  const type = cx.exprs.sequenceType(text, element);
+  if (type.occurrence !== "" || type.itemType === null) {
+    throw xsltError("XTSE0020", `"${text}" is not an item type`);
+  }
+  return type;
+}
+
+/**
+ * The step that checks the context item of a template.
+ * @param {Element} element - xsl:context-item
+ * @param {boolean} named - The template has a name
+ * @param {object} cx
+ * @returns {{binding: Function}}
+ */
+function compileCheck(element, named, cx) {
+  checkAttributes(element);
+  const use = (attr(element, "use") ?? "optional").trim();
+  if (!USES.has(use)) throw xsltError("XTSE0020", `Invalid use "${use}"`);
+  if (use === "absent" && attr(element, "as") !== undefined) {
+    throw xsltError("XTSE3088", 'use="absent" cannot have a type');
+  }
+  if (!named && use !== "required") {
+    throw xsltError("XTSE0020", "A template rule requires its context item");
+  }
+  const type = itemType(element, cx);
+  return {
+    binding(xc) {
+      if (use === "absent") {
+        // no focus, hence no current template rule either (XTDE0560)
+        return derive(xc, {
+          item: undefined,
+          position: 0,
+          size: 0,
+          rule: null,
+        });
+      }
+      if (xc.item === undefined) {
+        if (use === "required") {
+          throw xsltError("XTTE3090", "The template requires a context item");
+        }
+      } else if (type && !matchesSequenceType([xc.item], type)) {
+        throw xsltError("XTTE0590", "The context item has the wrong type");
+      }
+      return xc;
+    },
+  };
+}
+
+/**
+ * Separates the xsl:context-item of a template from its other children.
+ * @param {Array<object>} children - Significant children of the template
+ * @param {Element} template
+ * @param {object} cx
+ * @returns {{rest: Array<object>, steps: Array}} the other children, and
+ *   the step that checks the context item (to run first)
+ */
+export function splitContextItem(children, template, cx) {
+  const index = children.findIndex((child) => !isWhitespaceText(child));
+  const first = children[index];
+  const declared = first !== undefined && isXsl(first, "context-item");
+  const rest = declared ? children.slice(index + 1) : children;
+  if (rest.some((child) => isXsl(child, "context-item"))) {
+    throw xsltError("XTSE0010", "xsl:context-item must be the first child");
+  }
+  if (!declared) return { rest, steps: [] };
+  const named = attr(template, "name") !== undefined;
+  return { rest, steps: [compileCheck(first, named, cx)] };
+}