How liam-ilan/crumb works
Project type and purpose
• This is an interpreter for the Crumb programming language, written in C. It implements a full interpreter pipeline (lexing, parsing, AST, evaluation), a functional standard library, and a CLI. It also provides a “Loaf” template for building standalone binaries from Crumb programs.
File structure
• Top-level
• src/: all C modules of the interpreter
• examples/: sample .crumb programs
• loaf-template/: template.crumb used by Loaf to generate C code
• src/ modules
• main.c – CLI entry point
• file.c/.h – file I/O primitives
• lex.c/.h, tokens.c/.h
– lexical analysis, token definitions
• parse.c/.h, ast.c/.h
– parser, AST node representation
• eval.c/.h, run.c/.h
– AST evaluation, execution engine
• scope.c/.h – dynamic scopes/environments
• stdlib.c/.h – built-in functions (IO, math, list, string, events)
• generic.c/.h, list.c/.h, string.c/.h
– core data types & operations
• events.c/.h – terminal event handling
• Configuration and build
• .gitignore
• README.md (project overview, syntax, stdlib docs)
Extract architectural clues from README
• Interpreter pipeline: code → tokens → AST → evaluator
• Dynamic typing, garbagecollection, dynamic scoping
• Standard library implemented as native C functions
• Loaf: uses loaf-template/template.crumb to generate a C “main.c” that wraps crumb interpreter + program entry
a. Main components
• CLI / Entry Point (main.c)
• File Loader (file module)
• Lexer (lex + tokens)
• Parser (parse)
• AST Model (ast)
• Evaluator / Runtime (eval + run)
• Scope Manager (scope)
• Standard Library (stdlib + generic + list + string + events)
• Garbage Collector (implicit within evaluator modules)
• Loaf Templating (loaf-template)
• Examples / User Code (.crumb files)
b. Relationships & Data Flow
1. User invokes “./crumb program.crumb”
2. main.c calls File Loader → source text
3. Lexer tokenizes text → token stream
4. Parser consumes token stream → AST
5. Evaluator traverses AST, consults Scope Manager → executes nodes
6. Evaluator calls into Standard Library modules for I/O, list, string operations, events
7. Results produce stdout/events, may read/write files or spawn shell
8. Loaf: template.crumb + used_files feed into template_main → generates C code → compiled with src/*.c into standalone binary
c. Architectural patterns & design principles
• Interpreter pipeline (classic compiler front-end + interpreter back-end)
• Modular decomposition by concern (lexing, parsing, AST, evaluation, stdlib)
• Dynamic scoping via central Scope Manager
• Functional core: all language constructs are functions; no side effects except I/O
• Extensibility: stdlib and loaftemplate can be extended or replaced
d. Key technologies, frameworks, libraries
• C99 (gcc, -Wall, -g, -lm)
• Valgrind, macOS leaks for debugging
• ANSI escape codes for terminal events