Expand description
PEG grammar AST + recursive-descent interpreter (G-2).
The Peg enum is the grammar AST. It derives DslNode + DslSchema
from the kit — grammars therefore get the L1-L4.6 toolchain for free
(walk traversal, schema JSON, lint, variant_name, MCP pretty-print)
per parser-design §2. Parse execution is a small dedicated
recursive-descent interpreter that walks a Grammar value against
input text and produces a ParseTree (crate root).
§Quality bar (parser-design §3.5, non-negotiable)
- PEG semantics, exactly. Ordered
Peg::Choicecommits on the first alternative that matches (no reparse of committed input);Peg::Repeatis greedy and never backtracks into completed iterations; a failed alternative restores the input position fully (no partial-consume leaks). - Farthest-failure tracking from day one. The interpreter records
the rightmost failure position + the expected set at that point as
it runs.
dsl_kit_loadsees a diagnostic with position + expected set on failure. - Termination guarantees at runtime. Left recursion (a rule
re-entered at the same input position) and nullable-body
Peg::Repeat(body succeeds without consuming) both trip guards that either error out (left recursion) or break the loop (nullable repeat) rather than hanging. G-3’sGrammarCheckwill catch these statically.
§Capture model
Three capture primitives:
Peg::Node{ variant, body }— opens aParseTreescope with the given variant name. Insidebody, everyPeg::Fieldbinding becomes a field or child slot on the tree. On success the tree is contributed upwards (to an enclosing Field, or to the top-level result at the root).Peg::Field{ name, body }— captures body’s productions (raw text spans fromPeg::Token+ trees fromPeg::Node) and binds them undernameon the enclosing Node scope. Productions that are all text → oneRawValue::Textfield (joined). All trees → child slot with one or more subtrees. Mixed → tree productions win (raw text is dropped as syntactic noise from sub-Nodes’ brackets etc.); empty → the Field silently no-ops. G-3’sGrammarCheckwill surface Mixed as a grammar bug.Peg::KeyedEntry{ slot, key, value }— one entry of a keyed child slot (Multiplicity::Map).keyproduces the entry’s key text,valuethe entry’s subtree, and the pair lands inParseTree::keyed_childrenunderslot. A separate primitive rather than aFieldconvention because aFieldbinds one name to its productions, which cannot express a name the input supplies; pairing adjacent text and tree productions inside aFieldinstead would make the capture depend on production order, which every backtracking path is free to disturb.Peg::Nodesorts each keyed slot by key before emitting, so grammars need not care what order the source was written in — the canonical orderParseTreerequires falls out.
§Whitespace policy (parser-design §3.5, decided in G-2)
Implicit skip of [ \t\r\n]* before every Peg::Token (except
the %ws class itself, which matches one-or-more whitespace
literally). No per-rule opt-out yet — deferred until a concrete
consumer demands it. Leading and trailing whitespace at the input
boundary are also skipped by Grammar::parse.
§Token pattern language
Peg::Token’s pat string is either a literal or a class:
%ident—[A-Za-z_][A-Za-z_0-9]*%int—-?[0-9]+%str— a double-quoted string literal with\"\\\n\t\rescapes. Unlike every other token, the production it contributes is the decoded inner content (quotes stripped, escapes resolved), so aFieldwrapping%strbinds the string value directly.%str_raw— same matching rules as%str, but the production is the raw source slice (quotes and escape sequences kept verbatim). Field authors use this when downstream consumers need the JSON-compatible literal — typically the built-inVec<String>mapping inschema_gen, which relies onserde_json::from_strinbuild_field_vecto reparse the captured["a", "b"]text.%ws—[ \t\r\n]+(skip is disabled for this class)%kw:<word>— literal<word>with a word-boundary guard: the byte immediately after the match must not be a word char. This is how you write reserved words likelet/inwithout swallowing the prefix of identifiers such asletme.- anything else — plain literal match with no boundary guard. Use
this for punctuation like
+,*,(,),=.
Modules§
- codes
- Diagnostic codes emitted by the PEG interpreter.
Structs§
Enums§
- Peg
- PEG grammar AST.
Functions§
- choice
- Builds a
Peg::Choicenode with a fresh id. - field
- Builds a
Peg::Fieldcapture node with a fresh id. - keyed_
entry - Builds a
Peg::KeyedEntrycapture node with a fresh id. - node
- Builds a
Peg::Nodecapture node with a fresh id. - repeat
- Builds a
Peg::Repeatnode with a fresh id. - rule
- Builds a
Peg::Rulenode with a fresh id. - rule_
ref - Builds a
Peg::RuleRefnode with a fresh id. - seq
- Builds a
Peg::Seqnode with a fresh id. - token
- Builds a
Peg::Tokennode with a fresh id.