Comprehend

Comprehend logo

Comprehend is a PHP parser-combinator library for building grammars from small, reusable parsers. It supports named grammars, ABNF authoring, RFC libraries, immutable syntax trees and lazy semantic values with explicit commit effects.

Installation

Requires PHP 8.2+, JSON and mbstring. DOM is optional for XML serialization. Comprehend is MIT licensed.

composer require vanderlee/comprehend

See the breaking-release guide for the status and migration requirements of the 2.0.0 redesign.

Quick start

Parse 2d6+3 into a description of two six-sided dice with a +3 modifier. The bundled Numbers and Extraction extensions load automatically; this example parses the notation without rolling any dice.

require 'vendor/autoload.php';

use Vanderlee\Comprehend\Comprehend as C;
use Vanderlee\Comprehend\Extensions\Numbers\SignPolicy;

$modifier = C::integerValue(-100, 100, allowLeadingZeros: true, sign: SignPolicy::REQUIRED)
    ->optionalValue(default: 0);
$roll = C::collect(
    C::integerValue(1, 100)->thenIgnore('d'),
    C::integerValue(2, 1000)->named('sides'),
    $modifier,
)->map(static fn(array $parts): array => [
    'dice' => $parts[0],
    'sides' => $parts[1],
    'modifier' => $parts[2],
]);

$result = $roll->parse('2d6+3');
if ($result->ok) {
    $value = $result->output(); // ['dice' => 2, 'sides' => 6, 'modifier' => 3]
    echo $result->rawText();    // '2d6+3' (original text)
}

thenIgnore('d') keeps the count's value, collect() gathers the values, and map() gives them descriptive keys. 1d20 defaults the modifier to zero; 2d6-3 produces -3. Counts range from 1–100, sides from 2–1000, and modifiers from -100 to 100. The count and lowercase d are required. allowLeadingZeros: true permits signed zero and leading zeros in the modifier.

parse() requires complete input. Semantic values are lazy and cached; rawText() preserves the original source. All offsets and spans use bytes. Side effects run only through explicit commit().

Explore the documentation

Examples run locally with PHP; this website serves static documentation.