How lostella/loscheme works
Project Type and Purpose
• Type: A language interpreter for Scheme, written in Rust, with both CLI (native) and Web (WASM) front ends.
• Purpose:
• Offer a REPL and script-runner for Scheme programs on the command line.
File Structure
• Top-Level Executables
• src/bin/loscheme.rs: CLI entry point.
• src/web.rs + web/index.html: WebAssembly front end.
• Core Library (src/lib.rs)
Breaks down into modules:
• parser.rs: Source → AST
• treewalk/: AST evaluator + standard library (builtin.rs)
• rationals.rs: Numeric type
• run.rs: Orchestrates parsing + evaluation in REPL/script mode
• rv32.rs: (Optional) support for RV32 architecture?
• errors.rs: Error definitions and handling
• Scripts (scripts/*.scm): Example Scheme programs that exercise core features.
• Tests (tests/test.rs): Integration tests for interpreter behavior.
• CI (.github/workflows/ci.yml): Defines build & test pipeline.
• Cargo.toml: Dependency and build configuration.
Extract Insights from the README
• CLI usage: cargo run --release → REPL.
• Script execution: cargo run -- path/to/script.scm.
• Browser: precompiled WebAssembly available on GitHub Pages.
Main Components
a. Front-ends
• CLI Binary (loscheme)
• WebAssembly Module (loaded by index.html)
b. Core Interpreter Library
• Parser → produces AST
• Evaluator (Tree-walker) → executes AST
• Built-ins (arithmetic, list ops, I/O)
• Numeric subsystem (rationals)
• Runtime / REPL loop (run.rs)
• Error handler
c. Supporting Artifacts
• Scripts directory (external inputs)
• Tests
• CI pipeline
• Cargo build system
Interactions and Data Flow
• User types input (REPL) or invokes script →
the CLI or Browser front-end calls into →
run.rs → parser → AST → treewalker + built-ins → result →
back to front-end → stdout or browser UI.
• The Cargo toolchain orchestrates compilation to native binary or WASM.
• CI checks out code, runs cargo test and cargo build --target wasm32-unknown-unknown, then deploys.
Architectural Patterns & Principles
• Modular Separation: clear split between front-ends and core library.
• Single Binary / Single WASM Module: both share the same core.
• Tree-walk Interpreter: parser produces AST, then a single pass evaluator.
• Rust Ownership & Error Handling: typed errors module.