Named, frozen and fluent grammars

All authoring styles compose the same Parser objects and use the canonical Source/ParseSession/ParseResult runtime. No grammar text compiler or second recognition engine is introduced.

Facade sequence() arguments retain insertion order, including named variadic arguments. An unannotated sequence prefix is flattened with either calling style; named nodes and explicit spacing policies preserve their composition boundaries.

Explicit names and roots

use Vanderlee\Comprehend\Builder\Ruleset;
use Vanderlee\Comprehend\Parser\Structure\Sequence;
use Vanderlee\Comprehend\Parser\Terminal\Text;
use Vanderlee\Comprehend\Source\Utf8Source;

$rules = new Ruleset();
$rules->root('word');
$rules->define('word', new Sequence(new Text('a'), $rules->ref('suffix')));
$rules->define('suffix', new Text('b'));
$grammar = $rules->freeze();
$grammar->parseAll(new Utf8Source('ab'))->success; // true

define(string, Comprehend|Parser|Definition|callable) registers a facade, typed parser or factory. ref(string, ...$arguments) creates a deferred named reference; definitions can be written in any order. root(string|Comprehend|Parser) chooses the start rule by name or supplies its facade or parser directly. rule() returns a Comprehend facade around the deferred reference, while ref() returns the RuleReference parser itself.

use Vanderlee\Comprehend\Comprehend;

$digits = $rules->rule('digit')->some();
$rules->define('digit', Comprehend::range('0', '9'));
$digits->freeze()->parseAll(new Utf8Source('123'))->success; // true

Use ref() in low-level Parser-only object constructors. Facade references are recognized through parse(), parseAll() or matchPrefix() (which freeze automatically), or through an explicitly retained frozen grammar; they retain forward/recursive lookup, factory arguments and named rule groups. References never guess a literal or class name. Missing names and invalid factory returns are grammar errors. Named references preserve their Ruleset group in AST/diagnostic output. Ruleset roots inherit the selected root's typed value unless the Ruleset has its own mapping.

Freezing shares resolved productions while preserving each reference's own guards, names, tags, value mappings, semantic validators and commit effects. Specification roots and nested references retain the specification's group name.

Ruleset constructor entries, define() and root() accept Comprehend values directly. Registration exports a detached parser graph internally, preserving facade isolation without explicit parser() calls. Deferred references still consult their owning builder until freezing. Factories can accept and return Comprehend values directly; Parser returns remain supported for extensions. Factory arguments are passed unchanged. Definition accepts facade generators, and build(...arguments) returns an independent immutable facade that can be composed directly. Comprehend::of(Definition) builds its unparameterized facade. Factories remain deferred until recognition or freezing.

Resolved graph snapshots

freeze() returns a FrozenGrammar with parse(), matchPrefix(), parseAll() and read-only analysisWarnings. It resolves the root's reference graph, builds factory implementations, snapshots Parser/Definition state and validates known graph safety. Sharing and consuming recursive cycles are preserved. The result does not expose its internal mutable parser objects.

Changing a builder, shared Sequence/Choice, Stub target or Definition after freezing does not change that snapshot. Freeze again to capture new definitions or factory output. Each freeze bypasses the builder's lazy implementation cache; implementations in the frozen graph live for that snapshot's lifetime. Matching it creates a new ParseSession and fresh semantic/effect caches each time.

When resolved parser snapshots are copied or composed again, references retain their resolved productions. Snapshots of different revisions of the same builder remain independent, even when their rule names and factory arguments match.

Parameterized references use rule-scope identity, name and argument identity. Equal scalar/array arguments reuse one implementation within a freeze; objects and resources use identity, without serializing user objects. Recursive factories must produce a finite graph of distinct parameterizations. Factories may run during freezing and must not perform application effects. Factory output and RFC imports are detached just like ordinary object grammar children:

use Vanderlee\Comprehend\Extensions\Network\Grammar\Rfc3986;

