Named grammar builders¶
Ruleset provides explicit define(string, Comprehend|Parser|Definition|callable),
ref(string, ...$arguments), root(string|Comprehend|Parser), defined(string) and
undefine(string) operations. rule(string, ...$arguments) returns an immutable
Comprehend facade for fluent authoring; ref() returns a RuleReference parser for
low-level object constructors and direct recognition.
Rule lookup is deferred so forward/recursive definitions can be constructed in
any order. Undefined names raise LogicException on recognition; there is no
literal fallback or magic/static registry. Select the document parser explicitly
through root() and freeze to resolve/check its reachable graph.
use Vanderlee\Comprehend\Builder\Ruleset;
use Vanderlee\Comprehend\Comprehend as C;
$grammar = new Ruleset([], 'example');
$grammar->define('twice', fn (C $item): C => $item->repeat(2, 2));
$grammar->root($grammar->rule('twice', C::text('x')));
$result = $grammar->freeze()->parse('xx');
Facade values supplied through constructor entries, define() or root() are
converted to detached Parser graphs at registration. Reusing a facade in several
Rulesets does not share mutable parser state with those builders.
Factories return Comprehend facade values; low-level Parser returns remain
supported for extensions. Invalid returns raise grammar errors. Factory arguments
are passed unchanged, so facade parameters can be typed as Comprehend.
Concrete Parser and facade rules take no factory arguments.
Definition accepts a facade, custom Parser or factory. build(...$arguments)
returns an immutable facade snapshot without evaluating factories; it supports
composition and parsing directly. Later Definition edits do not change an existing
build. Definition validators and processors retain the selected semantic lifecycle.
Comprehend::of(Definition) builds an unparameterized facade. implementation()
is an internal runtime boundary for low-level integration, not public authoring.
Stub::setParser(Parser) supplies explicit recursion for object grammars.
Each Ruleset owns its rules and cached unparameterized implementations. Redefinition clears that instance's cache; existing results keep snapshots. Parameterized factories are not cached across ordinary lookups. Frozen graphs materialize references/factories per snapshot and remain independent of later builder changes. See Grammar authoring for cache lifetime, the immutable facade and graph safety, or ABNF for text authoring.