From 6eb14b64209b9d24554c587f610d7e300ef809ea Mon Sep 17 00:00:00 2001 From: salmonik Date: Sat, 1 Aug 2026 13:14:07 +0200 Subject: shell: keyword redirection + post-filter flags (ADR 0002) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implement the shell experience redesign: one canonical grammar for every command — 'cmd args [USE src] [TIL marker] [filters...] [output kw dst]'. - Keyword redirection (uppercase-only, aliases valid, fully reserved): WRITING/WRITE overwrite, TO append, USE/USING input source, TIL/UNTIL heredoc/terminator (exact full-line marker). > >> < << are removed; '>' is plain text. - Post-filter stages applied left to right over a line stream, each repeatable: -h N (head kills the upstream), -t N (tail holds a rolling window, flushes at EOF/^C), -g PAT (smart-case literal substring), -p (screenful pager, terminal only). A file sink replaces the screen; -p is a no-op with one. - C-style quoting: "..." groups and literalizes, \x escapes one char; quoted/escaped text is never an operator, never split. - Input consumers: cat/hexdump, path-less only (stdin until ^D, USE f, TIL m heredoc, USE f TIL m truncation). Other commands reject input keywords; paths + input keyword is a syntax error. - ^D is EOF everywhere and never powers off; poweroff/exit are the only shutdown verbs. - help rewritten; test-disk.sh and sendkeys.py use the keyword syntax. Verified in QEMU: 26 grammar checks on fresh and reused disks, disk round trip, pager pacing, -h stopping /dev/mem at N lines, ^C flushing a -t window. Two bugs found during verification and fixed: 1. WRITING over an existing file wrote after stale NUL padding — fs::size() is stale after set_len(0); the sink writes at offset 0 after truncation. 2. USE f TIL m leaked the post-marker remainder — the final partial-line emit ran after the marker break; guarded with a stopped flag. --- .../0002-keyword-redirection-and-post-filters.md | 76 ++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 docs/adr/0002-keyword-redirection-and-post-filters.md (limited to 'docs/adr') diff --git a/docs/adr/0002-keyword-redirection-and-post-filters.md b/docs/adr/0002-keyword-redirection-and-post-filters.md new file mode 100644 index 0000000..1584077 --- /dev/null +++ b/docs/adr/0002-keyword-redirection-and-post-filters.md @@ -0,0 +1,76 @@ +# ADR 0002 — Keyword Redirection and Post-Filter Flags Instead of Pipes + +## Status + +Accepted. + +## Context + +The shell (a freestanding, no_std kernel component) needs the data-flow +features every shell has: redirecting command output to files, feeding +input from files or typed blocks, and trimming output to `head`/`tail`/ +`grep`/pager views. The obvious model — Unix pipes plus `> < << >>` +operators — was considered and rejected. The project is explicitly +not POSIX-compatible, is TempleOS-inspired, and values minimal machinery +and natural-language-flavoured input over familiarity. The old shell +had only an ad-hoc `>`/`>>` parse baked into `cmd_echo`, no head/tail/ +grep at all, and ^D at the prompt powered the machine off. + +## Decision + +One canonical command-line grammar, applied uniformly to every command: + +``` +cmd args [USE src] [TIL marker] [filters…] [output kw dst] +``` + +- **Redirection uses reserved uppercase keywords**, never symbols: + `WRITING`/`WRITE` overwrite, `TO` appends, `USE`/`USING` names the + input source, `TIL`/`UNTIL` truncates the input at an exact full-line + marker (marker and everything after it is discarded). At most one + input keyword (USE and TIL may pair, USE first) and one output + keyword; input keywords precede the filters, the output keyword + comes last. +- **Filters are trailing flags** applied left to right as stages over a + line stream: `-h N` (emit first N lines, then kill the upstream + command), `-t N` (hold back a rolling window of the last N lines; + emit only when the stream ends — EOF or ^C, which flushes), + `-g PAT` (smart-case literal substring match: case-insensitive unless + PAT contains an uppercase letter), `-p` (pause at each screenful, + `more`-style, only when output exceeds one screenful). Every flag + may repeat; each instance is another stage. After `-g`, the next + token is the pattern verbatim. +- **There are no pipes.** The four built-in filters cover the cases + pipes are usually built for; arbitrary command composition is + deliberately out of scope. +- **`> >> < <<` are removed** — `>` is now ordinary text. The shell + prints to both GOP and serial; a file sink replaces terminal output + entirely. +- **^D is EOF everywhere and no longer powers off** (^C keeps its + line-cancel / stream-abort role; `poweroff`/`exit` are the only + shutdown verbs). +- **Quoting (`"..."` groups and literalizes, `\x` escapes one char)** + is the escape hatch: quoted/escaped text is never an operator, which + makes keywords expressible as data and enables spaces in filenames. + +## Consequences + +- **Positive:** One grammar, one parser — the per-command redirection + hacks (`cmd_echo`'s `>` scan) disappear. Filters compose uniformly + with any command and with each other, including intermediate views + (`-h N -p -g pat -p` shows each stage's result). No pipe machinery, + no process/stream abstraction to build. Lowercase text can never + collide with operators, so ordinary words stay ordinary. +- **Positive:** `tail` on an infinite stream (`cat /dev/mem -g 100 + -t 10`) is expressible without a pipe; ^C flushes the held-back + window instead of losing it. +- **Negative:** Breaks existing muscle memory and tooling: POSIX users + must learn the keywords; `scripts/test-disk.sh` and the `help` text + must be rewritten from `echo >` to the keyword syntax. +- **Negative:** Keywords are reserved, so printing text like `WRITING` + requires quoting; unknown commands cannot be filtered with flags + beyond the four built-ins; there is no way to compose arbitrary + commands (accepted — the shell has no external commands today). +- **Negative:** `-t` on a stream that never ends shows nothing until + the user ^C's — an intentional trade-off for simplicity (no pager + machinery, no infinite buffering beyond the window). -- cgit v1.2.3