Reading the Source

Start here: main.go.

Everything begins in src/main.go. The runCompile function is the entire compiler pipeline in nine lines:

func runCompile(source, outPath string) error {
    prog, err := syntax.Parse(source)        // source text → AST
    if err != nil { return err }

    info, err := types.Check(prog)           // AST → typed Info
    if err != nil { return err }

    return codegen.GenerateWithTypes(prog, outPath, info)
    // ↑ typed AST + Info → C source, then cc compiles it
}

Three function calls, three packages. The compiler is that flat. Each package is a pure function — it takes the previous stage's output and returns the next stage's output. No global state.

The four packages.

The three structs that cross package boundaries.

Each pipeline stage hands something to the next. Understanding these three types tells you how the whole compiler fits together.

// ast.go
type Program struct {
    Stmts []Stmt
}

// ast_stmt.go — examples
type VarDeclStmt struct { Name string; Value Expr; Type *TypeExpr; IsConst bool; Pos Pos }
type IfStmt      struct { Condition Expr; Then *BlockStmt; Else Stmt; Pos Pos }
type ForStmt     struct { VarName string; Iterable Expr; Body *BlockStmt; Pos Pos }

// ast_expr.go — examples
type BinaryExpr  struct { Left, Right Expr; Op TokenKind; Pos Pos }
type CallExpr    struct { Callee Expr; Args []Expr; Pos Pos }
type FuncExpr    struct { Params []Param; ReturnType TypeExpr; Body *BlockStmt; Pos Pos }

for item in scores {   // → ForStmt { VarName:"item", Iterable:IdentExpr("scores"), Body:... }
    show(item)         //     body contains ExprStmt { CallExpr { Callee:IdentExpr("show"), Args:[IdentExpr("item")] } }
}

let total = add(1, 2)  // → VarDeclStmt { Name:"total", Init:CallExpr { Callee:IdentExpr("add"), Args:[NumberExpr(1),NumberExpr(2)] } }

if total > 10 {        // → IfStmt { Condition:BinaryExpr(>, IdentExpr("total"), NumberExpr(10)), Then:..., Else:nil }
    show("big")
}

// checker.go
type Info struct {
    // Every Expr node → its computed type
    Types map[syntax.Expr]*Type

    // Every VarDeclStmt → its resolved type (annotation || inferred)
    Decls map[*syntax.VarDeclStmt]*Type

    // Every FuncExpr → its full signature (params + return)
    // Used by codegen to decide whether to emit an unboxed function
    Funcs map[*syntax.FuncExpr]*Type
}

// Monk source
let x int = 42          // VarDeclStmt — Decls[this] = Int
let y = x + 1           // VarDeclStmt — Decls[this] = Int (inferred)
                        // BinaryExpr(+) — Types[this] = Int
                        // IdentExpr(x)  — Types[this] = Int
                        // NumberExpr(1) — Types[this] = Int

const add = (a int, b int) int { return a + b }
// FuncExpr — Funcs[this] = (int,int)->int
// Codegen sees Funcs[this] is all-scalar → emits int64_t add(int64_t, int64_t)

// types.go
type Kind int
const (
    KindAny Kind = iota   // unknown / dynamic
    KindInt               // int64_t
    KindFloat             // double
    KindStr               // char*
    KindBool              // bool
    KindNone              // void / null
    KindArray             // []T
    KindRecord            // {field: T, ...}
    KindFunc              // (T1, T2) -> T3
)

type Type struct {
    Kind       Kind
    Optional   bool          // T? — the orthogonal nullable flag
    Elem       *Type         // for KindArray
    Fields     []RecordTypeField  // for KindRecord
    RecordName string        // for named records ("Point", "User")
    Params     []*Type       // for KindFunc
    Return     *Type         // for KindFunc
    MinParams  int           // for KindFunc with defaults
}

The generator struct: codegen's working state.

Codegen's entire state is one struct. Understanding its fields explains most of what gen.go and gen_stmt.go are doing.

