1re::engine::RE2(3)    User Contributed Perl Documentation   re::engine::RE2(3)
2
3
4

NAME

6       re::engine::RE2 - RE2 regex engine
7

SYNOPSIS

9           use re::engine::RE2;
10
11           if ("Hello, world" =~ /Hello, (world)/) {
12               print "Greetings, $1!";
13           }
14

DESCRIPTION

16       This module replaces perl's regex engine in a given lexical scope with
17       RE2.
18
19       RE2 is a primarily DFA based regexp engine from Google that is very
20       fast at matching large amounts of text. However it does not support
21       look behind and some other Perl regular expression features. See RE2's
22       website <http://code.google.com/p/re2> for more information.
23
24       Fallback to normal Perl regexp is implemented by this module. If RE2 is
25       unable to compile a regexp it will use Perl instead, therefore features
26       not implemented by RE2 don't suddenly stop working, they will just use
27       Perl's regexp implementation.
28

METHODS

30       To access extra functionality of RE2 methods can be called on a
31       compiled regular expression (i.e. a "qr//").
32
33       •   "possible_match_range([length = 10])"
34
35           Returns an array of two strings: where the expression will start
36           matching and just after where it will finish matching. See RE2's
37           documentation on PossibleMatchRange for further details.
38
39           Example:
40
41               my($min, $max) = qr/^(a|b)/->possible_match_range;
42               is $min, 'a';
43               is $max, 'c';'
44
45       •   named_captures()
46
47           Returns a hash of the name captures and index.
48
49           Example:
50
51               my $named_captures = qr/(?P<a>\w+) (?P<d>\w+)/->named_captures;
52               is $named_captures->{a}, 1;
53               is $named_captures->{d}, 2;
54
55       •   number_of_capture_groups()
56
57           Return number of capture groups
58
59           Example:
60
61               my $captures = qr/(Hello), (world)/->number_of_capture_groups;
62               is $captures, 2;
63

PRAGMA OPTIONS

65       Various options can be set by providing options to the "use" line.
66       These will be pragma scoped.
67
68       •   "-max_mem => 1<<24"
69
70           Configure RE2's memory limit.
71
72       •   "-strict => 1"
73
74           Be strict, i.e. don't allow regexps that are not supported by RE2.
75
76       •   "-longest_match => 1"
77
78           Match on the longest match in alternations. For example with this
79           option set matching "abc" against "(a|abc)" will match "abc",
80           without depending on order.
81
82       •   "-never_nl => 1"
83
84           Never match a newline ("\n") even if the provided regexp contains
85           it.
86

PERFORMANCE

88       Performance is really the primary reason for using RE2, so here's some
89       benchmarks. Like any benchmark take them with a pinch of salt.
90
91   Simple matching
92         my $foo = "foo bar baz";
93         $foo =~ /foo/;
94         $foo =~ /foox/;
95
96       On this very simple match RE2 is actually slower:
97
98                  Rate  re2   re
99         re2  674634/s   -- -76%
100         re  2765739/s 310%   --
101
102   URL matching
103       Matching "m{([a-zA-Z][a-zA-Z0-9]*)://([^ /]+)(/[^ ]*)?|([^ @]+)@([^
104       @]+)}" against a several KB file:
105
106               Rate    re   re2
107         re  35.2/s    --  -99%
108         re2 2511/s 7037%    --
109
110   Many alternatives
111       Matching a string against a regexp with 17,576 alternatives ("aaa ..
112       zzz").
113
114       This uses trie matching on Perl (obviously RE2 does similar by
115       default).
116
117         $ perl misc/altern.pl
118                 Rate   re  re2
119         re   52631/s   -- -91%
120         re2 554938/s 954%   --
121

NOTES

123       •   No support for "m//x"
124
125           The "/x" modifier is not supported. (There's no particular reason
126           for this, just RE2 itself doesn't support it). Fallback to Perl
127           regexp will happen automatically if "//x" is used.
128
129       •   "re2/dfa.cc:447: DFA out of memory: prog size xxx mem yyy"
130
131           If you attempt to compile a really large regular expression you may
132           get this error. RE2 has an internal limit on memory consumption for
133           the DFA state tables. By default this is 8 MiB.
134
135           If you need to increase this size then use the max_mem parameter:
136
137             use re::engine::RE2 -max_mem => 8<<23; # 64MiB
138
139       •   How do I tell if RE2 will be used?
140
141           See if your regexp is matching quickly or slowly ;).
142
143           Alternatively normal OO concepts apply and you may examine the
144           object returned by "qr//":
145
146             use re::engine::RE2;
147
148             ok qr/foo/->isa("re::engine::RE2");
149
150             # Perl Regexp used instead
151             ok not qr/(?<=foo)bar/->isa("re::engine::RE2");
152
153           If you wish to force RE2, use the "-strict" option.
154

BUGS

156       Known issues:
157
158       •   Unicode handling
159
160           Currently the Unicode handling of re::engine::RE2 does not fully
161           match Perl's behaviour.
162
163           The UTF-8 flag of the regexp currently determines how the string is
164           matched.  This is obviously broken, so will be fixed at some point.
165
166       •   Final newline matching differs to Perl
167
168             "\n" =~ /$/
169
170           The above is true in Perl, false in RE2. To work around the issue
171           you can write "\n?\z" when you mean Perl's "$".
172
173       Please report bugs or provide patches at
174       <https://github.com/dgl/re-engine-RE2>.
175

AUTHORS

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

180       Copyright 2010 David Leadbeater.
181
182       Based on re::engine::PCRE:
183
184       Copyright 2007 Ævar Arnfjörð Bjarmason.
185
186       The original version was copyright 2006 Audrey Tang <cpan@audreyt.org>
187       and Yves Orton.
188
189       This program is free software; you can redistribute it and/or modify it
190       under the same terms as Perl itself.
191
192       (However the bundled copy of RE2 has a different copyright owner and is
193       under a BSD-like license, see re2/LICENSE.)
194
195
196
197perl v5.36.1                      2023-06-19                re::engine::RE2(3)
Impressum