@fnndsc/brasa 0.56.2 → 0.56.3

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

@@ -1,62 +1,451 @@
-import { CommandEnvelope } from '@fnndsc/menu';
-/** One text a filter reads: the pipe's, or a file's under its name. */
+import { type CommandEnvelope } from '@fnndsc/menu';
+/**
+ * One text a filter reads: the pipe's, or a file's under its name.
+ *
+ * @example
+ * ```ts
+ * const source: FilterSource = { name: 'notes.txt', text: 'a\nb\n' };
+ * ```
+ */
 export interface FilterSource {
     /** The operand as typed; null for the pipe. */
     name: string | null;
+    /** What it holds. */
     text: string;
 }
-/** A line's words read by one filter: what it asks, its operands, or what it does not take. */
-interface FilterParse<T> {
-    ask: T;
-    operands: string[];
-    /** A flag this builtin does not take: the line is the system program's. */
-    foreign: string | null;
-    /** A flag taken but given wrong: said by name. */
-    refused: string | null;
+/**
+ * The file operand every filter but `uniq` takes.
+ *
+ * @example
+ * ```ts
+ * const GRAMMAR = { operands: [FILES_OPERAND] } as const satisfies CommandGrammar;
+ * ```
+ */
+export declare const FILES_OPERAND: {
+    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";
+};
+/**
+ * The lines of a text, without the last line's newline.
+ *
+ * @param text - The text.
+ * @returns Its lines; none for the empty text.
+ *
+ * @example
+ * ```ts
+ * lines_split('a\nb\n'); // ['a', 'b']
+ * ```
+ */
+export declare function lines_split(text: string): string[];
+/**
+ * Lines written back as text, each ended by a newline.
+ *
+ * @param lines - The lines.
+ * @returns The text; empty for no lines.
+ *
+ * @example
+ * ```ts
+ * lines_join(['a', 'b']); // 'a\nb\n'
+ * ```
+ */
+export declare function lines_join(lines: ReadonlyArray<string>): string;
+/**
+ * A word as a POSIX shell reads it back.
+ *
+ * @param word - The word.
+ * @returns The word, quoted when the shell would read it otherwise.
+ *
+ * @example
+ * ```ts
+ * word_quote("it's"); // "'it'\\''s'"
+ * ```
+ */
+export declare function word_quote(word: string): string;
+/**
+ * What a filter read: the sources, in order, and what could not be read.
+ *
+ * @example
+ * ```ts
+ * const read: FilterRead = { sources: [{ name: 'a.txt', text: 'a\n' }], errors: 'wc: b.txt: no such file\n' };
+ * ```
+ */
+export interface FilterRead {
+    /** The texts read. */
+    sources: FilterSource[];
+    /** A line per operand that could not be read; empty when all were. */
+    errors: string;
 }
-/** What `wc` counts. */
+/**
+ * Reads one ChRIS file through the one store-path resolver, under its name as typed.
+ *
+ * @param command - The filter's name, for what it says.
+ * @param operand - The path as typed.
+ * @returns The source, or the line that says why it could not be read.
+ *
+ * @example
+ * ```ts
+ * await filterFile_read('wc', 'notes.txt'); // { name: 'notes.txt', text: '…' }
+ * ```
+ */
+export declare function filterFile_read(command: string, operand: string): Promise<FilterSource | {
+    error: string;
+}>;
+/**
+ * Reads what a filter works on: the files named, in order (`-` is the
+ * pipe), else what was piped in.
+ *
+ * @param command - The filter's name, for what it says.
+ * @param operands - The file operands.
+ * @returns The sources and what could not be read, or a refusal when there is nothing at all.
+ *
+ * @example
+ * ```ts
+ * await filterSources_read('wc', ['a.txt', '-']);
+ * ```
+ */
+export declare function filterSources_read(command: string, operands: ReadonlyArray<string>): Promise<FilterRead | {
+    refusal: string;
+}>;
+/**
+ * A filter's answer over what it read: the output, with what could not be
+ * read on the error channel (exit 1).
+ *
+ * @param read - What was read.
+ * @param answer - Turns the sources into the filter's output.
+ * @returns The envelope.
+ *
+ * @example
+ * ```ts
+ * filterRead_answer(read, (sources: FilterSource[]): string => wc_render(ask, sources));
+ * ```
+ */
+export declare function filterRead_answer(read: FilterRead, answer: (sources: FilterSource[]) => string): CommandEnvelope;
+/**
+ * Runs a filter: reads its sources and answers them; a file it cannot read
+ * is said by name, and the others are still answered.
+ *
+ * @param command - The filter's name.
+ * @param files - The file operands (`-` is the pipe); none for the pipe alone.
+ * @param answer - Turns the sources into the filter's output.
+ * @returns The envelope: the output, with what could not be read on the error channel.
+ *
+ * @example
+ * ```ts
+ * await filter_run('wc', ['notes.txt'], (sources: FilterSource[]): string => wc_render(ask, sources));
+ * ```
+ */
+export declare function filter_run(command: string, files: ReadonlyArray<string>, answer: (sources: FilterSource[]) => string): Promise<CommandEnvelope>;
+/**
+ * What `wc` counts.
+ *
+ * @example
+ * ```ts
+ * const ask: WcAsk = { lines: true, words: false, bytes: false, chars: false };
+ * ```
+ */
 export interface WcAsk {
+    /** Newlines. */
     lines: boolean;
+    /** Words between blanks. */
     words: boolean;
+    /** Bytes. */
     bytes: boolean;
+    /** Characters. */
     chars: boolean;
 }
-/** One source's counts. */
+/**
+ * One source's counts.
+ *
+ * @example
+ * ```ts
+ * const counts: WcCounts = wc_count('a b\n');
+ * ```
+ */
 export interface WcCounts {
+    /** Newlines. */
     lines: number;
+    /** Words between blanks. */
     words: number;
+    /** Bytes, in UTF-8. */
     bytes: number;
+    /** Characters. */
     chars: number;
 }
-/** Counts a text as `wc` does: newlines, words between blanks, bytes, characters. */
+/**
+ * Counts a text as `wc` does: newlines, words between blanks, bytes, characters.
+ *
+ * @param text - The text.
+ * @returns Its counts.
+ *
+ * @example
+ * ```ts
+ * wc_count('héllo\n'); // { lines: 1, words: 1, bytes: 7, chars: 6 }
+ * ```
+ */
 export declare function wc_count(text: string): WcCounts;
-/** Reads `wc`'s words. */
-export declare function wcArgs_parse(args: ReadonlyArray<string>): FilterParse<WcAsk>;
-/** `wc`'s answer: a row per source (and a total for more than one), counts in POSIX order. */
+/**
+ * `wc`'s answer: a row per source (and a total for more than one), counts in POSIX order.
+ *
+ * @param ask - What to count.
+ * @param sources - The sources.
+ * @returns The rows.
+ *
+ * @example
+ * ```ts
+ * wc_render({ lines: true, words: false, bytes: false, chars: false }, [{ name: null, text: 'a\n' }]); // '1\n'
+ * ```
+ */
 export declare function wc_render(ask: WcAsk, sources: ReadonlyArray<FilterSource>): string;
-/** `wc [-lwcm] [FILE]...` */
+/**
+ * `wc [-lwcm] [FILE]...`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [wcCommand] });
+ * ```
+ */
+export declare const wcCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        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 lines: {
+            readonly short: "l";
+            readonly long: "lines";
+            readonly summary: "Count lines";
+        };
+        readonly words: {
+            readonly short: "w";
+            readonly long: "words";
+            readonly summary: "Count words";
+        };
+        readonly bytes: {
+            readonly short: "c";
+            readonly long: "bytes";
+            readonly summary: "Count bytes";
+        };
+        readonly chars: {
+            readonly short: "m";
+            readonly long: "chars";
+            readonly summary: "Count characters";
+        };
+    };
+}>;
+/**
+ * `wc` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `wc`.
+ * @returns The counts, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_wc(['-l', 'notes.txt']);
+ * ```
+ */
 export declare function builtin_wc(args: string[]): Promise<CommandEnvelope>;
