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.