$rfc = new Rfc3986();
$rules = new Ruleset();
$rules->define('scheme', $rfc->ref('scheme'))->root('scheme');
$scheme = $rules->freeze();
$rfc->define('scheme', new Text('changed'));
$scheme->parseAll(new Utf8Source('https'))->success; // still true

Snapshots clone Parser/Definition objects and register each clone before copying its owned grammar dependencies. Constructors do not run; custom __clone() hooks do run and must not perform application effects. Metadata arrays use PHP's copy-on-write behavior. Closures and non-parser service/value objects remain caller-owned dependencies; freeze does not deep-freeze external objects or variables captured by reference.

Custom composite recognizers must expose dependencies through children() and copy them in copyDependencies(GraphSnapshot), calling the parent hook first. Owned dependency fields must permit replacement on the clone; scalar readonly fields can stay readonly. See the snapshot copying contract. Dynamic child construction remains opaque to static analysis. Rulesets, deferred references and factory implementations retain specialized snapshot methods for resolution, pruning and cache refresh.

Immutable fluent composition

The Comprehend facade returns a new value for every composition or metadata operation. It uses Sequence, Choice, Repeat and the existing directives:

use Vanderlee\Comprehend\Comprehend;

$base = Comprehend::text('a');
$longer = $base->then(Comprehend::text('b'));
$alternative = $base->or(Comprehend::text('c'));
$base->freeze()->parseAll(new Utf8Source('a'))->success; // true
$longer->freeze()->parseAll(new Utf8Source('ab'))->success; // true
$alternative->freeze()->parseAll(new Utf8Source('c'))->success; // true

The bundled RFC grammars import the facade as C with use Vanderlee\Comprehend\Comprehend as C; to keep composition concise.

Operation Underlying behavior
text(), char(), set(), range(), regex(), of(Comprehend\|Parser\|Definition) Immutable public syntax; wrap custom parsers or build definitions
any(), nothing(), start(), end() Remaining terminals
integer(minimum, maximum, base, allowLeadingZeros, digits) Bounded numeric text; defaults are minimum 0, no maximum, base 10, no leading zeros and the standard digit alphabet
binary(), octal(), hexadecimal(), octet() Base-2/8/16 factories and decimal range 0–255; optional leading zeros
literalWindow(literal) Regex matching with a proven finite literal read window
ref(Ruleset, name, ...args) Deferred supported named reference
sequence(...items), then(...items) Sequence composition
prepend(...items) Sequence the supplied items before the current expression, preserving their order; no arguments returns the same facade
->text(), ->char(), ->set(), ->range(), ->regex(), ->literalWindow() Append a terminal with the same arguments/defaults as its static factory
->any(), ->nothing(), ->start(), ->end() Append unit, empty or boundary terminals
->integer(), ->binary(), ->octal(), ->hexadecimal(), ->octet() Append numeric terminals with the same options as their factories
choice(...items), or(...items) Choice composition inheriting the scoped ranking policy (first by default)
first(...items) Explicit local first-success choice
longest(...items), shortest(...items) Explicit local choice ranking
all(...items), except(match, not), not(item) Intersection (shortest accepted span), exclusion, negative lookahead
repeat(min, max) Repeat with existing bounds/progress semantics
some() / plus(), many() / star() / kleene(), maybe() / optional() One or more, zero or more, zero or one
some(item), many(item), maybe(item), repeat(item, min, max) Static repetition factories accepting a facade, Parser or literal string
named(string\|int\|callable), tag(...tags), mapValue() Fixed or pure dynamic names, tags and semantic mappings on a detached graph
Extraction's mapText(callable) Text mapping through the automatically loaded Extraction expansion
guard(), validateSemantic(), onCommit(), assignTo() Pure recognition predicate, selected semantic validation, explicit committed effects and assignments
setResult(), concatResult(), pushResult() Cached named result collections, independent of source text
label(text) Replace entry-position expectations, preserving deeper failures; see labels
diagnosticRule(name) A readable rule-path name, separate from expectation labels and tree names
caseSensitive(bool), prefer(preference) Scoped case and choice policy; preference uses Runtime\ChoicePolicy::FIRST, LONGEST, or SHORTEST
spacing(), lexeme(), trivia() Existing scoped directives
parser() Detached object graph for low-level integration
freeze() Resolved, analyzed reusable snapshot
parse(input), parseAll(input), matchPrefix(input) Freeze automatically and recognize a Source or validated UTF-8 string; parse/parseAll require complete input

