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, failures included. much of kanso's value is in its compile errors, so the book shows them as often as it shows working programs. 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 the build.
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; modules, imports and tests; and sequences that run as one loop. each chapter builds on the last and ends with exercises.
part ii—building and shipping builds two programs from an empty directory, a command-line tool and a web service, then measures one, makes it cheaper, and ships both as binaries. its last chapter depends on a published package and shows how to publish one.
part iii—real programs reads two larger programs closely: kanso-json, the json decoder from the standard library, and a voting-theory simulator that reproduces the field's known results, method by method.
part iv—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 cost goldens and structural specs hold those results in place.
the appendices are the reference: every diagnostic the compiler can raise and what it protects, every builtin with its failure behavior, the complete canonical-form law, recipes for everyday jobs, and the idioms the compiler leaves to you.
- start here
- →a tour of kansoeighteen programs you can edit and run in the page, a minute each
- 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 ioprograms that describe their side effects and tests that need no mocks
- 06flow and concurrencygroups, binds, and green threads—dependence declared, order earned
- 07modules and testsa directory is a module, tests are constants, and an import enrolls a module's names
- 08sequencesadapters are recipes, consumers pull one element at a time, and the chain fuses to one loop
- part ii — building and shipping
- 09a command-line toola project from an empty directory: arguments, stdin, exit codes, tests, a binary
- 10a web servicea handler is a function from a request and state to a response, tested by calling it
- 11measuring and shippingcounters that never vary, a cost golden ci diffs, and a binary on a server
- 12packagesdepending on a published hako: the import is the manifest, a tag is a release, the lock is exact
- part iii — real programs
- 13a json librarykanso-json read closely: dispatch at byte level, failure with positions
- 14a voting simulatormonte carlo in a pure language; six voting methods, honestly compared
- part iv — under the hood
- 15fast by constructionpast serde_json without memory syntax, and the ratchet that holds it
- 16conventions at compile timea derivation reads the program while it compiles and answers checked declarations; senro's conventions as the case study
- appendices
- athe diagnostics catalogevery error kind, what it protects, and the exact message
- bbuiltin referencethe whole surface: the ambient names, the std modules and the list vocabulary
- ccanonical formthe formatting law: one rendering per program, enforced
- drecipesshort programs for everyday jobs, each with its output
- eidiomsthe decisions the compiler leaves to you, each with the chapter that argues for it