@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/xpath/syntax/index.js

@@ -0,0 +1,44 @@
+/**
+ * XPath 3.1 syntax: the parser from expression text to an AST.
+ *
+ * ```js
+ * import { parseXPath } from "./xpath/syntax/index.js";
+ * parseXPath("for $x in 1 to 3 return $x * 2");
+ * // { type: "ForExpr", bindings: [...], returnExpr: {...}, start: 0, end: 30 }
+ * ```
+ *
+ * The node types are documented in ast.js and typeAst.js.
+ *
+ * @module @tradik/xslt3/xpath/syntax
+ */
+
+import { parseExpr } from "./expressions.js";
+import { TokenStream } from "./tokenStream.js";
+
+/** XPath versions the parser accepts as `xpathVersion`. */
+const VERSIONS = new Set(["3.1"]);
+
+/**
+ * Parses an XPath 3.1 expression.
+ *
+ * @param {string} expression - The expression text
+ * @param {object} [options] - Options
+ * @param {"3.1"} [options.xpathVersion] - Language version, "3.1" (the only
+ *   one so far). TODO: "2.0" / "3.0" could reject the newer constructs
+ *   (maps, arrays, `=>`, `!`, `||`, let, inline functions) here.
+ * @returns {import("./ast.js").Expr} The root of the AST
+ * @throws {import("../../errors.js").XPathError} XPST0003 on a syntax error
+ *   (the message gives the offset and an excerpt), XPTY0004 for a
+ *   processing-instruction() test whose string is not an NCName
+ * @throws {RangeError} For an unsupported `xpathVersion`
+ */
+export function parseXPath(expression, options = {}) {
+  const { xpathVersion = "3.1" } = options;
+  if (!VERSIONS.has(xpathVersion)) {
+    throw new RangeError(`Unsupported XPath version: ${xpathVersion}`);
+  }
+  const p = new TokenStream(String(expression), { xpathVersion });
+  const expr = parseExpr(p);
+  if (p.peek().type !== "eof") p.fail("Unexpected token");
+  return expr;
+}

package/src/xpath/syntax/kindTests.js

