Module parser 

Event-based recovering parser (spec 0001 §4.2, §4.3, §4.4, §4.6).

Architecture

The parser is a hand-written recursive-descent engine that emits an Event stream rather than directly mutating a tree. A separate SyntaxTreeBuilder — living in the internal builder module — consumes the events and produces the rowan green tree. This split lets the parser:

• rewrite events for associativity fixing in Pratt expression parsing (the Start event can be retroactively relocated via the Marker::precede mechanism);
• group or suppress spurious errors before they reach diagnostics;
• interleave trivia tokens (whitespace, comments) between significant tokens so the constructed tree is byte-lossless per §4.4.

Error recovery

Per spec §4.3 the recovering parser exposes two primitives the grammar builds on:

• Synchronisation-set skip (Parser::recover_until): when a clause fails, tokens are bumped into an ERROR node until we see a clause-level keyword, a ;, or EOF.
• Virtual-token insertion (Parser::expect): when a required closer/keyword is missing, an ERROR node of zero width is recorded at the expected position; the parser continues.

Both primitives are shared across productions; per-production recovery tables (spec §4.3) land in a later bead (cy-2vh).

Losslessness invariant

Spec §4.4: parse(s).syntax().to_string() == s for every input. Trivia and ERROR tokens are preserved in the tree; the property test lossless_on_arbitrary_utf8 enforces the invariant.

Structs

Parse

A completed parse: green tree + accumulated syntax errors.

SyntaxError

A single syntax error record. Spec §4.3 + §10.

Functions

parse

Entry point. Parses a complete source file.