How beariish/bolt works
Project type and purpose
• Bolt is a compiler/interpreter project: a lightweight, embeddable programming language implemented in C, delivered as a static library plus a CLI.
• Purpose: parse, type-check, compile, and execute Bolt code in real time; expose embedding APIs for host applications; provide a small standard library; include a command-line REPL/compiler tool.
File structure
Top-level:
• bolt/ ← Core implementation (lexer, parser, compiler, runtime, GC, embedding API)
• boltstd/ ← Standard library modules (arrays, I/O, math, regex, etc.)
• bolt-cli/ ← Example CLI tool showing embedding and usage
• benchmarks/ ← Benchmark suites written in Bolt language
• examples/ ← .bolt source examples for language features
• tests/ ← Parser, runtime, and stdlib test cases (Bolt scripts)
• doc/ ← User guides, embedding guide, performance, standard library reference
• CMakeLists.txt, .github/ ← Build and CI configuration
Key insights from README
• Bolt is designed for ultra-fast compilation and execution, embed-first.
• Only depends on C standard library and libm, plus picomatch for regex.
• The CLI (bolt-cli) serves as a minimal embedding example.
• Emphasis on type safety, compactness, and easy integration.
Main components
a. CLI / Host Application
– bolt-cli/main.c (shows how an external C program links libbolt and invokes the API)
b. Core Bolt Library (libbolt.a/so)
– Tokenizer (bt_tokenizer.c/.h)
– Parser (bt_parser.c/.h)
– Type Checker & Inference (bt_type.c/.h)
– Compiler / Bytecode Generator (bt_compiler.c/.h)
– Runtime & VM / Evaluator (bt_context.c/.h, bt_value.c/.h, bt_object.c/.h)
– Garbage Collector (bt_gc.c/.h)
– Embedding API (bt_embedding.c/.h, bt_userdata.c/.h)
– Prelude & Standard Library Loader (bt_prelude.c/.h)
c. Bolt Standard Library Module Loader
– boltstd/*.c/.h
– picomatch submodule (regex engine)
d. Build System
– CMake orchestrates building libbolt and bolt-cli across platforms
e. Benchmarks & Tests
– .bolt scripts fed into bolt-cli or test harness via API
Relationships & data flow
1. Source Code (user .bolt files)
→ Tokenizer splits into tokens
→ Parser builds AST
→ Type Checker infers and annotates types
→ Compiler emits bytecode or IR
→ Runtime/Evaluator executes bytecode in a VM/Context
→ GC manages memory of allocated Bolt objects
→ Standard Library modules are loaded into the execution context
→ Host application (CLI or embedded) sends/receives data via the Embedding API
2. Host Application links against libbolt, calls initialization (bt_init), loads scripts, retrieves results.
Architectural patterns & design principles
• Modular C code separated by concern (lexer, parser, type, compile, runtime, GC)
• Embeddable API boundary between host and language runtime
• Static library + example CLI (single‐process, single‐threaded by default)
• Pluggable standard library modules, configurable via bt_config.h
• Minimal external dependencies, enabling portability.