Home /Modules/sleela-terminal/ARCHITECTURE.md

ARCHITECTURE.md

sleela-terminal/ARCHITECTURE.md · 262 line(s) · markdown

SleelaTerminal™ shell — architecture

SleelaTerminal™ is an original command shell (see 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

        ┌─────────────────────────────────────────────┐
   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

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):
    TierOperatorsAssoc
    1||left
    2&&left
    3== !=left
    4< <= > >=left
    5+ -left
    6* / %left
    7unary + - !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:

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:

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 "<script>", a script file argument, or an interactive read-eval-print loop. The driver enters M5 first and then delegates ordinary text to lex → parse → execute.

Testing

The existing smoke target exercises the M1–M4 layers. m5-smoke.sh adds integration checks for a select menu, <(...), >(...), and a USR1 trap. The GitHub Actions workflow .github/workflows/sleela-terminal-m5.yml builds the shell and runs both smoke layers on changes to sleela-terminal.

Milestones

M2 layer touch-points

LayerM2 addition
L1 coreNodeKind::{For,Case,FunctionDef}, CaseItem, function table + positional params on Environment
L2 lexerfor/in/case/esac keywords; ( ) { } tokens; $( … ) command-sub word spans; structural-keyword recognition
L3 parserparseFor, parseCase, parseFunctionDef, parseBraceGroup
L4 expansioncommand substitution (via a CommandRunner callback → no L4→L5 cycle), field splitting, globPattern/globMatch, $1../$@/$#
L5 executorexecFor, execCase, execFunctionDef, callFunction (scoped positionals), captureCommand for $( … ), multi-field argv

M3 layer touch-points

LayerM3 addition
L1 coreRedirOp::Heredoc + Redirection.body/expand_body; Tok::{DLess,DLessDash,HeredocBody}
L2 lexer<< / <<- here-doc capture (delimiter + body lines, tab-stripping, quoted-delimiter flag); {/} only structural when standalone (so x{1,2} stays one word)
L3 parserhere-doc redirection (delimiter + body token); strips the expand/literal flag
L4 expansionbraceExpand ( {a,b} / {m..n}, cartesian ), tildeExpand (~/~user via getpwnam), parameter operators ${x:-/:=/:+/:?} and ${#x} (env is now mutable for :=)
L5 executorhere-doc body piped to stdin (expanded per expand_body); functions/builtins run correctly as pipeline stages

M4 layer touch-points

LayerM4 addition
L1 coreNodeKind::Until; Tok::{Amp,Bang}; Node.child_async (per-list-child & flag) and Node.negated (pipeline !); Environment::Job + job table (addJob/jobs/findJob/removeJob); loop-control signal (requestBreak/requestContinue/consumeLoopSignal)
L2 lexeruntil opener; & → Tok::Amp (background); bare ! at command-start → Tok::Bang; both are command-start positions
L3 parserparseUntil; parseList treats & as an async separator; parsePipeline consumes a leading ! (wrapping a lone command in a negated Pipeline); newline allowed after do
L4 expansion(unchanged — M4 adds no new word syntax)
L5 executorexecUntil; async children in execList (fork + register job + [id] pid); pipeline negation; loop-signal consumption in execWhile/execUntil/execFor/execList; builtins jobs/fg/bg/wait, test/[, read, getopts, break/continue

M5 layer touch-points

LayerM5 addition
L6 orchestrationm5.hpp / m5.cpp; M5 callback boundary; select loop; FIFO process substitution; async-safe signal capture
L4 expansionExisting component-by-component filesystem globbing is treated as the M5 multi-segment pathname capability
L5 execution boundaryM5 delegates nested commands back through the normal lex → parse → execute runner; no duplicate executor is introduced
Testsm5-smoke.sh and .github/workflows/sleela-terminal-m5.yml