NAME

Pegex::Grammar - Pegex Grammar Base Class

SYNOPSIS

Define a Pegex grammar (for the Foo syntax):

package Pegex::Grammar::Foo;
use base 'Pegex::Grammar';

use constant text => q{
foo: <bar> <baz>
... rest of Foo grammar ...
};
use constant receiver => 'Pegex::Receiver';

then use it to parse some Foo:

use Pegex::Grammar::Foo;
my $ast = Pegex::Grammar::Foo->parse('my/file.foo');

DESCRIPTION

Pegex::Grammar is a base class for defining your own Pegex grammar classes. It provides a single action method, `parse()`, that invokes a Pegex parser (usually Pegex::Parser) for you, and then returns the kind of result that you want it to. In other words, subclassing Pegex::Grammar is usually all you need to do to create a parser/compiler for your language/syntax.

Pegex::Grammar classes are very simple. You just need to define a text property that returns your Pegex grammar string, or (if you don't want to incur the compilation of the grammar each time) a tree property which returns a precompiled grammar.

You also need to define the receiver class or object that will produce a result from your parse. 'Pegex::Receiver' is the easiest choice, as long as you are satisfied which its results. Otherwise you can subclass it or define something different.

PROPERTIES

There are 4 properties of a Pegex::Grammar: tree, text, parser and receiver.

tree

This is the data structure containing the compiled grammar for your syntax. It is usually produced by Pegex::Compiler. You can inline it in the tree method, or else the tree_ method will be called to produce it.

The tree_ method will call on Pegex::Compiler to compile the text property by default. You can define your own tree_ method to do override this behavior.

Often times you will want to generate your own Pegex::Grammar subclasses in an automated fashion. The Pegex and TestML modules do this to be performant. This also allows you to keep your grammar text in a separate file, and often in a separate repository, so it can be shared by multiple programming language's module implementations. See the src/ subdirectory in http://github.com/ingydotnet/pegex-pm/.

text

This is simply the text of your grammar, if you define this, you should (probably) not define the tree property. This grammar text will be automatically compiled when the tree is required.

parser

This will default to Pegex::Parser and you should probably never need to change that. It's the Parser class that will handle the work for the parse() method. If you need to subclass the parser for some reason, you would set the sublass here.

receiver

This will default to Pegex::Receiver. It is the class or object that will handle all the callbacks from the parser, and do something with them. Usually it will create a data structure representing the parsed input, but you can have it do whatever you want. The default receiver creates a fairly messy data structure with the result of your parse, but subclassing TestML::Receiver is easy.

You can also set this to a reference of your Grammar object, if you want to specify all your grammar receiver callbacks inline. You can do that like this (assuming a Moose compliant subclass):

has receiver => (
    is => 'ro',
    default => sub { shift },
);

METHODS

There is only one public method:

parse($input [ , $start_rule ])

The parse method applies the grammar against the text, and tells the receiver object what is happening as it happens. If the parse fails, an error is thrown. If it succeeds, then parse returns the data structure created by the receiver object.

This method is really just a handy proxy for Pegex::Parser::parse. It takes the same input arguments and produces the same outputs.

The first (required) argument is the input to be parsed. This can be a text string, a file path, or a Pegex::Input object.

The second (optional) argument is the starting rule name. By default, this is the first rule specified in the grammar, or the rule named 'TOP' (if present).

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2010, 2011. Ingy döt Net.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html