prosebook 0.2.0 → 0.4.0

package/src/tools/native/number.ts

@@ -0,0 +1,210 @@
+/**
+ * A number format taken apart at build time, so native code can put it back together with no
+ * formatter of its own: the digits to round to, the symbols, how integers group, and the text around
+ * the number for each sign. Read from `Intl.NumberFormat` and checked against it before any code is
+ * written, so a native target says what the browser says, or the build says why it can't.
+ */
+
+/** The text before and after the number. */
+export type Affix = readonly [prefix: string, suffix: string];
+
+export interface NumberSpec {
+  minInt: number;
+  minFrac: number;
+  maxFrac: number;
+  /** How far the decimal point moves right before rounding: 2 for a percent. */
+  shift: number;
+  /** Integer digits grouped from the right, `primary` then `secondary` at a time, once there are `primary + min` of them; `min` 0 never groups. */
+  grouping: { primary: number; secondary: number; min: number };
+  decimal: string;
+  group: string;
+  /** The numbering system's digits, 0 to 9, where it isn't ASCII's. */
+  digits?: string[];
+  positive: Affix;
+  negative: Affix;
+  /** A value that rounds to zero, by its sign. */
+  zero: Affix;
+  negativeZero: Affix;
+  nan: string;
+  infinity: string;
+  negativeInfinity: string;
+}
+
+/** The plural operands' digits: rounded as `Intl.PluralRules` rounds before it selects. */
+export interface Rounding {
+  minFrac: number;
+  maxFrac: number;
+}
+
+const NUMBER_PARTS = new Set(['integer', 'group', 'decimal', 'fraction']);
+
+/** Values the spec must format as `Intl` does: signs, zeros, ties, grouping thresholds, every plural form a unit could take. */
+const SAMPLES = [
+  0,
+  -0,
+  1,
+  -1,
+  2,
+  3,
+  5,
+  11,
+  21,
+  0.5,
+  1.5,
+  2.5,
+  -2.5,
+  0.125,
+  0.0001,
+  -0.0001,
+  0.07,
+  1.005,
+  12.345,
+  999.9999,
+  1000,
+  10000,
+  100000,
+  1234.5678,
+  -1234.5678,
+  1e6,
+  123456789.987,
+  1e21,
+  NaN,
+  Infinity,
+  -Infinity,
+];
+
+function affixOf(parts: Intl.NumberFormatPart[]): Affix {
+  const first = parts.findIndex((p) => NUMBER_PARTS.has(p.type));
+  const last = parts.findLastIndex((p) => NUMBER_PARTS.has(p.type));
+  const text = (from: number, to: number) =>
+    parts
+      .slice(from, to)
+      .map((p) => p.value)
+      .join('');
+  return [text(0, first), text(last + 1, parts.length)];
+}
+
+function partOf(parts: Intl.NumberFormatPart[], type: string): string | undefined {
+  return parts.find((p) => p.type === type)?.value;
+}
+
+/**
+ * What a format with `options` takes in `locale`. Throws a sentence saying what a native target
+ * can't reproduce, which the caller puts in front of a fix.
+ */
+export function numberSpec(locale: string, options: Intl.NumberFormatOptions = {}): NumberSpec {
+  const format = new Intl.NumberFormat(locale, options);
+  const resolved = format.resolvedOptions();
+  if (resolved.notation !== 'standard') throw new Error(`${resolved.notation} notation reads the size of the number at runtime`);
+  if (resolved.minimumSignificantDigits !== undefined) throw new Error('significant digits round by the size of the number');
+  if (resolved.roundingIncrement !== 1 || resolved.roundingMode !== 'halfExpand')
+    throw new Error('it rounds other than half away from zero');
+  if (resolved.trailingZeroDisplay !== 'auto') throw new Error('it drops trailing zeros by value');
+
+  const at = (more: Intl.NumberFormatOptions) => new Intl.NumberFormat(locale, { ...options, ...more });
+  const whole = at({ minimumFractionDigits: 0, maximumFractionDigits: 0 });
+  const integers = whole
+    .formatToParts(1234567891234)
+    .filter((p) => p.type === 'integer')
+    .map((p) => p.value.length);
+  const grouped = (digits: number) =>
+    whole.formatToParts(10 ** (digits - 1 - (resolved.style === 'percent' ? 2 : 0))).some((p) => p.type === 'group');
+  const primary = integers.at(-1) ?? 3;
+  const secondary = integers.length > 2 ? integers.at(-2)! : primary;
+  const min = integers.length < 2 ? 0 : ([1, 2, 3, 4].find((m) => grouped(primary + m)) ?? 0);
+
+  const native = new Intl.NumberFormat(locale, { numberingSystem: resolved.numberingSystem, useGrouping: false });
+  const digits = Array.from({ length: 10 }, (_, d) => native.format(d));
+  const spec: NumberSpec = {
+    minInt: resolved.minimumIntegerDigits,
+    minFrac: resolved.minimumFractionDigits ?? 0,
+    maxFrac: resolved.maximumFractionDigits ?? 0,
+    shift: resolved.style === 'percent' ? 2 : 0,
+    grouping: { primary, secondary, min },
+    decimal: partOf(at({ minimumFractionDigits: 1, maximumFractionDigits: 1 }).formatToParts(1.5), 'decimal') ?? '.',
+    group: partOf(whole.formatToParts(1234567891234), 'group') ?? ',',
+    ...(digits.join('') !== '0123456789' && { digits }),
+    positive: affixOf(format.formatToParts(1)),
+    negative: affixOf(format.formatToParts(-1)),
+    zero: affixOf(format.formatToParts(0)),
+    negativeZero: affixOf(format.formatToParts(-0)),
+    nan: format.format(NaN),
+    infinity: format.format(Infinity),
+    negativeInfinity: format.format(-Infinity),
+  };
+  for (const sample of SAMPLES) {
+    const expected = format.format(sample);
+    const actual = formatNumber(spec, sample);
+    if (actual !== expected) throw new Error(`it writes ${sample} as "${expected}", which native code would write as "${actual}"`);
+  }
+  return spec;
+}
+
+/** How `Intl.PluralRules` rounds before it selects, with `options` (MF2's selector options) in `locale`. */
+export function roundingOf(locale: string, options: Intl.PluralRulesOptions = {}): Rounding {
+  const resolved = new Intl.PluralRules(locale, options).resolvedOptions();
+  if (resolved.minimumSignificantDigits !== undefined) throw new Error('significant digits select by the size of the number');
+  return { minFrac: resolved.minimumFractionDigits ?? 0, maxFrac: resolved.maximumFractionDigits ?? 3 };
+}
+
+/**
+ * The digits of a finite, non-negative double as the shortest decimal that reads back as it, which
+ * is what `Intl` rounds: 1.005 is 1.00499… in binary, and still rounds to 1.01. Every target's
+ * shortest form (`String()` here) may use an exponent, which moves the point.
+ */
+export function shortestDigits(value: number): { int: string; frac: string } {
+  const [mantissa = '', exponent = '0'] = String(value).split('e');
+  const [int = '', frac = ''] = mantissa.split('.');
+  const point = int.length + Number(exponent);
+  const all = int + frac;
+  if (point <= 0) return { int: '0', frac: '0'.repeat(-point) + all };
+  return { int: all.slice(0, point).padEnd(point, '0'), frac: all.slice(point) };
+}
+
+/**
+ * Exact digits moved `shift` places right, rounded half away from zero to `maxFrac`, with trailing
+ * zeros cut down to `minFrac`. The algorithm every target writes out; keep them in step.
+ */
+export function roundDigits(int: string, frac: string, shift: number, minFrac: number, maxFrac: number): { int: string; frac: string } {
+  const padded = frac.padEnd(shift, '0');
+  const whole = int + padded.slice(0, shift);
+  const rest = padded.slice(shift);
+  const kept = (whole + rest.slice(0, maxFrac).padEnd(maxFrac, '0')).split('').map(Number);
+  if ((rest[maxFrac] ?? '0') >= '5') {
+    let at = kept.length - 1;
+    while (at >= 0 && kept[at] === 9) kept[at--] = 0;
+    if (at < 0) kept.unshift(1);
+    else kept[at]!++;
+  }
+  const all = kept.join('');
+  let outFrac = all.slice(all.length - maxFrac);
+  while (outFrac.length > minFrac && outFrac.endsWith('0')) outFrac = outFrac.slice(0, -1);
+  return { int: all.slice(0, all.length - maxFrac).replace(/^0+/, ''), frac: outFrac };
+}
+
+function groupDigits(int: string, { primary, secondary, min }: NumberSpec['grouping'], separator: string): string {
+  if (min === 0 || int.length < primary + min) return int;
+  const groups = [int.slice(-primary)];
+  let rest = int.slice(0, -primary);
+  while (rest.length > secondary) {
+    groups.unshift(rest.slice(-secondary));
+    rest = rest.slice(0, -secondary);
+  }
+  groups.unshift(rest);
+  return groups.join(separator);
+}
+
+/** `value` as the spec writes it: the reference for the code each target generates. */
+export function formatNumber(spec: NumberSpec, value: number): string {
+  if (Number.isNaN(value)) return spec.nan;
+  if (!Number.isFinite(value)) return value > 0 ? spec.infinity : spec.negativeInfinity;
+  const shortest = shortestDigits(Math.abs(value));
+  const { int, frac } = roundDigits(shortest.int, shortest.frac, spec.shift, spec.minFrac, spec.maxFrac);
+  const negative = value < 0 || Object.is(value, -0);
+  const zero = /^0*$/.test(int + frac);
+  const [prefix, suffix] = zero ? (negative ? spec.negativeZero : spec.zero) : negative ? spec.negative : spec.positive;
+  const shown =
+    groupDigits(int.padStart(Math.max(spec.minInt, 1), '0'), spec.grouping, spec.group) + (frac === '' ? '' : spec.decimal + frac);
+  const digits = spec.digits;
+  return prefix + (digits === undefined ? shown : shown.replace(/[0-9]/g, (d) => digits[Number(d)]!)) + suffix;
+}

