@fnndsc/brasa 0.56.1 → 0.56.3

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

@@ -1,5 +1,62 @@
 import { CommandEnvelope } from '@fnndsc/menu';
 /** The meanings of a term, or none. */
 export declare function wtf_lookup(term: string): ReadonlyArray<string>;
-/** `wtf [is] <term>... | wtf -l` */
+/**
+ * `wtf [is] <term>... | wtf -l`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [wtfCommand] });
+ * ```
+ */
+export declare const wtfCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "terms";
+        readonly kind: "word";
+        readonly optional: true;
+        readonly repeat: true;
+        readonly summary: "The terms to look up, after an optional \"is\"";
+    }];
+    readonly options: {
+        readonly list: {
+            readonly short: "l";
+            readonly long: "list";
+            readonly summary: "Every term in the book";
+        };
+    };
+}>;
+/**
+ * `wtf` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `wtf`.
+ * @returns The meanings, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_wtf(['is', 'lonk']);
+ * ```
+ */
 export declare function builtin_wtf(args: string[]): Promise<CommandEnvelope>;
+/**
+ * Lists every term in the book.
+ *
+ * @returns The terms on one line.
+ *
+ * @example
+ * ```ts
+ * await wtfList_run();
+ * ```
+ */
+export declare function wtfList_run(): Promise<CommandEnvelope>;
+/**
+ * Looks up the piped terms, else the words given.
+ *
+ * @param terms - The words given, an `is` or an article among them dropped.
+ * @returns Each term's meanings, or a refusal when there is no term.
+ *
+ * @example
+ * ```ts
+ * await wtf_run(['is', 'lonk']);
+ * ```
+ */
+export declare function wtf_run(terms: ReadonlyArray<string>): Promise<CommandEnvelope>;

package/dist/builtins/games/wtf.js

@@ -10,18 +10,79 @@ import chalk from 'chalk';
 import { ACRONYMS } from './wtf.data.js';
 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 meanings of a term, or none. */
 export function wtf_lookup(term) {
     const key = term.trim().toLowerCase().replace(/[?.!,]+$/, '');
     return ACRONYMS[key] ?? ACRONYMS[key.replace(/-/g, '')] ?? [];
 }
-/** `wtf [is] <term>... | wtf -l` */
+/** What a `wtf` line may hold. */
+const WTF_GRAMMAR = {
+    operands: [{ name: 'terms', kind: 'word', optional: true, repeat: true, summary: 'The terms to look up, after an optional "is"' }],
+    options: {
+        list: { short: 'l', long: 'list', summary: 'Every term in the book' },
+    },
+};
+/**
+ * `wtf [is] <term>... | wtf -l`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [wtfCommand] });
+ * ```
+ */
+export const wtfCommand = command_declare({
+    name: 'wtf',
+    grammar: WTF_GRAMMAR,
+    help: {
+        summary: 'What an acronym means: wtf is lonk',
+        description: 'BSD\'s acronym expander with the lab\'s own book: ChRIS, CUBE, pfdcm, oxidicom, LONK, PACS, DICOM, MRN, SeaGaP, the mise packages and more. A term the book lacks is said so; -l lists every term it has.',
+        examples: ['wtf is lonk', 'wtf cube pfdcm', 'wtf -l'],
+    },
+    handler: async (args) => (args.options.list ? wtfList_run() : wtf_run(args.operands.terms)),
+});
+/**
+ * `wtf` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `wtf`.
+ * @returns The meanings, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_wtf(['is', 'lonk']);
+ * ```
+ */
 export async function builtin_wtf(args) {
-    if (args[0] === '-l' || args[0] === '--list') {
-        const terms = Object.keys(ACRONYMS).sort();
-        return envelope_ok(`${terms.join('  ')}\n`, { kind: 'games.wtf', data: { terms } });
-    }
-    const text = text_input(args);
+    return declaredCommand_run(wtfCommand, args);
+}
+/**
+ * Lists every term in the book.
+ *
+ * @returns The terms on one line.
+ *
+ * @example
+ * ```ts
+ * await wtfList_run();
+ * ```
+ */
+export async function wtfList_run() {
+    const terms = Object.keys(ACRONYMS).sort();
+    return envelope_ok(`${terms.join('  ')}\n`, { kind: 'games.wtf', data: { terms } });
+}
+/**
+ * Looks up the piped terms, else the words given.
+ *
+ * @param terms - The words given, an `is` or an article among them dropped.
+ * @returns Each term's meanings, or a refusal when there is no term.
+ *
+ * @example
+ * ```ts
+ * await wtf_run(['is', 'lonk']);
+ * ```
+ */
+export async function wtf_run(terms) {
+    const text = text_input(terms);
     const words = (text ?? '').trim().split(/\s+/).filter((w) => w.length > 0 && !/^(is|are|the|a|an)$/i.test(w));
     if (words.length === 0)
         return envelope_error('', undefined, 'wtf: usage: wtf [is] <term>   (wtf -l lists the terms)\n');

package/dist/builtins/games/wtf.js.map

@@ -1 +1 @@
-{"version":3,"file":"wtf.js","sourceRoot":"","sources":["../../../src/builtins/games/wtf.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wtf.js","sourceRoot":"","sources":["../../../src/builtins/games/wtf.ts"],"names":[],"mappings":"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"}

package/dist/builtins/help.d.ts

@@ -2,7 +2,9 @@ import { type HelpLookup } from './helpSections.js';
 import { type CommandHelp } from '../core/commandRegistry.js';
 import type { CommandEnvelope } from '@fnndsc/menu';
 /**
- * Help-text registry keyed by builtin command name.
+ * Help-text registry keyed by builtin command name, for the commands not yet
+ * declared in one record: a declared command's help is generated from its
+ * declaration, and its entry leaves this table.
  */
 export declare const helpText: Record<string, CommandHelp>;
 /**
@@ -81,11 +83,47 @@ export declare function verb_available(name: string): boolean;
  */
 export declare function args_checkHasHelpFlag(args: string[], command?: string): boolean;
 /**
- * Builtin help command - displays command list or specific command help.
+ * `help [topic…]`: the declaration.
  *
- * @param args - Command arguments (optional command name).
+ * @example
+ * ```ts
+ * commands_register({ declarations: [helpCommand] });
+ * ```
+ */
+export declare const helpCommand: import("../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "topic";
+        readonly kind: "word";
+        readonly optional: true;
+        readonly repeat: true;
+        readonly summary: "A command, a section or a Shell topic; help pacs query, a subcommand";
+    }];
+}>;
+/**
+ * `help` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `help`.
+ * @returns The page, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_help(['ls']);
+ * ```
  */
 export declare function builtin_help(args: string[]): Promise<CommandEnvelope>;
+/**
+ * The help page a topic names: bare, the table of contents; else a section,
+ * a Shell topic, a command, or what the backend answers for the name.
+ *
+ * @param topic - The words naming it (two for a subcommand: `pacs query`).
+ * @returns The page.
+ *
+ * @example
+ * ```ts
+ * await help_answer(['PACS']);
+ * ```
+ */
+export declare function help_answer(topic: readonly string[]): Promise<CommandEnvelope>;
 /**
  * What the help sections read of the commands this session has.
  *