Delimiters and value selection¶
These structural operations are available in core, without installing an extension.
These fluent methods recognize every operand and select one operand's lazy value:
| Method | Recognition order | Default value |
|---|---|---|
$a->thenIgnore($b) |
A, B | A's value |
$a->ignoreThen($b) |
A, B | B's value |
$body->between($open, $close) |
Open, body, close | Body's value |
Operands accept Comprehend expressions, Parser objects, or literal strings. Syntax
vocabularies expose the same fluent methods. Existing then() retains its ordinary
sequence behavior; it does not select a child value.
These names are reserved core built-ins.
use Vanderlee\Comprehend\Extensions\Extraction\Extraction;
$number = Extraction::syntax()->integer()->mapText(static fn(string $text): int => (int) $text);
$numbers = $number->separatedBy(',')->between('[', ']');
$result = $numbers->parse('[10,20]');
$result->value(); // [10, 20], lazy and cached
$result->rawText(); // '[10,20]'
$number->thenIgnore(';')->parse('42;')->value(); // 42
Extraction::syntax()->text('return:')->ignoreThen($number)->parse('return:42')->value(); // 42
Extraction::syntax()->text('hello')->between('(', ')')->parse('(hello)')->value(); // 'hello'
Syntax, spacing and lifecycle¶
All operands must recognize successfully, including closing delimiters. Prefix
parsing permits remaining input only after the complete sequence succeeds.
Diagnostics, work limits and scoped spacing use the ordinary sequence runtime.
Spacing is inserted between operands; leading and trailing document trivia remain
explicit. lexeme() suppresses inserted spacing and spacing(null) disables it
locally. Value-selecting sequences retain their composition boundaries.
The outer span and rawText() include every accepted operand and intervening
trivia. The CST retains all syntax, and naming and tags keep their normal AST
behavior. Selection does not implicitly mark delimiters as trivia or hide named
nodes. Selecting an unmapped body returns the body's own raw text, rather than
the surrounding delimiters. Empty selected text and null mapped values remain
valid values.
Reading the selected value evaluates only that operand's value and caches its
output or exception. Unselected value mappings are not evaluated merely to obtain
the selected value. A later list/sequence-level mapValue() or mapText() replaces
the default selection and receives the full outer result or raw text respectively.
All accepted operands still contribute named collections, semantic validation and explicit commit effects in recognition order. An unselected operand's validator may explicitly read its own value. Automatic trivia retains the existing validation and effect behavior. Failed or discarded sequences never commit their effects.
Low-level object authoring¶
new ValueSequence(int $valueIndex, Parser ...$parsers) uses zero-based operand
positions, excluding automatic trivia. For example:
use Vanderlee\Comprehend\Parser\Structure\ValueSequence;
use Vanderlee\Comprehend\Parser\Terminal\Text;
$wrapped = new ValueSequence(1, new Text('('), new Text('hello'), new Text(')'));
Positions must refer to an existing operand. Mutable container operations address the current operand order; removing enough operands to invalidate selection raises a grammar error when freezing, or an exception during successful direct recognition. Snapshots detach operands and retain independent per-recognition value caches.
Run php docs/examples/value-selection.php for checked examples.