package/src/tools/native/plurals.ts

@@ -0,0 +1,103 @@
+/**
+ * CLDR's plural rules, read into conditions a native target writes as code. Swift, the JVM and Rust
+ * have no plural rules of their own that every platform carries, so each generated file brings the
+ * rules of the locales it formats, from the same CLDR data `Intl.PluralRules` is built on.
+ */
+import ordinals from 'cldr-core/supplemental/ordinals.json' with { type: 'json' };
+import cardinals from 'cldr-core/supplemental/plurals.json' with { type: 'json' };
+
+/** CLDR's operands: `n` the absolute value, `i` its integer digits, `v`/`w` the count of fraction digits with and without trailing zeros, `f`/`t` those digits, `c`/`e` the compact exponent. */
+export type Operand = 'n' | 'i' | 'v' | 'w' | 'f' | 't' | 'c' | 'e';
+
+/** `i % 10 = 2..4, 7`: the operand, less its modulus, in (or with `negated`, not in) the ranges. A single value is a range of one. */
+export interface Relation {
+  operand: Operand;
+  mod?: number;
+  negated: boolean;
+  ranges: (readonly [number, number])[];
+}
+
+/** Relations joined by `and`, those joined by `or`. */
+export type Condition = Relation[][];
+
+/** A locale's categories in CLDR's order, each with its condition. `other` holds wherever none does, so it has none. */
+export type PluralRules = (readonly [category: string, Condition])[];
+
+export type Operands = Record<Operand, number>;
+
+type RuleData = Record<string, Record<string, string>>;
+
+const DATA = {
+  cardinal: cardinals.supplemental['plurals-type-cardinal'] as RuleData,
+  ordinal: ordinals.supplemental['plurals-type-ordinal'] as RuleData,
+};
+
+/**
+ * The rules for `locale`, found as `Intl.PluralRules` finds its locale, then by its parents
+ * (`pt-PT`, then `pt`), so the generated code picks the category the browser would.
+ */
+export function pluralRules(locale: string, type: 'cardinal' | 'ordinal'): PluralRules {
+  const data = DATA[type];
+  let tag = new Intl.PluralRules(locale, { type }).resolvedOptions().locale;
+  while (!(tag in data) && tag.includes('-')) tag = tag.slice(0, tag.lastIndexOf('-'));
+  const rules = data[tag] ?? data['root'] ?? {};
+  return Object.entries(rules).flatMap(([name, rule]) => {
+    const category = name.slice('pluralRule-count-'.length);
+    return category === 'other' ? [] : [[category, parseCondition(rule.split('@', 1)[0]!)] as const];
+  });
+}
+
+/** `v = 0 and i % 10 = 1 or n = 0..1`, its samples already cut. */
+export function parseCondition(source: string): Condition {
+  return source
+    .trim()
+    .split(/\s+or\s+/)
+    .map((and) => and.split(/\s+and\s+/).map(parseRelation));
+}
+
+function parseRelation(source: string): Relation {
+  const match = /^([nivwftce])\s*(?:%\s*(\d+))?\s*(!?=)\s*(.+)$/.exec(source.trim());
+  if (match === null) throw new Error(`prosebook: a CLDR plural rule it can't read: "${source}"`);
+  const [, operand, mod, op, list] = match;
+  return {
+    operand: operand as Operand,
+    ...(mod !== undefined && { mod: Number(mod) }),
+    negated: op === '!=',
+    ranges: list!.split(',').map((range) => {
+      const [from, to = from] = range.trim().split('..');
+      return [Number(from), Number(to)] as const;
+    }),
+  };
+}
+
+/** A range of one is an equality; a wider range holds integers only, as CLDR's `in` does. */
+export function inRange(value: number, [from, to]: readonly [number, number]): boolean {
+  return from === to ? value === from : Number.isInteger(value) && value >= from && value <= to;
+}
+
+function holds(relation: Relation, operands: Operands): boolean {
+  const raw = operands[relation.operand];
+  const value = relation.mod === undefined ? raw : raw % relation.mod;
+  return relation.ranges.some((range) => inRange(value, range)) !== relation.negated;
+}
+
+/** The category `rules` give, as the generated code picks it. */
+export function categoryOf(rules: PluralRules, operands: Operands): string {
+  for (const [category, condition] of rules) if (condition.some((and) => and.every((r) => holds(r, operands)))) return category;
+  return 'other';
+}
+
+/** The operands of a number written with `int` and `frac` digits, as CLDR reads them. */
+export function operandsOf(int: string, frac: string): Operands {
+  const trimmed = frac.replace(/0+$/, '');
+  return {
+    n: Number(`${int}.${frac || '0'}`),
+    i: Number(int),
+    v: frac.length,
+    w: trimmed.length,
+    f: Number(frac || '0'),
+    t: Number(trimmed || '0'),
+    c: 0,
+    e: 0,
+  };
+}

