@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/functions/random.js

@@ -0,0 +1,128 @@
+/**
+ * fn:random-number-generator (F&O 3.1 section 17.3.1): a map with a
+ * pseudo-random `number` in [0, 1), a `next` generator and a `permute`
+ * function. The sequence is deterministic for a seed (the canonical string
+ * of the seed value, hashed with FNV-1a) and uses the Mulberry32
+ * generator; without a seed, the current date and time of the evaluation
+ * is the seed, so calls in one evaluation agree.
+ *
+ * @module @tradik/xslt3/functions/random
+ */
+
+import { FunctionItem } from "../items/function.js";
+import { XdmMap } from "../items/map.js";
+import { formatDateTime } from "../xdm/datetime.js";
+import { canonicalString } from "../xdm/lexical.js";
+import { sequenceTypeOf } from "../xpath/eval/functionItems.js";
+import { define, doubleItem, stringItem } from "./support.js";
+
+/**
+ * FNV-1a hash of a string.
+ * @param {string} text
+ * @returns {number} an unsigned 32-bit integer
+ */
+export function hashSeed(text) {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    hash = Math.imul(hash ^ text.charCodeAt(i), 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+/**
+ * One step of Mulberry32.
+ * @param {number} state - Unsigned 32-bit state
+ * @returns {[number, number]} a number in [0, 1) and the next state
+ */
+export function step(state) {
+  const next = (state + 0x6d2b79f5) >>> 0;
+  let t = next;
+  t = Math.imul(t ^ (t >>> 15), t | 1);
+  t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+  return [((t ^ (t >>> 14)) >>> 0) / 4294967296, next];
+}
+
+/**
+ * A random permutation (Fisher-Yates) of a sequence.
+ * @param {Array} items
+ * @param {number} state
+ * @returns {Array}
+ */
+function permute(items, state) {
+  const result = [...items];
+  let s = state;
+  for (let i = result.length - 1; i > 0; i--) {
+    const [r, next] = step(s);
+    s = next;
+    const j = Math.floor(r * (i + 1));
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}
+
+const NEXT = {
+  params: [],
+  returns: sequenceTypeOf("map(xs:string, item())"),
+};
+const PERMUTE = {
+  params: [sequenceTypeOf("item()*")],
+  returns: sequenceTypeOf("item()*"),
+};
+
+/**
+ * The generator map of a state.
+ * @param {number} state
+ * @returns {XdmMap}
+ */
+export function generator(state) {
+  const [number, next] = step(state);
+  return XdmMap.from([
+    [stringItem("number"), [doubleItem(number)]],
+    [
+      stringItem("next"),
+      [
+        new FunctionItem({
+          arity: 0,
+          signature: NEXT,
+          invoke: () => [generator(next)],
+        }),
+      ],
+    ],
+    [
+      stringItem("permute"),
+      [
+        new FunctionItem({
+          arity: 1,
+          signature: PERMUTE,
+          invoke: ([items]) => permute(items, hashSeed(`p${next}`)),
+        }),
+      ],
+    ],
+  ]);
+}
+
+/**
+ * The seed of an optional atomic value.
+ * @param {Array} seed
+ * @param {object} context - Gives the current date and time
+ * @returns {number}
+ */
+const seedOf = (seed, context) =>
+  hashSeed(
+    seed.length
+      ? `${seed[0].type.primitive.localName}:${canonicalString(seed[0])}`
+      : formatDateTime("dateTime", context.currentDateTime),
+  );
+
+/** Function definitions. */
+export const randomFunctions = [
+  define("random-number-generator", [], "map(xs:string, item())", (_, c) => [
+    generator(seedOf([], c)),
+  ]),
+  define(
+    "random-number-generator",
+    ["xs:anyAtomicType?"],
+    "map(xs:string, item())",
+    ([seed], c) => [generator(seedOf(seed, c))],
+  ),
+];

package/src/functions/regex/analyzeString.js

@@ -0,0 +1,144 @@
+/**
+ * fn:analyze-string (F&O 3.1 section 5.6.6).
+ *
+ * The result is computed as a plain tree, `{ name, attributes, children }`
+ * with string children for text, and then built as DOM nodes through the
+ * dynamic context hook `context.createDocument()`, which must return an
+ * empty DOM Document (createElementNS, createTextNode, setAttribute and
+ * appendChild are used). The element is appended to that document, as
+ * its document element, and returned. Without the hook the plain tree is
+ * returned as is.
+ *
+ * @module @tradik/xslt3/functions/regex/analyzeString
+ */
+
+import { define, FN_NAMESPACE, stringArg } from "../support.js";
+import { allMatches, compileRegex, rejectEmptyMatch } from "./compile.js";
+
+/**
+ * @typedef {object} ResultElement
+ * @property {string} name - Local name in the fn namespace
+ * @property {Record<string, string>} attributes
+ * @property {Array<ResultElement|string>} children
+ */
+
+/** @returns {ResultElement} */
+const element = (name, children, attributes = {}) => ({
+  name,
+  attributes,
+  children,
+});
+
+/**
+ * Children of a match or group: text and the nested groups.
+ * @param {RegExpExecArray} match - With indices
+ * @param {import("./compile.js").CompiledRegex} compiled
+ * @param {number} parent - Group number, 0 for the whole match
+ * @param {[number, number]} range - Offsets of the parent in the input
+ * @returns {Array<ResultElement|string>}
+ */
+function groupChildren(match, compiled, parent, [start, end]) {
+  const input = match.input;
+  const children = [];
+  let position = start;
+  for (let group = 1; group <= compiled.groups; group++) {
+    const span = match.indices[group];
+    // a group of an earlier iteration of a repeated parent lies outside it
+    if (
+      compiled.parents[group] !== parent ||
+      span === undefined ||
+      span[0] < position ||
+      span[1] > end
+    ) {
+      continue;
+    }
+    if (span[0] > position) children.push(input.slice(position, span[0]));
+    children.push(
+      element("group", groupChildren(match, compiled, group, span), {
+        nr: String(group),
+      }),
+    );
+    position = span[1];
+  }
+  if (position < end) children.push(input.slice(position, end));
+  return children;
+}
+
+/**
+ * The fn:analyze-string-result tree of a string.
+ * @param {string} input
+ * @param {string} pattern
+ * @param {string} [flags=""]
+ * @returns {ResultElement}
+ * @throws {XPathError} FORX0001, FORX0002, FORX0003
+ */
+export function analyzeStringTree(input, pattern, flags = "") {
+  const compiled = compileRegex(pattern, flags);
+  rejectEmptyMatch(compiled);
+  const children = [];
+  let last = 0;
+  for (const match of allMatches(compiled, input)) {
+    if (match.index > last) {
+      children.push(element("non-match", [input.slice(last, match.index)]));
+    }
+    children.push(
+      element("match", groupChildren(match, compiled, 0, match.indices[0])),
+    );
+    last = match.index + match[0].length;
+  }
+  if (last < input.length) {
+    children.push(element("non-match", [input.slice(last)]));
+  }
+  return element("analyze-string-result", children);
+}
+
+/**
+ * Builds a result tree as DOM nodes.
+ * @param {ResultElement} tree
+ * @param {Document} doc
+ * @returns {Element}
+ */
+export function toDom(tree, doc) {
+  const node = doc.createElementNS(FN_NAMESPACE, tree.name);
+  for (const [name, value] of Object.entries(tree.attributes)) {
+    node.setAttribute(name, value);
+  }
+  for (const child of tree.children) {
+    node.appendChild(
+      typeof child === "string" ? doc.createTextNode(child) : toDom(child, doc),
+    );
+  }
+  return node;
+}
+
+/**
+ * fn:analyze-string implementation.
+ * @param {Array<*>[]} args - [$input, $pattern, $flags?]
+ * @param {{createDocument?: () => Document}} context
+ * @returns {Array<*>}
+ */
+function analyzeString([input, [pattern], flags], context) {
+  const tree = analyzeStringTree(
+    stringArg(input),
+    pattern.value,
+    flags === undefined ? "" : flags[0].value,
+  );
+  const doc = context.createDocument?.();
+  if (!doc) return [tree];
+  const root = toDom(tree, doc);
+  doc.appendChild(root);
+  return [root];
+}
+
+const RESULT = "element(fn:analyze-string-result)";
+
+/** @type {import("../support.js").FunctionDefinition[]} */
+export const analyzeStringFunctions = [
+  define("analyze-string", ["xs:string?", "xs:string"], RESULT, analyzeString),
+  define(
+    "analyze-string",
+    ["xs:string?", "xs:string", "xs:string"],
+    RESULT,
+    analyzeString,
+  ),
+];

package/src/functions/regex/charClass.js

@@ -0,0 +1,112 @@
+/**
+ * Character classes of XPath regular expressions (XSD 1.1
+ * Part 2 appendix G with the F&O 3.1 section 5.6.1 extensions), translated
+ * to JavaScript `u`-mode syntax.
+ *
+ * A class item is either `{ set }`, text that fits inside a JS `[...]`
+ * (characters, ranges, `\p{..}`), or `{ atom }`, a standalone JS
+ * expression matching one character (used for negated sets such as `\w`
+ * and `\I`, which cannot be nested in a JS class). Single characters also
+ * carry `char`, their codepoint, so they can start or end a range.
+ * Subtraction `[a-z-[aeiou]]` and negated mixtures become a negative
+ * lookahead in the generated expression: `(?:(?![aeiou])[a-z])`.
+ *
+ * @module @tradik/xslt3/functions/regex/charClass
+ */
+
+import { jsChar, parseEscape, regexError } from "./escapes.js";
+
+/**
+ * One class character: an escape or a literal character. An unescaped
+ * "-" is a literal at the start or end of the group and right after a
+ * range (as in [a-c-x], XSD 1.1); it then cannot start a range.
+ * @param {import("./reader.js").RegexReader} reader
+ * @param {boolean} hyphenAllowed - First item, or after a range
+ * @returns {{set?: string, atom?: string, char?: number, hyphen?: boolean}}
+ */
+function classChar(reader, hyphenAllowed) {
+  const c = reader.next();
+  if (c === "\\") return parseEscape(reader);
+  if (c === "[") regexError("unescaped [ in a character class");
+  const cp = c.codePointAt(0);
+  if (c === "-" && reader.peek() !== "]") {
+    if (!hyphenAllowed) regexError("misplaced - in a character class");
+    return { char: cp, set: jsChar(cp), hyphen: true };
+  }
+  return { char: cp, set: jsChar(cp) };
+}
+
+/**
+ * A JS expression matching one character of any of the items.
+ * @param {Array<{set?: string, atom?: string}>} items
+ * @param {boolean} negated
+ * @returns {string}
+ */
+function itemsToAtom(items, negated) {
+  const set = items.map((item) => item.set ?? "").join("");
+  const atoms = items.filter((item) => item.set === undefined);
+  if (atoms.length === 0) return `[${negated ? "^" : ""}${set}]`;
+  const alternatives = (set ? [`[${set}]`] : []).concat(
+    atoms.map((item) => item.atom),
+  );
+  const positive =
+    alternatives.length === 1
+      ? alternatives[0]
+      : `(?:${alternatives.join("|")})`;
+  return negated ? `(?:(?!${positive})[^])` : positive;
+}
+
+/**
+ * Parses a character class expression; the reader is after its "[".
+ * @param {import("./reader.js").RegexReader} reader
+ * @returns {string} JS expression matching one character
+ * @throws {XPathError} FORX0002 for invalid classes
+ */
+export function parseCharClass(reader) {
+  const negated = reader.peek() === "^";
+  if (negated) reader.next();
+  const items = [];
+  let subtraction = null;
+  for (;;) {
+    const c = reader.peek();
+    if (c === undefined) regexError("unterminated character class");
+    if (items.length > 0 && c === "-" && reader.peek(1) === "[") {
+      reader.next();
+      reader.next();
+      subtraction = parseCharClass(reader);
+      if (reader.next() !== "]") regexError("expected ] after subtraction");
+      break;
+    }
+    if (c === "]") {
+      reader.next();
+      if (items.length === 0) regexError("empty character class");
+      break;
+    }
+    const item = classChar(
+      reader,
+      items.length === 0 || items.at(-1).range === true,
+    );
+    const next = reader.peek(1);
+    if (
+      item.char === undefined ||
+      (item.hyphen && items.length > 0) ||
+      reader.peek() !== "-" ||
+      next === "]"
+    ) {
+      items.push(item);
+      continue;
+    }
+    if (next === "[" || next === undefined) {
+      items.push(item);
+      continue;
+    }
+    reader.next();
+    const end = classChar(reader, false);
+    if (end.char === undefined || end.char < item.char) {
+      regexError("invalid character range");
+    }
+    items.push({ set: `${item.set}-${end.set}`, range: true });
+  }
+  const atom = itemsToAtom(items, negated);
+  return subtraction === null ? atom : `(?:(?!${subtraction})${atom})`;
+}

package/src/functions/regex/compile.js

@@ -0,0 +1,81 @@
+/**
+ * Compilation of XPath regular expressions to cached JS RegExp objects.
+ *
+ * @module @tradik/xslt3/functions/regex/compile
+ */
+
+import { XPathError } from "../../errors.js";
+import { regexError } from "./escapes.js";
+import { translateRegex } from "./translate.js";
+
+/** Maximum number of compiled expressions kept. */
+const CACHE_SIZE = 256;
+const cache = new Map();
+
+/**
+ * @typedef {import("./translate.js").TranslatedRegex & {
+ *   regex: RegExp, literal: boolean}} CompiledRegex
+ * `regex` has the `g` and `d` flags; `literal` is true for the q flag.
+ */
+
+/**
+ * Translates and compiles a pattern, reusing earlier compilations.
+ * @param {string} pattern
+ * @param {string} [flags=""]
+ * @returns {CompiledRegex}
+ * @throws {XPathError} FORX0001, FORX0002
+ */
+export function compileRegex(pattern, flags = "") {
+  const key = `${flags}\u0000${pattern}`;
+  let compiled = cache.get(key);
+  if (compiled === undefined) {
+    const translated = translateRegex(pattern, flags);
+    let regex;
+    // the translator only emits valid syntax: the catch is a safety net
+    try {
+      regex = new RegExp(translated.source, `${translated.flags}gd`);
+      /* node:coverage ignore next 3 */
+    } catch (error) {
+      regexError(error.message);
+    }
+    compiled = { ...translated, regex, literal: flags.includes("q") };
+    if (cache.size >= CACHE_SIZE) cache.clear();
+    cache.set(key, compiled);
+  }
+  return compiled;
+}
+
+/**
+ * All matches of a compiled expression in a string, left to right.
+ * @param {CompiledRegex} compiled
+ * @param {string} input
+ * @returns {RegExpExecArray[]} with `indices`
+ */
+export function allMatches(compiled, input) {
+  compiled.regex.lastIndex = 0;
+  return Array.from(input.matchAll(compiled.regex));
+}
+
+/**
+ * Whether a compiled expression matches somewhere in a string.
+ * @param {CompiledRegex} compiled
+ * @param {string} input
+ * @returns {boolean}
+ */
+export function testRegex(compiled, input) {
+  compiled.regex.lastIndex = 0;
+  return compiled.regex.test(input);
+}
+
+/**
+ * @param {CompiledRegex} compiled
+ * @throws {XPathError} FORX0003 when the expression matches ""
+ */
+export function rejectEmptyMatch(compiled) {
+  if (testRegex(compiled, "")) {
+    throw new XPathError(
+      "FORX0003",
+      "The regular expression matches a zero-length string",
+    );
+  }
+}

package/src/functions/regex/escapes.js

@@ -0,0 +1,109 @@
+/**
+ * Escapes of XPath regular expressions (XSD 1.1 Part 2 appendix G and F&O
+ * 3.1 section 5.6.1): single-character escapes, multi-character escapes
+ * (\s \d \w \i \c and their complements) and \p{..}/\P{..} category and
+ * block escapes, as items for charClass.js and parser.js.
+ *
+ * @module @tradik/xslt3/functions/regex/escapes
+ */
+
+import { XPathError } from "../../errors.js";
+import { namePatterns } from "../../xdm/types.js";
+import { blockRanges } from "./unicodeBlocks.js";
+
+/**
+ * @param {string} message
+ * @returns {never}
+ * @throws {XPathError} FORX0002
+ */
+export function regexError(message) {
+  throw new XPathError("FORX0002", `Invalid regular expression: ${message}`);
+}
+
+/**
+ * A codepoint as JS regular expression text, valid inside and outside a
+ * class in `u` mode.
+ * @param {number} cp
+ * @returns {string}
+ */
+export function jsChar(cp) {
+  const char = String.fromCodePoint(cp);
+  return /[A-Za-z0-9_]/.test(char) ? char : `\\u{${cp.toString(16)}}`;
+}
+
+// NameStartChar and NameChar of XML 1.0 fifth edition, with ":"
+const [, NAME_START, NAME_CHAR] = /^\^\[(.+?)\]\[(.+)\]\*\$$/.exec(
+  namePatterns.name.source,
+);
+const SPACE = "\\u{9}\\u{a}\\u{d}\\u{20}";
+
+/** Multi-character escapes (XSD G.4.2.4 and XML name escapes). */
+const multiEscapes = {
+  s: { set: SPACE },
+  S: { atom: `[^${SPACE}]` },
+  d: { set: "\\p{Nd}" },
+  D: { set: "\\P{Nd}" },
+  w: { atom: "[^\\p{P}\\p{Z}\\p{C}]" },
+  W: { set: "\\p{P}\\p{Z}\\p{C}" },
+  i: { set: NAME_START },
+  I: { atom: `[^${NAME_START}]` },
+  c: { set: NAME_CHAR },
+  C: { atom: `[^${NAME_CHAR}]` },
+};
+
+/** Characters after "\" that stand for themselves (plus n, r, t). */
+const singleEscapes = new Set([..."\\|.?*+(){}-[]^$"]);
+const controlEscapes = { n: 0xa, r: 0xd, t: 0x9 };
+
+const categories = new Set(
+  (
+    "L Lu Ll Lt Lm Lo M Mn Mc Me N Nd Nl No P Pc Pd Ps Pe Pi Pf Po " +
+    "Z Zs Zl Zp S Sm Sc Sk So C Cc Cf Co Cn"
+  ).split(" "),
+);
+
+/**
+ * The item of `\p{name}` or `\P{name}` (the reader is after "p" or "P").
+ * @param {import("./reader.js").RegexReader} reader
+ * @param {boolean} negated - For `\P`
+ * @returns {{set?: string, atom?: string}}
+ */
+function categoryEscape(reader, negated) {
+  if (reader.next() !== "{") regexError("expected { after \\p");
+  let name = "";
+  while (reader.peek() !== undefined && reader.peek() !== "}") {
+    name += reader.next();
+  }
+  if (reader.next() !== "}") regexError("unterminated \\p{");
+  if (categories.has(name)) {
+    const set = `\\${negated ? "P" : "p"}{${name}}`;
+    // with the i flag a category still matches by its own case
+    return reader.caseless ? { atom: `(?-i:[${set}])` } : { set };
+  }
+  const ranges = name.startsWith("Is") && blockRanges(name.slice(2));
+  if (!ranges) regexError(`unknown category or block \\p{${name}}`);
+  const set = ranges
+    .map(([from, to]) => `${jsChar(from)}-${jsChar(to)}`)
+    .join("");
+  return negated ? { atom: `[^${set}]` } : { set };
+}
+
+/**
+ * Parses an escape after its backslash (not a back-reference).
+ * @param {import("./reader.js").RegexReader} reader
+ * @returns {{set?: string, atom?: string, char?: number}}
+ * @throws {XPathError} FORX0002 for unknown escapes
+ */
+export function parseEscape(reader) {
+  const c = reader.next();
+  if (c === undefined) regexError("trailing backslash");
+  if (singleEscapes.has(c)) {
+    return { char: c.codePointAt(0), set: jsChar(c.codePointAt(0)) };
+  }
+  if (c in controlEscapes) {
+    return { char: controlEscapes[c], set: jsChar(controlEscapes[c]) };
+  }
+  if (Object.hasOwn(multiEscapes, c)) return multiEscapes[c];
+  if (c === "p" || c === "P") return categoryEscape(reader, c === "P");
+  return regexError(`unknown escape \\${c}`);
+}