Reference-bearing facade expressions deliberately resolve names at freeze, after definitions are complete. Each fluent composition protects reused parser containers; forward references still consult their builder until freezing. Exporting via parser() does not expose the facade's internal containers. FrozenGrammar::from($facade, $flags) copies directly into its destination snapshot without first creating a standalone export. It still creates a fresh snapshot; unlike $facade->freeze($flags), it does not consult facade preparation caches or dispatch a custom root freeze() override. Factory-returned facades retain their separate export boundary so named productions keep independent ownership and metadata. Mutable object builders remain available: migrate shared add()/array edits to facade then()/or(), or freeze a graph before changing its builders. Composition flattens anonymous sequence prefixes while retaining named and decorated groups.

then() and or() accept any number of facade values, Parser objects or strings. With no arguments they return the unchanged facade; supplied object parsers are detached. String arguments become Text literals in sequence, choice, chaining, intersection, exclusion and negative lookahead. Empty strings retain Text's rejection; use nothing() for a zero-width match. Object constructors remain Parser-only, and rule lookup still requires explicit names. One variadic call groups its supplied children together. Successive sequence calls flatten an anonymous sequence prefix, reducing nesting in chains such as text('a')->text('b')->text('c'). Names, tags, semantic callbacks, result operations, assignments, diagnostic labels, explicit sequence spacing and subclass boundaries prevent flattening. Directive wrappers remain intact. Non-prefix nested sequences are retained because nullable items can otherwise change how often spacing is consumed. Empty prefixes and recursive boundaries are retained as well. Anonymous CST grouping and recognition depth/work counts can therefore differ; source spans and named semantic boundaries remain.

Anonymous choices that inherit their policy also flatten during choice(), or() and explicit ranked-factory composition. Chained text('a')->or('b')->or('c') therefore has one choice container. Explicit first/longest/shortest policies, metadata, subclasses and directive wrappers retain their boundaries. Alternative order and ranking ties remain unchanged. As with sequences, anonymous CST nesting and recognition work/depth counts may change; reused expressions remain immutable.

$digits = Comprehend::range('0', '9')->some()->named('digits');
$bracketed = Comprehend::sequence('[', $digits, ']');
$grammar = $bracketed->or('none', 'empty');
$grammar->parse('[123]')->success; // true

prepend(...items) is the immutable counterpart of then(...items): it constructs sequence(...items, currentExpression) and detaches supplied Parser objects. Names, policies and callbacks on the current expression stay attached to that subtree. The returned expression retains its custom syntax scope.

use Vanderlee\Comprehend\Extensions\Extraction\Extraction;

$word = Extraction::syntax()->text('hello')->mapText('strtoupper');
$word->parse('hello')->output(); // 'HELLO'; rawText() remains 'hello'
$wrapped = $word->prepend('[')->text(']');
$wrapped->parse('[hello]')->rawText(); // '[hello]'; $word still matches 'hello'

mapText() accepts a callable taking the original matched string and returning any value. It shares mapValue()'s lazy cache and effect boundaries: failed parses do not call it, and reading output does not commit effects. Both configure the same value mapper, so a later mapping replaces the earlier one rather than forming a transformation pipeline. A mapping on a child remains local to that child; map the completed composition to transform its whole value.

