Welcome to The Koru Book
This isn't like traditional programming tutorials. Instead of static examples, you're looking at living documentation — every page is backed by a real test that actually runs.
When you see a ✓, that means the code actually compiles and runs correctly. When you see ✗, you're looking at something we're still working on. This is documentation that can never drift from reality because it IS reality.
That said, tests can go cold. A ✓ means the test passed when last run — not that every example is perfectly idiomatic or complete. Koru is under active development.
The Zen of Koru
The atom is the event. Functions are just events that forgot how to branch.
Branches are how decisions actually work. Flows are how things actually happen.
What you don't write can't break. What you don't hide can't surprise.
What you don't promise can't fail. Fail loudly, fix honestly.
Model reality, not abstractions. Let patterns emerge from events.
Complex behavior from simple rules. The AST is the program.
Zero cost at runtime. All magic at compile time. The boundary dissolves.
We built this together. Human vision, AI capability.
Working Features
Green tests (✓) are ready to learn from today
In Progress
Red tests (✗) are features we're currently building
Coming Soon
Blue tests (○) are planned features on the horizon
Suggested Learning Path
1. Start with Core Language — Learn the fundamentals of events and procs
2. Move to Control Flow — Understand how Koru programs flow with labels and continuations
3. Explore Advanced Topics — Event taps, phantom types, metacircular compilation
The Koru Book
Learn Koru through working examples. Every lesson is a real test from the compiler's regression suite.
core language / basic syntax
6/6core language / events flows
12/12core language / types values
7/7Tests for expression-based flow syntax (design under review).
core language / control flow
27/28module system / imports
16/16module system / namespaces
2/2module system / packages
1/1parser
7/7This category defines the structure of the Koru Abstract Syntax Tree (AST) and the parsing rules.
compiler features / parser
49/50This category provides **gold-standard testing** for Koru's parser, validating both successful parses (AST structure) and syntax error cases (precise error messages).
compiler features / compilation
16/16compiler features / flow checker
3/4compiler features / codegen
1/1compiler features / emitter
4/4compiler features / std library
1/1compiler features / subflow
1/1syntax / struct constructors
2/2advanced features / comptime
51/54Tests for compile-time evaluation and metacircular features.
advanced features / stdlib
42/47advanced features / keyword
5/5advanced features / phantom types
60/66Tests for the phantom type-state system - compile-time tracking of runtime states.
advanced features / transforms
2/2advanced features / type system
1/1advanced features / types
4/4advanced features / auto proc
4/4advanced features / pattern branches
2/3advanced features / subflows
12/12advanced features / optional branches
9/10advanced features / taps observers
6/7Tests for the tap system - observer pattern for events.
advanced features / interceptors
0/4advanced features / phantom types
3/3advanced features / variants
4/8advanced features / templating
2/4advanced features / kernel
13/15**Why kernels exist, what they guarantee, and why they are fast**
advanced features / testing
10/10control flow
3/4> Zero-cost abstractions through template expansion
runtime features
2/2runtime features / budgeted interpreter
7/7runtime features / purity checking
8/11runtime features / performance
0/20Tests for compiler optimizations and zero-cost abstractions.
runtime features / coordination
7/10runtime features / runtime
36/36runtime features / resource bridge
2/2integration testing / negative tests
32/33This directory contains tests that validate the compiler's error messages and failure modes. These tests ensure that:
integration testing / negative tests / 020 parse errors
1/1integration testing / negative tests / 030 type errors
1/1integration testing / bug reproduction
6/6integration testing / validation
7/7Tests for type checking, branch coverage, and phantom types.
stdlib / string
2/2stdlib / fmt
1/1event globbing
4/10examples showcase
1/1Working examples that appear on korulang.org. These tests ensure the website never shows broken code.
examples showcase / language shootout
9/9> **"Be within 20% of C/Zig, then optimize to beat them."**
How This Works
Every page in this book is backed by a real test in the Koru compiler's regression suite. When you see a ✓, that means the code actually compiles and runs correctly. When you see ✗, you're looking at something we're still working on.
This is living documentation — it can never drift from reality because it IS reality. The tests run on every commit.