Design Philosophy

Matchbox 0.2 favors a small, inspectable implementation over a broad set of language features. The compiler supports a compact subset of the tokens recognized by the lexer, reports unsupported operators explicitly, and keeps runtime execution closely aligned with the generated bytecode.

The current implementation is an early step toward the broader Project Vision: a fast, lightweight, and portable language with a clear runtime model and enough built-in functionality for developers to create real programs without immediately assembling a separate toolchain.

Small Core

The current language core includes integer values, variables, functions, arithmetic, bitwise operations, built-in functions implemented as services, and straightforward lexical scoping. The lexer recognizes several keywords and tokens that are not yet implemented as language features. Recognizing them now allows the compiler to provide clearer diagnostics and reserves them for future syntax rather than treating them as ordinary identifiers.

Zero-Cost Abstractions

Matchbox is intended to support zero-cost abstractions: programs should not pay runtime costs for language features they do not use, and higher-level features should map to direct, understandable runtime behavior whenever possible.

This does not mean every feature must expose low-level machinery in source code. It means abstractions should have visible semantics, predictable storage and execution costs, and a clear path to efficient bytecode or native output. When a feature requires runtime support, that support should be explicit in the language model rather than hidden behind surprising compiler behavior.

Direct Pipeline

The 0.2 source pipeline is direct: the lexer reads one token at a time, the parser builds checked AST nodes and records symbols, the compiler emits bytecode, and the VM executes that bytecode.

Matchbox 0.2 does not include separate analyzer or optimizer stages during compilation. This keeps the current implementation easier to understand and allows errors to be reported close to the stage where they are discovered. Future releases are expected to add analyzer and optimizer stages as the language grows.

Single-Pass Parsing

In 0.2, parsing occurs in a single pass. Names are resolved as the parser reads the source, so variables and functions must be declared before they are used.

A function is added to the current scope only after its body has been parsed. As a result, a function can call functions declared earlier, but it cannot call itself directly in this release.

Top-Level Execution

Top-level statements are executable parts of a Matchbox program. A source file does not require a main function.

Matchbox compiles top-level variable definitions, assignments, function definitions, expression statements, and built-in function calls into the module's top-level function. Function bodies are compiled into separate function objects and invoked through bytecode instructions.