@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/xslt/compiler/packageRegistry.js

@@ -0,0 +1,95 @@
+/**
+ * What a package adds to the registries of a stylesheet (XSLT 3.0
+ * section 3.5): the modes accepted from used packages, the modes the
+ * package refers to (declared-modes), and the name xsl:original while an
+ * overriding declaration is compiled.
+ *
+ * @module @tradik/xslt3/xslt/compiler/packageRegistry
+ */
+
+import { attr, clarkOf, ORIGINAL } from "../names.js";
+import { infoOf } from "./elementInfo.js";
+import { CompilerRegistry } from "./registry.js";
+
+/** Registries of a package. */
+export class PackageRegistry extends CompilerRegistry {
+  /** @param {object} options - See compileStylesheet (and packageChain) */
+  constructor(options) {
+    super(options);
+    /** @type {Map<string, import("../patterns/modes.js").Mode>} */
+    this.acceptedModes = new Map();
+    /** @type {Set<string>} modes named by xsl:apply-templates */
+    this.modeRefs = new Set();
+    /** @type {object|null} the component an overriding one is compiled for */
+    this.overriding = null;
+    /** @type {string[]} names of the packages being compiled */
+    this.packageChain = options.packageChain ?? [];
+    this.uses = [];
+    this.table = new Map();
+  }
+
+  /**
+   * The scope of top-level declarations.
+   * @param {number} [original] - Index of the global that the name
+   *   xsl:original refers to (in an overriding variable)
+   * @returns {{vars: object|null}}
+   */
+  globalScope(original) {
+    if (original === undefined) return super.globalScope();
+    let vars = null;
+    this.globalKeys.forEach((key, i) => {
+      vars = { key: i === original ? ORIGINAL : key, next: vars };
+    });
+    return { vars };
+  }
+
+  /**
+   * The registry key of a template or attribute set reference: the
+   * overridden component for xsl:original in an overriding declaration.
+   * @param {string} kind - "template" or "attribute-set"
+   * @param {string} name - Clark name
+   * @returns {string|null} null when the name is not xsl:original there
+   */
+  originalName(kind, name) {
+    if (name !== ORIGINAL || this.overriding?.kind !== kind) return null;
+    return `${ORIGINAL}#${this.overriding.key}`;
+  }
+
+  /**
+   * @param {Element} element - xsl:mode
+   * @returns {string} the Clark name of the mode it declares
+   */
+  declaredModeName(element) {
+    const text = attr(element, "name");
+    return text === undefined ? "" : clarkOf(this.exprs.qname(text, element));
+  }
+
+  /**
+   * @param {Element} element
+   * @returns {string} the default mode of an element
+   */
+  defaultModeOf(element) {
+    return infoOf(element).defaultMode;
+  }
+
+  /**
+   * A mode accepted from a used package, else one of this package.
+   * @param {string} name - Clark name, "" for the unnamed mode
+   * @returns {import("../patterns/modes.js").Mode}
+   */
+  mode(name) {
+    return this.acceptedModes.get(name) ?? super.mode(name);
+  }
+
+  /**
+   * Resolves the mode attribute of xsl:apply-templates, noting the mode.
+   * @param {string|undefined} text
+   * @param {Element} element
+   * @returns {{current: boolean, name: string}}
+   */
+  modeRef(text, element) {
+    const ref = super.modeRef(text, element);
+    if (!ref.current) this.modeRefs.add(ref.name);
+    return ref;
+  }
+}

package/src/xslt/compiler/packageTable.js

