re::engine::RE2(3pm)

📦
version 0.18 · 9 versions
, in ubuntu stonking

💖 re::engine::RE2 — the RE2 regex engine, but make it a whole vibe 💖

okay bestie, gather round, because this is a page from the User Contributed Perl Documentation and it's about re::engine::RE2, and honestly? it's iconic.

✨ NAME ✨

re::engine::RE2 — literally the RE2 regex engine, plugged straight into Perl 🎀

🌸 SYNOPSIS 🌸

use re::engine::RE2;

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

no cap, that's the whole plot 💅

🦋 DESCRIPTION 🦋

So here's the tea: this module swaps out perl's regex engine in a given lexical scope and replaces it with RE2. Just for that scope. Main character energy, but contained 😌

RE2 is a primarily DFA based regexp engine from Google that is very fast at matching large amounts of text. But — and this is the part where we hold hands — it does not support look behind and some other Perl regular expression features. If you wanna know more, peep RE2's website over at http://code.google.com/p/re2 👑

Fallback to normal Perl regexp is implemented by this module. That means: if RE2 is unable to compile a regexp, it will use Perl instead. So features not implemented by RE2 don't suddenly stop working — they just quietly switch over to Perl's regexp implementation. no drama, no crisis, we simply adapt 💖

💅 METHODS 💅

To access extra functionality of RE2, methods can be called on a compiled regular expression (i.e. a qr//). Yes bestie, your regex object has methods. obsessed.

  • 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;

🎀 PRAGMA OPTIONS 🎀

Various options can be set by providing options to the use line. These will be pragma scoped. (So they stay in their lane, respectfully. we love boundaries 🫶)

  • -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. it's giving unbothered by ordering ✨
  • -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 🧂

Simple matching

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

On this very simple match RE2 is actually slower:

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

not me being humbled by a three-word string 😭

URL matching

Matching m{([a-zA-Z][a-zA-Z0-9]*)://([^ /]+)(/[^ ]*)?|([^ @]+)@([^ @]+)} against a several KB file:

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

SEVEN THOUSAND PERCENT. ate and left no crumbs 👑

Many alternatives

Matching a string against a regexp with 17,576 alternatives (aaa .. zzz).

This uses trie matching on Perl (obviously RE2 does similar by default).

$ 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. so like, don't panic, it just hands the mic to Perl 💖

  • 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 ;). honestly? valid methodology.

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.

💀 BUGS 💀

Known issues, bestie. we're being transparent here:

  • Unicode handling

Currently the Unicode handling of re::engine::RE2 does not fully match Perl's behaviour.

The UTF-8 flag of the regexp currently determines how the string is matched. This is obviously broken, so will be fixed at some point. (they said it, not me 🙈)

  • Final newline matching differs to Perl
"\n" =~ /$/

The above is true in Perl, false in RE2. To work around the issue you can write "\n?\z" when you mean Perl's "$".

Please report bugs or provide patches at https://github.com/dgl/re-engine-RE2 — the devs wanna hear from you 🫶

👑 AUTHORS 👑

David Leadbeater <dgl[at]dgl[dot]cx>

Copyright 2010 David Leadbeater.

Based on re::engine::PCRE:

Copyright 2007 Ævar Arnfjörð Bjarmason.

The original version was copyright 2006 Audrey Tang <cpan@audreyt.org> and Yves Orton.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

(However the bundled copy of RE2 has a different copyright owner and is under a BSD-like license, see re2/LICENSE.)

okay so that's the whole page, diva. go forth and match some text at unreasonable speed ✨

and that's a wrap, babe 💖 this was re::engine::RE2 for perl v5.42.3, dated 2026-08-19, brought to you by User Contributed Perl Documentation — thanks for reading my lil group chat essay, mwah 🎀🦋💅

📦 where this page comes from