@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/functions/format/datePicture.js

@@ -0,0 +1,115 @@
+/**
+ * Picture strings of format-dateTime, format-date and format-time (F&O
+ * 3.1 sections 9.8.4.1 and 9.8.4.2): literal text, variable markers with
+ * their component, presentation modifiers and width modifier.
+ *
+ * @module @tradik/xslt3/functions/format/datePicture
+ */
+
+import { XPathError } from "../../errors.js";
+
+/**
+ * @typedef {object} Marker
+ * @property {string} component - One of YMDdFWwHhPmsfZzCE
+ * @property {string|null} first - First presentation modifier, null for
+ *   the component's default
+ * @property {string|null} second - "a", "t", "c" or "o"
+ * @property {number|null} minWidth - null when absent or "*"
+ * @property {number|null} maxWidth - null when absent or "*"
+ */
+
+/**
+ * @param {string} message
+ * @returns {never}
+ * @throws {XPathError} FOFD1340
+ */
+export function dateFormatError(message) {
+  throw new XPathError("FOFD1340", `Invalid date/time picture: ${message}`);
+}
+
+const COMPONENTS = "YMDdFWwHhPmsfZzCE";
+const widthPattern = /^(\*|\d+)(?:-(\*|\d+))?$/;
+
+/**
+ * Parses the width modifier ("min" or "min-max", "*" for no limit).
+ * @param {string} text
+ * @returns {{minWidth: number|null, maxWidth: number|null}}
+ */
+function parseWidth(text) {
+  const match = widthPattern.exec(text);
+  if (!match) dateFormatError(`width modifier ,${text}`);
+  const [, min, max = "*"] = match;
+  const minWidth = min === "*" ? null : Number(min);
+  const maxWidth = max === "*" ? null : Number(max);
+  if (
+    minWidth === 0 ||
+    maxWidth === 0 ||
+    (maxWidth !== null && maxWidth < (minWidth ?? 0))
+  ) {
+    dateFormatError(`width modifier ,${text}`);
+  }
+  return { minWidth, maxWidth };
+}
+
+/**
+ * Parses the inside of a variable marker.
+ * @param {string} text - Between the brackets
+ * @returns {Marker}
+ */
+export function parseMarker(text) {
+  const marker = text.replace(/[ \t\n\r]+/g, "");
+  const component = marker[0];
+  if (component === undefined || !COMPONENTS.includes(component)) {
+    dateFormatError(`unknown component in [${text}]`);
+  }
+  const comma = marker.lastIndexOf(",");
+  const modifiers = comma < 0 ? marker.slice(1) : marker.slice(1, comma);
+  const width =
+    comma < 0
+      ? { minWidth: null, maxWidth: null }
+      : parseWidth(marker.slice(comma + 1));
+  const chars = Array.from(modifiers);
+  const hasSecond = chars.length > 1 && "atco".includes(chars.at(-1));
+  return {
+    component,
+    first:
+      modifiers === ""
+        ? null
+        : hasSecond
+          ? chars.slice(0, -1).join("")
+          : modifiers,
+    second: hasSecond ? chars.at(-1) : null,
+    ...width,
+  };
+}
+
+/**
+ * Splits a picture into literal strings and markers.
+ * @param {string} picture
+ * @returns {Array<string|Marker>}
+ * @throws {XPathError} FOFD1340 for unbalanced brackets or invalid markers
+ */
+export function parseDatePicture(picture) {
+  const parts = [];
+  let literal = "";
+  for (let i = 0; i < picture.length; i++) {
+    const c = picture[i];
+    if ((c === "[" || c === "]") && picture[i + 1] === c) {
+      literal += c;
+      i++;
+    } else if (c === "[") {
+      const end = picture.indexOf("]", i);
+      if (end < 0) dateFormatError("unterminated [");
+      if (literal) parts.push(literal);
+      literal = "";
+      parts.push(parseMarker(picture.slice(i + 1, end)));
+      i = end;
+    } else if (c === "]") {
+      dateFormatError("unescaped ]");
+    } else {
+      literal += c;
+    }
+  }
+  if (literal) parts.push(literal);
+  return parts;
+}

