Skip to content

Language Reference

The language/ folder is the language reference. It owns the source forms Catalyst code can write and the type-system semantics those forms lower through.

This folder should answer "what can I write, what does it mean, and which type-system rules does it depend on?"

Source Forms

  • Syntax: source grammar, comments, keywords, literals, expected-type shorthand, declarations, destructuring, operators, move syntax, conditional declarations, and naming conventions.
  • Functions: function declaration syntax, capabilities, parameters, signatures, function items, function pointers, defaults, inference, and main.
  • Control Flow: blocks, statements, conditionals, optional bindings, loops, loop-source selection, and divergence.
  • Errors: error-set syntax, error values, try, catch, and error handling forms.
  • Modules, Imports, and Module Roots: namespaces, module(...), include(...), imports, module boundaries, prelude initial-scope behavior, and the std root as a namespace.
  • Attributes: attribute syntax, provider shape, targets, resolution, and diagnostics.
  • Pattern Matching: pattern syntax and matching forms.
  • Capabilities and Destructuring: ordinary-parameter capability conventions and destructuring at source boundaries.
  • Comptime: source-level compile-time execution contract and its tooling/interpreter boundary.

Type Semantics

Boundary

Keep these outside language/:

  • compiler phase architecture, parser/sema/IR/backend contracts, diagnostics infrastructure, and snapshot policy: use compiler/
  • compiler-provided implicit namespace surface: use prelude/
  • normal std module namespace contents: use standard-library/
  • ABI details: use interop/
  • realtime and performance models: use performance/

Within language/, keep source-form docs and type-semantics docs separate enough to preserve ownership. For example, for loop source selection belongs under control flow, while Iterator(Item) laws belong under contracts.