Repetition shortcuts retain the same nullable-child rejection as repeat(), including optional repetition. Lifecycle operations retain their distinct timing: guard() receives ConcreteNode and may run speculatively; validateSemantic() and onCommit() receive ParseResult. Reading values does not commit effects. See Lifecycle for validation and commit behavior. Nested case or preference directives use the innermost applicable override.

Choice ranking values live in Vanderlee\Comprehend\Runtime\ChoicePolicy: FIRST, LONGEST and SHORTEST are backed enum cases. Pass a case to prefer(), Choice::setPreference(), Prefer, ParseSession and the ABNF compiler's choice option. Strings are rejected with TypeError. At a configuration boundary, use ChoicePolicy::from($value) to validate a string, or tryFrom() to handle invalid input explicitly. Read ->value for the strings first, longest and shortest. setPreference(null) restores inherited policy. The Prefer directive applies the policy to a subtree.

Terminal chaining and static repetition

$token = Comprehend::text('a')->set('01')->text('!');
$token->parse('a1!')->success; // true
$digits = Comprehend::some(Comprehend::range('0', '9'));
$suffix = Comprehend::maybe('!');

Terminal chains sequence a new terminal after the existing expression, preserving named groups, scoped policies and immutable reuse. To name, tag or map only the appended terminal, compose it separately and pass it to then(). Shared names now use __call()/__callStatic() only at the facade authoring boundary. Static calls construct syntax; fluent factory calls append it. Fluent or() extends alternatives instead of sequencing, while static or() is a choice factory. Static repeat(item, min, max) and fluent repeat(min, max) retain distinct signatures. Static some/many/maybe require an item; their fluent forms take no arguments and repeat the current expression. Typed catalog callbacks validate arguments and preserve named arguments. Terminal chains use these shared short names; redundant thenText()-style helpers and static repetition *Of() helpers have been removed. All repetition bounds, nullable-child checks and deferred references are unchanged.

Scoped expandable syntax

Optional factory bundles can implement Syntax\SyntaxExtension and be installed with $syntax->extend($extension). See Syntax extensions for generator-based authoring and the optional ASCII identifier/keyword vocabulary.

$syntax = Comprehend::syntax()->defineRule('word',
    static fn(): Comprehend => Comprehend::range('a', 'z')->some()->lexeme()->named('word'));
$grammar = $syntax->text('let ')->word()->text(';');
$grammar->parse('let name;')->success; // true

defineRule(name, callable) returns a new immutable Syntax vocabulary. Factories may return Comprehend, custom Parser or Definition; any other result throws. Factories run during authoring, and should only construct syntax. Named/default parameters and variadic arguments follow the factory's typed signature. There is no implicit conversion of invalid scalar arguments or fallback to rule names. Unknown syntax, surplus nonvariadic arguments and reserved names raise explicit errors.

For transformations of the current expression, defineFluent(name, callable) registers a callback receiving the current Comprehend as its first parameter, followed by user arguments. A fluent-only name cannot start syntax. A name may have separate static and fluent definitions in the same vocabulary. Without a custom fluent, calling a registered static factory fluently appends it.

$syntax = $syntax->defineFluent('surround',
    static fn(Comprehend $item, string $left, string $right): Comprehend =>
        Comprehend::sequence($left, $item, $right));
$grammar = $syntax->word()->surround('(', ')');

Custom syntax works for static and fluent factories within that vocabulary. Facade metadata/composition operations retain their scope; define a replacement in a new vocabulary without changing existing expressions. No global registration affects Comprehend::word() or other vocabularies. Build through $syntax to select the scope explicitly, or use $syntax->call(name, ...arguments) when the method name is data. names() lists built-in and registered factory names. Freezing performs no syntax dispatch. Its optimizer replaces eligible recognition operations with specialized parsers, retaining the Repeat boundary and each original per-unit CST node:

Repeated child Scanner Conditions
Inclusive Set ReadWhileSet Plain built-in child
Inclusive Range ReadWhileRange ASCII or open bounds, ordered before and after case folding
Inclusive Char ReadWhileSet ASCII character
Excluded Char ReadUntil ASCII character; stops before the excluded unit
Text ReadWhileSet One ASCII character
Any ReadWhileRange over all units Ignores case policy, as the original child does

All rewrites preserve repetition bounds. Eligible scans build the original per-unit concrete nodes directly, without temporary child execution records or a discarded scanner tree. Literal and range scanners inherit the child's local or enclosing case policy. Names, tags, groups, guards, lazy values, validators and commit effects on the repeat remain intact. Decorated children, excluded sets/ranges, non-ASCII literal/range bounds, multi-unit text and custom subclasses retain their original recognition. Maximum zero never scans. Active intervening spacing or work/depth limits use ordinary repetition so trivia, diagnostics and budget failures retain their contracts. Authoring copies do not run the optimizer; mutable builders remain unchanged.

Control optimization when preparing a grammar with Builder\FreezeFlags:

The bundled Extensions\Optimizer\GraphOptimizer is discovered through extensions/Optimizer/Optimizer.extension.json. Core combinators retain ordinary recognition; the extension supplies internal parser implementations for optimized execution. Their concrete syntax trees retain the original parser kinds.

use Vanderlee\Comprehend\Builder\FreezeFlags;
use Vanderlee\Comprehend\Builder\FrozenGrammar;

$optimized = $grammar->freeze(); // FreezeFlags::DEFAULT enables OPTIMIZE.
$plain = $grammar->freeze(flags: FreezeFlags::NONE);
$explicit = FrozenGrammar::from($grammar, FreezeFlags::OPTIMIZE);
$result = $plain->parse('input');

Both Parser and facade freeze(int $flags = FreezeFlags::DEFAULT) accept flags. NONE disables only optimizer rewrites: graph isolation, reference resolution and structural safety checks always run. Unknown flag bits raise InvalidArgumentException before preparation. Flags support bitwise | composition; OPTIMIZE is currently the only option. Reusable facade snapshots are cached separately for each flag set. Normal facade parsing continues to use DEFAULT; parse through an explicitly frozen grammar to disable optimization.

NONE does not resolve an optimizer provider. With OPTIMIZE, preparation requires exactly one discovered optimizer; missing or competing providers raise an error. Optimizer providers implement Builder\GraphOptimization: replace() creates snapshot parsers, and prepare() initializes the isolated, validated graph. Manifests advertise this interface in the class-to-interfaces providers map; preparation resolves it through ExtensionLoader::requireOne(GraphOptimization::class). See Extension capabilities for generic discovery.

After references are resolved and graph safety checks pass, adjacent literal runs within sequences can also compile to internal Text terminals. Compilation recursively follows sequences, exact-count repetitions and resolved named references whose leaves are case-sensitive ASCII Text terminals. For example, a sequence containing Repeat::exact(new Text('ab'), 256) followed by Text('!') recognizes its complete literal in one terminal call. Source-free templates reconstruct every original child node, name, tag and span; the CST is not collapsed to one text node.

Optimizer preparation reuses successful composite classifications within that one resolved graph. Cached structural heights preserve the original depth bounds at each caller. Shared literal operands also reuse immutable, operand-relative syntax templates; each occurrence still creates fresh source-bound CST nodes. The temporary preparation context is released after freezing. It does not cache mutable definitions, recognition sessions, results, semantic values or effects across freezes.

Each literal run is bounded to 64 KiB, 4,096 expanded child nodes and 32 levels of descent. Child guards, dynamic names, mappings, validators, effects, labels, custom parser classes and local spacing separate runs and retain ordinary recognition. For example, Text('a'), Text('b'), Regex(...), Text('c'), Text('d') can batch ab and cd while recognizing the regex normally. Root metadata still executes normally. On mismatch, a flat run of Text operands skips the already proven successful operands and recognizes the original failing Text for its diagnostic and partial-progress behavior. Skipped parser entries and literal units still charge their original work. Nested runs retain the original operand fallback; preceding executable operands are not repeated. Active spacing, case-insensitive scopes and work/depth limits use the original sequence. Non-ASCII text, variable repetitions and general regexes remain ordinary operands between runs. Freezing classifies only proven callback-free children and retains their source-free templates; recognition always creates fresh nodes bound to the current source.

