@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/serialize/output/encoding.js

@@ -0,0 +1,146 @@
+/**
+ * Output encodings: which characters an encoding can represent (the others
+ * are written as character references, or are an error where references
+ * are not possible) and the conversion of the serialized string to bytes.
+ *
+ * Supported: UTF-8, UTF-16 (big-endian, or UTF-16BE/UTF-16LE), ISO-8859-1,
+ * US-ASCII, and the single-byte encodings of the WHATWG Encoding Standard
+ * that the platform's TextDecoder knows (windows-1252, ISO-8859-2, KOI8-R,
+ * ...). Other encodings are a SESU0007 error.
+ *
+ * @module @tradik/xslt3/serialize/output/encoding
+ */
+
+import { XPathError } from "../../errors.js";
+
+/**
+ * @typedef {object} Encoding
+ * @property {string} name - The name as requested (written in the XML
+ *   declaration and the HTML content type)
+ * @property {string} kind - "utf-8", "utf-16be", "utf-16le" or "single-byte"
+ * @property {((codePoint: number) => boolean)|null} encodable - null when
+ *   every character can be encoded
+ * @property {Map<number, number>} [table] - Code point to byte
+ */
+
+const ALIASES = {
+  "utf-8": "utf-8",
+  utf8: "utf-8",
+  "utf-16": "utf-16be",
+  utf16: "utf-16be",
+  "utf-16be": "utf-16be",
+  "utf-16le": "utf-16le",
+  "iso-8859-1": "latin1",
+  iso_8859_1: "latin1",
+  "iso_8859-1": "latin1",
+  latin1: "latin1",
+  l1: "latin1",
+  "us-ascii": "ascii",
+  ascii: "ascii",
+  "iso-646": "ascii",
+};
+
+/** Canonical names of the WHATWG single-byte encodings. */
+const SINGLE_BYTE = new Set([
+  "ibm866",
+  "koi8-r",
+  "koi8-u",
+  "macintosh",
+  "windows-874",
+  "x-mac-cyrillic",
+  ...[2, 3, 4, 5, 6, 7, 8, 10, 13, 14, 15, 16].map((n) => `iso-8859-${n}`),
+  ...[0, 1, 2, 3, 4, 5, 6, 7, 8].map((n) => `windows-125${n}`),
+]);
+
+/** What a decoder returns for a byte it does not map. */
+const REPLACEMENT_CHARACTER = String.fromCharCode(0xfffd);
+
+/** @type {Map<string, Map<number, number>>} tables by canonical name */
+const tables = new Map();
+
+/**
+ * Code point to byte table of a single-byte encoding, from the platform
+ * decoder.
+ * @param {string} canonical - Canonical WHATWG name
+ * @returns {Map<number, number>}
+ */
+function singleByteTable(canonical) {
+  let table = tables.get(canonical);
+  if (!table) {
+    const decoder = new globalThis.TextDecoder(canonical);
+    table = new Map();
+    for (let byte = 0; byte < 256; byte++) {
+      const char = decoder.decode(Uint8Array.of(byte));
+      if (char !== REPLACEMENT_CHARACTER) table.set(char.codePointAt(0), byte);
+    }
+    tables.set(canonical, table);
+  }
+  return table;
+}
+
+/**
+ * The canonical WHATWG name of an encoding label, or null.
+ * @param {string} label
+ * @returns {string|null}
+ */
+function whatwgName(label) {
+  try {
+    return new globalThis.TextDecoder(label).encoding;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolves the encoding parameter.
+ * @param {string} name - Encoding name, case-insensitive
+ * @returns {Encoding}
+ * @throws {XPathError} SESU0007 when the encoding is not supported
+ */
+export function resolveEncoding(name) {
+  const alias = ALIASES[name.trim().toLowerCase()];
+  if (alias === "latin1" || alias === "ascii") {
+    const limit = alias === "latin1" ? 0xff : 0x7f;
+    return { name, kind: "single-byte", encodable: (cp) => cp <= limit };
+  }
+  if (alias) return { name, kind: alias, encodable: null };
+  const canonical = whatwgName(name.trim());
+  if (canonical === null || !SINGLE_BYTE.has(canonical)) {
+    throw new XPathError("SESU0007", `Unsupported encoding ${name}`);
+  }
+  const table = singleByteTable(canonical);
+  return { name, kind: "single-byte", encodable: (cp) => table.has(cp), table };
+}
+
+/** U+FEFF, written first with byte-order-mark. */
+const BYTE_ORDER_MARK = String.fromCharCode(0xfeff);
+
+/**
+ * Encodes serialized text (already free of unencodable characters).
+ * @param {string} text
+ * @param {Encoding} encoding
+ * @param {boolean} byteOrderMark - Start with the byte order mark (UTF-8
+ *   and UTF-16 only)
+ * @returns {Uint8Array}
+ */
+export function encodeText(text, encoding, byteOrderMark) {
+  const { kind } = encoding;
+  const content =
+    byteOrderMark && kind !== "single-byte" ? BYTE_ORDER_MARK + text : text;
+  if (kind === "utf-8") return new globalThis.TextEncoder().encode(content);
+  if (kind === "single-byte") {
+    const bytes = new Uint8Array(content.length);
+    for (let i = 0; i < content.length; i++) {
+      const cp = content.charCodeAt(i);
+      bytes[i] = encoding.table ? encoding.table.get(cp) : cp;
+    }
+    return bytes;
+  }
+  const bytes = new Uint8Array(content.length * 2);
+  const view = new DataView(bytes.buffer);
+  const littleEndian = kind === "utf-16le";
+  for (let i = 0; i < content.length; i++) {
+    view.setUint16(i * 2, content.charCodeAt(i), littleEndian);
+  }
+  return bytes;
+}

package/src/serialize/output/expander.js

@@ -0,0 +1,204 @@
+/**
+ * Character expansion (Serialization 3.1 section 4, phase 2): character
+ * maps, Unicode normalization, escaping of the characters markup gives a
+ * meaning to, and character references for the characters the encoding
+ * cannot represent. A character replaced by a character map is written as
+ * it is mapped: it is neither normalized nor escaped.
+ *
+ * @module @tradik/xslt3/serialize/output/expander
+ */
+
+import { XPathError } from "../../errors.js";
+
+/**
+ * @param {number} codePoint
+ * @returns {string} a hexadecimal character reference, e.g. "é"
+ */
+export const characterReference = (codePoint) =>
+  `&#x${codePoint.toString(16).toUpperCase()};`;
+
+const NAMED = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" };
+
+/**
+ * Characters escaped in each context. XML escapes CR, NEL, LINE
+ * SEPARATOR, DEL and the C1 controls as references, attributes also tab
+ * and newline (which attribute value normalization would turn into
+ * spaces); the other C0 controls are only allowed, as references, in XML
+ * 1.1. HTML attributes keep "&{" (a script macro) and "<" unescaped.
+ */
+const C0 = "\\u0001-\\u0008\\u000B\\u000C\\u000E-\\u001F";
+const C1 = "\\u007F-\\u009F\\u2028";
+const PATTERNS = {
+  xmlText: `[&<>\\r${C0}${C1}]`,
+  xmlAttribute: `[&<>"\\t\\n\\r${C0}${C1}]`,
+  htmlText: "[&<>]",
+  htmlAttribute: '&(?!\\{)|"',
+};
+
+/** Expands characters for one serialization. */
+export class Expander {
+  /**
+   * @param {import("../params/settings.js").Settings} settings
+   */
+  constructor(settings) {
+    this.map = settings.useCharacterMaps;
+    this.form =
+      settings.normalizationForm === "none" ? null : settings.normalizationForm;
+    this.encodable = settings.encoding.encodable;
+    this.xml11 = settings.version === "1.1";
+    this.html = settings.method === "html";
+    const restricted = this.encodable ? "|[^\\u0000-\\u007F]" : "";
+    const compile = (name) => new RegExp(PATTERNS[name] + restricted, "gu");
+    this.textPattern = compile(this.html ? "htmlText" : "xmlText");
+    this.attributePattern = compile(
+      this.html ? "htmlAttribute" : "xmlAttribute",
+    );
+    this.replace = (char) => this.replacement(char);
+  }
+
+  /**
+   * The escaped form of a character matched by a pattern.
+   * @param {string} char
+   * @returns {string}
+   */
+  replacement(char) {
+    const named = NAMED[char];
+    if (named) return named;
+    const cp = char.codePointAt(0);
+    if (cp < 0x20 && cp !== 9 && cp !== 10 && cp !== 13 && !this.xml11) {
+      throw new XPathError(
+        "SERE0006",
+        `Character #x${cp.toString(16)} is not allowed in XML 1.0`,
+      );
+    }
+    if (cp < 0xa0 || cp === 0x2028 || !this.encodable(cp)) {
+      return characterReference(cp);
+    }
+    return char;
+  }
+
+  /**
+   * Splits text into the runs of unmapped characters (normalized and
+   * passed to `write`) and the replacements of mapped ones (kept as they
+   * are).
+   * @param {string} text
+   * @param {(run: string) => string} write - Expands an unmapped run
+   * @returns {string}
+   */
+  mapped(text, write) {
+    const expand = (run) => write(this.form ? run.normalize(this.form) : run);
+    if (!this.map) return expand(text);
+    let result = "";
+    let run = "";
+    for (const char of text) {
+      const replacement = this.map.get(char);
+      if (replacement === undefined) {
+        run += char;
+      } else {
+        if (run) result += expand(run);
+        result += replacement;
+        run = "";
+      }
+    }
+    return run ? result + expand(run) : result;
+  }
+
+  /**
+   * Checks the characters of HTML output (SERE0014: C1 controls).
+   * @param {string} text
+   */
+  checkHtml(text) {
+    if (this.html && /[\u007F-\u009F]/.test(text)) {
+      throw new XPathError(
+        "SERE0014",
+        "The HTML output method cannot write the characters #x7F to #x9F",
+      );
+    }
+  }
+
+  /**
+   * @param {string} text - Content of a text node
+   * @returns {string} escaped character data
+   */
+  text(text) {
+    this.checkHtml(text);
+    return this.mapped(text, (run) =>
+      run.replace(this.textPattern, this.replace),
+    );
+  }
+
+  /**
+   * @param {string} value - Attribute value
+   * @returns {string} the escaped value, to be written between quotes
+   */
+  attribute(value) {
+    this.checkHtml(value);
+    return this.mapped(value, (run) =>
+      run.replace(this.attributePattern, this.replace),
+    );
+  }
+
+  /**
+   * Text written as CDATA sections; a mapped or unencodable character
+   * ends the section, and "]]>" is split across two sections.
+   * @param {string} text
+   * @returns {string}
+   */
+  cdata(text) {
+    return this.mapped(text, (run) => {
+      let result = "";
+      let section = "";
+      const flush = () => {
+        if (section) {
+          const safe = section.replaceAll("]]>", "]]]]><![CDATA[>");
+          result += `<![CDATA[${safe}]]>`;
+        }
+        section = "";
+      };
+      for (const char of run) {
+        const cp = char.codePointAt(0);
+        if (this.encodable && !this.encodable(cp)) {
+          flush();
+          result += characterReference(cp);
+        } else {
+          section += char;
+        }
+      }
+      flush();
+      return result;
+    });
+  }
+
+  /**
+   * Text written without escaping (HTML script and style content, the
+   * text output method): character maps and normalization only.
+   * @param {string} text
+   * @returns {string}
+   * @throws {XPathError} SERE0008 for characters the encoding lacks
+   */
+  raw(text) {
+    this.checkHtml(text);
+    return this.mapped(text, (run) => this.unescaped(run));
+  }
+
+  /**
+   * Text written as it is, which must be encodable: names, comments,
+   * processing instructions, unescaped text.
+   * @param {string} text
+   * @returns {string}
+   * @throws {XPathError} SERE0008 for characters the encoding lacks
+   */
+  unescaped(text) {
+    if (this.encodable) {
+      for (const char of text) {
+        if (!this.encodable(char.codePointAt(0))) {
+          throw new XPathError(
+            "SERE0008",
+            `Character ${char} cannot be written in the output encoding`,
+          );
+        }
+      }
+    }
+    return text;
+  }
+}

package/src/serialize/params/fromElement.js

@@ -0,0 +1,141 @@
+/**
+ * Serialization parameters given as an `output:serialization-parameters`
+ * element (Serialization 3.1 section 3.1), as fn:serialize accepts them.
+ *
+ * Errors: XPTY0004 when the element is not output:serialization-parameters,
+ * SEPM0017 for an invalid element (unknown output:* parameter, element in
+ * no namespace, unknown attribute, invalid value), SEPM0018 for a
+ * character mapped twice, SEPM0019 for a parameter given twice. Elements
+ * in other namespaces are extension parameters, ignored.
+ *
+ * @module @tradik/xslt3/serialize/params/fromElement
+ */
+
+import { compareCodepoints } from "../../xdm/strings.js";
+import { XPathError } from "../../errors.js";
+import { isNamespaceDeclaration } from "../../xpath/eval/domNodes.js";
+import { inScopeNamespaces } from "../../xpath/eval/namespaceNodes.js";
+import { OUTPUT_NAMESPACE, PARAMETER_KINDS } from "./names.js";
+import { clarkName, CONVERTERS } from "./values.js";
+
+/**
+ * @param {string} message
+ * @returns {XPathError} SEPM0017
+ */
+const invalid = (message) => new XPathError("SEPM0017", message);
+
+/**
+ * @param {Element} element
+ * @returns {string[]} local names of its attributes in no namespace
+ */
+function plainAttributes(element) {
+  const names = [];
+  for (const attribute of element.attributes) {
+    if (!isNamespaceDeclaration(attribute) && !attribute.namespaceURI) {
+      names.push(attribute.localName ?? attribute.name);
+    }
+  }
+  return names;
+}
+
+/**
+ * @param {Element} element
+ * @returns {Element[]} its element children
+ */
+function elementChildren(element) {
+  const children = [];
+  for (let child = element.firstChild; child; child = child.nextSibling) {
+    if (child.nodeType === 1) children.push(child);
+  }
+  return children;
+}
+
+/**
+ * Reads the character map of output:use-character-maps.
+ * @param {Element} element
+ * @returns {Map<string, string>}
+ */
+function characterMap(element) {
+  const map = new Map();
+  for (const child of elementChildren(element)) {
+    const attributes = plainAttributes(child).sort(compareCodepoints).join(" ");
+    if (
+      child.namespaceURI !== OUTPUT_NAMESPACE ||
+      child.localName !== "character-map" ||
+      attributes !== "character map-string"
+    ) {
+      throw invalid("Invalid content of output:use-character-maps");
+    }
+    const character = child.getAttribute("character");
+    if ([...character].length !== 1) {
+      throw invalid(`Not a single character: ${character}`);
+    }
+    if (map.has(character)) {
+      throw new XPathError("SEPM0018", `Character ${character} mapped twice`);
+    }
+    map.set(character, child.getAttribute("map-string"));
+  }
+  return map;
+}
+
+/**
+ * Reads one parameter element.
+ * @param {Element} element - output:* parameter element
+ * @param {string} name - Its local name
+ * @returns {*} the converted value
+ */
+function parameterValue(element, name) {
+  const attributes = plainAttributes(element);
+  if (name === "use-character-maps") {
+    if (attributes.length) throw invalid(`Attributes on output:${name}`);
+    return characterMap(element);
+  }
+  if (attributes.join(" ") !== "value") {
+    throw invalid(`output:${name} needs exactly a value attribute`);
+  }
+  const value = element.getAttribute("value");
+  const bindings = inScopeNamespaces(element);
+  const resolve = (prefix) => bindings.get(prefix);
+  try {
+    return CONVERTERS[PARAMETER_KINDS[name]](name, value, resolve);
+  } catch (error) {
+    throw invalid(error.message);
+  }
+}
+
+/**
+ * Reads serialization parameters from an element.
+ * @param {Element} element - An output:serialization-parameters element
+ * @returns {Record<string, *>} parameters by hyphenated name
+ */
+export function parametersFromElement(element) {
+  if (
+    element.nodeType !== 1 ||
+    element.namespaceURI !== OUTPUT_NAMESPACE ||
+    element.localName !== "serialization-parameters"
+  ) {
+    throw new XPathError(
+      "XPTY0004",
+      "Serialization parameters must be an output:serialization-parameters element",
+    );
+  }
+  if (plainAttributes(element).length) {
+    throw invalid("Attributes on output:serialization-parameters");
+  }
+  const params = {};
+  const seen = new Set();
+  for (const child of elementChildren(element)) {
+    const namespace = child.namespaceURI ?? "";
+    const local = child.localName;
+    const key = clarkName(namespace, local);
+    if (seen.has(key)) {
+      throw new XPathError("SEPM0019", `Parameter ${local} given twice`);
+    }
+    seen.add(key);
+    if (namespace === "") throw invalid(`Parameter ${local} in no namespace`);
+    if (namespace !== OUTPUT_NAMESPACE) continue;
+    if (!PARAMETER_KINDS[local]) throw invalid(`Unknown parameter ${local}`);
+    params[local] = parameterValue(child, local);
+  }
+  return params;
+}

package/src/serialize/params/fromMap.js

@@ -0,0 +1,128 @@
+/**
+ * Serialization parameters given as a map (F&O 3.1 section 14.6.3): the
+ * keys are parameter names (xs:string), the values are converted to the
+ * type of each parameter with the function conversion rules (XPTY0004
+ * when they do not fit). Entries with other keys (QNames, unknown names)
+ * are ignored.
+ *
+ * | Kind         | Type                       |
+ * |--------------|----------------------------|
+ * | boolean      | xs:boolean?                |
+ * | string       | xs:string?                 |
+ * | decimal      | xs:decimal?                |
+ * | qnames       | xs:QName*                  |
+ * | method       | (xs:string \| xs:QName)?   |
+ * | standalone   | xs:boolean? (empty: omit)  |
+ * | characterMap | map(xs:string, xs:string)? |
+ *
+ * @module @tradik/xslt3/serialize/params/fromMap
+ */
+
+import { XPathError } from "../../errors.js";
+import { atomize, cast, derivesFrom, isMap } from "../../xdm/index.js";
+import { PARAMETER_KINDS } from "./names.js";
+
+/**
+ * @param {string} name
+ * @returns {XPathError} XPTY0004
+ */
+const wrongType = (name) =>
+  new XPathError("XPTY0004", `Wrong type for serialization parameter ${name}`);
+
+/**
+ * @param {import("../../xdm/atomic.js").AtomicValue} item
+ * @param {string} type - Local name of an xs: type
+ * @returns {boolean} whether the item is an instance of the type
+ */
+const isA = (item, type) => derivesFrom(item.type, type);
+
+/**
+ * Converts one atomic value to a type: instances are kept, untyped values
+ * are cast, xs:anyURI is promoted to xs:string.
+ * @param {string} name - Parameter name
+ * @param {import("../../xdm/atomic.js").AtomicValue} item
+ * @param {string} type
+ * @returns {*} the value
+ */
+function convertAtomic(name, item, type) {
+  if (isA(item, type)) return item.value;
+  if (type === "string" && isA(item, "anyURI")) return item.value;
+  if (isA(item, "untypedAtomic") && type !== "QName") {
+    try {
+      return cast(item, type).value;
+    } catch {
+      throw wrongType(name);
+    }
+  }
+  throw wrongType(name);
+}
+
+/**
+ * @param {string} name
+ * @param {Array} value
+ * @returns {Map<string, string>} the character map
+ */
+function characterMapValue(name, value) {
+  if (value.length !== 1 || !isMap(value[0])) throw wrongType(name);
+  const map = new Map();
+  for (const { key, value: replacement } of value[0].entries.values()) {
+    const [item] = replacement;
+    if (
+      !isA(key, "string") ||
+      replacement.length !== 1 ||
+      !isA(item, "string")
+    ) {
+      throw wrongType(name);
+    }
+    map.set(key.value, item.value);
+  }
+  return map;
+}
+
+/**
+ * Converts the value of one parameter.
+ * @param {string} name - Parameter name
+ * @param {Array} value - Entry value
+ * @returns {*} the value for the API, undefined when absent
+ */
+function parameterValue(name, value) {
+  const kind = PARAMETER_KINDS[name];
+  if (kind === "characterMap") {
+    return value.length ? characterMapValue(name, value) : undefined;
+  }
+  const items = atomize(value);
+  if (kind === "qnames") {
+    return items.map((item) => convertAtomic(name, item, "QName"));
+  }
+  if (items.length > 1) throw wrongType(name);
+  if (!items.length) return kind === "standalone" ? null : undefined;
+  const [item] = items;
+  switch (kind) {
+    case "boolean":
+    case "standalone":
+      return convertAtomic(name, item, "boolean");
+    case "decimal":
+      return convertAtomic(name, item, "decimal");
+    case "method":
+      return isA(item, "QName")
+        ? item.value
+        : convertAtomic(name, item, "string");
+    default:
+      return convertAtomic(name, item, "string");
+  }
+}
+
+/**
+ * Reads serialization parameters from a map.
+ * @param {import("../../items/map.js").XdmMap} map
+ * @returns {Record<string, *>} parameters by hyphenated name
+ */
+export function parametersFromMap(map) {
+  const params = {};
+  for (const { key, value } of map.entries.values()) {
+    if (!isA(key, "string") || !PARAMETER_KINDS[key.value]) continue;
+    const converted = parameterValue(key.value, value);
+    if (converted !== undefined) params[key.value] = converted;
+  }
+  return params;
+}

package/src/serialize/params/names.js

@@ -0,0 +1,69 @@
+/**
+ * The serialization parameters of Serialization 3.1 section 3: their
+ * names (hyphenated as in the specs, camelCase in the JavaScript API) and
+ * the kind of value each one takes.
+ *
+ * @module @tradik/xslt3/serialize/params/names
+ */
+
+/** Namespace of the serialization parameter elements (prefix output). */
+export const OUTPUT_NAMESPACE =
+  "http://www.w3.org/2010/xslt-xquery-serialization";
+
+/**
+ * Kind of value of each parameter, by hyphenated name:
+ * - "boolean": yes/no (true/false, 1/0)
+ * - "string": any string
+ * - "qnames": a list of element names (EQNames)
+ * - "method": xml, xhtml, html, text, json, adaptive or an extension QName
+ * - "decimal": a decimal number (html-version)
+ * - "standalone": yes, no or omit
+ * - "characterMap": character to replacement string
+ */
+export const PARAMETER_KINDS = Object.freeze({
+  "allow-duplicate-names": "boolean",
+  "byte-order-mark": "boolean",
+  "cdata-section-elements": "qnames",
+  "doctype-public": "string",
+  "doctype-system": "string",
+  encoding: "string",
+  "escape-uri-attributes": "boolean",
+  "html-version": "decimal",
+  "include-content-type": "boolean",
+  indent: "boolean",
+  "item-separator": "string",
+  "json-node-output-method": "method",
+  "media-type": "string",
+  method: "method",
+  "normalization-form": "string",
+  "omit-xml-declaration": "boolean",
+  standalone: "standalone",
+  "suppress-indentation": "qnames",
+  "undeclare-prefixes": "boolean",
+  "use-character-maps": "characterMap",
+  version: "string",
+});
+
+/**
+ * @param {string} name - Hyphenated name, e.g. "omit-xml-declaration"
+ * @returns {string} the camelCase name, e.g. "omitXmlDeclaration"
+ */
+export const toCamelCase = (name) =>
+  name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+
+/**
+ * @param {string} name - camelCase name, e.g. "omitXmlDeclaration"
+ * @returns {string} the hyphenated name, e.g. "omit-xml-declaration"
+ */
+export const toHyphenated = (name) =>
+  name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+
+/** Output methods of Serialization 3.1. */
+export const METHODS = Object.freeze([
+  "xml",
+  "xhtml",
+  "html",
+  "text",
+  "json",
+  "adaptive",
+]);