package/src/functions/format/decimalFormat.js

@@ -0,0 +1,65 @@
+/**
+ * Decimal formats of fn:format-number (XPath 3.1 static context, XSLT
+ * `xsl:decimal-format`).
+ *
+ * The evaluator supplies the formats through the dynamic context hook
+ * `context.decimalFormats`, an object with `get(name)`: it receives the
+ * format name as written in the third argument with surrounding whitespace
+ * removed (a lexical QName or `Q{uri}local`, so the hook resolves the
+ * prefix), or "" for the unnamed format, and returns a partial
+ * {@link DecimalFormat} (missing properties take the defaults) or
+ * undefined when no such format is declared.
+ *
+ * @module @tradik/xslt3/functions/format/decimalFormat
+ */
+
+import { XPathError } from "../../errors.js";
+
+/**
+ * Properties of a decimal format; all but `infinity` and `nan` are single
+ * characters.
+ * @typedef {object} DecimalFormat
+ * @property {string} decimalSeparator
+ * @property {string} groupingSeparator
+ * @property {string} exponentSeparator
+ * @property {string} infinity
+ * @property {string} minusSign
+ * @property {string} nan
+ * @property {string} percent
+ * @property {string} perMille
+ * @property {string} zeroDigit - First digit of the decimal digit family
+ * @property {string} digit - The optional digit sign
+ * @property {string} patternSeparator
+ */
+
+/** @type {Readonly<DecimalFormat>} the default (unnamed) decimal format */
+export const DEFAULT_DECIMAL_FORMAT = Object.freeze({
+  decimalSeparator: ".",
+  groupingSeparator: ",",
+  exponentSeparator: "e",
+  infinity: "Infinity",
+  minusSign: "-",
+  nan: "NaN",
+  percent: "%",
+  perMille: "‰",
+  zeroDigit: "0",
+  digit: "#",
+  patternSeparator: ";",
+});
+
+/**
+ * Looks up a decimal format.
+ * @param {string|undefined} name - The third argument of format-number,
+ *   undefined when absent or empty
+ * @param {{decimalFormats?: {get: (name: string) => (Partial<DecimalFormat>|undefined)}}} context
+ * @returns {DecimalFormat}
+ * @throws {XPathError} FODF1280 for an unknown format name
+ */
+export function getDecimalFormat(name, context) {
+  const key = name?.trim() ?? "";
+  const custom = context.decimalFormats?.get(key);
+  if (custom === undefined && key !== "") {
+    throw new XPathError("FODF1280", `Unknown decimal format ${key}`);
+  }
+  return { ...DEFAULT_DECIMAL_FORMAT, ...custom };
+}

package/src/functions/format/digitPattern.js

