@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/xpath/syntax/typeOperators.js

@@ -0,0 +1,127 @@
+/**
+ * Parser of the XPath 3.1 expressions between the binary operators and the
+ * paths: productions [25] InstanceofExpr to [35] SimpleMapExpr of Appendix
+ * A.1 (instance of, treat as, castable as, cast as, `=>`, unary signs and
+ * `!`).
+ *
+ * @module @tradik/xslt3/xpath/syntax/typeOperators
+ */
+
+import { makeNode } from "./ast.js";
+import { parsePathExpr } from "./paths.js";
+import { parseArgumentList } from "./postfix.js";
+import { parseParenthesizedExpr, parseVarRef } from "./primaries.js";
+import { qName } from "./tokenStream.js";
+import { parseSequenceType, parseSingleType } from "./types.js";
+
+/** @typedef {import("./tokenStream.js").TokenStream} TokenStream */
+/** @typedef {import("./ast.js").Expr} Expr */
+
+/**
+ * SimpleMapExpr ::= PathExpr ("!" PathExpr)*
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {Expr} The node
+ */
+function parseSimpleMapExpr(p) {
+  let left = parsePathExpr(p);
+  while (p.acceptSymbol("!")) {
+    const right = parsePathExpr(p);
+    left = makeNode("SimpleMapExpr", { left, right }, left.start, right.end);
+  }
+  return left;
+}
+
+/**
+ * UnaryExpr ::= ("-" | "+")* ValueExpr, ValueExpr being a SimpleMapExpr.
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {Expr} The node
+ */
+function parseUnaryExpr(p) {
+  const sign = p.acceptSymbol("-") ?? p.acceptSymbol("+");
+  if (!sign) return parseSimpleMapExpr(p);
+  const operand = parseUnaryExpr(p);
+  const fields = { operator: sign.value, operand };
+  return makeNode("UnaryExpr", fields, sign.start, operand.end);
+}
+
+/**
+ * ArrowExpr ::= UnaryExpr ("=>" ArrowFunctionSpecifier ArgumentList)*,
+ * the specifier being an EQName, a VarRef or a ParenthesizedExpr.
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {Expr} The node
+ */
+function parseArrowExpr(p) {
+  let expr = parseUnaryExpr(p);
+  while (p.acceptSymbol("=>")) {
+    let functionName = null;
+    let functionExpr = null;
+    if (p.peek().type === "name") functionName = qName(p.next());
+    else if (p.isSymbol("$")) functionExpr = parseVarRef(p);
+    else if (p.isSymbol("(")) functionExpr = parseParenthesizedExpr(p);
+    else p.fail('Expected a function after "=>"');
+    const { arguments: args, end } = parseArgumentList(p);
+    const fields = { expr, functionName, functionExpr, arguments: args };
+    expr = makeNode("ArrowExpr", fields, expr.start, end);
+  }
+  return expr;
+}
+
+/**
+ * Builds the parser of `E keyword1 keyword2 Type` (instance of, treat as,
+ * castable as, cast as). Each operator may appear at most once.
+ *
+ * @param {string} type - Node type
+ * @param {string} keywords - The two keywords, space-separated
+ * @param {(p: TokenStream) => Expr} operand - Parser of the next level
+ * @param {boolean} single - SingleType (cast, castable) or SequenceType
+ * @returns {(p: TokenStream) => Expr} Parser of the level
+ */
+function typeLevel(type, keywords, operand, single) {
+  const [first, second] = keywords.split(" ");
+  return (p) => {
+    const expr = operand(p);
+    if (!p.acceptKeyword(first)) return expr;
+    p.expectKeyword(second);
+    if (single) {
+      const { name, emptyAllowed, end } = parseSingleType(p);
+      const fields = { expr, targetType: name, emptyAllowed };
+      return makeNode(type, fields, expr.start, end);
+    }
+    const sequenceType = parseSequenceType(p);
+    return makeNode(type, { expr, sequenceType }, expr.start, sequenceType.end);
+  };
+}
+
+const parseCastExpr = typeLevel("CastExpr", "cast as", parseArrowExpr, true);
+const parseCastableExpr = typeLevel(
+  "CastableExpr",
+  "castable as",
+  parseCastExpr,
+  true,
+);
+const parseTreatExpr = typeLevel(
+  "TreatExpr",
+  "treat as",
+  parseCastableExpr,
+  false,
+);
+const parseInstanceof = typeLevel(
+  "InstanceOfExpr",
+  "instance of",
+  parseTreatExpr,
+  false,
+);
+
+/**
+ * InstanceofExpr ::= TreatExpr ("instance" "of" SequenceType)?, the entry
+ * point of this module.
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {Expr} The node
+ */
+export function parseInstanceofExpr(p) {
+  return parseInstanceof(p);
+}

