# SleelaTerminal™ shell — architecture SleelaTerminal™ is an **original** command shell (see [`NOTICE`](NOTICE)): a clean-room implementation, guided by public POSIX-shell *specifications* and the *ideas* common to shells, not by copying any existing shell's source. It aims at the same excellent capabilities as a mature shell — pipelines, redirections, quoting, expansion, control flow, functions, builtins, arithmetic — expressed through our own hierarchical, math-driven architecture. ## Design goals 1. **Hierarchical.** A strict layer stack; each layer depends only on the ones below it. No cycles, clean interfaces, testable in isolation. 2. **Math-driven.** Parsing and evaluation are grounded in explicit formal models: a token grammar, a precedence-climbing arithmetic evaluator, and an AST with well-defined evaluation rules — not ad-hoc string munging. 3. **Well-structured C++ (C++17).** Value types for the model, `std::variant`/ enums for node kinds, small focused translation units, no external deps. 4. **Original + attributed.** Ours to brand SleelaTerminal™; the ideas are POSIX-shell common knowledge, the code is new. ## The layer stack ```text ┌─────────────────────────────────────────────┐ L6 │ CLI / M5 orchestration │ │ · select menus, process substitution │ │ · signal trap registration/dispatch │ ├─────────────────────────────────────────────┤ L5 │ Executor run the AST │ │ · pipelines, redirections, exit status │ │ · control flow (if/while/until/for/case) │ │ · background jobs (&) + job-control │ │ · builtins registry │ ├─────────────────────────────────────────────┤ L4 │ Expansion words → strings │ │ · parameter/variable, quote removal │ │ · arithmetic $(( … )) via the Arith engine │ │ · pathname globbing across path segments │ ├─────────────────────────────────────────────┤ L3 │ Parser tokens → AST │ │ · recursive descent, one grammar per node │ ├─────────────────────────────────────────────┤ L2 │ Lexer text → tokens │ │ · words, quoting, operators, comments │ ├─────────────────────────────────────────────┤ L1 │ Core model shared types │ │ · Token, Word, AST nodes, Value │ │ · Arith engine (own precedence climber) │ │ · Environment (variables + exit status) │ └─────────────────────────────────────────────┘ ``` Dependencies point **downward only** for the core shell layers. The M5 driver is an orchestration boundary at L6: it can allocate operating-system resources (FIFOs/processes) and register signal handlers before delegating ordinary shell text to the established L1–L5 runner. Nothing in the parser or expansion layer depends on M5. ## L1 — Core model - **`Value`** — a shell value (string with an integer view for arithmetic). - **`Token`** — `{ kind, text }`; kinds: `Word`, `Assign`, `Pipe`, `Semi`, `Newline`, `Less`, `Great`, `DGreat`, `LParen`, `RParen`, `And`, `Or`, keywords (`If/Then/Elif/Else/Fi/While/Do/Done`), `Eof`. - **AST nodes** (a small, closed set): - `SimpleCommand` — assignments + words + redirections. - `Pipeline` — a list of commands joined by `|`. - `AndOr` — pipelines joined by `&&` / `||`. - `List` — commands separated by `;` / newline. - `IfClause`, `WhileClause` — control flow with body `List`s. - `Redirection` — `{ op, fd, target }`. - **`Environment`** — variable map, exit status `$?`, working directory. ## L1 — the arithmetic engine (math-driven core) A self-contained integer expression evaluator used by `$(( … ))` and the shell's own numeric needs. Two stages: 1. **Arith lexer** — numbers, identifiers, and operators `+ - * / % ( ) < <= > >= == != && || ! unary±`. 2. **Precedence-climbing evaluator** — a single recursive routine parameterised by binding power, giving correct precedence and associativity without a hand-written cascade of grammar functions. Precedence tiers (low→high): | Tier | Operators | Assoc | |---|---|---| | 1 | `\|\|` | left | | 2 | `&&` | left | | 3 | `== !=` | left | | 4 | `< <= > >=` | left | | 5 | `+ -` | left | | 6 | `* / %` | left | | 7 | unary `+ - !` | right | | 8 | `( )`, integer literal, variable | — | Division/modulo by zero is a reported error, not undefined behaviour. ## L2 — Lexer Text → `Token` stream. Handles single quotes (literal), double quotes (expansion-eligible span), operator recognition with maximal munch (`>` vs `>>`, `&` vs `&&`, `|` vs `||`), comments (`#` to end of line), and `name=value` assignment recognition at command-word position. Line/column tracking for diagnostics. ## L3 — Parser Recursive descent, one function per grammar production, producing the AST: ```text list := andor ( (';' | '\n') andor )* andor := pipeline ( ('&&' | '||') pipeline )* pipeline := command ( '|' command )* command := if_clause | while_clause | simple_command simple := (assignment)* (word | redirection)+ if := 'if' list 'then' list ('elif' list 'then' list)* ['else' list] 'fi' while := 'while' list 'do' list 'done' ``` Parse errors are structured (`{message, line, col}`), never crashes. ## L4 — Expansion Turns parsed words into final argument strings: variable/parameter expansion (`$name`, `${name}`), arithmetic expansion (`$(( expr ))` via the Arith engine), and quote removal — each as a distinct, ordered pass. Pure and testable: `(word, environment) → string`. Pathname globbing is implemented as a filesystem walk over path components. A pattern such as `src/*/include/*.hpp` is therefore resolved one component at a time rather than treating the entire path as one basename match. If no path matches, the original pattern is preserved (nullglob-off behaviour). ## L5 — Executor Evaluates the AST against an `Environment`: - **Simple command:** apply assignments, expand words, then dispatch to a **builtin** (registry lookup) or an **external** program (via `posix_spawn`/ `fork`+`execvp`), applying redirections. - **Pipeline:** wire stdout→stdin across children; exit status is the last. - **AndOr:** short-circuit on `$?`. - **Control flow:** `if`/`while` evaluate their condition `List` and branch on exit status (0 = true), matching shell truth semantics. - **Exit status** is a first-class value threaded through everything (`$?`). ## L6 — M5 orchestration `m5.cpp` is deliberately outside the normal grammar. It recognizes constructs that need operating-system resources or interactive state before ordinary lexing/parsing: ### `select` `select name in item...; do body; done` is handled by a small quote-aware M5 recognizer. The implementation prints a numbered menu to stderr, uses `PS3` as the prompt (default `#? `), stores the raw response in `REPLY`, assigns the selected item to `name`, and executes the body through the normal shell runner. `break` uses the existing M4 loop-control signal to leave the M5 loop. ### Process substitution `<(command)` and `>(command)` are represented by private FIFOs in `/tmp` with mode `0600`. A child shell executes the substitution command with a private `Environment` copy. FIFO startup uses a read/write descriptor in the child to avoid producer/consumer open deadlock. The resulting pathname is passed as ordinary command data; it is never reparsed as generated shell source. Child processes are waited for after the containing command completes. ### Signal traps Standalone `trap 'command' SIGNAL` declarations are consumed by M5 and mapped to a small signal-state table. The POSIX signal handler only records the signal number in `sig_atomic_t`; it never executes shell code from the asynchronous signal context. After the active shell command returns, M5 runs the registered trap action through the normal shell runner. Common signal names and numeric signals are accepted. M5 is intentionally conservative: it does not attempt to execute arbitrary shell code from a signal handler, and it does not replace the L1–L5 parser with a second general-purpose shell grammar. ## CLI / REPL `slsh` entry point: `-c "