Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Language reference

This page is a reference index — high-level pointers to the canonical formal definitions in the spec/ corpus. Where Concepts is pedagogical (how to think in Aperio), this page is for looking up what the compiler actually accepts.

The spec is the source of truth. If something here disagrees with the spec, the spec wins.

Grammar and syntax

  • spec/grammar.ebnf — formal grammar in EBNF. Every syntactic construct the parser accepts.
  • spec/tokens.md — lexical structure: identifier rules, reserved words, literal forms (integer / float / decimal / string / bytes / time / duration / f-string), operators, contextual keywords.
  • spec/precedence.md — expression precedence and associativity table.

Semantics

  • spec/semantics.md — operational semantics. Program startup, locus instantiation, lifecycle method dispatch, bus dispatch, closure-test evaluation, recovery primitives, dissolve timing rules, fallible call semantics, topic declarations.
  • spec/runtime.md — what the runtime ships with: region allocator, scheduler, bus router, time primitives, schedule classes, perspective hot-load machinery.

Types

  • spec/types.md — the type system: primitive types, compound types, projection-class types, locus types, perspective types, structural interfaces, fallible typing.
  • Numeric coercion: Int → Float widening at let-binding type ascriptions and fn-arg sites (one-way; Decimal never participates). See types.md § “Numeric coercion”.

Storage and memory

  • spec/memory.md — the memory model. Hierarchical regions, per-projection- class allocators, capacity slots (pool / heap), bookkeeping reclamation, drain cascade, region-escape rules. Includes the codegen ABI summary.
  • spec/forms.md — the @form(...) annotation system: @form(vec), @form(hashmap), @form(ring_buffer). Contract, lowering, performance bands, anti-patterns.

Projects and packaging

  • spec/projects.md — project layout, per-directory seed model (F.19), cross-seed imports (F.25), workspace fallback, resolution order, mangling scheme.
  • spec/packages.md — the v1 package surface. aperio.toml manifest, aperio.lock, aperio fetch git-based dependency fetcher.

Style and conventions

Testing

  • spec/testing.md — the testing pipeline. Three layers of correctness, the std::test assertion library, benchmark surface.

Design rationale

  • spec/design-rationale.md — why the language is shaped the way it is. Numbered commitments F.0 through F.26 cover every design decision the compiler currently makes — from projection-class semantics to capacity slots to structural interfaces to the package model — with a “considered and rejected” section for each.

This is the longest single document in the corpus and the most useful for understanding the rationale behind a particular surface choice. Worth reading once, end-to-end, once you’ve internalized Concepts.

Standard library