@fnndsc/brasa 0.56.1 → 0.56.3

package/dist/builtins/sys/grep.js

@@ -9,111 +9,164 @@
  * wore — `@SER41` stays `@SER41`. The kept rows become the held listing, so
  * `gather add @SER41` and `${listing}` read what grep left.
  *
- * It takes grep's own flags only, with grep's meanings: -i -v -w -E -F -c
- * and -e. Anything else (or a file operand) is the system grep's business,
- * and the whole line goes there as text, said in one line. Plain text in is
- * always the system grep where the surface can run it; `command grep` skips
- * this builtin altogether.
+ * It takes grep's flags with grep's meanings: -i -v -w -E -F -c -e, and for
+ * text and files -n -l -o -h -r -A -B -C, which a listing (whole rows) has no
+ * use for and refuses by name. It is declared in one record, so any other
+ * flag is refused by the parser. A file named is a ChRIS path, read through
+ * the one store-path resolver (a folder walked under -r) and filtered here,
+ * named as typed. Plain text in is the system grep where the surface can run
+ * it, its line written back from the typed options, and filtered here where
+ * it cannot; `command grep` skips this builtin altogether.
+ *
+ * Key components:
+ * - grepCommand: the declaration.
+ * - builtin_grep: the declaration run over words already split.
+ * - grepExpression_build, grepMatcher_build: the expression, and the test a line passes.
+ * - textSources_grep: the lines a grep over text writes, as GNU grep writes them.
+ * - listingRows_grep: the rows a grep keeps of a listing.
+ *
+ * Typical usage:
+ * ```ts
+ * await builtin_grep(['-i', 't1']);
+ * await builtin_grep(['-c', 'todo', 'notes.txt']);
+ * ```
+ *
+ * Dependencies: the held and piped listings, the session's filesystem (via
+ * the text filters' reader), and the surface's system grep.
  *
  * @module
  */
 import chalk from 'chalk';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
 import { stdin_take } from '../games/stdin.js';
+import { errorStack, errno_words } from '@fnndsc/fond';
+import { filterFile_read, filterRead_answer, filterSources_read, FILES_OPERAND, lines_join, lines_split, word_quote, } from './textFilters.js';
+import { storePath_resolve } from '../utils.js';
+import { vfsDispatcher_get } from '../../core/filesystem.js';
+import { itemType_isContainer } from '../../core/itemKinds.js';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
 import { listingIn_take } from '../../core/listing.js';
 import { answerKinds_get } from '../../core/answerKinds.js';
 import { surface_get } from '../../core/surface.js';
 import { answer_get, answerFilter_apply, answerNumbering_derive, answerOrdinals_attach, answerRow_key, answerRows_derive, handle_word, numberedFooter_render, } from '../../session/answer.js';
 import { exitCode_set } from '../../core/handlerRun.js';
