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.
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
4/4core language / events flows
12/12core language / types values
6/6Tests for expression-based flow syntax (design under review).
core language / control flow
32/34module system / imports
15/16module system / namespaces
2/2module system / packages
1/2parser
6/6This category defines the structure of the Koru Abstract Syntax Tree (AST) and the parsing rules.
compiler features / parser
47/48This 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/3compiler features / codegen
1/1compiler features / emitter
3/3compiler features / subflow
1/1syntax / struct constructors
2/2advanced features / comptime
46/55Tests for compile-time evaluation and metacircular features.
advanced features / stdlib
38/46advanced features / keyword
5/5advanced features / phantom types
59/64Tests for the phantom type-state system - compile-time tracking of runtime states.
advanced features / fusion
2/6advanced features / transforms
2/2advanced features / type system
1/1advanced features / types
1/1advanced features / auto proc
4/4advanced features / subflows
7/7advanced features / taps observers
5/7Tests for the tap system - observer pattern for events.
advanced features / interceptors
0/4advanced features / phantom types
0/1advanced features / polyglot
3/8advanced features / templating
2/4advanced features / kernel
7/10**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
6/6runtime features / purity checking
8/11runtime features / performance
0/29Tests for compiler optimizations and zero-cost abstractions.
runtime features / coordination
7/10runtime features / runtime
34/34runtime features / resource bridge
2/2integration testing / negative tests
10/10This 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 / negative tests / 060 compiler crashes
1/1integration testing / bug reproduction
7/7integration testing / validation
7/7Tests for type checking, branch coverage, and phantom types.
stdlib / string
2/2event globbing
4/11examples showcase
1/1Working examples that appear on korulang.org. These tests ensure the website never shows broken code.
examples showcase / language shootout
4/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.