the kanso book
this book is the language: the canon, the tutorial, and the reference in one place. the about page carries the philosophy; here is where you sit down and actually write some kanso.
a promise
every program in this book was run before it was printed, and every output panel shows what actually came back—including the failures, especially the failures. half of kanso's value is its compile errors, so this book treats a red diagnostic as a feature demo, not an apology. the samples live in the repository under docs/book/samples/, one file per panel, with the captured output beside each; a check script re-runs the whole corpus, so a panel whose output drifts from the language fails a build before it can lie on a page.
who this is for
a working programmer. you don't need to have used a pure language, a dispatch-based language, or anything academic—kanso is designed to be learned in an evening and idiomatic in a week, and the book is paced for that. you need a terminal and a rust toolchain to build the compiler; chapter 01 walks through it. if you'd rather not install anything, the playground runs the real toolchain in your browser tab, and every part-i example fits in it.
how the book is organized
part i—the language teaches kanso from nothing: values, bindings, and the canonical form; dispatch as the only branch; failure as a value; effects as descriptions; the flow model that makes concurrency a property of data dependence; and modules with tests. each chapter builds on the last and ends with exercises.
part ii—real programs reads two programs that earn their living: kanso-json, the standard library's json decoder—the one that outruns hand-tuned parsers in chapter 10—and a voting-theory simulator that reproduces the canonical results of the field, method by method.
part iii—under the hood is the performance story: how a pure language with no memory syntax decodes json faster than serde_json, rust's hand-tuned parser, on this machine and this fixture—and how those wins are held by cost goldens and structural specs instead of stopwatches. we measured; chapter 10 keeps the receipts.
the appendices are the reference: every diagnostic the compiler can raise and what it protects, every builtin with its failure behavior, and the complete canonical-form law.
- part i — the language
- 01hello, kansothe toolchain, the first program, and a compile error worth meeting
- 02values and bindingsevery value form, arbitrary-precision ints, widening, and the rebind rule
- 03types and dispatchoverloads, typesets, markers, destructuring—the only branch you get
- 04failure is a valueerr, none, the railway, and the taxonomy of things going wrong
- 05effects are descriptionsprograms that describe their side effects and tests that need no mocks
- 06flow and concurrencygroups, walls, and green threads—dependence declared, order earned
- 07modules and testsa directory is a module, private is the default, tests are constants
- part ii — real programs
- 08a json librarykanso-json read closely: dispatch at byte level, failure with positions
- 09a voting simulatormonte carlo in a pure language; six voting methods, honestly compared
- part iii — under the hood
- 10fast by constructionpast serde_json without memory syntax, and the ratchet that holds it
- 11modulesa directory is a module, an import enrolls its names, and a surface is a kept promise
- 12sequencesadapters are recipes, consumers pull one element at a time, and the chain fuses to one loop
- appendices
- athe diagnostics catalogevery error kind, what it protects, and the exact message
- bbuiltin referencethe whole surface: six ambient names, the std modules, the 33-verb list vocabulary
- ccanonical formthe formatting law: one rendering per program, enforced