@@ -0,0 +1,134 @@
+/**
+ * Parser of the XPath 3.1 kind tests, used both as node tests of axis steps
+ * and as item types: productions [83] KindTest to [100] TypeName of
+ * Appendix A.1.
+ *
+ * @module @tradik/xslt3/xpath/syntax/kindTests
+ */
+
+import { makeNode } from "./ast.js";
+import { isNCName, normalizeSpace } from "./chars.js";
+import { isPlainName, qName } from "./tokenStream.js";
+
+/** @typedef {import("./tokenStream.js").TokenStream} TokenStream */
+
+/** Kind tests without arguments, by keyword. */
+const EMPTY_TESTS = {
+  node: "AnyKindTest",
+  text: "TextTest",
+  comment: "CommentTest",
+  "namespace-node": "NamespaceNodeTest",
+};
+
+/** Parsers of the kind tests with arguments, after the "(". */
+const TESTS_WITH_ARGUMENTS = {
+  "document-node": parseDocumentTestBody,
+  element: (p) => parseNamedTestBody(p, "ElementTest"),
+  attribute: (p) => parseNamedTestBody(p, "AttributeTest"),
+  "schema-element": (p) => ({
+    type: "SchemaElementTest",
+    name: qName(p.expectName()),
+  }),
+  "schema-attribute": (p) => ({
+    type: "SchemaAttributeTest",
+    name: qName(p.expectName()),
+  }),
+  "processing-instruction": parsePITestBody,
+};
+
+/**
+ * @param {import("./lexer.js").Token} token - Name token followed by "("
+ * @returns {boolean} Whether the name is the keyword of a kind test
+ */
+export function isKindTestName(token) {
+  return (
+    isPlainName(token) &&
+    (Object.hasOwn(EMPTY_TESTS, token.local) ||
+      Object.hasOwn(TESTS_WITH_ARGUMENTS, token.local))
+  );
+}
+
+/**
+ * KindTest, e.g. `element(*, xs:untyped)` or `document-node(element(a))`.
+ * The caller has checked {@link isKindTestName}.
+ *
+ * @param {TokenStream} p - Tokens, at the keyword
+ * @returns {import("./typeAst.js").KindTest} The test
+ */
+export function parseKindTest(p) {
+  const keyword = p.next();
+  p.expectSymbol("(");
+  const emptyType = EMPTY_TESTS[keyword.local];
+  const { type, ...fields } = emptyType
+    ? { type: emptyType }
+    : TESTS_WITH_ARGUMENTS[keyword.local](p);
+  const end = p.expectSymbol(")").end;
+  return makeNode(type, fields, keyword.start, end);
+}
+
+/**
+ * Inside `document-node(...)`: an optional element or schema-element test.
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {{type: string, elementTest: object|null}} Fields of the test
+ */
+function parseDocumentTestBody(p) {
+  let elementTest = null;
+  if (p.isKeyword("element") || p.isKeyword("schema-element")) {
+    elementTest = parseKindTest(p);
+  } else if (!p.isSymbol(")")) {
+    p.fail("Expected element(...) or schema-element(...)");
+  }
+  return { type: "DocumentTest", elementTest };
+}
+
+/**
+ * Inside `element(...)` or `attribute(...)`: (name | "*") ("," TypeName)?,
+ * plus a "?" (nillable) after the type name of an element test.
+ *
+ * @param {TokenStream} p - Tokens
+ * @param {"ElementTest"|"AttributeTest"} type - Test type
+ * @returns {object} Fields of the test
+ */
+function parseNamedTestBody(p, type) {
+  let name = null;
+  let typeName = null;
+  let nillable = false;
+  if (!p.isSymbol(")")) {
+    if (!p.acceptSymbol("*")) name = qName(p.expectName('a name or "*"'));
+    if (p.acceptSymbol(",")) {
+      typeName = qName(p.expectName("a type name"));
+      if (type === "ElementTest") nillable = Boolean(p.acceptSymbol("?"));
+    }
+  }
+  return type === "ElementTest"
+    ? { type, name, typeName, nillable }
+    : { type, name, typeName };
+}
+
+/**
+ * Inside `processing-instruction(...)`: an NCName or a string literal, whose
+ * whitespace-normalized value must be an NCName (else XPTY0004).
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {{type: "PITest", target: string|null}} Fields of the test
+ */
+function parsePITestBody(p) {
+  const token = p.peek();
+  if (p.isSymbol(")")) return { type: "PITest", target: null };
+  if (token.type === "string") {
+    p.next();
+    const target = normalizeSpace(token.value);
+    if (!isNCName(target)) {
+      p.fail(
+        "Processing-instruction target is not an NCName",
+        token,
+        "XPTY0004",
+      );
+    }
+    return { type: "PITest", target };
+  }
+  if (!isPlainName(token)) p.fail("Expected an NCName or a string literal");
+  p.next();
+  return { type: "PITest", target: token.local };
+}

package/src/xpath/syntax/lexer.js

