NAME

Pugs::Compiler::Regex - Compiler for Perl 6 Regex

SYNOPSIS

    use Pugs::Compiler::Regex;
    use Pugs::Runtime::Match;

    $regex = Pugs::Compiler::Regex->compile('a*b');
    $match = $regex->match('aaab');
    print $match->(), "\n";
    print $match->from, "\n";
    print $match->to, "\n";

    package MyGrammar;
    $regex = Pugs::Compiler::Regex->compile(
        'a*', { ratchet => 1, continue => 1, sigspace => 1 }
    );
    *my_match = $regex->code();
    $match = MyGrammar->my_match('aaaa');
    print "$match\n";

    package MyGrammar2;
    $regex = Pugs::Compiler::Regex->install(
        my_match => 'a*',
        { ratchet => 1, continue => 1, sigspace => 1 }
    );
    $match = MyGrammar->my_match('aaaa');
    print "$match\n";

DESCRIPTION

This class provides an implementation for Perl 6 regexes. It serves as a base class for Pugs::Compiler::Rule and Pugs::Compiler::Token.

METHODS

"$regex = Pugs::Compiler::Regex->compile($str, $params);": This method acts like a constructor, which returns a Pugs::Compiler::Regex object from the p6 regex specified in $str, or throws an exception on invalid rule syntax.
$params is an optional argument which specifies the following p6 regex modifiers:

"grammar => 'Pugs::Grammar::Base'"

Specify which namespace (Grammar) the rule belongs to. if "grammar" is not specified, then "Pugs::Grammar::Base" will be assumed.

"continue => 0"

"c => 0"

These modifiers cause the pattern to continue scanning from the string's current "pos":

Note that in Perl 6 form

    m:c/pattern/

is roughlh equivalent to

    m:p/ .*? pattern /

Here is an example:

    package Foo;
    Pugs::Compiler::Regex->install(
        word => '\w+',
        { ratchet => 1, continue => 1 }
    );
    $s = 'hello world';
    $match = Foo->word($s); # got 'hello'
    $match = Foo->word($s); # got 'world'

XXX Note that "continue" or "c" currently are not supported in non-ratchet mode.

"ratchet => 0"

Disable backtracking. Much faster. Defaults to 0. (Pugs::Compiler::Rule and Pugs::Compiler::Token have the default value of 1).

"pos => undef"

"p => undef"

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

"sigspace => 0"

Whitespace is significant. Defaults to 0 for Pugs::Compiler::Regex while 1 for Pugs::Compiler::Rule.

"ignorecase => 0"

Ignore character case. Defaults to 0 for Pugs::Compiler::Regex.

"$regex->perl5()"

"$regex->perl()"

Return a string holding the Perl 5 code for reconstructing the current Pugs::Compiler::Regex object.

We are trying to make the "perl5" method does something like serializing a Pugs::Compiler::Regex instance.

If you want the raw Perl 5 code generated by the various emitters, use "$regex->{perl5}" directly.

"$regex->match($str, $grammar, $params)"

Performs matching action on $str. Note that it's a thin wrapper around the p5 code compiled from the p6 regex with run-time modifier handling via the $params argument.

Here is an example:

    $regex = Pugs::Compiler::regex->compile('a*\w');
    my $match = $regex->match('aaa');
    print "Capture: $match";
    print "From: ", $match->from;
    print "To: ", $match->to;

"$regex->code()"

Returns a closure (or an anonymous sub) which does the actual matching task. For example:

  $regex = Pugs::Compiler::Regex->compile('a|b', { ratchet => 1 });
  my $sub = $regex->code();
  my $match = $sub->('MyGrammar', 'aaa');

Or inserts the sub into the current package:

  package Foo;
  $regex = Pugs::Compiler::Regex->compile('a*');
  *match = $regex->code();
  my $match = __PACKAGE__->match('aaa');

Technically it's a thin wrapper around the "match" method.

"$regex->install($name, @args_for_compile)"

Installs the subroutine returned from the "code" method as a named subroutine using the name specified by $name;

If $name is fully qualified, then the corresponding package is used, otherwise the current package is assumed.

@args_for_compile are those arguments fed into the "compile" method.

It will croak if there's already a sub with the same name exists. If that's not what you want, use the "reinstall" method instead.

Here are some examples:

  package Bar;
  Pugs::Compiler::Regex->install(match => 'a*', {ratchet => 1});
  $match = Bar->match('aaa');

  # The following line dies with the message
  # "Can't install regex 'match' as 'Bar::match' which already
  # exists":
  Pugs::Compiler::Regex->install(match => 'b*');

"$regex->reinstall($name, @args_for_compile)"

Like the "install" method but it can replaces the named sub if it already exists:

  package Bar;
  Pugs::Compiler::Regex->install('match', 'a*', {ratchet => 1});
  Pugs::Compiler::Regex->reinstall('match', 'b*');
  };
  $match = Bar->match('bbb'); # matched here

PACKAGE VARIABLES

$Pugs::Compiler::Regex::NoCache: By default, the "compile" method will cache the compiled form (p5 source) of the p6 regex. The "NoCache" variable prevents any caching.

AUTHORS

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

COPYRIGHT

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>