@@ -0,0 +1,181 @@
+/**
+ * The components of a package (XSLT 3.0 section 3.5.3): its own
+ * declarations, the components accepted from used packages and the
+ * overriding declarations, checked for conflicts (XTSE3050, XTSE3055);
+ * the non-hidden ones are what a using package sees (`exports`). Global
+ * variables are slots of one environment shared by every package of the
+ * stylesheet; each package names the slots it can see.
+ *
+ * @module @tradik/xslt3/xslt/compiler/packageTable
+ */
+
+import { attr, isXsl, xsltError } from "../names.js";
+import { yesNo } from "./attributes.js";
+import { declaredComponents, exposeComponents } from "./components.js";
+import { parseVersion } from "./packageVersions.js";
+import { modesOf } from "./templatesDecl.js";
+import { parseVisibilityRules } from "./visibility.js";
+
+/** Import precedences of the packages that use another one start here. */
+export const LEVEL_PRECEDENCE = 1e6;
+
+/**
+ * The attributes of the package: name, version, declared-modes.
+ * @param {Element} root - Root of the principal module
+ * @returns {{name: string|undefined, version: string, declaredModes:
+ *   boolean, implicit: boolean}}
+ */
+export function packageHeader(root) {
+  if (!isXsl(root, "package")) {
+    return {
+      name: undefined,
+      version: "1",
+      declaredModes: false,
+      implicit: true,
+    };
+  }
+  const version = attr(root, "package-version")?.trim() ?? "1";
+  if (parseVersion(version) === null) {
+    throw xsltError("XTSE0020", `Invalid package-version ${version}`);
+  }
+  return {
+    name: attr(root, "name")?.trim(),
+    version,
+    declaredModes: yesNo(root, "declared-modes", true),
+    implicit: false,
+  };
+}
+
+/**
+ * Adds a component to the table of a package.
+ * @param {Map<string, object>} table
+ * @param {object} entry
+ * @param {string} code - Error code of a conflict
+ */
+function enter(table, entry, code) {
+  const id = `${entry.kind} ${entry.key}`;
+  if (table.has(id)) {
+    throw xsltError(code, `Two components ${entry.kind} ${entry.local}`);
+  }
+  table.set(id, entry);
+}
+
+/**
+ * A variable slot (see the module comment).
+ * @param {string} name - Clark name
+ * @param {object} owner - Compiler of the declaration that gives its value
+ * @param {object} declaration - `{element, key}`
+ * @returns {object}
+ */
+const slot = (name, owner, declaration) => ({
+  name,
+  owner,
+  declaration,
+  original: null,
+  abstract: false,
+});
+
+/**
+ * Builds the component table, the exports and the variable slots.
+ * @param {object} cx - The package's compiler after compileContext
+ * @param {(kind: string) => object[]} all - Declarations by kind
+ * @param {{signatures: Map, globals: Map, definitions: Map}} context
+ */
+export function buildTable(cx, all, context) {
+  const rules = parseVisibilityRules(
+    all("expose").map(({ element }) => element),
+    cx,
+    {
+      allowed: new Set(["public", "private", "final", "abstract"]),
+      anyCode: "XTSE3022",
+    },
+  );
+  const own = declaredComponents(all, cx, context);
+  exposeComponents(own, rules, cx.header.implicit);
+  // kept for the modes used without declaration (see packageChecks.js)
+  cx.exposeRules = rules;
+  const table = new Map();
+  cx.ownSlots = [];
+  cx.globalNames = new Map();
+  for (const component of own) {
+    const entry = { ...component, owner: cx };
+    if (component.kind === "function") {
+      entry.definition = context.definitions.get(component.key);
+      entry.cell = cx.functionBodies.get(component.key);
+    } else if (component.kind === "variable") {
+      const declaration = context.globals.get(component.key);
+      entry.slot = slot(component.key, cx, declaration);
+      entry.slot.abstract = component.visibility === "abstract";
+      cx.ownSlots.push(entry.slot);
+      cx.globalNames.set(component.key, entry.slot);
+    }
+    enter(table, entry, "XTSE3050");
+  }
+  const overridden = new Set();
+  for (const use of cx.uses) {
+    for (const { component, visibility, override } of use.accepted) {
+      const entry = { ...component, visibility, override };
+      if (override) {
+        const id = `${component.kind} ${component.key}`;
+        if (table.has(id) && !overridden.has(id)) {
+          throw xsltError(
+            component.kind === "function" ? "XTSE0770" : "XTSE3055",
+            `${component.local} is declared and overridden`,
+          );
+        }
+        overridden.add(id);
+        if (component.kind === "variable") overrideSlot(cx, entry, override);
+        entry.owner = cx;
+      }
+      if (component.kind === "variable") {
+        cx.globalNames.set(entry.key, entry.slot);
+      }
+      enter(table, entry, "XTSE3050");
+    }
+  }
+  checkRulesInAcceptedModes(cx, all, table);
+  cx.table = table;
+  cx.exports = [...table.values()];
+}
+
+/**
+ * Gives a variable slot the value of its overriding declaration; the
+ * value it had moves to a new hidden slot, its `xsl:original`.
+ * @param {object} cx
+ * @param {object} entry - Table entry of the accepted variable
+ * @param {Element} element - The overriding xsl:variable or xsl:param
+ */
+function overrideSlot(cx, entry, element) {
+  const target = entry.slot;
+  const original = slot("", target.owner, target.declaration);
+  original.original = target.original;
+  original.abstract = target.abstract;
+  cx.ownSlots.push(original);
+  target.owner = cx;
+  target.declaration = { element, key: entry.key };
+  target.original = original;
+  target.abstract = false;
+  entry.isParam = isXsl(element, "param");
+}
+
+/**
+ * XTSE3050: template rules outside xsl:override cannot be added to a mode
+ * of a used package.
+ * @param {object} cx
+ * @param {(kind: string) => object[]} all
+ * @param {Map<string, object>} table
+ */
+function checkRulesInAcceptedModes(cx, all, table) {
+  for (const { element } of all("template")) {
+    if (attr(element, "match") === undefined) continue;
+    for (const mode of modesOf(element, cx)) {
+      const entry = table.get(`mode ${mode}`);
+      if (entry && entry.owner !== cx) {
+        throw xsltError(
+          "XTSE3050",
+          `The mode ${mode} belongs to a used package`,
+        );
+      }
+    }
+  }
+}

