@fnndsc/brasa 0.56.1 → 0.56.3

package/dist/builtins/sys/textFilters.js

@@ -7,11 +7,26 @@
  * runs none, so `find /proc/jobs | wc -l` had nowhere to go. As builtins
  * these run on every surface, and none starts a process anywhere.
  *
- * Each reads what was piped in, else the files named (`-` is the
- * pipe), and takes the POSIX flags most lines use, with their meanings. A
- * flag it does not take is the system program's: the line goes there with
- * the piped text when the surface can run one, and is refused by name when
- * it cannot. `command wc` skips the builtin altogether.
+ * Each reads what was piped in, else the files named (`-` is the pipe), and
+ * takes the POSIX flags most lines use, with their meanings. Each is declared
+ * in one record, so a flag it does not take is refused by the parser before
+ * it runs; `command wc` skips the builtin and runs the system program.
+ *
+ * Key components:
+ * - wcCommand, headCommand, tailCommand, sortCommand, uniqCommand, cutCommand: the declarations.
+ * - builtin_wc … builtin_cut: each declaration run over words already split.
+ * - filter_run: reads the sources and answers them, for any filter; filterFile_read,
+ *   filterSources_read and filterRead_answer are its parts, which grep's files use too.
+ * - wc_render, head_lines, tail_lines, sort_lines, uniq_lines, cut_lines: the typed cores.
+ *
+ * Typical usage:
+ * ```ts
+ * await builtin_wc(['-l', 'notes.txt']);
+ * await builtin_head(['-5']);
+ * ```
+ *
+ * Dependencies: the session's filesystem (through the one store-path
+ * resolver) and what was piped in.
  *
  * @module
  */
@@ -19,30 +34,105 @@ import chalk from 'chalk';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
 import { errno_words } from '@fnndsc/fond';
 import { stdin_take } from '../games/stdin.js';
-import { surface_get } from '../../core/surface.js';
 import { vfsDispatcher_get } from '../../core/filesystem.js';
-import { path_resolve } from '../utils.js';
+import { storePath_resolve } from '../utils.js';
 import { exitCode_set } from '../../core/handlerRun.js';
-/** A whole number from a flag's argument, or null. */
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
+/**
+ * The file operand every filter but `uniq` takes.
+ *
+ * @example
+ * ```ts
+ * const GRAMMAR = { operands: [FILES_OPERAND] } as const satisfies CommandGrammar;
+ * ```
+ */
+export const FILES_OPERAND = {
+    name: 'files', kind: 'cfsPath', optional: true, repeat: true, glob: true,
+    summary: 'ChRIS files to read, in order (a wildcard matches paths; - is the pipe); the pipe when none is named',
+};
+/** What the posix pages say of each filter. */
+const POSIX_GROUP = 'Text';
+/**
+ * A whole number from a flag's argument, or null.
+ *
+ * @param word - The argument.
+ * @returns The number, or null when it is not digits.
+ */
 function count_parse(word) {
-    if (word === undefined || !/^\d+$/.test(word))
-        return null;
-    return Number(word);
+    return /^\d+$/.test(word) ? Number(word) : null;
 }
