Bundled RFC and specification grammars¶
Discoverable subject extensions¶
Grammar classes live in their owning extension's Grammar namespace, such as
Vanderlee\Comprehend\Extensions\Network\Grammar\Rfc3986 and
Vanderlee\Comprehend\Extensions\Encodings\Grammar\Rfc4648.
Each subject below has its own bundled extension manifest. Factories load on first
static, scoped Syntax, or fluent use and construct a fresh specification graph.
They return the original text; they do not decode formats, resolve names, evaluate
policies, validate mail delivery, or construct application values.
Each grammar has one owner. Cross-subject imports remain explicit: Network uses
Abnf grammars, while Mail uses Abnf, Network, and Xml grammars. Shared base classes
live in core as Builder\AbstractSpecification and Syntax\SpecificationExtension,
with reusable Unicode helpers in Extensions\Shared\Internal. YAML-specific helpers live in
Extensions\Yaml\Internal. The former Library namespaces have no aliases.
use Vanderlee\Comprehend\Comprehend as C;
C::ipv4()->parse('192.0.2.1')->value(); // '192.0.2.1'
C::text('@')->ignoreThen(C::uuid());
C::rfc3986(rule: 'host')->parse('example.org');
C::rfc5234(rule: 'DIGIT')->some()->parse('42');
| Extension | Factories |
|---|---|
| Network | ipv4(), ipv6(), hostname(), uri(), uriReference(), absoluteUri(), iri(), urn(), uriTemplate(), hostnameLabel(), uriScheme(), uriAuthority(), uriHost(), uriPort(), uriRelativePart(), uriPathAbempty(), uriSegment(), uriQuery(), uriFragment(), uriPercentEncoded(), uriUnreserved(), iriUcschar(), iriPrivateChar() |
emailAddress(), mailbox(), mailboxList(), emailAddressList(), mailMessage(), emailLocalPart(), emailDomain(), emailDotAtomText(), emailQuotedString(), emailFoldingWhitespace(), emailCommentsAndFoldingWhitespace() |
|
| DateTime | dateTime(), annotatedDateTime(), dateTimeDate(), dateTimeTime() |
| Uuid | uuid(), uuidUrn() |
| SemVer | semver() |
| LanguageTag | languageTag() |
| Encodings | base16(), base32(), base32Hex(), base64(), base64Url(), base64Unpadded(), base64UrlUnpadded() |
| Json | json(), jsonPointer(), jsonPath(), jsonString(), jsonNumber() |
| HttpStructuredFields | structuredFieldItem(), structuredFieldList(), structuredFieldDictionary() |
| Xml | xmlDocument() |
| Yaml | yaml() |
| Abnf | Compiler::compile() (existing compiler API) |
dateTime() selects RFC 3339 date_time; annotatedDateTime() selects RFC
9557 date_time_ext, which also accepts timestamps without annotations.
dateTimeDate() and dateTimeTime() select full_date and full_time.
emailAddress() selects addr_spec; mailbox() may include a display name.
emailAddressList() selects address_list and may contain groups;
mailboxList() selects the narrower mailbox_list.
The URI subrule names select their corresponding RFC 3986 productions:
uriPathAbempty() is path_abempty, uriPercentEncoded() is pct_encoded,
and uriUnreserved() matches one unreserved unit. hostnameLabel() uses RFC
1123 label; the IRI character factories select RFC 3987 ucschar and
iprivate. Mail subrules select RFC 5322 local_part, domain,
dot_atom_text, quoted_string, fws, and cfws. jsonString() and
jsonNumber() select RFC 8259 lexical productions. Consumers that refine these
rules still need their own restrictions and semantic checks.
Explicit RFC versions¶
Every implemented RFC has a factory accepting string $rule = 'ROOT':
| Extension | Versioned factories |
|---|---|
| Network | rfc1034(), rfc1035(), rfc1123(), rfc3513(), rfc3986(), rfc3987(), rfc4291(), rfc6570(), rfc8141() |
rfc2045(), rfc2046(), rfc4408(), rfc5321(), rfc5322(), rfc6376(), rfc6531(), rfc6532(), rfc6854(), rfc7208(), rfc9989(), rfc9990(), rfc9991() |
|
| DateTime | rfc3339(), rfc9557() |
| Uuid | rfc9562() |
| LanguageTag | rfc5646() |
| Encodings | rfc4648() |
| Json | rfc6901(), rfc8259(), rfc9535() |
| HttpStructuredFields | rfc9651() |
| Abnf | rfc2234(), rfc4234(), rfc5234(), rfc7405() |
The default selects the specification's existing ROOT. RFC 3986 has no
ROOT production, so its factory explicitly selects URI when the argument
is omitted or is 'ROOT'. Other rule names are passed unchanged, including
existing underscores and case. Undefined rules retain the normal preparation error.
ipv6() selects a bare address; the RFC 4291 default root includes a prefix length.
Versioned factories never substitute a newer RFC, including when an older RFC has been obsoleted. Existing shared implementations and coverage limits remain; a versioned entry point is not a claim to implement all document requirements. Direct classes still support custom rule overrides:
use Vanderlee\Comprehend\Extensions\Network\Grammar\Rfc3986;
use Vanderlee\Comprehend\Extensions\SemVer\Grammar\SemVer;
use Vanderlee\Comprehend\Extensions\Xml\Grammar\Xml;
use Vanderlee\Comprehend\Extensions\Yaml\Grammar\Yaml;
$host = (new Rfc3986())->rule('host');
$prerelease = (new SemVer())->rule('prerelease');
$element = (new Xml())->rule('element');
$stream = (new Yaml())->rule('stream');
Factories are discoverable rather than reserved names. Explicit Syntax definitions
can override them locally. An explicit extend(new Network()) (under
Vanderlee\Comprehend\Extensions) installs that subject into one vocabulary.
FreezeFlags::NONE remains supported. Existing Numbers, Extraction, Expressions,
AsciiIdentifiers, Optimizer, and Recovery factories are unchanged.
See the runnable example.
Rfc2234, Rfc4234, Rfc5234 and Rfc7405 provide ABNF-related reusable rules. Rfc3513 and Rfc4291 provide IPv6 rules, Rfc3986 provides URI rules, and Rfc4408 and Rfc7208 provide SPF-related grammar assets. The library also includes email, MIME, DNS, JSON/JSONPath, HTTP structured fields, timestamps, UUIDs, encodings, language tags, URI extensions, DMARC, SemVer, XML and YAML. See the specification catalog for class names, root rules, coverage boundaries and upstream acceptance tests. They use the public facade with explicit Ruleset references and the same source runtime as application parsers.
$rfc = new \Vanderlee\Comprehend\Extensions\Network\Grammar\Rfc3986();
$result = $rfc->rule('IPv4address')->parse('192.0.2.1');
$result->ast()->firstNamed('dec_octet')->rawText(); // 192
Use rule('name') for fluent imports; ref('name') is the low-level Parser
reference. Magic property/method imports are removed.
Octet rules such as OCTET require ByteSource. ASCII rules generally work in both
source modes; mode-incompatible octet bounds are explicit errors in UTF-8 mode.
Tests preserve existing acceptance fixtures in both modes where meaningful.
These assets are not a claim of exhaustive RFC conformance; conformance review
is separate from runtime consolidation. Constructors accept facade, custom Parser,
Definition or factory overrides as named maps. Factories may return facade values.
Rfc3986::rule('URI') accepts authority, absolute-path, rootless and empty-path
forms, including https://example.com/path, file:/path, urn:example:animal
and scheme:. Use relative_ref for relative paths, query-only and
fragment-only references. These alternatives follow
RFC 3986 Appendix A.
The Rfc4408 root can be frozen and used to parse complete records such as
v=spf1, v=spf1 -all and v=spf1 a mx -all, with optional trailing spaces.
Its explain_string rule repeats individual macro expansions, literal characters
and spaces so every iteration consumes input, including when the explanation is
empty. This preserves the syntax of
RFC 4408's macro productions
without repeating a nullable parser.
Use Rfc4291 for the IPv6 text forms in
RFC 4291, which supersedes RFC 3513.
Its root (also named ipv6) recognizes an address with a /prefix-length from
0 to 128. Import ipv6_address to recognize a bare address, including compressed
forms and embedded IPv4 addresses. Zone identifiers such as %eth0 are outside
this RFC's address syntax.
Use Rfc7208 for SPF record syntax in
RFC 7208 Section 12, which supersedes
RFC 4408. Its root is record. It supports case-insensitive SPF keywords,
optional ptr domains, IPv4 and IPv6 CIDR bounds, and macro syntax including
%{v}. Named imports include domain_spec, macro_string, explain_string,
ip4_network and ip6_network; mechanism rules retain the existing names
A, MX, PTR, IP4 and IP6. It recognizes syntax only: it does not perform
DNS lookups, evaluate policies, expand macros, or parse Received-SPF headers.
Rfc3513 shares the corrected compressed-address recognition with Rfc4291,
including lowercase hexadecimal digits. Rfc4408 also benefits from that IPv6
fix; its SPF-specific rules keep their existing behavior.
$spf = new \Vanderlee\Comprehend\Extensions\Mail\Grammar\Rfc7208();
$result = $spf->freeze()->parse('v=spf1 ip6:2001:db8::/32 -all');
$result->success; // true
Run php docs/examples/libraries.php for checked IPv6 and SPF examples.
The ABNF IPv4 example compares the frontend's documented local-longest policy with equivalent object/Ruleset grammars and bundled RFC acceptance fixtures. It does not promise generalized ABNF ambiguity handling.