1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
NAME
re::engine::RE2 - RE2 regex engine
SYNOPSIS
use re::engine::RE2;
if ("Hello, world" =~ /Hello, (world)/) {
print "Greetings, $1!";
}
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 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;
PRAGMA 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.
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% --
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% --
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.
* "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.
BUGS
Known issues:
* 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.
* 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>.
AUTHORS
David Leadbeater <dgl[at]dgl[dot]cx>
COPYRIGHT
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.)
|
