ABNF authoring subset

The bundled ABNF extension exposes Extensions\Abnf\Compiler::compile($text, $root, $numericEncoding, $choice). It translates authoring text into the existing Ruleset/combinator graph and returns a FrozenGrammar. Syntax reading is a compile-time operation; generated parsers use the same source, diagnostics, CST/AST, semantic and effect runtime as object grammars. There is no generated PHP or separate input-recognition engine.

use Vanderlee\Comprehend\Extensions\Abnf\Compiler;
use Vanderlee\Comprehend\Source\ByteSource;

$grammar = Compiler::compile('word = 1*DIGIT', 'word');
$result = $grammar->parseAll(new ByteSource('42'));
$result->success; // true
$result->rawText(); // '42'
$result->ast()->children[0]->name; // 'word'

Compiler, Reader, and SyntaxException live in Extensions\Abnf and are autoloaded directly; no registration is needed. The extension preserves the static compilation API and does not advertise syntax factories or capability providers. Update former Vanderlee\Comprehend\Abnf imports; no compatibility aliases remain.

Supported initial syntax

Syntax Translation
name = expression, references Case-insensitive rule lookup, normalized lower-case names
name =/ expression Incremental alternatives on an existing definition
a b, a / b, (a b) Sequence, local Choice, grouping
nitem, *item, n*mitem Exact, unbounded or bounded Repeat
[expression] Optional Repeat
"abc", %i"abc", %s"abc" Insensitive or explicitly sensitive ASCII literal
%b..., %d..., %x... Numeric literal, dotted sequence or inclusive range
; comment, indented continuation Grammar comments and folded expressions

The subset follows the naming, literal and operator conventions of RFC 5234, with explicit string case flags from RFC 7405. Grammar text is ASCII. Quoted-literal case folding stays within ASCII, including on UTF-8 input. LF and CRLF are accepted, and the final newline is optional as a file authoring convenience. Concatenation needs whitespace; quoted values have no backslash escape syntax. Empty quoted strings produce zero-width nodes. Core rules are available through the bundled RFC 5234 library, including DIGIT, ALPHA, WSP, CRLF and OCTET. Explicit definitions can override their normalized names; this does not rewrite dependencies inside the imported RFC library.

Numeric terminals default to octets (0–255). Pass SourceMode::UTF8 to encode numeric values as Unicode scalars; out-of-range values and surrogate endpoints are rejected. Choose a matching input source: non-ASCII octets need ByteSource, and Unicode numeric values need Utf8Source. ASCII grammars work in either source mode. Imported OCTET remains the library's byte rule. Grammar whitespace is syntax only: no whitespace skipping is inserted into the generated grammar. Recognize input whitespace explicitly with rules such as WSP.

Alternative semantics are explicit

ABNF declaratively describes alternatives; this runtime selects locally and does not revisit a successful choice after a later suffix failure. Default choice is ChoicePolicy::FIRST, with explicit LONGEST/SHORTEST enum cases available. Pass a ChoicePolicy case; string policies are rejected.

use Vanderlee\Comprehend\Runtime\ChoicePolicy;

$text = 'root = ("a" / "ab") "c"';
Compiler::compile($text, 'root')->parseAll(new ByteSource('abc'))->success; // false
Compiler::compile($text, 'root', choice: ChoicePolicy::LONGEST)
    ->parseAll(new ByteSource('abc'))->success; // true

The policy is scoped over all generated choices, including imported core choices. Longest choice is not general CFG ambiguity handling or backtracking. Repetition remains greedy. Refactor grammars when those execution semantics differ from their declarative language; the frontend does not promise arbitrary RFC grammar equivalence.

SyntaxException exposes a source-bound diagnostic and readable byte/line/column position. Undefined names, duplicate definitions, invalid numeric/bound values, unclosed groups and unsupported prose values fail explicitly. Generated graph safety errors retain their existing LogicException rule paths. Left recursion and nullable repeated children remain unsupported. Prose values, EBNF, grammar text macros, generated PHP and generalized ambiguity handling are outside this subset. Compilation has no ParseLimits; treat authoring text as trusted input.

Checked RFC example

The IPv4 example translates the IPv4/dec-octet definitions from RFC 3986 section 3.2.2 using explicit longest choice. It compares valid and invalid addresses with object/Ruleset forms and the bundled RFC grammar, including raw output and spans. Equivalent authored names also have matching AST shape; the bundled library retains its own rule spellings/groups. Run php docs/examples/abnf.php; CI runs it.