@@ -0,0 +1,145 @@
+/**
+ * Decimal digit patterns of format-integer and format-date/time pictures
+ * (F&O 3.1 section 4.6.1): mandatory digits of one digit family, optional
+ * "#" digits and grouping separators, regular or not.
+ *
+ * @module @tradik/xslt3/functions/format/digitPattern
+ */
+
+import { XPathError } from "../../errors.js";
+
+const isDigitChar = (c) => /^\p{Nd}$/u.test(c);
+const isAlphanumeric = (c) => /^[\p{L}\p{N}]$/u.test(c);
+
+/**
+ * @param {string} message
+ * @returns {never}
+ * @throws {XPathError} FODF1310
+ */
+export function pictureError(message) {
+  throw new XPathError("FODF1310", `Invalid picture string: ${message}`);
+}
+
+/**
+ * The zero digit of the family of a decimal digit: Unicode digit runs are
+ * contiguous blocks of ten starting at their zero.
+ * @param {string} digit - A character of category Nd
+ * @returns {number} codepoint of the zero
+ */
+export function zeroOf(digit) {
+  const cp = digit.codePointAt(0);
+  let start = cp;
+  while (isDigitChar(String.fromCodePoint(start - 1))) start--;
+  return cp - ((cp - start) % 10);
+}
+
+/**
+ * @typedef {object} DigitPattern
+ * @property {number} zero - Codepoint of the zero digit
+ * @property {number} mandatory - Number of mandatory digits
+ * @property {number} digits - Number of digit signs, "#" included
+ * @property {Map<number, string>} separators - Separator by number of
+ *   digit signs to its right
+ * @property {number} grouping - Regular grouping size, 0 when irregular
+ */
+
+/**
+ * Whether a format token is a decimal digit pattern: it has a decimal
+ * digit ("#" alone falls back to the default format, see W3C bug 19004).
+ * @param {string} token
+ * @returns {boolean}
+ */
+export const isDigitPattern = (token) => Array.from(token).some(isDigitChar);
+
+/**
+ * Parses a decimal digit pattern.
+ * @param {string} token
+ * @returns {DigitPattern}
+ * @throws {XPathError} FODF1310 when invalid
+ */
+export function parseDigitPattern(token) {
+  const chars = Array.from(token);
+  let zero = null;
+  let mandatory = 0;
+  const marks = [];
+  chars.forEach((c, i) => {
+    if (c === "#") {
+      if (mandatory > 0) pictureError(`"#" after a digit in ${token}`);
+      marks.push(null);
+    } else if (isDigitChar(c)) {
+      if (zero !== null && zeroOf(c) !== zero) {
+        pictureError(`digits of different families in ${token}`);
+      }
+      zero = zeroOf(c);
+      mandatory++;
+      marks.push(null);
+    } else if (isAlphanumeric(c)) {
+      pictureError(`letter ${c} in ${token}`);
+    } else {
+      if (i === 0 || i === chars.length - 1 || marks.at(-1) !== null) {
+        pictureError(`misplaced grouping separator in ${token}`);
+      }
+      marks.push(c);
+    }
+  });
+  if (zero === null) pictureError(`no mandatory digit in ${token}`);
+  const digits = marks.filter((m) => m === null).length;
+  const separators = new Map();
+  let right = 0;
+  for (let i = marks.length - 1; i >= 0; i--) {
+    if (marks[i] === null) right++;
+    else separators.set(right, marks[i]);
+  }
+  return {
+    zero,
+    mandatory,
+    digits,
+    separators,
+    grouping: regularGrouping(separators, digits),
+  };
+}
+
+/**
+ * The grouping size when the separators are regular (one character, at
+ * every multiple of the first position), else 0.
+ * @param {Map<number, string>} separators
+ * @param {number} digits
+ * @returns {number}
+ */
+export function regularGrouping(separators, digits) {
+  if (separators.size === 0) return 0;
+  const size = Math.min(...separators.keys());
+  const chars = new Set(separators.values());
+  for (const position of separators.keys()) {
+    if (position % size !== 0) return 0;
+  }
+  for (let position = size; position < digits; position += size) {
+    if (!separators.has(position)) return 0;
+  }
+  return chars.size === 1 ? size : 0;
+}
+
+/**
+ * Formats a non-negative integer with a digit pattern.
+ * @param {bigint|string} value - Non-negative integer, or its ASCII digits
+ * @param {DigitPattern} pattern
+ * @param {number} [minDigits] - Overrides the mandatory digit count
+ * @returns {string}
+ */
+export function formatDigits(value, pattern, minDigits = pattern.mandatory) {
+  const ascii = String(value).padStart(minDigits, "0");
+  const { zero, separators, grouping } = pattern;
+  const separator = grouping ? separators.get(grouping) : null;
+  let result = "";
+  for (let i = ascii.length - 1, count = 0; i >= 0; i--) {
+    if (count > 0) {
+      const mark = grouping
+        ? count % grouping === 0 && separator
+        : separators.get(count);
+      if (mark) result = mark + result;
+    }
+    result = String.fromCodePoint(zero + Number(ascii[i])) + result;
+    count++;
+  }
+  return result;
+}

package/src/functions/format/formatDateTime.js

