NAME

       Parser::MGC::Tutorial

INTRODUCTION

       Parser::MGC is an abstract base class that provides useful features to assist writing a parser.

       A parser written using this module will be a subclass of "Parser::MGC", which provides a "parse" method.
       For example, the following trivial parser accepts only input content matching the given regexp.

        package ExampleParser;
        use base qw( Parser::MGC );

        sub parse
        {
           my $self = shift;

           $self->expect( qr/hello world/i );

           return 1;
        }

       A program using this parser constructs an instance of it, and uses this instance to parse content.
       Content is passed either as string value to the "from_string" method, or from a named file or filehandle
       to the "from_file" method.

        use feature qw( say );
        use ExampleParser;

        my $parser = ExampleParser->new;

        say $parser->from_string( "Hello World" );

       When run, this program outputs the return value of the "from_string" method, which itself is the value
       returned by the "parse" method.

        $ perl tut01.pl
        1

       Content can also be provided by "from_file" instead:

        use feature qw( say );
        use ExampleParser;

        my $parser = ExampleParser->new;

        say $parser->from_file( \*STDIN );

   Returning Values
       Of course, a parser that simply returns 1 to say it matches may not be all that useful. Almost always
       when a parser is being used to match some input, it is because some values or structure are needed from
       this input, which should be returned to the caller.

       The "expect" method attempts to match the next part of the input string with the given regexp, and
       returns the matching substring. A subsequent "expect" call will continue parsing where the previous one
       finished. "Parser::MGC" will automatically skip over whitespace between these calls, so most grammars
       that are whitespace-insensitive should not need to worry about this explicitly.

       By using two "expect" calls, a parser can first examine that some given literal is present, and then
       return a matched substring from the input.

        sub parse
        {
           my $self = shift;

           $self->expect( qr/hello/i );
           my $name = $self->expect( qr/\w+/ );

           return $name;
        }

        say $parser->from_string( "Hello World" );

        $ perl tut02.pl
        World

       Token methods make this easier by providing convenient shortcuts to commonly-used matching patterns.

        sub parse
        {
           my $self = shift;

           $self->expect( qr/hello/i );
           return $self->token_ident;
        }

       If instead we pass in a value that does not match the regexp, an exception is thrown, including details
       of how the parse failed.

        say $parser->from_string( "Hello, world!" );

        $ perl tut03.pl
        Expected (?i-xsm:hello world) on line 1 at:
        Hello, world!
        ^

       A typical use of a parser is to form an Abstract Syntax Tree (AST) from a given input. In this case it is
       likely that the return value from the parse method will be some object the application can use to inspect
       the syntax.

        sub parse
        {
           my $self = shift;

           my $num = $self->token_number;
           return MyGrammar::Expression::Number->new( $num );
        }

   Indicating Failure
       While the basic methods such as "expect" and the various token methods will indicate a failure
       automatically, there may be cases in the grammar that more logic is required by the parser. If this logic
       wishes to indicate a failure in the input and cause back-tracking to occur, it can use the "fail" method.

        sub parse
        {
           my $self = shift;

           my $num = $self->token_number;
           $num >= 0 or $self->fail( "Expected a non-negative number" );

           return $num;
        }