@@ -0,0 +1,220 @@
+/**
+ * XPath 3.1 lexer (XPath 3.1 Appendix A.2, lexical structure).
+ *
+ * Keywords are not reserved in XPath, so the lexer does not know them: `div`,
+ * `for` or `union` come out as name tokens and the parser decides from the
+ * context whether a name is an operator, a keyword or a name test. Names
+ * follow maximal munch, so `a-b` is one name while `a - b` and `a -b` are a
+ * subtraction (A.2.2). Comments `(: ... :)`, which nest, count as whitespace.
+ *
+ * @module @tradik/xslt3/xpath/syntax/lexer
+ */
+
+import {
+  NAME_START_CHAR,
+  NCNAME,
+  NUMBER,
+  WHITESPACE,
+  matchAt,
+  normalizeSpace,
+} from "./chars.js";
+import { syntaxError } from "./syntaxError.js";
+
+/**
+ * A token. `type` is "name" (NCName, QName or EQName: `prefix`, `local`,
+ * `uri`), "wildcard" (`prefix:*`, `*:local`, `Q{uri}*`; a bare `*` is the
+ * symbol "*"), "integer", "decimal", "double", "string" (`value` holds the
+ * lexical form of a number, the unescaped content of a string), "symbol"
+ * (`value` is the operator or punctuation) or "eof".
+ *
+ * @typedef {object} Token
+ * @property {"name"|"wildcard"|"integer"|"decimal"|"double"|"string"|"symbol"|"eof"} type
+ * @property {string} [value] - Symbol, literal content or numeric lexical form
+ * @property {string|null} [prefix] - Prefix of a name or wildcard
+ * @property {string|null} [local] - Local part of a name or wildcard
+ * @property {string|null} [uri] - Namespace of an EQName / `Q{uri}*`
+ * @property {number} start - Offset of the first character
+ * @property {number} end - Offset after the last character
+ */
+
+/** Symbols of two characters, tried before the single-character ones. */
+const LONG_SYMBOLS = new Set("!= <= >= << >> => || // :: := ..".split(" "));
+const SHORT_SYMBOLS = new Set("!#$()*+,-./:<=>?@[]{}|");
+
+/** Tokenizer over one expression; use {@link tokenize}. */
+class Lexer {
+  /** @param {string} source - The expression */
+  constructor(source) {
+    this.source = source;
+    this.pos = 0;
+  }
+
+  /** @returns {never} Throws XPST0003 at the current offset. */
+  fail(message, offset = this.pos) {
+    throw syntaxError(this.source, offset, message);
+  }
+
+  /** Skips whitespace and (nested) comments. */
+  skipIgnorable() {
+    for (;;) {
+      const space = matchAt(WHITESPACE, this.source, this.pos);
+      if (space) this.pos += space.length;
+      else if (this.source.startsWith("(:", this.pos)) this.skipComment();
+      else return;
+    }
+  }
+
+  /** Skips one comment, which may contain nested comments. */
+  skipComment() {
+    const start = this.pos;
+    let depth = 0;
+    do {
+      if (this.pos >= this.source.length) this.fail("Unclosed comment", start);
+      if (this.source.startsWith("(:", this.pos)) {
+        depth++;
+        this.pos += 2;
+      } else if (this.source.startsWith(":)", this.pos)) {
+        depth--;
+        this.pos += 2;
+      } else this.pos++;
+    } while (depth > 0);
+  }
+
+  /** @returns {Token} The next token (eof at the end). */
+  next() {
+    this.skipIgnorable();
+    const { source, pos } = this;
+    const char = source[pos];
+    if (pos >= source.length) return { type: "eof", start: pos, end: pos };
+    if (char === '"' || char === "'") return this.string(char);
+    if (matchAt(NUMBER, source, pos)) return this.number();
+    if (source.startsWith("Q{", pos)) return this.bracedName();
+    if (matchAt(NCNAME, source, pos)) return this.name();
+    if (char === "*" && source[pos + 1] === ":") {
+      const local = matchAt(NCNAME, source, pos + 2);
+      if (local) {
+        return this.named(
+          "wildcard",
+          null,
+          local,
+          null,
+          pos + 2 + local.length,
+        );
+      }
+    }
+    const pair = source.slice(pos, pos + 2);
+    if (LONG_SYMBOLS.has(pair)) {
+      return this.token("symbol", { value: pair }, pos + 2);
+    }
+    if (SHORT_SYMBOLS.has(char)) {
+      return this.token("symbol", { value: char }, pos + 1);
+    }
+    return this.fail(`Unexpected character ${JSON.stringify(char)}`);
+  }
+
+  /** @returns {Token} A token from the current offset to `end`. */
+  token(type, fields, end) {
+    const token = Object.assign({ type }, fields);
+    token.start = this.pos;
+    token.end = end;
+    this.pos = end;
+    return token;
+  }
+
+  /** @returns {Token} A string literal; `""` / `''` stand for one quote. */
+  string(quote) {
+    let value = "";
+    let at = this.pos + 1;
+    for (;;) {
+      const close = this.source.indexOf(quote, at);
+      if (close < 0) this.fail("Unterminated string literal");
+      value += this.source.slice(at, close);
+      if (this.source[close + 1] !== quote) {
+        return this.token("string", { value }, close + 1);
+      }
+      value += quote;
+      at = close + 2;
+    }
+  }
+
+  /** @returns {Token} A numeric literal, keeping its lexical form. */
+  number() {
+    const text = matchAt(NUMBER, this.source, this.pos);
+    const end = this.pos + text.length;
+    // A.2.2: a numeric literal must not run into a name ("10div") or into
+    // another numeric literal ("1.2.3").
+    if (
+      matchAt(NAME_START_CHAR, this.source, end) ||
+      matchAt(NUMBER, this.source, end)
+    ) {
+      this.fail("Numeric literal followed by a name or number", end);
+    }
+    let type = "integer";
+    if (/[eE]/.test(text)) type = "double";
+    else if (text.includes(".")) type = "decimal";
+    return this.token(type, { value: text }, end);
+  }
+
+  /**
+   * @param {"name"|"wildcard"} type - Token type
+   * @param {string|null} prefix - Prefix
+   * @param {string|null} local - Local name
+   * @param {string|null} uri - Braced URI
+   * @param {number} end - Offset after the token
+   * @returns {Token} A name or wildcard token
+   */
+  named(type, prefix, local, uri, end) {
+    return this.token(type, { prefix, local, uri }, end);
+  }
+
+  /** @returns {Token} `Q{uri}local` or `Q{uri}*`. */
+  bracedName() {
+    const close = this.source.indexOf("}", this.pos + 2);
+    const open = this.source.indexOf("{", this.pos + 2);
+    if (close < 0 || (open >= 0 && open < close)) {
+      this.fail("Malformed braced URI literal");
+    }
+    // The namespace is whitespace-normalized like an xs:anyURI.
+    const uri = normalizeSpace(this.source.slice(this.pos + 2, close));
+    if (this.source[close + 1] === "*") {
+      return this.named("wildcard", null, null, uri, close + 2);
+    }
+    const local = matchAt(NCNAME, this.source, close + 1);
+    if (!local) this.fail("Expected a local name", close + 1);
+    return this.named("name", null, local, uri, close + 1 + local.length);
+  }
+
+  /** @returns {Token} An NCName, a QName or a `prefix:*` wildcard. */
+  name() {
+    const first = matchAt(NCNAME, this.source, this.pos);
+    const end = this.pos + first.length;
+    if (this.source[end] === ":") {
+      const local = matchAt(NCNAME, this.source, end + 1);
+      if (local) {
+        return this.named("name", first, local, null, end + 1 + local.length);
+      }
+      if (this.source[end + 1] === "*") {
+        return this.named("wildcard", first, null, null, end + 2);
+      }
+    }
+    return this.named("name", null, first, null, end);
+  }
+}
+
+/**
+ * Splits an expression into tokens, comments and whitespace removed.
+ *
+ * @param {string} source - XPath expression
+ * @returns {Token[]} The tokens, the last one of type "eof"
+ * @throws {import("../../errors.js").XPathError} XPST0003 on a lexical error
+ */
+export function tokenize(source) {
+  const lexer = new Lexer(source);
+  const tokens = [];
+  let token;
+  do {
+    token = lexer.next();
+    tokens.push(token);
+  } while (token.type !== "eof");
+  return tokens;
+}

