Skip to main content

Module peg

Module peg 

Source
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::Choice commits on the first alternative that matches (no reparse of committed input); Peg::Repeat is 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_load sees 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’s GrammarCheck will catch these statically.

§Capture model

Three capture primitives:

  • Peg::Node { variant, body } — opens a ParseTree scope with the given variant name. Inside body, every Peg::Field binding 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 from Peg::Token + trees from Peg::Node) and binds them under name on the enclosing Node scope. Productions that are all text → one RawValue::Text field (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’s GrammarCheck will surface Mixed as a grammar bug.
  • Peg::KeyedEntry { slot, key, value } — one entry of a keyed child slot (Multiplicity::Map). key produces the entry’s key text, value the entry’s subtree, and the pair lands in ParseTree::keyed_children under slot. A separate primitive rather than a Field convention because a Field binds one name to its productions, which cannot express a name the input supplies; pairing adjacent text and tree productions inside a Field instead would make the capture depend on production order, which every backtracking path is free to disturb. Peg::Node sorts each keyed slot by key before emitting, so grammars need not care what order the source was written in — the canonical order ParseTree requires 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 \r escapes. Unlike every other token, the production it contributes is the decoded inner content (quotes stripped, escapes resolved), so a Field wrapping %str binds 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-in Vec<String> mapping in schema_gen, which relies on serde_json::from_str in build_field_vec to 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 like let / in without swallowing the prefix of identifiers such as letme.
  • anything else — plain literal match with no boundary guard. Use this for punctuation like +, *, (, ), =.

Modules§

codes
Diagnostic codes emitted by the PEG interpreter.

Structs§

Grammar
A PEG grammar: a flat list of top-level Peg::Rules plus the name of the start rule.

Enums§

Peg
PEG grammar AST.

Functions§

choice
Builds a Peg::Choice node with a fresh id.
field
Builds a Peg::Field capture node with a fresh id.
keyed_entry
Builds a Peg::KeyedEntry capture node with a fresh id.
node
Builds a Peg::Node capture node with a fresh id.
repeat
Builds a Peg::Repeat node with a fresh id.
rule
Builds a Peg::Rule node with a fresh id.
rule_ref
Builds a Peg::RuleRef node with a fresh id.
seq
Builds a Peg::Seq node with a fresh id.
token
Builds a Peg::Token node with a fresh id.