view release on metacpan or  search on metacpan

lib/re/engine/RE2.pm  view on Meta::CPAN

package re::engine::RE2;
use 5.020;

BEGIN {
  $re::engine::RE2::VERSION = "0.18";
}

use XSLoader ();

# All engines should subclass the core Regexp package
our @ISA = 'Regexp';

BEGIN
{
    XSLoader::load __PACKAGE__, $re::engine::RE2::VERSION;
}

sub import
{
    my $class = shift;

    $^H{regcomp} = ENGINE;

    if (@_) {
        my %args = @_;
        if (exists $args{"-max_mem"}) {
            $^H{__PACKAGE__ . "::max-mem"} = $args{"-max_mem"};
        }

        if (exists $args{"-strict"}) {
            $^H{__PACKAGE__ . "::strict"} = $args{"-strict"};
        }

        if (exists $args{"-longest_match"}) {
            $^H{__PACKAGE__ . "::longest-match"} = $args{"-longest_match"};
        }

        if (exists $args{"-never_nl"}) {
            $^H{__PACKAGE__ . "::never-nl"} = $args{"-never_nl"};
        }
    }
}

sub unimport
{
    delete $^H{regcomp}
        if $^H{regcomp} == ENGINE;
}

1;

__END__

=encoding utf8

=head1 NAME

re::engine::RE2 - RE2 regex engine

=head1 SYNOPSIS

    use re::engine::RE2;

    if ("Hello, world" =~ /Hello, (world)/) {
        print "Greetings, $1!";
    }

=head1 DESCRIPTION

This module replaces perl's regex engine in a given lexical scope with RE2.

RE2 is a primarily DFA based regexp engine from Google that is very fast at
matching large amounts of text. However it does not support look behind and
some other Perl regular expression features. See
L<RE2's website|http://code.google.com/p/re2> for more information.

Fallback to normal Perl regexp is implemented by this module. If RE2 is unable
to compile a regexp it will use Perl instead, therefore features not
implemented by RE2 don't suddenly stop working, they will just use Perl's
regexp implementation.

=head1 METHODS

To access extra functionality of RE2 methods can be called on a compiled
regular expression (i.e. a C<qr//>).

=over 4

=item * C<possible_match_range([length = 10])>

Returns an array of two strings: where the expression will start matching and
just after where it will finish matching. See RE2's documentation on
PossibleMatchRange for further details.

Example:

    my($min, $max) = qr/^(a|b)/->possible_match_range;
    is $min, 'a';
    is $max, 'c';'