package/src/xpath/syntax/types.js

@@ -0,0 +1,158 @@
+/**
+ * Parser of XPath 3.1 types: SingleType, SequenceType and ItemType with the
+ * function, map and array tests (productions [77] SingleType to [116]
+ * ParenthesizedItemType of Appendix A.1). Kind tests are in kindTests.js.
+ *
+ * Occurrence-indicators constraint (A.1.2): a `?`, `*` or `+` right after
+ * an item type always belongs to it, so `4 treat as item() + - 5` is
+ * `(4 treat as item()+) - 5`.
+ *
+ * @module @tradik/xslt3/xpath/syntax/types
+ */
+
+import { makeNode } from "./ast.js";
+import { isKindTestName, parseKindTest } from "./kindTests.js";
+import { isPlainName, qName } from "./tokenStream.js";
+
+/** @typedef {import("./tokenStream.js").TokenStream} TokenStream */
+/** @typedef {import("./typeAst.js").SequenceType} SequenceType */
+/** @typedef {import("./typeAst.js").ItemType} ItemType */
+
+const OCCURRENCES = ["?", "*", "+"];
+
+/**
+ * SingleType ::= SimpleTypeName "?"?
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {{name: import("./ast.js").QName, emptyAllowed: boolean, end: number}}
+ *   The type name, whether "?" follows, and the offset after the type
+ */
+export function parseSingleType(p) {
+  const token = p.expectName("a type name");
+  const question = p.acceptSymbol("?");
+  const end = question ? question.end : token.end;
+  return { name: qName(token), emptyAllowed: Boolean(question), end };
+}
+
+/**
+ * SequenceType ::= ("empty-sequence" "(" ")") | (ItemType OccurrenceIndicator?)
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {SequenceType} The type
+ */
+export function parseSequenceType(p) {
+  const start = p.peek().start;
+  if (p.isKeyword("empty-sequence") && p.isSymbol("(", 1)) {
+    p.next();
+    p.next();
+    const end = p.expectSymbol(")").end;
+    return makeNode(
+      "SequenceType",
+      { itemType: null, occurrence: "" },
+      start,
+      end,
+    );
+  }
+  const itemType = parseItemType(p);
+  const indicator = OCCURRENCES.find((symbol) => p.isSymbol(symbol));
+  const end = indicator ? p.next().end : itemType.end;
+  return makeNode(
+    "SequenceType",
+    { itemType, occurrence: indicator ?? "" },
+    start,
+    end,
+  );
+}
+
+/**
+ * ItemType ::= KindTest | ("item" "(" ")") | FunctionTest | MapTest |
+ * ArrayTest | AtomicOrUnionType | ParenthesizedItemType
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {ItemType} The type
+ */
+export function parseItemType(p) {
+  const token = p.peek();
+  if (p.acceptSymbol("(")) {
+    const inner = parseItemType(p);
+    p.expectSymbol(")");
+    return inner;
+  }
+  if (token.type !== "name") p.fail("Expected an item type");
+  if (p.isSymbol("(", 1)) {
+    if (isKindTestName(token)) return parseKindTest(p);
+    const parse =
+      isPlainName(token) && Object.hasOwn(TYPE_TESTS, token.local)
+        ? TYPE_TESTS[token.local]
+        : null;
+    if (parse) {
+      p.next();
+      p.next();
+      const { type, ...fields } = parse(p);
+      let end = p.expectSymbol(")").end;
+      if (type === "TypedFunctionTest") {
+        p.expectKeyword("as");
+        fields.returnType = parseSequenceType(p);
+        end = fields.returnType.end;
+      }
+      return makeNode(type, fields, token.start, end);
+    }
+  }
+  p.next();
+  return makeNode("AtomicType", { name: qName(token) }, token.start, token.end);
+}
+
+/** Parsers of the item tests with a keyword, after the "(". */
+const TYPE_TESTS = {
+  item: () => ({ type: "AnyItemTest" }),
+  function: parseFunctionTestBody,
+  map: parseMapTestBody,
+  array: parseArrayTestBody,
+};
+
+/**
+ * Inside `function(...)`: "*" or the parameter types; the caller reads the
+ * `as` return type of a typed test after the ")".
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {object} Fields of the test
+ */
+function parseFunctionTestBody(p) {
+  if (p.acceptSymbol("*")) return { type: "AnyFunctionTest" };
+  const paramTypes = [];
+  if (!p.isSymbol(")")) {
+    do paramTypes.push(parseSequenceType(p));
+    while (p.acceptSymbol(","));
+  }
+  return { type: "TypedFunctionTest", paramTypes };
+}
+
+/**
+ * Inside `map(...)`: "*" or AtomicOrUnionType "," SequenceType.
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {object} Fields of the test
+ */
+function parseMapTestBody(p) {
+  if (p.acceptSymbol("*")) return { type: "AnyMapTest" };
+  const token = p.expectName("an atomic type");
+  const keyType = makeNode(
+    "AtomicType",
+    { name: qName(token) },
+    token.start,
+    token.end,
+  );
+  p.expectSymbol(",");
+  return { type: "TypedMapTest", keyType, valueType: parseSequenceType(p) };
+}
+
+/**
+ * Inside `array(...)`: "*" or SequenceType.
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {object} Fields of the test
+ */
+function parseArrayTestBody(p) {
+  if (p.acceptSymbol("*")) return { type: "AnyArrayTest" };
+  return { type: "TypedArrayTest", memberType: parseSequenceType(p) };
+}