-/** The lines of a text, without the last line's newline. */
-function lines_split(text) {
+/**
+ * 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 function lines_split(text) {
     if (text === '')
         return [];
     return (text.endsWith('\n') ? text.slice(0, -1) : text).split('\n');
 }
-/** Lines written back as text, each ended by a newline. */
-function lines_join(lines) {
+/**
+ * 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 function lines_join(lines) {
     return lines.length === 0 ? '' : `${lines.join('\n')}\n`;
 }
-/** A word as a POSIX shell reads it back. */
-function word_quote(word) {
+/**
+ * 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 function word_quote(word) {
     return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
 }
+/**
+ * A filter's refusal: said on the error channel, the line's status 1.
+ *
+ * @param words - What was wrong.
+ * @returns The envelope.
+ */
+function filter_refuse(words) {
+    exitCode_set(1);
+    return envelope_error('', undefined, `${words}\n`);
+}
+/**
+ * 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 async function filterFile_read(command, operand) {
+    const target = await storePath_resolve(operand);
+    const read = await vfsDispatcher_get().read(target);
+    return read.ok ? { name: operand, text: read.value } : { error: `${command}: ${operand}: ${read.reason ?? errno_words(read.errno)}\n` };
+}
 /**
  * Reads what a filter works on: the files named, in order (`-` is the
  * pipe), else what was piped in.
@@ -50,8 +140,13 @@ function word_quote(word) {
  * @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', '-']);
+ * ```
  */
-async function sources_read(command, operands) {
+export async function filterSources_read(command, operands) {
     const piped = stdin_take();
     if (operands.length === 0) {
         if (piped === null)
@@ -65,123 +160,98 @@ async function sources_read(command, operands) {
             sources.push({ name: '-', text: piped ?? '' });
             continue;
         }
-        const target = await path_resolve(operand);
-        const read = await vfsDispatcher_get().read(target);
-        if (read.ok)
-            sources.push({ name: operand, text: read.value });
+        const read = await filterFile_read(command, operand);
+        if ('error' in read)
+            errors += read.error;
         else
-            errors += `${command}: ${operand}: ${read.reason ?? errno_words(read.errno)}\n`;
+            sources.push(read);
     }
     return { sources, errors };
 }
 /**
- * Runs a filter: a line it does not take goes to the system program, else
- * the sources are read and answered.
+ * A filter's answer over what it read: the output, with what could not be
+ * read on the error channel (exit 1).
  *
- * @param command - The filter's name.
- * @param args - The words after it.
- * @param parsed - What they ask.
+ * @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));
+ * ```
  */
-async function filter_run(command, args, parsed, answer) {
-    if (parsed.refused !== null) {
-        exitCode_set(1);
-        return envelope_error('', undefined, `${parsed.refused}\n`);
-    }
-    if (parsed.foreign !== null)
-        return foreign_run(command, args, parsed.foreign, parsed.operands);
-    const read = await sources_read(command, parsed.operands);
-    if ('refusal' in read) {
-        exitCode_set(1);
-        return envelope_error('', undefined, `${read.refusal}\n`);
-    }
+export function filterRead_answer(read, answer) {
     if (read.errors !== '')
         exitCode_set(1);
-    const out = read.sources.length > 0 || read.errors === '' ? answer(parsed.ask, read.sources) : '';
+    const out = read.sources.length > 0 || read.errors === '' ? answer(read.sources) : '';
     return read.errors === '' ? envelope_ok(out) : { ...envelope_ok(out), status: out === '' ? 'error' : 'ok', renderedErr: chalk.red(read.errors) };
 }
 /**
- * A line with a flag the builtin does not take: the system program's, fed
- * the piped text, where the surface runs one; refused by name where not.
+ * 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 args - The words after it.
- * @param flag - The flag not taken.
- * @param operands - The file operands (session paths, which a system program cannot read).
+ * @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 async function filter_run(command, files, answer) {
+    const read = await filterSources_read(command, files);
+    if ('refusal' in read)
+        return filter_refuse(read.refusal);
+    return filterRead_answer(read, answer);
+}
+/**
+ * Runs a filter once its options are read: a refusal is said, else the
+ * sources are answered.
+ *
+ * @param command - The filter's name.
+ * @param read - What its options ask, or why not.
+ * @param files - The file operands.
+ * @param answer - Turns what it asks and the sources into its output.
  * @returns The envelope.
  */
-async function foreign_run(command, args, flag, operands) {
-    const surface = surface_get();
-    const text = stdin_take();
-    if (!surface.capabilities.pipeSegments || operands.length > 0 || text === null) {
-        exitCode_set(1);
-        const why = operands.length > 0 || text === null
-            ? `the builtin does not take it, and a system ${command} cannot read the session's files`
-            : `the builtin does not take it, and this surface runs no system ${command} (command ${command} asks for one)`;
-        return envelope_error('', undefined, `${command}: ${flag}: ${why}\n`);
-    }
-    const out = await surface.pipeSegment(`${command} ${args.map(word_quote).join(' ')}`.trim(), Buffer.from(text, 'utf-8'));
-    return envelope_ok(out.toString('utf-8'));
-}
-/**
- * Reads short flags (`-lw`), each taking an argument attached or next
- * (`-n5`, `-n 5`), and operands; `--` ends the flags.
- *
- * @param args - The words.
- * @param takes - The flags without an argument.
- * @param withArg - The flags that take one.
- * @param long - Long flags to their short letter.
- * @returns The flags met (in order, with any argument), the operands, and a flag not taken.
- */
-function flags_read(args, takes, withArg, long = {}) {
-    const flags = [];
-    const operands = [];
-    let ended = false;
-    for (let i = 0; i < args.length; i++) {
-        const word = args[i];
-        if (ended || word === '-' || !word.startsWith('-')) {
-            operands.push(word);
-            continue;
-        }
-        if (word === '--') {
-            ended = true;
-            continue;
-        }
-        if (word.startsWith('--')) {
-            const [name, value] = (word.includes('=') ? [word.slice(0, word.indexOf('=')), word.slice(word.indexOf('=') + 1)] : [word, undefined]);
-            const letter = long[name];
-            if (letter === undefined)
-                return { flags, operands, foreign: word, missing: null };
-            if (withArg.includes(letter)) {
-                const arg = value ?? args[++i];
-                if (arg === undefined)
-                    return { flags, operands, foreign: null, missing: name };
-                flags.push([letter, arg]);
-            }
-            else {
-                flags.push([letter, undefined]);
-            }
-            continue;
-        }
-        for (let j = 1; j < word.length; j++) {
-            const letter = word[j];
-            if (withArg.includes(letter)) {
-                const rest = word.slice(j + 1);
-                const arg = rest !== '' ? rest : args[++i];
-                if (arg === undefined)
-                    return { flags, operands, foreign: null, missing: `-${letter}` };
-                flags.push([letter, arg]);
-                break;
-            }
-            if (!takes.includes(letter))
-                return { flags, operands, foreign: `-${letter}`, missing: null };
-            flags.push([letter, undefined]);
-        }
-    }
-    return { flags, operands, foreign: null, missing: null };
+async function askedFilter_run(command, read, files, answer) {
+    if ('refused' in read)
+        return filter_refuse(read.refused);
+    return filter_run(command, files, (sources) => answer(read.ask, sources));
 }
-/** Counts a text as `wc` does: newlines, words between blanks, bytes, characters. */
+/**
+ * Every line of every source, in order.
+ *
+ * @param sources - The sources.
+ * @returns Their lines.
+ */
+function sourceLines_list(sources) {
+    return sources.flatMap((s) => lines_split(s.text));
+}
+/** What a `wc` line may hold. */
+const WC_GRAMMAR = {
+    operands: [FILES_OPERAND],
+    options: {
+        lines: { short: 'l', long: 'lines', summary: 'Count lines' },
+        words: { short: 'w', long: 'words', summary: 'Count words' },
+        bytes: { short: 'c', long: 'bytes', summary: 'Count bytes' },
+        chars: { short: 'm', long: 'chars', summary: 'Count 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 function wc_count(text) {
     return {
         lines: (text.match(/\n/g) ?? []).length,
@@ -190,28 +260,18 @@ export function wc_count(text) {
         chars: [...text].length,
     };
 }
-/** Reads `wc`'s words. */
-export function wcArgs_parse(args) {
-    const read = flags_read(args, 'lwcm', '', { '--lines': 'l', '--words': 'w', '--bytes': 'c', '--chars': 'm' });
-    const ask = { lines: false, words: false, bytes: false, chars: false };
-    for (const [flag] of read.flags) {
-        if (flag === 'l')
-            ask.lines = true;
-        if (flag === 'w')
-            ask.words = true;
-        if (flag === 'c')
-            ask.bytes = true;
-        if (flag === 'm')
-            ask.chars = true;
-    }
-    if (!ask.lines && !ask.words && !ask.bytes && !ask.chars) {
-        ask.lines = true;
-        ask.words = true;
-        ask.bytes = true;
-    }
-    return { ask, operands: read.operands, foreign: read.foreign, refused: null };
-}
-/** `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 function wc_render(ask, sources) {
     const rows = sources.map((s) => ({ counts: wc_count(s.text), name: s.name }));
     if (rows.length > 1) {
@@ -228,92 +288,304 @@ export function wc_render(ask, sources) {
     const width = single ? 1 : Math.max(...rows.flatMap((r) => pick(r.counts).map((n) => String(n).length)));
     return lines_join(rows.map((r) => [...pick(r.counts).map((n) => String(n).padStart(width)), ...(r.name === null ? [] : [r.name])].join(' ')));
 }
-/** `wc [-lwcm] [FILE]...` */
+/**
+ * `wc [-lwcm] [FILE]...`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [wcCommand] });
+ * ```
+ */
+export const wcCommand = command_declare({
+    name: 'wc',
+    grammar: WC_GRAMMAR,
+    help: {
+        summary: 'Count lines, words and bytes',
+        description: 'Counts what is piped in, else each file named (- is the pipe), with a total for more than one. With no flag it counts lines, words and bytes; one count of the pipe prints the number alone. It runs in the session, on every surface; a flag it does not take is refused, and command wc runs the system wc.',
+        category: 'Files',
+        posix: { group: POSIX_GROUP, differs: 'as wc; a FILE is a ChRIS path' },
+        examples: ['find /proc/jobs -plugin pl-dylld | wc -l', 'wc -l notes.txt', 'cat a.csv | wc'],
+    },
+    holds: [],
+    handler: async (args) => {
+        const { lines, words, bytes, chars } = args.options;
+        const none = !lines && !words && !bytes && !chars;
+        const ask = none ? { lines: true, words: true, bytes: true, chars: false } : { lines, words, bytes, chars };
+        return filter_run('wc', args.operands.files, (sources) => wc_render(ask, sources));
+    },
+});
+/**
+ * `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 async function builtin_wc(args) {
-    return filter_run('wc', args, wcArgs_parse(args), wc_render);
-}
-/** Reads `head`'s or `tail`'s words: `-n N`, `-N`, and for head `-n -N`, for tail `-n +N`. */
-export function endsArgs_parse(command, args) {
-    const ask = { count: 10, butLast: false, fromLine: false };
-    // `-5` is `-n 5`, as both have always taken it.
-    const words = args.map((w, i) => (/^-\d+$/.test(w) && args[i - 1] !== '-n' && args[i - 1] !== '--lines' ? `-n${w.slice(1)}` : w));
-    const read = flags_read(words, '', 'n', { '--lines': 'n' });
-    if (read.missing !== null)
-        return { ask, operands: read.operands, foreign: null, refused: `${command}: ${read.missing} needs a number` };
-    for (const [, value] of read.flags) {
-        const raw = value ?? '';
-        const sign = raw.startsWith('-') || raw.startsWith('+') ? raw[0] : '';
-        const n = count_parse(sign === '' ? raw : raw.slice(1));
-        const signTaken = sign === '' || (command === 'head' && sign === '-') || (command === 'tail' && sign === '+');
-        if (n === null || !signTaken)
-            return { ask, operands: read.operands, foreign: null, refused: `${command}: -n takes a number${command === 'head' ? ' (-N: all but the last N)' : ' (+N: from line N)'}, not '${raw}'` };
-        ask.count = n;
-        ask.butLast = command === 'head' && sign === '-';
-        ask.fromLine = command === 'tail' && sign === '+';
+    return declaredCommand_run(wcCommand, args);
+}
+/** What a `head` line may hold. */
+const HEAD_GRAMMAR = {
+    operands: [FILES_OPERAND],
+    options: {
+        lines: {
+            short: 'n', long: 'lines', numeral: true, value: { name: 'count', kind: 'word' },
+            summary: 'The first N lines (-N says the same); -n -N: all but the last N',
+        },
+        bytes: { short: 'c', long: 'bytes', value: { name: 'count', kind: 'word' }, summary: 'The first N bytes; -c -N: all but the last N' },
+    },
+};
+/** What a `tail` line may hold. */
+const TAIL_GRAMMAR = {
+    operands: [FILES_OPERAND],
+    options: {
+        lines: {
+            short: 'n', long: 'lines', numeral: true, value: { name: 'count', kind: 'word' },
+            summary: 'The last N lines (-N says the same); -n +N: from line N to the end',
+        },
+        bytes: { short: 'c', long: 'bytes', value: { name: 'count', kind: 'word' }, summary: 'The last N bytes; -c +N: from byte N to the end' },
+        follow: { short: 'f', long: 'follow', summary: 'Taken: the text is read once and its last lines shown; a ChRIS file or a pipe is not followed' },
+    },
+};
+/** What tail says of -f, which it takes but cannot do. */
+const FOLLOW_NOTE = 'tail: -f: a ChRIS file or a pipe is not followed; its last lines are shown once';
+/**
+ * Reads `head`'s or `tail`'s count: N, and for head -N, for tail +N, of
+ * lines (-n) or bytes (-c).
+ *
+ * @param command - Which of the two.
+ * @param lines - The -n count as given, or undefined.
+ * @param bytes - The -c count as given, or undefined.
+ * @returns What it asks (ten lines when neither is given), or the refusal of a count that is not one.
+ */
+function endsAsk_read(command, lines, bytes) {
+    if (lines !== undefined && bytes !== undefined)
+        return { refused: `${command}: -n and -c do not mix; take one` };
+    const raw = bytes ?? lines;
+    const flag = bytes !== undefined ? '-c' : '-n';
+    if (raw === undefined)
+        return { ask: { count: 10, butLast: false, fromLine: false, bytes: false } };
+    const sign = raw.startsWith('-') || raw.startsWith('+') ? raw[0] : '';
+    const n = count_parse(sign === '' ? raw : raw.slice(1));
+    const signTaken = sign === '' || (command === 'head' && sign === '-') || (command === 'tail' && sign === '+');
+    if (n === null || !signTaken) {
+        const unit = bytes !== undefined ? 'byte' : 'line';
+        return { refused: `${command}: ${flag} takes a number${command === 'head' ? ' (-N: all but the last N)' : ` (+N: from ${unit} N)`}, not '${raw}'` };
     }
-    return { ask, operands: read.operands, foreign: read.foreign, refused: null };
+    return { ask: { count: n, butLast: command === 'head' && sign === '-', fromLine: command === 'tail' && sign === '+', bytes: bytes !== undefined } };
 }
-/** 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 function head_lines(ask, text) {
     const lines = lines_split(text);
     return ask.butLast ? lines.slice(0, Math.max(0, lines.length - ask.count)) : lines.slice(0, ask.count);
 }
-/** 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 function tail_lines(ask, text) {
     const lines = lines_split(text);
     if (ask.fromLine)
         return lines.slice(Math.max(0, ask.count - 1));
     return ask.count === 0 ? [] : lines.slice(-ask.count);
 }
-/** Each source's kept lines, under `==> name <==` when there is more than one. */
-function ends_render(keep) {
+/**
+ * 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 function head_bytes(ask, text) {
+    const all = Buffer.from(text, 'utf-8');
+    return (ask.butLast ? all.subarray(0, Math.max(0, all.length - ask.count)) : all.subarray(0, ask.count)).toString('utf-8');
+}
+/**
+ * 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 function tail_bytes(ask, text) {
+    const all = Buffer.from(text, 'utf-8');
+    if (ask.fromLine)
+        return all.subarray(Math.max(0, ask.count - 1)).toString('utf-8');
+    return (ask.count === 0 ? all.subarray(all.length) : all.subarray(-ask.count)).toString('utf-8');
+}
+/**
+ * Each source's kept part, under `==> name <==` when there is more than one.
+ *
+ * @param keepLines - The lines one source keeps.
+ * @param keepBytes - The bytes one source keeps.
+ * @returns The answer over the sources.
+ */
+function ends_render(keepLines, keepBytes) {
+    const keep = (ask, text) => (ask.bytes ? keepBytes(ask, text) : lines_join(keepLines(ask, text)));
     return (ask, sources) => {
         if (sources.length === 1)
-            return lines_join(keep(ask, sources[0].text));
-        return sources.map((s) => `==> ${s.name === '-' ? 'standard input' : s.name} <==\n${lines_join(keep(ask, s.text))}`).join('\n');
+            return keep(ask, sources[0].text);
+        return sources.map((s) => `==> ${s.name === '-' ? 'standard input' : s.name ?? ''} <==\n${keep(ask, s.text)}`).join('\n');
     };
 }
-/** `head [-n N | -N] [FILE]...` */
+/**
+ * `head [-n N | -N | -c N] [FILE]...`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [headCommand] });
+ * ```
+ */
+export const headCommand = command_declare({
+    name: 'head',
+    grammar: HEAD_GRAMMAR,
+    help: {
+        summary: 'The first lines',
+        description: 'Prints the first ten lines of what is piped in, else of each file named (under ==> name <== for more than one). -N is -n N; -n -N prints all but the last N; -c N prints the first N bytes. It runs in the session, on every surface; a flag it does not take is refused, and command head runs the system head.',
+        category: 'Files',
+        posix: { group: POSIX_GROUP, differs: 'as head; a FILE is a ChRIS path' },
+        examples: ['ls -l | head -n 5', 'head -3 notes.txt', 'head -c 100 notes.txt'],
+    },
+    holds: [],
+    handler: async (args) => askedFilter_run('head', endsAsk_read('head', args.options.lines, args.options.bytes), args.operands.files, ends_render(head_lines, head_bytes)),
+});
+/**
+ * `tail [-n N | -N | -n +N | -c N] [-f] [FILE]...`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [tailCommand] });
+ * ```
+ */
+export const tailCommand = command_declare({
+    name: 'tail',
+    grammar: TAIL_GRAMMAR,
+    help: {
+        summary: 'The last lines',
+        description: 'Prints the last ten lines of what is piped in, else of each file named (under ==> name <== for more than one). -N is -n N; -n +N prints from line N on; -c N prints the last N bytes, -c +N from byte N on. -f is taken but cannot follow: a ChRIS file or a pipe is read once and its last lines shown, and tail says so. It runs in the session, on every surface; a flag it does not take is refused, and command tail runs the system tail.',
+        category: 'Files',
+        posix: { group: POSIX_GROUP, differs: 'as tail; -f shows the last lines once, never follows; a FILE is a ChRIS path' },
+        examples: ['cat /proc/jobs/feed_12/pl-dircopy_40/log | tail -n 20', 'tail -n +2 a.csv', 'tail -c 64 notes.txt'],
+    },
+    holds: [],
+    handler: async (args) => {
+        const envelope = await askedFilter_run('tail', endsAsk_read('tail', args.options.lines, args.options.bytes), args.operands.files, ends_render(tail_lines, tail_bytes));
+        if (!args.options.follow || envelope.status !== 'ok')
+            return envelope;
+        return { ...envelope, renderedErr: `${envelope.renderedErr ?? ''}${chalk.gray(FOLLOW_NOTE)}\n` };
+    },
+});
+/**
+ * `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 async function builtin_head(args) {
-    return filter_run('head', args, endsArgs_parse('head', args), ends_render(head_lines));
+    return declaredCommand_run(headCommand, args);
 }
-/** `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 async function builtin_tail(args) {
-    return filter_run('tail', args, endsArgs_parse('tail', args), ends_render(tail_lines));
+    return declaredCommand_run(tailCommand, args);
 }
-/** Reads `sort`'s words. */
-export function sortArgs_parse(args) {
-    const ask = { reverse: false, numeric: false, fold: false, unique: false, key: null, separator: null };
-    const read = flags_read(args, 'rnfu', 'kt', {
-        '--reverse': 'r', '--numeric-sort': 'n', '--ignore-case': 'f', '--unique': 'u', '--key': 'k', '--field-separator': 't',
-    });
-    if (read.missing !== null)
-        return { ask, operands: read.operands, foreign: null, refused: `sort: ${read.missing} needs an argument` };
-    for (const [flag, value] of read.flags) {
-        if (flag === 'r')
-            ask.reverse = true;
-        if (flag === 'n')
-            ask.numeric = true;
-        if (flag === 'f')
-            ask.fold = true;
-        if (flag === 'u')
-            ask.unique = true;
-        if (flag === 't') {
-            if ((value ?? '').length !== 1)
-                return { ask, operands: read.operands, foreign: null, refused: `sort: -t takes one character, not '${value ?? ''}'` };
-            ask.separator = value;
-        }
-        if (flag === 'k') {
-            // A key's own options (-k2n, -k1.3) are the system sort's.
-            const key = /^(\d+)(?:,(\d+))?$/.exec(value ?? '');
-            if (key === null)
-                return { ask, operands: read.operands, foreign: `-k ${value ?? ''}`, refused: null };
-            ask.key = { from: Number(key[1]), to: key[2] === undefined ? null : Number(key[2]) };
+/** What a `sort` line may hold. */
+const SORT_GRAMMAR = {
+    operands: [FILES_OPERAND],
+    options: {
+        reverse: { short: 'r', long: 'reverse', summary: 'Reverse the order' },
+        numeric: { short: 'n', long: 'numeric-sort', summary: 'Compare by number' },
+        human: { short: 'h', long: 'human-numeric-sort', summary: 'Compare human sizes: 2K < 1M < 3G' },
+        version: { short: 'V', long: 'version-sort', summary: 'Compare versions: runs of digits as numbers (v2 < v10)' },
+        fold: { short: 'f', long: 'ignore-case', summary: 'Ignore case' },
+        unique: { short: 'u', long: 'unique', summary: 'One of each equal line' },
+        key: { short: 'k', long: 'key', value: { name: 'N[,M]', kind: 'word' }, summary: 'Compare fields N to M (to the end without M)' },
+        separator: { short: 't', long: 'field-separator', value: { name: 'C', kind: 'word' }, summary: 'Fields split at C, not at runs of blanks' },
+    },
+};
+/** The size suffixes `sort -h` reads, smallest first. */
+const HUMAN_SUFFIXES = 'KMGTPEZY';
+/**
+ * Reads `sort`'s options: its switches, a key of whole fields, a one-character separator.
+ *
+ * @param options - The typed options.
+ * @returns What they ask, or the refusal of a key, a separator or a mix of orders it does not take.
+ */
+function sortAsk_read(options) {
+    const orders = [
+        ...(options.numeric ? ['numeric'] : []), ...(options.human ? ['human'] : []), ...(options.version ? ['version'] : []),
+    ];
+    if (orders.length > 1)
+        return { refused: 'sort: -n, -h and -V do not mix; take one' };
+    const ask = { reverse: options.reverse, compare: orders[0] ?? 'text', fold: options.fold, unique: options.unique, key: null, separator: null };
+    if (options.separator !== undefined) {
+        if (options.separator.length !== 1)
+            return { refused: `sort: -t takes one character, not '${options.separator}'` };
+        ask.separator = options.separator;
+    }
+    if (options.key !== undefined) {
+        const key = /^(\d+)(?:,(\d+))?$/.exec(options.key);
+        if (key === null) {
+            return { refused: `sort: -k takes whole fields, N or N,M, not '${options.key}'; a key with its own options is the system sort's: command sort …` };
         }
+        ask.key = { from: Number(key[1]), to: key[2] === undefined ? null : Number(key[2]) };
     }
-    return { ask, operands: read.operands, foreign: read.foreign, refused: null };
+    return { ask };
 }
-/** The part of a line a sort compares. */
+/**
+ * The part of a line a sort compares.
+ *
+ * @param ask - How it orders.
+ * @param line - The line.
+ * @returns The key's text.
+ */
 function sortKey_extract(ask, line) {
     if (ask.key === null)
         return line;
@@ -321,18 +593,68 @@ function sortKey_extract(ask, line) {
     const to = ask.key.to ?? fields.length;
     return fields.slice(ask.key.from - 1, to).join(ask.separator ?? ' ');
 }
-/** The lines in `sort`'s order: stable, by key, numeric or text, then reversed, then unique by key. */
+/**
+ * Compares two keys by version: runs of digits as numbers, the rest as text.
+ *
+ * @param a - One key.
+ * @param b - The other.
+ * @returns Negative, zero or positive.
+ */
+function version_compare(a, b) {
+    const runsA = a.match(/\d+|\D+/g) ?? [];
+    const runsB = b.match(/\d+|\D+/g) ?? [];
+    for (let i = 0; i < Math.min(runsA.length, runsB.length); i++) {
+        const x = runsA[i];
+        const y = runsB[i];
+        if (x === y)
+            continue;
+        const digits = /^\d/.test(x) && /^\d/.test(y);
+        if (digits) {
+            const delta = BigInt(x) - BigInt(y);
+            if (delta !== 0n)
+                return delta < 0n ? -1 : 1;
+        }
+        return x < y ? -1 : 1;
+    }
+    return runsA.length - runsB.length;
+}
+/**
+ * Compares two keys as the sort asks.
+ *
+ * @param ask - How it orders.
+ * @param a - One key.
+ * @param b - The other.
+ * @returns Negative, zero or positive.
+ */
+function sortKeys_compare(ask, a, b) {
+    if (ask.compare === 'version')
+        return version_compare(a.key, b.key);
+    if (ask.compare === 'human' && a.rank !== b.rank)
+        return a.rank - b.rank;
+    if (ask.compare !== 'text' && a.num !== b.num)
+        return a.num - b.num;
+    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+}
+/**
+ * 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 function sort_lines(ask, lines) {
     const keyed = lines.map((line) => {
         const key = sortKey_extract(ask, line);
-        const num = Number(/^\s*-?\d+(?:\.\d+)?/.exec(key)?.[0] ?? 0);
-        return { line, key: ask.fold ? key.toLowerCase() : key, num };
+        const number = /^\s*(-?\d+(?:\.\d+)?)([a-zA-Z]?)/.exec(key);
+        const rank = HUMAN_SUFFIXES.indexOf((number?.[2] ?? '').toUpperCase()) + 1;
+        return { line, key: ask.fold ? key.toLowerCase() : key, num: Number(number?.[1] ?? 0), rank: (number?.[2] ?? '') === '' ? 0 : rank };
     });
-    const compare = (a, b) => {
-        if (ask.numeric && a.num !== b.num)
-            return a.num - b.num;
-        return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
-    };
+    const compare = (a, b) => sortKeys_compare(ask, a, b);
     keyed.sort((a, b) => (ask.reverse ? compare(b, a) : compare(a, b)));
     if (!ask.unique)
         return keyed.map((k) => k.line);
@@ -345,29 +667,63 @@ export function sort_lines(ask, lines) {
     }
     return out;
 }
-/** `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 const sortCommand = command_declare({
+    name: 'sort',
+    grammar: SORT_GRAMMAR,
+    help: {
+        summary: 'Lines in order',
+        description: 'Sorts the lines of what is piped in, else of the files named, stably: as text, or by number (-n), by human size (-h: 2K < 1M < 3G) or by version (-V: v2 < v10). -k compares fields N to M (to the end without M), split at -t C or at runs of blanks. It runs in the session, on every surface; a flag it does not take, or a key with its own options (-k2n), is refused, and command sort runs the system sort.',
+        category: 'Files',
+        posix: { group: POSIX_GROUP, differs: 'as sort, a key by whole fields; a FILE is a ChRIS path' },
+        examples: ['find /proc/jobs -status finishedWithError | sort', 'cat a.csv | sort -t , -k 2 -n', 'du -h | sort -h', 'ls | sort -V'],
+    },
+    holds: [],
+    handler: async (args) => askedFilter_run('sort', sortAsk_read(args.options), args.operands.files, (ask, sources) => lines_join(sort_lines(ask, sourceLines_list(sources)))),
+});
+/**
+ * `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 async function builtin_sort(args) {
-    return filter_run('sort', args, sortArgs_parse(args), (ask, sources) => lines_join(sort_lines(ask, sources.flatMap((s) => lines_split(s.text)))));
-}
-/** Reads `uniq`'s words; one input at most, as uniq takes. */
-export function uniqArgs_parse(args) {
-    const ask = { count: false, repeated: false, unique: false, fold: false };
-    const read = flags_read(args, 'cdui', '', { '--count': 'c', '--repeated': 'd', '--unique': 'u', '--ignore-case': 'i' });
-    for (const [flag] of read.flags) {
-        if (flag === 'c')
-            ask.count = true;
-        if (flag === 'd')
-            ask.repeated = true;
-        if (flag === 'u')
-            ask.unique = true;
-        if (flag === 'i')
-            ask.fold = true;
-    }
-    // A second operand is uniq's output file, written on the host: the system uniq's.
-    const foreign = read.foreign ?? (read.operands.length > 1 ? read.operands[1] : null);
-    return { ask, operands: read.operands, foreign, refused: null };
+    return declaredCommand_run(sortCommand, args);
 }
-/** Adjacent equal lines folded to one, as `uniq` does. */
+/** What a `uniq` line may hold: one input at most; a second operand, uniq's output file, is the system uniq's. */
+const UNIQ_GRAMMAR = {
+    operands: [{ name: 'file', kind: 'cfsPath', optional: true, glob: true, summary: 'A ChRIS file to read (- is the pipe); the pipe when none is named' }],
+    options: {
+        count: { short: 'c', long: 'count', summary: 'Prefix each with its count' },
+        repeated: { short: 'd', long: 'repeated', summary: 'Only repeated lines' },
+        unique: { short: 'u', long: 'unique', summary: 'Only lines never repeated' },
+        fold: { short: 'i', long: 'ignore-case', summary: 'Ignore case' },
+    },
+};
+/**
+ * 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 function uniq_lines(ask, lines) {
     const out = [];
     const same = (a, b) => (ask.fold ? a.toLowerCase() === b.toLowerCase() : a === b);
@@ -383,11 +739,62 @@ export function uniq_lines(ask, lines) {
     }
     return out;
 }
-/** `uniq [-cdui] [FILE]` */
+/**
+ * `uniq [-cdui] [FILE]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [uniqCommand] });
+ * ```
+ */
+export const uniqCommand = command_declare({
+    name: 'uniq',
+    grammar: UNIQ_GRAMMAR,
+    help: {
+        summary: 'Fold adjacent equal lines to one',
+        description: 'Folds each run of equal adjacent lines to one, of what is piped in or of one file. Sort first to fold every equal line. It runs in the session, on every surface; a flag it does not take, or an output file, is refused, and command uniq runs the system uniq.',
+        category: 'Files',
+        posix: { group: POSIX_GROUP, differs: 'as uniq, without an output file; a FILE is a ChRIS path' },
+        examples: ['cut -d , -f 1 a.csv | sort | uniq -c', 'ls | uniq'],
+    },
+    holds: [],
+    handler: async (args) => {
+        const ask = { count: args.options.count, repeated: args.options.repeated, unique: args.options.unique, fold: args.options.fold };
+        const files = args.operands.file === undefined ? [] : [args.operands.file];
+        return filter_run('uniq', files, (sources) => lines_join(uniq_lines(ask, sourceLines_list(sources))));
+    },
+});
+/**
+ * `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 async function builtin_uniq(args) {
-    return filter_run('uniq', args, uniqArgs_parse(args), (ask, sources) => lines_join(uniq_lines(ask, sources.flatMap((s) => lines_split(s.text)))));
+    return declaredCommand_run(uniqCommand, args);
 }
-/** Reads a cut LIST: `1,3`, `2-4`, `3-`, `-2`. */
+/** What a `cut` line may hold. */
+const CUT_GRAMMAR = {
+    operands: [FILES_OPERAND],
+    options: {
+        fields: { short: 'f', long: 'fields', value: { name: 'LIST', kind: 'word' }, summary: 'Keep these fields' },
+        chars: { short: 'c', long: 'characters', value: { name: 'LIST', kind: 'word' }, summary: 'Keep these characters' },
+        bytes: { short: 'b', long: 'bytes', value: { name: 'LIST', kind: 'word' }, summary: 'Keep these characters (as -c)' },
+        delimiter: { short: 'd', long: 'delimiter', value: { name: 'C', kind: 'word' }, summary: 'The field delimiter (a tab when not said)' },
+        onlyDelimited: { short: 's', long: 'only-delimited', summary: 'Only lines that hold the delimiter' },
+    },
+};
+/**
+ * Reads a cut LIST: `1,3`, `2-4`, `3-`, `-2`.
+ *
+ * @param list - The LIST.
+ * @returns Its ranges, or null when it is not one.
+ */
 function cutList_parse(list) {
     const ranges = [];
     for (const part of list.split(',')) {
@@ -402,37 +809,43 @@ function cutList_parse(list) {
     }
     return ranges;
 }
-/** Reads `cut`'s words. */
-export function cutArgs_parse(args) {
-    const ask = { by: 'fields', ranges: [], delimiter: '\t', onlyDelimited: false };
-    const read = flags_read(args, 's', 'fcbd', { '--fields': 'f', '--characters': 'c', '--bytes': 'b', '--delimiter': 'd', '--only-delimited': 's' });
-    if (read.missing !== null)
-        return { ask, operands: read.operands, foreign: null, refused: `cut: ${read.missing} needs an argument` };
-    let listed = false;
-    for (const [flag, value] of read.flags) {
-        if (flag === 's')
-            ask.onlyDelimited = true;
-        if (flag === 'd') {
-            if ((value ?? '').length !== 1)
-                return { ask, operands: read.operands, foreign: null, refused: `cut: -d takes one character, not '${value ?? ''}'` };
-            ask.delimiter = value;
-        }
-        if (flag === 'f' || flag === 'c' || flag === 'b') {
-            if (listed)
-                return { ask, operands: read.operands, foreign: null, refused: 'cut: only one of -f, -c or -b' };
-            const ranges = cutList_parse(value ?? '');
-            if (ranges === null)
-                return { ask, operands: read.operands, foreign: null, refused: `cut: a list is N, N-M, N- or -M joined by commas, not '${value ?? ''}'` };
-            ask.by = flag === 'f' ? 'fields' : 'chars';
-            ask.ranges = ranges;
-            listed = true;
-        }
+/**
+ * Reads `cut`'s options: one LIST, of fields or characters, and a one-character delimiter.
+ *
+ * @param options - The typed options.
+ * @returns What they ask, or the refusal of a list or delimiter it does not take.
+ */
+function cutAsk_read(options) {
+    const ask = { by: 'fields', ranges: [], delimiter: '\t', onlyDelimited: options.onlyDelimited };
+    if (options.delimiter !== undefined) {
+        if (options.delimiter.length !== 1)
+            return { refused: `cut: -d takes one character, not '${options.delimiter}'` };
+        ask.delimiter = options.delimiter;
     }
-    if (!listed && read.foreign === null)
-        return { ask, operands: read.operands, foreign: null, refused: 'cut: say what to keep: -f LIST (fields) or -c LIST (characters)' };
-    return { ask, operands: read.operands, foreign: read.foreign, refused: null };
+    const lists = [
+        ...(options.fields !== undefined ? [{ by: 'fields', list: options.fields }] : []),
+        ...(options.chars !== undefined ? [{ by: 'chars', list: options.chars }] : []),
+        ...(options.bytes !== undefined ? [{ by: 'chars', list: options.bytes }] : []),
+    ];
+    if (lists.length > 1)
+        return { refused: 'cut: only one of -f, -c or -b' };
+    const chosen = lists[0];
+    if (chosen === undefined)
+        return { refused: 'cut: say what to keep: -f LIST (fields) or -c LIST (characters)' };
+    const ranges = cutList_parse(chosen.list);
+    if (ranges === null)
+        return { refused: `cut: a list is N, N-M, N- or -M joined by commas, not '${chosen.list}'` };
+    ask.by = chosen.by;
+    ask.ranges = ranges;
+    return { ask };
 }
-/** The positions a cut keeps of `n`, in order, each once. */
+/**
+ * The positions a cut keeps of `n`, in order, each once.
+ *
+ * @param ask - What it keeps.
+ * @param n - How many fields or characters the line has.
+ * @returns The positions, 1-based.
+ */
 function cutPositions_derive(ask, n) {
     const kept = new Set();
     for (const range of ask.ranges)
@@ -440,7 +853,18 @@ function cutPositions_derive(ask, n) {
             kept.add(i);
     return [...kept].sort((a, b) => a - b);
 }
-/** 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 function cut_lines(ask, lines) {
     const out = [];
     for (const line of lines) {
@@ -459,8 +883,39 @@ export function cut_lines(ask, lines) {
     }
     return out;
 }
-/** `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 const cutCommand = command_declare({
+    name: 'cut',
+    grammar: CUT_GRAMMAR,
+    help: {
+        summary: 'Keep fields or characters of each line',
+        description: 'Keeps the fields (split at -d C, a tab when not said) or the characters LIST names, of each line piped in or of the files named. A LIST is N, N-M, N- or -M, joined by commas; -b is -c. -s drops a line with no delimiter. It runs in the session, on every surface; a flag it does not take is refused, and command cut runs the system cut.',
+        category: 'Files',
+        posix: { group: POSIX_GROUP, differs: 'as cut, -b as -c; a FILE is a ChRIS path' },
+        examples: ['cut -d , -f 1,3 a.csv', 'ls | cut -c 1-8'],
+    },
+    holds: [],
+    handler: async (args) => askedFilter_run('cut', cutAsk_read(args.options), args.operands.files, (ask, sources) => lines_join(cut_lines(ask, sourceLines_list(sources)))),
+});
+/**
+ * `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 async function builtin_cut(args) {
-    return filter_run('cut', args, cutArgs_parse(args), (ask, sources) => lines_join(cut_lines(ask, sources.flatMap((s) => lines_split(s.text)))));
+    return declaredCommand_run(cutCommand, args);
 }
 //# sourceMappingURL=textFilters.js.map