Compiler

Compiler

This document describes the bytecode compiler and virtual machine at a high level for language tooling and implementation work. It is intentionally brief and the Go implementation is the source of truth.

Pipeline overview

1. Parsing: source is tokenized and parsed into an AST.
2. Analysis: an analyzer resolves symbols, validates static references, and assigns IDs.
3. Compilation: the compiler emits bytecode instructions and a constant pool.
4. Execution: the VM evaluates bytecode with a stack-based model.

Bytecode model

• Constant pool: literals and compiled functions live in a constant pool referenced by index.
• Instruction stream: opcodes are encoded in big endian with optional operands.
• Stack: most instructions pop operands and push results.
• Control flow: conditional and unconditional jumps alter the instruction pointer.

Functions and closures

Functions compile to bytecode chunks with metadata such as arity. Closures capture their environment using upvalue cells — heap-allocated boxes that allow mutable var bindings to be shared between the enclosing scope and all capturing closures. The MakeClosure opcode builds a closure from a compiled function and its captured values, while WrapLocal converts a local into an upvalue cell. Closures are invoked through the Call opcode in the VM.

Iteration

for element <- value compiles to a call into the value’s @Iterable implementation. MakeIterYield builds a closure over the loop body — it carries the binding’s local slot and the body’s instruction range — and CallIterate invokes the iterable with the value and that closure. A return inside the loop body has to escape both the closure and the iterable that called it, so the VM raises it as a signal and unwinds to the frame the loop belongs to — a custom iterable behaves like a built-in one.

Type hints and type matching

Type hints (: T, -> T) are parsed into TypeExpr AST nodes and stored on declarations and parameters. The IsType opcode performs runtime type checking against data types, extern types, union membership, and attribute constraints. switch statements compile type patterns (case is T:) using IsType.

Guarded member access

All four begin with an asoption or asresult over the target. A value already in the union it names is left alone; anything else is asked for one through the toOption or toResult of its attribute, which the VM calls reentrantly the same way an extern function calls back into Zirric. What is on the stack afterwards is therefore always a Some, None, Ok or Err, so the instructions that follow only have to tell those apart, and the getfield "value" that ends each of them is the unwrapping step nobody writes.

?. then emits a jumpistype against None that leaves the value where it is, so the jump carries the None itself to the end of the chain; every ?. in one chain jumps to the same place, where a wrapoption turns the value the chain did produce into an Option. Because the chain is compiled as one unit, a call cannot be part of it — the call’s arguments are already on the stack when the short-circuit would jump past it — which is why the compiler rejects that shape instead.

!. emits a returnistype against Err, which returns the error from the running frame. Nothing has to be unwound or jumped over, since the frame is discarded along with whatever else is on its stack.

?? and !! are the same shape as each other: one jumpistype over the normalized left operand — None for ??, Err for !! — and a pop in front of the right operand, which is only ever reached on the missing path.

Core opcodes