README

Build object oriented LR(1) lexer, tokenizers and parsers in PHP using BNF-based syntax.

Copyright © 2011-2024 Martijn W. van der Lee Toyls.com, MIT license applies.

Project status

Comprehend is beta software. Its parser primitives and test suite are mature, but parts of the documentation and higher-level tooling are still incomplete. The current release supports PHP 7 and PHP 8; the former Match base class was renamed to AbstractMatch because match became a reserved keyword in PHP 8.

Grammars are currently constructed programmatically from parser objects or a Ruleset. Comprehend does not read BNF or EBNF grammar files directly.

Documentation

The documentation is maintained in the docs directory:

• Tutorial
• Builder
• Facade
• Bundled RFC libraries
• Reference
• Frequently asked questions
• Contributing

Choosing a grammar style

Use a Ruleset for most complete grammars. It names rules and resolves recursive references automatically. Direct parser objects are useful for small compositions or custom parsers, but recursive object graphs need explicit Stub placeholders. Both styles use the same parser primitives underneath.

Comprehend does not have separate generated lexer and parser phases. Terminal parsers recognize input; assigning token names to parser rules makes the result usable as a token stream or syntax tree. Parsers are interpreted at runtime and are not compiled into generated PHP source.

Features

• Closely follows BNF syntax using objects as operands.
• Includes various pre-defined RFC syntax rules.
• Whitespace skipping.
• Support for tokenizing.
• Add your own custom parsers.
• Create full sets of rules.
• Optional case (in)sensitivity.

Example

Imports used below

use Vanderlee\Comprehend\Builder\Ruleset;
use Vanderlee\Comprehend\Parser\Structure\Repeat;
use Vanderlee\Comprehend\Parser\Structure\Sequence;
use Vanderlee\Comprehend\Parser\Terminal\Regex;
use function Vanderlee\Comprehend\Library\plus;
use function Vanderlee\Comprehend\Library\regex;
use function Vanderlee\Comprehend\Library\s;
use function Vanderlee\Comprehend\Library\star;

ABNF

word	= [A-Za-z]+
list	= word *[ ',' word ]    

Comprehend, using objects:

$word	= new Repeat(new Regex('/[A-Za-z]/'), 1);
$list	= new Sequence($word, new Repeat(new Sequence(',', $word)));

Comprehend, using objects and array notation:

$word	= new Repeat(new Regex('/[A-Za-z]/'), 1);
$list	= new Sequence($word, new Repeat([',', $word]));

Comprehend, using library functions:

$word	= plus(regex('/[A-Za-z]/'));
$list	= s($word, star([',', $word]));

Comprehend, using Ruleset constructor

$list = new Ruleset();
$list->define('word', plus(regex('/[A-Za-z]/')));
$list->define(Ruleset::ROOT, s($list->word, star([',', $list->word])));