Language Reference

The language in full, organized for looking things up rather than for reading through.

The tour teaches sysl in the order the ideas make sense to learn. This section is the other shape: every construct written down once, in its own place, with the rules complete rather than the ones a beginner needs first.

It is meant to answer the question you actually have. What may follow for? Which conversions are implicit? What exactly does ? do to a &T payload? When is a closure boxed? Those are lookups, and a tutorial answers them only by accident.

The same guarantee holds here. Every program on these pages is compiled and run by the test suite, and every refusal is a refusal the compiler really makes, quoted from its own diagnostic. A page that drifts from the compiler fails the build. Where a rule has an edge, the edge is shown as a program rather than described — a sentence about what would happen is a guess, and a fenced block that runs is not.

Where a rule exists for a reason, the reason is here too. A reference that only lists behaviour tells you what to type and leaves you unable to predict anything you have not looked up yet. sysl’s rules are unusually load-bearing on one another — the memory model decides what a closure costs, which decides what a trait object can be, which decides what a generic can promise — so the connections are written down where they matter. Thorough is the point; brevity is not.

How this section is organized

The order runs from the smallest units upward: what the compiler reads, then what a type is, then what an expression is, then the declarations that bind them, then the systems built on top — memory, traits, generics, reflection, modules, errors, async and tasks, the foreign interface, and the forms that reach into the compilation itself.

One page is the opposite of thorough, on purpose. Compact reference is the whole language on a single page — tables and one-line rules, plus the house idioms — for a reader who already programs and wants the rules without the argument, or for a tool with a budget to read them in. Everything on it is said in full somewhere above.

One page is about the project rather than the language. Packages is what package.hocon says and what it means to depend on somebody else’s code — a build-time concern rather than a rule the compiler enforces on an expression, but one that decides which modules a program even has.

What ships beside the language is a section of its own. The standard library is ordinary sysl — no type in it is a language feature and a program could have written any of it — so it is documented apart from the rules the compiler enforces.

This section is the specification. It used to share that job with a set of numbered design chapters in the compiler’s repository, which carried each rule’s argument and the alternatives that were rejected; those were removed once this section had overtaken them, because two documents saying the same thing is one that goes stale. What is here is what the language is, and the reason is given wherever a rule would be unpredictable without it.

Pages

Lexical structure — What the compiler reads before it parses anything — tokens, literals, and the layout rules that decide where a statement ends.
Types — Every type the language has — the open integer families, the closed float set, and the aggregates built on them.
Expressions and operators — The precedence ladder, every operator's meaning, evaluation order, and the traits an operator dispatches through.
Statements and control flow — Blocks, bindings, every loop and branch form, and what each one yields — because in sysl most of them yield something.
Declarations — Bindings, functions, structs, enums and type declarations — what each form states, and what it leaves to be inferred.
Patterns and matching — Every pattern form, how arms are chosen, what guards do to exhaustiveness, and why alternatives may not bind.
Memory — The three modes, ARC, weak references, places and `ref`, escape analysis, the raw tier, and device memory.
Arrays and slices — Two sequence types — storage and a view of it — and the rules for writing one down, indexing it, slicing it, and knowing what it keeps alive.
Fixed-point numbers — `q31`, `i32q16`, `u32q32` — an integer counted in units of 2^-F, with the arithmetic a DSP wants: saturating, rounding to nearest, mixed formats read from where a result goes, and literals that are constant data on a board with no FPU.
Vectors — `T` is an array that computes lane-wise — one instruction for N additions, one kernel for every register width, and it still compiles where there is no vector unit at all.
Strings — An immutable, validated `[]u8` — the representation, the guarantee, every form that makes new bytes, and where the allocator line falls.
Traits — The one polymorphism mechanism — declaring, implementing, coherence, associated types, required traits, and trait objects.
Generics — Type parameters, bidirectional inference, bounds checked at the definition, and monomorphization.
Reflection — What a type answers about its own make-up while compiling — kind, name, fields, variants, annotations — and how a library writes a derivation from it.
Modules — A module is a directory — visibility, imports, the acyclic graph, where a program starts, and separate compilation.
Packages — package.hocon, dependencies on other people's code, version selection, and what a fetched package's modules are called here.
Errors, traps and contracts — Two channels for failure — a value you handle and a stop you cannot — plus the constrained types, invariants and contracts that decide which one you get.
Async and tasks — Async functions, the Task they hand back, await, the executor contract, frames on the heap, cancellation by drop, and when a task may cross a concurrency domain.
The foreign interface — `extern`, link names, intrinsics, function addresses, variadics, opaque handles, interrupt handlers, and a library that carries C.
Inline assembly — Machine instructions, in an arm per architecture — where operands are values and the compiler owns the constraint string, the escaping, and the labels.
Attributes, annotations, and compile time — `::` attributes a type answers, the eighteen annotations a function takes, the three that lay out or place what they mark, the five a file's header takes, `@assert` which stands on its own, and the `#if` directive that gates lines before the lexer sees them.
Verification — Quantifiers, loop invariants, termination measures, `@pure`, `@reads`/`@writes`, `@ghost`, and `sysl prove` — the clauses that say what a program means, and the prover that reads them.
Compact reference — The whole language on one page, for a reader who already programs — tables and one-line rules instead of explanation, with the idioms that keep new code in style.