// gen.go
type generator struct {
    // Output buffers: functions are hoisted above main()
    funcs  strings.Builder  // static C function definitions
    body   strings.Builder  // main() body

    // Type info from checker
    info   *types.Info

    // Storage maps: what C type does each variable use?
    // storeBoxed → MonkValue, storeInt → int64_t, etc.
    storage map[string]storageKind   // current scope's variable kinds

    // Function tracking
    funcCount  int                        // counter for unique names
    funcNames  map[string]string          // monk name → C name
    fnStorage  map[string]funcStorage     // C name → param/return kinds
    funcHasCapture map[string]bool        // does this func close over anything?
    funcDefaults   map[string][]syntax.Expr  // default param expressions

    // Current function context
    retStorage      storageKind  // return type of the function being emitted
    currentCaptures []string     // captured variable names (for save-back on return)

    // Bounds-check elision (nil when no type info)
    constVals map[string]int64    // compile-time constant variables (e.g. let N = 400)
    arrayLens map[string]int64    // statically known lengths of typed array variables
    varBounds map[string][2]int64 // inclusive [lo, hi] range for while-loop counters

    // Temp variable counter
    tempCount int
}

The key insight: storage is the map from variable name → C type. When codegen decides to emit int64_t x = ... instead of MonkValue x = ..., it sets storage["mk_x"] = storeInt. Later, when that variable is read by emitExpr, it boxes it back up.

After compiling this program, the generator's storage map looks like this:

let count int = 0          // storage["mk_count"] = storeInt   → emits int64_t
let name = "Monk"          // storage["mk_name"]  = storeBoxed  → emits MonkValue
let pi float = 3.14        // storage["mk_pi"]    = storeFloat  → emits double

const add = (a int, b int) int { return a + b }
// fnStorage["_monk_func_1"] = funcStorage{params:[storeInt,storeInt], ret:storeInt}
// → emits int64_t _monk_func_1(int64_t mk_a, int64_t mk_b) { ... }

Two emission paths: boxed vs unboxed.

This is the most non-obvious part of codegen. There are two ways to emit any expression:

// gen_expr.go — boxed addition
case syntax.Plus:
    tmp := g.newTemp()
    return fmt.Sprintf(
        "({MonkValue %s=%s; %s.kind==MONK_STRING ? "+
        "monk_string_concat(%s,%s) : monk_add(%s,%s);})",
        tmp, left, tmp, tmp, right, tmp, right)

// unbox.go — unboxed addition (int + int)
case syntax.Plus:
    if lk == storeInt && rk == storeInt {
        return fmt.Sprintf("(%s + %s)", lc, rc), storeInt
    }

The two paths coexist. When an unboxed value ends up in a boxed context (e.g. passed to a builtin that expects MonkValue), boxExpr wraps it. When a boxed value feeds into an unboxed path, unboxExpr extracts the raw field. The function coerce(code, from, to) handles both directions.

The same expression emits differently depending on what the checker knows:

Function hoisting and the two-buffer trick.

C requires a function to be declared before it's called. Monk allows forward references and mutual recursion. The solution: two output buffers.

// gen.go — the generator has two output buffers
type generator struct {
    funcs  strings.Builder  // hoisted C functions go here
    body   strings.Builder  // main() body goes here
    ...
}

// gen.go — final assembly
func (g *generator) emit() string {
    return preamble + g.funcs.String() +
           "int main(void) {
" +
           g.body.String() +
           "    return 0;
}
"
}

This Monk program:

const double = (n int) int { return n * 2 }
show(double(21))

Produces two output buffers that get concatenated:

When codegen encounters let add = (a int, b int) int { ... }, it immediately writes the C function definition into g.funcs (above main), then writes MonkValue mk_add = monk_make_function(...); into g.body. When later code calls add(3, 4), the C function is already declared above.

Recursive self-reference works because emitVarDecl pre-registers the C name in g.funcNames before hoisting the body. So when the body refers to fib, emitCall finds it in funcNames and emits a direct C call.

Checker non-obvious details.

// This works — fib calls itself before it's "defined"
const fib = (n int) int {
    if n <= 1 { return n }
    return fib(n - 1) + fib(n - 2)  // pass 2 hoisted fib's signature; pass 3 checks this call
}

// This works — distance takes a Point, defined after the function
const distance = (p Point) float { return sqrt(p.x * p.x + p.y * p.y) }
type Point { x float, y float }  // pass 1 resolves this; pass 2 can use it in distance's signature

// This triggers p.typeErr — "int?" is a valid type, "int??" is not
let x int?? = none   // parseTypeExpr sees "??" and sets p.typeErr
                     // parseProgram surfaces it: "invalid type annotation: int??"

for i in scores {
    let i = 99      // OK — "let i" in the body scope shadows the loop var (separate scope)
    show(i)         // prints 99
}

for i in scores {
    i = 99          // ERROR — "i" in the loop scope is const; assignment rejected
}

Suggested reading order for contributors.