-/** grep's long flags this grep takes, to their short form. */
-const LONG_FLAGS = {
-    '--ignore-case': 'i', '--invert-match': 'v', '--word-regexp': 'w',
-    '--extended-regexp': 'E', '--fixed-strings': 'F', '--count': 'c',
+/**
+ * The layout of a grep line that asks none: lines as they are.
+ *
+ * @example
+ * ```ts
+ * const layout: GrepLayout = { ...GREP_LAYOUT_PLAIN, onlyMatching: true };
+ * ```
+ */
+export const GREP_LAYOUT_PLAIN = {
+    lineNumber: false, filesWithMatches: false, onlyMatching: false, noFilename: false, withFilename: false, recursive: false,
+    after: undefined, before: undefined, context: undefined, color: undefined,
+};
+/** The switches of a grep line, as the line writes them back. */
+const GREP_SWITCHES = [
+    { letter: 'i', on: (ask) => ask.insensitive },
+    { letter: 'v', on: (ask) => ask.invert },
+    { letter: 'w', on: (ask) => ask.word },
+    { letter: 'E', on: (ask) => ask.extended },
+    { letter: 'F', on: (ask) => ask.fixed },
+    { letter: 'c', on: (ask) => ask.count },
+    { letter: 'n', on: (_ask, layout) => layout.lineNumber },
+    { letter: 'l', on: (_ask, layout) => layout.filesWithMatches },
+    { letter: 'o', on: (_ask, layout) => layout.onlyMatching },
+    { letter: 'h', on: (_ask, layout) => layout.noFilename },
+    { letter: 'H', on: (_ask, layout) => layout.withFilename },
+    { letter: 'r', on: (_ask, layout) => layout.recursive },
+];
+/** The layout flags a numbered listing has no use for, each with why, as grep says it. */
+const LISTING_REFUSALS = [
+    { flag: '-n', given: (layout) => layout.lineNumber, why: 'a listing\'s rows wear their handles, not line numbers' },
+    { flag: '-l', given: (layout) => layout.filesWithMatches, why: 'a listing is not files to name' },
+    { flag: '-o', given: (layout) => layout.onlyMatching, why: 'a listing keeps whole rows' },
+    { flag: '-h', given: (layout) => layout.noFilename, why: 'a listing has no file names to drop' },
+    { flag: '-H', given: (layout) => layout.withFilename, why: 'a listing has no file names to show' },
+    { flag: '-r', given: (layout) => layout.recursive, why: 'a listing is not a folder to walk' },
+    { flag: '-A', given: (layout) => layout.after !== undefined, why: 'a listing keeps a row with its group, not lines after it' },
+    { flag: '-B', given: (layout) => layout.before !== undefined, why: 'a listing keeps a row with its group, not lines before it' },
+    { flag: '-C', given: (layout) => layout.context !== undefined, why: 'a listing keeps a row with its group, not lines around it' },
+];
+/** What a `grep` line may hold. */
+const GREP_GRAMMAR = {
+    operands: [
+        { name: 'pattern', kind: 'word', optional: true, unless: 'regexp', summary: 'The pattern, unless -e gives it' },
+        FILES_OPERAND,
+    ],
+    options: {
+        insensitive: { short: 'i', long: 'ignore-case', summary: 'Ignore case' },
+        invert: { short: 'v', long: 'invert-match', summary: 'Keep what does not match' },
+        word: { short: 'w', long: 'word-regexp', summary: 'Whole words' },
+        extended: { short: 'E', long: 'extended-regexp', summary: 'Extended regular expressions' },
+        fixed: { short: 'F', long: 'fixed-strings', summary: 'Fixed strings' },
+        count: { short: 'c', long: 'count', summary: 'Count only' },
+        regexp: { short: 'e', long: 'regexp', repeat: true, value: { name: 'pattern', kind: 'word' }, summary: 'A pattern (repeatable: any of them matches)' },
+        lineNumber: { short: 'n', long: 'line-number', summary: 'Each line\'s number (text and files)' },
+        filesWithMatches: { short: 'l', long: 'files-with-matches', summary: 'Only the names of files with a match' },
+        onlyMatching: { short: 'o', long: 'only-matching', summary: 'Only the matching parts, one per line' },
+        noFilename: { short: 'h', long: 'no-filename', summary: 'No file-name prefix' },
+        withFilename: { short: 'H', long: 'with-filename', summary: 'The file-name prefix, even for one file' },
+        color: { long: 'color', value: { name: 'when', kind: 'word', optional: true }, summary: 'Colour the matches (always, never, auto): the system grep colours; the session\'s own grep writes plain text' },
+        recursive: { short: 'r', long: 'recursive', summary: 'Walk each folder for files (. when none is named)' },
+        after: { short: 'A', long: 'after-context', value: { name: 'N', kind: 'int', min: 0 }, summary: 'N lines after each match' },
+        before: { short: 'B', long: 'before-context', value: { name: 'N', kind: 'int', min: 0 }, summary: 'N lines before each match' },
+        context: { short: 'C', long: 'context', value: { name: 'N', kind: 'int', min: 0 }, summary: 'N lines around each match' },
+    },
 };
 /**
- * Reads a grep line's words.
+ * `grep [-ivwEFcnlohr] [-A N] [-B N] [-C N] [-e PATTERN]... [PATTERN] [FILE]...`: the declaration.
  *
- * @param args - The words after `grep`.
- * @returns What they ask.
+ * @example
+ * ```ts
+ * commands_register({ declarations: [grepCommand] });
+ * ```
  */
-export function grepArgs_parse(args) {
-    const ask = { insensitive: false, invert: false, word: false, extended: false, fixed: false, count: false, patterns: [], foreign: null };
-    const operands = [];
-    const flag = (letter) => {
-        if (letter === 'i')
-            ask.insensitive = true;
-        else if (letter === 'v')
-            ask.invert = true;
-        else if (letter === 'w')
-            ask.word = true;
-        else if (letter === 'E')
-            ask.extended = true;
-        else if (letter === 'F')
-            ask.fixed = true;
-        else if (letter === 'c')
-            ask.count = true;
-        else
-            return false;
-        return true;
-    };
-    for (let at = 0; at < args.length; at++) {
-        const word = args[at] ?? '';
-        if (word === '--') {
-            operands.push(...args.slice(at + 1));
-            break;
-        }
-        if (word === '-e' || word === '--regexp') {
-            const pattern = args[at + 1];
-            if (pattern === undefined) {
-                ask.foreign = word;
-                break;
-            }
-            ask.patterns.push(pattern);
-            at += 1;
-            continue;
-        }
-        if (word.startsWith('--regexp=')) {
-            ask.patterns.push(word.slice('--regexp='.length));
-            continue;
-        }
-        if (word.startsWith('--')) {
-            const short = LONG_FLAGS[word];
-            if (short === undefined) {
-                ask.foreign ??= word;
-                continue;
-            }
-            flag(short);
-            continue;
-        }
-        if (word.startsWith('-') && word.length > 1) {
-            // Clustered short flags: -vi. An -e inside a cluster takes the rest.
-            const letters = word.slice(1);
-            for (let index = 0; index < letters.length; index++) {
-                const letter = letters[index] ?? '';
-                if (letter === 'e') {
-                    const rest = letters.slice(index + 1);
-                    const pattern = rest !== '' ? rest : args[++at];
-                    if (pattern === undefined)
-                        ask.foreign ??= word;
-                    else
-                        ask.patterns.push(pattern);
-                    break;
-                }
-                if (!flag(letter)) {
-                    ask.foreign ??= `-${letter}`;
-                    break;
-                }
-            }
-            continue;
-        }
-        operands.push(word);
-    }
-    if (ask.patterns.length === 0 && operands.length > 0)
-        ask.patterns.push(operands.shift());
-    // A file to read is the system grep's: this one reads a listing or a pipe.
-    if (operands.length > 0)
-        ask.foreign ??= operands[0] ?? null;
-    return ask;
+export const grepCommand = command_declare({
+    name: 'grep',
+    grammar: GREP_GRAMMAR,
+    help: {
+        summary: 'Keep the lines, or the rows of a numbered listing, that match',
+        description: 'Filters text, or a numbered listing keeping its handles. Fed a numbered listing (piped in, or the held one when nothing is piped), grep keeps rows: a matching row stays with the rows above it, a matched group keeps all of its rows, and every kept row keeps its handle (@SER41 stays @SER41). What it kept becomes the listing @ and ${listing} name; -c counts and changes nothing. A pattern matches a study\'s and a patient\'s own text too: grep -i t1 meant for series descriptions keeps a WHOLE study whose description says t1, and grep -i "mri brain" picking whole studies is the same rule. A file named is a ChRIS path, read here (- is the pipe; a wildcard matches paths); with several, each line or count is under its file\'s name as typed. -r walks each folder named (. when none is) for its files; links met on the way are not followed. -n numbers lines, -l names the files with a match, -o keeps only the matching parts, -h drops the names and -H keeps them for one file, --color colours the matches of the system grep (this one writes plain text), and -A, -B and -C show lines after, before and around each match, groups apart by --; a listing keeps whole rows, so these are refused for one. Text piped in is the system grep where the surface runs one, else filtered here with the same flags. With -e every word after the options is a file. A flag it does not take is refused; command grep runs the system grep.',
+        category: 'Files',
+        posix: { group: 'Files', differs: 'also filters numbered listings, keeping their handles (help grep)' },
+        examples: [
+            'query PatientID:1234567,Modality:MR | grep -i t1 | grep -vi gadavist',
+            'grep -i -e t1 -e mprage',
+            'gather list | grep -i sag | gather remove',
+            'cat notes.txt | grep -c todo',
+            'grep -c error a.log b.log',
+            'grep -rn TODO notes',
+            'grep -C 2 error run.log',
+        ],
+    },
+    holds: [],
+    handler: async (args) => grep_run(args),
+});
+/**
+ * A grep line written back from what it asks: its switches, its context
+ * counts, then its patterns (each under -e when there are several, or one
+ * starts with a dash).
+ *
+ * @param ask - What the grep line asks of a match.
+ * @param layout - How it writes what it kept.
+ * @returns The line, `grep -i -v -n -A 2 -e t1 -e t2`.
+ */
+function grepLine_render(ask, layout) {
+    const switches = GREP_SWITCHES.filter(({ on }) => on(ask, layout)).map(({ letter }) => `-${letter}`);
+    const counts = [
+        ...(layout.after !== undefined ? ['-A', String(layout.after)] : []),
+        ...(layout.before !== undefined ? ['-B', String(layout.before)] : []),
+        ...(layout.context !== undefined ? ['-C', String(layout.context)] : []),
+        ...(layout.color === undefined ? [] : [layout.color === '' ? '--color' : `--color=${word_quote(layout.color)}`]),
+    ];
+    const lone = ask.patterns.length === 1 ? ask.patterns[0] : undefined;
+    const patterns = lone !== undefined && !lone.startsWith('-')
+        ? [word_quote(lone)]
+        : ask.patterns.flatMap((pattern) => ['-e', word_quote(pattern)]);
+    return ['grep', ...switches, ...counts, ...patterns].join(' ');
 }
 /**
  * A basic regular expression (grep's default) as a JavaScript one: in a BRE
@@ -139,24 +192,46 @@ function basic_convertToSource(pattern) {
     return out;
 }
 /**
- * Builds the test a line (or a row's text) passes.
+ * 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.
- * @returns The test, or a refusal when a pattern does not compile.
+ * @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 function grepMatcher_build(ask) {
+export function grepExpression_build(ask) {
     const sources = ask.patterns.map((pattern) => {
         const source = ask.fixed ? pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') : ask.extended ? pattern : basic_convertToSource(pattern);
         return ask.word ? `(?<![\\w])(?:${source})(?![\\w])` : `(?:${source})`;
     });
     try {
-        const expression = new RegExp(sources.join('|'), ask.insensitive ? 'i' : '');
-        return (text) => expression.test(text);
+        return new RegExp(sources.join('|'), ask.insensitive ? 'i' : '');
     }
     catch (error) {
         return { refused: `grep: ${error instanceof Error ? error.message : String(error)}` };
     }
 }
+/**
+ * Builds the test a line (or a row's text) passes.
+ *
+ * @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 function grepMatcher_build(ask) {
+    const built = grepExpression_build(ask);
+    if (!(built instanceof RegExp))
+        return built;
+    return (text) => built.test(text);
+}
 /**
  * Which rows a grep keeps of a listing: a matching row with its parents, a
  * matched group with all its rows; under -v the matching rows (and a
@@ -266,63 +341,275 @@ function listing_grep(listing, ask, line) {
     return envelope_ok(rendered, { kind: listing.kind, data: filtered });
 }
 /**
- * Plain grep on text: the system's, where the surface runs host programs;
- * otherwise this grep's own line filter, with the same flags.
+ * 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 function textSources_grep(expression, ask, layout, sources, named) {
+    const after = layout.after ?? layout.context ?? 0;
+    const before = layout.before ?? layout.context ?? 0;
+    const grouped = (after > 0 || before > 0) && !layout.onlyMatching;
+    const every = new RegExp(expression.source, `${expression.flags.replace('g', '')}g`);
+    const out = [];
+    let selected = 0;
+    let printedAny = false;
+    for (const source of sources) {
+        const name = source.name === '-' || source.name === null ? '(standard input)' : source.name;
+        const lines = lines_split(source.text);
+        const hits = lines.map((line) => expression.test(line) !== ask.invert);
+        const kept = hits.filter((hit) => hit).length;
+        selected += kept;
+        if (layout.filesWithMatches) {
+            if (kept > 0)
+                out.push(name);
+            continue;
+        }
+        if (ask.count) {
+            out.push(named ? `${name}:${kept}` : String(kept));
+            continue;
+        }
+        const prefix = (at, mark) => `${named ? `${name}${mark}` : ''}${layout.lineNumber ? `${at + 1}${mark}` : ''}`;
+        if (layout.onlyMatching) {
+            // Under -v the kept lines are those with no match: no part to show.
+            if (ask.invert)
+                continue;
+            lines.forEach((line, at) => {
+                for (const match of line.matchAll(every))
+                    if (match[0] !== '')
+                        out.push(`${prefix(at, ':')}${match[0]}`);
+            });
+            continue;
+        }
+        const shown = lines.map(() => false);
+        hits.forEach((hit, at) => {
+            if (!hit)
+                return;
+            for (let near = Math.max(0, at - before); near <= Math.min(lines.length - 1, at + after); near++)
+                shown[near] = true;
+        });
+        let last = -2;
+        lines.forEach((line, at) => {
+            if (!shown[at])
+                return;
+            if (grouped && printedAny && at !== last + 1)
+                out.push('--');
+            out.push(`${prefix(at, hits[at] === true ? ':' : '-')}${line}`);
+            printedAny = true;
+            last = at;
+        });
+    }
+    return { text: lines_join(out), selected };
+}
+/**
+ * Walks a folder for its files, depth first: each file read under its name
+ * as shown (the folder as typed, then the names below it). A link met on the
+ * way is not followed, as grep -r does not.
+ *
+ * @param store - The folder's store path.
+ * @param shown - The folder as the output names it; empty for the working directory unnamed.
+ * @param read - Where the files and the errors go.
+ */
+async function folder_walk(store, shown, read) {
+    const mark = errorStack.checkpoint_mark();
+    const listed = await vfsDispatcher_get().list(store);
+    errorStack.checkpoint_drain(mark);
+    if (!listed.ok) {
+        read.errors += `grep: ${shown || '.'}: cannot list the folder\n`;
+        return;
+    }
+    for (const item of listed.value) {
+        const childStore = store === '/' ? `/${item.name}` : `${store}/${item.name}`;
+        const childShown = shown === '' ? item.name : `${shown}/${item.name}`;
+        if (itemType_isContainer(item.type)) {
+            await folder_walk(childStore, childShown, read);
+            continue;
+        }
+        if (item.type === 'link')
+            continue;
+        const file = await vfsDispatcher_get().read(childStore);
+        if (file.ok)
+            read.sources.push({ name: childShown, text: file.value });
+        else
+            read.errors += `grep: ${childShown}: ${file.reason ?? errno_words(file.errno)}\n`;
+    }
+}
+/**
+ * Reads what grep -r works on: each operand a file, or a folder walked for
+ * its files (`-` is the pipe); no operand walks the working directory, its
+ * files named below it.
+ *
+ * @param operands - The operands, as typed.
+ * @returns The files read, under the names shown, and whether a folder was walked.
+ */
+async function recursiveSources_read(operands) {
+    const piped = stdin_take();
+    const read = { sources: [], errors: '', walked: false };
+    if (operands.length === 0) {
+        read.walked = true;
+        await folder_walk(await storePath_resolve('.'), '', read);
+        return read;
+    }
+    for (const operand of operands) {
+        if (operand === '-') {
+            read.sources.push({ name: '-', text: piped ?? '' });
+            continue;
+        }
+        const file = await filterFile_read('grep', operand);
+        if (!('error' in file)) {
+            read.sources.push(file);
+            continue;
+        }
+        const store = await storePath_resolve(operand);
+        const mark = errorStack.checkpoint_mark();
+        const listed = await vfsDispatcher_get().list(store);
+        errorStack.checkpoint_drain(mark);
+        if (!listed.ok) {
+            read.errors += file.error;
+            continue;
+        }
+        read.walked = true;
+        await folder_walk(store, operand.length > 1 ? operand.replace(/\/+$/, '') : operand, read);
+    }
+    return read;
+}
+/**
+ * grep over text it filters itself: ChRIS files (each read through the one
+ * store-path resolver, a folder walked under -r) or the piped text, named
+ * as typed.
+ *
+ * @param ask - What the grep line asks of a match.
+ * @param layout - How it writes what it kept.
+ * @param files - The file operands (`-` is the pipe); none, with text piped, for the pipe alone.
+ * @returns The envelope; exit 1 when no line was kept.
+ */
+async function sources_grep(ask, layout, files) {
+    const built = grepExpression_build(ask);
+    if (!(built instanceof RegExp)) {
+        exitCode_set(1);
+        return envelope_error('', undefined, `${built.refused}\n`);
+    }
+    let read;
+    if (layout.recursive) {
+        read = await recursiveSources_read(files);
+    }
+    else {
+        const plain = await filterSources_read('grep', files);
+        if ('refusal' in plain)
+            return envelope_error('', undefined, `${plain.refusal}\n`);
+        read = { ...plain, walked: false };
+    }
+    let selected = 0;
+    const envelope = filterRead_answer(read, (sources) => {
+        const named = layout.withFilename || (!layout.noFilename && (sources.length > 1 || read.walked));
+        const answer = textSources_grep(built, ask, layout, sources, named);
+        selected = answer.selected;
+        return answer.text;
+    });
+    if (selected === 0)
+        exitCode_set(1);
+    return envelope;
+}
+/**
+ * Plain grep on piped text: the system's, its line written back from the
+ * typed options, where the surface runs host programs; otherwise this
+ * grep's own filter, with the same flags.
  *
  * @param text - The text piped in.
- * @param ask - What the grep line asks.
- * @param args - The words after `grep`, for the system grep.
+ * @param ask - What the grep line asks of a match.
+ * @param layout - How it writes what it kept.
  * @returns The envelope.
  */
-async function text_grep(text, ask, args) {
+async function text_grep(text, ask, layout) {
     const surface = surface_get();
     if (surface.capabilities.pipeSegments) {
-        const out = await surface.pipeSegment(`grep ${args.map(word_quote).join(' ')}`, Buffer.from(text, 'utf-8'));
+        const out = await surface.pipeSegment(grepLine_render(ask, layout), Buffer.from(text, 'utf-8'));
         return envelope_ok(out.toString('utf-8'));
     }
-    if (ask.foreign !== null)
-        return envelope_error('', undefined, `grep ${ask.foreign}: this surface has no system grep to pass it to\n`);
-    const built = grepMatcher_build(ask);
-    if (typeof built !== 'function')
+    const built = grepExpression_build(ask);
+    if (!(built instanceof RegExp))
         return envelope_error('', undefined, `${built.refused}\n`);
-    const lines = text.replace(/\n$/, '').split('\n').filter((line) => built(line) !== ask.invert);
-    if (lines.length === 0)
+    const answer = textSources_grep(built, ask, layout, [{ name: null, text }], false);
+    if (answer.selected === 0)
         exitCode_set(1);
-    return envelope_ok(ask.count ? `${lines.length}\n` : lines.length > 0 ? `${lines.join('\n')}\n` : '');
+    return envelope_ok(answer.text);
 }
-/** A word as a POSIX shell reads it back. */
-function word_quote(word) {
-    return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
+/**
+ * The refusal of a layout flag a numbered listing has no use for, or null.
+ *
+ * @param layout - How the line asks to write what it kept.
+ * @returns The envelope that says so, or null when the line asks none.
+ */
+function listingLayout_refuse(layout) {
+    const refused = LISTING_REFUSALS.find(({ given }) => given(layout));
+    if (refused === undefined)
+        return null;
+    exitCode_set(1);
+    return envelope_error('', undefined, `grep ${refused.flag}: ${refused.why}\n`);
 }
 /**
- * `grep [-ivwEFc] [-e PATTERN]... [PATTERN]`
+ * The typed grep line run: the files named (or walked under -r), else a
+ * piped listing, else piped text, else the held listing.
  *
- * @param args - The words after `grep`.
+ * @param args - The typed line.
  * @returns The envelope.
  */
-export async function builtin_grep(args) {
-    const ask = grepArgs_parse(args);
-    const line = `grep ${args.map(word_quote).join(' ')}`.trim();
-    const piped = listingIn_take();
-    const text = stdin_take();
-    // A flag or a file this grep does not take: the system grep's, as text.
-    if (ask.foreign !== null) {
-        const answered = await text_grep(text ?? '', ask, args);
-        if (answered.status === 'ok') {
-            return { ...answered, renderedErr: `${chalk.gray(`grep ${ask.foreign}: passed to the system grep; the held listing is unchanged`)}\n` };
-        }
-        return answered;
-    }
+async function grep_run(args) {
+    const given = args.options.regexp;
+    const pattern = args.operands.pattern;
+    const files = args.operands.files;
+    const ask = {
+        insensitive: args.options.insensitive, invert: args.options.invert, word: args.options.word,
+        extended: args.options.extended, fixed: args.options.fixed, count: args.options.count,
+        patterns: given.length > 0 ? given : pattern === undefined ? [] : [pattern],
+    };
+    const layout = {
+        lineNumber: args.options.lineNumber, filesWithMatches: args.options.filesWithMatches, onlyMatching: args.options.onlyMatching,
+        noFilename: args.options.noFilename, withFilename: args.options.withFilename, recursive: args.options.recursive,
+        after: args.options.after, before: args.options.before, context: args.options.context, color: args.options.color,
+    };
     if (ask.patterns.length === 0)
         return envelope_error('', undefined, 'grep: a pattern to keep: grep [-ivwEFc] [-e PATTERN] PATTERN\n');
-    if (piped !== null)
-        return listing_grep({ ...piped, source: '' }, ask, line);
+    const piped = listingIn_take();
+    if (piped !== null && files.length === 0) {
+        stdin_take();
+        return listingLayout_refuse(layout) ?? listing_grep({ ...piped, source: '' }, ask, grepLine_render(ask, layout));
+    }
+    if (files.length > 0 || layout.recursive)
+        return sources_grep(ask, layout, files);
+    const text = stdin_take();
     if (text !== null)
-        return text_grep(text, ask, args);
+        return text_grep(text, ask, layout);
     // Nothing piped: the held listing, as an index reads it.
     const held = answer_get();
     if (held === null)
         return envelope_error('', undefined, 'grep: nothing to filter: pipe text or a listing in, or list something first (query, ls, gather list)\n');
-    return listing_grep({ kind: held.kind, data: held.data, source: held.source }, ask, line);
+    return listingLayout_refuse(layout) ?? listing_grep({ kind: held.kind, data: held.data, source: held.source }, ask, grepLine_render(ask, layout));
+}
+/**
+ * `grep` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `grep`.
+ * @returns The envelope, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_grep(['-i', 't1']);
+ * ```
+ */
+export async function builtin_grep(args) {
+    return declaredCommand_run(grepCommand, args);
 }
 //# sourceMappingURL=grep.js.map