package/src/xslt/api.js

@@ -0,0 +1,153 @@
+/**
+ * XSLT 3.0 and 2.0 (and 1.0 in backwards-compatible mode): compile a
+ * stylesheet once, run it on many documents.
+ *
+ * ```js
+ * import { compileStylesheet } from "@tradik/xslt3";
+ * const stylesheet = compileStylesheet(xslDocument, { baseUri });
+ * const { principal, secondary, messages } = stylesheet.transform({
+ *   source: xmlDocument,
+ *   params: { title: "Report" },
+ * });
+ * ```
+ *
+ * @module @tradik/xslt3/xslt
+ */
+
+import { StylesheetCompiler } from "./compiler/stylesheet.js";
+import { normalizeParams } from "./runtime/params.js";
+import { withDefaultMethod } from "./runtime/defaultMethod.js";
+import { setCompiler } from "./runtime/compilerHook.js";
+import { runTransformation } from "./runtime/transformation.js";
+import { xsltError } from "./names.js";
+
+/**
+ * Parses XML text with the given parser or the global DOMParser.
+ * @param {string} text
+ * @param {string|undefined} uri
+ * @param {((text: string, uri?: string) => Document)|undefined} parseXml
+ * @returns {Document}
+ */
+function parse(text, uri, parseXml) {
+  if (parseXml) return parseXml(text, uri);
+  const Parser = globalThis.DOMParser;
+  if (!Parser) {
+    throw xsltError("XTSE0165", "No XML parser: pass the parseXml option");
+  }
+  return new Parser().parseFromString(text, "application/xml");
+}
+
+/** A compiled stylesheet. */
+export class CompiledStylesheet {
+  /** @param {StylesheetCompiler} compiled */
+  constructor(compiled) {
+    this.compiled = compiled;
+    /** @type {Map<string, object>} xsl:output parameters by Clark name ("" unnamed) */
+    this.outputs = compiled.outputs;
+  }
+
+  /**
+   * The parameters of the unnamed output definition, with
+   * `use-character-maps` expanded to a Map of characters to strings.
+   * @returns {object}
+   */
+  get output() {
+    return this.compiled.outputFor(null);
+  }
+
+  /**
+   * Runs the stylesheet.
+   * @param {object} [options]
+   * @param {Node} [options.source] - Source document (global context item
+   *   and initial match selection)
+   * @param {string} [options.initialTemplate] - Name of the initial
+   *   template (`local`, `Q{uri}local`)
+   * @param {string} [options.initialMode] - Clark name of the initial mode
+   * @param {Array} [options.initialMatchSelection] - Items to apply
+   *   templates to (default: the source)
+   * @param {object|Map} [options.params] - Stylesheet parameters by name
+   * @param {boolean} [options.paramsAsUntyped] - JavaScript strings among
+   *   the stylesheet parameters are xs:untypedAtomic, so that they convert
+   *   to the declared type (`as="xs:integer"`) as command-line parameters
+   *   do in other processors; see also `untypedAtomic()`
+   * @param {object|Map} [options.templateParams] - Parameters of the
+   *   initial template or mode
+   * @param {object|Map} [options.tunnelParams] - Tunnel parameters
+   * @param {(uri: string, base?: string) => Document} [options.documentLoader]
+   *   - Loads documents for doc() and document(): gets the absolute URI
+   *   and the base URI the reference was resolved against
+   * @param {(uri: string) => (string|Uint8Array|object|null)} [options.textLoader]
+   *   - Reads text resources for unparsed-text(), json-doc() and the like
+   *   (default: none; `readFileUri` reads `file:` URIs)
+   * @param {(uri: string|null) => Array|null} [options.collections] - The
+   *   items of a collection for collection() and uri-collection(), `uri`
+   *   null for the default collection (default: none)
+   * @param {(text: string, baseUri?: string) => Document} [options.xmlParser]
+   *   - Parser for parse-xml() (default: the global DOMParser)
+   * @param {() => Document} [options.createDocument] - Creates documents
+   * @param {(message: Node) => void} [options.onMessage] - xsl:message
+   * @param {string} [options.baseOutputUri] - Base of result-document URIs
+   * @param {{name: string, args: Array}} [options.initialFunction] - A
+   *   stylesheet function to call instead (its result is the principal
+   *   result)
+   * @param {*} [options.globalContextItem] - Default: the source
+   * @param {number} [options.implicitTimezone] - Minutes, default 0
+   * @param {Date} [options.currentDateTime] - Default: now
+   * @param {boolean} [options.buildTree] - Overrides the build-tree
+   *   serialization parameter of every result: false delivers the raw
+   *   sequences (as fn:transform does for delivery-format "raw")
+   * @param {number} [options.maxDepth] - Deepest nesting of instructions
+   *   (default 1,000,000; deeper is reported as an infinite recursion)
+   * @returns {{principal: Node|Array, secondary: Map<string, {document:
+   *   Node, output: object}>, messages: Array, output: object}} the
+   *   results; `output` holds the serialization parameters of the
+   *   principal result: those of the xsl:result-document that wrote it,
+   *   else those of the `output` getter
+   */
+  transform(options = {}) {
+    const { principalOutput, ...result } = runTransformation(
+      this.compiled,
+      options,
+    );
+    const output =
+      principalOutput ??
+      withDefaultMethod(
+        this.output,
+        result.principal,
+        this.compiled.versionOf(this.compiled.tree.root) === 1,
+      );
+    return { ...result, output };
+  }
+}
+
+/**
+ * Compiles a stylesheet.
+ * @param {Document|Element|string} stylesheet - The principal module
+ * @param {object} [options]
+ * @param {string} [options.baseUri] - URI of the principal module
+ * @param {(uri: string, base?: string) => Document|string} [options.loadStylesheet]
+ *   - Loads included and imported modules (and parameter documents): gets
+ *   the absolute URI and the base URI the href was resolved against
+ * @param {(text: string, uri?: string) => Document} [options.parseXml] -
+ *   XML parser (default: the global DOMParser)
+ * @param {object|Map} [options.staticParams] - Values of static
+ *   parameters (XSLT 3.0) by name
+ * @returns {CompiledStylesheet}
+ * @throws {import("../errors.js").XPathError} the static errors (XTSE...)
+ */
+export function compileStylesheet(stylesheet, options = {}) {
+  const parseXml = (text, uri) => parse(text, uri, options.parseXml);
+  const source =
+    typeof stylesheet === "string"
+      ? parseXml(stylesheet, options.baseUri)
+      : stylesheet;
+  const compiler = new StylesheetCompiler({
+    ...options,
+    parse: parseXml,
+    staticParams: normalizeParams(options.staticParams),
+  });
+  const uri = options.baseUri ?? (source.documentURI || undefined);
+  return new CompiledStylesheet(compiler.compile(source, uri));
+}
+
+setCompiler(compileStylesheet);

