Extraction expansion

Extensions\Extraction\Extraction is the automatically loaded application-value vocabulary. It is bundled with Comprehend and uses the shared parser graph, recognition, immutable syntax trees, cached projections and explicit commit effects.

use Vanderlee\Comprehend\Comprehend as C;
use Vanderlee\Comprehend\Extensions\Extraction\Extraction;

$syntax = C::syntax();
$number = $syntax->integer()->mapText('intval');
$list = $number->separatedBy(',')->between('[', ']');
$list->parse('[1,2]')->value(); // [1, 2]

Global C::collect() and expressions' map() or mapText() calls load the extension automatically. Explicit registration remains local and immutable; Extraction::syntax() is still supported. Use $syntax->of($expressionOrParser) to attach the vocabulary to an existing facade, rule reference or object parser. Facade inputs retain their semantic value type; object-parser inputs remain conservatively mixed in static analysis.

Parser implementations live in Extraction\Parser; static authoring signatures use ordinary PHPDoc in core Syntax and Syntax\ValueMappings.

Operations

Operation Selected value
map(callable) Transform the current value, composing lazily
mapText(callable) Replace projection using original matched text
mapWith(next, combine) Combine the current and next parser's values
foldLeft(step, combine, min: 0, max: null) Reduce a head and repeated steps from left to right
collect(...) Tuple of direct operand values
record(fields) Array of direct field values under the supplied keys
valueChoice(...) Selected alternative's value
manyValues(), someValues(), repeatValues(min, max) List of accepted item values
optionalValue(default: null) Accepted value or literal default

Collection, choice, repetition and optional operations have both vocabulary factories and fluent forms. Mapping and fold operations are fluent. Factories accept literal strings, facades and Parser objects; low-level constructors accept Parser objects explicitly.

mapWith() evaluates the left value, the right value, and the combiner in that order, lazily on the first value read. foldLeft() evaluates its head first, then each accepted step followed by its combiner. Zero steps return the head unchanged, including null or an object. Bounds count steps, excluding the head; the combiner returns the next accumulator of the head's value type. No intermediate step-value array is built, and a throwing combiner prevents later step values from being evaluated. Results and exceptions are cached per recognition.

$number = Extraction::syntax()->integer()->mapText('intval');
$minus = Extraction::syntax()->text('-')->ignoreThen($number);
$subtraction = $number->foldLeft($minus, static fn(int $a, int $b): int => $a - $b);
$subtraction->parse('10-3-2')->value(); // 5: (10 - 3) - 2

These operations reuse Sequence and Repeat recognition: all source syntax and selected effects remain in the tree and lifecycle graph. A failed optional step rolls back its input, diagnostics, trivia and effects; prefix parsing can leave an incomplete operator unconsumed, while full-input parsing rejects that leftover input. Required-step failures retain their diagnostics. Steps must consume input unless max: 0 disables repetition. Ordinary sequence spacing applies between the head and tail as well, including an empty tail; use zero-or-more trivia when spacing is optional. Callbacks never choose syntax or run during recognition.

MapWith and FoldLeft are also available as low-level constructors: new MapWith(Parser $left, Parser $right, callable $combine) and new FoldLeft(Parser $head, Parser $step, callable $combine, int $min = 0, ?int $max = null). They live in Extensions\Extraction\Parser; FoldSteps is an internal repetition implementation. Both fluent names load automatically but are not exposed as Syntax factories. Run the pipeline and fold example.

record() is a vocabulary factory accepting an ordered array of field parsers. Fields recognize in insertion order, and their lazy, cached values retain the original string or integer keys. Automatic spacing contributes source text and syntax nodes but no extra fields. Optional fields retain their key with the configured default, including null. An empty record recognizes empty input and returns [].

$record = Extraction::syntax()->record([
    'name' => Extraction::syntax()->readWhileRange('a', 'z', min: 1),
    'count' => Extraction::syntax()->integer()->mapText('intval'),
])->spacing(C::readWhileSet(' '));
$record->parse('item 12')->value(); // ['name' => 'item', 'count' => 12]

Fields may be literal strings, facades or Parser objects, including nested records. Projection does not run effects; selected effects require commit(). Static analysis describes records as array<array-key, mixed> rather than keyed shapes. Calling ->record(fields) on an existing expression follows ordinary terminal chaining: it appends the record and the enclosing sequence returns raw text. Use the vocabulary factory to obtain the record's value directly. Run php docs/examples/record.php for a checked example.

Concrete extraction classes are Collect, Record, ValueChoice, ValueRepeat, OptionalValue, MapWith and FoldLeft under Vanderlee\Comprehend\Extensions\Extraction\Parser. They can be constructed directly without installing a vocabulary.

Core provides separatedBy(), thenIgnore(), ignoreThen() and between() with the same item-value and operand-selection contracts whether Extraction is installed or not. Their object parsers are Parser\Structure\SeparatedList and Parser\Structure\ValueSequence. Core also retains ordinary sequence/choice/repetition, the mapValue() projection primitive, named collections, validation and explicit effects. Extraction adds explicit application-value extraction and transformation. Expression and recovery extensions reuse extraction classes where needed without activating Extraction syntax names.

The extension was renamed from Binding to Extraction; update imports. No compatibility aliases are provided.

Static analysis

No PHPStan extension or configuration include is required. Remove the former phpstan-extension.neon and extensions/Extraction/phpstan.neon includes. PHPDoc declares the bundled vocabulary for analysis; runtime dispatch discovers it automatically. Custom vocabulary overrides retain their own runtime contracts. Mappings and pipelines infer callback return types; folds preserve the head's accumulator type and check compatible callback arguments/returns. Records, collections and overloaded factory operations have conservative types. See static value types. PHPStan is a development tool, not a runtime dependency.

See the application tutorial, value composition, delimiter selection and separated lists for recognition and lifecycle contracts. Run php docs/examples/application-values.php for a checked example.