Brass documentation

Every Brass document in one place, grouped by what you're looking for.

Start here

The two essays: what Brass is, and what the trials found.

• Welcome to Brass Language: a getting-to-know-you tour of the language, set in a dinosaur park.
• The AI Token Efficiency of Brass: what forty coding sessions tell us about language, tooling and cost.

Reference

For looking things up. When two documents disagree, the specification wins.

• Specification: which programs are valid, what checking establishes and how programs behave when they run.
• Grammar: how each construct is written and how its operators group.
• Cheat sheet: every common form on one page, with notes for Python and Rust programmers.
• Principles: why the rules take the form they do, what the design gives up and what the trials established.

Code

Brass at work, from small programs to complete systems.

• Everyday code: six ordinary programs, from FizzBuzz to retrying a call, each with a verdict on how Brass handles it.
• Three examples: complete programs that follow permissions, promises and state changes.
  • Refund: a merchant refunds a customer on an open support case.
  • Paddock lockdown: a staff member asks to lock a paddock down.
  • Feeding delivery: a keeper delivers a paddock's pending feeding.

Design notes

Companions to the specification: how the brass tool reports what it finds, and what a full checker has to handle.

• Brass Info Report: how brass shows what a function requires, what it can affect and what depends on it.
• Brass Checker: the cases a full checker must accept and reject, its proof limits and its messages.

Background

• History: how Brass went from a question to v0.3, week by week.