Parse application values

This tutorial uses the automatically loaded Extraction expansion. C::syntax() and global calls work without registration; Extraction::syntax() remains supported in the examples below.

Build a parser that returns a domain object directly. This tutorial uses a small job format with an optional retry setting and nested lists of batch IDs:

report retry=off [[1, 2], [], [3]]
report [[1], [2, 3]]

The first job disables retries. The second omits the setting and defaults to three retries. Empty outer and inner lists are accepted. IDs range from 0 to 999, and numeric retry counts from 0 to 9. The format has no quoted names or comments.

Run the complete, checked example:

php docs/examples/application-values.php

The grammar source contains the domain class and jobParser() factory used by the regression tests. The steps below build the same grammar with the Comprehend facade.

Start with the domain object

final class Job
{
    public readonly string $name;
    public readonly int|bool $retries;
    /** @var list<list<int>> */
    public readonly array $batches;

    /** @param list<list<int>> $batches */
    public function __construct(string $name, int|bool $retries, array $batches)
    {
        $this->name = $name;
        $this->retries = $retries;
        $this->batches = $batches;
    }
}

The grammar supplies either an integer retry count or false for disabled retries. Application values do not require naming AST nodes or traversing syntax.

Recognize text and convert numbers

use Vanderlee\Comprehend\Extensions\Extraction\Extraction;

$name = Extraction::syntax()->regex('/[A-Za-z][A-Za-z0-9_]*/A');
$number = Extraction::syntax()->integer(0, 999)->mapText('intval');

An unmapped parser returns its matched text. mapText() converts the number's source text to an integer. Conversion is deferred until its value is needed. The regex is anchored at the parser's current position; names use ASCII letters, digits and underscores and must begin with a letter.

Preserve values from alternatives

use Vanderlee\Comprehend\Extensions\Extraction\Extraction;

$retryValue = Extraction::syntax()->valueChoice(
    Extraction::syntax()->integer(0, 9)->mapText('intval'),
    Extraction::syntax()->text('off')->map(static fn(string $text): bool => false),
);
$retries = Extraction::syntax()->text('retry=')->ignoreThen($retryValue)->optionalValue(default: 3);

valueChoice() forwards the successful alternative's value. Ordinary choice() returns its matched text by default. ignoreThen() recognizes the literal prefix but selects the setting's value. optionalValue() supplies 3 only when the whole setting is absent; a present zero or false remains unchanged. A successful child whose value is null would likewise preserve null.

An incomplete setting is not repaired. When used inside this job grammar, retry=unknown cannot match the following batch list, so complete parsing fails. Optional parsing itself can accept an empty prefix when its child fails; it does not commit to a field just because part of its prefix matched.

Build nested lists without source traversal

$batch = $number->separatedBy(',')->between('[', ']');
$batches = $batch->separatedBy(',')->between('[', ']');

separatedBy() returns a list of item values. between() selects that list while recognizing both delimiters. Applying them twice preserves the nesting: [[1, 2], [], [3]] becomes the same shape of PHP arrays containing integers. The default minimum is zero, and trailing separators are rejected.

For adjacent items without separators, use manyValues() or someValues(). Use repeatValues(min: ..., max: ...) for explicit bounds. These return lists of item values too; ordinary many() and some() retain raw-text defaults.

Collect fields and construct the object

use Vanderlee\Comprehend\Extensions\Extraction\Extraction;

$job = Extraction::syntax()->collect($name, $retries, $batches)
    ->map(static fn(array $parts): Job => new Job($parts[0], $parts[1], $parts[2]))
    ->spacing(Extraction::syntax()->set(" \t\r\n")->many());

collect() supplies the direct operand values in order: name, retry setting, and nested lists. map() transforms that array into a Job. It composes with the existing value projection, whereas mapText() would receive the entire matched string and mapValue() would receive a ParseResult.

Spacing applies between grammar items, including list separators. It does not add entries to collected values or lists. This grammar accepts spaces, tabs and line breaks between items, but does not trim leading or trailing whitespace. The literal retry= stays contiguous. Recognize document boundary trivia explicitly if your format allows it; see spacing and trivia.

Parse, check success, then read the value

$grammar = $job->freeze();
$input = 'report retry=off [[1, 2], [], [3]]';
$result = $grammar->parse($input);
if (!$result->success) {
    throw new RuntimeException($result->diagnostic?->message() ?? 'Invalid job');
}

$value = $result->value();
$value->name;    // 'report'
$value->retries; // false
$value->batches; // [[1, 2], [], [3]]
$result->rawText(); // original input, including spaces and punctuation

parse() requires complete input. Malformed fields, missing delimiters and trailing input fail. Check success instead of using the value as a success flag: valid parsers can return false or null. Structured failures describe their byte offset and expectations; see diagnostics.

Freezing prepares a reusable grammar; each parse still owns its value caches. Constructors and mapping callbacks are lazy: parsing alone does not construct the Job. Repeated value() calls return the same cached object for that result; another parse constructs its own object. A mapping exception is also cached and is thrown when the value is read. Recognition success does not guarantee that application mapping code will complete successfully.

The syntax tree and byte spans retain the source independently of the domain object. Keep mappings pure. Value access does not run commit effects; use onCommit() and explicit commit() for application effects. See semantic values and lifecycle for details.

For static analysis, the example's factory declares @return C<Job>. With the PHPDoc signatures, its mapping callbacks are checked and jobParser()->freeze()->parse($input)->value() has type Job|null. The nullable result accounts for recognition failure; checking the boolean success property alone does not narrow that value type. Collected tuple positions are conservatively mixed in static analysis.