@fnndsc/brasa 0.56.2 → 0.56.4

package/dist/builtins/sys/echo.d.ts

@@ -12,20 +12,63 @@
  * Both answer with text and no model, as the text filters do, so
  * `A=$(echo …)` holds what was written.
  *
+ * Each is declared in one record (`echoCommand`, `printfCommand`). `printf`
+ * parses its line as every declared command does; `echo` declares its words
+ * its own (`grammar: 'expression'`), since a dash-word past the front is a
+ * word to it, never an option.
+ *
  * @module
  */
 import { type CommandEnvelope } from '@fnndsc/menu';
+import { type ExpressionDeclaration } from '../../core/commandDeclaration.js';
 /** What a format turned into, or why it could not be. */
 type Formatted = {
     text: string;
 } | {
     refused: string;
 };
+/**
+ * `echo [WORD]…`: the declaration. Its grammar is its own: every word is a
+ * word, dashes and all, so the GNU option grammar would take `echo use -n
+ * here` for an option; only `-n`, `-e` or `-E` at the front is refused.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [echoCommand] });
+ * ```
+ */
+export declare const echoCommand: ExpressionDeclaration;
+/**
+ * `printf FORMAT [ARG]…`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [printfCommand] });
+ * ```
+ */
+export declare const printfCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "format";
+        readonly kind: "word";
+        readonly summary: "The format: %s, %d, %i and %% with flags, width and precision; the escapes \\n, \\t and \\\\";
+    }, {
+        readonly name: "argument";
+        readonly kind: "word";
+        readonly optional: true;
+        readonly repeat: true;
+        readonly summary: "The values the format takes, in turn";
+    }];
+}>;
 /**
  * `echo [WORD]…`: the words, joined by a space, on one line.
  *
  * @param args - The words after `echo`.
  * @returns The line.
+ *
+ * @example
+ * ```ts
+ * (await builtin_echo(['feed', '5596'])).rendered; // 'feed 5596\n'
+ * ```
  */
 export declare function builtin_echo(args: string[]): Promise<CommandEnvelope>;
 /**
@@ -38,10 +81,28 @@ export declare function builtin_echo(args: string[]): Promise<CommandEnvelope>;
  */
 export declare function printf_format(format: string, args: string[]): Formatted;
 /**
- * `printf FORMAT [ARG]…`: the arguments written under the format.
+ * `printf` over words already split: the declaration's parse and handler.
  *
  * @param args - The format, then its arguments.
- * @returns The text, its line ended.
+ * @returns The text, its line ended, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * (await builtin_printf(['%s-%03d', 'scan', '7'])).rendered; // 'scan-007\n'
+ * ```
  */
 export declare function builtin_printf(args: string[]): Promise<CommandEnvelope>;
+/**
+ * The arguments written under the format.
+ *
+ * @param format - The format.
+ * @param rest - Its arguments.
+ * @returns The text, its line ended, or the refusal of what printf here does not read.
+ *
+ * @example
+ * ```ts
+ * await printf_run('%s=%d', ['a', '1']);
+ * ```
+ */
+export declare function printf_run(format: string, rest: readonly string[]): Promise<CommandEnvelope>;
 export {};

package/dist/builtins/sys/echo.js

@@ -12,19 +12,83 @@
  * Both answer with text and no model, as the text filters do, so
  * `A=$(echo …)` holds what was written.
  *
