Mo grammar, v0
Draft, 12 Sep 2026. Covers every construct in design-v0/04-syntax.md. EBNF: x* zero or more, x+ one or more, x? optional, | alternatives, "…" literal tokens. NL is a newline; the lexer joins lines that end inside an open paren. The formatter owns all whitespace, so indentation carries no meaning.
1. Lexical
comment = "#" any* NL
ident = lower (alnum | "_")* "?"? # snake_case; "?" only on predicates
TypeName = Upper (alnum)* # CapCase; also enum variants, modules
path = TypeName ("." TypeName)* # Payments.Refund, Money
int = digit (digit | "_")* # 10_000
float = int "." digit+
string = '"' (char | escape | "#{" expr "}")* '"'
| '"""' NL (line NL)* '"""' # common indentation stripped; escapes and holes as in '"'
escape = "\n" | "\t" | "\r" | "\\" | '\"' | "\#" | "\u{" hex hex? hex? hex? hex? hex? "}" # Session 6, step 27: a Unicode scalar value; any other backslash is MO0101
atom = ":" ident # only where the grammar names it
keyword = module use intent never expose fn requires ensures var inout if else end
case for in break return try and or implies is old result assert
struct enum type where trait impl process state invariant message
supervisor child per recipe needs test rejects property any
verified true false
# Session 6, step 27: state is a keyword only inside a process, result only inside an
# ensures, and old only inside an ensures or an invariant; elsewhere each is a name
No block comments, no single-quoted strings, no literal type suffixes. Every string interpolates.
2. Module
module = "module" path NL expose? use* intent? never* decl* test* verified?
expose = "expose" name ("," name)* NL # the exposed surface; everything else is private
name = ident | TypeName
use = "use" path "{" name ("," name)* "}" NL # types and functions from the expose line; no bare use, no wildcards, no aliases
intent = "intent" string NL
never = "never" string NL (comprehension | expr NL) "end" NL # a comprehension, or one checkable call such as flows(...)
verified = "verified:" any* NL # toolchain-owned; hand edits are errors
decl = struct | enum | typedef | trait | impl | fn | main | process | supervisor | recipe
main = "fn" "main" "(" ident ":" "Platform" ")" NL block "end" NL # no return type, like update; once per program
One module per file; the file path equals the module path.
3. Types
typeexpr = path ("(" typeexpr ("," typeexpr)* ")")? # Result(Charge, RefundError)
| "(" typeexpr ("," typeexpr)+ ")" # tuple
| typeexpr "where" expr # refinement: List(T) where size <= 1_000
struct = "struct" TypeName NL field+ "end" NL
field = ident ":" typeexpr NL
enum = "enum" TypeName NL variant+ "end" NL
variant = TypeName ("(" field_list ")")? NL
field_list = ident ":" typeexpr ("," ident ":" typeexpr)*
typedef = "type" TypeName "=" typeexpr NL # type Money = UInt64 where value <= ...
trait = "trait" TypeName NL signature+ "end" NL
impl = "impl" TypeName "for" typeexpr NL fn+ "end" NL
4. Functions and contracts
fn = signature NL contract* NL? block "end" NL
params_untyped = ident ("," ident)* # anonymous function parameters: fn(acc, x)
signature = "fn" ident "(" params? ")" (":" typeexpr)? generics? # no return type: returns nothing, like main
params = param ("," param)*
param = "inout"? ident ":" typeexpr
generics = "where" TypeName ":" path ("," TypeName ":" path)*
contract = ("requires" | "ensures") expr NL
Contracts sit directly under the signature; a blank line separates them from the body. result is valid only inside ensures; old(expr) inside ensures and invariant. Session 6, step 27: only there are they keywords, and elsewhere result and old are names like any other, a parameter, a binding, a var, a for name, a pattern’s binding, or a field, as state is outside a process.
5. Statements
block = stmt*
stmt = binding | assign | return | for | if_stmt | case | assert | "break" NL | expr NL
assert = "assert" expr NL # test, rejects, and property blocks only
binding = "var"? ident "=" expr NL
assign = place ("=" | "+=" | "-=") expr NL # place must root at a var, inout, or state
place = ident ("." ident)*
return = "return" expr ("if" expr)? NL # trailing if only here
for = "for" (ident | "_") "in" expr NL block "end" NL # _ when the index is unused
if_stmt = "if" expr NL block ("else" NL block)? "end" NL
case = "case" expr NL arm+ "end" NL
arm = pattern ("|" pattern)* ("if" expr)? ":" (expr NL | NL block) # runs until the next arm or end
Session 5, step 18: an arm may group alternatives, A | B | C: body, so a closed enum’s arms that share a body are one arm and still name every variant.
6. Expressions
expr = or_expr ("implies" or_expr)?
or_expr = and_expr ("or" and_expr)* # on Option(T): default
and_expr = not_expr ("and" not_expr)*
not_expr = "!" not_expr | cmp
cmp = range (("==" | "!=" | "<" | "<=" | ">" | ">=") range | "is" pattern)?
range = add (".." add)? # a..b is a up to and excluding b
add = mul (("+" | "-") mul)* # left-associative: a - b - c is (a - b) - c
mul = unary (("*" | "/" | "%") unary)*
unary = "-" unary | "try" unary | postfix
postfix = primary ( "." ident call_args? # dot call: x.f(a) is f(x, a); 200.ms
| "." int # tuple field: result.0
| call_args )*
call_args = "(" (arg ("," arg)*)? ")"
arg = (ident ":")? expr # named args: within: 200.ms
primary = literal | ident | path call_args? # Money.cents(500), Charge.fixture(...)
| TypeName call_args? # Ok(x), Some(x), None, Refund(charge: id, ...)
| "(" expr ("," expr)* ")" # group or tuple
| "[" (expr ("," expr)*)? "]"
| "if" expr NL block "else" NL block "end" # if as expression
| "if" expr ":" expr "else" ":" expr # one-line if: a value only, else: required
| "case" expr NL arm+ "end"
| "fn" "(" params_untyped? ")" (expr | NL block) "end" # anonymous, call-argument only
| "old" "(" expr ")" | "result" # in ensures (old also in invariant); elsewhere names (Session 6, step 27)
| "any" "(" typeexpr ")" # generators, property only
literal = int | float | string | "true" | "false"
Anonymous functions may appear only as an arg. Construction is always by named fields; positional construction does not parse.
Session 5, step 25: an if may be one line where a value goes, label = if n > 1: "lines" else: "line" (pick 16). else: is required and each branch is one expression; a statement in a branch (return, a binding, an assignment) is MO0101, and so is a one-line if that starts a line, which is a statement. Its tree is the block form’s, and mo fmt writes it on one line when it fits and no comment sits inside, and as the block otherwise.
7. Patterns
pattern = "_" | ident | "-"? literal
| TypeName ("(" pattern ")")? # one-field variant, positional: Ok(c), Some(x), Enqueue(request)
| TypeName "(" ident ":" pattern ("," ident ":" pattern)* ")" # named fields: WindowExpired(now: n)
| "(" pattern ("," pattern)* ")"
_ is allowed inside a pattern, never as a whole arm on a closed enum (a semantic rule).
Session 5, step 18: the alternatives of a grouped arm (arm, §5) are each a whole pattern; they bind the same names, of the same types, or none, and each counts toward exhaustiveness as an arm of its own. A grouped pattern is an arm’s only; is takes one pattern.
8. Comprehensions (never, property)
comprehension = "for" gen ("," gen)* ("if" expr)? NL block "end" # every for closes with end; in never the block is one expr
gen = ident "in" expr # r in Refund.all, x in any(Money)
9. Processes and supervisors
process = "process" TypeName "(" params? ")" ("mailbox:" int)? NL
state invariant* message+ update "end" NL
state = "state" NL state_field+ "end" NL
state_field = ident ":" typeexpr ("=" expr)? NL # "= expr" required when the type has no zero value
invariant = "invariant" string NL expr NL "end" NL # the condition that holds after every update
message = "message" TypeName ("(" field_list ")")? (":" typeexpr)? NL # reply type for ask
update = "fn" "update" "(" "state" "," "message" ")" NL case "end" NL
supervisor = "supervisor" TypeName ("(" params? ")")? NL child+ "end" NL
child = "child" TypeName call_args? "," "restart:" atom ("," "max_restarts:" int "per" expr)? NL # args are the process's parameters
state is mutable inside update and nowhere else. Restart atoms: :always, :on_crash, :never.
10. Tests
test = "test" "rejects"? string NL block "end" NL
| "property" string NL comprehension "end" NL
assert = "assert" expr NL # a stmt inside test blocks only
11. Recipes
recipe = "recipe" TypeName NL intent needs signature_only* never* test* "end" NL
needs = "needs" (TypeName ("," TypeName)* | "nothing") NL
signature_only = signature NL contract* "end" NL # no body
Session 5, step 19: a recipe may hold never blocks, after its signatures and before its tests. They are checked in the recipe’s module and run only against an implementation, with the recipe’s tests, by mo check --recipe (design-v0/06); before, a recipe’s nevers sat at its module’s head and nothing ran them.
Semantic rules the grammar does not express
- A name binds once per scope; rebinding and unused bindings are errors. Only
var,inout, andstateplaces may be assigned. caseis exhaustive.tryapplies only toResultandOption.oron anOption(T)yieldsT.- Function bodies are at most 70 lines, nesting at most 3, parameters at most 6, process state at most 12 fields (the 500-line file law was dropped in session 6, step 27).
- Every
requireshas atest rejectsthat trips it. Every capability call that can wait passeswithin:and returns aResult;clock.nowandevents.emitcannot wait and return plain values. - The
exposeline, the exposed signatures, contracts,never, andverified:form the spec altitude; changing them is a breaking change. Every name onexposemust be declared in the module; an undeclared or duplicated name is an error. - Session 4:
pubreplaced by theexposeline (Robert:pubhas OOP vibes).use A.B{X, Y}lost the dot before the braces (Robert). Comprehensions close withend(Robert: no implicit block ends). Formatter rule: aforwhose body is a pure expression is rewritten tomap/filter/reduce;forstays for effects,try,break,return.
Session 5 decisions (the productions above already reflect them)
Three workers wrote the 50-file corpus from this grammar and recorded where it ran out (examples/GAPS.md, the bake-off branches). Claude (Fable) decided each gap here, on Robert’s instruction to decide and build; every decision is provisional and first tested by the interpreter milestone unless another test is named. Robert overturns any of them on sight.
Grammar bugs found by the corpus, fixed above: cmp demanded an operand after is pattern; assert was missing from stmt; old was allowed only in ensures but invariant needs it; never allowed only a comprehension, yet flows(...) is a bare call; add was right-recursive; params_untyped was used but never defined; a comprehension body is a block, so property can assert.
- Literals. An integer literal is typed from its uses inside the function (Rust-style inference); with no constraint it is
Int64. Float literals areFloat64. Integer types:Int8…Int64,UInt8…UInt64; floatsFloat32,Float64.sizeon any collection or string isUInt64; named conversions (n.to_u32) cross widths, never implicit ones. - Ranges.
a..bexcludesb, so0..nhasnitems. - Strings.
s.sizecounts graphemes;s.bytesis the byte sequence,s.bytes.sizecounts it. - Body value. The last statement of a body is its value; an
if/casein that position is the expression form. - Patterns. A one-field variant is matched positionally (
Ok(c),Some(x),Enqueue(request)); variants with two or more fields are matched by name. Construction is always by name. A name bound byisinsideassertis in scope for the rest of the test; insideif x is Some(v)it is in scope for the then-block. - Anonymous functions.
fn(acc, x) ... end;reduce(start, fn(acc, x) ... end)is the argument order. - Traits.
Selfnames the implementing type in a trait’s signatures. - Refinements. A base-type value is checked when it crosses into a refined parameter or field; a failed check is a tripped contract, so
test rejectscovers it. Type.all. Inneveronly; means every value of that type the program holds. Tier 2 skips such anever, tier 3 checks it inMo.Sim.- Deadlines (amends the chapter 2 law). Only capability calls that can wait take
within:and return aResult; the platform marks which ones.clock.nowandevents.emitcannot wait and return plain values, so chapter 4’s example stands as written. tryacross error types.tryonResult(T, E1)inside a function returningResult(_, E2)requires every variant ofE1to exist inE2with the same name and fields; the value is re-tagged, nothing is converted. Platform errors are ordinary enums (Timeout,NotFound(id: ChargeId)). First tested by the checker on the refund module.- Time.
TimeandDurationare stdlib types;10.ms,90.days,1.minuteareDuration;Time - TimeisDuration;Time + DurationisTime. - Platforms.
mo testalways runs onMo.Sim,mo runon the real platform; a module never names its platform, so theuse Mo.Simline in chapter 3 is withdrawn. In tests, every capability has afixtureconstructor (Clock.fixture(), a fixed instant that moves with the simulator’s time when a fixture call waits, frozen inside an update, session 6, step 28;Fs.fixture(), empty;Fs.fixture(delay: 1.minute), times out) andTime.fixture()is a fixed instant. Narrowing (fs.scoped(...).read_only) is pure and keeps the type. - Processes.
statefields start at the type’s zero value (0,"",[],None); a field whose type has no zero (an enum, a refinement excluding zero) must write= expr.Name.start(args)givesHandle(Name);h.send(Msg)is a statement;h.ask(Msg, within: d)returnsResult(T, AskError)for the message’s reply typeT, withAskError=Timeout | Down. The arm for a message with a reply type evaluates to the reply. Messages from one sender arrive in order. A test maystarta process without a supervisor; the test runner is its supervisor. - The deferred reply (Session 8, step 31). In the arm for a message that carries a reply,
reply_to(aReply(T)) andreply_by(the asker’sDeadline) are bound asstateis; the arm answers by its value or by movingreply_tointo astatefield, exactly one of the two (MO0411), and a held reply is answered later byreply.answer(value). No new production: they are names bound in that position, chapter 3 and chapter 9 (examples/processes/deferred-reply.mo). - Supervisors. A supervisor takes parameters like a process and passes them on the
childline:supervisor Payments(db: Ledger, clock: Clock, events: Events)…child RefundQueue(db, clock, events), restart: :always. The one piece of new syntax in this list; nothing else could say where a child’s capabilities come from. First tested by program 1’smain. main. Robert (Q18):fn main(platform: Platform)with no return type, likeupdate; exit code 0, or the lastplatform.exit(code), or 70 on a crash.Platformholdsargs,env,stdout,stderr,fs,clock,exit.mo run file.mo -- argsruns it onMo.Server.- Files. A CapCase module segment maps to a lowercase, hyphen-separated file name:
Basics.AnonymousFunctionsisbasics/anonymous-functions.mo. - Recipes. A recipe’s tests are the file’s tests. A
test rejectsinside a recipe must trip arequiresdeclared in the recipe (chapter 6’s example is corrected). - Stdlib names the corpus may assume. Lists:
size,push,map,filter,reduce,contains?,first,last. Strings:size,bytes,starts_with?.Fs:read(path, within:)givingResult(String, FsError). Integers:checked_add,saturating_sub,wrapping_muland their siblings (checked_returnsOption). Everything else is a gap until the stdlib chapter exists. invariantstays true. The block is the condition that holds after everyupdate(state.done >= old(state.done)under “done never goes backwards”), and it trips when the block is false;neverkeeps the negative form. Session 5, step 18: flipped from “true when broken”, which the outside review of 13 Sep showed reads backwards (state.count <= 3tripped on a count of 1). First tested byprocesses/invariant-trips.mounder both runtimes.- Sibling handles. A supervisor that must give one child another’s handle takes it as a parameter (
supervisor Line(sink: Handle(Sink)),child Source(sink)); who startsSinkfirst ismain’s job. First tested by program 1. - Line budget. A corpus file with two processes may exceed 40 lines; the 70-line function law is the real bound.
for _ in 0..n._as the loop binder says the index is unused; the unused-binding law does not fire. Found by Fable testing mailbox bounds in step 4.usenames functions too.use A.B{X, y}brings the named types and functions into scope by bare name; every name must be onA.B’sexposeline; a bareuse A.BisMO0321. A program is a tree of files under amo.rootmarker (or the main file’s directory);A.Bisa/b.mo. Found by program 2 (toolchain bug 1). First tested by step 7.- Program root and module files (step 7).
mo.rootmarks the program root (examples/programs/mo.rootfor the corpus).MO0322: ausenames something not on the module’sexposeline.MO0323: the module has no file under the root, or its file declares a different module. Auseof a module with no file is allowed only when every name is a prelude stand-in. - Step 12 decisions (from program 3). A function may omit its return type when it returns nothing; a negative integer literal is a pattern;
String.byte_sizeis a stdlib row. Found bykv(examples/GAPS.md). First tested by step 12.