STRUCTURE

       So far we've managed to parse simple patterns that could have been specified with a simple regular
       expression. Any parser for a nontrivial grammar will need other abilities as well; it will need to be
       able to choose from a list of alternatives, to be able to repeat patterns, and to form nested scopes to
       match other content within.

       "Parser::MGC" provides a set of methods that take one or more "CODE" references that perform some parsing
       step, and form a higher-level construction out of them. These can be used to build more complex parsers
       out of simple ones. It is this recursive structure that gives "Parser::MGC" its main power over simple
       one-shot regexp matching.

       Any nontrivial grammar is likely to be formed from multiple named rules. It is natural therefore to split
       the parser for such a grammar into methods whose names reflect the structure of the grammar to be parsed.
       Each of the structure-forming methods which takes "CODE" references invokes each by passing in the parser
       object itself as the first argument. This makes it simple to invoke sub-rules by passing references to
       method subs themselves, because the parser object will already be passed as the invocant.

       The following examples will build together into a parser for a simple C-like expression language.

   Optional Rules
       The simplest of the structure-forming methods, "maybe", attempts to run the parser step it is given and
       if it succeeds, returns the value returned by that step. If it fails by throwing an exception, then the
       "maybe" call simply returns "undef" and resets the current parse position back to where it was before it
       started. This allows writing a grammar that includes an optional element, similar to the "?" quantifier
       in a regular expression.

        sub parse_type
        {
           my $self = shift;

           my $storage = $self->maybe( sub {
              $self->token_kw(qw( static auto typedef ));
           } );

           return MyGrammar::Type->new( $self->parse_ident, $storage );
        }

   Repeated Rules
       The next structure-forming method, "sequence_of", attempts to run the parser step it is given multiple
       times until it fails, and returns an "ARRAY" reference collecting up all the return values from each
       iteration that succeeded. By itself, "sequence_of" can never fail; if the body never matches then it just
       yields an empty array and consumes nothing from the input. This allows writing a grammar that includes a
       repeating element, similar to the "*" quantifier in a regular expression.

        sub parse_statements
        {
           my $self = shift;

           my $statements = $self->sequence_of( sub {
              $self->parse_statement;
           } );

           return MyGrammar::Statements->new( $statements );
        }

       Often it is the case that the grammar requires at least one item to be present, and should not accept an
       empty parse of zero elements. This can be achieved in code by testing the size of the returned array, and
       using the "fail" method. This could be considered similar to the "+" quantifier in a regular expression.

        sub parse_statements
        {
           my $self = shift;

           my $statements = $self->sequence_of( sub {
              $self->parse_statement;
           } );

           @$statements > 0 or $self->fail( "Expected at least one statement" );

           return MyGrammar::Statements->new( $statements );
        }

       Another case that often happens it that the grammar requires some simple separation pattern between each
       parsed item, such as a comma. The "list_of" method helps here because it automatically handles those
       separating patterns between the items, returning a reference to an array containing only the actual
       parsed items without the separators.

        sub parse_expression_list
        {
           my $self = shift;

           my $exprs = $self->list_of( ",", sub {
              $self->parse_expression;
           } );

           return MyGrammar::ExpressionList->new( $exprs );
        }

   Alternate Rules
       To handle a choice of multiple different alternatives in the grammar, the "any_of" method takes an
       ordered list of parser steps, and attempts to invoke each in turn. It yields as its result the result of
       the first one of these that didn't fail. This allows writing a grammar that allows a choice of multiple
       different rules at some point, similar to the "|" alternation in a regular expression.

        sub parse_statement
        {
           my $self = shift;

           $self->any_of(
              sub { $self->parse_declaration },
              sub { $self->parse_expression; $self->expect( ';' ); },
              sub { $self->parse_block_statement },
           );
        }

   Scoping Rules
       The final structure-forming method has no direct analogy to a regular expression, though usually similar
       structures can be found. To handle the case where some nested structure has to be handled between opening
       and closing markers, the "scope_of" method can be used. It takes three arguments, being the opening
       marker, a parser step to handle the contents of the body, and the closing marker. It expects to find each
       of these in sequence, and returns the value that the inner parsing step returned.

       However, what makes it more interesting is that during execution of the inner parsing step, the basic
       token functions all take into account the closing marker. No token function will return a result if the
       stream now looks like the scope closing marker. Instead, they'll all fail claiming to be at the end of
       the scope. This makes it much simpler to parse, for example, lists of values surrounded by braces.

        sub parse_array_initialiser
        {
           my $self = shift;

           $self->scope_of( "{", sub { $self->parse_expression_list }, "}" );
        }

       During execution of the inner call to "parse_expression_list", any occurence in the stream of the "}"
       marker will appear to be the end of the stream, causing the inner call to stop at hopefully the right
       place (barring other syntax errors), and terminating correctly.