@@ -0,0 +1,204 @@
+/**
+ * fn:format-dateTime, fn:format-date and fn:format-time (F&O 3.1 section
+ * 9.8). Output is English with the Gregorian ("AD") or ISO calendar;
+ * other languages produce English prefixed with "[Language: en]", other
+ * calendars the Gregorian form prefixed with "[Calendar: AD]". A place
+ * that is an IANA timezone name adjusts the value (see place.js).
+ *
+ * @module @tradik/xslt3/functions/format/formatDateTime
+ */
+
+import { define, stringItem } from "../support.js";
+import {
+  componentName,
+  componentValue,
+  isAvailable,
+  presentName,
+} from "./dateComponents.js";
+import { dateFormatError, parseDatePicture } from "./datePicture.js";
+import {
+  formatDigits,
+  isDigitPattern,
+  parseDigitPattern,
+} from "./digitPattern.js";
+import { formatToken } from "./formatInteger.js";
+import { formatFraction } from "./fractionFormat.js";
+import { applyPlace } from "./place.js";
+import { formatTimezone } from "./timezoneFormat.js";
+import { XPathError } from "../../errors.js";
+
+const NAMED = new Set(["n", "N", "Nn"]);
+/** Default presentation modifiers other than "1". */
+/* calendar and era names keep their case ("AD") by default */
+const DEFAULT_TOKENS = { m: "01", s: "01", F: "n", P: "n", C: "Nn", E: "Nn" };
+const NUMBER_TOKENS = /^(a|A|i|I|w|W|Ww)$/;
+const CALENDARS = new Set(
+  (
+    "AD AH AME AM AP AS BE CB CE CL CS EE FE ISO JE KE KY ME MS NS OS RS " +
+    "SE SH SS TE VE VS"
+  ).split(" "),
+);
+
+/**
+ * Formats a numeric component with a digit pattern and width.
+ * @param {number} n - Non-negative
+ * @param {import("./datePicture.js").Marker} marker
+ * @param {string} token - A decimal digit pattern
+ * @returns {string}
+ */
+function formatNumeric(n, marker, token) {
+  const pattern = parseDigitPattern(token);
+  let value = BigInt(n);
+  if (marker.component === "Y") {
+    const width = marker.maxWidth ?? (pattern.digits >= 2 ? pattern.digits : 0);
+    if (width) value %= 10n ** BigInt(width);
+  }
+  const digits = formatDigits(
+    value,
+    pattern,
+    Math.max(pattern.mandatory, marker.minWidth ?? 0),
+  );
+  return marker.second === "o" ? formatToken(value, token, true) : digits;
+}
+
+/**
+ * Formats one variable marker.
+ * @param {import("./datePicture.js").Marker} marker
+ * @param {import("../../xdm/datetime.js").DateTimeValue} value
+ * @param {string} calendar
+ * @param {string|null} zone - Timezone name from the place argument
+ * @returns {string}
+ */
+function formatMarker(marker, value, calendar, zone) {
+  const { component, minWidth, maxWidth } = marker;
+  if (component === "Z" || component === "z") {
+    return formatTimezone(value.timezone, marker, zone);
+  }
+  if (component === "f") return formatFraction(value.second, marker);
+  const name = componentName(value, component, calendar);
+  const fallback = DEFAULT_TOKENS[component] ?? "1";
+  let token = marker.first ?? fallback;
+  if (NAMED.has(token) && name === null) token = fallback;
+  if (NAMED.has(token)) return presentName(name, token, minWidth, maxWidth);
+  if ("PCE".includes(component)) {
+    return presentName(name, fallback, minWidth, maxWidth);
+  }
+  const n = componentValue(value, component);
+  if (isDigitPattern(token)) return formatNumeric(n, marker, token);
+  if (NUMBER_TOKENS.test(token)) {
+    // the year is shown modulo 10^max-width (F&O 3.1 section 9.8.4.4)
+    const shown = component === "Y" && maxWidth ? n % 10 ** maxWidth : n;
+    const text = formatToken(BigInt(shown), token, marker.second === "o");
+    return text.padEnd(minWidth ?? 0, " ");
+  }
+  return fallback === "n"
+    ? presentName(name, "n", minWidth, maxWidth)
+    : formatNumeric(n, marker, fallback);
+}
+
+const EQNAME =
+  /^(Q\{[^{}]*\}|[\p{L}_][\p{L}\p{N}._-]*:)[\p{L}_][\p{L}\p{N}._-]*$/u;
+
+/**
+ * The calendar used for a calendar argument: AD, ISO or CE are supported;
+ * other known designators and calendars in a namespace fall back to AD
+ * with a "[Calendar: AD]" prefix.
+ * @param {string|null|undefined} calendar
+ * @returns {{used: string, prefix: string}}
+ * @throws {XPathError} FOFD1340 for an unknown calendar in no namespace
+ */
+function resolveCalendar(calendar) {
+  const name = (calendar?.trim() ?? "").replace(/^Q\{\}/, "");
+  if (name === "" || name === "AD" || name === "ISO" || name === "CE") {
+    return { used: name || "AD", prefix: "" };
+  }
+  if (!CALENDARS.has(name) && !EQNAME.test(name)) {
+    dateFormatError(`unknown calendar ${calendar}`);
+  }
+  return { used: "AD", prefix: "[Calendar: AD]" };
+}
+
+/**
+ * Formats a date/time value with a picture string.
+ * @param {string} kind - "dateTime", "date" or "time"
+ * @param {import("../../xdm/datetime.js").DateTimeValue} value
+ * @param {string} picture
+ * @param {{language?: string|null, calendar?: string|null,
+ *   place?: string|null}} [options]
+ * @returns {string}
+ * @throws {XPathError} FOFD1340 for an invalid picture or calendar,
+ *   FOFD1350 for a component the value does not have
+ */
+export function formatDateTime(kind, value, picture, options = {}) {
+  try {
+    return formatParts(kind, value, picture, options);
+  } catch (error) {
+    // invalid digit patterns inside markers are picture errors here
+    if (error.code !== "FODF1310") throw error;
+    return dateFormatError(error.message);
+  }
+}
+
+/**
+ * {@link formatDateTime} without the error code mapping.
+ * @param {string} kind
+ * @param {import("../../xdm/datetime.js").DateTimeValue} original
+ * @param {string} picture
+ * @param {object} options
+ * @returns {string}
+ */
+function formatParts(kind, original, picture, options) {
+  const { value, zone } = applyPlace(kind, original, options.place);
+  const { used, prefix } = resolveCalendar(options.calendar);
+  const language = options.language?.trim();
+  const fallback =
+    language && !/^en(-|$)/i.test(language) ? "[Language: en]" : "";
+  const parts = parseDatePicture(picture).map((part) => {
+    if (typeof part === "string") return part;
+    if (!isAvailable(kind, part.component)) {
+      throw new XPathError(
+        "FOFD1350",
+        `[${part.component}] is not available in an xs:${kind}`,
+      );
+    }
+    return formatMarker(part, value, used, zone);
+  });
+  return prefix + fallback + parts.join("");
+}
+
+/**
+ * Declares the 2- and 5-argument forms of one function.
+ * @param {string} kind
+ * @returns {import("../support.js").FunctionDefinition[]}
+ */
+function definitions(kind) {
+  const local = `format-${kind}`;
+  const param = `xs:${kind}?`;
+  const impl = ([value, [picture], language, calendar, place]) =>
+    value.length === 0
+      ? []
+      : [
+          stringItem(
+            formatDateTime(kind, value[0].value, picture.value, {
+              language: language?.[0]?.value,
+              calendar: calendar?.[0]?.value,
+              place: place?.[0]?.value,
+            }),
+          ),
+        ];
+  const S_OPT = "xs:string?";
+  return [
+    define(local, [param, "xs:string"], "xs:string?", impl),
+    define(
+      local,
+      [param, "xs:string", S_OPT, S_OPT, S_OPT],
+      "xs:string?",
+      impl,
+    ),
+  ];
+}
+
+/** @type {import("../support.js").FunctionDefinition[]} */
+export const formatDateTimeFunctions = ["dateTime", "date", "time"].flatMap(
+  definitions,
+);