-/** How many lines `head` or `tail` keeps: the first or last N, all but the last N, or from line N on. */
+/**
+ * How much `head` or `tail` keeps: the first or last N lines (or bytes), all
+ * but the last N, or from line (or byte) N on.
+ *
+ * @example
+ * ```ts
+ * const ask: EndsAsk = { count: 5, butLast: false, fromLine: false, bytes: false };
+ * ```
+ */
 export interface EndsAsk {
+    /** N. */
     count: number;
+    /** head -n -N (or -c -N): all but the last N. */
     butLast: boolean;
+    /** tail -n +N (or -c +N): from line (or byte) N on. */
     fromLine: boolean;
+    /** -c: N counts bytes, not lines. */
+    bytes: boolean;
 }
-/** Reads `head`'s or `tail`'s words: `-n N`, `-N`, and for head `-n -N`, for tail `-n +N`. */
-export declare function endsArgs_parse(command: 'head' | 'tail', args: ReadonlyArray<string>): FilterParse<EndsAsk>;
-/** The lines `head` keeps of a text. */
+/**
+ * The lines `head` keeps of a text.
+ *
+ * @param ask - How many.
+ * @param text - The text.
+ * @returns The kept lines.
+ *
+ * @example
+ * ```ts
+ * head_lines({ count: 1, butLast: false, fromLine: false, bytes: false }, 'a\nb\n'); // ['a']
+ * ```
+ */
 export declare function head_lines(ask: EndsAsk, text: string): string[];
