re::engine::RE23pm

Usage

    use re::engine::RE2;
    if ("Hello, world" =~ /Hello, (world)/) {
        print "Greetings, $1!";
    }

Overview

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 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.

Methods

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

•

"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';'

•

named_captures()

Returns a hash of the name captures and index.

Example:

    my $named_captures = qr/(?P<a>\w+) (?P<d>\w+)/->named_captures;
    is $named_captures->{a}, 1;
    is $named_captures->{d}, 2;

•

number_of_capture_groups()

Return number of capture groups

Example:

    my $captures = qr/(Hello), (world)/->number_of_capture_groups;
    is $captures, 2;

Options

Various options can be set by providing options to the "use" line. These will be pragma scoped.

•

"-max_mem => 1<<24"

Configure RE2's memory limit.

•

"-strict => 1"

Be strict, i.e. don't allow regexps that are not supported by RE2.

•

"-longest_match => 1"

Match on the longest match in alternations. For example with this option set matching "abc" against "(a|abc)" will match "abc", without depending on order.

•

"-never_nl => 1"

Never match a newline ("\n") even if the provided regexp contains it.

Performance

Performance is really the primary reason for using RE2, so here's some benchmarks. Like any benchmark take them with a pinch of salt.

  my $foo = "foo bar baz";
  $foo =~ /foo/;
  $foo =~ /foox/;

           Rate  re2   re
  re2  674634/s   -- -76%
  re  2765739/s 310%   --

        Rate    re   re2
  re  35.2/s    --  -99%
  re2 2511/s 7037%    --

  $ perl misc/altern.pl
          Rate   re  re2
  re   52631/s   -- -91%
  re2 554938/s 954%   --

Notes

•

No support for "m//x"

The "/x" modifier is not supported. (There's no particular reason for this, just RE2 itself doesn't support it). Fallback to Perl regexp will happen automatically if "//x" is used.

•

"re2/dfa.cc:447: DFA out of memory: prog size xxx mem yyy"

If you attempt to compile a really large regular expression you may get this error. RE2 has an internal limit on memory consumption for the DFA state tables. By default this is 8 MiB.

If you need to increase this size then use the max_mem parameter:

  use re::engine::RE2 -max_mem => 8<<23; # 64MiB

•

How do I tell if RE2 will be used?

See if your regexp is matching quickly or slowly ;).

Alternatively normal OO concepts apply and you may examine the object returned by "qr//":

  use re::engine::RE2;
  ok qr/foo/->isa("re::engine::RE2");
  # Perl Regexp used instead
  ok not qr/(?<=foo)bar/->isa("re::engine::RE2");

If you wish to force RE2, use the "-strict" option.