@fnndsc/brasa 0.56.2 → 0.56.4

package/dist/builtins/games/numbers.d.ts

@@ -1,4 +1,5 @@
 import { CommandEnvelope } from '@fnndsc/menu';
+import { type ExpressionDeclaration } from '../../core/commandDeclaration.js';
 /** The most primes `primes` lists in one call. */
 export declare const PRIMES_MAX: number;
 /** The prime factors of n, smallest first, with repeats. */
@@ -34,13 +35,248 @@ export declare function units_convert(value: number, from: string, to: string):
 };
 /** The unit names `units` knows, for its help and its refusals. */
 export declare function units_known(): string[];
-/** `factor N...` */
+/**
+ * `factor N [N...]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [factorCommand] });
+ * ```
+ */
+export declare const factorCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "numbers";
+        readonly kind: "int";
+        readonly min: 1;
+        readonly max: number;
+        readonly optional: true;
+        readonly repeat: true;
+        readonly summary: "Whole numbers to factor (default: the numbers piped in)";
+    }];
+}>;
+/**
+ * `factor` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `factor`.
+ * @returns The factorisations, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_factor(['360']);
+ * ```
+ */
 export declare function builtin_factor(args: string[]): Promise<CommandEnvelope>;
-/** `primes [FROM] TO` */
+/**
+ * Factors the numbers piped in, else the numbers given.
+ *
+ * @param numbers - The numbers given, as words.
+ * @returns Each number with its prime factors, or a refusal for a word that is not a positive whole number.
+ *
+ * @example
+ * ```ts
+ * await factor_run(['360']); // 360: 2 2 2 3 3 5
+ * ```
+ */
+export declare function factor_run(numbers: ReadonlyArray<string>): Promise<CommandEnvelope>;
+/**
+ * `primes [FROM] TO`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [primesCommand] });
+ * ```
+ */
+export declare const primesCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "numbers";
+        readonly kind: "int";
+        readonly repeat: true;
+        readonly summary: "[FROM] TO";
+    }];
+}>;
+/**
+ * `primes` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `primes`.
+ * @returns The primes, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_primes(['20']);
+ * ```
+ */
 export declare function builtin_primes(args: string[]): Promise<CommandEnvelope>;
-/** `roll [NdS[+M]]...` — 1d6 when bare. */
+/**
+ * Lists the primes in a range.
+ *
+ * @param nums - `TO`, or `FROM` and `TO`.
+ * @returns The primes on one line, or a refusal for a wrong count of numbers.
+ *
+ * @example
+ * ```ts
+ * await primes_run([1000, 1100]);
+ * ```
+ */
+export declare function primes_run(nums: ReadonlyArray<number>): Promise<CommandEnvelope>;
+/**
+ * `roll [NdS[+M]...]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [rollCommand] });
+ * ```
+ */
+export declare const rollCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "dice";
+        readonly kind: "word";
+        readonly optional: true;
+        readonly repeat: true;
+        readonly summary: "Dice as NdS[+M] (default 1d6)";
+    }];
+}>;
+/**
+ * `roll` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `roll`.
+ * @returns The rolls, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_roll(['2d6']);
+ * ```
+ */
 export declare function builtin_roll(args: string[]): Promise<CommandEnvelope>;
-/** `calc EXPRESSION` */
+/**
+ * Rolls each die spec, one six-sided die when there are none.
+ *
+ * @param dice - The specs, as `NdS[+M]`.
+ * @returns Each spec's faces and total, or a refusal for a spec that is not dice.
+ *
+ * @example
+ * ```ts
+ * await roll_run(['2d6+1']);
+ * ```
+ */
+export declare function roll_run(dice: ReadonlyArray<string>): Promise<CommandEnvelope>;
+/**
+ * `calc EXPRESSION`: the declaration. Its words are an arithmetic
+ * expression, so one may begin with a dash (`calc -3+4`): it takes them
+ * as they come, parsing none as an option.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [calcCommand] });
+ * ```
+ */
+export declare const calcCommand: ExpressionDeclaration;
+/**
+ * `calc` over words already split.
+ *
+ * @param args - The words after `calc`.
+ * @returns The value, or the refusal of a malformed expression.
+ *
+ * @example
+ * ```ts
+ * await builtin_calc(['2^10']);
+ * ```
+ */
 export declare function builtin_calc(args: string[]): Promise<CommandEnvelope>;
