Starting Simple - The "pegex" Function

    use Pegex;
    use YAML;

    $grammar = "
    expr: num PLUS num
    num: /( DIGIT+ )/
    ";

    print Dump pegex($grammar)->parse('2+2');

This program would produce:

    expr:
    - num: 2
    - num: 2

Let's review what's happening here. The Pegex module is exporting a "pegex" function. This function takes a Pegex grammar string as input. Internally this function compiles the grammar string into a grammar object. Then it creates a parser object containing the grammar object and returns it.

The parse method is called on the input string: '2+2'. The string matches, and a nice data structure is returned.

So how was the data structure created? By the receiver object, of course! But we didn't specify one, did we? Nope. It used the default receiver, Pegex::Tree::Wrap. We could have said:

    print Dump pegex($grammar, 'Pegex::Tree::Wrap')->parse('2+2');

This receiver basically generates a mapping, where rule names of matches are the keys, and the leaf values are the regex captures.

The more basic receiver called Pegex::Tree generates a tree of sequences that contain just the data (without the rule names). This code:

    print Dump pegex($grammar, 'Pegex::Tree')->parse('2+2');

would produce:

    - 2
    - 2

If we wrote our own receiver class called "Calculator" like this:

    package Calculator;
    use base 'Pegex::Tree';

    sub got_expr {
        my ($receiver, $data) = @_;
        my ($a, $b) = @$data;
        return $a + $b;
    }

Then, this:

    print pegex(grammar, 'Calculator')->parse('2+2');

would print:

    4

More Explicit Usage

    use Pegex::Parser;
    use Pegex::Grammar;
    use Pegex::Tree;
    use Pegex::Input;
    use YAML;

    $grammar_text = "
    expr: num PLUS num
    num: /( DIGIT+ )/
    ";

    $grammar = Pegex::Grammar->new(text => $grammar_text);
    $receiver = Pegex::Tree->new();
    $parser = Pegex::Parser->new(
        grammar => $grammar,
        receiver => $receiver,
    );
    $input = Pegex::Input->new(string => '2+2');

    print Dump $parser->parse($input);

This code does the same thing as the first example, but this time we've made all the objects ourselves.

Precompiled Grammars

Say the grammar_text about is stored in a file called "share/expr.pgx". If you create a module called "lib/MyThing/Grammar.pm" with content like this:

    package MyThing::Grammar;
    use base 'Pegex::Grammar';
    use constant file => './share/expr.pgx';
    sub make_tree {
    }
    1;

Then run this command line:

    perl -Ilib -MMyThing::Grammar=compile

It will rewrite your module to look something like this:

    package MyThing::Grammar;
    use base 'Pegex::Grammar';
    use constant file => './share/expr.pgx';
    sub make_tree {
      { '+toprule' => 'expr',
        'PLUS' => { '.rgx' => qr/\G\+/ },
        'expr' => {
          '.all' => [
            { '.ref' => 'num' },
            { '.ref' => 'PLUS' },
            { '.ref' => 'num' }
          ]
        },
        'num' => { '.rgx' => qr/\G([0-9]+)/ }
      }
    }
    1;

This command found the file where your grammar is, compiled it, and used Data::Dumper to output it back into your module's "make_tree" method.

This is what a compiled Pegex grammar looks like. As soon as this module is loaded, the grammar is ready to be used by Pegex.

Automatically rebuilding during development with environment variable

If you find yourself needing to compile your grammar module a lot during development, just set this environment variable like so:

    export PERL_PEGEX_AUTO_COMPILE=MyThing::Grammar

Now, every time the grammar module is loaded it will check to see if it needs to be recompiled, and do it on the fly.

If you have more than one grammar to recompile, just list all the names separated by commas.

Automatically rebuilding during development using "make"

Alternatively, if your module uses "ExtUtils::MakeMaker", you can have "make" automatically rebuild your "Grammar" class if your ".pgx" file is updated.

Simply add this at the bottom of your "Makefile.PL":

    sub MY::postamble {
      <<EOF;
    lib/MyThing/Grammar.pm : share/expr.pgx
    \t\$(PERL) -Ilib -MMyThing::Grammar=compile
    EOF
    }