package/src/functions/format/formatInteger.js

@@ -0,0 +1,109 @@
+/**
+ * fn:format-integer (F&O 3.1 section 4.6.1). Supported primary format
+ * tokens: decimal digit patterns in any Unicode digit family with
+ * grouping separators, "a", "A", "i", "I", "w", "W" and "Ww"; other tokens
+ * fall back to "1". The format modifier "o" gives ordinals ("1st",
+ * "first"). Words and ordinals follow the language argument where
+ * numberLanguages.js knows it (English and German), else English.
+ *
+ * @module @tradik/xslt3/functions/format/formatInteger
+ */
+
+import { define, stringItem } from "../support.js";
+import {
+  formatDigits,
+  isDigitPattern,
+  parseDigitPattern,
+  pictureError,
+} from "./digitPattern.js";
+import { numberLanguage } from "./numberLanguages.js";
+import { alphabetic, caseWords, MAX_ROMAN, roman } from "./numberWords.js";
+
+const DEFAULT_PATTERN = parseDigitPattern("1");
+
+/**
+ * Formats a non-negative integer with a primary format token.
+ * @param {bigint} n - Non-negative
+ * @param {string} token - Primary format token
+ * @param {boolean|string} ordinal - Whether the "o" modifier is present,
+ *   or its form (the text in parentheses, "" for none)
+ * @param {import("./numberLanguages.js").NumberLanguage} [language]
+ * @returns {string}
+ */
+export function formatToken(n, token, ordinal, language = numberLanguage()) {
+  const form = ordinal === true ? "" : ordinal;
+  if (isDigitPattern(token)) {
+    const digits = formatDigits(n, parseDigitPattern(token));
+    return form === false ? digits : digits + language.suffix(n);
+  }
+  if ((token === "a" || token === "A") && n > 0n) return alphabetic(n, token);
+  if ((token === "i" || token === "I") && n > 0n && n <= MAX_ROMAN) {
+    const numerals = roman(n);
+    return token === "I" ? numerals.toUpperCase() : numerals;
+  }
+  if (token === "w" || token === "W" || token === "Ww") {
+    const words =
+      form === false ? language.cardinal(n) : language.ordinal(n, form);
+    return caseWords(words, token);
+  }
+  const digits = formatDigits(n, DEFAULT_PATTERN);
+  return form === false ? digits : digits + language.suffix(n);
+}
+
+/**
+ * Splits a picture into its primary format token and whether the format
+ * modifier asks for ordinal numbering.
+ * @param {string} picture
+ * @returns {{token: string, ordinal: boolean|string}} ordinal: false, or
+ *   the text in parentheses after "o" ("" for none)
+ * @throws {XPathError} FODF1310 for an empty token or invalid modifier
+ */
+export function parseIntegerPicture(picture) {
+  const semicolon = picture.lastIndexOf(";");
+  const token = semicolon < 0 ? picture : picture.slice(0, semicolon);
+  const modifier = semicolon < 0 ? "" : picture.slice(semicolon + 1);
+  if (token === "") pictureError("empty primary format token");
+  if (!/^([co](\(.+\))?)?[at]?$/su.test(modifier)) {
+    pictureError(`invalid format modifier ${modifier}`);
+  }
+  const form = /^o(?:\((.+)\))?/su.exec(modifier);
+  return { token, ordinal: form ? (form[1] ?? "") : false };
+}
+
+/**
+ * fn:format-integer on JS values.
+ * @param {bigint} value
+ * @param {string} picture
+ * @param {string|null} [lang] - Language tag
+ * @returns {string}
+ */
+export function formatInteger(value, picture, lang = null) {
+  const { token, ordinal } = parseIntegerPicture(picture);
+  const negative = value < 0n;
+  const language = numberLanguage(lang);
+  const body = formatToken(negative ? -value : value, token, ordinal, language);
+  return negative ? `-${body}` : body;
+}
+
+/**
+ * @param {Array<*>[]} args - [$value, $picture, $lang?]
+ * @returns {Array<*>}
+ */
+const impl = ([value, [picture], lang]) => [
+  stringItem(
+    value.length === 0
+      ? ""
+      : formatInteger(value[0].value, picture.value, lang?.[0]?.value),
+  ),
+];
+
+/** @type {import("../support.js").FunctionDefinition[]} */
+export const formatIntegerFunctions = [
+  define("format-integer", ["xs:integer?", "xs:string"], "xs:string", impl),
+  define(
+    "format-integer",
+    ["xs:integer?", "xs:string", "xs:string?"],
+    "xs:string",
+    impl,
+  ),
+];