package/src/xslt/compiler/packageVersions.js

@@ -0,0 +1,143 @@
+/**
+ * Package versions and version ranges (XSLT 3.0 section 3.5.1): parsing,
+ * ordering, and matching a version against the range of an
+ * xsl:use-package declaration.
+ *
+ * @module @tradik/xslt3/xslt/compiler/packageVersions
+ */
+
+import { xsltError } from "../names.js";
+
+/**
+ * Parses a package version into its portions: integers (BigInt) and an
+ * optional final NCName.
+ * @param {string} text - `NumericPart ("-" NamePart)?`
+ * @param {boolean} [keepZeros] - Keep trailing zero portions (prefixes)
+ * @returns {Array<bigint|string>|null} null when the syntax is wrong
+ */
+export function parseVersion(text, keepZeros = false) {
+  const match = /^(\d+(?:\.\d+)*)(?:-(.+))?$/.exec(text.trim());
+  // the name part is an NCName; any name without ":" is accepted
+  if (!match || match[2]?.includes(":")) return null;
+  const portions = match[1].split(".").map(BigInt);
+  if (!keepZeros) {
+    while (portions.length > 1 && portions.at(-1) === 0n) portions.pop();
+  }
+  if (match[2] !== undefined) portions.push(match[2]);
+  return portions;
+}
+
+/**
+ * Compares two portions: integers numerically, names by code point, a
+ * name before an integer.
+ * @param {bigint|string} a
+ * @param {bigint|string} b
+ * @returns {number}
+ */
+function comparePortion(a, b) {
+  const aName = typeof a === "string";
+  if (aName !== (typeof b === "string")) return aName ? -1 : 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Compares two parsed versions.
+ * @param {Array<bigint|string>} a
+ * @param {Array<bigint|string>} b
+ * @returns {number} negative, zero or positive
+ */
+export function compareVersions(a, b) {
+  const length = Math.min(a.length, b.length);
+  for (let i = 0; i < length; i++) {
+    const order = comparePortion(a[i], b[i]);
+    if (order !== 0) return order;
+  }
+  if (a.length === b.length) return 0;
+  // the longer one is greater when its next portion is an integer
+  const longer = a.length > b.length ? a : b;
+  const sign = typeof longer[length] === "string" ? -1 : 1;
+  return a.length > b.length ? sign : -sign;
+}
+
+/**
+ * A version or a version prefix (`1.3.*`) of a range.
+ * @param {string} text
+ * @returns {{portions: Array<bigint|string>, prefix: boolean}}
+ */
+function parseBound(text) {
+  const prefix = text.endsWith(".*");
+  const portions = parseVersion(prefix ? text.slice(0, -2) : text, prefix);
+  if (!portions) throw xsltError("XTSE0020", `Invalid version ${text}`);
+  return { portions, prefix };
+}
+
+/**
+ * Whether a version is at most some version matching a bound.
+ * @param {Array<bigint|string>} version
+ * @param {{portions: Array, prefix: boolean}} bound
+ * @returns {boolean}
+ */
+function atMost(version, bound) {
+  if (!bound.prefix) return compareVersions(version, bound.portions) <= 0;
+  return (
+    matchesPrefix(version, bound.portions) ||
+    compareVersions(version, bound.portions) < 0
+  );
+}
+
+/**
+ * @param {Array<bigint|string>} version
+ * @param {Array<bigint|string>} prefix
+ * @returns {boolean} whether the leading portions of the version are the
+ *   prefix
+ */
+function matchesPrefix(version, prefix) {
+  const name = typeof version.at(-1) === "string" ? [version.at(-1)] : [];
+  const numbers = version.slice(0, version.length - name.length);
+  // trailing zeros were dropped: 1.0.* matches 1
+  while (numbers.length < prefix.length) numbers.push(0n);
+  const padded = [...numbers, ...name];
+  return prefix.every((portion, i) => portion === padded[i]);
+}
+
+/**
+ * Parses a version range into a predicate.
+ * @param {string|undefined} text - The package-version attribute of
+ *   xsl:use-package (absent: any version)
+ * @returns {(version: Array<bigint|string>) => boolean}
+ * @throws {import("../../errors.js").XPathError} XTSE0020 for a bad range
+ */
+export function parseVersionRange(text) {
+  const range = (text ?? "*").trim();
+  if (range === "*") return () => true;
+  const tests = range.split(/\s*,\s*/).map((part) => {
+    const to = /^(.*?)\s*\bto\s+(\S+)$/.exec(part);
+    if (to) {
+      const upper = parseBound(to[2]);
+      if (to[1] === "") return (v) => atMost(v, upper);
+      const lower = parseBound(to[1]);
+      if (lower.prefix) throw xsltError("XTSE0020", `Invalid range ${part}`);
+      return (v) => compareVersions(v, lower.portions) >= 0 && atMost(v, upper);
+    }
+    if (part.endsWith("+")) {
+      const lower = parseBound(part.slice(0, -1));
+      return (v) => compareVersions(v, lower.portions) >= 0;
+    }
+    const bound = parseBound(part);
+    return bound.prefix
+      ? (v) => matchesPrefix(v, bound.portions)
+      : (v) => compareVersions(v, bound.portions) === 0;
+  });
+  return (version) => tests.some((test) => test(version));
+}
+
+/**
+ * Whether a package version matches a version range.
+ * @param {string} version - Package version (absent: "1")
+ * @param {string} [range] - Version range (absent: "*")
+ * @returns {boolean}
+ */
+export function versionMatches(version, range) {
+  const parsed = parseVersion(version ?? "1");
+  return parsed !== null && parseVersionRange(range)(parsed);
+}

package/src/xslt/compiler/packages.js

@@ -0,0 +1,138 @@
+/**
+ * xsl:use-package (XSLT 3.0 section 3.5.2): the used package located
+ * through the `resolvePackage` option and compiled for this use, and the
+ * components it offers accepted (xsl:accept) or overridden
+ * (xsl:override) by the using package (section 3.5.3.2).
+ *
+ * @module @tradik/xslt3/xslt/compiler/packages
+ */
+
+import { attr, isXsl, xsltError } from "../names.js";
+import { acceptComponents, matchOverrides } from "./acceptance.js";
+import { checkAttributes, required } from "./attributes.js";
+import { parseVersionRange, versionMatches } from "./packageVersions.js";
+import { checkUnmatched, parseVisibilityRules } from "./visibility.js";
+
+const ACCEPT_VALUES = new Set([
+  "public",
+  "private",
+  "final",
+  "abstract",
+  "hidden",
+]);
+const OVERRIDABLE = new Set([
+  "template",
+  "function",
+  "variable",
+  "param",
+  "attribute-set",
+]);
+
+/**
+ * Locates and prepares the package of an xsl:use-package declaration.
+ * @param {Element} element
+ * @param {object} cx - The using package's compiler
+ * @returns {object} the prepared compiler of the used package
+ */
+function locatePackage(element, cx) {
+  const name = required(element, "name").trim();
+  const range = attr(element, "package-version");
+  parseVersionRange(range);
+  if (cx.packageChain.includes(name)) {
+    throw xsltError("XTSE3005", `The package ${name} depends on itself`);
+  }
+  const found = cx.options.resolvePackage?.(name, range?.trim() ?? "*");
+  if (!found) throw xsltError("XTSE3000", `No package ${name} ${range ?? ""}`);
+  const { source, baseUri } =
+    typeof found === "object" && "source" in found ? found : { source: found };
+  const child = cx.usedPackage([...cx.packageChain, name]);
+  const document =
+    typeof source === "string" ? cx.options.parse(source, baseUri) : source;
+  child.prepare(document, baseUri ?? (document.documentURI || undefined));
+  // a package without a name takes the one it was found by
+  const named = child.packageName ?? name;
+  if (named !== name || !versionMatches(child.packageVersion, range)) {
+    throw xsltError("XTSE3000", `No package ${name} ${range ?? ""}`);
+  }
+  return child;
+}
+
+/**
+ * The xsl:accept rules and overriding declarations of an xsl:use-package.
+ * @param {Element} element
+ * @param {object} cx
+ * @returns {{rules: object[], overrides: Element[]}}
+ */
+function useContent(element, cx) {
+  const accepts = [];
+  const overrides = [];
+  for (const child of cx.children(element)) {
+    if (isXsl(child, "accept")) {
+      checkAttributes(child);
+      accepts.push(child);
+    } else if (isXsl(child, "override")) {
+      checkAttributes(child);
+      for (const declaration of cx.children(child)) {
+        if (
+          declaration.nodeType !== 1 ||
+          !OVERRIDABLE.has(declaration.localName) ||
+          !isXsl(declaration)
+        ) {
+          throw xsltError(
+            "XTSE0010",
+            "xsl:override holds only overridable declarations",
+          );
+        }
+        overrides.push(declaration);
+      }
+    } else {
+      throw xsltError(
+        "XTSE0010",
+        "xsl:use-package holds xsl:accept and xsl:override",
+      );
+    }
+  }
+  const rules = parseVisibilityRules(accepts, cx, {
+    allowed: ACCEPT_VALUES,
+    anyCode: "XTSE3032",
+  });
+  return { rules, overrides };
+}
+
+/**
+ * Resolves an xsl:use-package declaration: prepares the used package and
+ * decides the visibility of each of its components in this package.
+ * @param {object} declaration - `{element, imported}`
+ * @param {object} cx - The using package's compiler
+ * @returns {object} `{element, child, accepted, overrides}`: accepted
+ *   components `{component, visibility, override}` (hidden ones left
+ *   out), overriding declarations `{element, symbol, component}`
+ */
+export function usePackage(declaration, cx) {
+  const { element } = declaration;
+  if (declaration.imported) {
+    throw xsltError(
+      "XTSE3008",
+      "xsl:use-package cannot be in an imported module",
+    );
+  }
+  checkAttributes(element);
+  const child = locatePackage(element, cx);
+  const { rules, overrides } = useContent(element, cx);
+  const byKey = new Map(child.exports.map((c) => [`${c.kind} ${c.key}`, c]));
+  const { list, overridden } = matchOverrides(overrides, rules, byKey, cx);
+  const accepted = acceptComponents(
+    child.exports,
+    overridden,
+    rules,
+    cx.header.implicit,
+  );
+  checkUnmatched(rules, "XTSE3030");
+  return {
+    element,
+    child,
+    accepted,
+    overrides: list,
+    precedence: declaration.precedence,
+  };
+}