cococopi/corros

Purpose and Entry Points

Corros is a dependency-free Rust implementation of a bytecode-compiled scripting language, plus a self-hosted implementation written in Corros. The native CLI runs scripts, starts an interactive REPL, dumps bytecode, and executes serialized bytecode. Primary entry points are src/main.rs (CLI), src/lib.rs (crate API), and src/repl.rs (interactive mode).

Source Loading and Module Boundary

Programs are read and expanded before compilation. adopt imports are resolved relative to source files, spliced into the token stream, and guarded against cycles by src/loader.rs. The language prelude is injected ahead of user code from lib/prelude.cor, making much of the standard library ordinary Corros source rather than Rust runtime code.

Front End: Lexing and Single-Pass Compilation

src/lexer.rs scans source into Corros tokens, including language-specific keywords, literals, operators, and comments. src/compiler.rs combines recursive-descent parsing with immediate bytecode emission: it manages scopes, globals/locals, assignment expressions, control-flow jumps, functions, closures, and upvalue capture. Compilation errors are represented and source-located through src/error.rs.

Bytecode Representation

src/chunk.rs defines executable chunks: instructions, constant pools, and bytecode disassembly used by --dump. src/bc.rs supports bytecode-oriented execution and is the boundary used by the self-hosting bootstrap flow (--run-bc). Compiler output is therefore independent of the source parser at runtime.

Runtime Model and VM

src/vm.rs is a stack-machine interpreter that executes chunks, manages call frames, globals, closures/upvalues, collection operations, and runtime traceback generation. Runtime objects and their semantics—numbers, strings, lists, maps, ranges, functions, closures, and native functions—are centralized in src/value.rs. This is the main host-language boundary: Rust owns memory/runtime representation while Corros code supplies higher-level behavior.

Native and Corros Standard Libraries

src/stdlib.rs registers host builtins for I/O, conversion, math, timing, assertions/errors, and primitives that require native access. lib/prelude.cor layers Corros-defined list, string, map, and range behavior above those primitives, including method dispatch. Thus method-heavy user programs generally flow through prelude code, with Rust as fallback for irreducible host operations.

Self-Hosting Bootstrap

The self-hosted compiler and VM are Corros programs at selfhost/compiler.cor and selfhost/vm.cor. selfhost/demo.sh uses the Rust implementation to compile both, then runs the compiled VM/compiler chain and compares produced bytecode for byte-identical results. This validates compatibility between the native compiler/VM and the language-level implementation.

Runtime and Infrastructure

The project is one Rust crate (Cargo.toml) requiring Rust 1.70+ for source builds and has no external dependencies. Distribution is via release binaries with source-build fallback in install.sh; there are no databases, network services, or web infrastructure in the runtime architecture.