rumil library

Rumil — parser combinators for Dart.

Classes

Attempt<E, A>
Wraps the outcome of parser in a Result, always succeeding.
Capture<E, A>
Matches parser and returns the consumed input as a string.
Chainl1<E, A>
Left-associative binary operator chain: p (op p)* folded as ((a op b) op c) op d.
Chainr1<E, A>
Right-associative binary operator chain: p (op p)* folded as a op (b op (c op d)).
Choice<E, A>
Tries each alternative in order until one succeeds.
CustomError
A custom error message.
Debug<E, A>
Prints verbose debug output on enter/exit. No effect on results.
Defer<E, A>
Defers parser construction until first use.
EndOfInput
Reached end of input when more was expected.
Eof<E>
Matches end of input.
Expect<A>
Replaces the error message on failure with message.
Fail<E, A>
Always fails with error, consuming no input.
Failure<E, A>
Parse failed, no value produced.
FirstCharChoice<E, A>
Dispatches to one of dispatch's parsers based on the leading code unit at the current position. O(1) lookup vs Or / Choice's linear scan, useful for value-alternatives in formats with disjoint leading characters (JSON values: n/t/f/digits/"/[/{).
FlatMap<E, A, B>
Sequences source then applies f to the result (monadic bind).
GetPosition<E>
Succeeds without consuming input, yielding the current byte offset.
GreenCache
A mutable, parse-scoped hash-cons cache over green nodes.
GreenMissing<Tok, Syn>
Zero-width placeholder for a token the parser expected but didn't find.
GreenNode<Tok, Syn>
A position-independent green-tree node, parameterized by a language's token alphabet Tok and syntax-tree-node alphabet Syn.
GreenNodeOps
Operations on green trees. Lifted into a namespace rather than methods on GreenNode so the ADT stays minimal data and the operations are easy to extend without modifying the sealed hierarchy. The GreenNodeExt extension below forwards to these for ergonomic node.textLength / node.toSource() call sites.
GreenToken<Tok, Syn>
Leaf token: kind + raw text.
GreenTree<Tok, Syn>
Interior node: kind + ordered children.
GreenUnexpected<Tok, Syn>
Wraps tokens skipped during error recovery.
IncrementalConfig
Incremental-parse tuning.
IncrementalResult<Tok, Syn>
The result of an incremental parse.
InfixLeft<A>
Left-associative infix: a op b op c → (a op b) op c.
InfixRight<A>
Right-associative infix: a op b op c → a op (b op c).
InternedGreen<E, Tok, Syn>
Runs inner and interns its produced green through the parse-scoped GreenCache, replacing the value with the canonical instance so structurally-equal greens across the parse collapse to one heap object.
LineIndex
A precomputed index of newline offsets in a source document.
Location
A position in source text.
LookAhead<E, A>
Matches without consuming input (positive lookahead).
Many<E, A>
Matches parser zero or more times.
Many1<E, A>
Matches parser one or more times.
Mapped<E, A, B>
Transforms the result of source using f.
Memo<E, A>
Memoized parser with optional left-recursion support.
Named<A>
Attaches name to error messages on failure.
NotFollowedBy<A>
Succeeds only if parser would fail (negative lookahead).
Optional<E, A>
Matches parser zero or one times. Returns null on no match.
Or<E, A>
Tries left; on failure (without consuming), tries right.
ParseError
A parse error with source location.
Parser<E, A>
A parser that consumes input and produces a value of type A, or fails with an error of type E.
ParserState
Mutable state carried through a parse.
Partial<E, A>
Parse succeeded but accumulated errors (resilient parsing).
Postfix<A>
Postfix operator: applies after its operand (e.g. n!).
Pratt<E, A>
Top-Down Operator Precedence (Pratt) parser node.
PrattOp<A>
Operator produced by a getOp parser and consumed by the Pratt loop.
PrattOpEntry<A>
A single operator entry in a PrattOpTable bucket.
PrattOperator<A>
Operator description for the pratt combinator.
PrattOpInfix<A>
Infix operator: binds lhs op rhs into a combined value.
PrattOpPostfix<A>
Postfix operator: binds to the accumulated LHS, no RHS needed.
PrattOpTable<A>
Pre-compiled operator dispatch table indexed by the first code unit of each operator's prefix.
PrattPrefix<E, A>
Prefix operator descriptor stored on a Pratt node for stack-safe dispatch. The combinator builder pre-decomposes user-supplied Prefix(symbol, bp, fn) operators into this form so the interpreter can detect prefixes by running symbol directly, push a pending-apply frame, and continue iteratively — without recursing through nud.
PrecomputedLocation
A Location with precomputed line and column.
Prefix<A>
Prefix operator: applies before its operand (e.g. unary -).
RadixNode
A node in a radix tree (compressed trie).
RecoverWith<E, A>
On failure, tries recovery. Success via recovery produces Partial.
RedTree<Tok, Syn>
A position-aware view over a GreenNode, parameterized by a language's token alphabet Tok and syntax-tree-node alphabet Syn.
ReparseableParsers<Tok, Syn>
The grammar-supplied policy an incremental reparse needs.
Result<E, A>
The result of a parse or decode operation.
Satisfy
Matches a single character satisfying pred.
SkipMany<E, A>
Matches parser zero or more times, discarding results.
StringChoice
Matches one of several string alternatives via a radix tree.
StringMatch
Matches the exact string target.
Succeed<E, A>
Always succeeds with value, consuming no input.
Success<E, A>
Parse succeeded with no errors.
TextEdit
An edit replacing [startOffset, endOffset) with newText.
TokenGuard
Post-prefix guard applied before committing to an operator match.
TokenGuardNone
The "no guard" variant.
TokenGuardNotFollowedByChar
Guard requiring the next char not to equal codeUnit.
TokenGuardWordBoundary
Guard requiring the next char to be a non-identifier boundary.
Trace<E, A>
Prints trace output on enter/exit. No effect on results.
TreeSplicing
Subtree replacement operations on green trees.
Unexpected
Found unexpected input where something else was expected.
Zip<E, A, B>
Sequences left then right, returning both results as a record.

Enums

IncrementalStrategy
Which tier of incrementalParse produced the result.

Extension Types

MemoKey
Identity-based memoization key with phantom type parameters.
Span
A contiguous range in source text from start to end.

Extensions

GreenNodeExt on GreenNode<Tok, Syn>
Ergonomic source accessor on GreenNode. GreenNode.textLength is already an instance getter; this adds the matching node.toSource() so callers don't have to reach through GreenNodeOps.
IncrementalGreenExt on GreenNode<Tok, Syn>
Fluent incremental update on a green tree.
ParseErrorOps on Parser<ParseError, A>
Extensions for parsers with ParseError error type.
ParserOps on Parser<E, A>
Core combinator extensions.
ResultOps on Result<E, A>
Convenience extensions on Result.

Functions

alphaNum() → Parser<ParseError, String>
Parses a single alphanumeric character.
anyChar() → Parser<ParseError, String>
Parses any single character.
batchIncrementalParse<Tok, Syn>(GreenNode<Tok, Syn> previousTree, String previousSource, List<TextEdit> edits, ReparseableParsers<Tok, Syn> parsers, {IncrementalConfig config = const IncrementalConfig()}) → IncrementalResult<Tok, Syn>
Batch several edits into one incremental update.
cFamilyPrecedence<A>({required Parser<ParseError, String> sym(String), required A binary(String op, A left, A right), required A unary(String op, A operand)}) → List<PrattOperator<A>>
C-family operator precedence: 15 operators across 7 levels.
chainl1<E, A>(Parser<E, A> p, Parser<E, A Function(A, A)> op) → Parser<E, A>
Left-associative binary operator chain.
chainr1<E, A>(Parser<E, A> p, Parser<E, A Function(A, A)> op) → Parser<E, A>
Right-associative binary operator chain.
char(String c) → Parser<ParseError, String>
Parses a specific single character.
choice<E, A>(List<Parser<E, A>> alternatives) → Parser<E, A>
Try alternatives in order until one succeeds.
count<E, A>(int n, Parser<E, A> p) → Parser<E, List<A>>
Exactly n occurrences of p.
defer<E, A>(Parser<E, A> thunk()) → Parser<E, A>
Defers parser construction for recursive grammars.
digit() → Parser<ParseError, String>
Parses a single digit (0-9).
eof() → Parser<ParseError, void>
Matches end of input.
expectToken<Tok, Syn>(Tok kind, Parser<ParseError, GreenNode<Tok, Syn>> inner) → Parser<ParseError, GreenNode<Tok, Syn>>
Expect a token via inner; on failure synthesize a zero-width GreenMissing placeholder of kind kind and continue as a Result.Partial.
failure<E, A>(E error) → Parser<E, A>
Always fails with error, consuming no input.
firstCharChoice<A>(Map<String, Parser<ParseError, A>> dispatch, {Parser<ParseError, A>? fallback}) → Parser<ParseError, A>
Dispatch to one of several parsers based on the leading character at the current position.
incrementalParse<Tok, Syn>(GreenNode<Tok, Syn> previousTree, String previousSource, TextEdit edit, ReparseableParsers<Tok, Syn> parsers, {IncrementalConfig config = const IncrementalConfig()}) → IncrementalResult<Tok, Syn>
Incrementally update previousTree (parsed from previousSource) after edit, using parsers. See the library doc for the three-tier strategy.
internToken<E, Tok, Syn>(Parser<E, GreenNode<Tok, Syn>> inner) → Parser<E, GreenNode<Tok, Syn>>
Intern inner's produced green through the parse-scoped cache, so every structurally-equal token green (e.g. each GreenToken(num, "5") in the parse) collapses to one canonical heap instance.
internTree<E, Tok, Syn>(Parser<E, GreenNode<Tok, Syn>> inner) → Parser<E, GreenNode<Tok, Syn>>
Intern inner's produced green through the parse-scoped cache. For tree-producing parsers: every structurally-equal subtree — same kind, same children in order, children themselves structurally equal — collapses to one canonical instance.
isIdentChar(int codeUnit) → bool
True if codeUnit is an ASCII identifier continuation character.
keywords<A>(Map<String, A> mappings) → Parser<ParseError, A>
Parses a keyword and maps it to a value using O(m) radix tree matching.
letter() → Parser<ParseError, String>
Parses a single letter (a-z, A-Z).
lexeme<A>(Parser<ParseError, A> parser) → Parser<ParseError, A>
Wraps parser to consume trailing whitespace.
listEquals<T>(List<T> a, List<T> b) → bool
Deep equality for lists.
listHash<T>(List<T> items) → int
Combined hash for a list of values.
mapEquals<K, V>(Map<K, V> a, Map<K, V> b) → bool
Deep equality for maps.
mapHash<K, V>(Map<K, V> m) → int
Combined hash for a map's entries.
noneOf(String chars) → Parser<ParseError, String>
Parses any character NOT in chars.
oneOf(String chars) → Parser<ParseError, String>
Parses any character from chars.
position<E>() → Parser<E, int>
Succeeds without consuming input, yielding the current byte offset.
pratt<A>(Parser<ParseError, A> atom, List<PrattOperator<A>> operators) → Parser<ParseError, A>
Top-Down Operator Precedence (Pratt) expression combinator.
rule<E, A>(Parser<E, A> thunk()) → Parser<E, A>
Creates a left-recursion-enabled memoized parser (Warth seed-growth).
run<E, A>(Parser<E, A> parser, String input) → Result<E, A>
Run a parser on input, returning a Result.
runRecursive<E, A>(Parser<E, A> parser, String input) → Result<E, A>
Run without the trampoline (direct recursion).
satisfy(bool pred(String), String expected) → Parser<ParseError, String>
Parses a character satisfying pred.
setEquals<T>(Set<T> a, Set<T> b) → bool
Deep equality for sets.
setHash<T>(Set<T> s) → int
Combined hash for a set's elements (order-insensitive).
spaces() → Parser<ParseError, List<String>>
Parses zero or more whitespace characters.
spaces1() → Parser<ParseError, List<String>>
Parses one or more whitespace characters.
string(String s) → Parser<ParseError, String>
Parses an exact string.
stringIn(List<String> strings) → Parser<ParseError, String>
Parses one of several strings using O(m) radix tree matching.
succeed<E, A>(A value) → Parser<E, A>
Always succeeds with value, consuming no input.
symbol(String s) → Parser<ParseError, String>
Parses s then consumes trailing whitespace.
syncUntil<Tok, Syn>(Parser<ParseError, GreenNode<Tok, Syn>> inner, Set<String> syncChars, Tok errorTokenKind) → Parser<ParseError, GreenNode<Tok, Syn>>
Panic-mode recovery: if inner fails, skip input up to (but not including) the next character in syncChars, wrap the skipped text in a GreenUnexpected, and surface inner's errors via Result.Partial. The sync character is left unconsumed so the caller can match it next.
treeOf<Tok, Syn>(Syn kind, List<Parser<ParseError, GreenNode<Tok, Syn>>> parts) → Parser<ParseError, GreenNode<Tok, Syn>>
Compose child green-producing parsers into a GreenTree of kind kind.
whitespace() → Parser<ParseError, String>
Parses a single whitespace character.