Writing syntax extensions¶
Syntax::extend(SyntaxExtension $extension) installs named factories into a new
immutable vocabulary. Explicit registrations stay local, and existing vocabularies
and expressions remain unchanged. Extensions use defineRule() and defineFluent()
internally, preserving their naming, replacement and typed factory contracts.
For bundled features, see Overview and loading. For package manifests and capability contracts, see Discovery and capability providers.
Writing an extension¶
Implement Vanderlee\Comprehend\Syntax\SyntaxExtension. Both rules() and
fluents() return iterable<string, callable> using generators or arrays.
Return an empty iterable for either kind of registration you do not need:
Extensions previously implementing factories() must rename it to rules()
and add fluents(), returning [] when no fluent operations are supplied.
use Vanderlee\Comprehend\Comprehend as C;
use Vanderlee\Comprehend\Syntax\SyntaxExtension;
final class Punctuation implements SyntaxExtension
{
public function rules(): iterable
{
yield 'semicolon' => static fn(): C => C::text(';');
yield 'comma' => static fn(): C => C::text(',');
}
public function fluents(): iterable
{
return [];
}
}
$syntax = C::syntax()->extend(new Punctuation());
Installation consumes rules() first, then fluents(), immediately and in order.
Factories run only when invoked during grammar authoring, not during installation or input
recognition. Factories may return Comprehend, Parser or Definition, and named and
default parameters keep their typed signatures. Extension factories should build
graphs without application effects. Explicit installation bypasses discovery;
both paths use the same typed parser graph and recognition runtime.
Names are case-insensitive. Later registrations replace earlier custom factories
under the same name, including duplicate keys yielded by a generator. Built-in
and declared method names remain reserved; extend is now a reserved Syntax name.
Two empty iterables return the original vocabulary. If iteration or registration
throws, the original vocabulary is unchanged and no partially extended vocabulary
is returned. External side effects performed by extension code cannot be undone.
rules() supplies factories installed through defineRule(). fluents() supplies
transformations installed through defineFluent(). Each fluent callback receives
the current Comprehend expression before user arguments and runs only during
grammar authoring. Fluent-only extensions return an empty iterable from rules().
use Vanderlee\Comprehend\Extensions\Extraction\Extraction;
use Vanderlee\Comprehend\Syntax\SyntaxExtension;
final class Delimiters implements SyntaxExtension
{
public function rules(): iterable
{
return [];
}
public function fluents(): iterable
{
yield 'parenthesized' => static fn(C $item): C => $item->between('(', ')');
}
}
$syntax = Extraction::syntax()->extend(new Delimiters());
$result = $syntax->text('hello')->parenthesized()->parse('(hello)');
Static and fluent names are independent: a static call starts an expression,
while a fluent call transforms the current expression when both share a name.
Duplicate fluent names replace earlier fluent registrations case-insensitively.
Reserved names and typed factory contracts follow defineFluent(). A failure in
either iterable leaves the original vocabulary unchanged. defineFluent() also
remains available for registering individual transformations.
Run the syntax extension example for checked examples.
Composer discovery¶
See Composer discovery.
Capability providers¶
See Capability providers.
Bundled ASCII vocabulary¶
See ASCII identifiers and keywords.
Expression tables¶
See Expressions.