Prepared sequences also batch adjacent plain ReadWhileSet and ReadWhileRange operands through their shared scan primitive. This reduces checked child dispatch; it does not combine patterns, change greedy bounds or collapse scanner nodes. Each original child, including zero-width matches, keeps its own byte span and default value. Metadata-bearing operands separate runs. Active intervening spacing, case-insensitive enclosing scopes and finite work/depth limits retain ordinary sequence recognition; lexemes can batch with inherited spacing suppressed. A failed run retries only its own callback-free scanners for the original progress and diagnostics, without repeating earlier executable operands. Prepared plans retain grammar references only and are cleared when copying back to authoring graphs.

Historical measurements of literal preparation and warm recognition with CST are recorded in Performance measurements.

Prepared snapshots also specialize plain ReadWhileSet/ReadWhileRange trivia and eligible repeated-character trivia. The wrapper scans its operand directly and constructs the original operand nodes without an intermediate child match. Automatic spacing retains zero-width trivia nodes and repeated-character detail; explicit trivia keeps its own metadata, lazy mappings and commit lifecycle. Operand metadata, custom classes and finite work/depth limits retain ordinary delegation. Authoring copies clear these prepared plans.

Prepared sequence, repeat and separated-list implementations can also retain nullable automatic trivia directly as immutable syntax, avoiding the wrapper's temporary execution record. Both original node layers and each source-bound span remain present, including empty trivia. Required-minimum trivia and custom combinators keep execution records; the existing skipSpacing() session method also continues to return independent matches. This specialization shares the prepared operand scan and restores the lexeme scope on exceptions. It does not evaluate semantic values or effects, and finite work/depth limits retain checked delegation and the original budget positions and paths. The syntax-spacing session path shares its cached wrapper with ordinary spacing and avoids forwarding through the match-returning helper. Eligible prepared wrappers retain source-free kind names once, avoiding repeated lookups for each new node. Custom trivia hooks still run under the restored lexeme scope contract.

Plain ASCII Text separators in built-in separated lists can construct their CST nodes directly too. The existing list loop still owns bounds, leading/trailing separator policies, spacing and rollback. Decorated/custom separators, incompatible case policies and finite limits use ordinary recognition. Preceding trivia with deferred behavior also retains the ordinary separator record so validation, collections and effects preserve their original ownership and order. Literal mismatches retry only the separator for its original diagnostics; preceding trivia is never replayed. Neither optimization removes syntax nodes or evaluates semantic callbacks during recognition. FreezeFlags::NONE disables both.

After references are resolved and graph safety checks pass, optimization also prepares bounded lexical tables for Repeat operands, Choice alternatives and Not probes. These cover named character rules, character-class choices, fixed escapes such as URI %HH, finite group sequences and literal delimiter checks. First observations use the original recognition runtime; later observations reproduce fresh CST nodes and merge the same diagnostics under the current caller's rule path. Original branch ordering and first/longest/shortest policies remain intact.

Tables retain at most 128 entries per operand, with at most 32 bytes of proven ASCII lookahead. They retain relative syntax recipes, not Sources, ParseResults or semantic state. Keys distinguish source mode, case policy and choice policy. Non-ASCII lookahead, executable metadata (including dynamic names), custom classes, recursive/unbounded patterns, local spacing inside a candidate and active spacing/budgets use ordinary recognition. A narrow regex subset is eligible: a single character class, optionally with a finite quantifier. There is no general regex conversion or parse-position memoization. FreezeFlags::NONE disables these tables too.