+ * Each is declared in one record (`echoCommand`, `printfCommand`). `printf`
+ * parses its line as every declared command does; `echo` declares its words
+ * its own (`grammar: 'expression'`), since a dash-word past the front is a
+ * word to it, never an option.
+ *
  * @module
  */
 import { envelope_error, envelope_ok } from '@fnndsc/menu';
 import { exitCode_set } from '../../core/handlerRun.js';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
 /** The options other echos take at the front of the line, which this one refuses so a word is never silently eaten. */
 const ECHO_OPTIONS = new Set(['-n', '-e', '-E']);
 /** A conversion: `%`, flags, width, precision, then the letter. */
 const CONVERSION = /^%([-+ 0#]*)(\d*|\*)(?:\.(\d*|\*))?([a-zA-Z%])/;
+/** What a `printf` line may hold. */
+const PRINTF_GRAMMAR = {
+    operands: [
+        { name: 'format', kind: 'word', summary: 'The format: %s, %d, %i and %% with flags, width and precision; the escapes \\n, \\t and \\\\' },
+        { name: 'argument', kind: 'word', optional: true, repeat: true, summary: 'The values the format takes, in turn' },
+    ],
+};
+/**
+ * `echo [WORD]…`: the declaration. Its grammar is its own: every word is a
+ * word, dashes and all, so the GNU option grammar would take `echo use -n
+ * here` for an option; only `-n`, `-e` or `-E` at the front is refused.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [echoCommand] });
+ * ```
+ */
+export const echoCommand = {
+    name: 'echo',
+    grammar: 'expression',
+    help: {
+        usage: 'echo [WORD]…',
+        summary: 'Write words on a line',
+        description: 'Writes its words joined by a space and ends the line. It takes no option and reads no escape, since the System V and BSD echos disagree on both; -n, -e or -E as the first word is refused by name rather than obeyed; later it is a word. A field of a variable is a word like any other: echo ${R.feedId}. It answers with text, so A=$(echo …) holds what it wrote. To see a variable whole, set NAME.',
+        category: 'General',
+        posix: { group: 'Text', differs: 'no options and no escapes: the words, joined by a space, on one line; printf writes anything else' },
+        examples: ['echo hello', 'echo feed ${R.feedId}', 'X=$(echo t1 cohort)'],
+    },
+    holds: [],
+    handler: (args) => builtin_echo(args),
+};
+/**
+ * `printf FORMAT [ARG]…`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [printfCommand] });
+ * ```
+ */
+export const printfCommand = command_declare({
+    name: 'printf',
+    grammar: PRINTF_GRAMMAR,
+    help: {
+        summary: 'Write arguments under a format',
+        description: 'Writes each argument under the format, as POSIX printf does: %s a word, %d and %i a whole number, %% a percent sign, each with the flags - 0 + and space, a width and a precision (%-12s, %05d, %.3s). With more arguments than the format takes, the format is written again until they run out; one missing is empty for %s and 0 for %d. The escapes are \\n, \\t and \\\\; a backslash in quotes reaches printf as written, so \'%s\\n\' or "%s\\n" writes a newline. Any other conversion or escape is refused by name. A session writes whole lines, so the text always ends its line. It answers with text, so A=$(printf …) holds what it wrote. An argument that starts with a dash (-5) follows --: printf -- \'%d\' -5.',
+        category: 'General',
+        posix: { group: 'Text', differs: 'POSIX\'s subset: %s, %d, %i, %%, flags, width and precision; the escapes \\n, \\t and \\\\; always ends the line' },
+        examples: ['printf "feed %s: %s" ${R.feedId} done', "printf '%-8s %5d\\n' a 1 bb 22", 'NAME=$(printf "%s-%03d" scan 7)'],
+    },
+    holds: [],
+    handler: async (args) => printf_run(args.operands.format, args.operands.argument),
+});
 /**
  * `echo [WORD]…`: the words, joined by a space, on one line.
  *
  * @param args - The words after `echo`.
  * @returns The line.
+ *
+ * @example
+ * ```ts
+ * (await builtin_echo(['feed', '5596'])).rendered; // 'feed 5596\n'
+ * ```
  */
 export async function builtin_echo(args) {
     const option = args[0];
@@ -161,18 +225,33 @@ export function printf_format(format, args) {
     return { text };
 }
 /**
- * `printf FORMAT [ARG]…`: the arguments written under the format.
+ * `printf` over words already split: the declaration's parse and handler.
  *
  * @param args - The format, then its arguments.
- * @returns The text, its line ended.
+ * @returns The text, its line ended, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * (await builtin_printf(['%s-%03d', 'scan', '7'])).rendered; // 'scan-007\n'
+ * ```
  */
 export async function builtin_printf(args) {
-    const [format, ...rest] = args;
-    if (format === undefined) {
-        exitCode_set(1);
-        return envelope_error('', undefined, 'printf: give a format: printf FORMAT [ARG]…\n');
-    }
-    const formatted = printf_format(format, rest);
+    return declaredCommand_run(printfCommand, args);
+}
+/**
+ * The arguments written under the format.
+ *
+ * @param format - The format.
+ * @param rest - Its arguments.
+ * @returns The text, its line ended, or the refusal of what printf here does not read.
+ *
+ * @example
+ * ```ts
+ * await printf_run('%s=%d', ['a', '1']);
+ * ```
+ */
+export async function printf_run(format, rest) {
+    const formatted = printf_format(format, [...rest]);
     if ('refused' in formatted) {
         exitCode_set(1);
         return envelope_error('', undefined, `${formatted.refused}\n`);

package/dist/builtins/sys/echo.js.map

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

package/dist/builtins/sys/fortune.d.ts

@@ -8,10 +8,35 @@ import { CommandEnvelope } from '@fnndsc/menu';
  * @returns The chosen fortune text (no trailing newline).
  */
 export declare function fortune_random(maxLines?: number): string;
+/**
+ * `fortune`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [fortuneCommand] });
+ * ```
+ */
+export declare const fortuneCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{}>;
+/**
+ * `fortune` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `fortune`.
+ * @returns A fortune, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_fortune([]);
+ * ```
+ */
+export declare function builtin_fortune(args: string[]): Promise<CommandEnvelope>;
 /**
  * Reports a random fortune as a command envelope.
  *
- * @param _args - Unused.
  * @returns An envelope carrying the chosen fortune and a typed model of it.
+ *
+ * @example
+ * ```ts
+ * await fortune_run();
+ * ```
  */
-export declare function builtin_fortune(_args: string[]): Promise<CommandEnvelope>;
+export declare function fortune_run(): Promise<CommandEnvelope>;

package/dist/builtins/sys/fortune.js

@@ -10,6 +10,8 @@
  */
 import { FORTUNES } from './fortunes.data.js';
 import { envelope_ok } from '@fnndsc/menu';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
 /**
  * Picks a random fortune from the bundled collection.
  *
@@ -25,13 +27,53 @@ export function fortune_random(maxLines) {
     const pool = bounded.length > 0 ? bounded : FORTUNES;
     return pool[Math.floor(Math.random() * pool.length)];
 }
+/** What a `fortune` line may hold: nothing. */
+const FORTUNE_GRAMMAR = {};
+/**
+ * `fortune`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [fortuneCommand] });
+ * ```
+ */
+export const fortuneCommand = command_declare({
+    name: 'fortune',
+    grammar: FORTUNE_GRAMMAR,
+    help: {
+        summary: 'Print a random fortune cookie',
+        description: 'Prints a random fortune — the classic UNIX fortune cookie, bundled and self-contained.',
+        examples: ['fortune'],
+        category: 'Games',
+    },
+    holds: [],
+    handler: async (_args) => fortune_run(),
+});
+/**
+ * `fortune` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `fortune`.
+ * @returns A fortune, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_fortune([]);
+ * ```
+ */
+export async function builtin_fortune(args) {
+    return declaredCommand_run(fortuneCommand, args);
+}
 /**
  * Reports a random fortune as a command envelope.
  *
- * @param _args - Unused.
  * @returns An envelope carrying the chosen fortune and a typed model of it.
+ *
+ * @example
+ * ```ts
+ * await fortune_run();
+ * ```
  */
-export async function builtin_fortune(_args) {
+export async function fortune_run() {
     const fortune = fortune_random();
     return envelope_ok(`${fortune}\n`, {
         kind: 'sys.fortune',

package/dist/builtins/sys/fortune.js.map

@@ -1 +1 @@
-{"version":3,"file":"fortune.js","sourceRoot":"","sources":["../../../src/builtins/sys/fortune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAmB,WAAW,EAAE,MAAM,cAAc,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,QAAiB;IAC9C,MAAM,OAAO,GACX,QAAQ,KAAK,SAAS;QACpB,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC;QAC3E,CAAC,CAAC,QAAQ,CAAC;IACf,MAAM,IAAI,GAAsB,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;IACxE,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAAe;IACnD,MAAM,OAAO,GAAW,cAAc,EAAE,CAAC;IACzC,OAAO,WAAW,CAAC,GAAG,OAAO,IAAI,EAAE;QACjC,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,EAAE,OAAO,EAAE;KAClB,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"fortune.js","sourceRoot":"","sources":["../../../src/builtins/sys/fortune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAmB,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,eAAe,EAA8C,MAAM,kCAAkC,CAAC;AAC/G,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,QAAiB;IAC9C,MAAM,OAAO,GACX,QAAQ,KAAK,SAAS;QACpB,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC;QAC3E,CAAC,CAAC,QAAQ,CAAC;IACf,MAAM,IAAI,GAAsB,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;IACxE,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,+CAA+C;AAC/C,MAAM,eAAe,GAAG,EAAoC,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAAC;IAC5C,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,eAAe;IACxB,IAAI,EAAE;QACJ,OAAO,EAAE,+BAA+B;QACxC,WAAW,EAAE,wFAAwF;QACrG,QAAQ,EAAE,CAAC,SAAS,CAAC;QACrB,QAAQ,EAAE,OAAO;KAClB;IACD,KAAK,EAAE,EAAE;IACT,OAAO,EAAE,KAAK,EAAE,KAA+C,EAA4B,EAAE,CAAC,WAAW,EAAE;CAC5G,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAc;IAClD,OAAO,mBAAmB,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,OAAO,GAAW,cAAc,EAAE,CAAC;IACzC,OAAO,WAAW,CAAC,GAAG,OAAO,IAAI,EAAE;QACjC,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,EAAE,OAAO,EAAE;KAClB,CAAC,CAAC;AACL,CAAC"}

package/dist/builtins/sys/grep.d.ts

@@ -1,29 +1,231 @@
-import { CommandEnvelope } from '@fnndsc/menu';
+import { type CommandEnvelope } from '@fnndsc/menu';
+import { type FilterSource } from './textFilters.js';
 import { type AnswerRow } from '../../session/answer.js';
-/** What a grep line asks. */
+/**
+ * What a grep line asks of a match: the flags that decide which lines (or
+ * rows) are kept, and the patterns.
+ *
+ * @example
+ * ```ts
+ * const ask: GrepAsk = { insensitive: true, invert: false, word: false, extended: false, fixed: false, count: false, patterns: ['t1'] };
+ * ```
+ */
 export interface GrepAsk {
+    /** -i: ignore case. */
     insensitive: boolean;
+    /** -v: keep what does not match. */
     invert: boolean;
+    /** -w: whole words. */
     word: boolean;
+    /** -E: extended regular expressions. */
     extended: boolean;
+    /** -F: fixed strings. */
     fixed: boolean;
+    /** -c: count only. */
     count: boolean;
+    /** The patterns: any of them matches. */
     patterns: string[];
-    /** A flag or operand this grep does not take: the line is the system grep's. */
-    foreign: string | null;
 }
 /**
- * Reads a grep line's words.
+ * How a grep line over text writes what it kept: the flags that mean
+ * something for lines and files, and nothing for a numbered listing.
  *
- * @param args - The words after `grep`.
- * @returns What they ask.
+ * @example
+ * ```ts
+ * const layout: GrepLayout = { ...GREP_LAYOUT_PLAIN, lineNumber: true, after: 2 };
+ * ```
+ */
+export interface GrepLayout {
+    /** -n: each line's number. */
+    lineNumber: boolean;
+    /** -l: only the names of files with a match. */
+    filesWithMatches: boolean;
+    /** -o: only the matching parts, one per line. */
+    onlyMatching: boolean;
+    /** -h: no file-name prefix. */
+    noFilename: boolean;
+    /** -H: the file-name prefix even for one file. */
+    withFilename: boolean;
+    /** --color[=WHEN], as given: the kernel writes no colour; the system grep is told. */
+    color: string | undefined;
+    /** -r: each folder operand walked for files. */
+    recursive: boolean;
+    /** -A N, as given. */
+    after: number | undefined;
+    /** -B N, as given. */
+    before: number | undefined;
+    /** -C N, as given. */
+    context: number | undefined;
+}
+/**
+ * The layout of a grep line that asks none: lines as they are.
+ *
+ * @example
+ * ```ts
+ * const layout: GrepLayout = { ...GREP_LAYOUT_PLAIN, onlyMatching: true };
+ * ```
+ */
+export declare const GREP_LAYOUT_PLAIN: GrepLayout;
+/**
+ * `grep [-ivwEFcnlohr] [-A N] [-B N] [-C N] [-e PATTERN]... [PATTERN] [FILE]...`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [grepCommand] });
+ * ```
+ */
+export declare const grepCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "pattern";
+        readonly kind: "word";
+        readonly optional: true;
+        readonly unless: "regexp";
+        readonly summary: "The pattern, unless -e gives it";
+    }, {
+        readonly name: "files";
+        readonly kind: "cfsPath";
+        readonly optional: true;
+        readonly repeat: true;
+        readonly glob: true;
+        readonly summary: "ChRIS files to read, in order (a wildcard matches paths; - is the pipe); the pipe when none is named";
+    }];
+    readonly options: {
+        readonly insensitive: {
+            readonly short: "i";
+            readonly long: "ignore-case";
+            readonly summary: "Ignore case";
+        };
+        readonly invert: {
+            readonly short: "v";
+            readonly long: "invert-match";
+            readonly summary: "Keep what does not match";
+        };
+        readonly word: {
+            readonly short: "w";
+            readonly long: "word-regexp";
+            readonly summary: "Whole words";
+        };
+        readonly extended: {
+            readonly short: "E";
+            readonly long: "extended-regexp";
+            readonly summary: "Extended regular expressions";
+        };
+        readonly fixed: {
+            readonly short: "F";
+            readonly long: "fixed-strings";
+            readonly summary: "Fixed strings";
+        };
+        readonly count: {
+            readonly short: "c";
+            readonly long: "count";
+            readonly summary: "Count only";
+        };
+        readonly regexp: {
+            readonly short: "e";
+            readonly long: "regexp";
+            readonly repeat: true;
+            readonly value: {
+                readonly name: "pattern";
+                readonly kind: "word";
+            };
+            readonly summary: "A pattern (repeatable: any of them matches)";
+        };
+        readonly lineNumber: {
+            readonly short: "n";
+            readonly long: "line-number";
+            readonly summary: "Each line's number (text and files)";
+        };
+        readonly filesWithMatches: {
+            readonly short: "l";
+            readonly long: "files-with-matches";
+            readonly summary: "Only the names of files with a match";
+        };
+        readonly onlyMatching: {
+            readonly short: "o";
+            readonly long: "only-matching";
+            readonly summary: "Only the matching parts, one per line";
+        };
+        readonly noFilename: {
+            readonly short: "h";
+            readonly long: "no-filename";
+            readonly summary: "No file-name prefix";
+        };
+        readonly withFilename: {
+            readonly short: "H";
+            readonly long: "with-filename";
+            readonly summary: "The file-name prefix, even for one file";
+        };
+        readonly color: {
+            readonly long: "color";
+            readonly value: {
+                readonly name: "when";
+                readonly kind: "word";
+                readonly optional: true;
+            };
+            readonly summary: "Colour the matches (always, never, auto): the system grep colours; the session's own grep writes plain text";
+        };
+        readonly recursive: {
+            readonly short: "r";
+            readonly long: "recursive";
+            readonly summary: "Walk each folder for files (. when none is named)";
+        };
+        readonly after: {
+            readonly short: "A";
+            readonly long: "after-context";
+            readonly value: {
+                readonly name: "N";
+                readonly kind: "int";
+                readonly min: 0;
+            };
+            readonly summary: "N lines after each match";
+        };
+        readonly before: {
+            readonly short: "B";
+            readonly long: "before-context";
+            readonly value: {
+                readonly name: "N";
+                readonly kind: "int";
+                readonly min: 0;
+            };
+            readonly summary: "N lines before each match";
+        };
+        readonly context: {
+            readonly short: "C";
+            readonly long: "context";
+            readonly value: {
+                readonly name: "N";
+                readonly kind: "int";
+                readonly min: 0;
+            };
+            readonly summary: "N lines around each match";
+        };
+    };
+}>;
+/**
+ * Builds the expression a line (or a row's text) is matched by: any of the
+ * patterns, read as grep reads them under -F, -E or neither, -w and -i.
+ *
+ * @param ask - What the grep line asks of a match.
+ * @returns The expression (not global), or a refusal when a pattern does not compile.
+ *
+ * @example
+ * ```ts
+ * grepExpression_build({ ...ask, patterns: ['t1\\|t2'] }); // /(?:t1|t2)/
+ * ```
  */
-export declare function grepArgs_parse(args: ReadonlyArray<string>): GrepAsk;
+export declare function grepExpression_build(ask: GrepAsk): RegExp | {
+    refused: string;
+};
 /**
  * Builds the test a line (or a row's text) passes.
  *
- * @param ask - What the grep line asks.
+ * @param ask - What the grep line asks of a match.
  * @returns The test, or a refusal when a pattern does not compile.
+ *
+ * @example
+ * ```ts
+ * const matches = grepMatcher_build({ ...ask, patterns: ['T1'], word: true });
+ * ```
  */
 export declare function grepMatcher_build(ask: GrepAsk): ((text: string) => boolean) | {
     refused: string;
@@ -39,10 +241,42 @@ export declare function grepMatcher_build(ask: GrepAsk): ((text: string) => bool
  * @returns The kept rows, in order.
  */
 export declare function listingRows_grep(rows: ReadonlyArray<AnswerRow>, matches: (text: string) => boolean, invert: boolean): AnswerRow[];
+/** What a grep over text wrote, and how many lines it kept. */
+interface GrepAnswer {
+    /** The output. */
+    readonly text: string;
+    /** Lines selected over every source, for the exit status. */
+    readonly selected: number;
+}
+/**
+ * The lines a grep over text writes for its sources, as GNU grep writes
+ * them: `name:` before each line when named, `N:` under -n (`-` for a
+ * context line), `--` between groups apart under -A, -B or -C; -l the
+ * names with a match, -c a count each, -o the matching parts.
+ *
+ * @param expression - The match, compiled.
+ * @param ask - What the line asks of a match.
+ * @param layout - How it writes what it kept.
+ * @param sources - The texts, under the names shown.
+ * @param named - Whether each line is under its file's name.
+ * @returns The output and how many lines were kept.
+ *
+ * @example
+ * ```ts
+ * textSources_grep(/b/, ask, GREP_LAYOUT_PLAIN, [{ name: null, text: 'a\nb\n' }], false).text; // 'b\n'
+ * ```
+ */
+export declare function textSources_grep(expression: RegExp, ask: GrepAsk, layout: GrepLayout, sources: ReadonlyArray<FilterSource>, named: boolean): GrepAnswer;
 /**
- * `grep [-ivwEFc] [-e PATTERN]... [PATTERN]`
+ * `grep` over words already split: the declaration's parse and handler.
  *
  * @param args - The words after `grep`.
- * @returns The envelope.
+ * @returns The envelope, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_grep(['-i', 't1']);
+ * ```
  */
 export declare function builtin_grep(args: string[]): Promise<CommandEnvelope>;
+export {};