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

PRAGMA OPTIONS

46       Various options can be set by providing options to the "use" line.
47       These will be pragma scoped.
48
49       ·   "-max_mem => 1<<24"
50
51           Configure RE2's memory limit.
52
53       ·   "-strict => 1"
54
55           Be strict, i.e. don't allow regexps that are not supported by RE2.
56
57       ·   "-longest_match => 1"
58
59           Match on the longest match in alternations. For example with this
60           option set matching "abc" against "(a|abc)" will match "abc",
61           without depending on order.
62
63       ·   "-never_nl => 1"
64
65           Never match a newline ("\n") even if the provided regexp contains
66           it.
67

PERFORMANCE

69       Performance is really the primary reason for using RE2, so here's some
70       benchmarks. Like any benchmark take them with a pinch of salt.
71
72   Simple matching
73         my $foo = "foo bar baz";
74         $foo =~ /foo/;
75         $foo =~ /foox/;
76
77       On this very simple match RE2 is actually slower:
78
79                  Rate  re2   re
80         re2  674634/s   -- -76%
81         re  2765739/s 310%   --
82
83   URL matching
84       Matching "m{([a-zA-Z][a-zA-Z0-9]*)://([^ /]+)(/[^ ]*)?|([^ @]+)@([^
85       @]+)}" against a several KB file:
86
87               Rate    re   re2
88         re  35.2/s    --  -99%
89         re2 2511/s 7037%    --
90
91   Many alternatives
92       Matching a string against a regexp with 17,576 alternatives ("aaa ..
93       zzz").
94
95       This uses trie matching on Perl (obviously RE2 does similar by
96       default).
97
98         $ perl misc/altern.pl
99                 Rate   re  re2
100         re   52631/s   -- -91%
101         re2 554938/s 954%   --
102

NOTES

104       ·   No support for "m//x"
105
106           The "/x" modifier is not supported. (There's no particular reason
107           for this, just RE2 itself doesn't support it). Fallback to Perl
108           regexp will happen automatically if "//x" is used.
109
110       ·   "re2/dfa.cc:447: DFA out of memory: prog size xxx mem yyy"
111
112           If you attempt to compile a really large regular expression you may
113           get this error. RE2 has an internal limit on memory consumption for
114           the DFA state tables. By default this is 8 MiB.
115
116           If you need to increase this size then use the max_mem parameter:
117
118             use re::engine::RE2 -max_mem => 8<<23; # 64MiB
119
120       ·   How do I tell if RE2 will be used?
121
122           See if your regexp is matching quickly or slowly ;).
123
124           Alternatively normal OO concepts apply and you may examine the
125           object returned by "qr//":
126
127             use re::engine::RE2;
128
129             ok qr/foo/->isa("re::engine::RE2");
130
131             # Perl Regexp used instead
132             ok not qr/(?<=foo)bar/->isa("re::engine::RE2");
133
134           If you wish to force RE2, use the "-strict" option.
135

BUGS

137       Known issues:
138
139       ·   Unicode handling
140
141           Currently the Unicode handling of re::engine::RE2 does not fully
142           match Perl's behaviour.
143
144           The UTF-8 flag of the regexp currently determines how the string is
145           matched.  This is obviously broken, so will be fixed at some point.
146
147       ·   Final newline matching differs to Perl
148
149             "\n" =~ /$/
150
151           The above is true in Perl, false in RE2. To work around the issue
152           you can write "\n?\z" when you mean Perl's "$".
153
154       Please report bugs via RT in the normal way. (Or a patch at
155       <https://github.com/dgl/re-engine-RE2> would be most welcome.)
156

AUTHORS

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

161       Copyright 2010 David Leadbeater.
162
163       Based on re::engine::PCRE:
164
165       Copyright 2007 Ævar Arnfjörð Bjarmason.
166
167       The original version was copyright 2006 Audrey Tang <cpan@audreyt.org>
168       and Yves Orton.
169
170       This program is free software; you can redistribute it and/or modify it
171       under the same terms as Perl itself.
172
173       (However the bundled copy of RE2 has a different copyright owner and is
174       under a BSD-like license, see re2/LICENSE.)
175
176
177
178perl v5.28.0                      2015-01-18                re::engine::RE2(3)
Impressum