Separated lists¶
Separated lists are available in core, without installing an extension.
Parser\Structure\SeparatedList recognizes the list and lazily projects item values.
$item->separatedBy($separator, min: 0, max: null, allowLeading: false,
allowTrailing: false) recognizes consuming items separated by another parser.
The facade accepts literal strings for either operand; static
Comprehend::separatedBy($item, $separator, ...) and Syntax vocabularies expose
the same operation. Low-level object grammars use
new Parser\Structure\SeparatedList(Parser $item, Parser $separator, ...).
use Vanderlee\Comprehend\Extensions\Extraction\Extraction;
$numbers = Extraction::syntax()->integer()->mapText(static fn(string $text): int => (int) $text)
->separatedBy(',', min: 1, allowTrailing: true);
$result = $numbers->parse('10,20,');
$result->value(); // [10, 20], lazy and cached
$result->rawText(); // '10,20,'
Bounds count items, not separators. Negative bounds and maximums below the minimum are rejected. A zero maximum recognizes an empty list without attempting either operand. Known nullable items are rejected when freezing; every successful item must consume input at runtime too. A separator may be zero-width because items supply progress.
Empty lists are accepted when min is zero. Leading and trailing separators
are disabled by default and enabled independently. Either boundary separator
requires at least one item: a separator alone is never accepted as a complete
list, even with both options enabled. Repeated separators do not stand for empty
items. At the maximum item count, an allowed trailing separator can still be
consumed, but no additional item is attempted.
Prefixes and spacing¶
The parser is greedy and uses the same prefix semantics as repetition. Once the
minimum is met, a failed separator/item extension ends the list. With an item
parser for a, matchPrefix('a,x') accepts a; with trailing separators enabled
it accepts a,. Complete-input parse() rejects both because x remains.
Use explicit closing delimiters when embedding a list in a larger document.
There is no implicit syntax cut or retry after a later suffix failure.
Scoped spacing applies between items and separators, including zero-width
separators. Boundary whitespace remains explicit. Local spacing() and
lexeme() policies work as on sequences and repetitions. Spacing before an
abandoned pair is rolled back; with an accepted trailing separator, spacing
before that separator is retained, while spacing after it is not. Ordinary
failed extension probes do not pollute diagnostics; failures needed to satisfy
the minimum retain their expectations. Abandoned item/separator diagnostics are
also retained separately for a failed enclosing parse or complete-input check.
The farthest failure wins, with tied expectations combined. Successful prefix
and complete parses still suppress ordinary termination probes; this changes
diagnostics only, without committing to a separator or consuming failed items.
Trees and lifecycle¶
The CST retains accepted items, separators and automatic trivia in source order, with original byte spans. Separator names and tags retain their normal AST behavior; separators are not implicitly trivia. Raw text always slices the accepted source span.
The default value is a list of item values. Item mappings are evaluated lazily,
and separator mappings are not read to build the list. A list-level mapValue()
or mapText() replaces this default projection. Each recognition has independent
value and error caches.
Accepted item and separator named collections, semantic validators and explicit commit effects participate normally. Automatic trivia contributes validation and effects, but no named collections. Abandoned extensions contribute neither selected validation nor committed effects. Parsing and reading values never commit effects.
Run php docs/examples/separated-lists.php for a checked example.