Module parser 

Parser infrastructure for the query language.

Architecture

This parser produces a lossless concrete syntax tree (CST) via Rowan’s green tree builder. Key design decisions borrowed from rust-analyzer, rnix-parser, and taplo:

• Zero-copy parsing: tokens carry spans, text sliced only when building tree nodes
• Trivia buffering: whitespace/comments collected, then attached as leading trivia
• Checkpoint-based wrapping: retroactively wrap nodes for quantifiers *+?
• Explicit recovery sets: per-production sets determine when to bail vs consume diagnostics

Recovery Strategy

The parser is resilient — it always produces a tree. Recovery follows these rules:

1. Unknown tokens get wrapped in SyntaxKind::Error nodes and consumed
2. Missing expected tokens emit a diagnostic but don’t consume (parent may handle)
3. Recovery sets define “synchronization points” per production
4. On recursion limit, remaining input goes into single Error node

However, fuel exhaustion (exec_fuel, recursion_fuel) returns an actual error immediately.

Modules

ast

Typed AST wrappers over CST nodes.

Structs

AltExpr

Anchor

AnonymousNode

Anonymous node: string literal ("+") or wildcard (_). Maps from CST Str or Wildcard.

Branch

CapturedExpr

Def

FieldExpr

NamedNode

NegatedField

NodePredicate

ParseResult

Parser

Trivia tokens are buffered and flushed when starting a new node.

QuantifiedExpr

Ref

RegexLiteral

Root

SeqExpr

Token

Zero-copy token: kind + span, text retrieved via token_text when needed.

Type

Enums

AltKind

Whether an alternation uses tagged or untagged branches.

Expr

Expression: any pattern that can appear in the tree.

PredicateOp

Predicate operator for node text filtering.

PredicateValue

Predicate value: either a string or a regex pattern.

SeqItem

Either an expression or an anchor in a sequence.

SyntaxKind

All token and node kinds. Tokens first, then nodes, then __LAST sentinel. #[repr(u16)] enables safe transmute in kind_from_raw.

Functions

is_truly_empty_scope

Checks if expression is a truly empty scope (sequence/alternation with no children). Used to distinguish { } @x (empty struct) from {(expr) @_} @x (Node capture).

lex

Tokenizes source into a vector of span-based tokens.

token_src

Extracts token text with source lifetime.

token_text

Retrieves the text slice for a token. O(1) slice into source.

Type Aliases

SyntaxNode

Type aliases for Rowan types parameterized by our language.

SyntaxToken