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

VERSION
    This document describes Pugs::Compiler::Rule 0.28 released on 31 Oct,
    2007.

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>
        });

    where $grammar is normally a Perl 5 package.

DESCRIPTION
    This module provides an pure Perl 5 implementation for Perl 6 regexes,
    which does not depend on the Haskell Pugs.

    It is a front-end to several other modules:

    Front-end Modules

    * Pugs::Compiler::Grammar compiles Perl 6 grammars to Perl 5.
    * 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.
    * Pugs::Emitter::Grammar::Perl5 converts parsed grammars to Perl 5 code.

INHERITANCE
      Pugs::Compiler::Rule
         isa Pugs::Compiler::Regex

METHODS
    This class (i.e. Pugs::Compiler::Rule) is a subclass of
    Pugs::Compiler::Regex and thus owns all the methods of its base class.
    See Pugs::Compiler::Regex for the detailed docs.

    "$rule = Pugs::Compiler::Rule->compile($p6_regex, $params)"
        Specifically, this class overrides the "compile" method of
        Pugs::Compiler::Regex which resets the following options' default
        values:

        "ratchet => 1"
            Here is an example:

                $rule = Pugs::Compiler::Rule->compile(
                    'a*\w',
                );
                my $match = $rule->match('aaa');
                # $match->bool is false since no backtracking
                # happened

        "sigspace => 1"
            Here is an example:

                my $rule = Pugs::Compiler::Rule->compile(
                    'a b',
                );
                my $match = $rule->match('a     b');
                ok $match->bool, 'sigspace works';
                is $match->(), 'a     b', 'sigspace works (2)';

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

    The set of implemented features depend 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
    *   Pugs::Compiler::Regex

    *   Pugs::Compiler::Grammar

    *   compile_p6grammar.pl

    *   The Perl 6 Rules Spec: <http://perlcabal.org/syn/S05.html>

COPYRIGHT
    Copyright 2006, 2007 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>