Guide
Languages / 言語: English · 日本語 — the Japanese edition is a complete machine-assisted translation under review; corrections are welcome. 日本語版は機械翻訳を基にした全訳で、レビューを進めています。修正のご提案を歓迎します。
Navigation: Documentation Root
Onboarding-oriented documentation for new users and embedders. Where the architecture, spec, and reference sections describe what Keleusma is, this section describes how to use it.
You can try Keleusma in your browser at the playground: it compiles and verifies your program with the compiler running as WebAssembly and reports its worst-case execution-time and memory bounds live, no installation required.
The guide is in two layers. The first is a linear course of forty chapters that teaches Keleusma from scratch, sized for video presentation and ordered as a single learning arc. The second is a set of reference pages for lookup and deeper study. The course and the reference pages overlap by design: the course is for first learning, the reference pages are for going back.
The Course
Forty chapters in ten parts. Each chapter is self-contained and demo-driven, sized to roughly one short video. Parts I through VIII teach the language; Part IX teaches embedding into a Rust host; Part X points onward.
Part I — Setting Out
| Chapter | Title |
|---|---|
| 1 | What Keleusma Is, and What It Is Not |
| 2 | Installing Keleusma and the Interactive Prompt |
| 3 | A Complete First Program |
Part II — The Building Blocks
| Chapter | Title |
|---|---|
| 4 | Values and Types |
| 5 | Names and Bindings |
| 6 | Functions |
| 7 | Making Decisions |
| 8 | Bounded Repetition |
| 9 | The Pipeline Operator |
Part III — Shaping Data
| Chapter | Title |
|---|---|
| 10 | Structs |
| 11 | Enums |
| 12 | Tuples and Arrays |
| 13 | Pattern Matching in Depth |
| 14 | Multiheaded Functions and Guards |
Part IV — The Heart of Keleusma
| Chapter | Title |
|---|---|
| 15 | The Three Function Categories |
| 16 | Yield: Talking to the Host |
| 17 | The loop Function |
| 18 | The Data Segment |
Part V — The Verifier and the Guarantees
| Chapter | Title |
|---|---|
| 19 | Why Was My Program Rejected? |
| 20 | Time and Memory Budgets |
Part VI — Going Deeper
| Chapter | Title |
|---|---|
| 21 | Generics and Traits |
| 22 | Newtypes and Refinement Types |
| 23 | Handling Partial Operations |
| 24 | Information-Flow Labels |
Part VII — Shipping a Program
| Chapter | Title |
|---|---|
| 25 | From Source to Bytecode |
| 26 | Signed Modules and Hot Code Swap |
Part VIII — The Capstone: Making Music
| Chapter | Title |
|---|---|
| 27 | The Piano Roll: How It Works |
| 28 | Setting Up Your Own Song Playground |
| 29 | Writing and Modifying a Song |
| 30 | A Tour of the Song Roster |
Part IX — Embedding Keleusma in a Rust Program
Part X — Where to Go Next
| Chapter | Title |
|---|---|
| 40 | Further Reading |
Reference Pages
The reference pages are the topic-organized companions to the linear course. Each is a self-contained document that the corresponding course chapters draw on and that a reader returns to when looking up a specific question.
| Document | Audience | Purpose |
|---|---|---|
| GETTING_STARTED.md | First-time user | Install the CLI, write a first script, run it, embed it in a twenty-line Rust host. Course coverage: Chapter 2, Chapter 31. |
| EMBEDDING.md | Rust host author | The complete host-facing reference: Vm construction, native function registration, arena sizing, the call and resume protocol, error recovery, opaque host types, the Library trait, signed modules. Course coverage: Part IX (Chapters 31 through 39). |
| PIANO_ROLL.md | Song author, host lifter, or host architect | The long-form manual for the piano-roll example: composing songs, lifting the host loop into another application, and using the example as an architectural reference for other control-loop domains. Course coverage: Part VIII (Chapters 27 through 30). |
| ROGUE.md | Game author or host architect | The long-form manual for the roguelike example: gameplay rules, the host and multi-script architecture, dungeon generation, the artificial-intelligence archetypes, item effects, and exercises. Not covered by a chapter; pointed to from Chapter 40. |
| WHY_REJECTED.md | Anyone whose program failed verification | The full catalogue of verifier rejection messages, mapped to root causes and proposed rewrites. Course coverage: Chapter 19 introduces the three most common rejections; this document is the full list. |
| FAQ.md | Anyone who hit a surprise | Common rough edges in V0.2.0, including string handling, escape sequences, the immutable-locals constraint, and migration notes from the V0.1.x line. |
| COOKBOOK.md | Embedder reaching for a known-good pattern | Working recipes for embedding patterns: the data-loader pattern, auto-sizing the arena from a module’s WCMU, narrow-runtime type aliasing, signed bytecode distribution, calibrated WCET with a measured cost model. Course coverage: Chapter 39 names the patterns; this document is the recipes. |
| BIG_NUMBERS.md | Author needing multi-digit arithmetic | The full worked example for the overflow construct: 64-by-64 to 128-bit multiplication via the high half, and addition with explicit carry-out propagation for chained multi-digit arithmetic. Course coverage: Chapter 23 introduces the construct; this document is the full technique. |
| LLM_USAGE.md | Operator using AI coding assistants | Patterns AI tools tend to get wrong, the read-AGENTS-first session protocol, prompt patterns that reduce iteration time. |
| AUTOMATION_SCRIPTING.md | Operator writing devops or sysadmin automation in Keleusma | The consolidated CLI scripting story: the three ways to run a script, script arguments, the entry kinds mapped to one-shot, staged, and daemon deployment shapes, the shell bundle as an orchestrator, signed and encrypted bytecode distribution, the run-tasks multi-script runner, and where the static guarantees do not hold. Ties together Chapters 2, 15 through 18, 25, and 26 with the operator reference docs. |
| SECURITY_POLICY.md | Operator deploying keleusma-cli in constrained environments | The strict-mode signing and encryption policies introduced in V0.2.1: key generation, policy activation, deployment scenarios, the trust model, daemon deployments and tick-interval cadences. |
| METRICS.md | Operator planning embedded or constrained deployments | Binary size, RSS, peak memory footprint, CPU cycles, comparison to bash, Lua, Python, Ruby, and Node.js. Includes steady-state daemon footprint under the tick-interval rate limiter. |
| SHELL_AUDIT.md | Operator evaluating whether stddsl::Shell is rich enough for a planned daemon | Present capabilities of the bundle, closed gaps, and open recommendations for V0.2.x point releases. |
Companion Material
| Path | Content |
|---|---|
examples/scripts/ | Standalone .kel files demonstrating language features. Run any of them with keleusma run examples/scripts/<file>.kel. |
examples/ | Rust embedding examples. Run with cargo run --example <name>. |
examples/piano_roll.rs | End-to-end SDL3 audio host with hot code swap across a song roster. Run with cargo run --release --example piano_roll --features sdl3-example. |
examples/rogue/ | End-to-end SDL3 video host driving a roguelike. Run with cargo run --release --example rogue --features sdl3-example. |
keleusma-cli/ | The standalone command-line frontend installed by cargo install --path keleusma-cli --bin keleusma. |
Reference Cross-Links
When a term is unfamiliar:
- GLOSSARY.md defines core terms.
- LANGUAGE_DESIGN.md describes the function categories, the five guarantees, and the conservative- verification stance.
- GRAMMAR.md is the formal syntax reference.
- TYPE_SYSTEM.md describes primitive types, string discipline, and composite types.
- STANDARD_LIBRARY.md lists the bundled
native functions in the
audio::andmath::namespaces.
Planning Document
OUTLINE.md is the planning document the course was drafted against. It records the pedagogical decisions, the music-to- Keleusma concept map, and the open questions still under review. It is working material rather than user-facing documentation.