-/** The lines `tail` keeps of a text. */
+/**
+ * The lines `tail` keeps of a text.
+ *
+ * @param ask - How many.
+ * @param text - The text.
+ * @returns The kept lines.
+ *
+ * @example
+ * ```ts
+ * tail_lines({ count: 1, butLast: false, fromLine: false, bytes: false }, 'a\nb\n'); // ['b']
+ * ```
+ */
 export declare function tail_lines(ask: EndsAsk, text: string): string[];
-/** `head [-n N | -N] [FILE]...` */
+/**
+ * The bytes `head -c` keeps of a text, as text.
+ *
+ * @param ask - How many.
+ * @param text - The text.
+ * @returns The kept bytes.
+ *
+ * @example
+ * ```ts
+ * head_bytes({ count: 3, butLast: false, fromLine: false, bytes: true }, 'hello\n'); // 'hel'
+ * ```
+ */
+export declare function head_bytes(ask: EndsAsk, text: string): string;
+/**
+ * The bytes `tail -c` keeps of a text, as text.
+ *
+ * @param ask - How many.
+ * @param text - The text.
+ * @returns The kept bytes.
+ *
+ * @example
+ * ```ts
+ * tail_bytes({ count: 3, butLast: false, fromLine: false, bytes: true }, 'hello\n'); // 'lo\n'
+ * ```
+ */
+export declare function tail_bytes(ask: EndsAsk, text: string): string;
+/**
+ * `head [-n N | -N | -c N] [FILE]...`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [headCommand] });
+ * ```
+ */
+export declare const headCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        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 lines: {
+            readonly short: "n";
+            readonly long: "lines";
+            readonly numeral: true;
+            readonly value: {
+                readonly name: "count";
+                readonly kind: "word";
+            };
+            readonly summary: "The first N lines (-N says the same); -n -N: all but the last N";
+        };
+        readonly bytes: {
+            readonly short: "c";
+            readonly long: "bytes";
+            readonly value: {
+                readonly name: "count";
+                readonly kind: "word";
+            };
+            readonly summary: "The first N bytes; -c -N: all but the last N";
+        };
+    };
+}>;
+/**
+ * `tail [-n N | -N | -n +N | -c N] [-f] [FILE]...`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [tailCommand] });
+ * ```
+ */
+export declare const tailCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        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 lines: {
+            readonly short: "n";
+            readonly long: "lines";
+            readonly numeral: true;
+            readonly value: {
+                readonly name: "count";
+                readonly kind: "word";
+            };
+            readonly summary: "The last N lines (-N says the same); -n +N: from line N to the end";
+        };
+        readonly bytes: {
+            readonly short: "c";
+            readonly long: "bytes";
+            readonly value: {
+                readonly name: "count";
+                readonly kind: "word";
+            };
+            readonly summary: "The last N bytes; -c +N: from byte N to the end";
+        };
+        readonly follow: {
+            readonly short: "f";
+            readonly long: "follow";
+            readonly summary: "Taken: the text is read once and its last lines shown; a ChRIS file or a pipe is not followed";
+        };
+    };
+}>;
+/**
+ * `head` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `head`.
+ * @returns The lines, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_head(['-5', 'notes.txt']);
+ * ```
+ */
 export declare function builtin_head(args: string[]): Promise<CommandEnvelope>;
-/** `tail [-n N | -N | -n +N] [FILE]...` */
+/**
+ * `tail` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `tail`.
+ * @returns The lines, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_tail(['-n', '+2', 'a.csv']);
+ * ```
+ */
 export declare function builtin_tail(args: string[]): Promise<CommandEnvelope>;