Choices with at least two distinguishable first bytes among eligible long ASCII Text alternatives can also prepare first-byte rejection recipes. This deliberately small first set covers exact built-in Text operands outside lexical-table coverage; it does not infer through nullable, guarded or unknown graphs. The first alternative keeps its existing path, avoiding extra lookahead for early ordered success. Later impossible alternatives record their original expectation and rule path in order, with zero failure progress and the original two work units. Possible matches still use the original recognizer. Ranked policies, ties and the alternative loop are unchanged. Active spacing, case-insensitive scopes, finite limits and custom combinator subclasses retain their existing paths. Recipes retain no source, semantic state or results, and authoring copies clear them. Byte tries and internal prefix factoring remain research tools; see the choice-plan comparison.

See Library optimizer measurements for performance and retained-memory tradeoffs.

Built-in static calls such as Comprehend::text() resolve directly from a fixed catalog. That catalog coordinates typed static/fluent callbacks, aliases, name discovery and reserved names. Scoped Syntax vocabularies resolve callbacks directly through their immutable catalog, without registries or resolution caches. Factories run for every authoring call and parser expressions are never cached. Extending a vocabulary creates a new catalog, leaving existing expressions unchanged. Parser construction, repetition, composition, directives and fluent metadata are implemented by catalog callbacks, dispatched directly through magic calls; parsing, freezing, graph export and reference-based assignTo() remain declared on the facade.

Built-in @method annotations provide completion and return types. Repetition annotations describe overloaded dispatch broadly; runtime signatures remain strict. Custom names require consumer annotations or the explicit call() API for tooling. Native reflection sees dispatch hooks and declared lifecycle operations, not declared public methods for every syntax name. Reference parameters in custom factories are unsupported by magic forwarding; use explicit facade lifecycle APIs such as assignTo() for referenced assignments.

Direct parsing and numeric factories

parse() is a complete-input alias for parseAll(). A facade whose entire graph declares the ReusableSnapshot capability prepares its snapshot once per flag set and reuses it for later calls, including explicit freeze() calls. This cache belongs to that immutable expression; composition and metadata changes create a new expression. Recognition results, semantic caches and effects remain separate for every parse.

Deferred rule references, Definition implementations and custom parsers without that capability still freeze freshly on each call, so builder edits and factory state changes remain visible. Custom subclasses do not inherit built-in cache eligibility merely by inheriting the interface; they must explicitly declare their own guarantee. See preparation reuse. Retain freeze() once when those graphs should use stable definitions. Per-call spacing composition creates a separate expression rather than a global cache. Strings always mean validated UTF-8, never automatic encoding detection; pass ByteSource for arbitrary bytes. Offsets and limits keep their canonical contracts.

Facade parse(), parseAll() and matchPrefix() also accept a fourth optional spacing: Comprehend|Parser|null argument. A non-null value supplies an outer spacing policy for that call, without modifying the grammar. Local spacing() and lexeme() directives take precedence. Null or omission leaves the grammar's spacing unchanged. This consumes intervening trivia only, not leading/trailing material. For repeated parsing, configure spacing() before freeze(); frozen entry points retain their existing signatures.

// The bundled Numbers extension loads automatically; no registration is needed.
$hex = Comprehend::hexadecimal(0, 255, allowLeadingZeros: true)->caseSensitive(false);
$hex->parse('00FF')->success; // true
$hex->parse('100')->success;  // false: outside the range
$hex->matchPrefix('100')->rawText(); // '10': longest in-range prefix
Comprehend::integer(2, 2, base: 2, digits: 'αβ')->parse('βα')->success; // true