package/src/xslt/compiler/acceptance.js

@@ -0,0 +1,178 @@
+/**
+ * The components of a used package seen from the using package (XSLT 3.0
+ * sections 3.5.3.2 and 3.5.3.3): the overriding declarations matched to
+ * the components they override, and the visibility of every other
+ * component after xsl:accept.
+ *
+ * @module @tradik/xslt3/xslt/compiler/acceptance
+ */
+
+import { attr, clarkOf, isXsl, tokens, xsltError } from "../names.js";
+import { checkCompatible } from "./compatibility.js";
+import { declaredVisibility } from "./components.js";
+import { infoOf } from "./elementInfo.js";
+import { splitParams } from "./templatesDecl.js";
+import { EXPLICIT, matchesOf } from "./visibility.js";
+
+/** Errors of two overriding declarations of the same component. */
+const DUPLICATE = {
+  template: "XTSE0660",
+  function: "XTSE0770",
+  variable: "XTSE0630",
+  "attribute-set": "XTSE3055",
+};
+
+/** Visibilities in the used package that each xsl:accept value allows. */
+const ACCEPTABLE = {
+  public: ["public"],
+  private: ["public", "final"],
+  final: ["public", "final"],
+  abstract: ["abstract"],
+  hidden: ["public", "final", "abstract"],
+};
+
+/**
+ * The visibility in the using package of a component that is not
+ * overridden (Visibility of Components in Used and Using Packages).
+ * @param {object} component - Exported by the used package
+ * @param {object[]} rules - Parsed xsl:accept rules
+ * @returns {string}
+ */
+function acceptedVisibility(component, rules) {
+  if (component.isParam) return "public";
+  for (const { rule, precision } of matchesOf(rules, component)) {
+    if (ACCEPTABLE[rule.visibility].includes(component.visibility)) {
+      return rule.visibility;
+    }
+    if (precision === EXPLICIT) {
+      throw xsltError(
+        "XTSE3040",
+        `${component.local} cannot be accepted as ${rule.visibility}`,
+      );
+    }
+  }
+  return ["public", "final"].includes(component.visibility)
+    ? "private"
+    : "hidden";
+}
+
+/**
+ * The component an overriding declaration names.
+ * @param {Element} element - Child of xsl:override
+ * @param {object} cx
+ * @returns {object|null} `{kind, uri, local, arity, key}`, null for a
+ *   template rule without a name
+ */
+function overrideSymbol(element, cx) {
+  const name = attr(element, "name");
+  if (name === undefined) return null;
+  const qname = cx.exprs.qname(name, element);
+  const kind = element.localName === "param" ? "variable" : element.localName;
+  const key = `{${qname.uri}}${qname.local}`;
+  if (kind !== "function") return { kind, ...qname, arity: null, key };
+  const arity = splitParams(cx.children(element)).params.length;
+  return { kind, ...qname, arity, key: `${key}#${arity}` };
+}
+
+/**
+ * Checks that the modes of an overriding template rule are public modes
+ * of the used package (XTSE3440 for the unnamed mode, XTSE3060).
+ * @param {Element} element - xsl:template with a match pattern
+ * @param {Map<string, object>} byKey - Exported components
+ * @param {object} cx
+ */
+function checkRuleModes(element, byKey, cx) {
+  const text = attr(element, "mode");
+  const { defaultMode } = infoOf(element);
+  const keys =
+    text === undefined
+      ? [defaultMode]
+      : tokens(text).map((token) => {
+          if (token === "#default") return defaultMode;
+          return token.startsWith("#")
+            ? ""
+            : clarkOf(cx.exprs.qname(token, element));
+        });
+  for (const key of keys) {
+    if (key === "") {
+      throw xsltError("XTSE3440", "An overriding template rule needs a mode");
+    }
+    if (byKey.get(`mode ${key}`)?.visibility !== "public") {
+      throw xsltError("XTSE3060", `No template rules can be added to ${key}`);
+    }
+  }
+}
+
+/**
+ * Matches the overriding declarations of an xsl:use-package with the
+ * components they override.
+ * @param {Element[]} overrides - Children of xsl:override
+ * @param {object[]} rules - Parsed xsl:accept rules
+ * @param {Map<string, object>} byKey - Exported components by "kind key"
+ * @param {object} cx - The using package's compiler
+ * @returns {{list: object[], overridden: Map<object, Element>}} the
+ *   declarations `{element, symbol, component}` and the overridden
+ *   components
+ */
+export function matchOverrides(overrides, rules, byKey, cx) {
+  const overridden = new Map();
+  const list = [];
+  for (const element of overrides) {
+    const symbol = overrideSymbol(element, cx);
+    if (attr(element, "match") !== undefined) {
+      checkRuleModes(element, byKey, cx);
+    }
+    if (!symbol) {
+      list.push({ element, symbol: null, component: null });
+      continue;
+    }
+    const component = byKey.get(`${symbol.kind} ${symbol.key}`);
+    if (!component) {
+      throw xsltError("XTSE3058", `${symbol.local} overrides nothing`);
+    }
+    if (!["public", "abstract"].includes(component.visibility)) {
+      throw xsltError("XTSE3060", `${symbol.local} cannot be overridden`);
+    }
+    if (matchesOf(rules, symbol).some((m) => m.precision === EXPLICIT)) {
+      throw xsltError("XTSE3051", `${symbol.local} is accepted and overridden`);
+    }
+    if (overridden.has(component)) {
+      throw xsltError(DUPLICATE[symbol.kind], `${symbol.local} twice`);
+    }
+    checkCompatible(element, component, cx);
+    overridden.set(component, element);
+    list.push({ element, symbol, component });
+  }
+  return { list, overridden };
+}
+
+/**
+ * The components of the used package with their visibility in the using
+ * package, hidden ones left out.
+ * @param {object[]} exported - Components exported by the used package
+ * @param {Map<object, Element>} overridden - From {@link matchOverrides}
+ * @param {object[]} rules - Parsed xsl:accept rules
+ * @param {boolean} [implicit] - The using package is an implicit one (an
+ *   xsl:stylesheet), whose templates and modes are public by default
+ * @returns {object[]} `{component, visibility, override}`
+ */
+export function acceptComponents(exported, overridden, rules, implicit) {
+  const accepted = [];
+  for (const component of exported) {
+    const element = overridden.get(component);
+    let visibility;
+    if (!element) visibility = acceptedVisibility(component, rules);
+    else if (isXsl(element, "param")) visibility = "public";
+    else {
+      const fallback =
+        implicit && ["template", "mode"].includes(component.kind)
+          ? "public"
+          : "private";
+      visibility = declaredVisibility(element, component.kind) ?? fallback;
+    }
+    if (visibility !== "hidden") {
+      accepted.push({ component, visibility, override: element ?? null });
+    }
+  }
+  return accepted;
+}