NAME
    Pugs::Compiler::Rule - Compiler for Perl 6 Rules

SYNOPSIS
    Un-named rules are objects:

        use Pugs::Compiler::Rule;

        my $rule = Pugs::Compiler::Rule->compile( '((.).).' );
        my $match = $rule->match( 'abc' );

        if ($match) {               # true
            print $match;           # "abc"
            print $match->from;     # 0
            print $match->to;       # 3
            print $match->[0];      # "ab"
            print $match->[0][0];   # "a"
        }

    Named rules are methods in a Grammar:

        package MyGrammar;
        use Pugs::Compiler::Rule;
        use base 'Pugs::Grammar::Base';

        Pugs::Compiler::Rule->install( rule => '((.).).' );
        my $match = MyGrammar->rule( 'abc' );

    Rules may have parameters:

        $grammar->install(subrule => $source, { signature => $sig } );

        $grammar->install(rule => q{
                <subrule: param1, param2>
        });

DESCRIPTION
    This module provides an implementation for Perl 6 Rules. It is a
    front-end to several other modules:

    Front-end Modules

    *   Pugs::Compiler::Rule compiles Perl 6 Rules to Perl 5.

    *   Pugs::Compiler::Token compiles Perl 6 Tokens to Perl 5.

    *   Pugs::Compiler::Regex compiles Perl 6 Regexes to Perl 5.

    *   Pugs::Compiler::RegexPerl5 wraps Perl 5 Regexes to return a Match
        object.

    Runtime Classes

    *   Pugs::Runtime::Rule provides the runtime engine for Rules.

    *   Pugs::Runtime::Match represents a Match object.

    *   Pugs::Runtime::Grammar represents a Grammar class / object.

    Grammars

    *   Pugs::Grammar::Rule parses the Rules syntax.

    *   Pugs::Grammar::Base is the base Grammar: <ws>, <space>.

    Code Emitters

    *   Pugs::Emitter::Rule::Perl5 converts parsed Rules to Perl 5 code.

    *   Pugs::Emitter::Rule::Perl5::Ratchet converts parsed :ratchet Rules
        to Perl 5 code.

METHODS
    compile (Str $rule_source, \%options)
        Class method. Returns a compiled rule object, or throws an exception
        on invalid rule syntax.

        options:

        *   grammar => $class

            Specify which namespace (Grammar) the rule belongs to.

        *   ratchet => 1

            Disable backtracking. Match faster. Defaults to 1 in Rules and
            Tokens.

        *   pos => $pos

            Specify a string position to match. Starts in zero. Defaults to
            "undef", which matches anywhere in the string.

        *   sigspace => 1

            Whitespace is significant. Defaults to 1 in Rules.

        *   Perl5 => 1

            Use Perl 5 grammar and semantics for Regex.

    match (Str $match_against)
        Instance method. Returns a Pugs::Runtime::Match object.

    install (Str $name, Str $rule_source, \%options)
        Install a rule into the method $name. If $name is fully qualified
        then it will be installed into that path e.g "MyGrammar::rulename",
        otherwise it will install it into the current package.

    perl
        Instance method. Returns a string that can be eval'ed into a
        rule/token/regex object.

CAVEATS
    This is an experimental development version. The API is still in flux.

    The set of implemented features depends on the "ratchet" switch.

AUTHORS
    The Pugs Team "<perl6-compiler@perl.org>".

    Please join us on irc.freenode.net #perl6 if you'd like to participate.

SEE ALSO
    The Perl 6 Rules Spec:
    <http://dev.perl.org/perl6/doc/design/syn/S05.html>

COPYRIGHT
    Copyright 2006 by Flavio Soibelmann Glock and others.

    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>