package/src/xpath/syntax/operators.js

@@ -0,0 +1,111 @@
+/**
+ * Parser of the XPath 3.1 binary operator expressions, from `or` (lowest
+ * precedence) down to `intersect`/`except`: productions [8] OrExpr to [24]
+ * IntersectExceptExpr of Appendix A.1. The levels below (instance of ... !)
+ * are in typeOperators.js.
+ *
+ * Operator keywords are recognised only here, in operator position, so
+ * `div div div` divides the child element `div` by itself.
+ *
+ * @module @tradik/xslt3/xpath/syntax/operators
+ */
+
+import { makeNode } from "./ast.js";
+import { parseInstanceofExpr } from "./typeOperators.js";
+
+/** @typedef {import("./tokenStream.js").TokenStream} TokenStream */
+/** @typedef {import("./ast.js").Expr} Expr */
+
+/** Kind of each comparison operator (ComparisonExpr.kind). */
+const COMPARISON_KINDS = {
+  ...Object.fromEntries(
+    "= != < <= > >=".split(" ").map((op) => [op, "general"]),
+  ),
+  ...Object.fromEntries(
+    "eq ne lt le gt ge".split(" ").map((op) => [op, "value"]),
+  ),
+  ...Object.fromEntries("is << >>".split(" ").map((op) => [op, "node"])),
+};
+
+/** Operators stored under another name. */
+const ALIASES = { "|": "union" };
+
+/**
+ * Builds the parser of one binary precedence level. Each operator may be
+ * a symbol or a keyword; both are tried, as names and symbols never clash.
+ *
+ * @param {string} type - Node type
+ * @param {string} operators - Space-separated operators of the level
+ * @param {(p: TokenStream) => Expr} operand - Parser of the next level
+ * @param {object} [options] - Level options
+ * @param {boolean} [options.chain] - Left-associative; false allows at most
+ *   one operator (comparisons and `to` are non-associative)
+ * @param {boolean} [options.withOperator] - Store the operator in the node
+ * @returns {(p: TokenStream) => Expr} Parser of the level
+ */
+export function binaryLevel(type, operators, operand, options = {}) {
+  const { chain = true, withOperator = true } = options;
+  const spellings = operators.split(" ");
+  const match = (p) =>
+    spellings.find((op) => p.acceptSymbol(op) || p.acceptKeyword(op));
+  return (p) => {
+    let left = operand(p);
+    let spelling;
+    while ((spelling = match(p))) {
+      const right = operand(p);
+      const operator = ALIASES[spelling] ?? spelling;
+      const kind = COMPARISON_KINDS[operator];
+      const fields = withOperator ? { operator, left, right } : { left, right };
+      const node = kind ? { kind, ...fields } : fields;
+      left = makeNode(type, node, left.start, right.end);
+      if (!chain) break;
+    }
+    return left;
+  };
+}
+
+const parseIntersectExceptExpr = binaryLevel(
+  "SetExpr",
+  "intersect except",
+  parseInstanceofExpr,
+);
+const parseUnionExpr = binaryLevel(
+  "SetExpr",
+  "union |",
+  parseIntersectExceptExpr,
+);
+const parseMultiplicativeExpr = binaryLevel(
+  "ArithmeticExpr",
+  "* div idiv mod",
+  parseUnionExpr,
+);
+const parseAdditiveExpr = binaryLevel(
+  "ArithmeticExpr",
+  "+ -",
+  parseMultiplicativeExpr,
+);
+const parseRangeExpr = binaryLevel("RangeExpr", "to", parseAdditiveExpr, {
+  chain: false,
+  withOperator: false,
+});
+const parseStringConcatExpr = binaryLevel(
+  "StringConcatExpr",
+  "||",
+  parseRangeExpr,
+  { withOperator: false },
+);
+const parseComparisonExpr = binaryLevel(
+  "ComparisonExpr",
+  Object.keys(COMPARISON_KINDS).join(" "),
+  parseStringConcatExpr,
+  { chain: false },
+);
+const parseAndExpr = binaryLevel("LogicalExpr", "and", parseComparisonExpr);
+
+/**
+ * OrExpr ::= AndExpr ("or" AndExpr)*, the operator expression of lowest
+ * precedence and the entry point of this module.
+ *
+ * @type {(p: TokenStream) => Expr}
+ */
+export const parseOrExpr = binaryLevel("LogicalExpr", "or", parseAndExpr);