-/** How `sort` orders. */
+/**
+ * How `sort` orders.
+ *
+ * @example
+ * ```ts
+ * const ask: SortAsk = { reverse: false, compare: 'numeric', fold: false, unique: false, key: { from: 2, to: null }, separator: ',' };
+ * ```
+ */
 export interface SortAsk {
+    /** Reverse the order. */
     reverse: boolean;
-    numeric: boolean;
+    /** How two keys compare: as text, by number (-n), by human size (-h, 2K < 1M), or by version (-V, digit runs as numbers). */
+    compare: 'text' | 'numeric' | 'human' | 'version';
+    /** Ignore case. */
     fold: boolean;
+    /** One of each equal line. */
     unique: boolean;
     /** The key's fields, 1-based, inclusive; null for the whole line. */
     key: {
@@ -66,26 +455,189 @@ export interface SortAsk {
     /** The field separator; null for runs of blanks. */
     separator: string | null;
 }
-/** Reads `sort`'s words. */
-export declare function sortArgs_parse(args: ReadonlyArray<string>): FilterParse<SortAsk>;
-/** The lines in `sort`'s order: stable, by key, numeric or text, then reversed, then unique by key. */
+/**
+ * The lines in `sort`'s order: stable, by key, as text, number, size or version, then reversed, then unique by key.
+ *
+ * @param ask - How it orders.
+ * @param lines - The lines.
+ * @returns The lines in order.
+ *
+ * @example
+ * ```ts
+ * sort_lines({ reverse: false, compare: 'human', fold: false, unique: false, key: null, separator: null }, ['1M', '2K']); // ['2K', '1M']
+ * ```
+ */
 export declare function sort_lines(ask: SortAsk, lines: ReadonlyArray<string>): string[];
-/** `sort [-rnfu] [-k N[,M]] [-t C] [FILE]...` */
+/**
+ * `sort [-rnhVfu] [-k N[,M]] [-t C] [FILE]...`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [sortCommand] });
+ * ```
+ */
+export declare const sortCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        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 reverse: {
+            readonly short: "r";
+            readonly long: "reverse";
+            readonly summary: "Reverse the order";
+        };
+        readonly numeric: {
+            readonly short: "n";
+            readonly long: "numeric-sort";
+            readonly summary: "Compare by number";
+        };
+        readonly human: {
+            readonly short: "h";
+            readonly long: "human-numeric-sort";
+            readonly summary: "Compare human sizes: 2K < 1M < 3G";
+        };
+        readonly version: {
+            readonly short: "V";
+            readonly long: "version-sort";
+            readonly summary: "Compare versions: runs of digits as numbers (v2 < v10)";
+        };
+        readonly fold: {
+            readonly short: "f";
+            readonly long: "ignore-case";
+            readonly summary: "Ignore case";
+        };
+        readonly unique: {
+            readonly short: "u";
+            readonly long: "unique";
+            readonly summary: "One of each equal line";
+        };
+        readonly key: {
+            readonly short: "k";
+            readonly long: "key";
+            readonly value: {
+                readonly name: "N[,M]";
+                readonly kind: "word";
+            };
+            readonly summary: "Compare fields N to M (to the end without M)";
+        };
+        readonly separator: {
+            readonly short: "t";
+            readonly long: "field-separator";
+            readonly value: {
+                readonly name: "C";
+                readonly kind: "word";
+            };
+            readonly summary: "Fields split at C, not at runs of blanks";
+        };
+    };
+}>;
+/**
+ * `sort` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `sort`.
+ * @returns The lines in order, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_sort(['-t', ',', '-k', '2', 'a.csv']);
+ * ```
+ */
 export declare function builtin_sort(args: string[]): Promise<CommandEnvelope>;
-/** What `uniq` keeps of each run of equal lines. */
+/**
+ * What `uniq` keeps of each run of equal lines.
+ *
+ * @example
+ * ```ts
+ * const ask: UniqAsk = { count: true, repeated: false, unique: false, fold: false };
+ * ```
+ */
 export interface UniqAsk {
+    /** Prefix each with its count. */
     count: boolean;
+    /** Only repeated lines. */
     repeated: boolean;
+    /** Only lines never repeated. */
     unique: boolean;
+    /** Ignore case. */
     fold: boolean;
 }
-/** Reads `uniq`'s words; one input at most, as uniq takes. */
-export declare function uniqArgs_parse(args: ReadonlyArray<string>): FilterParse<UniqAsk>;
-/** Adjacent equal lines folded to one, as `uniq` does. */
+/**
+ * Adjacent equal lines folded to one, as `uniq` does.
+ *
+ * @param ask - What it keeps.
+ * @param lines - The lines.
+ * @returns The kept lines.
+ *
+ * @example
+ * ```ts
+ * uniq_lines({ count: false, repeated: false, unique: false, fold: false }, ['a', 'a', 'b']); // ['a', 'b']
+ * ```
+ */
 export declare function uniq_lines(ask: UniqAsk, lines: ReadonlyArray<string>): string[];