-/** `units VALUE FROM [to] TO` */
+/**
+ * Evaluates the piped expression, else the words joined.
+ *
+ * @param words - The words of the expression.
+ * @returns The value, or a refusal naming what is wrong with the expression.
+ *
+ * @example
+ * ```ts
+ * await calc_run(['-3+4']); // 1
+ * ```
+ */
+export declare function calc_run(words: ReadonlyArray<string>): Promise<CommandEnvelope>;
+/**
+ * `units VALUE FROM [to] TO | units list`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [unitsCommand] });
+ * ```
+ */
+export declare const unitsCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "value";
+        readonly kind: "number";
+        readonly summary: "The quantity";
+    }, {
+        readonly name: "from";
+        readonly kind: "word";
+        readonly summary: "The unit it is in";
+    }, {
+        readonly name: "to";
+        readonly kind: "word";
+        readonly summary: "The unit to give it in (or the joining word to, in or as, then the unit)";
+    }, {
+        readonly name: "target";
+        readonly kind: "word";
+        readonly optional: true;
+        readonly summary: "The unit to give it in, after the joining word";
+    }];
+    readonly subcommands: {
+        readonly list: {
+            readonly summary: "Name the units known";
+        };
+    };
+    readonly bare: {
+        readonly summary: "Convert a quantity";
+    };
+}>;
+/**
+ * `units` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `units`.
+ * @returns The conversion, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_units(['10', 'mm', 'in']);
+ * ```
+ */
 export declare function builtin_units(args: string[]): Promise<CommandEnvelope>;
+/**
+ * The unit a conversion is to: the third word, or the fourth after a joining word.
+ *
+ * @param to - The third word.
+ * @param target - The fourth word, when there is one.
+ * @returns The destination unit, or null when a fourth word follows a third that is not `to`, `in` or `as`.
+ *
+ * @example
+ * ```ts
+ * units_destination('to', 'in'); // 'in'
+ * ```
+ */
+export declare function units_destination(to: string, target: string | undefined): string | null;
+/**
+ * Names every unit `units` knows.
+ *
+ * @returns The names on one line.
+ *
+ * @example
+ * ```ts
+ * await unitsList_run();
+ * ```
+ */
+export declare function unitsList_run(): Promise<CommandEnvelope>;
+/**
+ * Converts a quantity and says so.
+ *
+ * @param value - The quantity.
+ * @param from - The unit it is in.
+ * @param to - The unit to give it in.
+ * @returns The conversion, or a refusal naming the unit or kind that does not fit.
+ *
+ * @example
+ * ```ts
+ * await units_run(10, 'mm', 'in'); // 10 mm = 0.3937007874 in
+ * ```
+ */
+export declare function units_run(value: number, from: string, to: string): Promise<CommandEnvelope>;

package/dist/builtins/games/numbers.js

@@ -9,6 +9,8 @@
  */
 import { text_input } from './stdin.js';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
 /** The most primes `primes` lists in one call. */
 export const PRIMES_MAX = 10_000;
 /** The prime factors of n, smallest first, with repeats. */
