Expression builder extension¶
Extensions\Expressions\Expressions provides an automatically loaded precedence-table builder. It composes
the existing parser graph and recognition runtime, with lazy cached reductions and
explicit commit effects. It does not enable left recursion or introduce a separate
Pratt/LR recognition engine.
Operator and OperatorKind live in Extensions\Expression; internal parser
implementations live in Extensions\Expression\Parser.
use Vanderlee\Comprehend\Extensions\Extraction\Extraction;
use Vanderlee\Comprehend\Comprehend as C;
use Vanderlee\Comprehend\Extensions\Expression\Operator as O;
$syntax = C::syntax();
$number = Extraction::syntax()->regex('/[0-9]+/A')->mapText('intval');
$expression = $syntax->operatorExpression(
$number,
O::infixLeft('+', 10, static fn(int $a, int $b): int => $a + $b),
O::infixLeft('*', 20, static fn(int $a, int $b): int => $a * $b),
O::prefix('-', 30, static fn(int $a): int => -$a),
O::infixRight('^', 40, static fn(int $a, int $b): int => $a ** $b),
)->spacing(Extraction::syntax()->text(' ')->many());
$result = $expression->parse('2 + 3 * 4');
$result->value(); // 14, lazy and cached
$result->rawText(); // '2 + 3 * 4'
Explicit overrides remain local to their Syntax vocabulary.
Both factories also have fluent forms. primary->operatorExpression(...operators)
uses the current expression as its primary, rather than appending another parser.
primary->expressionChoice(...alternatives) includes the current expression as
the first alternative and preserves the selected value lazily. These operations
also load automatically on unscoped expressions:
$expression = $syntax->regex('/[0-9]+/A')->mapText('intval')->operatorExpression(
O::infixLeft('+', 10, static fn(int $a, int $b): int => $a + $b),
);
$expression->parse('2+3')->value(); // 5
These fluent forms replace the previous chained rule fallback, which appended a separately constructed expression or choice to the current expression.
No operators are supplied implicitly. Operands and operator syntax accept facades,
Parser objects or literal strings; operator definitions are explicit Operator
objects. Definitions detach caller-owned parser builders when constructed.
Precedence and associativity¶
Higher integer precedence binds tighter. Integers may be negative, and declaration order need not follow precedence order. Every operator at a given precedence must have the same kind; mixing kinds raises InvalidArgumentException during authoring. Give prefix, postfix, and different infix associativities distinct precedences.
| Definition | Behavior |
|---|---|
O::infixLeft(syntax, precedence, reducer) |
a-b-c becomes (a-b)-c |
O::infixRight(syntax, precedence, reducer) |
a^b^c becomes a^(b^c) |
O::infixNone(syntax, precedence, reducer) |
At most one operator at that level; a<b<c fails complete parsing |
O::prefix(syntax, precedence, reducer) |
Repeated prefix operators apply right to left |
O::postfix(syntax, precedence, reducer) |
Repeated postfix operators apply left to right |
Unary reducers receive one operand value. Binary reducers receive left and right
operand values. They may return scalars, objects, arrays or null, so a reducer can
build domain AST objects instead of calculating numbers. Reducers should be pure;
application effects belong in onCommit().
Operator alternatives at one level retain declaration order and the session's
choice policy. Put overlapping longer spellings before shorter ones, or apply
prefer(ChoicePolicy::LONGEST) explicitly. A later missing operand does not retry
an already selected operator. An empty operator spelling is rejected by Text;
nullable operator parsers and consuming-operand violations are rejected by graph
analysis, with runtime progress checks for custom parsers.
This is a precedence-table grammar: each level takes operands from tighter levels.
With prefix - below ^, -2^2 means -(2^2), but a negative exponent must be
grouped as 2^(-2) rather than 2^-2. Choose reducers that support the desired
numeric types; overflow, division and arithmetic exceptions follow normal PHP rules.
Parentheses and alternative values¶
Use explicit recursive Ruleset references for grouping:
use Vanderlee\Comprehend\Extensions\Extraction\Extraction;
use Vanderlee\Comprehend\Builder\Ruleset;
$rules = new Ruleset();
$primary = $syntax->expressionChoice(
$number,
$syntax->of($rules->rule('expr'))->between('(', ')'),
);
$rules->define('expr', $syntax->operatorExpression(
$primary,
O::infixLeft('+', 10, static fn(int $a, int $b): int => $a + $b),
O::infixLeft('*', 20, static fn(int $a, int $b): int => $a * $b),
)->spacing(Extraction::syntax()->text(' ')->many()))->root('expr');
$rules->freeze()->parse('(2+3)*4')->value(); // 20
expressionChoice(...alternatives) forwards the selected alternative's value
lazily, including values from grouped expressions. Ordinary choice()/or()
retain their existing default raw-text projection. With no operator definitions,
operatorExpression(primary) preserves the primary parser's behavior and value.
Sources, spacing and lifecycle¶
No whitespace is inserted into operator syntax. Existing intervening spacing and
lexeme policies apply. The builder does not trim document boundaries; recognize
leading and trailing trivia explicitly when wanted. An incomplete extension such
as 1 + bad may yield the prefix 1, with its abandoned spacing and operator
discarded. Complete-input parsing rejects the remaining text. Prefix parsing of a
non-associative chain likewise returns the accepted first comparison.
All syntax, including operators, parentheses and accepted trivia, remains in the CST with byte-based spans. Naming and tags retain their usual AST behavior. Domain values do not rewrite the source tree into an operator-shaped AST automatically; construct that representation in reducers when needed. Byte and UTF-8 sources, file snapshots, graph freezing and recognition limits use their existing contracts.
Parsing, AST inspection and raw-text reads do not run reducers. value() evaluates
and caches the selected reductions or thrown error for that recognition. A later
mapValue() or mapText() on the expression replaces the default reduction.
Operator parser mappings are not evaluated to select the reducer; validators may
still explicitly read them. All accepted operands/operators retain their named
collections, semantic validation and ordered explicit effects. Discarded attempts
contribute no selected validation or committed effects. Reduction callbacks are
ordinary PHP work and are not preempted by recognition budgets.
Internally, the extension specializes Sequence, Choice, Repeat and SeparatedList only to project lazy values. The shared list runtime handles chain spacing and rollback; the core list's default item-value projection remains unchanged.
Run php docs/examples/expressions.php for checked arithmetic and grouping.