package/src/xpath/syntax/paths.js

@@ -0,0 +1,102 @@
+/**
+ * Parser of XPath 3.1 path expressions: productions [36] PathExpr to [52]
+ * RelativePathExpr of Appendix A.1; the steps are parsed in steps.js.
+ *
+ * Leading-lone-slash constraint (A.1.2): a `/` followed by a token that can
+ * start a step is the start of a path, so `/ * 5` is `/*` followed by an
+ * unexpected `5`; `(/) * 5` multiplies the root.
+ *
+ * @module @tradik/xslt3/xpath/syntax/paths
+ */
+
+import { makeNode } from "./ast.js";
+import { parseStepExpr } from "./steps.js";
+
+/** @typedef {import("./tokenStream.js").TokenStream} TokenStream */
+/** @typedef {import("./ast.js").Expr} Expr */
+
+/** Symbols that can start a step (leading-lone-slash constraint). */
+const STEP_START_SYMBOLS = new Set(["*", "@", ".", "..", "$", "(", "?", "["]);
+const LITERAL_TOKENS = new Set([
+  "name",
+  "wildcard",
+  "integer",
+  "decimal",
+  "double",
+  "string",
+]);
+
+/**
+ * PathExpr ::= ("/" RelativePathExpr?) | ("//" RelativePathExpr) |
+ * RelativePathExpr
+ *
+ * @param {TokenStream} p - Tokens
+ * @returns {Expr} A PathExpr, or the step itself when there is no slash
+ */
+export function parsePathExpr(p) {
+  const slash = p.acceptSymbol("/");
+  if (slash) {
+    if (!startsStep(p)) {
+      return makeNode(
+        "PathExpr",
+        { absolute: true, steps: [] },
+        slash.start,
+        slash.end,
+      );
+    }
+    return continuePath(p, slash.start, true, [parseStepExpr(p)]);
+  }
+  const doubleSlash = p.acceptSymbol("//");
+  if (doubleSlash) {
+    const steps = [descendantOrSelfStep(doubleSlash), parseStepExpr(p)];
+    return continuePath(p, doubleSlash.start, true, steps);
+  }
+  const first = parseStepExpr(p);
+  if (!p.isSymbol("/") && !p.isSymbol("//")) return first;
+  return continuePath(p, first.start, false, [first]);
+}
+
+/**
+ * Reads the `("/" | "//") StepExpr` pairs that follow the first step.
+ *
+ * @param {TokenStream} p - Tokens
+ * @param {number} start - Offset of the path
+ * @param {boolean} absolute - Whether the path starts with a slash
+ * @param {Expr[]} steps - Steps read so far
+ * @returns {import("./ast.js").PathExpr} The path
+ */
+function continuePath(p, start, absolute, steps) {
+  let separator;
+  while ((separator = p.acceptSymbol("/") ?? p.acceptSymbol("//"))) {
+    if (separator.value === "//") steps.push(descendantOrSelfStep(separator));
+    steps.push(parseStepExpr(p));
+  }
+  return makeNode("PathExpr", { absolute, steps }, start, steps.at(-1).end);
+}
+
+/**
+ * @param {TokenStream} p - Tokens
+ * @returns {boolean} Whether the current token can start a StepExpr
+ */
+function startsStep(p) {
+  const token = p.peek();
+  return token.type === "symbol"
+    ? STEP_START_SYMBOLS.has(token.value)
+    : LITERAL_TOKENS.has(token.type);
+}
+
+/**
+ * The step `descendant-or-self::node()` that `//` stands for.
+ *
+ * @param {import("./lexer.js").Token} token - The `//` token
+ * @returns {import("./ast.js").AxisStep} The step
+ */
+function descendantOrSelfStep(token) {
+  const nodeTest = makeNode("AnyKindTest", {}, token.start, token.end);
+  return makeNode(
+    "AxisStep",
+    { axis: "descendant-or-self", nodeTest, predicates: [] },
+    token.start,
+    token.end,
+  );
+}