@@ -192,10 +194,58 @@ export function units_convert(value, from, to) {
 export function units_known() {
     return Object.keys(UNITS);
 }
-/* --------------------------------------------------------- builtins */
-/** `factor N...` */
+/* ----------------------------------------------------- declarations */
+/** What a `factor` line may hold. */
+const FACTOR_GRAMMAR = {
+    operands: [{ name: 'numbers', kind: 'int', min: 1, max: Number.MAX_SAFE_INTEGER, optional: true, repeat: true, summary: 'Whole numbers to factor (default: the numbers piped in)' }],
+};
+/**
+ * `factor N [N...]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [factorCommand] });
+ * ```
+ */
+export const factorCommand = command_declare({
+    name: 'factor',
+    grammar: FACTOR_GRAMMAR,
+    help: {
+        summary: 'Prime factors of a number',
+        description: 'Prints each number with its prime factors, smallest first, repeats included, as factor does.',
+        examples: ['factor 360', 'factor 2026 1729'],
+        posix: { group: 'System', differs: 'as factor' },
+    },
+    holds: [],
+    handler: async (args) => factor_run(args.operands.numbers.map(String)),
+});
+/**
+ * `factor` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `factor`.
+ * @returns The factorisations, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_factor(['360']);
+ * ```
+ */
 export async function builtin_factor(args) {
-    const words = text_input(args)?.trim().split(/\s+/) ?? [];
+    return declaredCommand_run(factorCommand, args);
+}
+/**
+ * Factors the numbers piped in, else the numbers given.
+ *
+ * @param numbers - The numbers given, as words.
+ * @returns Each number with its prime factors, or a refusal for a word that is not a positive whole number.
+ *
+ * @example
+ * ```ts
+ * await factor_run(['360']); // 360: 2 2 2 3 3 5
+ * ```
+ */
+export async function factor_run(numbers) {
+    const words = text_input(numbers)?.trim().split(/\s+/) ?? [];
     if (words.length === 0)
         return envelope_error('', undefined, 'factor: usage: factor N [N...]\n');
     const lines = [];
@@ -210,20 +260,112 @@ export async function builtin_factor(args) {
     }
     return envelope_ok(`${lines.join('\n')}\n`, { kind: 'games.factor', data: { numbers: data } });
 }
-/** `primes [FROM] TO` */
+/** What a `primes` line may hold. */
+const PRIMES_GRAMMAR = {
+    operands: [{ name: 'numbers', kind: 'int', repeat: true, summary: '[FROM] TO' }],
+};
+/**
+ * `primes [FROM] TO`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [primesCommand] });
+ * ```
+ */
+export const primesCommand = command_declare({
+    name: 'primes',
+    grammar: PRIMES_GRAMMAR,
+    help: {
+        summary: 'The primes up to a number',
+        description: 'Lists the primes from FROM (2 when omitted) to TO, at most 10000 of them.',
+        examples: ['primes 100', 'primes 1000 1100'],
+        posix: { group: 'System', differs: 'as primes' },
+    },
+    holds: [],
+    handler: async (args) => primes_run(args.operands.numbers),
+});
+/**
+ * `primes` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `primes`.
+ * @returns The primes, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_primes(['20']);
+ * ```
+ */
 export async function builtin_primes(args) {
-    const nums = args.map(Number);
-    if (nums.length === 0 || nums.length > 2 || nums.some((n) => !Number.isInteger(n))) {
+    return declaredCommand_run(primesCommand, args);
+}
+/**
+ * Lists the primes in a range.
+ *
+ * @param nums - `TO`, or `FROM` and `TO`.
+ * @returns The primes on one line, or a refusal for a wrong count of numbers.
+ *
+ * @example
+ * ```ts
+ * await primes_run([1000, 1100]);
+ * ```
+ */
+export async function primes_run(nums) {
+    if (nums.length === 0 || nums.length > 2)
         return envelope_error('', undefined, 'primes: usage: primes [FROM] TO\n');
-    }
     const [from, to] = nums.length === 1 ? [2, nums[0]] : [nums[0], nums[1]];
     const primes = primes_between(from, to);
     const note = primes.length >= PRIMES_MAX ? `primes: stopped at ${PRIMES_MAX}\n` : '';
     return envelope_ok(`${primes.join(' ')}\n${note}`, { kind: 'games.primes', data: { from, to, primes } });
 }
-/** `roll [NdS[+M]]...` — 1d6 when bare. */
+/** What a `roll` line may hold. */
+const ROLL_GRAMMAR = {
+    operands: [{ name: 'dice', kind: 'word', optional: true, repeat: true, summary: 'Dice as NdS[+M] (default 1d6)' }],
+};
+/**
+ * `roll [NdS[+M]...]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [rollCommand] });
+ * ```
+ */
+export const rollCommand = command_declare({
+    name: 'roll',
+    grammar: ROLL_GRAMMAR,
+    help: {
+        summary: 'Roll dice: roll 2d6+1, roll d20',
+        description: 'Rolls dice written the tabletop way: N dice of S sides, plus or minus a modifier. Bare roll is one six-sided die. Shows each face and the total.',
+        examples: ['roll', 'roll 2d6', 'roll d20 3d8+2'],
+    },
+    handler: async (args) => roll_run(args.operands.dice),
+});
+/**
+ * `roll` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `roll`.
+ * @returns The rolls, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_roll(['2d6']);
+ * ```
+ */
 export async function builtin_roll(args) {
-    const specs = args.length === 0 ? ['1d6'] : args;
+    return declaredCommand_run(rollCommand, args);
+}
+/**
+ * Rolls each die spec, one six-sided die when there are none.
+ *
+ * @param dice - The specs, as `NdS[+M]`.
+ * @returns Each spec's faces and total, or a refusal for a spec that is not dice.
+ *
+ * @example
+ * ```ts
+ * await roll_run(['2d6+1']);
+ * ```
+ */
+export async function roll_run(dice) {
+    const specs = dice.length === 0 ? ['1d6'] : dice;
     const lines = [];
     const data = [];
     for (const spec of specs) {
@@ -236,9 +378,55 @@ export async function builtin_roll(args) {
     }
     return envelope_ok(`${lines.join('\n')}\n`, { kind: 'games.roll', data: { rolls: data } });
 }
-/** `calc EXPRESSION` */
+/**
+ * `calc EXPRESSION`: the declaration. Its words are an arithmetic
+ * expression, so one may begin with a dash (`calc -3+4`): it takes them
+ * as they come, parsing none as an option.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [calcCommand] });
+ * ```
+ */
+export const calcCommand = {
+    name: 'calc',
+    grammar: 'expression',
+    help: {
+        usage: 'calc <expression>',
+        summary: 'Arithmetic: calc 2^10, calc sqrt(2)*pi',
+        description: 'Evaluates an arithmetic expression: + - * / % ^, parentheses, sqrt, abs, ln, log, log2, exp, sin, cos, tan, asin, acos, atan, floor, ceil, round, and the constants pi, e and tau. No shell is involved. Its words are the expression, so one may begin with a dash: calc -3+4.',
+        examples: ['calc 2^10', 'calc (3+4)*5', 'calc sqrt(2)*pi', 'calc 1024*1024'],
+    },
+    holds: [],
+    handler: (args) => calc_run(args),
+};
+/**
+ * `calc` over words already split.
+ *
+ * @param args - The words after `calc`.
+ * @returns The value, or the refusal of a malformed expression.
+ *
+ * @example
+ * ```ts
+ * await builtin_calc(['2^10']);
+ * ```
+ */
 export async function builtin_calc(args) {
-    const expression = text_input(args);
+    return calc_run(args);
+}
+/**
+ * Evaluates the piped expression, else the words joined.
+ *
+ * @param words - The words of the expression.
+ * @returns The value, or a refusal naming what is wrong with the expression.
+ *
+ * @example
+ * ```ts
+ * await calc_run(['-3+4']); // 1
+ * ```
+ */
+export async function calc_run(words) {
+    const expression = text_input(words);
     if (expression === null)
         return envelope_error('', undefined, 'calc: usage: calc <expression>   (e.g. calc 2^10, calc sqrt(2)*pi)\n');
     try {
@@ -250,21 +438,108 @@ export async function builtin_calc(args) {
         return envelope_error('', undefined, `${error instanceof Error ? error.message : String(error)}\n`);
     }
 }
-/** `units VALUE FROM [to] TO` */
+/** What a `units` line may hold: a conversion, or `list`. */
+const UNITS_GRAMMAR = {
+    operands: [
+        { name: 'value', kind: 'number', summary: 'The quantity' },
+        { name: 'from', kind: 'word', summary: 'The unit it is in' },
+        { name: 'to', kind: 'word', summary: 'The unit to give it in (or the joining word to, in or as, then the unit)' },
+        { name: 'target', kind: 'word', optional: true, summary: 'The unit to give it in, after the joining word' },
+    ],
+    subcommands: {
+        list: { summary: 'Name the units known' },
+    },
+    bare: { summary: 'Convert a quantity' },
+};
+/**
+ * `units VALUE FROM [to] TO | units list`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [unitsCommand] });
+ * ```
+ */
+export const unitsCommand = command_declare({
+    name: 'units',
+    grammar: UNITS_GRAMMAR,
+    help: {
+        summary: 'Convert between units: units 10 mm in',
+        description: 'Converts a quantity between two units of one kind: length (mm cm m km in ft yd mi), mass (g kg mg lb oz), time (ms s min h d wk yr), data (B kB MB GB TB KiB MiB GiB TiB bit) and temperature (C F K). units list names them all. The line is units VALUE FROM [to] TO, or units list.',
+        examples: ['units 10 mm in', 'units 72 F to C', 'units 1 GiB MB', 'units list'],
+        posix: { group: 'System', differs: 'a small set of conversions' },
+    },
+    holds: [],
+    handler: async (args) => {
+        if (args.subcommand === 'list')
+            return unitsList_run();
+        const destination = units_destination(args.operands.to, args.operands.target);
+        if (destination === null)
+            return envelope_error('', undefined, 'units: usage: units VALUE FROM [to] TO   (units list names the units)\n');
+        return units_run(args.operands.value, args.operands.from, destination);
+    },
+});
+/**
+ * `units` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `units`.
+ * @returns The conversion, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_units(['10', 'mm', 'in']);
+ * ```
+ */
 export async function builtin_units(args) {
-    // `units 10 mm to in`, `units 10 mm in in`: the joining word is dropped.
-    const words = args.length === 4 && /^(to|in|as)$/i.test(args[2]) ? [args[0], args[1], args[3]] : [...args];
-    if (words.length === 1 && (words[0] === 'list' || words[0] === '--list')) {
-        return envelope_ok(`${units_known().join(' ')}\n`, { kind: 'games.units', data: { known: units_known() } });
-    }
-    if (words.length !== 3 || !Number.isFinite(Number(words[0]))) {
-        return envelope_error('', undefined, 'units: usage: units VALUE FROM [to] TO   (units list names the units)\n');
-    }
-    const value = Number(words[0]);
-    const r = units_convert(value, words[1], words[2]);
+    return declaredCommand_run(unitsCommand, args);
+}
+/**
+ * The unit a conversion is to: the third word, or the fourth after a joining word.
+ *
+ * @param to - The third word.
+ * @param target - The fourth word, when there is one.
+ * @returns The destination unit, or null when a fourth word follows a third that is not `to`, `in` or `as`.
+ *
+ * @example
+ * ```ts
+ * units_destination('to', 'in'); // 'in'
+ * ```
+ */
+export function units_destination(to, target) {
+    if (target === undefined)
+        return to;
+    return /^(to|in|as)$/i.test(to) ? target : null;
+}
+/**
+ * Names every unit `units` knows.
+ *
+ * @returns The names on one line.
+ *
+ * @example
+ * ```ts
+ * await unitsList_run();
+ * ```
+ */
+export async function unitsList_run() {
+    return envelope_ok(`${units_known().join(' ')}\n`, { kind: 'games.units', data: { known: units_known() } });
+}
+/**
+ * Converts a quantity and says so.
+ *
+ * @param value - The quantity.
+ * @param from - The unit it is in.
+ * @param to - The unit to give it in.
+ * @returns The conversion, or a refusal naming the unit or kind that does not fit.
+ *
+ * @example
+ * ```ts
+ * await units_run(10, 'mm', 'in'); // 10 mm = 0.3937007874 in
+ * ```
+ */
+export async function units_run(value, from, to) {
+    const r = units_convert(value, from, to);
     if ('refusal' in r)
         return envelope_error('', undefined, `${r.refusal}\n`);
     const shown = String(Number(r.value.toPrecision(10)));
-    return envelope_ok(`${value} ${words[1]} = ${shown} ${words[2]}\n`, { kind: 'games.units', data: { value, from: words[1], to: words[2], result: r.value } });
+    return envelope_ok(`${value} ${from} = ${shown} ${to}\n`, { kind: 'games.units', data: { value, from, to, result: r.value } });
 }
 //# sourceMappingURL=numbers.js.map