package/src/tools/native/printf.ts

@@ -0,0 +1,95 @@
+/**
+ * Messages as printf-style format strings, for the targets whose platform fills values in itself:
+ * Android's resources and Apple's `.strings` files. Text and plain `{name}` placeholders, as `%N$s`
+ * with N the argument's place in the message's arguments, so a translation can put them in another
+ * order; anything `Intl` would format fails with the fix.
+ */
+import { isDateElement, isNumberElement, isTimeElement } from '@formatjs/icu-messageformat-parser';
+
+import type { Message } from '#src/tools/catalog.ts';
+import { numberOptions, placeholderOf, TYPE, type MessageFormatElement } from '#src/tools/icu.ts';
+import { docText } from './emit.ts';
+import { LEAVE_OUT } from './model.ts';
+
+export interface Printf {
+  /** Who fills values in, and with what, as problems name them: `Android`, `String.format`. */
+  platform: string;
+  formatter: string;
+  /** What holds the text, as problems name it: `Android resources`. */
+  holder: string;
+  /** A string argument's conversion: `s`, or `@` for Apple's objects. */
+  string: string;
+  /** Text as the file holds it; `formatted` when the string has arguments, so `%` must be doubled. */
+  escape: (text: string, formatted: boolean) => string;
+  /** The problem with a plural the target can't hold where it is. */
+  plural: (name: string) => string;
+}
+
+/** The context and what each argument holds, on one line, for the comment above an entry. */
+export function noteOf(m: Message): string {
+  const lines = [
+    m.context,
+    ...[...m.args.keys()].map((a) => (m.argDocs.has(a) ? `${a}: ${m.argDocs.get(a)!.replace(/\.$/, '')}.` : undefined)),
+  ];
+  return docText(lines.filter((l) => l !== undefined && l !== '').join(' '));
+}
+
+/** What a plural's arms may hold as its count: `#`, or the count as a plain `:number` or `:integer`. */
+function isCount(el: MessageFormatElement, count: string): boolean {
+  if (el.type === TYPE.pound) return true;
+  if (!isNumberElement(el) || el.value !== count) return false;
+  const options = Object.entries(numberOptions(el) ?? {});
+  return options.length === 0 || (options.length === 1 && options[0]![0] === 'maximumFractionDigits' && options[0]![1] === 0);
+}
+
+/** `elements` as a format string over `args`; inside a plural, its `count` is `%N$d`. */
+export function formatString(elements: MessageFormatElement[], args: string[], printf: Printf, count?: string): string {
+  const formatted = args.length > 0;
+  const place = (el: MessageFormatElement, name: string, conversion: string) => {
+    const at = args.indexOf(name);
+    if (at < 0) throw new Error(`{${name}} is not an argument of this message: say it in the source text too`);
+    const { isolate } = placeholderOf(el, name);
+    const spec = `%${at + 1}$${conversion}`;
+    return isolate === undefined ? spec : `${printf.escape(isolate[0], formatted)}${spec}${printf.escape(isolate[1], formatted)}`;
+  };
+  let out = '';
+  for (const el of elements) {
+    if (count !== undefined && isCount(el, count)) {
+      out += place(el, count, 'd');
+      continue;
+    }
+    if (isDateElement(el) || isTimeElement(el)) {
+      throw new Error(
+        `{${el.value}} is a date, which ${printf.holder} don't format: pass it formatted, as a plain {${el.value}}, ${LEAVE_OUT}`,
+      );
+    }
+    if (isNumberElement(el)) {
+      throw new Error(
+        `{${el.value}} is a formatted number, and ${printf.platform} fills values in with ${printf.formatter}, not Intl: pass it formatted, as a plain {${el.value}}, ${LEAVE_OUT}`,
+      );
+    }
+    switch (el.type) {
+      case TYPE.literal:
+        out += printf.escape(el.value, formatted);
+        break;
+      case TYPE.argument:
+        out += place(el, el.value, printf.string);
+        break;
+      case TYPE.pound:
+        // Outside a plural, `#` is text.
+        out += '#';
+        break;
+      case TYPE.select:
+        throw new Error(
+          `{${el.value}} is a select, which ${printf.holder} can't hold: write a key per case and pick one in code, ${LEAVE_OUT}`,
+        );
+      case TYPE.plural:
+        throw new Error(printf.plural(el.value));
+      case TYPE.tag:
+        throw new Error(`<${el.value}> is a tag, and ${printf.holder} here hold plain text: say it without the tag, ${LEAVE_OUT}`);
+      default:
+        throw new Error(`prosebook: no ${printf.platform} writer for ICU element type ${(el as MessageFormatElement).type}`);
+    }
+  }
+  return out;
+}