-/** `uniq [-cdui] [FILE]` */
+/**
+ * `uniq [-cdui] [FILE]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [uniqCommand] });
+ * ```
+ */
+export declare const uniqCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "file";
+        readonly kind: "cfsPath";
+        readonly optional: true;
+        readonly glob: true;
+        readonly summary: "A ChRIS file to read (- is the pipe); the pipe when none is named";
+    }];
+    readonly options: {
+        readonly count: {
+            readonly short: "c";
+            readonly long: "count";
+            readonly summary: "Prefix each with its count";
+        };
+        readonly repeated: {
+            readonly short: "d";
+            readonly long: "repeated";
+            readonly summary: "Only repeated lines";
+        };
+        readonly unique: {
+            readonly short: "u";
+            readonly long: "unique";
+            readonly summary: "Only lines never repeated";
+        };
+        readonly fold: {
+            readonly short: "i";
+            readonly long: "ignore-case";
+            readonly summary: "Ignore case";
+        };
+    };
+}>;
+/**
+ * `uniq` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `uniq`.
+ * @returns The folded lines, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_uniq(['-c']);
+ * ```
+ */
 export declare function builtin_uniq(args: string[]): Promise<CommandEnvelope>;
-/** What `cut` keeps of each line. */
+/**
+ * What `cut` keeps of each line.
+ *
+ * @example
+ * ```ts
+ * const ask: CutAsk = { by: 'fields', ranges: [{ from: 1, to: 1 }], delimiter: ',', onlyDelimited: false };
+ * ```
+ */
 export interface CutAsk {
     /** Fields or characters. */
     by: 'fields' | 'chars';
@@ -94,14 +646,94 @@ export interface CutAsk {
         from: number;
         to: number | null;
     }>;
+    /** The field delimiter. */
     delimiter: string;
     /** With fields: drop a line that holds no delimiter. */
     onlyDelimited: boolean;
 }
-/** Reads `cut`'s words. */
-export declare function cutArgs_parse(args: ReadonlyArray<string>): FilterParse<CutAsk>;
-/** What `cut` keeps of each line. */
+/**
+ * What `cut` keeps of each line.
+ *
+ * @param ask - What it keeps.
+ * @param lines - The lines.
+ * @returns The kept parts, a line each (a line with no delimiter dropped under -s).
+ *
+ * @example
+ * ```ts
+ * cut_lines({ by: 'fields', ranges: [{ from: 2, to: 2 }], delimiter: ',', onlyDelimited: false }, ['a,b']); // ['b']
+ * ```
+ */
 export declare function cut_lines(ask: CutAsk, lines: ReadonlyArray<string>): string[];
-/** `cut -f LIST [-d C] [-s] | -c LIST [FILE]...` */
+/**
+ * `cut -f LIST [-d C] [-s] | -c LIST [FILE]...`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [cutCommand] });
+ * ```
+ */
+export declare const cutCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        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 fields: {
+            readonly short: "f";
+            readonly long: "fields";
+            readonly value: {
+                readonly name: "LIST";
+                readonly kind: "word";
+            };
+            readonly summary: "Keep these fields";
+        };
+        readonly chars: {
+            readonly short: "c";
+            readonly long: "characters";
+            readonly value: {
+                readonly name: "LIST";
+                readonly kind: "word";
+            };
+            readonly summary: "Keep these characters";
+        };
+        readonly bytes: {
+            readonly short: "b";
+            readonly long: "bytes";
+            readonly value: {
+                readonly name: "LIST";
+                readonly kind: "word";
+            };
+            readonly summary: "Keep these characters (as -c)";
+        };
+        readonly delimiter: {
+            readonly short: "d";
+            readonly long: "delimiter";
+            readonly value: {
+                readonly name: "C";
+                readonly kind: "word";
+            };
+            readonly summary: "The field delimiter (a tab when not said)";
+        };
+        readonly onlyDelimited: {
+            readonly short: "s";
+            readonly long: "only-delimited";
+            readonly summary: "Only lines that hold the delimiter";
+        };
+    };
+}>;
+/**
+ * `cut` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `cut`.
+ * @returns The kept parts, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_cut(['-d', ',', '-f', '1', 'a.csv']);
+ * ```
+ */
 export declare function builtin_cut(args: string[]): Promise<CommandEnvelope>;
-export {};