Numeric factories preserve raw text as their default value; use mapValue() for typed application values. The digit alphabet is valid UTF-8 with unique code-point symbols in numeric order, beginning with zero. Minus is reserved for the sign. The base selects the initial symbols and must be at least two and no larger than the alphabet. Case-insensitive matching rejects alphabets with colliding folded symbols. Leading zeros, including signed zero, are opt-in. Out-of-range and overflowing candidates are trimmed to whole-digit prefixes; full-input parsing rejects an unconsumed suffix. PHP_INT_MIN and PHP_INT_MAX are matched exactly. Base factories recognize digits without prefixes such as 0x or 0b.

Replacing the Library functions

The free functions in Vanderlee\Comprehend\Library have been removed. Import Vanderlee\Comprehend\Comprehend and compose facade values instead:

Former call Comprehend replacement
text($text), char($char), set($set), range($first, $last), regex($pattern) Corresponding Comprehend::text/char/set/range/regex(...) factory
s(...$items) Comprehend::sequence(...$items)
c(...$items) Comprehend::choice(...$items)
star($parser) Comprehend::of($parser)->repeat()
plus($parser) Comprehend::of($parser)->repeat(1)
opt($parser) Comprehend::of($parser)->repeat(0, 1)
repeat($min, $max, $parser) Comprehend::of($parser)->repeat($min, $max)

Call repeat() directly on an existing Comprehend value. char() and set() accept an optional include flag; range() accepts an optional in flag. These retain the underlying terminal's byte/Unicode and exclusion semantics. Supply facade values directly to Ruleset definitions or roots. Export through parser() only for low-level object constructors or integration that require Parser; use freeze() to resolve and recognize a complete grammar:

$rules = new Ruleset();
$rules->define('digits', Comprehend::range('0', '9')->repeat(1));
$grammar = Comprehend::sequence(Comprehend::text('['), Comprehend::ref($rules, 'digits'), Comprehend::text(']'));
$grammar->freeze()->parseAll(new Utf8Source('[123]'))->success; // true

Static and runtime safety

Freeze rejects known left-recursive cycles, including indirect cycles and cycles after known nullable prefixes. Errors include the offending rule/parser path. Consuming recursion is allowed. Known zero-width children of Repeat are rejected even for optional/bounded repetition, matching the existing runtime progress contract; maximum zero is allowed because no child executes. Undefined Stubs also fail at freeze.

Nullability is a conservative structural property. Zero-width terminals and negative lookahead are nullable; guards and input-dependent conditions are not executed by analysis. Intersections may consume their shortest child, so a zero-width required branch makes repetition unsafe. Valid grammars depending on such conditions may need restructuring rather than disabling progress checks.

Opaque custom parsers appear in analysisWarnings. Analysis does not infer their nullable or leading behavior, nor prove cycles through unknown prefixes safe. Custom parsers can opt into these checks through the optional structural analysis contract, without changing the analyzer. Built-ins implement that same contract; subclasses that change recognition must also maintain their inherited analysis declarations. Runtime checks still reject a parser re-entering at the same byte position and a repeated successful child consuming zero bytes. Session state restores on exceptions. This is not left-recursion support, memoization, or a general depth or work limit by itself. ParseLimits adds optional per-session depth and work budgets; it does not add memoization or wall-clock deadlines.

Nullability preparation tracks which estimates each calculation reads and revisits affected parsers when those estimates change. This avoids repeated whole-graph passes on deep nullable chains while preserving stable fixed-point rounds and custom analysis contracts. Dependency tables add temporary memory during preparation. Analysis stores first-discovery parent links and captured labels, materializing full paths only for warnings and errors. Leading-cycle checks share one active ancestry map and restore it on exceptions. See the nullability comparison and compact ancestry measurements.

Checked authoring examples

Run php docs/examples/authoring.php. The complete example implements integer arithmetic with multiplication precedence, addition, parentheses and whitespace in object, Ruleset and facade styles. It verifies accepted/rejected inputs, typed values, exact named AST shape, byte spans and raw text. It also compares an RFC-based scheme://host grammar in all three styles; paths are deliberately outside that example's grammar. CI runs both this script and the canonical execution examples.