Supported API reference

Concern API
Input Source, ByteSource, Utf8Source, ByteFileSource, Utf8FileSource, EncodedFileSource, SourceMode, immutable Span
Runtime ParseSession; checked recognizeInSession(Source, int, ParseSession) delegation
Entry points matchPrefix(Source, int = 0, ?ParseLimits = null), parseAll(Source, int = 0, ?ParseLimits = null)
Public entry points Facade and frozen parse/parseAll/matchPrefix(Source\|string, int = 0, ?ParseLimits = null)
Per-call spacing Facade entry points accept a fourth spacing: Comprehend\|Parser\|null argument; local grammar policies take precedence
Limits/profile ParseLimits(maxDepth, maxWork), ParseLimitException, optional bounded ParseMetrics
Bounded regex Regex::literalWindow(string) for quoted literals; general Regex keeps full-subject semantics
Run scanners readWhile(predicate, min: 0, max: null), readUntil(literalOrPredicate, min: 0, max: null), readWhileSet(characters, min: 0, max: null), readWhileRange(first, last, min: 0, max: null), readRest(); skipWhile/skipUntil/skipRest return null; contracts and examples
Terminals Text(string), Char(string, bool = true), Any, Set(string, bool = true), Range(?string, ?string, bool = true), Regex(string), Start, End, Nothing
Numbers extension Automatically loaded Extensions\Numbers\Numbers: integer, binary, octal, hexadecimal, octet, float; parsers Numbers\Parser\IntegerNumber and FloatNumber; sign policies and syntax
Typed numbers integerValue, binaryValue, octalValue, hexadecimalValue, octetValue, floatValue; lazy native values with preserved source text; all numeric factories accept optional strict: true
Structures Sequence(Parser...), Choice(Parser...), All(Parser...), Except(Parser, Parser), Not(Parser), Repeat(Parser, int = 0, ?int = null)
Repetition Comprehend::of(Parser)->repeat(min, max); object factories Repeat::plus/star/optional/exact
Separated lists Core separatedBy(...) and Parser\Structure\SeparatedList project item values; behavior and values
Shared repetition names Static some/many/maybe(item), repeat(item, min, max); fluent some/many/maybe(), repeat(min, max)
Terminal chaining ->text/char/set/range/regex/literalWindow/any/nothing/start/end/integer/binary/octal/hexadecimal/octet/float(...)
Choice policy first/longest/shortest(Parser...), scoped Prefer
Scoped policy CaseSensitive(bool, Parser), Space(?Parser, Parser), spacing(?Parser), lexeme(), trivia()
Grammar Ruleset, Definition, Implementation, RuleReference, explicit Stub setter
Named operations define(string, Comprehend\|Parser\|Definition\|callable), ref(string, ...args), root(string\|Comprehend\|Parser)
Frozen graphs freeze() returning FrozenGrammar with syntax checks and analysisWarnings
Immutable facade Comprehend text/char/set/range/regex/ref, sequence/choice, then/or/repeat, naming and scoped policy
Expandable syntax Comprehend::syntax()->defineRule(name, factory); immutable scoped static/fluent factories, call(), names()
Extensions Bundled and Composer-advertised providers load on first use; Syntax::extend(SyntaxExtension) provides explicit local installation; loading, discovery and extension authoring
Expression tables Optional Extensions\Expressions\Expressions: operatorExpression(primary, Operator...), expressionChoice(alternatives...); precedence and lifecycle
ABNF authoring Bundled Extensions\Abnf\Compiler::compile(string, root, numericEncoding, choice) returning FrozenGrammar; ABNF extension
Specification grammars Discoverable subject factories such as uri, emailAddress, dateTime, uuid, semver, languageTag, json, yaml; explicit rfcNNNN(rule: 'ROOT'); direct classes in each extension's Grammar namespace; complete catalog
Naming name(string|int, ?string = null, bool $leaf = false)
Meaning Core mapValue(callable), named set/concat/push collection operations
Extraction expansion Automatically loaded Extensions\Extraction\Extraction: map, mapText, collect, valueChoice, manyValues, someValues, repeatValues, optionalValue; classes and types
Prepending Facade prepend(Comprehend\|Parser\|string ...items) returns an immutable sequence of the supplied items followed by the current expression
Value selection Core fluent thenIgnore(next), ignoreThen(next), between(open, close); object Parser\Structure\ValueSequence(int, Parser...); delimiters and lifecycle
Lifecycle guard(callable), validateSemantic(callable), onCommit(callable), assignments
Results ParseResult, Diagnostic, ValidationResult, immutable ConcreteNode and AstNode
Diagnostic serialization Diagnostic::toArray(includeLocation: false, includeExcerpt: false), toJson(...) and JsonSerializable; schema and source costs
Error recovery Optional Extensions\Recovery\Recovery: RecoverUntil, RecoverDelimited, RecoverItem, RecoverWith under Extensions\Recovery\Parser; rule/fluent factories, shared recovery records and diagnostics; recovery contracts
Simple result access Readonly ok aliases success; output() aliases lazy typed value(), returning null on syntax failure without committing effects
AST navigation child(), firstChild(), lastChild(), firstNamed(), allNamed(), firstInGroup(), allInGroup(), descendants()
Tree metadata tag(), fixed or callable named(), hasTag(), firstTagged(), allTagged(), AST preamble/postamble spans and text helpers
Serialization CST/AST toArray(), toJson(), JsonSerializable; toXml() returns DOMDocument and requires optional ext-dom

Use Comprehend for concise authoring. It returns immutable facade values; Ruleset constructor entries, definitions and roots accept those values directly and detach their parser graphs at registration. parser() exports a detached Parser only for low-level integration. Factories can return facade values; Definition accepts facades and build() returns a facade. Wrap a custom Parser with Comprehend::of() to use the public authoring API. The former free functions in Vanderlee\Comprehend\Library have been removed.

See Grammar authoring for frozen factory lifetimes, immutable composition, safety limits and checked arithmetic/RFC examples.

See ABNF for the supported text subset and breaking release for caller changes, supported runtimes and publication gates. IntegerNumber recognizes bounded integers; its bounds must be integers/null. The default alphabet supports bases 2–36. Custom UTF-8 alphabets and opt-in leading zeros are supported by IntegerNumber and the facade's integer(); binary(), octal(), hexadecimal() and octet() provide common factories. Overflow is rejected or trimmed to an in-range prefix, never saturated. See Grammar authoring. Use explicit chr() for octet literals, not integer-to-character coercion.

See custom extensions, builders, results and breaking changes.