The Language Guide explains how to write Atoll. It is organized around the current parser, semantic checker, prelude, and source-to-runtime tests—not the age or confidence of the older documents.
Guide map
| Section | What it covers |
|---|---|
| Fundamentals | Source text, literals, bindings, constants, functions, closures, operators, decorators |
| Control flow | Blocks, conditions, patterns, match, four loop forms, transfer expressions, defer |
| Types | Type forms, inference, generics, structs, enums, aliases, tuples, traits, references |
| Errors | Option, Result, declared errors, ?, catch, error unions |
| Modules | Project modules, imports, aliases, and visibility |
| Concurrency | Effects, suspension, tasks, spawn, select, race, streams, cancellation |
| SQL | Integrated SQL, models, schemas, routing, queries, frames, writes, transactions |
| Standard Library | Scalars, text, collections, time, I/O, networking, traits, intrinsics |
| Feature Status | Historical proposals and the current implementation boundary |
Learning path
For a first pass through the language:
- Read Source, Bindings, and Functions to learn file and declaration syntax.
- Continue through Control Flow and Types for expression typing, patterns, generics, and user-defined data.
- Read Errors before using I/O, concurrency, or integrated queries; all three expose typed fallibility.
- Add Modules when moving from a source file to a project.
- Treat Concurrency and SQL as advanced language subsystems, then consult the Standard Library by task.
Compiler and runtime contributors should read the Language Specification after this guide, then follow the HIR, MIR, WasmIR, Compiler, and Runtime sections. The guide teaches how to use features; those sections define their grammar, lowering, and representation.
Contract layers
A construct can exist at one compiler layer without being usable at every later layer. The guide uses four distinct claims:
| Claim | Evidence needed | What it establishes |
|---|---|---|
| Accepted | Lexer, parser, and AST | Source text has a defined syntax and can be represented without inventing nodes |
| Checked | Name resolution, type/effect checking, and HIR lowering | Valid programs receive a meaning and invalid programs receive source diagnostics |
| Emitted | Monomorphization, MIR, WasmIR, and WebAssembly tests | The backend can lower the checked construct without an ABI leak or unsupported fallback |
| Executed | Runtime or end-to-end tests | The emitted behavior works through the current runtime boundary |
“The parser accepts this” therefore does not imply “this is a supported language feature.” Decorators are a common example: generic decorator syntax is represented in the AST, while the compiler supplies semantics only for specific decorators.
Most pages teach the strongest implementation-backed contract available. When a later stage is incomplete, the page names the exact boundary instead of silently treating parseability as completion. Use Feature Status for the maturity model and Pipeline for the stage handoffs behind it.
Page status
Every page records how closely its public contract has been checked:
| Status | Meaning |
|---|---|
| Verified | Reconciled with current parser, semantic checker, stubs, or executable tests |
| Provisional | The implemented core works, but edge behavior or backend coverage is still moving |
| Historical | Preserved design context that is not current language syntax |
The sourceDocs frontmatter identifies legacy inputs; verifiedAgainst
identifies current implementation evidence. When they disagree, this book
follows the implementation and calls out the unsupported or provisional edge.
Status applies to the page, not automatically to every adjacent subsystem. A verified syntax page may link to a provisional backend behavior. Conversely, a provisional page can contain individually verified core operations while reserving judgment on its moving edges. Each chapter should make those boundaries explicit in its prose.
Current spelling at a glance
struct Order {
id: int
items: List[LineItem]
}
error OrderError {
Empty
}
fn total(order: Order): float ! OrderError {
if order.items.is_empty() {
error Empty
}
mut sum := 0.0
for item in order.items {
sum += item.price
}
return sum
}Atoll uses snake_case for functions, methods, locals, parameters, and fields; PascalCase for nominal/composite types and enum variants; and SCREAMING_SNAKE_CASE for constants. Scalar builtins remain lowercase.
The legacy docs frequently use let, camelCase APIs, Int/Boolean,
angle-bracket generics, data, and proposed framework declarations. This book
rewrites examples into current syntax and records the source audit in
legacy documentation audit.
For normative grammar and invariants, use the Language Specification. For lowering and representation, continue to the Compiler, IR, and Runtime sections.