ARCHITECTURE.md

Architecture

This project is a small POSIX shell implementation that is intentionally Unix/Linux-focused.

High-level flow

1. src/main.c initializes a ShellContext and loads history from $HISTFILE.
2. shell_repl_run() (in src/repl/repl.c) drives the REPL loop:
   • prints the prompt
   • reads a line with raw-mode editing (src/line_edit/line_edit.c)
   • stores the line in history (src/history/history.c)
   • tokenizes/parses into a pipeline (src/tokenizer/tokenizer.c, src/parser/parser.c)
   • executes builtins or external programs (src/builtins/builtins.c, src/exec/exec.c)

Module map

REPL

• include/shell/repl/repl.h
• src/repl/repl.c

Owns the interactive loop and glues modules together.

Line editing (raw mode)

• include/shell/line_edit/line_edit.h
• src/line_edit/line_edit.c

Implements a minimal readline-like UX using termios:

• character echo
• backspace
• up/down history navigation
• tab completion integration

History

• include/shell/history/history.h
• src/history/history.c

Owns:

• in-memory history list
• printing (with numeric indices)
• persistence: load/save/append (including tracking the last appended index)

Completion

• include/shell/completion/completion.h
• src/completion/completion.c

Owns TAB completion behavior:

• builtin completion for the first token
• PATH executable completion
• bell on first ambiguous TAB, list on second TAB

Tokenizer

• include/shell/tokenizer/tokenizer.h
• src/tokenizer/tokenizer.c

Tokenizes a command line in-place and implements the quote/backslash rules used by this shell.

Parser

• include/shell/parser/parser.h
• src/parser/parser.c

Builds a ShellPipeline by:

• splitting on |
• extracting per-command redirections

Redirections

• include/shell/redir/redir.h
• src/redir/redir.c

Extracts redirection tokens (>, >>, 2>, 2>>, etc.) and applies them via dup2().

Builtins

• include/shell/builtins/builtins.h
• src/builtins/builtins.c

Implements builtins:

• echo, pwd, cd, type, history, exit

Execution

• include/shell/exec/exec.h
• src/exec/exec.c

Runs external programs and pipelines:

• fork() / execv() / waitpid()
• pipe() wiring across stages
• builtin execution inside pipeline child processes

PATH resolution

• include/shell/path/path.h
• src/path/path.c

Finds executables either directly via / paths or by searching $PATH.