| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PERLRE 1" |
| 58 |
.TH PERLRE 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perlre \- Perl regular expressions |
| 65 |
.IX Xref "regular expression regex regexp" |
| 66 |
.SH DESCRIPTION |
| 67 |
.IX Header "DESCRIPTION" |
| 68 |
This page describes the syntax of regular expressions in Perl. |
| 69 |
.PP |
| 70 |
If you haven't used regular expressions before, a tutorial introduction |
| 71 |
is available in perlretut. If you know just a little about them, |
| 72 |
a quick-start introduction is available in perlrequick. |
| 73 |
.PP |
| 74 |
Except for "The Basics" section, this page assumes you are familiar |
| 75 |
with regular expression basics, like what is a "pattern", what does it |
| 76 |
look like, and how it is basically used. For a reference on how they |
| 77 |
are used, plus various examples of the same, see discussions of \f(CW\*(C`m//\*(C'\fR, |
| 78 |
\&\f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`qr//\*(C'\fR and \f(CW"??"\fR in "Regexp Quote-Like Operators" in perlop. |
| 79 |
.PP |
| 80 |
New in v5.22, \f(CW\*(C`use re \*(Aqstrict\*(Aq\*(C'\fR applies stricter |
| 81 |
rules than otherwise when compiling regular expression patterns. It can |
| 82 |
find things that, while legal, may not be what you intended. |
| 83 |
.SS "The Basics" |
| 84 |
.IX Xref "regular expression, version 8 regex, version 8 regexp, version 8" |
| 85 |
.IX Subsection "The Basics" |
| 86 |
Regular expressions are strings with the very particular syntax and |
| 87 |
meaning described in this document and auxiliary documents referred to |
| 88 |
by this one. The strings are called "patterns". Patterns are used to |
| 89 |
determine if some other string, called the "target", has (or doesn't |
| 90 |
have) the characteristics specified by the pattern. We call this |
| 91 |
"matching" the target string against the pattern. Usually the match is |
| 92 |
done by having the target be the first operand, and the pattern be the |
| 93 |
second operand, of one of the two binary operators \f(CW\*(C`=~\*(C'\fR and \f(CW\*(C`!~\*(C'\fR, |
| 94 |
listed in "Binding Operators" in perlop; and the pattern will have been |
| 95 |
converted from an ordinary string by one of the operators in |
| 96 |
"Regexp Quote-Like Operators" in perlop, like so: |
| 97 |
.PP |
| 98 |
.Vb 1 |
| 99 |
\& $foo =~ m/abc/ |
| 100 |
.Ve |
| 101 |
.PP |
| 102 |
This evaluates to true if and only if the string in the variable \f(CW$foo\fR |
| 103 |
contains somewhere in it, the sequence of characters "a", "b", then "c". |
| 104 |
(The \f(CW\*(C`=~ m\*(C'\fR, or match operator, is described in |
| 105 |
"m/PATTERN/msixpodualngc" in perlop.) |
| 106 |
.PP |
| 107 |
Patterns that aren't already stored in some variable must be delimited, |
| 108 |
at both ends, by delimiter characters. These are often, as in the |
| 109 |
example above, forward slashes, and the typical way a pattern is written |
| 110 |
in documentation is with those slashes. In most cases, the delimiter |
| 111 |
is the same character, fore and aft, but there are a few cases where a |
| 112 |
character looks like it has a mirror-image mate, where the opening |
| 113 |
version is the beginning delimiter, and the closing one is the ending |
| 114 |
delimiter, like |
| 115 |
.PP |
| 116 |
.Vb 1 |
| 117 |
\& $foo =~ m<abc> |
| 118 |
.Ve |
| 119 |
.PP |
| 120 |
Most times, the pattern is evaluated in double-quotish context, but it |
| 121 |
is possible to choose delimiters to force single-quotish, like |
| 122 |
.PP |
| 123 |
.Vb 1 |
| 124 |
\& $foo =~ m\*(Aqabc\*(Aq |
| 125 |
.Ve |
| 126 |
.PP |
| 127 |
If the pattern contains its delimiter within it, that delimiter must be |
| 128 |
escaped. Prefixing it with a backslash (\fIe.g.\fR, \f(CW"/foo\e/bar/"\fR) |
| 129 |
serves this purpose. |
| 130 |
.PP |
| 131 |
Any single character in a pattern matches that same character in the |
| 132 |
target string, unless the character is a \fImetacharacter\fR with a special |
| 133 |
meaning described in this document. A sequence of non-metacharacters |
| 134 |
matches the same sequence in the target string, as we saw above with |
| 135 |
\&\f(CW\*(C`m/abc/\*(C'\fR. |
| 136 |
.PP |
| 137 |
Only a few characters (all of them being ASCII punctuation characters) |
| 138 |
are metacharacters. The most commonly used one is a dot \f(CW"."\fR, which |
| 139 |
normally matches almost any character (including a dot itself). |
| 140 |
.PP |
| 141 |
You can cause characters that normally function as metacharacters to be |
| 142 |
interpreted literally by prefixing them with a \f(CW"\e"\fR, just like the |
| 143 |
pattern's delimiter must be escaped if it also occurs within the |
| 144 |
pattern. Thus, \f(CW"\e."\fR matches just a literal dot, \f(CW"."\fR instead of |
| 145 |
its normal meaning. This means that the backslash is also a |
| 146 |
metacharacter, so \f(CW"\e\e"\fR matches a single \f(CW"\e"\fR. And a sequence that |
| 147 |
contains an escaped metacharacter matches the same sequence (but without |
| 148 |
the escape) in the target string. So, the pattern \f(CW\*(C`/blur\e\efl/\*(C'\fR would |
| 149 |
match any target string that contains the sequence \f(CW"blur\efl"\fR. |
| 150 |
.PP |
| 151 |
The metacharacter \f(CW"|"\fR is used to match one thing or another. Thus |
| 152 |
.PP |
| 153 |
.Vb 1 |
| 154 |
\& $foo =~ m/this|that/ |
| 155 |
.Ve |
| 156 |
.PP |
| 157 |
is TRUE if and only if \f(CW$foo\fR contains either the sequence \f(CW"this"\fR or |
| 158 |
the sequence \f(CW"that"\fR. Like all metacharacters, prefixing the \f(CW"|"\fR |
| 159 |
with a backslash makes it match the plain punctuation character; in its |
| 160 |
case, the VERTICAL LINE. |
| 161 |
.PP |
| 162 |
.Vb 1 |
| 163 |
\& $foo =~ m/this\e|that/ |
| 164 |
.Ve |
| 165 |
.PP |
| 166 |
is TRUE if and only if \f(CW$foo\fR contains the sequence \f(CW"this|that"\fR. |
| 167 |
.PP |
| 168 |
You aren't limited to just a single \f(CW"|"\fR. |
| 169 |
.PP |
| 170 |
.Vb 1 |
| 171 |
\& $foo =~ m/fee|fie|foe|fum/ |
| 172 |
.Ve |
| 173 |
.PP |
| 174 |
is TRUE if and only if \f(CW$foo\fR contains any of those 4 sequences from |
| 175 |
the children's story "Jack and the Beanstalk". |
| 176 |
.PP |
| 177 |
As you can see, the \f(CW"|"\fR binds less tightly than a sequence of |
| 178 |
ordinary characters. We can override this by using the grouping |
| 179 |
metacharacters, the parentheses \f(CW"("\fR and \f(CW")"\fR. |
| 180 |
.PP |
| 181 |
.Vb 1 |
| 182 |
\& $foo =~ m/th(is|at) thing/ |
| 183 |
.Ve |
| 184 |
.PP |
| 185 |
is TRUE if and only if \f(CW$foo\fR contains either the sequence \f(CW"this\ thing"\fR or the sequence \f(CW"that\ thing"\fR. The portions of the string |
| 186 |
that match the portions of the pattern enclosed in parentheses are |
| 187 |
normally made available separately for use later in the pattern, |
| 188 |
substitution, or program. This is called "capturing", and it can get |
| 189 |
complicated. See "Capture groups". |
| 190 |
.PP |
| 191 |
The first alternative includes everything from the last pattern |
| 192 |
delimiter (\f(CW"("\fR, \f(CW"(?:"\fR (described later), \fIetc\fR. or the beginning |
| 193 |
of the pattern) up to the first \f(CW"|"\fR, and the last alternative |
| 194 |
contains everything from the last \f(CW"|"\fR to the next closing pattern |
| 195 |
delimiter. That's why it's common practice to include alternatives in |
| 196 |
parentheses: to minimize confusion about where they start and end. |
| 197 |
.PP |
| 198 |
Alternatives are tried from left to right, so the first |
| 199 |
alternative found for which the entire expression matches, is the one that |
| 200 |
is chosen. This means that alternatives are not necessarily greedy. For |
| 201 |
example: when matching \f(CW\*(C`foo|foot\*(C'\fR against \f(CW"barefoot"\fR, only the \f(CW"foo"\fR |
| 202 |
part will match, as that is the first alternative tried, and it successfully |
| 203 |
matches the target string. (This might not seem important, but it is |
| 204 |
important when you are capturing matched text using parentheses.) |
| 205 |
.PP |
| 206 |
Besides taking away the special meaning of a metacharacter, a prefixed |
| 207 |
backslash changes some letter and digit characters away from matching |
| 208 |
just themselves to instead have special meaning. These are called |
| 209 |
"escape sequences", and all such are described in perlrebackslash. A |
| 210 |
backslash sequence (of a letter or digit) that doesn't currently have |
| 211 |
special meaning to Perl will raise a warning if warnings are enabled, |
| 212 |
as those are reserved for potential future use. |
| 213 |
.PP |
| 214 |
One such sequence is \f(CW\*(C`\eb\*(C'\fR, which matches a boundary of some sort. |
| 215 |
\&\f(CW\*(C`\eb{wb}\*(C'\fR and a few others give specialized types of boundaries. |
| 216 |
(They are all described in detail starting at |
| 217 |
"\eb{}, \eb, \eB{}, \eB" in perlrebackslash.) Note that these don't match |
| 218 |
characters, but the zero-width spaces between characters. They are an |
| 219 |
example of a zero-width assertion. Consider again, |
| 220 |
.PP |
| 221 |
.Vb 1 |
| 222 |
\& $foo =~ m/fee|fie|foe|fum/ |
| 223 |
.Ve |
| 224 |
.PP |
| 225 |
It evaluates to TRUE if, besides those 4 words, any of the sequences |
| 226 |
"feed", "field", "Defoe", "fume", and many others are in \f(CW$foo\fR. By |
| 227 |
judicious use of \f(CW\*(C`\eb\*(C'\fR (or better (because it is designed to handle |
| 228 |
natural language) \f(CW\*(C`\eb{wb}\*(C'\fR), we can make sure that only the Giant's |
| 229 |
words are matched: |
| 230 |
.PP |
| 231 |
.Vb 2 |
| 232 |
\& $foo =~ m/\eb(fee|fie|foe|fum)\eb/ |
| 233 |
\& $foo =~ m/\eb{wb}(fee|fie|foe|fum)\eb{wb}/ |
| 234 |
.Ve |
| 235 |
.PP |
| 236 |
The final example shows that the characters \f(CW"{"\fR and \f(CW"}"\fR are |
| 237 |
metacharacters. |
| 238 |
.PP |
| 239 |
Another use for escape sequences is to specify characters that cannot |
| 240 |
(or which you prefer not to) be written literally. These are described |
| 241 |
in detail in "Character Escapes" in perlrebackslash, but the next three |
| 242 |
paragraphs briefly describe some of them. |
| 243 |
.PP |
| 244 |
Various control characters can be written in C language style: \f(CW"\en"\fR |
| 245 |
matches a newline, \f(CW"\et"\fR a tab, \f(CW"\er"\fR a carriage return, \f(CW"\ef"\fR a |
| 246 |
form feed, \fIetc\fR. |
| 247 |
.PP |
| 248 |
More generally, \f(CW\*(C`\e\fR\f(CInnn\fR\f(CW\*(C'\fR, where \fInnn\fR is a string of three octal |
| 249 |
digits, matches the character whose native code point is \fInnn\fR. You |
| 250 |
can easily run into trouble if you don't have exactly three digits. So |
| 251 |
always use three, or since Perl 5.14, you can use \f(CW\*(C`\eo{...}\*(C'\fR to specify |
| 252 |
any number of octal digits. |
| 253 |
.PP |
| 254 |
Similarly, \f(CW\*(C`\ex\fR\f(CInn\fR\f(CW\*(C'\fR, where \fInn\fR are hexadecimal digits, matches the |
| 255 |
character whose native ordinal is \fInn\fR. Again, not using exactly two |
| 256 |
digits is a recipe for disaster, but you can use \f(CW\*(C`\ex{...}\*(C'\fR to specify |
| 257 |
any number of hex digits. |
| 258 |
.PP |
| 259 |
Besides being a metacharacter, the \f(CW"."\fR is an example of a "character |
| 260 |
class", something that can match any single character of a given set of |
| 261 |
them. In its case, the set is just about all possible characters. Perl |
| 262 |
predefines several character classes besides the \f(CW"."\fR; there is a |
| 263 |
separate reference page about just these, perlrecharclass. |
| 264 |
.PP |
| 265 |
You can define your own custom character classes, by putting into your |
| 266 |
pattern in the appropriate place(s), a list of all the characters you |
| 267 |
want in the set. You do this by enclosing the list within \f(CW\*(C`[]\*(C'\fR bracket |
| 268 |
characters. These are called "bracketed character classes" when we are |
| 269 |
being precise, but often the word "bracketed" is dropped. (Dropping it |
| 270 |
usually doesn't cause confusion.) This means that the \f(CW"["\fR character |
| 271 |
is another metacharacter. It doesn't match anything just by itself; it |
| 272 |
is used only to tell Perl that what follows it is a bracketed character |
| 273 |
class. If you want to match a literal left square bracket, you must |
| 274 |
escape it, like \f(CW"\e["\fR. The matching \f(CW"]"\fR is also a metacharacter; |
| 275 |
again it doesn't match anything by itself, but just marks the end of |
| 276 |
your custom class to Perl. It is an example of a "sometimes |
| 277 |
metacharacter". It isn't a metacharacter if there is no corresponding |
| 278 |
\&\f(CW"["\fR, and matches its literal self: |
| 279 |
.PP |
| 280 |
.Vb 1 |
| 281 |
\& print "]" =~ /]/; # prints 1 |
| 282 |
.Ve |
| 283 |
.PP |
| 284 |
The list of characters within the character class gives the set of |
| 285 |
characters matched by the class. \f(CW"[abc]"\fR matches a single "a" or "b" |
| 286 |
or "c". But if the first character after the \f(CW"["\fR is \f(CW"^"\fR, the |
| 287 |
class instead matches any character not in the list. Within a list, the |
| 288 |
\&\f(CW"\-"\fR character specifies a range of characters, so that \f(CW\*(C`a\-z\*(C'\fR |
| 289 |
represents all characters between "a" and "z", inclusive. If you want |
| 290 |
either \f(CW"\-"\fR or \f(CW"]"\fR itself to be a member of a class, put it at the |
| 291 |
start of the list (possibly after a \f(CW"^"\fR), or escape it with a |
| 292 |
backslash. \f(CW"\-"\fR is also taken literally when it is at the end of the |
| 293 |
list, just before the closing \f(CW"]"\fR. (The following all specify the |
| 294 |
same class of three characters: \f(CW\*(C`[\-az]\*(C'\fR, \f(CW\*(C`[az\-]\*(C'\fR, and \f(CW\*(C`[a\e\-z]\*(C'\fR. All |
| 295 |
are different from \f(CW\*(C`[a\-z]\*(C'\fR, which specifies a class containing |
| 296 |
twenty-six characters, even on EBCDIC-based character sets.) |
| 297 |
.PP |
| 298 |
There is lots more to bracketed character classes; full details are in |
| 299 |
"Bracketed Character Classes" in perlrecharclass. |
| 300 |
.PP |
| 301 |
\fIMetacharacters\fR |
| 302 |
.IX Xref "metacharacter \\ ^ . $ | ( () [ []" |
| 303 |
.IX Subsection "Metacharacters" |
| 304 |
.PP |
| 305 |
"The Basics" introduced some of the metacharacters. This section |
| 306 |
gives them all. Most of them have the same meaning as in the \fIegrep\fR |
| 307 |
command. |
| 308 |
.PP |
| 309 |
Only the \f(CW"\e"\fR is always a metacharacter. The others are metacharacters |
| 310 |
just sometimes. The following tables lists all of them, summarizes |
| 311 |
their use, and gives the contexts where they are metacharacters. |
| 312 |
Outside those contexts or if prefixed by a \f(CW"\e"\fR, they match their |
| 313 |
corresponding punctuation character. In some cases, their meaning |
| 314 |
varies depending on various pattern modifiers that alter the default |
| 315 |
behaviors. See "Modifiers". |
| 316 |
.PP |
| 317 |
.Vb 10 |
| 318 |
\& PURPOSE WHERE |
| 319 |
\& \e Escape the next character Always, except when |
| 320 |
\& escaped by another \e |
| 321 |
\& ^ Match the beginning of the string Not in [] |
| 322 |
\& (or line, if /m is used) |
| 323 |
\& ^ Complement the [] class At the beginning of [] |
| 324 |
\& . Match any single character except newline Not in [] |
| 325 |
\& (under /s, includes newline) |
| 326 |
\& $ Match the end of the string Not in [], but can |
| 327 |
\& (or before newline at the end of the mean interpolate a |
| 328 |
\& string; or before any newline if /m is scalar |
| 329 |
\& used) |
| 330 |
\& | Alternation Not in [] |
| 331 |
\& () Grouping Not in [] |
| 332 |
\& [ Start Bracketed Character class Not in [] |
| 333 |
\& ] End Bracketed Character class Only in [], and |
| 334 |
\& not first |
| 335 |
\& * Matches the preceding element 0 or more Not in [] |
| 336 |
\& times |
| 337 |
\& + Matches the preceding element 1 or more Not in [] |
| 338 |
\& times |
| 339 |
\& ? Matches the preceding element 0 or 1 Not in [] |
| 340 |
\& times |
| 341 |
\& { Starts a sequence that gives number(s) Not in [] |
| 342 |
\& of times the preceding element can be |
| 343 |
\& matched |
| 344 |
\& { when following certain escape sequences |
| 345 |
\& starts a modifier to the meaning of the |
| 346 |
\& sequence |
| 347 |
\& } End sequence started by { |
| 348 |
\& \- Indicates a range Only in [] interior |
| 349 |
\& # Beginning of comment, extends to line end Only with /x modifier |
| 350 |
.Ve |
| 351 |
.PP |
| 352 |
Notice that most of the metacharacters lose their special meaning when |
| 353 |
they occur in a bracketed character class, except \f(CW"^"\fR has a different |
| 354 |
meaning when it is at the beginning of such a class. And \f(CW"\-"\fR and \f(CW"]"\fR |
| 355 |
are metacharacters only at restricted positions within bracketed |
| 356 |
character classes; while \f(CW"}"\fR is a metacharacter only when closing a |
| 357 |
special construct started by \f(CW"{"\fR. |
| 358 |
.PP |
| 359 |
In double-quotish context, as is usually the case, you need to be |
| 360 |
careful about \f(CW"$"\fR and the non-metacharacter \f(CW"@"\fR. Those could |
| 361 |
interpolate variables, which may or may not be what you intended. |
| 362 |
.PP |
| 363 |
These rules were designed for compactness of expression, rather than |
| 364 |
legibility and maintainability. The "/x and /xx" pattern |
| 365 |
modifiers allow you to insert white space to improve readability. And |
| 366 |
use of \f(CW\*(C`re\ \*(Aqstrict\*(Aq\*(C'\fR adds extra checking to |
| 367 |
catch some typos that might silently compile into something unintended. |
| 368 |
.PP |
| 369 |
By default, the \f(CW"^"\fR character is guaranteed to match only the |
| 370 |
beginning of the string, the \f(CW"$"\fR character only the end (or before the |
| 371 |
newline at the end), and Perl does certain optimizations with the |
| 372 |
assumption that the string contains only one line. Embedded newlines |
| 373 |
will not be matched by \f(CW"^"\fR or \f(CW"$"\fR. You may, however, wish to treat a |
| 374 |
string as a multi-line buffer, such that the \f(CW"^"\fR will match after any |
| 375 |
newline within the string (except if the newline is the last character in |
| 376 |
the string), and \f(CW"$"\fR will match before any newline. At the |
| 377 |
cost of a little more overhead, you can do this by using the |
| 378 |
\&\f(CW"/m"\fR modifier on the pattern match operator. (Older programs |
| 379 |
did this by setting \f(CW$*\fR, but this option was removed in perl 5.10.) |
| 380 |
.IX Xref "^ $ m" |
| 381 |
.PP |
| 382 |
To simplify multi-line substitutions, the \f(CW"."\fR character never matches a |
| 383 |
newline unless you use the \f(CW\*(C`/s\*(C'\fR modifier, which in effect tells |
| 384 |
Perl to pretend the string is a single line\-\-even if it isn't. |
| 385 |
.IX Xref ". s" |
| 386 |
.SS Modifiers |
| 387 |
.IX Subsection "Modifiers" |
| 388 |
\fIOverview\fR |
| 389 |
.IX Subsection "Overview" |
| 390 |
.PP |
| 391 |
The default behavior for matching can be changed, using various |
| 392 |
modifiers. Modifiers that relate to the interpretation of the pattern |
| 393 |
are listed just below. Modifiers that alter the way a pattern is used |
| 394 |
by Perl are detailed in "Regexp Quote-Like Operators" in perlop and |
| 395 |
"Gory details of parsing quoted constructs" in perlop. Modifiers can be added |
| 396 |
dynamically; see "Extended Patterns" below. |
| 397 |
.ie n .IP "\fR\fB""m""\fR\fB\fR" 4 |
| 398 |
.el .IP \fR\f(CBm\fR\fB\fR 4 |
| 399 |
.IX Xref " m regex, multiline regexp, multiline regular expression, multiline" |
| 400 |
.IX Item "m" |
| 401 |
Treat the string being matched against as multiple lines. That is, change \f(CW"^"\fR and \f(CW"$"\fR from matching |
| 402 |
the start of the string's first line and the end of its last line to |
| 403 |
matching the start and end of each line within the string. |
| 404 |
.ie n .IP "\fR\fB""s""\fR\fB\fR" 4 |
| 405 |
.el .IP \fR\f(CBs\fR\fB\fR 4 |
| 406 |
.IX Xref " s regex, single-line regexp, single-line regular expression, single-line" |
| 407 |
.IX Item "s" |
| 408 |
Treat the string as single line. That is, change \f(CW"."\fR to match any character |
| 409 |
whatsoever, even a newline, which normally it would not match. |
| 410 |
.Sp |
| 411 |
Used together, as \f(CW\*(C`/ms\*(C'\fR, they let the \f(CW"."\fR match any character whatsoever, |
| 412 |
while still allowing \f(CW"^"\fR and \f(CW"$"\fR to match, respectively, just after |
| 413 |
and just before newlines within the string. |
| 414 |
.ie n .IP "\fR\fB""i""\fR\fB\fR" 4 |
| 415 |
.el .IP \fR\f(CBi\fR\fB\fR 4 |
| 416 |
.IX Xref " i regex, case-insensitive regexp, case-insensitive regular expression, case-insensitive" |
| 417 |
.IX Item "i" |
| 418 |
Do case-insensitive pattern matching. For example, "A" will match "a" |
| 419 |
under \f(CW\*(C`/i\*(C'\fR. |
| 420 |
.Sp |
| 421 |
If locale matching rules are in effect, the case map is taken from the |
| 422 |
current |
| 423 |
locale for code points less than 255, and from Unicode rules for larger |
| 424 |
code points. However, matches that would cross the Unicode |
| 425 |
rules/non\-Unicode rules boundary (ords 255/256) will not succeed, unless |
| 426 |
the locale is a UTF\-8 one. See perllocale. |
| 427 |
.Sp |
| 428 |
There are a number of Unicode characters that match a sequence of |
| 429 |
multiple characters under \f(CW\*(C`/i\*(C'\fR. For example, |
| 430 |
\&\f(CW\*(C`LATIN SMALL LIGATURE FI\*(C'\fR should match the sequence \f(CW\*(C`fi\*(C'\fR. Perl is not |
| 431 |
currently able to do this when the multiple characters are in the pattern and |
| 432 |
are split between groupings, or when one or more are quantified. Thus |
| 433 |
.Sp |
| 434 |
.Vb 3 |
| 435 |
\& "\eN{LATIN SMALL LIGATURE FI}" =~ /fi/i; # Matches |
| 436 |
\& "\eN{LATIN SMALL LIGATURE FI}" =~ /[fi][fi]/i; # Doesn\*(Aqt match! |
| 437 |
\& "\eN{LATIN SMALL LIGATURE FI}" =~ /fi*/i; # Doesn\*(Aqt match! |
| 438 |
\& |
| 439 |
\& # The below doesn\*(Aqt match, and it isn\*(Aqt clear what $1 and $2 would |
| 440 |
\& # be even if it did!! |
| 441 |
\& "\eN{LATIN SMALL LIGATURE FI}" =~ /(f)(i)/i; # Doesn\*(Aqt match! |
| 442 |
.Ve |
| 443 |
.Sp |
| 444 |
Perl doesn't match multiple characters in a bracketed |
| 445 |
character class unless the character that maps to them is explicitly |
| 446 |
mentioned, and it doesn't match them at all if the character class is |
| 447 |
inverted, which otherwise could be highly confusing. See |
| 448 |
"Bracketed Character Classes" in perlrecharclass, and |
| 449 |
"Negation" in perlrecharclass. |
| 450 |
.ie n .IP "\fR\fB""x""\fR\fB\fR and \fB\fR\fB""xx""\fR\fB\fR" 4 |
| 451 |
.el .IP "\fR\f(CBx\fR\fB\fR and \fB\fR\f(CBxx\fR\fB\fR" 4 |
| 452 |
.IX Xref " x" |
| 453 |
.IX Item "x and xx" |
| 454 |
Extend your pattern's legibility by permitting whitespace and comments. |
| 455 |
Details in "/x and /xx" |
| 456 |
.ie n .IP "\fR\fB""p""\fR\fB\fR" 4 |
| 457 |
.el .IP \fR\f(CBp\fR\fB\fR 4 |
| 458 |
.IX Xref " p regex, preserve regexp, preserve" |
| 459 |
.IX Item "p" |
| 460 |
Preserve the string matched such that \f(CW\*(C`${^PREMATCH}\*(C'\fR, \f(CW\*(C`${^MATCH}\*(C'\fR, and |
| 461 |
\&\f(CW\*(C`${^POSTMATCH}\*(C'\fR are available for use after matching. |
| 462 |
.Sp |
| 463 |
In Perl 5.20 and higher this is ignored. Due to a new copy-on-write |
| 464 |
mechanism, \f(CW\*(C`${^PREMATCH}\*(C'\fR, \f(CW\*(C`${^MATCH}\*(C'\fR, and \f(CW\*(C`${^POSTMATCH}\*(C'\fR will be available |
| 465 |
after the match regardless of the modifier. |
| 466 |
.ie n .IP "\fR\fB""a""\fR\fB\fR, \fB\fR\fB""d""\fR\fB\fR, \fB\fR\fB""l""\fR\fB\fR, and \fB\fR\fB""u""\fR\fB\fR" 4 |
| 467 |
.el .IP "\fR\f(CBa\fR\fB\fR, \fB\fR\f(CBd\fR\fB\fR, \fB\fR\f(CBl\fR\fB\fR, and \fB\fR\f(CBu\fR\fB\fR" 4 |
| 468 |
.IX Xref " a d l u" |
| 469 |
.IX Item "a, d, l, and u" |
| 470 |
These modifiers, all new in 5.14, affect which character-set rules |
| 471 |
(Unicode, \fIetc\fR.) are used, as described below in |
| 472 |
"Character set modifiers". |
| 473 |
.ie n .IP "\fR\fB""n""\fR\fB\fR" 4 |
| 474 |
.el .IP \fR\f(CBn\fR\fB\fR 4 |
| 475 |
.IX Xref " n regex, non-capture regexp, non-capture regular expression, non-capture" |
| 476 |
.IX Item "n" |
| 477 |
Prevent the grouping metacharacters \f(CW\*(C`()\*(C'\fR from capturing. This modifier, |
| 478 |
new in 5.22, will stop \f(CW$1\fR, \f(CW$2\fR, \fIetc\fR... from being filled in. |
| 479 |
.Sp |
| 480 |
.Vb 2 |
| 481 |
\& "hello" =~ /(hi|hello)/; # $1 is "hello" |
| 482 |
\& "hello" =~ /(hi|hello)/n; # $1 is undef |
| 483 |
.Ve |
| 484 |
.Sp |
| 485 |
This is equivalent to putting \f(CW\*(C`?:\*(C'\fR at the beginning of every capturing group: |
| 486 |
.Sp |
| 487 |
.Vb 1 |
| 488 |
\& "hello" =~ /(?:hi|hello)/; # $1 is undef |
| 489 |
.Ve |
| 490 |
.Sp |
| 491 |
\&\f(CW\*(C`/n\*(C'\fR can be negated on a per-group basis. Alternatively, named captures |
| 492 |
may still be used. |
| 493 |
.Sp |
| 494 |
.Vb 3 |
| 495 |
\& "hello" =~ /(?\-n:(hi|hello))/n; # $1 is "hello" |
| 496 |
\& "hello" =~ /(?<greet>hi|hello)/n; # $1 is "hello", $+{greet} is |
| 497 |
\& # "hello" |
| 498 |
.Ve |
| 499 |
.IP "Other Modifiers" 4 |
| 500 |
.IX Item "Other Modifiers" |
| 501 |
There are a number of flags that can be found at the end of regular |
| 502 |
expression constructs that are \fInot\fR generic regular expression flags, but |
| 503 |
apply to the operation being performed, like matching or substitution (\f(CW\*(C`m//\*(C'\fR |
| 504 |
or \f(CW\*(C`s///\*(C'\fR respectively). |
| 505 |
.Sp |
| 506 |
Flags described further in |
| 507 |
"Using regular expressions in Perl" in perlretut are: |
| 508 |
.Sp |
| 509 |
.Vb 2 |
| 510 |
\& c \- keep the current position during repeated matching |
| 511 |
\& g \- globally match the pattern repeatedly in the string |
| 512 |
.Ve |
| 513 |
.Sp |
| 514 |
Substitution-specific modifiers described in |
| 515 |
"s/PATTERN/REPLACEMENT/msixpodualngcer" in perlop are: |
| 516 |
.Sp |
| 517 |
.Vb 4 |
| 518 |
\& e \- evaluate the right\-hand side as an expression |
| 519 |
\& ee \- evaluate the right side as a string then eval the result |
| 520 |
\& o \- pretend to optimize your code, but actually introduce bugs |
| 521 |
\& r \- perform non\-destructive substitution and return the new value |
| 522 |
.Ve |
| 523 |
.PP |
| 524 |
Regular expression modifiers are usually written in documentation |
| 525 |
as \fIe.g.\fR, "the \f(CW\*(C`/x\*(C'\fR modifier", even though the delimiter |
| 526 |
in question might not really be a slash. The modifiers \f(CW\*(C`/imnsxadlup\*(C'\fR |
| 527 |
may also be embedded within the regular expression itself using |
| 528 |
the \f(CW\*(C`(?...)\*(C'\fR construct, see "Extended Patterns" below. |
| 529 |
.PP |
| 530 |
\fIDetails on some modifiers\fR |
| 531 |
.IX Subsection "Details on some modifiers" |
| 532 |
.PP |
| 533 |
Some of the modifiers require more explanation than given in the |
| 534 |
"Overview" above. |
| 535 |
.PP |
| 536 |
\f(CW\*(C`/x\*(C'\fR and \f(CW\*(C`/xx\*(C'\fR |
| 537 |
.IX Subsection "/x and /xx" |
| 538 |
.PP |
| 539 |
A single \f(CW\*(C`/x\*(C'\fR tells |
| 540 |
the regular expression parser to ignore most whitespace that is neither |
| 541 |
backslashed nor within a bracketed character class, nor within the characters |
| 542 |
of a multi-character metapattern like \f(CW\*(C`(?i: ... )\*(C'\fR. You can use this to |
| 543 |
break up your regular expression into more readable parts. |
| 544 |
Also, the \f(CW"#"\fR character is treated as a metacharacter introducing a |
| 545 |
comment that runs up to the pattern's closing delimiter, or to the end |
| 546 |
of the current line if the pattern extends onto the next line. Hence, |
| 547 |
this is very much like an ordinary Perl code comment. (You can include |
| 548 |
the closing delimiter within the comment only if you precede it with a |
| 549 |
backslash, so be careful!) |
| 550 |
.PP |
| 551 |
Use of \f(CW\*(C`/x\*(C'\fR means that if you want real |
| 552 |
whitespace or \f(CW"#"\fR characters in the pattern (outside a bracketed character |
| 553 |
class, which is unaffected by \f(CW\*(C`/x\*(C'\fR), then you'll either have to |
| 554 |
escape them (using backslashes or \f(CW\*(C`\eQ...\eE\*(C'\fR) or encode them using octal, |
| 555 |
hex, or \f(CW\*(C`\eN{}\*(C'\fR or \f(CW\*(C`\ep{name=...}\*(C'\fR escapes. |
| 556 |
It is ineffective to try to continue a comment onto the next line by |
| 557 |
escaping the \f(CW\*(C`\en\*(C'\fR with a backslash or \f(CW\*(C`\eQ\*(C'\fR. |
| 558 |
.PP |
| 559 |
You can use "(?#text)" to create a comment that ends earlier than the |
| 560 |
end of the current line, but \f(CW\*(C`text\*(C'\fR also can't contain the closing |
| 561 |
delimiter unless escaped with a backslash. |
| 562 |
.PP |
| 563 |
A common pitfall is to forget that \f(CW"#"\fR characters (outside a |
| 564 |
bracketed character class) begin a comment under \f(CW\*(C`/x\*(C'\fR and are not |
| 565 |
matched literally. Just keep that in mind when trying to puzzle out why |
| 566 |
a particular \f(CW\*(C`/x\*(C'\fR pattern isn't working as expected. |
| 567 |
Inside a bracketed character class, \f(CW"#"\fR retains its non-special, |
| 568 |
literal meaning. |
| 569 |
.PP |
| 570 |
Starting in Perl v5.26, if the modifier has a second \f(CW"x"\fR within it, |
| 571 |
the effect of a single \f(CW\*(C`/x\*(C'\fR is increased. The only difference is that |
| 572 |
inside bracketed character classes, non-escaped (by a backslash) SPACE |
| 573 |
and TAB characters are not added to the class, and hence can be inserted |
| 574 |
to make the classes more readable: |
| 575 |
.PP |
| 576 |
.Vb 2 |
| 577 |
\& / [d\-e g\-i 3\-7]/xx |
| 578 |
\& /[ ! @ " # $ % ^ & * () = ? <> \*(Aq ]/xx |
| 579 |
.Ve |
| 580 |
.PP |
| 581 |
may be easier to grasp than the squashed equivalents |
| 582 |
.PP |
| 583 |
.Vb 2 |
| 584 |
\& /[d\-eg\-i3\-7]/ |
| 585 |
\& /[!@"#$%^&*()=?<>\*(Aq]/ |
| 586 |
.Ve |
| 587 |
.PP |
| 588 |
Note that this unfortunately doesn't mean that your bracketed classes |
| 589 |
can contain comments or extend over multiple lines. A \f(CW\*(C`#\*(C'\fR inside a |
| 590 |
character class is still just a literal \f(CW\*(C`#\*(C'\fR, and doesn't introduce a |
| 591 |
comment. And, unless the closing bracket is on the same line as the |
| 592 |
opening one, the newline character (and everything on the next line(s) |
| 593 |
until terminated by a \f(CW\*(C`]\*(C'\fR will be part of the class, just as if you'd |
| 594 |
written \f(CW\*(C`\en\*(C'\fR. |
| 595 |
.PP |
| 596 |
Taken together, these features go a long way towards |
| 597 |
making Perl's regular expressions more readable. Here's an example: |
| 598 |
.PP |
| 599 |
.Vb 6 |
| 600 |
\& # Delete (most) C comments. |
| 601 |
\& $program =~ s { |
| 602 |
\& /\e* # Match the opening delimiter. |
| 603 |
\& .*? # Match a minimal number of characters. |
| 604 |
\& \e*/ # Match the closing delimiter. |
| 605 |
\& } []gsx; |
| 606 |
.Ve |
| 607 |
.PP |
| 608 |
Note that anything inside |
| 609 |
a \f(CW\*(C`\eQ...\eE\*(C'\fR stays unaffected by \f(CW\*(C`/x\*(C'\fR. And note that \f(CW\*(C`/x\*(C'\fR doesn't affect |
| 610 |
space interpretation within a single multi-character construct. For |
| 611 |
example \f(CW\*(C`(?:...)\*(C'\fR can't have a space between the \f(CW"("\fR, |
| 612 |
\&\f(CW"?"\fR, and \f(CW":"\fR. Within any delimiters for such a construct, allowed |
| 613 |
spaces are not affected by \f(CW\*(C`/x\*(C'\fR, and depend on the construct. For |
| 614 |
example, all constructs using curly braces as delimiters, such as |
| 615 |
\&\f(CW\*(C`\ex{...}\*(C'\fR can have blanks within but adjacent to the braces, but not |
| 616 |
elsewhere, and no non-blank space characters. An exception are Unicode |
| 617 |
properties which follow Unicode rules, for which see |
| 618 |
"Properties accessible through \ep{} and \eP{}" in perluniprops. |
| 619 |
.IX Xref " x" |
| 620 |
.PP |
| 621 |
The set of characters that are deemed whitespace are those that Unicode |
| 622 |
calls "Pattern White Space", namely: |
| 623 |
.PP |
| 624 |
.Vb 11 |
| 625 |
\& U+0009 CHARACTER TABULATION |
| 626 |
\& U+000A LINE FEED |
| 627 |
\& U+000B LINE TABULATION |
| 628 |
\& U+000C FORM FEED |
| 629 |
\& U+000D CARRIAGE RETURN |
| 630 |
\& U+0020 SPACE |
| 631 |
\& U+0085 NEXT LINE |
| 632 |
\& U+200E LEFT\-TO\-RIGHT MARK |
| 633 |
\& U+200F RIGHT\-TO\-LEFT MARK |
| 634 |
\& U+2028 LINE SEPARATOR |
| 635 |
\& U+2029 PARAGRAPH SEPARATOR |
| 636 |
.Ve |
| 637 |
.PP |
| 638 |
Character set modifiers |
| 639 |
.IX Subsection "Character set modifiers" |
| 640 |
.PP |
| 641 |
\&\f(CW\*(C`/d\*(C'\fR, \f(CW\*(C`/u\*(C'\fR, \f(CW\*(C`/a\*(C'\fR, and \f(CW\*(C`/l\*(C'\fR, available starting in 5.14, are called |
| 642 |
the character set modifiers; they affect the character set rules |
| 643 |
used for the regular expression. |
| 644 |
.PP |
| 645 |
The \f(CW\*(C`/d\*(C'\fR, \f(CW\*(C`/u\*(C'\fR, and \f(CW\*(C`/l\*(C'\fR modifiers are not likely to be of much use |
| 646 |
to you, and so you need not worry about them very much. They exist for |
| 647 |
Perl's internal use, so that complex regular expression data structures |
| 648 |
can be automatically serialized and later exactly reconstituted, |
| 649 |
including all their nuances. But, since Perl can't keep a secret, and |
| 650 |
there may be rare instances where they are useful, they are documented |
| 651 |
here. |
| 652 |
.PP |
| 653 |
The \f(CW\*(C`/a\*(C'\fR modifier, on the other hand, may be useful. Its purpose is to |
| 654 |
allow code that is to work mostly on ASCII data to not have to concern |
| 655 |
itself with Unicode. |
| 656 |
.PP |
| 657 |
Briefly, \f(CW\*(C`/l\*(C'\fR sets the character set to that of whatever \fBL\fRocale is in |
| 658 |
effect at the time of the execution of the pattern match. |
| 659 |
.PP |
| 660 |
\&\f(CW\*(C`/u\*(C'\fR sets the character set to \fBU\fRnicode. |
| 661 |
.PP |
| 662 |
\&\f(CW\*(C`/a\*(C'\fR also sets the character set to Unicode, BUT adds several |
| 663 |
restrictions for \fBA\fRSCII-safe matching. |
| 664 |
.PP |
| 665 |
\&\f(CW\*(C`/d\*(C'\fR is the old, problematic, pre\-5.14 \fBD\fRefault character set |
| 666 |
behavior. Its only use is to force that old behavior. |
| 667 |
.PP |
| 668 |
At any given time, exactly one of these modifiers is in effect. Their |
| 669 |
existence allows Perl to keep the originally compiled behavior of a |
| 670 |
regular expression, regardless of what rules are in effect when it is |
| 671 |
actually executed. And if it is interpolated into a larger regex, the |
| 672 |
original's rules continue to apply to it, and don't affect the other |
| 673 |
parts. |
| 674 |
.PP |
| 675 |
The \f(CW\*(C`/l\*(C'\fR and \f(CW\*(C`/u\*(C'\fR modifiers are automatically selected for |
| 676 |
regular expressions compiled within the scope of various pragmas, |
| 677 |
and we recommend that in general, you use those pragmas instead of |
| 678 |
specifying these modifiers explicitly. For one thing, the modifiers |
| 679 |
affect only pattern matching, and do not extend to even any replacement |
| 680 |
done, whereas using the pragmas gives consistent results for all |
| 681 |
appropriate operations within their scopes. For example, |
| 682 |
.PP |
| 683 |
.Vb 1 |
| 684 |
\& s/foo/\eUbar/il |
| 685 |
.Ve |
| 686 |
.PP |
| 687 |
will match "foo" using the locale's rules for case-insensitive matching, |
| 688 |
but the \f(CW\*(C`/l\*(C'\fR does not affect how the \f(CW\*(C`\eU\*(C'\fR operates. Most likely you |
| 689 |
want both of them to use locale rules. To do this, instead compile the |
| 690 |
regular expression within the scope of \f(CW\*(C`use locale\*(C'\fR. This both |
| 691 |
implicitly adds the \f(CW\*(C`/l\*(C'\fR, and applies locale rules to the \f(CW\*(C`\eU\*(C'\fR. The |
| 692 |
lesson is to \f(CW\*(C`use locale\*(C'\fR, and not \f(CW\*(C`/l\*(C'\fR explicitly. |
| 693 |
.PP |
| 694 |
Similarly, it would be better to use \f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR |
| 695 |
instead of, |
| 696 |
.PP |
| 697 |
.Vb 1 |
| 698 |
\& s/foo/\eLbar/iu |
| 699 |
.Ve |
| 700 |
.PP |
| 701 |
to get Unicode rules, as the \f(CW\*(C`\eL\*(C'\fR in the former (but not necessarily |
| 702 |
the latter) would also use Unicode rules. |
| 703 |
.PP |
| 704 |
More detail on each of the modifiers follows. Most likely you don't |
| 705 |
need to know this detail for \f(CW\*(C`/l\*(C'\fR, \f(CW\*(C`/u\*(C'\fR, and \f(CW\*(C`/d\*(C'\fR, and can skip ahead |
| 706 |
to /a. |
| 707 |
.PP |
| 708 |
/l |
| 709 |
.IX Subsection "/l" |
| 710 |
.PP |
| 711 |
means to use the current locale's rules (see perllocale) when pattern |
| 712 |
matching. For example, \f(CW\*(C`\ew\*(C'\fR will match the "word" characters of that |
| 713 |
locale, and \f(CW"/i"\fR case-insensitive matching will match according to |
| 714 |
the locale's case folding rules. The locale used will be the one in |
| 715 |
effect at the time of execution of the pattern match. This may not be |
| 716 |
the same as the compilation-time locale, and can differ from one match |
| 717 |
to another if there is an intervening call of the |
| 718 |
\&\fBsetlocale()\fR function. |
| 719 |
.PP |
| 720 |
Prior to v5.20, Perl did not support multi-byte locales. Starting then, |
| 721 |
UTF\-8 locales are supported. No other multi byte locales are ever |
| 722 |
likely to be supported. However, in all locales, one can have code |
| 723 |
points above 255 and these will always be treated as Unicode no matter |
| 724 |
what locale is in effect. |
| 725 |
.PP |
| 726 |
Under Unicode rules, there are a few case-insensitive matches that cross |
| 727 |
the 255/256 boundary. Except for UTF\-8 locales in Perls v5.20 and |
| 728 |
later, these are disallowed under \f(CW\*(C`/l\*(C'\fR. For example, 0xFF (on ASCII |
| 729 |
platforms) does not caselessly match the character at 0x178, \f(CW\*(C`LATIN |
| 730 |
CAPITAL LETTER Y WITH DIAERESIS\*(C'\fR, because 0xFF may not be \f(CW\*(C`LATIN SMALL |
| 731 |
LETTER Y WITH DIAERESIS\*(C'\fR in the current locale, and Perl has no way of |
| 732 |
knowing if that character even exists in the locale, much less what code |
| 733 |
point it is. |
| 734 |
.PP |
| 735 |
In a UTF\-8 locale in v5.20 and later, the only visible difference |
| 736 |
between locale and non-locale in regular expressions should be tainting, |
| 737 |
if your perl supports taint checking (see perlsec). |
| 738 |
.PP |
| 739 |
This modifier may be specified to be the default by \f(CW\*(C`use locale\*(C'\fR, but |
| 740 |
see "Which character set modifier is in effect?". |
| 741 |
.IX Xref " l" |
| 742 |
.PP |
| 743 |
/u |
| 744 |
.IX Subsection "/u" |
| 745 |
.PP |
| 746 |
means to use Unicode rules when pattern matching. On ASCII platforms, |
| 747 |
this means that the code points between 128 and 255 take on their |
| 748 |
Latin\-1 (ISO\-8859\-1) meanings (which are the same as Unicode's). |
| 749 |
(Otherwise Perl considers their meanings to be undefined.) Thus, |
| 750 |
under this modifier, the ASCII platform effectively becomes a Unicode |
| 751 |
platform; and hence, for example, \f(CW\*(C`\ew\*(C'\fR will match any of the more than |
| 752 |
100_000 word characters in Unicode. |
| 753 |
.PP |
| 754 |
Unlike most locales, which are specific to a language and country pair, |
| 755 |
Unicode classifies all the characters that are letters \fIsomewhere\fR in |
| 756 |
the world as |
| 757 |
\&\f(CW\*(C`\ew\*(C'\fR. For example, your locale might not think that \f(CW\*(C`LATIN SMALL |
| 758 |
LETTER ETH\*(C'\fR is a letter (unless you happen to speak Icelandic), but |
| 759 |
Unicode does. Similarly, all the characters that are decimal digits |
| 760 |
somewhere in the world will match \f(CW\*(C`\ed\*(C'\fR; this is hundreds, not 10, |
| 761 |
possible matches. And some of those digits look like some of the 10 |
| 762 |
ASCII digits, but mean a different number, so a human could easily think |
| 763 |
a number is a different quantity than it really is. For example, |
| 764 |
\&\f(CW\*(C`BENGALI DIGIT FOUR\*(C'\fR (U+09EA) looks very much like an |
| 765 |
\&\f(CW\*(C`ASCII DIGIT EIGHT\*(C'\fR (U+0038), and \f(CW\*(C`LEPCHA DIGIT SIX\*(C'\fR (U+1C46) looks |
| 766 |
very much like an \f(CW\*(C`ASCII DIGIT FIVE\*(C'\fR (U+0035). And, \f(CW\*(C`\ed+\*(C'\fR, may match |
| 767 |
strings of digits that are a mixture from different writing systems, |
| 768 |
creating a security issue. A fraudulent website, for example, could |
| 769 |
display the price of something using U+1C46, and it would appear to the |
| 770 |
user that something cost 500 units, but it really costs 600. A browser |
| 771 |
that enforced script runs ("Script Runs") would prevent that |
| 772 |
fraudulent display. "\fBnum()\fR" in Unicode::UCD can also be used to sort this |
| 773 |
out. Or the \f(CW\*(C`/a\*(C'\fR modifier can be used to force \f(CW\*(C`\ed\*(C'\fR to match just the |
| 774 |
ASCII 0 through 9. |
| 775 |
.PP |
| 776 |
Also, under this modifier, case-insensitive matching works on the full |
| 777 |
set of Unicode |
| 778 |
characters. The \f(CW\*(C`KELVIN SIGN\*(C'\fR, for example matches the letters "k" and |
| 779 |
"K"; and \f(CW\*(C`LATIN SMALL LIGATURE FF\*(C'\fR matches the sequence "ff", which, |
| 780 |
if you're not prepared, might make it look like a hexadecimal constant, |
| 781 |
presenting another potential security issue. See |
| 782 |
<https://unicode.org/reports/tr36> for a detailed discussion of Unicode |
| 783 |
security issues. |
| 784 |
.PP |
| 785 |
This modifier may be specified to be the default by \f(CW\*(C`use feature |
| 786 |
\&\*(Aqunicode_strings\*(C'\fR, \f(CW\*(C`use locale \*(Aq:not_characters\*(Aq\*(C'\fR, or |
| 787 |
\&\f(CW\*(C`use v5.12\*(C'\fR (or higher), |
| 788 |
but see "Which character set modifier is in effect?". |
| 789 |
.IX Xref " u" |
| 790 |
.PP |
| 791 |
/d |
| 792 |
.IX Subsection "/d" |
| 793 |
.PP |
| 794 |
\&\fBIMPORTANT:\fR Because of the unpredictable behaviors this |
| 795 |
modifier causes, only use it to maintain weird backward compatibilities. |
| 796 |
Use the |
| 797 |
\&\f(CW\*(C`unicode_strings\*(C'\fR |
| 798 |
feature |
| 799 |
in new code to avoid inadvertently enabling this modifier by default. |
| 800 |
.PP |
| 801 |
What does this modifier do? It "Depends"! |
| 802 |
.PP |
| 803 |
This modifier means to use platform-native matching rules |
| 804 |
except when there is cause to use Unicode rules instead, as follows: |
| 805 |
.IP 1. 4 |
| 806 |
the target string's UTF8 flag |
| 807 |
(see below) is set; or |
| 808 |
.IP 2. 4 |
| 809 |
the pattern's UTF8 flag |
| 810 |
(see below) is set; or |
| 811 |
.IP 3. 4 |
| 812 |
the pattern explicitly mentions a code point that is above 255 (say by |
| 813 |
\&\f(CW\*(C`\ex{100}\*(C'\fR); or |
| 814 |
.IP 4. 4 |
| 815 |
the pattern uses a Unicode name (\f(CW\*(C`\eN{...}\*(C'\fR); or |
| 816 |
.IP 5. 4 |
| 817 |
the pattern uses a Unicode property (\f(CW\*(C`\ep{...}\*(C'\fR or \f(CW\*(C`\eP{...}\*(C'\fR); or |
| 818 |
.IP 6. 4 |
| 819 |
the pattern uses a Unicode break (\f(CW\*(C`\eb{...}\*(C'\fR or \f(CW\*(C`\eB{...}\*(C'\fR); or |
| 820 |
.IP 7. 4 |
| 821 |
the pattern uses \f(CW"(?[ ])"\fR |
| 822 |
.IP 8. 4 |
| 823 |
the pattern uses \f(CW\*(C`(*script_run: ...)\*(C'\fR |
| 824 |
.PP |
| 825 |
Regarding the "UTF8 flag" references above: normally Perl applications |
| 826 |
shouldn't think about that flag. It's part of Perl's internals, |
| 827 |
so it can change whenever Perl wants. \f(CW\*(C`/d\*(C'\fR may thus cause unpredictable |
| 828 |
results. See "The "Unicode Bug"" in perlunicode. This bug |
| 829 |
has become rather infamous, leading to yet other (without swearing) names |
| 830 |
for this modifier like "Dicey" and "Dodgy". |
| 831 |
.PP |
| 832 |
Here are some examples of how that works on an ASCII platform: |
| 833 |
.PP |
| 834 |
.Vb 3 |
| 835 |
\& $str = "\exDF"; # |
| 836 |
\& utf8::downgrade($str); # $str is not UTF8\-flagged. |
| 837 |
\& $str =~ /^\ew/; # No match, since no UTF8 flag. |
| 838 |
\& |
| 839 |
\& $str .= "\ex{0e0b}"; # Now $str is UTF8\-flagged. |
| 840 |
\& $str =~ /^\ew/; # Match! $str is now UTF8\-flagged. |
| 841 |
\& chop $str; |
| 842 |
\& $str =~ /^\ew/; # Still a match! $str retains its UTF8 flag. |
| 843 |
.Ve |
| 844 |
.PP |
| 845 |
Under Perl's default configuration this modifier is automatically |
| 846 |
selected by default when none of the others are, so yet another name |
| 847 |
for it (unfortunately) is "Default". |
| 848 |
.PP |
| 849 |
Whenever you can, use the |
| 850 |
\&\f(CW\*(C`unicode_strings\*(C'\fR |
| 851 |
to cause to be the default instead. |
| 852 |
.IX Xref " u" |
| 853 |
.PP |
| 854 |
/a (and /aa) |
| 855 |
.IX Subsection "/a (and /aa)" |
| 856 |
.PP |
| 857 |
This modifier stands for ASCII-restrict (or ASCII-safe). This modifier |
| 858 |
may be doubled-up to increase its effect. |
| 859 |
.PP |
| 860 |
When it appears singly, it causes the sequences \f(CW\*(C`\ed\*(C'\fR, \f(CW\*(C`\es\*(C'\fR, \f(CW\*(C`\ew\*(C'\fR, and |
| 861 |
the Posix character classes to match only in the ASCII range. They thus |
| 862 |
revert to their pre\-5.6, pre-Unicode meanings. Under \f(CW\*(C`/a\*(C'\fR, \f(CW\*(C`\ed\*(C'\fR |
| 863 |
always means precisely the digits \f(CW"0"\fR to \f(CW"9"\fR; \f(CW\*(C`\es\*(C'\fR means the five |
| 864 |
characters \f(CW\*(C`[ \ef\en\er\et]\*(C'\fR, and starting in Perl v5.18, the vertical tab; |
| 865 |
\&\f(CW\*(C`\ew\*(C'\fR means the 63 characters |
| 866 |
\&\f(CW\*(C`[A\-Za\-z0\-9_]\*(C'\fR; and likewise, all the Posix classes such as |
| 867 |
\&\f(CW\*(C`[[:print:]]\*(C'\fR match only the appropriate ASCII-range characters. |
| 868 |
.PP |
| 869 |
This modifier is useful for people who only incidentally use Unicode, |
| 870 |
and who do not wish to be burdened with its complexities and security |
| 871 |
concerns. |
| 872 |
.PP |
| 873 |
With \f(CW\*(C`/a\*(C'\fR, one can write \f(CW\*(C`\ed\*(C'\fR with confidence that it will only match |
| 874 |
ASCII characters, and should the need arise to match beyond ASCII, you |
| 875 |
can instead use \f(CW\*(C`\ep{Digit}\*(C'\fR (or \f(CW\*(C`\ep{Word}\*(C'\fR for \f(CW\*(C`\ew\*(C'\fR). There are |
| 876 |
similar \f(CW\*(C`\ep{...}\*(C'\fR constructs that can match beyond ASCII both white |
| 877 |
space (see "Whitespace" in perlrecharclass), and Posix classes (see |
| 878 |
"POSIX Character Classes" in perlrecharclass). Thus, this modifier |
| 879 |
doesn't mean you can't use Unicode, it means that to get Unicode |
| 880 |
matching you must explicitly use a construct (\f(CW\*(C`\ep{}\*(C'\fR, \f(CW\*(C`\eP{}\*(C'\fR) that |
| 881 |
signals Unicode. |
| 882 |
.PP |
| 883 |
As you would expect, this modifier causes, for example, \f(CW\*(C`\eD\*(C'\fR to mean |
| 884 |
the same thing as \f(CW\*(C`[^0\-9]\*(C'\fR; in fact, all non-ASCII characters match |
| 885 |
\&\f(CW\*(C`\eD\*(C'\fR, \f(CW\*(C`\eS\*(C'\fR, and \f(CW\*(C`\eW\*(C'\fR. \f(CW\*(C`\eb\*(C'\fR still means to match at the boundary |
| 886 |
between \f(CW\*(C`\ew\*(C'\fR and \f(CW\*(C`\eW\*(C'\fR, using the \f(CW\*(C`/a\*(C'\fR definitions of them (similarly |
| 887 |
for \f(CW\*(C`\eB\*(C'\fR). |
| 888 |
.PP |
| 889 |
Otherwise, \f(CW\*(C`/a\*(C'\fR behaves like the \f(CW\*(C`/u\*(C'\fR modifier, in that |
| 890 |
case-insensitive matching uses Unicode rules; for example, "k" will |
| 891 |
match the Unicode \f(CW\*(C`\eN{KELVIN SIGN}\*(C'\fR under \f(CW\*(C`/i\*(C'\fR matching, and code |
| 892 |
points in the Latin1 range, above ASCII will have Unicode rules when it |
| 893 |
comes to case-insensitive matching. |
| 894 |
.PP |
| 895 |
To forbid ASCII/non\-ASCII matches (like "k" with \f(CW\*(C`\eN{KELVIN SIGN}\*(C'\fR), |
| 896 |
specify the \f(CW"a"\fR twice, for example \f(CW\*(C`/aai\*(C'\fR or \f(CW\*(C`/aia\*(C'\fR. (The first |
| 897 |
occurrence of \f(CW"a"\fR restricts the \f(CW\*(C`\ed\*(C'\fR, \fIetc\fR., and the second occurrence |
| 898 |
adds the \f(CW\*(C`/i\*(C'\fR restrictions.) But, note that code points outside the |
| 899 |
ASCII range will use Unicode rules for \f(CW\*(C`/i\*(C'\fR matching, so the modifier |
| 900 |
doesn't really restrict things to just ASCII; it just forbids the |
| 901 |
intermixing of ASCII and non-ASCII. |
| 902 |
.PP |
| 903 |
To summarize, this modifier provides protection for applications that |
| 904 |
don't wish to be exposed to all of Unicode. Specifying it twice |
| 905 |
gives added protection. |
| 906 |
.PP |
| 907 |
This modifier may be specified to be the default by \f(CW\*(C`use re \*(Aq/a\*(Aq\*(C'\fR |
| 908 |
or \f(CW\*(C`use re \*(Aq/aa\*(Aq\*(C'\fR. If you do so, you may actually have occasion to use |
| 909 |
the \f(CW\*(C`/u\*(C'\fR modifier explicitly if there are a few regular expressions |
| 910 |
where you do want full Unicode rules (but even here, it's best if |
| 911 |
everything were under feature \f(CW"unicode_strings"\fR, along with the |
| 912 |
\&\f(CW\*(C`use re \*(Aq/aa\*(Aq\*(C'\fR). Also see "Which character set modifier is in |
| 913 |
effect?". |
| 914 |
.IX Xref " a aa" |
| 915 |
.PP |
| 916 |
Which character set modifier is in effect? |
| 917 |
.IX Subsection "Which character set modifier is in effect?" |
| 918 |
.PP |
| 919 |
Which of these modifiers is in effect at any given point in a regular |
| 920 |
expression depends on a fairly complex set of interactions. These have |
| 921 |
been designed so that in general you don't have to worry about it, but |
| 922 |
this section gives the gory details. As |
| 923 |
explained below in "Extended Patterns" it is possible to explicitly |
| 924 |
specify modifiers that apply only to portions of a regular expression. |
| 925 |
The innermost always has priority over any outer ones, and one applying |
| 926 |
to the whole expression has priority over any of the default settings that are |
| 927 |
described in the remainder of this section. |
| 928 |
.PP |
| 929 |
The \f(CW\*(C`use re \*(Aq/foo\*(Aq\*(C'\fR pragma can be used to set |
| 930 |
default modifiers (including these) for regular expressions compiled |
| 931 |
within its scope. This pragma has precedence over the other pragmas |
| 932 |
listed below that also change the defaults. Note that the /x modifier does |
| 933 |
NOT affect \f(CW\*(C`split STR\*(C'\fR patterns. |
| 934 |
.PP |
| 935 |
Otherwise, \f(CW\*(C`use locale\*(C'\fR sets the default modifier to \f(CW\*(C`/l\*(C'\fR; |
| 936 |
and \f(CW\*(C`use feature \*(Aqunicode_strings\*(C'\fR, or |
| 937 |
\&\f(CW\*(C`use v5.12\*(C'\fR (or higher) set the default to |
| 938 |
\&\f(CW\*(C`/u\*(C'\fR when not in the same scope as either \f(CW\*(C`use locale\*(C'\fR |
| 939 |
or \f(CW\*(C`use bytes\*(C'\fR. |
| 940 |
(\f(CW\*(C`use locale \*(Aq:not_characters\*(Aq\*(C'\fR also |
| 941 |
sets the default to \f(CW\*(C`/u\*(C'\fR, overriding any plain \f(CW\*(C`use locale\*(C'\fR.) |
| 942 |
Unlike the mechanisms mentioned above, these |
| 943 |
affect operations besides regular expressions pattern matching, and so |
| 944 |
give more consistent results with other operators, including using |
| 945 |
\&\f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \fIetc\fR. in substitution replacements. |
| 946 |
.PP |
| 947 |
If none of the above apply, for backwards compatibility reasons, the |
| 948 |
\&\f(CW\*(C`/d\*(C'\fR modifier is the one in effect by default. As this can lead to |
| 949 |
unexpected results, it is best to specify which other rule set should be |
| 950 |
used. |
| 951 |
.PP |
| 952 |
Character set modifier behavior prior to Perl 5.14 |
| 953 |
.IX Subsection "Character set modifier behavior prior to Perl 5.14" |
| 954 |
.PP |
| 955 |
Prior to 5.14, there were no explicit modifiers, but \f(CW\*(C`/l\*(C'\fR was implied |
| 956 |
for regexes compiled within the scope of \f(CW\*(C`use locale\*(C'\fR, and \f(CW\*(C`/d\*(C'\fR was |
| 957 |
implied otherwise. However, interpolating a regex into a larger regex |
| 958 |
would ignore the original compilation in favor of whatever was in effect |
| 959 |
at the time of the second compilation. There were a number of |
| 960 |
inconsistencies (bugs) with the \f(CW\*(C`/d\*(C'\fR modifier, where Unicode rules |
| 961 |
would be used when inappropriate, and vice versa. \f(CW\*(C`\ep{}\*(C'\fR did not imply |
| 962 |
Unicode rules, and neither did all occurrences of \f(CW\*(C`\eN{}\*(C'\fR, until 5.12. |
| 963 |
.SS "Regular Expressions" |
| 964 |
.IX Subsection "Regular Expressions" |
| 965 |
\fIQuantifiers\fR |
| 966 |
.IX Subsection "Quantifiers" |
| 967 |
.PP |
| 968 |
Quantifiers are used when a particular portion of a pattern needs to |
| 969 |
match a certain number (or numbers) of times. If there isn't a |
| 970 |
quantifier the number of times to match is exactly one. The following |
| 971 |
standard quantifiers are recognized: |
| 972 |
.IX Xref "metacharacter quantifier * + ? {n} {n,} {n,m}" |
| 973 |
.PP |
| 974 |
.Vb 7 |
| 975 |
\& * Match 0 or more times |
| 976 |
\& + Match 1 or more times |
| 977 |
\& ? Match 1 or 0 times |
| 978 |
\& {n} Match exactly n times |
| 979 |
\& {n,} Match at least n times |
| 980 |
\& {,n} Match at most n times |
| 981 |
\& {n,m} Match at least n but not more than m times |
| 982 |
.Ve |
| 983 |
.PP |
| 984 |
(If a non-escaped curly bracket occurs in a context other than one of |
| 985 |
the quantifiers listed above, where it does not form part of a |
| 986 |
backslashed sequence like \f(CW\*(C`\ex{...}\*(C'\fR, it is either a fatal syntax error, |
| 987 |
or treated as a regular character, generally with a deprecation warning |
| 988 |
raised. To escape it, you can precede it with a backslash (\f(CW"\e{"\fR) or |
| 989 |
enclose it within square brackets (\f(CW"[{]"\fR). |
| 990 |
This change will allow for future syntax extensions (like making the |
| 991 |
lower bound of a quantifier optional), and better error checking of |
| 992 |
quantifiers). |
| 993 |
.PP |
| 994 |
The \f(CW"*"\fR quantifier is equivalent to \f(CW\*(C`{0,}\*(C'\fR, the \f(CW"+"\fR |
| 995 |
quantifier to \f(CW\*(C`{1,}\*(C'\fR, and the \f(CW"?"\fR quantifier to \f(CW\*(C`{0,1}\*(C'\fR. \fIn\fR and \fIm\fR are limited |
| 996 |
to non-negative integral values less than a preset limit defined when perl is built. |
| 997 |
This is usually 65534 on the most common platforms. The actual limit can |
| 998 |
be seen in the error message generated by code such as this: |
| 999 |
.PP |
| 1000 |
.Vb 1 |
| 1001 |
\& $_ **= $_ , / {$_} / for 2 .. 42; |
| 1002 |
.Ve |
| 1003 |
.PP |
| 1004 |
By default, a quantified subpattern is "greedy", that is, it will match as |
| 1005 |
many times as possible (given a particular starting location) while still |
| 1006 |
allowing the rest of the pattern to match. If you want it to match the |
| 1007 |
minimum number of times possible, follow the quantifier with a \f(CW"?"\fR. Note |
| 1008 |
that the meanings don't change, just the "greediness": |
| 1009 |
.IX Xref "metacharacter greedy greediness ? *? +? ?? {n}? {n,}? {,n}? {n,m}?" |
| 1010 |
.PP |
| 1011 |
.Vb 7 |
| 1012 |
\& *? Match 0 or more times, not greedily |
| 1013 |
\& +? Match 1 or more times, not greedily |
| 1014 |
\& ?? Match 0 or 1 time, not greedily |
| 1015 |
\& {n}? Match exactly n times, not greedily (redundant) |
| 1016 |
\& {n,}? Match at least n times, not greedily |
| 1017 |
\& {,n}? Match at most n times, not greedily |
| 1018 |
\& {n,m}? Match at least n but not more than m times, not greedily |
| 1019 |
.Ve |
| 1020 |
.PP |
| 1021 |
Normally when a quantified subpattern does not allow the rest of the |
| 1022 |
overall pattern to match, Perl will backtrack. However, this behaviour is |
| 1023 |
sometimes undesirable. Thus Perl provides the "possessive" quantifier form |
| 1024 |
as well. |
| 1025 |
.PP |
| 1026 |
.Vb 7 |
| 1027 |
\& *+ Match 0 or more times and give nothing back |
| 1028 |
\& ++ Match 1 or more times and give nothing back |
| 1029 |
\& ?+ Match 0 or 1 time and give nothing back |
| 1030 |
\& {n}+ Match exactly n times and give nothing back (redundant) |
| 1031 |
\& {n,}+ Match at least n times and give nothing back |
| 1032 |
\& {,n}+ Match at most n times and give nothing back |
| 1033 |
\& {n,m}+ Match at least n but not more than m times and give nothing back |
| 1034 |
.Ve |
| 1035 |
.PP |
| 1036 |
For instance, |
| 1037 |
.PP |
| 1038 |
.Vb 1 |
| 1039 |
\& \*(Aqaaaa\*(Aq =~ /a++a/ |
| 1040 |
.Ve |
| 1041 |
.PP |
| 1042 |
will never match, as the \f(CW\*(C`a++\*(C'\fR will gobble up all the \f(CW"a"\fR's in the |
| 1043 |
string and won't leave any for the remaining part of the pattern. This |
| 1044 |
feature can be extremely useful to give perl hints about where it |
| 1045 |
shouldn't backtrack. For instance, the typical "match a double-quoted |
| 1046 |
string" problem can be most efficiently performed when written as: |
| 1047 |
.PP |
| 1048 |
.Vb 1 |
| 1049 |
\& /"(?:[^"\e\e]++|\e\e.)*+"/ |
| 1050 |
.Ve |
| 1051 |
.PP |
| 1052 |
as we know that if the final quote does not match, backtracking will not |
| 1053 |
help. See the independent subexpression |
| 1054 |
\&\f(CW"(?>\fR\f(CIpattern\fR\f(CW)"\fR for more details; |
| 1055 |
possessive quantifiers are just syntactic sugar for that construct. For |
| 1056 |
instance the above example could also be written as follows: |
| 1057 |
.PP |
| 1058 |
.Vb 1 |
| 1059 |
\& /"(?>(?:(?>[^"\e\e]+)|\e\e.)*)"/ |
| 1060 |
.Ve |
| 1061 |
.PP |
| 1062 |
Note that the possessive quantifier modifier can not be combined |
| 1063 |
with the non-greedy modifier. This is because it would make no sense. |
| 1064 |
Consider the follow equivalency table: |
| 1065 |
.PP |
| 1066 |
.Vb 5 |
| 1067 |
\& Illegal Legal |
| 1068 |
\& \-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- |
| 1069 |
\& X??+ X{0} |
| 1070 |
\& X+?+ X{1} |
| 1071 |
\& X{min,max}?+ X{min} |
| 1072 |
.Ve |
| 1073 |
.PP |
| 1074 |
\fIEscape sequences\fR |
| 1075 |
.IX Subsection "Escape sequences" |
| 1076 |
.PP |
| 1077 |
Because patterns are processed as double-quoted strings, the following |
| 1078 |
also work: |
| 1079 |
.PP |
| 1080 |
.Vb 10 |
| 1081 |
\& \et tab (HT, TAB) |
| 1082 |
\& \en newline (LF, NL) |
| 1083 |
\& \er return (CR) |
| 1084 |
\& \ef form feed (FF) |
| 1085 |
\& \ea alarm (bell) (BEL) |
| 1086 |
\& \ee escape (think troff) (ESC) |
| 1087 |
\& \ecK control char (example: VT) |
| 1088 |
\& \ex{}, \ex00 character whose ordinal is the given hexadecimal number |
| 1089 |
\& \eN{name} named Unicode character or character sequence |
| 1090 |
\& \eN{U+263D} Unicode character (example: FIRST QUARTER MOON) |
| 1091 |
\& \eo{}, \e000 character whose ordinal is the given octal number |
| 1092 |
\& \el lowercase next char (think vi) |
| 1093 |
\& \eu uppercase next char (think vi) |
| 1094 |
\& \eL lowercase until \eE (think vi) |
| 1095 |
\& \eU uppercase until \eE (think vi) |
| 1096 |
\& \eQ quote (disable) pattern metacharacters until \eE |
| 1097 |
\& \eE end either case modification or quoted section, think vi |
| 1098 |
.Ve |
| 1099 |
.PP |
| 1100 |
Details are in "Quote and Quote-like Operators" in perlop. |
| 1101 |
.PP |
| 1102 |
\fICharacter Classes and other Special Escapes\fR |
| 1103 |
.IX Subsection "Character Classes and other Special Escapes" |
| 1104 |
.PP |
| 1105 |
In addition, Perl defines the following: |
| 1106 |
.IX Xref "\\g \\k \\K backreference" |
| 1107 |
.PP |
| 1108 |
.Vb 10 |
| 1109 |
\& Sequence Note Description |
| 1110 |
\& [...] [1] Match a character according to the rules of the |
| 1111 |
\& bracketed character class defined by the "...". |
| 1112 |
\& Example: [a\-z] matches "a" or "b" or "c" ... or "z" |
| 1113 |
\& [[:...:]] [2] Match a character according to the rules of the POSIX |
| 1114 |
\& character class "..." within the outer bracketed |
| 1115 |
\& character class. Example: [[:upper:]] matches any |
| 1116 |
\& uppercase character. |
| 1117 |
\& (?[...]) [8] Extended bracketed character class |
| 1118 |
\& \ew [3] Match a "word" character (alphanumeric plus "_", plus |
| 1119 |
\& other connector punctuation chars plus Unicode |
| 1120 |
\& marks) |
| 1121 |
\& \eW [3] Match a non\-"word" character |
| 1122 |
\& \es [3] Match a whitespace character |
| 1123 |
\& \eS [3] Match a non\-whitespace character |
| 1124 |
\& \ed [3] Match a decimal digit character |
| 1125 |
\& \eD [3] Match a non\-digit character |
| 1126 |
\& \epP [3] Match P, named property. Use \ep{Prop} for longer names |
| 1127 |
\& \ePP [3] Match non\-P |
| 1128 |
\& \eX [4] Match Unicode "eXtended grapheme cluster" |
| 1129 |
\& \e1 [5] Backreference to a specific capture group or buffer. |
| 1130 |
\& \*(Aq1\*(Aq may actually be any positive integer. |
| 1131 |
\& \eg1 [5] Backreference to a specific or previous group, |
| 1132 |
\& \eg{\-1} [5] The number may be negative indicating a relative |
| 1133 |
\& previous group and may optionally be wrapped in |
| 1134 |
\& curly brackets for safer parsing. |
| 1135 |
\& \eg{name} [5] Named backreference |
| 1136 |
\& \ek<name> [5] Named backreference |
| 1137 |
\& \ek\*(Aqname\*(Aq [5] Named backreference |
| 1138 |
\& \ek{name} [5] Named backreference |
| 1139 |
\& \eK [6] Keep the stuff left of the \eK, don\*(Aqt include it in $& |
| 1140 |
\& \eN [7] Any character but \en. Not affected by /s modifier |
| 1141 |
\& \ev [3] Vertical whitespace |
| 1142 |
\& \eV [3] Not vertical whitespace |
| 1143 |
\& \eh [3] Horizontal whitespace |
| 1144 |
\& \eH [3] Not horizontal whitespace |
| 1145 |
\& \eR [4] Linebreak |
| 1146 |
.Ve |
| 1147 |
.IP [1] 4 |
| 1148 |
.IX Item "[1]" |
| 1149 |
See "Bracketed Character Classes" in perlrecharclass for details. |
| 1150 |
.IP [2] 4 |
| 1151 |
.IX Item "[2]" |
| 1152 |
See "POSIX Character Classes" in perlrecharclass for details. |
| 1153 |
.IP [3] 4 |
| 1154 |
.IX Item "[3]" |
| 1155 |
See "Unicode Character Properties" in perlunicode for details |
| 1156 |
.IP [4] 4 |
| 1157 |
.IX Item "[4]" |
| 1158 |
See "Misc" in perlrebackslash for details. |
| 1159 |
.IP [5] 4 |
| 1160 |
.IX Item "[5]" |
| 1161 |
See "Capture groups" below for details. |
| 1162 |
.IP [6] 4 |
| 1163 |
.IX Item "[6]" |
| 1164 |
See "Extended Patterns" below for details. |
| 1165 |
.IP [7] 4 |
| 1166 |
.IX Item "[7]" |
| 1167 |
Note that \f(CW\*(C`\eN\*(C'\fR has two meanings. When of the form \f(CW\*(C`\eN{\fR\f(CINAME\fR\f(CW}\*(C'\fR, it |
| 1168 |
matches the character or character sequence whose name is \fINAME\fR; and |
| 1169 |
similarly |
| 1170 |
when of the form \f(CW\*(C`\eN{U+\fR\f(CIhex\fR\f(CW}\*(C'\fR, it matches the character whose Unicode |
| 1171 |
code point is \fIhex\fR. Otherwise it matches any character but \f(CW\*(C`\en\*(C'\fR. |
| 1172 |
.IP [8] 4 |
| 1173 |
.IX Item "[8]" |
| 1174 |
See "Extended Bracketed Character Classes" in perlrecharclass for details. |
| 1175 |
.PP |
| 1176 |
\fIAssertions\fR |
| 1177 |
.IX Subsection "Assertions" |
| 1178 |
.PP |
| 1179 |
Besides \f(CW"^"\fR and \f(CW"$"\fR, Perl defines the following |
| 1180 |
zero-width assertions: |
| 1181 |
.IX Xref "zero-width assertion assertion regex, zero-width assertion regexp, zero-width assertion regular expression, zero-width assertion \\b \\B \\A \\Z \\z \\G" |
| 1182 |
.PP |
| 1183 |
.Vb 9 |
| 1184 |
\& \eb{} Match at Unicode boundary of specified type |
| 1185 |
\& \eB{} Match where corresponding \eb{} doesn\*(Aqt match |
| 1186 |
\& \eb Match a \ew\eW or \eW\ew boundary |
| 1187 |
\& \eB Match except at a \ew\eW or \eW\ew boundary |
| 1188 |
\& \eA Match only at beginning of string |
| 1189 |
\& \eZ Match only at end of string, or before newline at the end |
| 1190 |
\& \ez Match only at end of string |
| 1191 |
\& \eG Match only at pos() (e.g. at the end\-of\-match position |
| 1192 |
\& of prior m//g) |
| 1193 |
.Ve |
| 1194 |
.PP |
| 1195 |
A Unicode boundary (\f(CW\*(C`\eb{}\*(C'\fR), available starting in v5.22, is a spot |
| 1196 |
between two characters, or before the first character in the string, or |
| 1197 |
after the final character in the string where certain criteria defined |
| 1198 |
by Unicode are met. See "\eb{}, \eb, \eB{}, \eB" in perlrebackslash for |
| 1199 |
details. |
| 1200 |
.PP |
| 1201 |
A word boundary (\f(CW\*(C`\eb\*(C'\fR) is a spot between two characters |
| 1202 |
that has a \f(CW\*(C`\ew\*(C'\fR on one side of it and a \f(CW\*(C`\eW\*(C'\fR on the other side |
| 1203 |
of it (in either order), counting the imaginary characters off the |
| 1204 |
beginning and end of the string as matching a \f(CW\*(C`\eW\*(C'\fR. (Within |
| 1205 |
character classes \f(CW\*(C`\eb\*(C'\fR represents backspace rather than a word |
| 1206 |
boundary, just as it normally does in any double-quoted string.) |
| 1207 |
The \f(CW\*(C`\eA\*(C'\fR and \f(CW\*(C`\eZ\*(C'\fR are just like \f(CW"^"\fR and \f(CW"$"\fR, except that they |
| 1208 |
won't match multiple times when the \f(CW\*(C`/m\*(C'\fR modifier is used, while |
| 1209 |
\&\f(CW"^"\fR and \f(CW"$"\fR will match at every internal line boundary. To match |
| 1210 |
the actual end of the string and not ignore an optional trailing |
| 1211 |
newline, use \f(CW\*(C`\ez\*(C'\fR. |
| 1212 |
.IX Xref "\\b \\A \\Z \\z m" |
| 1213 |
.PP |
| 1214 |
The \f(CW\*(C`\eG\*(C'\fR assertion can be used to chain global matches (using |
| 1215 |
\&\f(CW\*(C`m//g\*(C'\fR), as described in "Regexp Quote-Like Operators" in perlop. |
| 1216 |
It is also useful when writing \f(CW\*(C`lex\*(C'\fR\-like scanners, when you have |
| 1217 |
several patterns that you want to match against consequent substrings |
| 1218 |
of your string; see the previous reference. The actual location |
| 1219 |
where \f(CW\*(C`\eG\*(C'\fR will match can also be influenced by using \f(CWpos()\fR as |
| 1220 |
an lvalue: see "pos" in perlfunc. Note that the rule for zero-length |
| 1221 |
matches (see "Repeated Patterns Matching a Zero-length Substring") |
| 1222 |
is modified somewhat, in that contents to the left of \f(CW\*(C`\eG\*(C'\fR are |
| 1223 |
not counted when determining the length of the match. Thus the following |
| 1224 |
will not match forever: |
| 1225 |
.IX Xref "\\G" |
| 1226 |
.PP |
| 1227 |
.Vb 5 |
| 1228 |
\& my $string = \*(AqABC\*(Aq; |
| 1229 |
\& pos($string) = 1; |
| 1230 |
\& while ($string =~ /(.\eG)/g) { |
| 1231 |
\& print $1; |
| 1232 |
\& } |
| 1233 |
.Ve |
| 1234 |
.PP |
| 1235 |
It will print 'A' and then terminate, as it considers the match to |
| 1236 |
be zero-width, and thus will not match at the same position twice in a |
| 1237 |
row. |
| 1238 |
.PP |
| 1239 |
It is worth noting that \f(CW\*(C`\eG\*(C'\fR improperly used can result in an infinite |
| 1240 |
loop. Take care when using patterns that include \f(CW\*(C`\eG\*(C'\fR in an alternation. |
| 1241 |
.PP |
| 1242 |
Note also that \f(CW\*(C`s///\*(C'\fR will refuse to overwrite part of a substitution |
| 1243 |
that has already been replaced; so for example this will stop after the |
| 1244 |
first iteration, rather than iterating its way backwards through the |
| 1245 |
string: |
| 1246 |
.PP |
| 1247 |
.Vb 4 |
| 1248 |
\& $_ = "123456789"; |
| 1249 |
\& pos = 6; |
| 1250 |
\& s/.(?=.\eG)/X/g; |
| 1251 |
\& print; # prints 1234X6789, not XXXXX6789 |
| 1252 |
.Ve |
| 1253 |
.PP |
| 1254 |
\fICapture groups\fR |
| 1255 |
.IX Subsection "Capture groups" |
| 1256 |
.PP |
| 1257 |
The grouping construct \f(CW\*(C`( ... )\*(C'\fR creates capture groups (also referred to as |
| 1258 |
capture buffers). To refer to the current contents of a group later on, within |
| 1259 |
the same pattern, use \f(CW\*(C`\eg1\*(C'\fR (or \f(CW\*(C`\eg{1}\*(C'\fR) for the first, \f(CW\*(C`\eg2\*(C'\fR (or \f(CW\*(C`\eg{2}\*(C'\fR) |
| 1260 |
for the second, and so on. |
| 1261 |
This is called a \fIbackreference\fR. |
| 1262 |
|
| 1263 |
|
| 1264 |
|
| 1265 |
|
| 1266 |
|
| 1267 |
|
| 1268 |
|
| 1269 |
|
| 1270 |
There is no limit to the number of captured substrings that you may use. |
| 1271 |
Groups are numbered with the leftmost open parenthesis being number 1, \fIetc\fR. If |
| 1272 |
a group did not match, the associated backreference won't match either. (This |
| 1273 |
can happen if the group is optional, or in a different branch of an |
| 1274 |
alternation.) |
| 1275 |
You can omit the \f(CW"g"\fR, and write \f(CW"\e1"\fR, \fIetc\fR, but there are some issues with |
| 1276 |
this form, described below. |
| 1277 |
.IX Xref "regex, capture buffer regexp, capture buffer regex, capture group regexp, capture group regular expression, capture buffer backreference regular expression, capture group backreference \\g{1} \\g{-1} \\g{name} relative backreference named backreference named capture buffer regular expression, named capture buffer named capture group regular expression, named capture group %+ $+{name} \\k<name>" |
| 1278 |
.PP |
| 1279 |
You can also refer to capture groups relatively, by using a negative number, so |
| 1280 |
that \f(CW\*(C`\eg\-1\*(C'\fR and \f(CW\*(C`\eg{\-1}\*(C'\fR both refer to the immediately preceding capture |
| 1281 |
group, and \f(CW\*(C`\eg\-2\*(C'\fR and \f(CW\*(C`\eg{\-2}\*(C'\fR both refer to the group before it. For |
| 1282 |
example: |
| 1283 |
.PP |
| 1284 |
.Vb 8 |
| 1285 |
\& / |
| 1286 |
\& (Y) # group 1 |
| 1287 |
\& ( # group 2 |
| 1288 |
\& (X) # group 3 |
| 1289 |
\& \eg{\-1} # backref to group 3 |
| 1290 |
\& \eg{\-3} # backref to group 1 |
| 1291 |
\& ) |
| 1292 |
\& /x |
| 1293 |
.Ve |
| 1294 |
.PP |
| 1295 |
would match the same as \f(CW\*(C`/(Y) ( (X) \eg3 \eg1 )/x\*(C'\fR. This allows you to |
| 1296 |
interpolate regexes into larger regexes and not have to worry about the |
| 1297 |
capture groups being renumbered. |
| 1298 |
.PP |
| 1299 |
You can dispense with numbers altogether and create named capture groups. |
| 1300 |
The notation is \f(CW\*(C`(?<\fR\f(CIname\fR\f(CW>...)\*(C'\fR to declare and \f(CW\*(C`\eg{\fR\f(CIname\fR\f(CW}\*(C'\fR to |
| 1301 |
reference. (To be compatible with .Net regular expressions, \f(CW\*(C`\eg{\fR\f(CIname\fR\f(CW}\*(C'\fR may |
| 1302 |
also be written as \f(CW\*(C`\ek{\fR\f(CIname\fR\f(CW}\*(C'\fR, \f(CW\*(C`\ek<\fR\f(CIname\fR\f(CW>\*(C'\fR or \f(CW\*(C`\ek\*(Aq\fR\f(CIname\fR\f(CW\*(Aq\*(C'\fR.) |
| 1303 |
\&\fIname\fR must not begin with a number, nor contain hyphens. |
| 1304 |
When different groups within the same pattern have the same name, any reference |
| 1305 |
to that name assumes the leftmost defined group. Named groups count in |
| 1306 |
absolute and relative numbering, and so can also be referred to by those |
| 1307 |
numbers. |
| 1308 |
(It's possible to do things with named capture groups that would otherwise |
| 1309 |
require \f(CW\*(C`(??{})\*(C'\fR.) |
| 1310 |
.PP |
| 1311 |
Capture group contents are dynamically scoped and available to you outside the |
| 1312 |
pattern until the end of the enclosing block or until the next successful |
| 1313 |
match in the same scope, whichever comes first. |
| 1314 |
See "Compound Statements" in perlsyn and |
| 1315 |
"Scoping Rules of Regex Variables" in perlvar for more details. |
| 1316 |
.PP |
| 1317 |
You can access the contents of a capture group by absolute number (using |
| 1318 |
\&\f(CW"$1"\fR instead of \f(CW"\eg1"\fR, \fIetc\fR); or by name via the \f(CW\*(C`%+\*(C'\fR hash, |
| 1319 |
using \f(CW"$+{\fR\f(CIname\fR\f(CW}"\fR. |
| 1320 |
.PP |
| 1321 |
Braces are required in referring to named capture groups, but are optional for |
| 1322 |
absolute or relative numbered ones. Braces are safer when creating a regex by |
| 1323 |
concatenating smaller strings. For example if you have \f(CW\*(C`qr/$x$y/\*(C'\fR, and \f(CW$x\fR |
| 1324 |
contained \f(CW"\eg1"\fR, and \f(CW$y\fR contained \f(CW"37"\fR, you would get \f(CW\*(C`/\eg137/\*(C'\fR which |
| 1325 |
is probably not what you intended. |
| 1326 |
.PP |
| 1327 |
If you use braces, you may also optionally add any number of blank |
| 1328 |
(space or tab) characters within but adjacent to the braces, like |
| 1329 |
\&\f(CW\*(C`\eg{\ \-1\ }\*(C'\fR, or \f(CW\*(C`\ek{\ \fR\f(CIname\fR\f(CW\ }\*(C'\fR. |
| 1330 |
.PP |
| 1331 |
The \f(CW\*(C`\eg\*(C'\fR and \f(CW\*(C`\ek\*(C'\fR notations were introduced in Perl 5.10.0. Prior to that |
| 1332 |
there were no named nor relative numbered capture groups. Absolute numbered |
| 1333 |
groups were referred to using \f(CW\*(C`\e1\*(C'\fR, |
| 1334 |
\&\f(CW\*(C`\e2\*(C'\fR, \fIetc\fR., and this notation is still |
| 1335 |
accepted (and likely always will be). But it leads to some ambiguities if |
| 1336 |
there are more than 9 capture groups, as \f(CW\*(C`\e10\*(C'\fR could mean either the tenth |
| 1337 |
capture group, or the character whose ordinal in octal is 010 (a backspace in |
| 1338 |
ASCII). Perl resolves this ambiguity by interpreting \f(CW\*(C`\e10\*(C'\fR as a backreference |
| 1339 |
only if at least 10 left parentheses have opened before it. Likewise \f(CW\*(C`\e11\*(C'\fR is |
| 1340 |
a backreference only if at least 11 left parentheses have opened before it. |
| 1341 |
And so on. \f(CW\*(C`\e1\*(C'\fR through \f(CW\*(C`\e9\*(C'\fR are always interpreted as backreferences. |
| 1342 |
There are several examples below that illustrate these perils. You can avoid |
| 1343 |
the ambiguity by always using \f(CW\*(C`\eg{}\*(C'\fR or \f(CW\*(C`\eg\*(C'\fR if you mean capturing groups; |
| 1344 |
and for octal constants always using \f(CW\*(C`\eo{}\*(C'\fR, or for \f(CW\*(C`\e077\*(C'\fR and below, using 3 |
| 1345 |
digits padded with leading zeros, since a leading zero implies an octal |
| 1346 |
constant. |
| 1347 |
.PP |
| 1348 |
The \f(CW\*(C`\e\fR\f(CIdigit\fR\f(CW\*(C'\fR notation also works in certain circumstances outside |
| 1349 |
the pattern. See "Warning on \e1 Instead of \f(CW$1\fR" below for details. |
| 1350 |
.PP |
| 1351 |
Examples: |
| 1352 |
.PP |
| 1353 |
.Vb 1 |
| 1354 |
\& s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two words |
| 1355 |
\& |
| 1356 |
\& /(.)\eg1/ # find first doubled char |
| 1357 |
\& and print "\*(Aq$1\*(Aq is the first doubled character\en"; |
| 1358 |
\& |
| 1359 |
\& /(?<char>.)\ek<char>/ # ... a different way |
| 1360 |
\& and print "\*(Aq$+{char}\*(Aq is the first doubled character\en"; |
| 1361 |
\& |
| 1362 |
\& /(?\*(Aqchar\*(Aq.)\eg1/ # ... mix and match |
| 1363 |
\& and print "\*(Aq$1\*(Aq is the first doubled character\en"; |
| 1364 |
\& |
| 1365 |
\& if (/Time: (..):(..):(..)/) { # parse out values |
| 1366 |
\& $hours = $1; |
| 1367 |
\& $minutes = $2; |
| 1368 |
\& $seconds = $3; |
| 1369 |
\& } |
| 1370 |
\& |
| 1371 |
\& /(.)(.)(.)(.)(.)(.)(.)(.)(.)\eg10/ # \eg10 is a backreference |
| 1372 |
\& /(.)(.)(.)(.)(.)(.)(.)(.)(.)\e10/ # \e10 is octal |
| 1373 |
\& /((.)(.)(.)(.)(.)(.)(.)(.)(.))\e10/ # \e10 is a backreference |
| 1374 |
\& /((.)(.)(.)(.)(.)(.)(.)(.)(.))\e010/ # \e010 is octal |
| 1375 |
\& |
| 1376 |
\& $x = \*(Aq(.)\e1\*(Aq; # Creates problems when concatenated. |
| 1377 |
\& $y = \*(Aq(.)\eg{1}\*(Aq; # Avoids the problems. |
| 1378 |
\& "aa" =~ /${x}/; # True |
| 1379 |
\& "aa" =~ /${y}/; # True |
| 1380 |
\& "aa0" =~ /${x}0/; # False! |
| 1381 |
\& "aa0" =~ /${y}0/; # True |
| 1382 |
\& "aa\ex08" =~ /${x}0/; # True! |
| 1383 |
\& "aa\ex08" =~ /${y}0/; # False |
| 1384 |
.Ve |
| 1385 |
.PP |
| 1386 |
Several special variables also refer back to portions of the previous |
| 1387 |
match. \f(CW$+\fR returns whatever the last bracket match matched. |
| 1388 |
\&\f(CW$&\fR returns the entire matched string. (At one point \f(CW$0\fR did |
| 1389 |
also, but now it returns the name of the program.) \f(CW\*(C`$\`\*(C'\fR returns |
| 1390 |
everything before the matched string. \f(CW\*(C`$\*(Aq\*(C'\fR returns everything |
| 1391 |
after the matched string. And \f(CW$^N\fR contains whatever was matched by |
| 1392 |
the most-recently closed group (submatch). \f(CW$^N\fR can be used in |
| 1393 |
extended patterns (see below), for example to assign a submatch to a |
| 1394 |
variable. |
| 1395 |
.IX Xref "$+ $^N $& $` $'" |
| 1396 |
.PP |
| 1397 |
These special variables, like the \f(CW\*(C`%+\*(C'\fR hash and the numbered match variables |
| 1398 |
(\f(CW$1\fR, \f(CW$2\fR, \f(CW$3\fR, \fIetc\fR.) are dynamically scoped |
| 1399 |
until the end of the enclosing block or until the next successful |
| 1400 |
match, whichever comes first. (See "Compound Statements" in perlsyn.) |
| 1401 |
.IX Xref "$+ $^N $& $` $' $1 $2 $3 $4 $5 $6 $7 $8 $9 @{^CAPTURE}" |
| 1402 |
.PP |
| 1403 |
The \f(CW\*(C`@{^CAPTURE}\*(C'\fR array may be used to access ALL of the capture buffers |
| 1404 |
as an array without needing to know how many there are. For instance |
| 1405 |
.PP |
| 1406 |
.Vb 1 |
| 1407 |
\& $string=~/$pattern/ and @captured = @{^CAPTURE}; |
| 1408 |
.Ve |
| 1409 |
.PP |
| 1410 |
will place a copy of each capture variable, \f(CW$1\fR, \f(CW$2\fR etc, into the |
| 1411 |
\&\f(CW@captured\fR array. |
| 1412 |
.PP |
| 1413 |
Be aware that when interpolating a subscript of the \f(CW\*(C`@{^CAPTURE}\*(C'\fR |
| 1414 |
array you must use demarcated curly brace notation: |
| 1415 |
.PP |
| 1416 |
.Vb 1 |
| 1417 |
\& print "${^CAPTURE[0]}"; |
| 1418 |
.Ve |
| 1419 |
.PP |
| 1420 |
See "Demarcated variable names using braces" in perldata for more on |
| 1421 |
this notation. |
| 1422 |
.PP |
| 1423 |
\&\fBNOTE\fR: Failed matches in Perl do not reset the match variables, |
| 1424 |
which makes it easier to write code that tests for a series of more |
| 1425 |
specific cases and remembers the best match. |
| 1426 |
.PP |
| 1427 |
\&\fBWARNING\fR: If your code is to run on Perl 5.16 or earlier, |
| 1428 |
beware that once Perl sees that you need one of \f(CW$&\fR, \f(CW\*(C`$\`\*(C'\fR, or |
| 1429 |
\&\f(CW\*(C`$\*(Aq\*(C'\fR anywhere in the program, it has to provide them for every |
| 1430 |
pattern match. This may substantially slow your program. |
| 1431 |
.PP |
| 1432 |
Perl uses the same mechanism to produce \f(CW$1\fR, \f(CW$2\fR, \fIetc\fR, so you also |
| 1433 |
pay a price for each pattern that contains capturing parentheses. |
| 1434 |
(To avoid this cost while retaining the grouping behaviour, use the |
| 1435 |
extended regular expression \f(CW\*(C`(?: ... )\*(C'\fR instead.) But if you never |
| 1436 |
use \f(CW$&\fR, \f(CW\*(C`$\`\*(C'\fR or \f(CW\*(C`$\*(Aq\*(C'\fR, then patterns \fIwithout\fR capturing |
| 1437 |
parentheses will not be penalized. So avoid \f(CW$&\fR, \f(CW\*(C`$\*(Aq\*(C'\fR, and \f(CW\*(C`$\`\*(C'\fR |
| 1438 |
if you can, but if you can't (and some algorithms really appreciate |
| 1439 |
them), once you've used them once, use them at will, because you've |
| 1440 |
already paid the price. |
| 1441 |
.IX Xref "$& $` $'" |
| 1442 |
.PP |
| 1443 |
Perl 5.16 introduced a slightly more efficient mechanism that notes |
| 1444 |
separately whether each of \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR, and \f(CW\*(C`$\*(Aq\*(C'\fR have been seen, and |
| 1445 |
thus may only need to copy part of the string. Perl 5.20 introduced a |
| 1446 |
much more efficient copy-on-write mechanism which eliminates any slowdown. |
| 1447 |
.PP |
| 1448 |
As another workaround for this problem, Perl 5.10.0 introduced \f(CW\*(C`${^PREMATCH}\*(C'\fR, |
| 1449 |
\&\f(CW\*(C`${^MATCH}\*(C'\fR and \f(CW\*(C`${^POSTMATCH}\*(C'\fR, which are equivalent to \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR |
| 1450 |
and \f(CW\*(C`$\*(Aq\*(C'\fR, \fBexcept\fR that they are only guaranteed to be defined after a |
| 1451 |
successful match that was executed with the \f(CW\*(C`/p\*(C'\fR (preserve) modifier. |
| 1452 |
The use of these variables incurs no global performance penalty, unlike |
| 1453 |
their punctuation character equivalents, however at the trade-off that you |
| 1454 |
have to tell perl when you want to use them. |
| 1455 |
.IX Xref " p p modifier" |
| 1456 |
.SS "Quoting metacharacters" |
| 1457 |
.IX Subsection "Quoting metacharacters" |
| 1458 |
Backslashed metacharacters in Perl are alphanumeric, such as \f(CW\*(C`\eb\*(C'\fR, |
| 1459 |
\&\f(CW\*(C`\ew\*(C'\fR, \f(CW\*(C`\en\*(C'\fR. Unlike some other regular expression languages, there |
| 1460 |
are no backslashed symbols that aren't alphanumeric. So anything |
| 1461 |
that looks like \f(CW\*(C`\e\e\*(C'\fR, \f(CW\*(C`\e(\*(C'\fR, \f(CW\*(C`\e)\*(C'\fR, \f(CW\*(C`\e[\*(C'\fR, \f(CW\*(C`\e]\*(C'\fR, \f(CW\*(C`\e{\*(C'\fR, or \f(CW\*(C`\e}\*(C'\fR is |
| 1462 |
always |
| 1463 |
interpreted as a literal character, not a metacharacter. This was |
| 1464 |
once used in a common idiom to disable or quote the special meanings |
| 1465 |
of regular expression metacharacters in a string that you want to |
| 1466 |
use for a pattern. Simply quote all non\-"word" characters: |
| 1467 |
.PP |
| 1468 |
.Vb 1 |
| 1469 |
\& $pattern =~ s/(\eW)/\e\e$1/g; |
| 1470 |
.Ve |
| 1471 |
.PP |
| 1472 |
(If \f(CW\*(C`use locale\*(C'\fR is set, then this depends on the current locale.) |
| 1473 |
Today it is more common to use the \f(CWquotemeta()\fR |
| 1474 |
function or the \f(CW\*(C`\eQ\*(C'\fR metaquoting escape sequence to disable all |
| 1475 |
metacharacters' special meanings like this: |
| 1476 |
.PP |
| 1477 |
.Vb 1 |
| 1478 |
\& /$unquoted\eQ$quoted\eE$unquoted/ |
| 1479 |
.Ve |
| 1480 |
.PP |
| 1481 |
Beware that if you put literal backslashes (those not inside |
| 1482 |
interpolated variables) between \f(CW\*(C`\eQ\*(C'\fR and \f(CW\*(C`\eE\*(C'\fR, double-quotish |
| 1483 |
backslash interpolation may lead to confusing results. If you |
| 1484 |
\&\fIneed\fR to use literal backslashes within \f(CW\*(C`\eQ...\eE\*(C'\fR, |
| 1485 |
consult "Gory details of parsing quoted constructs" in perlop. |
| 1486 |
.PP |
| 1487 |
\&\f(CWquotemeta()\fR and \f(CW\*(C`\eQ\*(C'\fR are fully described in "quotemeta" in perlfunc. |
| 1488 |
.SS "Extended Patterns" |
| 1489 |
.IX Subsection "Extended Patterns" |
| 1490 |
Perl also defines a consistent extension syntax for features not |
| 1491 |
found in standard tools like \fBawk\fR and |
| 1492 |
\&\fBlex\fR. The syntax for most of these is a |
| 1493 |
pair of parentheses with a question mark as the first thing within |
| 1494 |
the parentheses. The character after the question mark indicates |
| 1495 |
the extension. |
| 1496 |
.PP |
| 1497 |
A question mark was chosen for this and for the minimal-matching |
| 1498 |
construct because 1) question marks are rare in older regular |
| 1499 |
expressions, and 2) whenever you see one, you should stop and |
| 1500 |
"question" exactly what is going on. That's psychology.... |
| 1501 |
.ie n .IP """(?#\fItext\fR)""" 4 |
| 1502 |
.el .IP \f(CW(?#\fR\f(CItext\fR\f(CW)\fR 4 |
| 1503 |
.IX Xref "(?#)" |
| 1504 |
.IX Item "(?#text)" |
| 1505 |
A comment. The \fItext\fR is ignored. |
| 1506 |
Note that Perl closes |
| 1507 |
the comment as soon as it sees a \f(CW")"\fR, so there is no way to put a literal |
| 1508 |
\&\f(CW")"\fR in the comment. The pattern's closing delimiter must be escaped by |
| 1509 |
a backslash if it appears in the comment. |
| 1510 |
.Sp |
| 1511 |
See "/x" for another way to have comments in patterns. |
| 1512 |
.Sp |
| 1513 |
Note that a comment can go just about anywhere, except in the middle of |
| 1514 |
an escape sequence. Examples: |
| 1515 |
.Sp |
| 1516 |
.Vb 1 |
| 1517 |
\& qr/foo(?#comment)bar/\*(Aq # Matches \*(Aqfoobar\*(Aq |
| 1518 |
\& |
| 1519 |
\& # The pattern below matches \*(Aqabcd\*(Aq, \*(Aqabccd\*(Aq, or \*(Aqabcccd\*(Aq |
| 1520 |
\& qr/abc(?#comment between literal and its quantifier){1,3}d/ |
| 1521 |
\& |
| 1522 |
\& # The pattern below generates a syntax error, because the \*(Aq\ep\*(Aq must |
| 1523 |
\& # be followed immediately by a \*(Aq{\*(Aq. |
| 1524 |
\& qr/\ep(?#comment between \ep and its property name){Any}/ |
| 1525 |
\& |
| 1526 |
\& # The pattern below generates a syntax error, because the initial |
| 1527 |
\& # \*(Aq\e(\*(Aq is a literal opening parenthesis, and so there is nothing |
| 1528 |
\& # for the closing \*(Aq)\*(Aq to match |
| 1529 |
\& qr/\e(?#the backslash means this isn\*(Aqt a comment)p{Any}/ |
| 1530 |
\& |
| 1531 |
\& # Comments can be used to fold long patterns into multiple lines |
| 1532 |
\& qr/First part of a long regex(?# |
| 1533 |
\& )remaining part/ |
| 1534 |
.Ve |
| 1535 |
.ie n .IP """(?adlupimnsx\-imnsx)""" 4 |
| 1536 |
.el .IP \f(CW(?adlupimnsx\-imnsx)\fR 4 |
| 1537 |
.IX Item "(?adlupimnsx-imnsx)" |
| 1538 |
.PD 0 |
| 1539 |
.ie n .IP """(?^alupimnsx)""" 4 |
| 1540 |
.el .IP \f(CW(?^alupimnsx)\fR 4 |
| 1541 |
.IX Xref "(?) (?^)" |
| 1542 |
.IX Item "(?^alupimnsx)" |
| 1543 |
.PD |
| 1544 |
Zero or more embedded pattern-match modifiers, to be turned on (or |
| 1545 |
turned off if preceded by \f(CW"\-"\fR) for the remainder of the pattern or |
| 1546 |
the remainder of the enclosing pattern group (if any). |
| 1547 |
.Sp |
| 1548 |
This is particularly useful for dynamically-generated patterns, |
| 1549 |
such as those read in from a |
| 1550 |
configuration file, taken from an argument, or specified in a table |
| 1551 |
somewhere. Consider the case where some patterns want to be |
| 1552 |
case-sensitive and some do not: The case-insensitive ones merely need to |
| 1553 |
include \f(CW\*(C`(?i)\*(C'\fR at the front of the pattern. For example: |
| 1554 |
.Sp |
| 1555 |
.Vb 2 |
| 1556 |
\& $pattern = "foobar"; |
| 1557 |
\& if ( /$pattern/i ) { } |
| 1558 |
\& |
| 1559 |
\& # more flexible: |
| 1560 |
\& |
| 1561 |
\& $pattern = "(?i)foobar"; |
| 1562 |
\& if ( /$pattern/ ) { } |
| 1563 |
.Ve |
| 1564 |
.Sp |
| 1565 |
These modifiers are restored at the end of the enclosing group. For example, |
| 1566 |
.Sp |
| 1567 |
.Vb 1 |
| 1568 |
\& ( (?i) blah ) \es+ \eg1 |
| 1569 |
.Ve |
| 1570 |
.Sp |
| 1571 |
will match \f(CW\*(C`blah\*(C'\fR in any case, some spaces, and an exact (\fIincluding the case\fR!) |
| 1572 |
repetition of the previous word, assuming the \f(CW\*(C`/x\*(C'\fR modifier, and no \f(CW\*(C`/i\*(C'\fR |
| 1573 |
modifier outside this group. |
| 1574 |
.Sp |
| 1575 |
These modifiers do not carry over into named subpatterns called in the |
| 1576 |
enclosing group. In other words, a pattern such as \f(CW\*(C`((?i)(?&\fR\f(CINAME\fR\f(CW))\*(C'\fR does not |
| 1577 |
change the case-sensitivity of the \fINAME\fR pattern. |
| 1578 |
.Sp |
| 1579 |
A modifier is overridden by later occurrences of this construct in the |
| 1580 |
same scope containing the same modifier, so that |
| 1581 |
.Sp |
| 1582 |
.Vb 1 |
| 1583 |
\& /((?im)foo(?\-m)bar)/ |
| 1584 |
.Ve |
| 1585 |
.Sp |
| 1586 |
matches all of \f(CW\*(C`foobar\*(C'\fR case insensitively, but uses \f(CW\*(C`/m\*(C'\fR rules for |
| 1587 |
only the \f(CW\*(C`foo\*(C'\fR portion. The \f(CW"a"\fR flag overrides \f(CW\*(C`aa\*(C'\fR as well; |
| 1588 |
likewise \f(CW\*(C`aa\*(C'\fR overrides \f(CW"a"\fR. The same goes for \f(CW"x"\fR and \f(CW\*(C`xx\*(C'\fR. |
| 1589 |
Hence, in |
| 1590 |
.Sp |
| 1591 |
.Vb 1 |
| 1592 |
\& /(?\-x)foo/xx |
| 1593 |
.Ve |
| 1594 |
.Sp |
| 1595 |
both \f(CW\*(C`/x\*(C'\fR and \f(CW\*(C`/xx\*(C'\fR are turned off during matching \f(CW\*(C`foo\*(C'\fR. And in |
| 1596 |
.Sp |
| 1597 |
.Vb 1 |
| 1598 |
\& /(?x)foo/x |
| 1599 |
.Ve |
| 1600 |
.Sp |
| 1601 |
\&\f(CW\*(C`/x\*(C'\fR but NOT \f(CW\*(C`/xx\*(C'\fR is turned on for matching \f(CW\*(C`foo\*(C'\fR. (One might |
| 1602 |
mistakenly think that since the inner \f(CW\*(C`(?x)\*(C'\fR is already in the scope of |
| 1603 |
\&\f(CW\*(C`/x\*(C'\fR, that the result would effectively be the sum of them, yielding |
| 1604 |
\&\f(CW\*(C`/xx\*(C'\fR. It doesn't work that way.) Similarly, doing something like |
| 1605 |
\&\f(CW\*(C`(?xx\-x)foo\*(C'\fR turns off all \f(CW"x"\fR behavior for matching \f(CW\*(C`foo\*(C'\fR, it is not |
| 1606 |
that you subtract 1 \f(CW"x"\fR from 2 to get 1 \f(CW"x"\fR remaining. |
| 1607 |
.Sp |
| 1608 |
Any of these modifiers can be set to apply globally to all regular |
| 1609 |
expressions compiled within the scope of a \f(CW\*(C`use re\*(C'\fR. See |
| 1610 |
"'/flags' mode" in re. |
| 1611 |
.Sp |
| 1612 |
Starting in Perl 5.14, a \f(CW"^"\fR (caret or circumflex accent) immediately |
| 1613 |
after the \f(CW"?"\fR is a shorthand equivalent to \f(CW\*(C`d\-imnsx\*(C'\fR. Flags (except |
| 1614 |
\&\f(CW"d"\fR) may follow the caret to override it. |
| 1615 |
But a minus sign is not legal with it. |
| 1616 |
.Sp |
| 1617 |
Note that the \f(CW"a"\fR, \f(CW"d"\fR, \f(CW"l"\fR, \f(CW"p"\fR, and \f(CW"u"\fR modifiers are special in |
| 1618 |
that they can only be enabled, not disabled, and the \f(CW"a"\fR, \f(CW"d"\fR, \f(CW"l"\fR, and |
| 1619 |
\&\f(CW"u"\fR modifiers are mutually exclusive: specifying one de-specifies the |
| 1620 |
others, and a maximum of one (or two \f(CW"a"\fR's) may appear in the |
| 1621 |
construct. Thus, for |
| 1622 |
example, \f(CW\*(C`(?\-p)\*(C'\fR will warn when compiled under \f(CW\*(C`use warnings\*(C'\fR; |
| 1623 |
\&\f(CW\*(C`(?\-d:...)\*(C'\fR and \f(CW\*(C`(?dl:...)\*(C'\fR are fatal errors. |
| 1624 |
.Sp |
| 1625 |
Note also that the \f(CW"p"\fR modifier is special in that its presence |
| 1626 |
anywhere in a pattern has a global effect. |
| 1627 |
.Sp |
| 1628 |
Having zero modifiers makes this a no-op (so why did you specify it, |
| 1629 |
unless it's generated code), and starting in v5.30, warns under \f(CW\*(C`use |
| 1630 |
re \*(Aqstrict\*(Aq\*(C'\fR. |
| 1631 |
.ie n .IP """(?:\fIpattern\fR)""" 4 |
| 1632 |
.el .IP \f(CW(?:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1633 |
.IX Xref "(?:)" |
| 1634 |
.IX Item "(?:pattern)" |
| 1635 |
.PD 0 |
| 1636 |
.ie n .IP """(?adluimnsx\-imnsx:\fIpattern\fR)""" 4 |
| 1637 |
.el .IP \f(CW(?adluimnsx\-imnsx:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1638 |
.IX Item "(?adluimnsx-imnsx:pattern)" |
| 1639 |
.ie n .IP """(?^aluimnsx:\fIpattern\fR)""" 4 |
| 1640 |
.el .IP \f(CW(?^aluimnsx:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1641 |
.IX Xref "(?^:)" |
| 1642 |
.IX Item "(?^aluimnsx:pattern)" |
| 1643 |
.PD |
| 1644 |
This is for clustering, not capturing; it groups subexpressions like |
| 1645 |
\&\f(CW"()"\fR, but doesn't make backreferences as \f(CW"()"\fR does. So |
| 1646 |
.Sp |
| 1647 |
.Vb 1 |
| 1648 |
\& @fields = split(/\eb(?:a|b|c)\eb/) |
| 1649 |
.Ve |
| 1650 |
.Sp |
| 1651 |
matches the same field delimiters as |
| 1652 |
.Sp |
| 1653 |
.Vb 1 |
| 1654 |
\& @fields = split(/\eb(a|b|c)\eb/) |
| 1655 |
.Ve |
| 1656 |
.Sp |
| 1657 |
but doesn't spit out the delimiters themselves as extra fields (even though |
| 1658 |
that's the behaviour of "split" in perlfunc when its pattern contains capturing |
| 1659 |
groups). It's also cheaper not to capture |
| 1660 |
characters if you don't need to. |
| 1661 |
.Sp |
| 1662 |
Any letters between \f(CW"?"\fR and \f(CW":"\fR act as flags modifiers as with |
| 1663 |
\&\f(CW\*(C`(?adluimnsx\-imnsx)\*(C'\fR. For example, |
| 1664 |
.Sp |
| 1665 |
.Vb 1 |
| 1666 |
\& /(?s\-i:more.*than).*million/i |
| 1667 |
.Ve |
| 1668 |
.Sp |
| 1669 |
is equivalent to the more verbose |
| 1670 |
.Sp |
| 1671 |
.Vb 1 |
| 1672 |
\& /(?:(?s\-i)more.*than).*million/i |
| 1673 |
.Ve |
| 1674 |
.Sp |
| 1675 |
Note that any \f(CW\*(C`()\*(C'\fR constructs enclosed within this one will still |
| 1676 |
capture unless the \f(CW\*(C`/n\*(C'\fR modifier is in effect. |
| 1677 |
.Sp |
| 1678 |
Like the "(?adlupimnsx\-imnsx)" construct, \f(CW\*(C`aa\*(C'\fR and \f(CW"a"\fR override each |
| 1679 |
other, as do \f(CW\*(C`xx\*(C'\fR and \f(CW"x"\fR. They are not additive. So, doing |
| 1680 |
something like \f(CW\*(C`(?xx\-x:foo)\*(C'\fR turns off all \f(CW"x"\fR behavior for matching |
| 1681 |
\&\f(CW\*(C`foo\*(C'\fR. |
| 1682 |
.Sp |
| 1683 |
Starting in Perl 5.14, a \f(CW"^"\fR (caret or circumflex accent) immediately |
| 1684 |
after the \f(CW"?"\fR is a shorthand equivalent to \f(CW\*(C`d\-imnsx\*(C'\fR. Any positive |
| 1685 |
flags (except \f(CW"d"\fR) may follow the caret, so |
| 1686 |
.Sp |
| 1687 |
.Vb 1 |
| 1688 |
\& (?^x:foo) |
| 1689 |
.Ve |
| 1690 |
.Sp |
| 1691 |
is equivalent to |
| 1692 |
.Sp |
| 1693 |
.Vb 1 |
| 1694 |
\& (?x\-imns:foo) |
| 1695 |
.Ve |
| 1696 |
.Sp |
| 1697 |
The caret tells Perl that this cluster doesn't inherit the flags of any |
| 1698 |
surrounding pattern, but uses the system defaults (\f(CW\*(C`d\-imnsx\*(C'\fR), |
| 1699 |
modified by any flags specified. |
| 1700 |
.Sp |
| 1701 |
The caret allows for simpler stringification of compiled regular |
| 1702 |
expressions. These look like |
| 1703 |
.Sp |
| 1704 |
.Vb 1 |
| 1705 |
\& (?^:pattern) |
| 1706 |
.Ve |
| 1707 |
.Sp |
| 1708 |
with any non-default flags appearing between the caret and the colon. |
| 1709 |
A test that looks at such stringification thus doesn't need to have the |
| 1710 |
system default flags hard-coded in it, just the caret. If new flags are |
| 1711 |
added to Perl, the meaning of the caret's expansion will change to include |
| 1712 |
the default for those flags, so the test will still work, unchanged. |
| 1713 |
.Sp |
| 1714 |
Specifying a negative flag after the caret is an error, as the flag is |
| 1715 |
redundant. |
| 1716 |
.Sp |
| 1717 |
Mnemonic for \f(CW\*(C`(?^...)\*(C'\fR: A fresh beginning since the usual use of a caret is |
| 1718 |
to match at the beginning. |
| 1719 |
.ie n .IP """(?|\fIpattern\fR)""" 4 |
| 1720 |
.el .IP \f(CW(?|\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1721 |
.IX Xref "(?|) Branch reset" |
| 1722 |
.IX Item "(?|pattern)" |
| 1723 |
This is the "branch reset" pattern, which has the special property |
| 1724 |
that the capture groups are numbered from the same starting point |
| 1725 |
in each alternation branch. It is available starting from perl 5.10.0. |
| 1726 |
.Sp |
| 1727 |
Capture groups are numbered from left to right, but inside this |
| 1728 |
construct the numbering is restarted for each branch. |
| 1729 |
.Sp |
| 1730 |
The numbering within each branch will be as normal, and any groups |
| 1731 |
following this construct will be numbered as though the construct |
| 1732 |
contained only one branch, that being the one with the most capture |
| 1733 |
groups in it. |
| 1734 |
.Sp |
| 1735 |
This construct is useful when you want to capture one of a |
| 1736 |
number of alternative matches. |
| 1737 |
.Sp |
| 1738 |
Consider the following pattern. The numbers underneath show in |
| 1739 |
which group the captured content will be stored. |
| 1740 |
.Sp |
| 1741 |
.Vb 3 |
| 1742 |
\& # before \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-branch\-reset\-\-\-\-\-\-\-\-\-\-\- after |
| 1743 |
\& / ( a ) (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x |
| 1744 |
\& # 1 2 2 3 2 3 4 |
| 1745 |
.Ve |
| 1746 |
.Sp |
| 1747 |
Be careful when using the branch reset pattern in combination with |
| 1748 |
named captures. Named captures are implemented as being aliases to |
| 1749 |
numbered groups holding the captures, and that interferes with the |
| 1750 |
implementation of the branch reset pattern. If you are using named |
| 1751 |
captures in a branch reset pattern, it's best to use the same names, |
| 1752 |
in the same order, in each of the alternations: |
| 1753 |
.Sp |
| 1754 |
.Vb 2 |
| 1755 |
\& /(?| (?<a> x ) (?<b> y ) |
| 1756 |
\& | (?<a> z ) (?<b> w )) /x |
| 1757 |
.Ve |
| 1758 |
.Sp |
| 1759 |
Not doing so may lead to surprises: |
| 1760 |
.Sp |
| 1761 |
.Vb 3 |
| 1762 |
\& "12" =~ /(?| (?<a> \ed+ ) | (?<b> \eD+))/x; |
| 1763 |
\& say $+{a}; # Prints \*(Aq12\*(Aq |
| 1764 |
\& say $+{b}; # *Also* prints \*(Aq12\*(Aq. |
| 1765 |
.Ve |
| 1766 |
.Sp |
| 1767 |
The problem here is that both the group named \f(CW\*(C`a\*(C'\fR and the group |
| 1768 |
named \f(CW\*(C`b\*(C'\fR are aliases for the group belonging to \f(CW$1\fR. |
| 1769 |
.IP "Lookaround Assertions" 4 |
| 1770 |
.IX Xref "look-around assertion lookaround assertion look-around lookaround" |
| 1771 |
.IX Item "Lookaround Assertions" |
| 1772 |
Lookaround assertions are zero-width patterns which match a specific |
| 1773 |
pattern without including it in \f(CW$&\fR. Positive assertions match when |
| 1774 |
their subpattern matches, negative assertions match when their subpattern |
| 1775 |
fails. Lookbehind matches text up to the current match position, |
| 1776 |
lookahead matches text following the current match position. |
| 1777 |
.RS 4 |
| 1778 |
.ie n .IP """(?=\fIpattern\fR)""" 4 |
| 1779 |
.el .IP \f(CW(?=\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1780 |
.IX Item "(?=pattern)" |
| 1781 |
.PD 0 |
| 1782 |
.ie n .IP """(*pla:\fIpattern\fR)""" 4 |
| 1783 |
.el .IP \f(CW(*pla:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1784 |
.IX Item "(*pla:pattern)" |
| 1785 |
.ie n .IP """(*positive_lookahead:\fIpattern\fR)""" 4 |
| 1786 |
.el .IP \f(CW(*positive_lookahead:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1787 |
.IX Xref "(?=) (*pla (*positive_lookahead look-ahead, positive lookahead, positive" |
| 1788 |
.IX Item "(*positive_lookahead:pattern)" |
| 1789 |
.PD |
| 1790 |
A zero-width positive lookahead assertion. For example, \f(CW\*(C`/\ew+(?=\et)/\*(C'\fR |
| 1791 |
matches a word followed by a tab, without including the tab in \f(CW$&\fR. |
| 1792 |
.ie n .IP """(?!\fIpattern\fR)""" 4 |
| 1793 |
.el .IP \f(CW(?!\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1794 |
.IX Item "(?!pattern)" |
| 1795 |
.PD 0 |
| 1796 |
.ie n .IP """(*nla:\fIpattern\fR)""" 4 |
| 1797 |
.el .IP \f(CW(*nla:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1798 |
.IX Item "(*nla:pattern)" |
| 1799 |
.ie n .IP """(*negative_lookahead:\fIpattern\fR)""" 4 |
| 1800 |
.el .IP \f(CW(*negative_lookahead:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1801 |
.IX Xref "(?!) (*nla (*negative_lookahead look-ahead, negative lookahead, negative" |
| 1802 |
.IX Item "(*negative_lookahead:pattern)" |
| 1803 |
.PD |
| 1804 |
A zero-width negative lookahead assertion. For example \f(CW\*(C`/foo(?!bar)/\*(C'\fR |
| 1805 |
matches any occurrence of "foo" that isn't followed by "bar". Note |
| 1806 |
however that lookahead and lookbehind are NOT the same thing. You cannot |
| 1807 |
use this for lookbehind. |
| 1808 |
.Sp |
| 1809 |
If you are looking for a "bar" that isn't preceded by a "foo", \f(CW\*(C`/(?!foo)bar/\*(C'\fR |
| 1810 |
will not do what you want. That's because the \f(CW\*(C`(?!foo)\*(C'\fR is just saying that |
| 1811 |
the next thing cannot be "foo"\-\-and it's not, it's a "bar", so "foobar" will |
| 1812 |
match. Use lookbehind instead (see below). |
| 1813 |
.ie n .IP """(?<=\fIpattern\fR)""" 4 |
| 1814 |
.el .IP \f(CW(?<=\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1815 |
.IX Item "(?<=pattern)" |
| 1816 |
.PD 0 |
| 1817 |
.ie n .IP """\eK""" 4 |
| 1818 |
.el .IP \f(CW\eK\fR 4 |
| 1819 |
.IX Item "K" |
| 1820 |
.ie n .IP """(*plb:\fIpattern\fR)""" 4 |
| 1821 |
.el .IP \f(CW(*plb:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1822 |
.IX Item "(*plb:pattern)" |
| 1823 |
.ie n .IP """(*positive_lookbehind:\fIpattern\fR)""" 4 |
| 1824 |
.el .IP \f(CW(*positive_lookbehind:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1825 |
.IX Xref "(?<=) (*plb (*positive_lookbehind look-behind, positive lookbehind, positive \\K" |
| 1826 |
.IX Item "(*positive_lookbehind:pattern)" |
| 1827 |
.PD |
| 1828 |
A zero-width positive lookbehind assertion. For example, \f(CW\*(C`/(?<=\et)\ew+/\*(C'\fR |
| 1829 |
matches a word that follows a tab, without including the tab in \f(CW$&\fR. |
| 1830 |
.Sp |
| 1831 |
Prior to Perl 5.30, it worked only for fixed-width lookbehind, but |
| 1832 |
starting in that release, it can handle variable lengths from 1 to 255 |
| 1833 |
characters as an experimental feature. The feature is enabled |
| 1834 |
automatically if you use a variable length positive lookbehind assertion. |
| 1835 |
.Sp |
| 1836 |
In Perl 5.35.10 the scope of the experimental nature of this construct |
| 1837 |
has been reduced, and experimental warnings will only be produced when |
| 1838 |
the construct contains capturing parenthesis. The warnings will be |
| 1839 |
raised at pattern compilation time, unless turned off, in the |
| 1840 |
\&\f(CW\*(C`experimental::vlb\*(C'\fR category. This is to warn you that the exact |
| 1841 |
contents of capturing buffers in a variable length positive lookbehind |
| 1842 |
is not well defined and is subject to change in a future release of perl. |
| 1843 |
.Sp |
| 1844 |
Currently if you use capture buffers inside of a positive variable length |
| 1845 |
lookbehind the result will be the longest and thus leftmost match possible. |
| 1846 |
This means that |
| 1847 |
.Sp |
| 1848 |
.Vb 4 |
| 1849 |
\& "aax" =~ /(?=x)(?<=(a|aa))/ |
| 1850 |
\& "aax" =~ /(?=x)(?<=(aa|a))/ |
| 1851 |
\& "aax" =~ /(?=x)(?<=(a{1,2}?)/ |
| 1852 |
\& "aax" =~ /(?=x)(?<=(a{1,2})/ |
| 1853 |
.Ve |
| 1854 |
.Sp |
| 1855 |
will all result in \f(CW$1\fR containing \f(CW"aa"\fR. It is possible in a future |
| 1856 |
release of perl we will change this behavior. |
| 1857 |
.Sp |
| 1858 |
There is a special form of this construct, called \f(CW\*(C`\eK\*(C'\fR |
| 1859 |
(available since Perl 5.10.0), which causes the |
| 1860 |
regex engine to "keep" everything it had matched prior to the \f(CW\*(C`\eK\*(C'\fR and |
| 1861 |
not include it in \f(CW$&\fR. This effectively provides non-experimental |
| 1862 |
variable-length lookbehind of any length. |
| 1863 |
.Sp |
| 1864 |
And, there is a technique that can be used to handle variable length |
| 1865 |
lookbehinds on earlier releases, and longer than 255 characters. It is |
| 1866 |
described in |
| 1867 |
<http://www.drregex.com/2019/02/variable\-length\-lookbehinds\-actually.html>. |
| 1868 |
.Sp |
| 1869 |
Note that under \f(CW\*(C`/i\*(C'\fR, a few single characters match two or three other |
| 1870 |
characters. This makes them variable length, and the 255 length applies |
| 1871 |
to the maximum number of characters in the match. For |
| 1872 |
example \f(CW\*(C`qr/\eN{LATIN SMALL LETTER SHARP S}/i\*(C'\fR matches the sequence |
| 1873 |
\&\f(CW"ss"\fR. Your lookbehind assertion could contain 127 Sharp S |
| 1874 |
characters under \f(CW\*(C`/i\*(C'\fR, but adding a 128th would generate a compilation |
| 1875 |
error, as that could match 256 \f(CW"s"\fR characters in a row. |
| 1876 |
.Sp |
| 1877 |
The use of \f(CW\*(C`\eK\*(C'\fR inside of another lookaround assertion |
| 1878 |
is allowed, but the behaviour is currently not well defined. |
| 1879 |
.Sp |
| 1880 |
For various reasons \f(CW\*(C`\eK\*(C'\fR may be significantly more efficient than the |
| 1881 |
equivalent \f(CW\*(C`(?<=...)\*(C'\fR construct, and it is especially useful in |
| 1882 |
situations where you want to efficiently remove something following |
| 1883 |
something else in a string. For instance |
| 1884 |
.Sp |
| 1885 |
.Vb 1 |
| 1886 |
\& s/(foo)bar/$1/g; |
| 1887 |
.Ve |
| 1888 |
.Sp |
| 1889 |
can be rewritten as the much more efficient |
| 1890 |
.Sp |
| 1891 |
.Vb 1 |
| 1892 |
\& s/foo\eKbar//g; |
| 1893 |
.Ve |
| 1894 |
.Sp |
| 1895 |
Use of the non-greedy modifier \f(CW"?"\fR may not give you the expected |
| 1896 |
results if it is within a capturing group within the construct. |
| 1897 |
.ie n .IP """(?<!\fIpattern\fR)""" 4 |
| 1898 |
.el .IP \f(CW(?<!\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1899 |
.IX Item "(?<!pattern)" |
| 1900 |
.PD 0 |
| 1901 |
.ie n .IP """(*nlb:\fIpattern\fR)""" 4 |
| 1902 |
.el .IP \f(CW(*nlb:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1903 |
.IX Item "(*nlb:pattern)" |
| 1904 |
.ie n .IP """(*negative_lookbehind:\fIpattern\fR)""" 4 |
| 1905 |
.el .IP \f(CW(*negative_lookbehind:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1906 |
.IX Xref "(?<!) (*nlb (*negative_lookbehind look-behind, negative lookbehind, negative" |
| 1907 |
.IX Item "(*negative_lookbehind:pattern)" |
| 1908 |
.PD |
| 1909 |
A zero-width negative lookbehind assertion. For example \f(CW\*(C`/(?<!bar)foo/\*(C'\fR |
| 1910 |
matches any occurrence of "foo" that does not follow "bar". |
| 1911 |
.Sp |
| 1912 |
Prior to Perl 5.30, it worked only for fixed-width lookbehind, but |
| 1913 |
starting in that release, it can handle variable lengths from 1 to 255 |
| 1914 |
characters as an experimental feature. The feature is enabled |
| 1915 |
automatically if you use a variable length negative lookbehind assertion. |
| 1916 |
.Sp |
| 1917 |
In Perl 5.35.10 the scope of the experimental nature of this construct |
| 1918 |
has been reduced, and experimental warnings will only be produced when |
| 1919 |
the construct contains capturing parentheses. The warnings will be |
| 1920 |
raised at pattern compilation time, unless turned off, in the |
| 1921 |
\&\f(CW\*(C`experimental::vlb\*(C'\fR category. This is to warn you that the exact |
| 1922 |
contents of capturing buffers in a variable length negative lookbehind |
| 1923 |
is not well defined and is subject to change in a future release of perl. |
| 1924 |
.Sp |
| 1925 |
Currently if you use capture buffers inside of a negative variable length |
| 1926 |
lookbehind the result may not be what you expect, for instance: |
| 1927 |
.Sp |
| 1928 |
.Vb 1 |
| 1929 |
\& say "axfoo"=~/(?=foo)(?<!(a|ax)(?{ say $1 }))/ ? "y" : "n"; |
| 1930 |
.Ve |
| 1931 |
.Sp |
| 1932 |
will output the following: |
| 1933 |
.Sp |
| 1934 |
.Vb 2 |
| 1935 |
\& a |
| 1936 |
\& no |
| 1937 |
.Ve |
| 1938 |
.Sp |
| 1939 |
which does not make sense as this should print out "ax" as the "a" does |
| 1940 |
not line up at the correct place. Another example would be: |
| 1941 |
.Sp |
| 1942 |
.Vb 1 |
| 1943 |
\& say "yes: \*(Aq$1\-$2\*(Aq" if "aayfoo"=~/(?=foo)(?<!(a|aa)(a|aa)x)/; |
| 1944 |
.Ve |
| 1945 |
.Sp |
| 1946 |
will output the following: |
| 1947 |
.Sp |
| 1948 |
.Vb 1 |
| 1949 |
\& yes: \*(Aqaa\-a\*(Aq |
| 1950 |
.Ve |
| 1951 |
.Sp |
| 1952 |
It is possible in a future release of perl we will change this behavior |
| 1953 |
so both of these examples produced more reasonable output. |
| 1954 |
.Sp |
| 1955 |
Note that we are confident that the construct will match and reject |
| 1956 |
patterns appropriately, the undefined behavior strictly relates to the |
| 1957 |
value of the capture buffer during or after matching. |
| 1958 |
.Sp |
| 1959 |
There is a technique that can be used to handle variable length |
| 1960 |
lookbehind on earlier releases, and longer than 255 characters. It is |
| 1961 |
described in |
| 1962 |
<http://www.drregex.com/2019/02/variable\-length\-lookbehinds\-actually.html>. |
| 1963 |
.Sp |
| 1964 |
Note that under \f(CW\*(C`/i\*(C'\fR, a few single characters match two or three other |
| 1965 |
characters. This makes them variable length, and the 255 length applies |
| 1966 |
to the maximum number of characters in the match. For |
| 1967 |
example \f(CW\*(C`qr/\eN{LATIN SMALL LETTER SHARP S}/i\*(C'\fR matches the sequence |
| 1968 |
\&\f(CW"ss"\fR. Your lookbehind assertion could contain 127 Sharp S |
| 1969 |
characters under \f(CW\*(C`/i\*(C'\fR, but adding a 128th would generate a compilation |
| 1970 |
error, as that could match 256 \f(CW"s"\fR characters in a row. |
| 1971 |
.Sp |
| 1972 |
Use of the non-greedy modifier \f(CW"?"\fR may not give you the expected |
| 1973 |
results if it is within a capturing group within the construct. |
| 1974 |
.RE |
| 1975 |
.RS 4 |
| 1976 |
.RE |
| 1977 |
.ie n .IP """(?<\fINAME\fR>\fIpattern\fR)""" 4 |
| 1978 |
.el .IP \f(CW(?<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1979 |
.IX Item "(?<NAME>pattern)" |
| 1980 |
.PD 0 |
| 1981 |
.ie n .IP """(?\*(Aq\fINAME\fR\*(Aq\fIpattern\fR)""" 4 |
| 1982 |
.el .IP \f(CW(?\*(Aq\fR\f(CINAME\fR\f(CW\*(Aq\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 1983 |
.IX Xref "(?<NAME>) (?'NAME') named capture capture" |
| 1984 |
.IX Item "(?NAMEpattern)" |
| 1985 |
.PD |
| 1986 |
A named capture group. Identical in every respect to normal capturing |
| 1987 |
parentheses \f(CW\*(C`()\*(C'\fR but for the additional fact that the group |
| 1988 |
can be referred to by name in various regular expression |
| 1989 |
constructs (like \f(CW\*(C`\eg{\fR\f(CINAME\fR\f(CW}\*(C'\fR) and can be accessed by name |
| 1990 |
after a successful match via \f(CW\*(C`%+\*(C'\fR or \f(CW\*(C`%\-\*(C'\fR. See perlvar |
| 1991 |
for more details on the \f(CW\*(C`%+\*(C'\fR and \f(CW\*(C`%\-\*(C'\fR hashes. |
| 1992 |
.Sp |
| 1993 |
If multiple distinct capture groups have the same name, then |
| 1994 |
\&\f(CW$+{\fR\f(CINAME\fR\f(CW}\fR will refer to the leftmost defined group in the match. |
| 1995 |
.Sp |
| 1996 |
The forms \f(CW\*(C`(?\*(Aq\fR\f(CINAME\fR\f(CW\*(Aq\fR\f(CIpattern\fR\f(CW)\*(C'\fR and \f(CW\*(C`(?<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\*(C'\fR |
| 1997 |
are equivalent. |
| 1998 |
.Sp |
| 1999 |
\&\fBNOTE:\fR While the notation of this construct is the same as the similar |
| 2000 |
function in .NET regexes, the behavior is not. In Perl the groups are |
| 2001 |
numbered sequentially regardless of being named or not. Thus in the |
| 2002 |
pattern |
| 2003 |
.Sp |
| 2004 |
.Vb 1 |
| 2005 |
\& /(x)(?<foo>y)(z)/ |
| 2006 |
.Ve |
| 2007 |
.Sp |
| 2008 |
\&\f(CW$+{foo}\fR will be the same as \f(CW$2\fR, and \f(CW$3\fR will contain 'z' instead of |
| 2009 |
the opposite which is what a .NET regex hacker might expect. |
| 2010 |
.Sp |
| 2011 |
Currently \fINAME\fR is restricted to simple identifiers only. |
| 2012 |
In other words, it must match \f(CW\*(C`/^[_A\-Za\-z][_A\-Za\-z0\-9]*\ez/\*(C'\fR or |
| 2013 |
its Unicode extension (see utf8), |
| 2014 |
though it isn't extended by the locale (see perllocale). |
| 2015 |
.Sp |
| 2016 |
\&\fBNOTE:\fR In order to make things easier for programmers with experience |
| 2017 |
with the Python or PCRE regex engines, the pattern \f(CW\*(C`(?P<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\*(C'\fR |
| 2018 |
may be used instead of \f(CW\*(C`(?<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\*(C'\fR; however this form does not |
| 2019 |
support the use of single quotes as a delimiter for the name. |
| 2020 |
.ie n .IP """\ek<\fINAME\fR>""" 4 |
| 2021 |
.el .IP \f(CW\ek<\fR\f(CINAME\fR\f(CW>\fR 4 |
| 2022 |
.IX Item "k<NAME>" |
| 2023 |
.PD 0 |
| 2024 |
.ie n .IP """\ek\*(Aq\fINAME\fR\*(Aq""" 4 |
| 2025 |
.el .IP \f(CW\ek\*(Aq\fR\f(CINAME\fR\f(CW\*(Aq\fR 4 |
| 2026 |
.IX Item "kNAME" |
| 2027 |
.ie n .IP """\ek{\fINAME\fR}""" 4 |
| 2028 |
.el .IP \f(CW\ek{\fR\f(CINAME\fR\f(CW}\fR 4 |
| 2029 |
.IX Item "k{NAME}" |
| 2030 |
.PD |
| 2031 |
Named backreference. Similar to numeric backreferences, except that |
| 2032 |
the group is designated by name and not number. If multiple groups |
| 2033 |
have the same name then it refers to the leftmost defined group in |
| 2034 |
the current match. |
| 2035 |
.Sp |
| 2036 |
It is an error to refer to a name not defined by a \f(CW\*(C`(?<\fR\f(CINAME\fR\f(CW>)\*(C'\fR |
| 2037 |
earlier in the pattern. |
| 2038 |
.Sp |
| 2039 |
All three forms are equivalent, although with \f(CW\*(C`\ek{ \fR\f(CINAME\fR\f(CW }\*(C'\fR, |
| 2040 |
you may optionally have blanks within but adjacent to the braces, as |
| 2041 |
shown. |
| 2042 |
.Sp |
| 2043 |
\&\fBNOTE:\fR In order to make things easier for programmers with experience |
| 2044 |
with the Python or PCRE regex engines, the pattern \f(CW\*(C`(?P=\fR\f(CINAME\fR\f(CW)\*(C'\fR |
| 2045 |
may be used instead of \f(CW\*(C`\ek<\fR\f(CINAME\fR\f(CW>\*(C'\fR. |
| 2046 |
.ie n .IP """(?{ \fIcode\fR })""" 4 |
| 2047 |
.el .IP "\f(CW(?{ \fR\f(CIcode\fR\f(CW })\fR" 4 |
| 2048 |
.IX Xref "(?{}) regex, code in regexp, code in regular expression, code in" |
| 2049 |
.IX Item "(?{ code })" |
| 2050 |
\&\fBWARNING\fR: Using this feature safely requires that you understand its |
| 2051 |
limitations. Code executed that has side effects may not perform identically |
| 2052 |
from version to version due to the effect of future optimisations in the regex |
| 2053 |
engine. For more information on this, see "Embedded Code Execution |
| 2054 |
Frequency". |
| 2055 |
.Sp |
| 2056 |
This zero-width assertion executes any embedded Perl code. It always |
| 2057 |
succeeds, and its return value is set as \f(CW$^R\fR. |
| 2058 |
.Sp |
| 2059 |
In literal patterns, the code is parsed at the same time as the |
| 2060 |
surrounding code. While within the pattern, control is passed temporarily |
| 2061 |
back to the perl parser, until the logically-balancing closing brace is |
| 2062 |
encountered. This is similar to the way that an array index expression in |
| 2063 |
a literal string is handled, for example |
| 2064 |
.Sp |
| 2065 |
.Vb 1 |
| 2066 |
\& "abc$array[ 1 + f(\*(Aq[\*(Aq) + g()]def" |
| 2067 |
.Ve |
| 2068 |
.Sp |
| 2069 |
In particular, braces do not need to be balanced: |
| 2070 |
.Sp |
| 2071 |
.Vb 1 |
| 2072 |
\& s/abc(?{ f(\*(Aq{\*(Aq); })/def/ |
| 2073 |
.Ve |
| 2074 |
.Sp |
| 2075 |
Even in a pattern that is interpolated and compiled at run-time, literal |
| 2076 |
code blocks will be compiled once, at perl compile time; the following |
| 2077 |
prints "ABCD": |
| 2078 |
.Sp |
| 2079 |
.Vb 5 |
| 2080 |
\& print "D"; |
| 2081 |
\& my $qr = qr/(?{ BEGIN { print "A" } })/; |
| 2082 |
\& my $foo = "foo"; |
| 2083 |
\& /$foo$qr(?{ BEGIN { print "B" } })/; |
| 2084 |
\& BEGIN { print "C" } |
| 2085 |
.Ve |
| 2086 |
.Sp |
| 2087 |
In patterns where the text of the code is derived from run-time |
| 2088 |
information rather than appearing literally in a source code /pattern/, |
| 2089 |
the code is compiled at the same time that the pattern is compiled, and |
| 2090 |
for reasons of security, \f(CW\*(C`use re \*(Aqeval\*(Aq\*(C'\fR must be in scope. This is to |
| 2091 |
stop user-supplied patterns containing code snippets from being |
| 2092 |
executable. |
| 2093 |
.Sp |
| 2094 |
In situations where you need to enable this with \f(CW\*(C`use re \*(Aqeval\*(Aq\*(C'\fR, you should |
| 2095 |
also have taint checking enabled, if your perl supports it. |
| 2096 |
Better yet, use the carefully constrained evaluation within a Safe compartment. |
| 2097 |
See perlsec for details about both these mechanisms. |
| 2098 |
.Sp |
| 2099 |
From the viewpoint of parsing, lexical variable scope and closures, |
| 2100 |
.Sp |
| 2101 |
.Vb 1 |
| 2102 |
\& /AAA(?{ BBB })CCC/ |
| 2103 |
.Ve |
| 2104 |
.Sp |
| 2105 |
behaves approximately like |
| 2106 |
.Sp |
| 2107 |
.Vb 1 |
| 2108 |
\& /AAA/ && do { BBB } && /CCC/ |
| 2109 |
.Ve |
| 2110 |
.Sp |
| 2111 |
Similarly, |
| 2112 |
.Sp |
| 2113 |
.Vb 1 |
| 2114 |
\& qr/AAA(?{ BBB })CCC/ |
| 2115 |
.Ve |
| 2116 |
.Sp |
| 2117 |
behaves approximately like |
| 2118 |
.Sp |
| 2119 |
.Vb 1 |
| 2120 |
\& sub { /AAA/ && do { BBB } && /CCC/ } |
| 2121 |
.Ve |
| 2122 |
.Sp |
| 2123 |
In particular: |
| 2124 |
.Sp |
| 2125 |
.Vb 3 |
| 2126 |
\& { my $i = 1; $r = qr/(?{ print $i })/ } |
| 2127 |
\& my $i = 2; |
| 2128 |
\& /$r/; # prints "1" |
| 2129 |
.Ve |
| 2130 |
.Sp |
| 2131 |
Inside a \f(CW\*(C`(?{...})\*(C'\fR block, \f(CW$_\fR refers to the string the regular |
| 2132 |
expression is matching against. You can also use \f(CWpos()\fR to know what is |
| 2133 |
the current position of matching within this string. |
| 2134 |
.Sp |
| 2135 |
The code block introduces a new scope from the perspective of lexical |
| 2136 |
variable declarations, but \fBnot\fR from the perspective of \f(CW\*(C`local\*(C'\fR and |
| 2137 |
similar localizing behaviours. So later code blocks within the same |
| 2138 |
pattern will still see the values which were localized in earlier blocks. |
| 2139 |
These accumulated localizations are undone either at the end of a |
| 2140 |
successful match, or if the assertion is backtracked (compare |
| 2141 |
"Backtracking"). For example, |
| 2142 |
.Sp |
| 2143 |
.Vb 10 |
| 2144 |
\& $_ = \*(Aqa\*(Aq x 8; |
| 2145 |
\& m< |
| 2146 |
\& (?{ $cnt = 0 }) # Initialize $cnt. |
| 2147 |
\& ( |
| 2148 |
\& a |
| 2149 |
\& (?{ |
| 2150 |
\& local $cnt = $cnt + 1; # Update $cnt, |
| 2151 |
\& # backtracking\-safe. |
| 2152 |
\& }) |
| 2153 |
\& )* |
| 2154 |
\& aaaa |
| 2155 |
\& (?{ $res = $cnt }) # On success copy to |
| 2156 |
\& # non\-localized location. |
| 2157 |
\& >x; |
| 2158 |
.Ve |
| 2159 |
.Sp |
| 2160 |
will initially increment \f(CW$cnt\fR up to 8; then during backtracking, its |
| 2161 |
value will be unwound back to 4, which is the value assigned to \f(CW$res\fR. |
| 2162 |
At the end of the regex execution, \f(CW$cnt\fR will be wound back to its initial |
| 2163 |
value of 0. |
| 2164 |
.Sp |
| 2165 |
This assertion may be used as the condition in a |
| 2166 |
.Sp |
| 2167 |
.Vb 1 |
| 2168 |
\& (?(condition)yes\-pattern|no\-pattern) |
| 2169 |
.Ve |
| 2170 |
.Sp |
| 2171 |
switch. If \fInot\fR used in this way, the result of evaluation of \fIcode\fR |
| 2172 |
is put into the special variable \f(CW$^R\fR. This happens immediately, so |
| 2173 |
\&\f(CW$^R\fR can be used from other \f(CW\*(C`(?{ \fR\f(CIcode\fR\f(CW })\*(C'\fR assertions inside the same |
| 2174 |
regular expression. |
| 2175 |
.Sp |
| 2176 |
The assignment to \f(CW$^R\fR above is properly localized, so the old |
| 2177 |
value of \f(CW$^R\fR is restored if the assertion is backtracked; compare |
| 2178 |
"Backtracking". |
| 2179 |
.Sp |
| 2180 |
Note that the special variable \f(CW$^N\fR is particularly useful with code |
| 2181 |
blocks to capture the results of submatches in variables without having to |
| 2182 |
keep track of the number of nested parentheses. For example: |
| 2183 |
.Sp |
| 2184 |
.Vb 3 |
| 2185 |
\& $_ = "The brown fox jumps over the lazy dog"; |
| 2186 |
\& /the (\eS+)(?{ $color = $^N }) (\eS+)(?{ $animal = $^N })/i; |
| 2187 |
\& print "color = $color, animal = $animal\en"; |
| 2188 |
.Ve |
| 2189 |
.Sp |
| 2190 |
The use of this construct disables some optimisations globally in the |
| 2191 |
pattern, and the pattern may execute much slower as a consequence. |
| 2192 |
Use a \f(CW\*(C`*\*(C'\fR instead of the \f(CW\*(C`?\*(C'\fR block to create an optimistic form of |
| 2193 |
this construct. \f(CW\*(C`(*{ ... })\*(C'\fR should not disable any optimisations. |
| 2194 |
.ie n .IP """(*{ \fIcode\fR })""" 4 |
| 2195 |
.el .IP "\f(CW(*{ \fR\f(CIcode\fR\f(CW })\fR" 4 |
| 2196 |
.IX Xref "(*{}) regex, optimistic code" |
| 2197 |
.IX Item "(*{ code })" |
| 2198 |
This is *exactly* the same as \f(CW\*(C`(?{ \fR\f(CIcode\fR\f(CW })\*(C'\fR with the exception |
| 2199 |
that it does not disable \fBany\fR optimisations at all in the regex engine. |
| 2200 |
How often it is executed may vary from perl release to perl release. |
| 2201 |
In a failing match it may not even be executed at all. |
| 2202 |
.ie n .IP """(??{ \fIcode\fR })""" 4 |
| 2203 |
.el .IP "\f(CW(??{ \fR\f(CIcode\fR\f(CW })\fR" 4 |
| 2204 |
.IX Xref "(??{}) regex, postponed regexp, postponed regular expression, postponed" |
| 2205 |
.IX Item "(??{ code })" |
| 2206 |
\&\fBWARNING\fR: Using this feature safely requires that you understand its |
| 2207 |
limitations. Code executed that has side effects may not perform |
| 2208 |
identically from version to version due to the effect of future |
| 2209 |
optimisations in the regex engine. For more information on this, see |
| 2210 |
"Embedded Code Execution Frequency". |
| 2211 |
.Sp |
| 2212 |
This is a "postponed" regular subexpression. It behaves in \fIexactly\fR the |
| 2213 |
same way as a \f(CW\*(C`(?{ \fR\f(CIcode\fR\f(CW })\*(C'\fR code block as described above, except that |
| 2214 |
its return value, rather than being assigned to \f(CW$^R\fR, is treated as a |
| 2215 |
pattern, compiled if it's a string (or used as-is if its a qr// object), |
| 2216 |
then matched as if it were inserted instead of this construct. |
| 2217 |
.Sp |
| 2218 |
During the matching of this sub-pattern, it has its own set of |
| 2219 |
captures which are valid during the sub-match, but are discarded once |
| 2220 |
control returns to the main pattern. For example, the following matches, |
| 2221 |
with the inner pattern capturing "B" and matching "BB", while the outer |
| 2222 |
pattern captures "A"; |
| 2223 |
.Sp |
| 2224 |
.Vb 3 |
| 2225 |
\& my $inner = \*(Aq(.)\e1\*(Aq; |
| 2226 |
\& "ABBA" =~ /^(.)(??{ $inner })\e1/; |
| 2227 |
\& print $1; # prints "A"; |
| 2228 |
.Ve |
| 2229 |
.Sp |
| 2230 |
Note that this means that there is no way for the inner pattern to refer |
| 2231 |
to a capture group defined outside. (The code block itself can use \f(CW$1\fR, |
| 2232 |
\&\fIetc\fR., to refer to the enclosing pattern's capture groups.) Thus, although |
| 2233 |
.Sp |
| 2234 |
.Vb 1 |
| 2235 |
\& (\*(Aqa\*(Aq x 100)=~/(??{\*(Aq(.)\*(Aq x 100})/ |
| 2236 |
.Ve |
| 2237 |
.Sp |
| 2238 |
\&\fIwill\fR match, it will \fInot\fR set \f(CW$1\fR on exit. |
| 2239 |
.Sp |
| 2240 |
The following pattern matches a parenthesized group: |
| 2241 |
.Sp |
| 2242 |
.Vb 9 |
| 2243 |
\& $re = qr{ |
| 2244 |
\& \e( |
| 2245 |
\& (?: |
| 2246 |
\& (?> [^()]+ ) # Non\-parens without backtracking |
| 2247 |
\& | |
| 2248 |
\& (??{ $re }) # Group with matching parens |
| 2249 |
\& )* |
| 2250 |
\& \e) |
| 2251 |
\& }x; |
| 2252 |
.Ve |
| 2253 |
.Sp |
| 2254 |
See also |
| 2255 |
\&\f(CW\*(C`(?\fR\f(CIPARNO\fR\f(CW)\*(C'\fR |
| 2256 |
for a different, more efficient way to accomplish |
| 2257 |
the same task. |
| 2258 |
.Sp |
| 2259 |
Executing a postponed regular expression too many times without |
| 2260 |
consuming any input string will also result in a fatal error. The depth |
| 2261 |
at which that happens is compiled into perl, so it can be changed with a |
| 2262 |
custom build. |
| 2263 |
.Sp |
| 2264 |
The use of this construct disables some optimisations globally in the pattern, |
| 2265 |
and the pattern may execute much slower as a consequence. |
| 2266 |
.ie n .IP """(?\fIPARNO\fR)"" ""(?\-\fIPARNO\fR)"" ""(?+\fIPARNO\fR)"" ""(?R)"" ""(?0)""" 4 |
| 2267 |
.el .IP "\f(CW(?\fR\f(CIPARNO\fR\f(CW)\fR \f(CW(?\-\fR\f(CIPARNO\fR\f(CW)\fR \f(CW(?+\fR\f(CIPARNO\fR\f(CW)\fR \f(CW(?R)\fR \f(CW(?0)\fR" 4 |
| 2268 |
.IX Xref "(?PARNO) (?1) (?R) (?0) (?-1) (?+1) (?-PARNO) (?+PARNO) regex, recursive regexp, recursive regular expression, recursive regex, relative recursion GOSUB GOSTART" |
| 2269 |
.IX Item "(?PARNO) (?-PARNO) (?+PARNO) (?R) (?0)" |
| 2270 |
Recursive subpattern. Treat the contents of a given capture buffer in the |
| 2271 |
current pattern as an independent subpattern and attempt to match it at |
| 2272 |
the current position in the string. Information about capture state from |
| 2273 |
the caller for things like backreferences is available to the subpattern, |
| 2274 |
but capture buffers set by the subpattern are not visible to the caller. |
| 2275 |
.Sp |
| 2276 |
Similar to \f(CW\*(C`(??{ \fR\f(CIcode\fR\f(CW })\*(C'\fR except that it does not involve executing any |
| 2277 |
code or potentially compiling a returned pattern string; instead it treats |
| 2278 |
the part of the current pattern contained within a specified capture group |
| 2279 |
as an independent pattern that must match at the current position. Also |
| 2280 |
different is the treatment of capture buffers, unlike \f(CW\*(C`(??{ \fR\f(CIcode\fR\f(CW })\*(C'\fR |
| 2281 |
recursive patterns have access to their caller's match state, so one can |
| 2282 |
use backreferences safely. |
| 2283 |
.Sp |
| 2284 |
\&\fIPARNO\fR is a sequence of digits (not starting with 0) whose value reflects |
| 2285 |
the paren-number of the capture group to recurse to. \f(CW\*(C`(?R)\*(C'\fR recurses to |
| 2286 |
the beginning of the whole pattern. \f(CW\*(C`(?0)\*(C'\fR is an alternate syntax for |
| 2287 |
\&\f(CW\*(C`(?R)\*(C'\fR. If \fIPARNO\fR is preceded by a plus or minus sign then it is assumed |
| 2288 |
to be relative, with negative numbers indicating preceding capture groups |
| 2289 |
and positive ones following. Thus \f(CW\*(C`(?\-1)\*(C'\fR refers to the most recently |
| 2290 |
declared group, and \f(CW\*(C`(?+1)\*(C'\fR indicates the next group to be declared. |
| 2291 |
Note that the counting for relative recursion differs from that of |
| 2292 |
relative backreferences, in that with recursion unclosed groups \fBare\fR |
| 2293 |
included. |
| 2294 |
.Sp |
| 2295 |
The following pattern matches a function \f(CWfoo()\fR which may contain |
| 2296 |
balanced parentheses as the argument. |
| 2297 |
.Sp |
| 2298 |
.Vb 10 |
| 2299 |
\& $re = qr{ ( # paren group 1 (full function) |
| 2300 |
\& foo |
| 2301 |
\& ( # paren group 2 (parens) |
| 2302 |
\& \e( |
| 2303 |
\& ( # paren group 3 (contents of parens) |
| 2304 |
\& (?: |
| 2305 |
\& (?> [^()]+ ) # Non\-parens without backtracking |
| 2306 |
\& | |
| 2307 |
\& (?2) # Recurse to start of paren group 2 |
| 2308 |
\& )* |
| 2309 |
\& ) |
| 2310 |
\& \e) |
| 2311 |
\& ) |
| 2312 |
\& ) |
| 2313 |
\& }x; |
| 2314 |
.Ve |
| 2315 |
.Sp |
| 2316 |
If the pattern was used as follows |
| 2317 |
.Sp |
| 2318 |
.Vb 4 |
| 2319 |
\& \*(Aqfoo(bar(baz)+baz(bop))\*(Aq=~/$re/ |
| 2320 |
\& and print "\e$1 = $1\en", |
| 2321 |
\& "\e$2 = $2\en", |
| 2322 |
\& "\e$3 = $3\en"; |
| 2323 |
.Ve |
| 2324 |
.Sp |
| 2325 |
the output produced should be the following: |
| 2326 |
.Sp |
| 2327 |
.Vb 3 |
| 2328 |
\& $1 = foo(bar(baz)+baz(bop)) |
| 2329 |
\& $2 = (bar(baz)+baz(bop)) |
| 2330 |
\& $3 = bar(baz)+baz(bop) |
| 2331 |
.Ve |
| 2332 |
.Sp |
| 2333 |
If there is no corresponding capture group defined, then it is a |
| 2334 |
fatal error. Recursing deeply without consuming any input string will |
| 2335 |
also result in a fatal error. The depth at which that happens is |
| 2336 |
compiled into perl, so it can be changed with a custom build. |
| 2337 |
.Sp |
| 2338 |
The following shows how using negative indexing can make it |
| 2339 |
easier to embed recursive patterns inside of a \f(CW\*(C`qr//\*(C'\fR construct |
| 2340 |
for later use: |
| 2341 |
.Sp |
| 2342 |
.Vb 4 |
| 2343 |
\& my $parens = qr/(\e((?:[^()]++|(?\-1))*+\e))/; |
| 2344 |
\& if (/foo $parens \es+ \e+ \es+ bar $parens/x) { |
| 2345 |
\& # do something here... |
| 2346 |
\& } |
| 2347 |
.Ve |
| 2348 |
.Sp |
| 2349 |
\&\fBNote\fR that this pattern does not behave the same way as the equivalent |
| 2350 |
PCRE or Python construct of the same form. In Perl you can backtrack into |
| 2351 |
a recursed group, in PCRE and Python the recursed into group is treated |
| 2352 |
as atomic. Also, modifiers are resolved at compile time, so constructs |
| 2353 |
like \f(CW\*(C`(?i:(?1))\*(C'\fR or \f(CW\*(C`(?:(?i)(?1))\*(C'\fR do not affect how the sub-pattern will |
| 2354 |
be processed. |
| 2355 |
.ie n .IP """(?&\fINAME\fR)""" 4 |
| 2356 |
.el .IP \f(CW(?&\fR\f(CINAME\fR\f(CW)\fR 4 |
| 2357 |
.IX Xref "(?&NAME)" |
| 2358 |
.IX Item "(?&NAME)" |
| 2359 |
Recurse to a named subpattern. Identical to \f(CW\*(C`(?\fR\f(CIPARNO\fR\f(CW)\*(C'\fR except that the |
| 2360 |
parenthesis to recurse to is determined by name. If multiple parentheses have |
| 2361 |
the same name, then it recurses to the leftmost. |
| 2362 |
.Sp |
| 2363 |
It is an error to refer to a name that is not declared somewhere in the |
| 2364 |
pattern. |
| 2365 |
.Sp |
| 2366 |
\&\fBNOTE:\fR In order to make things easier for programmers with experience |
| 2367 |
with the Python or PCRE regex engines the pattern \f(CW\*(C`(?P>\fR\f(CINAME\fR\f(CW)\*(C'\fR |
| 2368 |
may be used instead of \f(CW\*(C`(?&\fR\f(CINAME\fR\f(CW)\*(C'\fR. |
| 2369 |
.ie n .IP """(?(\fIcondition\fR)\fIyes\-pattern\fR|\fIno\-pattern\fR)""" 4 |
| 2370 |
.el .IP \f(CW(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-pattern\fR\f(CW|\fR\f(CIno\-pattern\fR\f(CW)\fR 4 |
| 2371 |
.IX Xref "(?()" |
| 2372 |
.IX Item "(?(condition)yes-pattern|no-pattern)" |
| 2373 |
.PD 0 |
| 2374 |
.ie n .IP """(?(\fIcondition\fR)\fIyes\-pattern\fR)""" 4 |
| 2375 |
.el .IP \f(CW(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-pattern\fR\f(CW)\fR 4 |
| 2376 |
.IX Item "(?(condition)yes-pattern)" |
| 2377 |
.PD |
| 2378 |
Conditional expression. Matches \fIyes-pattern\fR if \fIcondition\fR yields |
| 2379 |
a true value, matches \fIno-pattern\fR otherwise. A missing pattern always |
| 2380 |
matches. |
| 2381 |
.Sp |
| 2382 |
\&\f(CW\*(C`(\fR\f(CIcondition\fR\f(CW)\*(C'\fR should be one of: |
| 2383 |
.RS 4 |
| 2384 |
.IP "an integer in parentheses" 4 |
| 2385 |
.IX Item "an integer in parentheses" |
| 2386 |
(which is valid if the corresponding pair of parentheses |
| 2387 |
matched); |
| 2388 |
.IP "a lookahead/lookbehind/evaluate zero-width assertion;" 4 |
| 2389 |
.IX Item "a lookahead/lookbehind/evaluate zero-width assertion;" |
| 2390 |
.PD 0 |
| 2391 |
.IP "a name in angle brackets or single quotes" 4 |
| 2392 |
.IX Item "a name in angle brackets or single quotes" |
| 2393 |
.PD |
| 2394 |
(which is valid if a group with the given name matched); |
| 2395 |
.ie n .IP "the special symbol ""(R)""" 4 |
| 2396 |
.el .IP "the special symbol \f(CW(R)\fR" 4 |
| 2397 |
.IX Item "the special symbol (R)" |
| 2398 |
(true when evaluated inside of recursion or eval). Additionally the |
| 2399 |
\&\f(CW"R"\fR may be |
| 2400 |
followed by a number, (which will be true when evaluated when recursing |
| 2401 |
inside of the appropriate group), or by \f(CW\*(C`&\fR\f(CINAME\fR\f(CW\*(C'\fR, in which case it will |
| 2402 |
be true only when evaluated during recursion in the named group. |
| 2403 |
.RE |
| 2404 |
.RS 4 |
| 2405 |
.Sp |
| 2406 |
Here's a summary of the possible predicates: |
| 2407 |
.ie n .IP """(1)"" ""(2)"" ..." 4 |
| 2408 |
.el .IP "\f(CW(1)\fR \f(CW(2)\fR ..." 4 |
| 2409 |
.IX Item "(1) (2) ..." |
| 2410 |
Checks if the numbered capturing group has matched something. |
| 2411 |
Full syntax: \f(CW\*(C`(?(1)then|else)\*(C'\fR |
| 2412 |
.ie n .IP """(<\fINAME\fR>)"" ""(\*(Aq\fINAME\fR\*(Aq)""" 4 |
| 2413 |
.el .IP "\f(CW(<\fR\f(CINAME\fR\f(CW>)\fR \f(CW(\*(Aq\fR\f(CINAME\fR\f(CW\*(Aq)\fR" 4 |
| 2414 |
.IX Item "(<NAME>) (NAME)" |
| 2415 |
Checks if a group with the given name has matched something. |
| 2416 |
Full syntax: \f(CW\*(C`(?(<name>)then|else)\*(C'\fR |
| 2417 |
.ie n .IP """(?=...)"" ""(?!...)"" ""(?<=...)"" ""(?<!...)""" 4 |
| 2418 |
.el .IP "\f(CW(?=...)\fR \f(CW(?!...)\fR \f(CW(?<=...)\fR \f(CW(?<!...)\fR" 4 |
| 2419 |
.IX Item "(?=...) (?!...) (?<=...) (?<!...)" |
| 2420 |
Checks whether the pattern matches (or does not match, for the \f(CW"!"\fR |
| 2421 |
variants). |
| 2422 |
Full syntax: \f(CW\*(C`(?(?=\fR\f(CIlookahead\fR\f(CW)\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR |
| 2423 |
.ie n .IP """(?{ \fICODE\fR })""" 4 |
| 2424 |
.el .IP "\f(CW(?{ \fR\f(CICODE\fR\f(CW })\fR" 4 |
| 2425 |
.IX Item "(?{ CODE })" |
| 2426 |
Treats the return value of the code block as the condition. |
| 2427 |
Full syntax: \f(CW\*(C`(?(?{ \fR\f(CICODE\fR\f(CW })\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR |
| 2428 |
.Sp |
| 2429 |
Note use of this construct may globally affect the performance |
| 2430 |
of the pattern. Consider using \f(CW\*(C`(*{ \fR\f(CICODE\fR\f(CW })\*(C'\fR |
| 2431 |
.ie n .IP """(*{ \fICODE\fR })""" 4 |
| 2432 |
.el .IP "\f(CW(*{ \fR\f(CICODE\fR\f(CW })\fR" 4 |
| 2433 |
.IX Item "(*{ CODE })" |
| 2434 |
Treats the return value of the code block as the condition. |
| 2435 |
Full syntax: \f(CW\*(C`(?(*{ \fR\f(CICODE\fR\f(CW })\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR |
| 2436 |
.ie n .IP """(R)""" 4 |
| 2437 |
.el .IP \f(CW(R)\fR 4 |
| 2438 |
.IX Item "(R)" |
| 2439 |
Checks if the expression has been evaluated inside of recursion. |
| 2440 |
Full syntax: \f(CW\*(C`(?(R)\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR |
| 2441 |
.ie n .IP """(R1)"" ""(R2)"" ..." 4 |
| 2442 |
.el .IP "\f(CW(R1)\fR \f(CW(R2)\fR ..." 4 |
| 2443 |
.IX Item "(R1) (R2) ..." |
| 2444 |
Checks if the expression has been evaluated while executing directly |
| 2445 |
inside of the n\-th capture group. This check is the regex equivalent of |
| 2446 |
.Sp |
| 2447 |
.Vb 1 |
| 2448 |
\& if ((caller(0))[3] eq \*(Aqsubname\*(Aq) { ... } |
| 2449 |
.Ve |
| 2450 |
.Sp |
| 2451 |
In other words, it does not check the full recursion stack. |
| 2452 |
.Sp |
| 2453 |
Full syntax: \f(CW\*(C`(?(R1)\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR |
| 2454 |
.ie n .IP """(R&\fINAME\fR)""" 4 |
| 2455 |
.el .IP \f(CW(R&\fR\f(CINAME\fR\f(CW)\fR 4 |
| 2456 |
.IX Item "(R&NAME)" |
| 2457 |
Similar to \f(CW\*(C`(R1)\*(C'\fR, this predicate checks to see if we're executing |
| 2458 |
directly inside of the leftmost group with a given name (this is the same |
| 2459 |
logic used by \f(CW\*(C`(?&\fR\f(CINAME\fR\f(CW)\*(C'\fR to disambiguate). It does not check the full |
| 2460 |
stack, but only the name of the innermost active recursion. |
| 2461 |
Full syntax: \f(CW\*(C`(?(R&\fR\f(CIname\fR\f(CW)\fR\f(CIthen\fR\f(CW|\fR\f(CIelse\fR\f(CW)\*(C'\fR |
| 2462 |
.ie n .IP """(DEFINE)""" 4 |
| 2463 |
.el .IP \f(CW(DEFINE)\fR 4 |
| 2464 |
.IX Item "(DEFINE)" |
| 2465 |
In this case, the yes-pattern is never directly executed, and no |
| 2466 |
no-pattern is allowed. Similar in spirit to \f(CW\*(C`(?{0})\*(C'\fR but more efficient. |
| 2467 |
See below for details. |
| 2468 |
Full syntax: \f(CW\*(C`(?(DEFINE)\fR\f(CIdefinitions\fR\f(CW...)\*(C'\fR |
| 2469 |
.RE |
| 2470 |
.RS 4 |
| 2471 |
.Sp |
| 2472 |
For example: |
| 2473 |
.Sp |
| 2474 |
.Vb 4 |
| 2475 |
\& m{ ( \e( )? |
| 2476 |
\& [^()]+ |
| 2477 |
\& (?(1) \e) ) |
| 2478 |
\& }x |
| 2479 |
.Ve |
| 2480 |
.Sp |
| 2481 |
matches a chunk of non-parentheses, possibly included in parentheses |
| 2482 |
themselves. |
| 2483 |
.Sp |
| 2484 |
A special form is the \f(CW\*(C`(DEFINE)\*(C'\fR predicate, which never executes its |
| 2485 |
yes-pattern directly, and does not allow a no-pattern. This allows one to |
| 2486 |
define subpatterns which will be executed only by the recursion mechanism. |
| 2487 |
This way, you can define a set of regular expression rules that can be |
| 2488 |
bundled into any pattern you choose. |
| 2489 |
.Sp |
| 2490 |
It is recommended that for this usage you put the DEFINE block at the |
| 2491 |
end of the pattern, and that you name any subpatterns defined within it. |
| 2492 |
.Sp |
| 2493 |
Also, it's worth noting that patterns defined this way probably will |
| 2494 |
not be as efficient, as the optimizer is not very clever about |
| 2495 |
handling them. |
| 2496 |
.Sp |
| 2497 |
An example of how this might be used is as follows: |
| 2498 |
.Sp |
| 2499 |
.Vb 5 |
| 2500 |
\& /(?<NAME>(?&NAME_PAT))(?<ADDR>(?&ADDRESS_PAT)) |
| 2501 |
\& (?(DEFINE) |
| 2502 |
\& (?<NAME_PAT>....) |
| 2503 |
\& (?<ADDRESS_PAT>....) |
| 2504 |
\& )/x |
| 2505 |
.Ve |
| 2506 |
.Sp |
| 2507 |
Note that capture groups matched inside of recursion are not accessible |
| 2508 |
after the recursion returns, so the extra layer of capturing groups is |
| 2509 |
necessary. Thus \f(CW$+{NAME_PAT}\fR would not be defined even though |
| 2510 |
\&\f(CW$+{NAME}\fR would be. |
| 2511 |
.Sp |
| 2512 |
Finally, keep in mind that subpatterns created inside a DEFINE block |
| 2513 |
count towards the absolute and relative number of captures, so this: |
| 2514 |
.Sp |
| 2515 |
.Vb 5 |
| 2516 |
\& my @captures = "a" =~ /(.) # First capture |
| 2517 |
\& (?(DEFINE) |
| 2518 |
\& (?<EXAMPLE> 1 ) # Second capture |
| 2519 |
\& )/x; |
| 2520 |
\& say scalar @captures; |
| 2521 |
.Ve |
| 2522 |
.Sp |
| 2523 |
Will output 2, not 1. This is particularly important if you intend to |
| 2524 |
compile the definitions with the \f(CW\*(C`qr//\*(C'\fR operator, and later |
| 2525 |
interpolate them in another pattern. |
| 2526 |
.RE |
| 2527 |
.ie n .IP """(?>\fIpattern\fR)""" 4 |
| 2528 |
.el .IP \f(CW(?>\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 2529 |
.IX Item "(?>pattern)" |
| 2530 |
.PD 0 |
| 2531 |
.ie n .IP """(*atomic:\fIpattern\fR)""" 4 |
| 2532 |
.el .IP \f(CW(*atomic:\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 2533 |
.IX Xref "(?>pattern) (*atomic backtrack backtracking atomic possessive" |
| 2534 |
.IX Item "(*atomic:pattern)" |
| 2535 |
.PD |
| 2536 |
An "independent" subexpression, one which matches the substring |
| 2537 |
that a standalone \fIpattern\fR would match if anchored at the given |
| 2538 |
position, and it matches \fInothing other than this substring\fR. This |
| 2539 |
construct is useful for optimizations of what would otherwise be |
| 2540 |
"eternal" matches, because it will not backtrack (see "Backtracking"). |
| 2541 |
It may also be useful in places where the "grab all you can, and do not |
| 2542 |
give anything back" semantic is desirable. |
| 2543 |
.Sp |
| 2544 |
For example: \f(CW\*(C`^(?>a*)ab\*(C'\fR will never match, since \f(CW\*(C`(?>a*)\*(C'\fR |
| 2545 |
(anchored at the beginning of string, as above) will match \fIall\fR |
| 2546 |
characters \f(CW"a"\fR at the beginning of string, leaving no \f(CW"a"\fR for |
| 2547 |
\&\f(CW\*(C`ab\*(C'\fR to match. In contrast, \f(CW\*(C`a*ab\*(C'\fR will match the same as \f(CW\*(C`a+b\*(C'\fR, |
| 2548 |
since the match of the subgroup \f(CW\*(C`a*\*(C'\fR is influenced by the following |
| 2549 |
group \f(CW\*(C`ab\*(C'\fR (see "Backtracking"). In particular, \f(CW\*(C`a*\*(C'\fR inside |
| 2550 |
\&\f(CW\*(C`a*ab\*(C'\fR will match fewer characters than a standalone \f(CW\*(C`a*\*(C'\fR, since |
| 2551 |
this makes the tail match. |
| 2552 |
.Sp |
| 2553 |
\&\f(CW\*(C`(?>\fR\f(CIpattern\fR\f(CW)\*(C'\fR does not disable backtracking altogether once it has |
| 2554 |
matched. It is still possible to backtrack past the construct, but not |
| 2555 |
into it. So \f(CW\*(C`((?>a*)|(?>b*))ar\*(C'\fR will still match "bar". |
| 2556 |
.Sp |
| 2557 |
An effect similar to \f(CW\*(C`(?>\fR\f(CIpattern\fR\f(CW)\*(C'\fR may be achieved by writing |
| 2558 |
\&\f(CW\*(C`(?=(\fR\f(CIpattern\fR\f(CW))\eg{\-1}\*(C'\fR. This matches the same substring as a standalone |
| 2559 |
\&\f(CW\*(C`a+\*(C'\fR, and the following \f(CW\*(C`\eg{\-1}\*(C'\fR eats the matched string; it therefore |
| 2560 |
makes a zero-length assertion into an analogue of \f(CW\*(C`(?>...)\*(C'\fR. |
| 2561 |
(The difference between these two constructs is that the second one |
| 2562 |
uses a capturing group, thus shifting ordinals of backreferences |
| 2563 |
in the rest of a regular expression.) |
| 2564 |
.Sp |
| 2565 |
Consider this pattern: |
| 2566 |
.Sp |
| 2567 |
.Vb 8 |
| 2568 |
\& m{ \e( |
| 2569 |
\& ( |
| 2570 |
\& [^()]+ # x+ |
| 2571 |
\& | |
| 2572 |
\& \e( [^()]* \e) |
| 2573 |
\& )+ |
| 2574 |
\& \e) |
| 2575 |
\& }x |
| 2576 |
.Ve |
| 2577 |
.Sp |
| 2578 |
That will efficiently match a nonempty group with matching parentheses |
| 2579 |
two levels deep or less. However, if there is no such group, it |
| 2580 |
will take virtually forever on a long string. That's because there |
| 2581 |
are so many different ways to split a long string into several |
| 2582 |
substrings. This is what \f(CW\*(C`(.+)+\*(C'\fR is doing, and \f(CW\*(C`(.+)+\*(C'\fR is similar |
| 2583 |
to a subpattern of the above pattern. Consider how the pattern |
| 2584 |
above detects no-match on \f(CW\*(C`((()aaaaaaaaaaaaaaaaaa\*(C'\fR in several |
| 2585 |
seconds, but that each extra letter doubles this time. This |
| 2586 |
exponential performance will make it appear that your program has |
| 2587 |
hung. However, a tiny change to this pattern |
| 2588 |
.Sp |
| 2589 |
.Vb 8 |
| 2590 |
\& m{ \e( |
| 2591 |
\& ( |
| 2592 |
\& (?> [^()]+ ) # change x+ above to (?> x+ ) |
| 2593 |
\& | |
| 2594 |
\& \e( [^()]* \e) |
| 2595 |
\& )+ |
| 2596 |
\& \e) |
| 2597 |
\& }x |
| 2598 |
.Ve |
| 2599 |
.Sp |
| 2600 |
which uses \f(CW\*(C`(?>...)\*(C'\fR matches exactly when the one above does (verifying |
| 2601 |
this yourself would be a productive exercise), but finishes in a fourth |
| 2602 |
the time when used on a similar string with 1000000 \f(CW"a"\fRs. Be aware, |
| 2603 |
however, that, when this construct is followed by a |
| 2604 |
quantifier, it currently triggers a warning message under |
| 2605 |
the \f(CW\*(C`use warnings\*(C'\fR pragma or \fB\-w\fR switch saying it |
| 2606 |
\&\f(CW"matches null string many times in regex"\fR. |
| 2607 |
.Sp |
| 2608 |
On simple groups, such as the pattern \f(CW\*(C`(?> [^()]+ )\*(C'\fR, a comparable |
| 2609 |
effect may be achieved by negative lookahead, as in \f(CW\*(C`[^()]+ (?! [^()] )\*(C'\fR. |
| 2610 |
This was only 4 times slower on a string with 1000000 \f(CW"a"\fRs. |
| 2611 |
.Sp |
| 2612 |
The "grab all you can, and do not give anything back" semantic is desirable |
| 2613 |
in many situations where on the first sight a simple \f(CW\*(C`()*\*(C'\fR looks like |
| 2614 |
the correct solution. Suppose we parse text with comments being delimited |
| 2615 |
by \f(CW"#"\fR followed by some optional (horizontal) whitespace. Contrary to |
| 2616 |
its appearance, \f(CW\*(C`#[ \et]*\*(C'\fR \fIis not\fR the correct subexpression to match |
| 2617 |
the comment delimiter, because it may "give up" some whitespace if |
| 2618 |
the remainder of the pattern can be made to match that way. The correct |
| 2619 |
answer is either one of these: |
| 2620 |
.Sp |
| 2621 |
.Vb 2 |
| 2622 |
\& (?>#[ \et]*) |
| 2623 |
\& #[ \et]*(?![ \et]) |
| 2624 |
.Ve |
| 2625 |
.Sp |
| 2626 |
For example, to grab non-empty comments into \f(CW$1\fR, one should use either |
| 2627 |
one of these: |
| 2628 |
.Sp |
| 2629 |
.Vb 2 |
| 2630 |
\& / (?> \e# [ \et]* ) ( .+ ) /x; |
| 2631 |
\& / \e# [ \et]* ( [^ \et] .* ) /x; |
| 2632 |
.Ve |
| 2633 |
.Sp |
| 2634 |
Which one you pick depends on which of these expressions better reflects |
| 2635 |
the above specification of comments. |
| 2636 |
.Sp |
| 2637 |
In some literature this construct is called "atomic matching" or |
| 2638 |
"possessive matching". |
| 2639 |
.Sp |
| 2640 |
Possessive quantifiers are equivalent to putting the item they are applied |
| 2641 |
to inside of one of these constructs. The following equivalences apply: |
| 2642 |
.Sp |
| 2643 |
.Vb 6 |
| 2644 |
\& Quantifier Form Bracketing Form |
| 2645 |
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- |
| 2646 |
\& PAT*+ (?>PAT*) |
| 2647 |
\& PAT++ (?>PAT+) |
| 2648 |
\& PAT?+ (?>PAT?) |
| 2649 |
\& PAT{min,max}+ (?>PAT{min,max}) |
| 2650 |
.Ve |
| 2651 |
.Sp |
| 2652 |
Nested \f(CW\*(C`(?>...)\*(C'\fR constructs are not no-ops, even if at first glance |
| 2653 |
they might seem to be. This is because the nested \f(CW\*(C`(?>...)\*(C'\fR can |
| 2654 |
restrict internal backtracking that otherwise might occur. For example, |
| 2655 |
.Sp |
| 2656 |
.Vb 1 |
| 2657 |
\& "abc" =~ /(?>a[bc]*c)/ |
| 2658 |
.Ve |
| 2659 |
.Sp |
| 2660 |
matches, but |
| 2661 |
.Sp |
| 2662 |
.Vb 1 |
| 2663 |
\& "abc" =~ /(?>a(?>[bc]*)c)/ |
| 2664 |
.Ve |
| 2665 |
.Sp |
| 2666 |
does not. |
| 2667 |
.ie n .IP """(?[ ])""" 4 |
| 2668 |
.el .IP "\f(CW(?[ ])\fR" 4 |
| 2669 |
.IX Item "(?[ ])" |
| 2670 |
See "Extended Bracketed Character Classes" in perlrecharclass. |
| 2671 |
.SS Backtracking |
| 2672 |
.IX Xref "backtrack backtracking" |
| 2673 |
.IX Subsection "Backtracking" |
| 2674 |
NOTE: This section presents an abstract approximation of regular |
| 2675 |
expression behavior. For a more rigorous (and complicated) view of |
| 2676 |
the rules involved in selecting a match among possible alternatives, |
| 2677 |
see "Combining RE Pieces". |
| 2678 |
.PP |
| 2679 |
A fundamental feature of regular expression matching involves the |
| 2680 |
notion called \fIbacktracking\fR, which is currently used (when needed) |
| 2681 |
by all regular non-possessive expression quantifiers, namely \f(CW"*"\fR, |
| 2682 |
\&\f(CW\*(C`*?\*(C'\fR, \f(CW"+"\fR, \f(CW\*(C`+?\*(C'\fR, \f(CW\*(C`{n,m}\*(C'\fR, and \f(CW\*(C`{n,m}?\*(C'\fR. Backtracking is often |
| 2683 |
optimized internally, but the general principle outlined here is valid. |
| 2684 |
.PP |
| 2685 |
For a regular expression to match, the \fIentire\fR regular expression must |
| 2686 |
match, not just part of it. So if the beginning of a pattern containing a |
| 2687 |
quantifier succeeds in a way that causes later parts in the pattern to |
| 2688 |
fail, the matching engine backs up and recalculates the beginning |
| 2689 |
part\-\-that's why it's called backtracking. |
| 2690 |
.PP |
| 2691 |
Here is an example of backtracking: Let's say you want to find the |
| 2692 |
word following "foo" in the string "Food is on the foo table.": |
| 2693 |
.PP |
| 2694 |
.Vb 4 |
| 2695 |
\& $_ = "Food is on the foo table."; |
| 2696 |
\& if ( /\eb(foo)\es+(\ew+)/i ) { |
| 2697 |
\& print "$2 follows $1.\en"; |
| 2698 |
\& } |
| 2699 |
.Ve |
| 2700 |
.PP |
| 2701 |
When the match runs, the first part of the regular expression (\f(CW\*(C`\eb(foo)\*(C'\fR) |
| 2702 |
finds a possible match right at the beginning of the string, and loads up |
| 2703 |
\&\f(CW$1\fR with "Foo". However, as soon as the matching engine sees that there's |
| 2704 |
no whitespace following the "Foo" that it had saved in \f(CW$1\fR, it realizes its |
| 2705 |
mistake and starts over again one character after where it had the |
| 2706 |
tentative match. This time it goes all the way until the next occurrence |
| 2707 |
of "foo". The complete regular expression matches this time, and you get |
| 2708 |
the expected output of "table follows foo." |
| 2709 |
.PP |
| 2710 |
Sometimes minimal matching can help a lot. Imagine you'd like to match |
| 2711 |
everything between "foo" and "bar". Initially, you write something |
| 2712 |
like this: |
| 2713 |
.PP |
| 2714 |
.Vb 4 |
| 2715 |
\& $_ = "The food is under the bar in the barn."; |
| 2716 |
\& if ( /foo(.*)bar/ ) { |
| 2717 |
\& print "got <$1>\en"; |
| 2718 |
\& } |
| 2719 |
.Ve |
| 2720 |
.PP |
| 2721 |
Which perhaps unexpectedly yields: |
| 2722 |
.PP |
| 2723 |
.Vb 1 |
| 2724 |
\& got <d is under the bar in the > |
| 2725 |
.Ve |
| 2726 |
.PP |
| 2727 |
That's because \f(CW\*(C`.*\*(C'\fR was greedy, so you get everything between the |
| 2728 |
\&\fIfirst\fR "foo" and the \fIlast\fR "bar". Here it's more effective |
| 2729 |
to use minimal matching to make sure you get the text between a "foo" |
| 2730 |
and the first "bar" thereafter. |
| 2731 |
.PP |
| 2732 |
.Vb 2 |
| 2733 |
\& if ( /foo(.*?)bar/ ) { print "got <$1>\en" } |
| 2734 |
\& got <d is under the > |
| 2735 |
.Ve |
| 2736 |
.PP |
| 2737 |
Here's another example. Let's say you'd like to match a number at the end |
| 2738 |
of a string, and you also want to keep the preceding part of the match. |
| 2739 |
So you write this: |
| 2740 |
.PP |
| 2741 |
.Vb 4 |
| 2742 |
\& $_ = "I have 2 numbers: 53147"; |
| 2743 |
\& if ( /(.*)(\ed*)/ ) { # Wrong! |
| 2744 |
\& print "Beginning is <$1>, number is <$2>.\en"; |
| 2745 |
\& } |
| 2746 |
.Ve |
| 2747 |
.PP |
| 2748 |
That won't work at all, because \f(CW\*(C`.*\*(C'\fR was greedy and gobbled up the |
| 2749 |
whole string. As \f(CW\*(C`\ed*\*(C'\fR can match on an empty string the complete |
| 2750 |
regular expression matched successfully. |
| 2751 |
.PP |
| 2752 |
.Vb 1 |
| 2753 |
\& Beginning is <I have 2 numbers: 53147>, number is <>. |
| 2754 |
.Ve |
| 2755 |
.PP |
| 2756 |
Here are some variants, most of which don't work: |
| 2757 |
.PP |
| 2758 |
.Vb 11 |
| 2759 |
\& $_ = "I have 2 numbers: 53147"; |
| 2760 |
\& @pats = qw{ |
| 2761 |
\& (.*)(\ed*) |
| 2762 |
\& (.*)(\ed+) |
| 2763 |
\& (.*?)(\ed*) |
| 2764 |
\& (.*?)(\ed+) |
| 2765 |
\& (.*)(\ed+)$ |
| 2766 |
\& (.*?)(\ed+)$ |
| 2767 |
\& (.*)\eb(\ed+)$ |
| 2768 |
\& (.*\eD)(\ed+)$ |
| 2769 |
\& }; |
| 2770 |
\& |
| 2771 |
\& for $pat (@pats) { |
| 2772 |
\& printf "%\-12s ", $pat; |
| 2773 |
\& if ( /$pat/ ) { |
| 2774 |
\& print "<$1> <$2>\en"; |
| 2775 |
\& } else { |
| 2776 |
\& print "FAIL\en"; |
| 2777 |
\& } |
| 2778 |
\& } |
| 2779 |
.Ve |
| 2780 |
.PP |
| 2781 |
That will print out: |
| 2782 |
.PP |
| 2783 |
.Vb 8 |
| 2784 |
\& (.*)(\ed*) <I have 2 numbers: 53147> <> |
| 2785 |
\& (.*)(\ed+) <I have 2 numbers: 5314> <7> |
| 2786 |
\& (.*?)(\ed*) <> <> |
| 2787 |
\& (.*?)(\ed+) <I have > <2> |
| 2788 |
\& (.*)(\ed+)$ <I have 2 numbers: 5314> <7> |
| 2789 |
\& (.*?)(\ed+)$ <I have 2 numbers: > <53147> |
| 2790 |
\& (.*)\eb(\ed+)$ <I have 2 numbers: > <53147> |
| 2791 |
\& (.*\eD)(\ed+)$ <I have 2 numbers: > <53147> |
| 2792 |
.Ve |
| 2793 |
.PP |
| 2794 |
As you see, this can be a bit tricky. It's important to realize that a |
| 2795 |
regular expression is merely a set of assertions that gives a definition |
| 2796 |
of success. There may be 0, 1, or several different ways that the |
| 2797 |
definition might succeed against a particular string. And if there are |
| 2798 |
multiple ways it might succeed, you need to understand backtracking to |
| 2799 |
know which variety of success you will achieve. |
| 2800 |
.PP |
| 2801 |
When using lookahead assertions and negations, this can all get even |
| 2802 |
trickier. Imagine you'd like to find a sequence of non-digits not |
| 2803 |
followed by "123". You might try to write that as |
| 2804 |
.PP |
| 2805 |
.Vb 4 |
| 2806 |
\& $_ = "ABC123"; |
| 2807 |
\& if ( /^\eD*(?!123)/ ) { # Wrong! |
| 2808 |
\& print "Yup, no 123 in $_\en"; |
| 2809 |
\& } |
| 2810 |
.Ve |
| 2811 |
.PP |
| 2812 |
But that isn't going to match; at least, not the way you're hoping. It |
| 2813 |
claims that there is no 123 in the string. Here's a clearer picture of |
| 2814 |
why that pattern matches, contrary to popular expectations: |
| 2815 |
.PP |
| 2816 |
.Vb 2 |
| 2817 |
\& $x = \*(AqABC123\*(Aq; |
| 2818 |
\& $y = \*(AqABC445\*(Aq; |
| 2819 |
\& |
| 2820 |
\& print "1: got $1\en" if $x =~ /^(ABC)(?!123)/; |
| 2821 |
\& print "2: got $1\en" if $y =~ /^(ABC)(?!123)/; |
| 2822 |
\& |
| 2823 |
\& print "3: got $1\en" if $x =~ /^(\eD*)(?!123)/; |
| 2824 |
\& print "4: got $1\en" if $y =~ /^(\eD*)(?!123)/; |
| 2825 |
.Ve |
| 2826 |
.PP |
| 2827 |
This prints |
| 2828 |
.PP |
| 2829 |
.Vb 3 |
| 2830 |
\& 2: got ABC |
| 2831 |
\& 3: got AB |
| 2832 |
\& 4: got ABC |
| 2833 |
.Ve |
| 2834 |
.PP |
| 2835 |
You might have expected test 3 to fail because it seems to a more |
| 2836 |
general purpose version of test 1. The important difference between |
| 2837 |
them is that test 3 contains a quantifier (\f(CW\*(C`\eD*\*(C'\fR) and so can use |
| 2838 |
backtracking, whereas test 1 will not. What's happening is |
| 2839 |
that you've asked "Is it true that at the start of \f(CW$x\fR, following 0 or more |
| 2840 |
non-digits, you have something that's not 123?" If the pattern matcher had |
| 2841 |
let \f(CW\*(C`\eD*\*(C'\fR expand to "ABC", this would have caused the whole pattern to |
| 2842 |
fail. |
| 2843 |
.PP |
| 2844 |
The search engine will initially match \f(CW\*(C`\eD*\*(C'\fR with "ABC". Then it will |
| 2845 |
try to match \f(CW\*(C`(?!123)\*(C'\fR with "123", which fails. But because |
| 2846 |
a quantifier (\f(CW\*(C`\eD*\*(C'\fR) has been used in the regular expression, the |
| 2847 |
search engine can backtrack and retry the match differently |
| 2848 |
in the hope of matching the complete regular expression. |
| 2849 |
.PP |
| 2850 |
The pattern really, \fIreally\fR wants to succeed, so it uses the |
| 2851 |
standard pattern back-off-and-retry and lets \f(CW\*(C`\eD*\*(C'\fR expand to just "AB" this |
| 2852 |
time. Now there's indeed something following "AB" that is not |
| 2853 |
"123". It's "C123", which suffices. |
| 2854 |
.PP |
| 2855 |
We can deal with this by using both an assertion and a negation. |
| 2856 |
We'll say that the first part in \f(CW$1\fR must be followed both by a digit |
| 2857 |
and by something that's not "123". Remember that the lookaheads |
| 2858 |
are zero-width expressions\-\-they only look, but don't consume any |
| 2859 |
of the string in their match. So rewriting this way produces what |
| 2860 |
you'd expect; that is, case 5 will fail, but case 6 succeeds: |
| 2861 |
.PP |
| 2862 |
.Vb 2 |
| 2863 |
\& print "5: got $1\en" if $x =~ /^(\eD*)(?=\ed)(?!123)/; |
| 2864 |
\& print "6: got $1\en" if $y =~ /^(\eD*)(?=\ed)(?!123)/; |
| 2865 |
\& |
| 2866 |
\& 6: got ABC |
| 2867 |
.Ve |
| 2868 |
.PP |
| 2869 |
In other words, the two zero-width assertions next to each other work as though |
| 2870 |
they're ANDed together, just as you'd use any built-in assertions: \f(CW\*(C`/^$/\*(C'\fR |
| 2871 |
matches only if you're at the beginning of the line AND the end of the |
| 2872 |
line simultaneously. The deeper underlying truth is that juxtaposition in |
| 2873 |
regular expressions always means AND, except when you write an explicit OR |
| 2874 |
using the vertical bar. \f(CW\*(C`/ab/\*(C'\fR means match "a" AND (then) match "b", |
| 2875 |
although the attempted matches are made at different positions because "a" |
| 2876 |
is not a zero-width assertion, but a one-width assertion. |
| 2877 |
.PP |
| 2878 |
\&\fBWARNING\fR: Particularly complicated regular expressions can take |
| 2879 |
exponential time to solve because of the immense number of possible |
| 2880 |
ways they can use backtracking to try for a match. For example, without |
| 2881 |
internal optimizations done by the regular expression engine, this will |
| 2882 |
take a painfully long time to run: |
| 2883 |
.PP |
| 2884 |
.Vb 1 |
| 2885 |
\& \*(Aqaaaaaaaaaaaa\*(Aq =~ /((a{0,5}){0,5})*[c]/ |
| 2886 |
.Ve |
| 2887 |
.PP |
| 2888 |
And if you used \f(CW"*"\fR's in the internal groups instead of limiting them |
| 2889 |
to 0 through 5 matches, then it would take forever\-\-or until you ran |
| 2890 |
out of stack space. Moreover, these internal optimizations are not |
| 2891 |
always applicable. For example, if you put \f(CW\*(C`{0,5}\*(C'\fR instead of \f(CW"*"\fR |
| 2892 |
on the external group, no current optimization is applicable, and the |
| 2893 |
match takes a long time to finish. |
| 2894 |
.PP |
| 2895 |
A powerful tool for optimizing such beasts is what is known as an |
| 2896 |
"independent group", |
| 2897 |
which does not backtrack (see \f(CW"(?>pattern)"\fR). Note also that |
| 2898 |
zero-length lookahead/lookbehind assertions will not backtrack to make |
| 2899 |
the tail match, since they are in "logical" context: only |
| 2900 |
whether they match is considered relevant. For an example |
| 2901 |
where side-effects of lookahead \fImight\fR have influenced the |
| 2902 |
following match, see \f(CW"(?>pattern)"\fR. |
| 2903 |
.SS "Script Runs" |
| 2904 |
.IX Xref "(*script_run:...) (sr:...) (*atomic_script_run:...) (asr:...)" |
| 2905 |
.IX Subsection "Script Runs" |
| 2906 |
A script run is basically a sequence of characters, all from the same |
| 2907 |
Unicode script (see "Scripts" in perlunicode), such as Latin or Greek. In |
| 2908 |
most places a single word would never be written in multiple scripts, |
| 2909 |
unless it is a spoofing attack. An infamous example, is |
| 2910 |
.PP |
| 2911 |
.Vb 1 |
| 2912 |
\& paypal.com |
| 2913 |
.Ve |
| 2914 |
.PP |
| 2915 |
Those letters could all be Latin (as in the example just above), or they |
| 2916 |
could be all Cyrillic (except for the dot), or they could be a mixture |
| 2917 |
of the two. In the case of an internet address the \f(CW\*(C`.com\*(C'\fR would be in |
| 2918 |
Latin, And any Cyrillic ones would cause it to be a mixture, not a |
| 2919 |
script run. Someone clicking on such a link would not be directed to |
| 2920 |
the real Paypal website, but an attacker would craft a look-alike one to |
| 2921 |
attempt to gather sensitive information from the person. |
| 2922 |
.PP |
| 2923 |
Starting in Perl 5.28, it is now easy to detect strings that aren't |
| 2924 |
script runs. Simply enclose just about any pattern like either of |
| 2925 |
these: |
| 2926 |
.PP |
| 2927 |
.Vb 2 |
| 2928 |
\& (*script_run:pattern) |
| 2929 |
\& (*sr:pattern) |
| 2930 |
.Ve |
| 2931 |
.PP |
| 2932 |
What happens is that after \fIpattern\fR succeeds in matching, it is |
| 2933 |
subjected to the additional criterion that every character in it must be |
| 2934 |
from the same script (see exceptions below). If this isn't true, |
| 2935 |
backtracking occurs until something all in the same script is found that |
| 2936 |
matches, or all possibilities are exhausted. This can cause a lot of |
| 2937 |
backtracking, but generally, only malicious input will result in this, |
| 2938 |
though the slow down could cause a denial of service attack. If your |
| 2939 |
needs permit, it is best to make the pattern atomic to cut down on the |
| 2940 |
amount of backtracking. This is so likely to be what you want, that |
| 2941 |
instead of writing this: |
| 2942 |
.PP |
| 2943 |
.Vb 1 |
| 2944 |
\& (*script_run:(?>pattern)) |
| 2945 |
.Ve |
| 2946 |
.PP |
| 2947 |
you can write either of these: |
| 2948 |
.PP |
| 2949 |
.Vb 2 |
| 2950 |
\& (*atomic_script_run:pattern) |
| 2951 |
\& (*asr:pattern) |
| 2952 |
.Ve |
| 2953 |
.PP |
| 2954 |
(See \f(CW"(?>\fR\f(CIpattern\fR\f(CW)"\fR.) |
| 2955 |
.PP |
| 2956 |
In Taiwan, Japan, and Korea, it is common for text to have a mixture of |
| 2957 |
characters from their native scripts and base Chinese. Perl follows |
| 2958 |
Unicode's UTS 39 (<https://unicode.org/reports/tr39/>) Unicode Security |
| 2959 |
Mechanisms in allowing such mixtures. For example, the Japanese scripts |
| 2960 |
Katakana and Hiragana are commonly mixed together in practice, along |
| 2961 |
with some Chinese characters, and hence are treated as being in a single |
| 2962 |
script run by Perl. |
| 2963 |
.PP |
| 2964 |
The rules used for matching decimal digits are slightly stricter. Many |
| 2965 |
scripts have their own sets of digits equivalent to the Western \f(CW0\fR |
| 2966 |
through \f(CW9\fR ones. A few, such as Arabic, have more than one set. For |
| 2967 |
a string to be considered a script run, all digits in it must come from |
| 2968 |
the same set of ten, as determined by the first digit encountered. |
| 2969 |
As an example, |
| 2970 |
.PP |
| 2971 |
.Vb 1 |
| 2972 |
\& qr/(*script_run: \ed+ \eb )/x |
| 2973 |
.Ve |
| 2974 |
.PP |
| 2975 |
guarantees that the digits matched will all be from the same set of 10. |
| 2976 |
You won't get a look-alike digit from a different script that has a |
| 2977 |
different value than what it appears to be. |
| 2978 |
.PP |
| 2979 |
Unicode has three pseudo scripts that are handled specially. |
| 2980 |
.PP |
| 2981 |
"Unknown" is applied to code points whose meaning has yet to be |
| 2982 |
determined. Perl currently will match as a script run, any single |
| 2983 |
character string consisting of one of these code points. But any string |
| 2984 |
longer than one code point containing one of these will not be |
| 2985 |
considered a script run. |
| 2986 |
.PP |
| 2987 |
"Inherited" is applied to characters that modify another, such as an |
| 2988 |
accent of some type. These are considered to be in the script of the |
| 2989 |
master character, and so never cause a script run to not match. |
| 2990 |
.PP |
| 2991 |
The other one is "Common". This consists of mostly punctuation, emoji, |
| 2992 |
characters used in mathematics and music, the ASCII digits \f(CW0\fR |
| 2993 |
through \f(CW9\fR, and full-width forms of these digits. These characters |
| 2994 |
can appear intermixed in text in many of the world's scripts. These |
| 2995 |
also don't cause a script run to not match. But like other scripts, all |
| 2996 |
digits in a run must come from the same set of 10. |
| 2997 |
.PP |
| 2998 |
This construct is non-capturing. You can add parentheses to \fIpattern\fR |
| 2999 |
to capture, if desired. You will have to do this if you plan to use |
| 3000 |
"(*ACCEPT) (*ACCEPT:arg)" and not have it bypass the script run |
| 3001 |
checking. |
| 3002 |
.PP |
| 3003 |
The \f(CW\*(C`Script_Extensions\*(C'\fR property as modified by UTS 39 |
| 3004 |
(<https://unicode.org/reports/tr39/>) is used as the basis for this |
| 3005 |
feature. |
| 3006 |
.PP |
| 3007 |
To summarize, |
| 3008 |
.IP \(bu 4 |
| 3009 |
All length 0 or length 1 sequences are script runs. |
| 3010 |
.IP \(bu 4 |
| 3011 |
A longer sequence is a script run if and only if \fBall\fR of the following |
| 3012 |
conditions are met: |
| 3013 |
.Sp |
| 3014 |
|
| 3015 |
.RS 4 |
| 3016 |
.IP 1. 4 |
| 3017 |
No code point in the sequence has the \f(CW\*(C`Script_Extension\*(C'\fR property of |
| 3018 |
\&\f(CW\*(C`Unknown\*(C'\fR. |
| 3019 |
.Sp |
| 3020 |
This currently means that all code points in the sequence have been |
| 3021 |
assigned by Unicode to be characters that aren't private use nor |
| 3022 |
surrogate code points. |
| 3023 |
.IP 2. 4 |
| 3024 |
All characters in the sequence come from the Common script and/or the |
| 3025 |
Inherited script and/or a single other script. |
| 3026 |
.Sp |
| 3027 |
The script of a character is determined by the \f(CW\*(C`Script_Extensions\*(C'\fR |
| 3028 |
property as modified by UTS 39 (<https://unicode.org/reports/tr39/>), as |
| 3029 |
described above. |
| 3030 |
.IP 3. 4 |
| 3031 |
All decimal digits in the sequence come from the same block of 10 |
| 3032 |
consecutive digits. |
| 3033 |
.RE |
| 3034 |
.RS 4 |
| 3035 |
.RE |
| 3036 |
.SS "Special Backtracking Control Verbs" |
| 3037 |
.IX Subsection "Special Backtracking Control Verbs" |
| 3038 |
These special patterns are generally of the form \f(CW\*(C`(*\fR\f(CIVERB\fR\f(CW:\fR\f(CIarg\fR\f(CW)\*(C'\fR. Unless |
| 3039 |
otherwise stated the \fIarg\fR argument is optional; in some cases, it is |
| 3040 |
mandatory. |
| 3041 |
.PP |
| 3042 |
Any pattern containing a special backtracking verb that allows an argument |
| 3043 |
has the special behaviour that when executed it sets the current package's |
| 3044 |
\&\f(CW$REGERROR\fR and \f(CW$REGMARK\fR variables. When doing so the following |
| 3045 |
rules apply: |
| 3046 |
.PP |
| 3047 |
On failure, the \f(CW$REGERROR\fR variable will be set to the \fIarg\fR value of the |
| 3048 |
verb pattern, if the verb was involved in the failure of the match. If the |
| 3049 |
\&\fIarg\fR part of the pattern was omitted, then \f(CW$REGERROR\fR will be set to the |
| 3050 |
name of the last \f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR pattern executed, or to TRUE if there was |
| 3051 |
none. Also, the \f(CW$REGMARK\fR variable will be set to FALSE. |
| 3052 |
.PP |
| 3053 |
On a successful match, the \f(CW$REGERROR\fR variable will be set to FALSE, and |
| 3054 |
the \f(CW$REGMARK\fR variable will be set to the name of the last |
| 3055 |
\&\f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR pattern executed. See the explanation for the |
| 3056 |
\&\f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR verb below for more details. |
| 3057 |
.PP |
| 3058 |
\&\fBNOTE:\fR \f(CW$REGERROR\fR and \f(CW$REGMARK\fR are not magic variables like \f(CW$1\fR |
| 3059 |
and most other regex-related variables. They are not local to a scope, nor |
| 3060 |
readonly, but instead are volatile package variables similar to \f(CW$AUTOLOAD\fR. |
| 3061 |
They are set in the package containing the code that \fIexecuted\fR the regex |
| 3062 |
(rather than the one that compiled it, where those differ). If necessary, you |
| 3063 |
can use \f(CW\*(C`local\*(C'\fR to localize changes to these variables to a specific scope |
| 3064 |
before executing a regex. |
| 3065 |
.PP |
| 3066 |
If a pattern does not contain a special backtracking verb that allows an |
| 3067 |
argument, then \f(CW$REGERROR\fR and \f(CW$REGMARK\fR are not touched at all. |
| 3068 |
.IP Verbs 3 |
| 3069 |
.IX Item "Verbs" |
| 3070 |
.RS 3 |
| 3071 |
.PD 0 |
| 3072 |
.ie n .IP """(*PRUNE)"" ""(*PRUNE:\fINAME\fR)""" 4 |
| 3073 |
.el .IP "\f(CW(*PRUNE)\fR \f(CW(*PRUNE:\fR\f(CINAME\fR\f(CW)\fR" 4 |
| 3074 |
.IX Xref "(*PRUNE) (*PRUNE:NAME)" |
| 3075 |
.IX Item "(*PRUNE) (*PRUNE:NAME)" |
| 3076 |
.PD |
| 3077 |
This zero-width pattern prunes the backtracking tree at the current point |
| 3078 |
when backtracked into on failure. Consider the pattern \f(CW\*(C`/\fR\f(CIA\fR\f(CW (*PRUNE) \fR\f(CIB\fR\f(CW/\*(C'\fR, |
| 3079 |
where \fIA\fR and \fIB\fR are complex patterns. Until the \f(CW\*(C`(*PRUNE)\*(C'\fR verb is reached, |
| 3080 |
\&\fIA\fR may backtrack as necessary to match. Once it is reached, matching |
| 3081 |
continues in \fIB\fR, which may also backtrack as necessary; however, should B |
| 3082 |
not match, then no further backtracking will take place, and the pattern |
| 3083 |
will fail outright at the current starting position. |
| 3084 |
.Sp |
| 3085 |
The following example counts all the possible matching strings in a |
| 3086 |
pattern (without actually matching any of them). |
| 3087 |
.Sp |
| 3088 |
.Vb 2 |
| 3089 |
\& \*(Aqaaab\*(Aq =~ /a+b?(?{print "$&\en"; $count++})(*FAIL)/; |
| 3090 |
\& print "Count=$count\en"; |
| 3091 |
.Ve |
| 3092 |
.Sp |
| 3093 |
which produces: |
| 3094 |
.Sp |
| 3095 |
.Vb 10 |
| 3096 |
\& aaab |
| 3097 |
\& aaa |
| 3098 |
\& aa |
| 3099 |
\& a |
| 3100 |
\& aab |
| 3101 |
\& aa |
| 3102 |
\& a |
| 3103 |
\& ab |
| 3104 |
\& a |
| 3105 |
\& Count=9 |
| 3106 |
.Ve |
| 3107 |
.Sp |
| 3108 |
If we add a \f(CW\*(C`(*PRUNE)\*(C'\fR before the count like the following |
| 3109 |
.Sp |
| 3110 |
.Vb 2 |
| 3111 |
\& \*(Aqaaab\*(Aq =~ /a+b?(*PRUNE)(?{print "$&\en"; $count++})(*FAIL)/; |
| 3112 |
\& print "Count=$count\en"; |
| 3113 |
.Ve |
| 3114 |
.Sp |
| 3115 |
we prevent backtracking and find the count of the longest matching string |
| 3116 |
at each matching starting point like so: |
| 3117 |
.Sp |
| 3118 |
.Vb 4 |
| 3119 |
\& aaab |
| 3120 |
\& aab |
| 3121 |
\& ab |
| 3122 |
\& Count=3 |
| 3123 |
.Ve |
| 3124 |
.Sp |
| 3125 |
Any number of \f(CW\*(C`(*PRUNE)\*(C'\fR assertions may be used in a pattern. |
| 3126 |
.Sp |
| 3127 |
See also \f(CW"(?>\fR\f(CIpattern\fR\f(CW)"\fR and possessive quantifiers for |
| 3128 |
other ways to |
| 3129 |
control backtracking. In some cases, the use of \f(CW\*(C`(*PRUNE)\*(C'\fR can be |
| 3130 |
replaced with a \f(CW\*(C`(?>pattern)\*(C'\fR with no functional difference; however, |
| 3131 |
\&\f(CW\*(C`(*PRUNE)\*(C'\fR can be used to handle cases that cannot be expressed using a |
| 3132 |
\&\f(CW\*(C`(?>pattern)\*(C'\fR alone. |
| 3133 |
.ie n .IP """(*SKIP)"" ""(*SKIP:\fINAME\fR)""" 4 |
| 3134 |
.el .IP "\f(CW(*SKIP)\fR \f(CW(*SKIP:\fR\f(CINAME\fR\f(CW)\fR" 4 |
| 3135 |
.IX Xref "(*SKIP)" |
| 3136 |
.IX Item "(*SKIP) (*SKIP:NAME)" |
| 3137 |
This zero-width pattern is similar to \f(CW\*(C`(*PRUNE)\*(C'\fR, except that on |
| 3138 |
failure it also signifies that whatever text that was matched leading up |
| 3139 |
to the \f(CW\*(C`(*SKIP)\*(C'\fR pattern being executed cannot be part of \fIany\fR match |
| 3140 |
of this pattern. This effectively means that the regex engine "skips" forward |
| 3141 |
to this position on failure and tries to match again, (assuming that |
| 3142 |
there is sufficient room to match). |
| 3143 |
.Sp |
| 3144 |
The name of the \f(CW\*(C`(*SKIP:\fR\f(CINAME\fR\f(CW)\*(C'\fR pattern has special significance. If a |
| 3145 |
\&\f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR was encountered while matching, then it is that position |
| 3146 |
which is used as the "skip point". If no \f(CW\*(C`(*MARK)\*(C'\fR of that name was |
| 3147 |
encountered, then the \f(CW\*(C`(*SKIP)\*(C'\fR operator has no effect. When used |
| 3148 |
without a name the "skip point" is where the match point was when |
| 3149 |
executing the \f(CW\*(C`(*SKIP)\*(C'\fR pattern. |
| 3150 |
.Sp |
| 3151 |
Compare the following to the examples in \f(CW\*(C`(*PRUNE)\*(C'\fR; note the string |
| 3152 |
is twice as long: |
| 3153 |
.Sp |
| 3154 |
.Vb 2 |
| 3155 |
\& \*(Aqaaabaaab\*(Aq =~ /a+b?(*SKIP)(?{print "$&\en"; $count++})(*FAIL)/; |
| 3156 |
\& print "Count=$count\en"; |
| 3157 |
.Ve |
| 3158 |
.Sp |
| 3159 |
outputs |
| 3160 |
.Sp |
| 3161 |
.Vb 3 |
| 3162 |
\& aaab |
| 3163 |
\& aaab |
| 3164 |
\& Count=2 |
| 3165 |
.Ve |
| 3166 |
.Sp |
| 3167 |
Once the 'aaab' at the start of the string has matched, and the \f(CW\*(C`(*SKIP)\*(C'\fR |
| 3168 |
executed, the next starting point will be where the cursor was when the |
| 3169 |
\&\f(CW\*(C`(*SKIP)\*(C'\fR was executed. |
| 3170 |
.ie n .IP """(*MARK:\fINAME\fR)"" ""(*:\fINAME\fR)""" 4 |
| 3171 |
.el .IP "\f(CW(*MARK:\fR\f(CINAME\fR\f(CW)\fR \f(CW(*:\fR\f(CINAME\fR\f(CW)\fR" 4 |
| 3172 |
.IX Xref "(*MARK) (*MARK:NAME) (*:NAME)" |
| 3173 |
.IX Item "(*MARK:NAME) (*:NAME)" |
| 3174 |
This zero-width pattern can be used to mark the point reached in a string |
| 3175 |
when a certain part of the pattern has been successfully matched. This |
| 3176 |
mark may be given a name. A later \f(CW\*(C`(*SKIP)\*(C'\fR pattern will then skip |
| 3177 |
forward to that point if backtracked into on failure. Any number of |
| 3178 |
\&\f(CW\*(C`(*MARK)\*(C'\fR patterns are allowed, and the \fINAME\fR portion may be duplicated. |
| 3179 |
.Sp |
| 3180 |
In addition to interacting with the \f(CW\*(C`(*SKIP)\*(C'\fR pattern, \f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR |
| 3181 |
can be used to "label" a pattern branch, so that after matching, the |
| 3182 |
program can determine which branches of the pattern were involved in the |
| 3183 |
match. |
| 3184 |
.Sp |
| 3185 |
When a match is successful, the \f(CW$REGMARK\fR variable will be set to the |
| 3186 |
name of the most recently executed \f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR that was involved |
| 3187 |
in the match. |
| 3188 |
.Sp |
| 3189 |
This can be used to determine which branch of a pattern was matched |
| 3190 |
without using a separate capture group for each branch, which in turn |
| 3191 |
can result in a performance improvement, as perl cannot optimize |
| 3192 |
\&\f(CW\*(C`/(?:(x)|(y)|(z))/\*(C'\fR as efficiently as something like |
| 3193 |
\&\f(CW\*(C`/(?:x(*MARK:x)|y(*MARK:y)|z(*MARK:z))/\*(C'\fR. |
| 3194 |
.Sp |
| 3195 |
When a match has failed, and unless another verb has been involved in |
| 3196 |
failing the match and has provided its own name to use, the \f(CW$REGERROR\fR |
| 3197 |
variable will be set to the name of the most recently executed |
| 3198 |
\&\f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR. |
| 3199 |
.Sp |
| 3200 |
See "(*SKIP)" for more details. |
| 3201 |
.Sp |
| 3202 |
As a shortcut \f(CW\*(C`(*MARK:\fR\f(CINAME\fR\f(CW)\*(C'\fR can be written \f(CW\*(C`(*:\fR\f(CINAME\fR\f(CW)\*(C'\fR. |
| 3203 |
.ie n .IP """(*THEN)"" ""(*THEN:\fINAME\fR)""" 4 |
| 3204 |
.el .IP "\f(CW(*THEN)\fR \f(CW(*THEN:\fR\f(CINAME\fR\f(CW)\fR" 4 |
| 3205 |
.IX Item "(*THEN) (*THEN:NAME)" |
| 3206 |
This is similar to the "cut group" operator \f(CW\*(C`::\*(C'\fR from Raku. Like |
| 3207 |
\&\f(CW\*(C`(*PRUNE)\*(C'\fR, this verb always matches, and when backtracked into on |
| 3208 |
failure, it causes the regex engine to try the next alternation in the |
| 3209 |
innermost enclosing group (capturing or otherwise) that has alternations. |
| 3210 |
The two branches of a \f(CW\*(C`(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-pattern\fR\f(CW|\fR\f(CIno\-pattern\fR\f(CW)\*(C'\fR do not |
| 3211 |
count as an alternation, as far as \f(CW\*(C`(*THEN)\*(C'\fR is concerned. |
| 3212 |
.Sp |
| 3213 |
Its name comes from the observation that this operation combined with the |
| 3214 |
alternation operator (\f(CW"|"\fR) can be used to create what is essentially a |
| 3215 |
pattern-based if/then/else block: |
| 3216 |
.Sp |
| 3217 |
.Vb 1 |
| 3218 |
\& ( COND (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ ) |
| 3219 |
.Ve |
| 3220 |
.Sp |
| 3221 |
Note that if this operator is used and NOT inside of an alternation then |
| 3222 |
it acts exactly like the \f(CW\*(C`(*PRUNE)\*(C'\fR operator. |
| 3223 |
.Sp |
| 3224 |
.Vb 1 |
| 3225 |
\& / A (*PRUNE) B / |
| 3226 |
.Ve |
| 3227 |
.Sp |
| 3228 |
is the same as |
| 3229 |
.Sp |
| 3230 |
.Vb 1 |
| 3231 |
\& / A (*THEN) B / |
| 3232 |
.Ve |
| 3233 |
.Sp |
| 3234 |
but |
| 3235 |
.Sp |
| 3236 |
.Vb 1 |
| 3237 |
\& / ( A (*THEN) B | C ) / |
| 3238 |
.Ve |
| 3239 |
.Sp |
| 3240 |
is not the same as |
| 3241 |
.Sp |
| 3242 |
.Vb 1 |
| 3243 |
\& / ( A (*PRUNE) B | C ) / |
| 3244 |
.Ve |
| 3245 |
.Sp |
| 3246 |
as after matching the \fIA\fR but failing on the \fIB\fR the \f(CW\*(C`(*THEN)\*(C'\fR verb will |
| 3247 |
backtrack and try \fIC\fR; but the \f(CW\*(C`(*PRUNE)\*(C'\fR verb will simply fail. |
| 3248 |
.ie n .IP """(*COMMIT)"" ""(*COMMIT:\fIarg\fR)""" 4 |
| 3249 |
.el .IP "\f(CW(*COMMIT)\fR \f(CW(*COMMIT:\fR\f(CIarg\fR\f(CW)\fR" 4 |
| 3250 |
.IX Xref "(*COMMIT)" |
| 3251 |
.IX Item "(*COMMIT) (*COMMIT:arg)" |
| 3252 |
This is the Raku "commit pattern" \f(CW\*(C`<commit>\*(C'\fR or \f(CW\*(C`:::\*(C'\fR. It's a |
| 3253 |
zero-width pattern similar to \f(CW\*(C`(*SKIP)\*(C'\fR, except that when backtracked |
| 3254 |
into on failure it causes the match to fail outright. No further attempts |
| 3255 |
to find a valid match by advancing the start pointer will occur again. |
| 3256 |
For example, |
| 3257 |
.Sp |
| 3258 |
.Vb 2 |
| 3259 |
\& \*(Aqaaabaaab\*(Aq =~ /a+b?(*COMMIT)(?{print "$&\en"; $count++})(*FAIL)/; |
| 3260 |
\& print "Count=$count\en"; |
| 3261 |
.Ve |
| 3262 |
.Sp |
| 3263 |
outputs |
| 3264 |
.Sp |
| 3265 |
.Vb 2 |
| 3266 |
\& aaab |
| 3267 |
\& Count=1 |
| 3268 |
.Ve |
| 3269 |
.Sp |
| 3270 |
In other words, once the \f(CW\*(C`(*COMMIT)\*(C'\fR has been entered, and if the pattern |
| 3271 |
does not match, the regex engine will not try any further matching on the |
| 3272 |
rest of the string. |
| 3273 |
.ie n .IP """(*FAIL)"" ""(*F)"" ""(*FAIL:\fIarg\fR)""" 4 |
| 3274 |
.el .IP "\f(CW(*FAIL)\fR \f(CW(*F)\fR \f(CW(*FAIL:\fR\f(CIarg\fR\f(CW)\fR" 4 |
| 3275 |
.IX Xref "(*FAIL) (*F)" |
| 3276 |
.IX Item "(*FAIL) (*F) (*FAIL:arg)" |
| 3277 |
This pattern matches nothing and always fails. It can be used to force the |
| 3278 |
engine to backtrack. It is equivalent to \f(CW\*(C`(?!)\*(C'\fR, but easier to read. In |
| 3279 |
fact, \f(CW\*(C`(?!)\*(C'\fR gets optimised into \f(CW\*(C`(*FAIL)\*(C'\fR internally. You can provide |
| 3280 |
an argument so that if the match fails because of this \f(CW\*(C`FAIL\*(C'\fR directive |
| 3281 |
the argument can be obtained from \f(CW$REGERROR\fR. |
| 3282 |
.Sp |
| 3283 |
It is probably useful only when combined with \f(CW\*(C`(?{})\*(C'\fR or \f(CW\*(C`(??{})\*(C'\fR. |
| 3284 |
.ie n .IP """(*ACCEPT)"" ""(*ACCEPT:\fIarg\fR)""" 4 |
| 3285 |
.el .IP "\f(CW(*ACCEPT)\fR \f(CW(*ACCEPT:\fR\f(CIarg\fR\f(CW)\fR" 4 |
| 3286 |
.IX Xref "(*ACCEPT)" |
| 3287 |
.IX Item "(*ACCEPT) (*ACCEPT:arg)" |
| 3288 |
This pattern matches nothing and causes the end of successful matching at |
| 3289 |
the point at which the \f(CW\*(C`(*ACCEPT)\*(C'\fR pattern was encountered, regardless of |
| 3290 |
whether there is actually more to match in the string. When inside of a |
| 3291 |
nested pattern, such as recursion, or in a subpattern dynamically generated |
| 3292 |
via \f(CW\*(C`(??{})\*(C'\fR, only the innermost pattern is ended immediately. |
| 3293 |
.Sp |
| 3294 |
If the \f(CW\*(C`(*ACCEPT)\*(C'\fR is inside of capturing groups then the groups are |
| 3295 |
marked as ended at the point at which the \f(CW\*(C`(*ACCEPT)\*(C'\fR was encountered. |
| 3296 |
For instance: |
| 3297 |
.Sp |
| 3298 |
.Vb 1 |
| 3299 |
\& \*(AqAB\*(Aq =~ /(A (A|B(*ACCEPT)|C) D)(E)/x; |
| 3300 |
.Ve |
| 3301 |
.Sp |
| 3302 |
will match, and \f(CW$1\fR will be \f(CW\*(C`AB\*(C'\fR and \f(CW$2\fR will be \f(CW"B"\fR, \f(CW$3\fR will not |
| 3303 |
be set. If another branch in the inner parentheses was matched, such as in the |
| 3304 |
string 'ACDE', then the \f(CW"D"\fR and \f(CW"E"\fR would have to be matched as well. |
| 3305 |
.Sp |
| 3306 |
You can provide an argument, which will be available in the var |
| 3307 |
\&\f(CW$REGMARK\fR after the match completes. |
| 3308 |
.RE |
| 3309 |
.RS 3 |
| 3310 |
.RE |
| 3311 |
.ie n .SS "Warning on ""\e1"" Instead of $1" |
| 3312 |
.el .SS "Warning on \f(CW\e1\fP Instead of \f(CW$1\fP" |
| 3313 |
.IX Subsection "Warning on 1 Instead of $1" |
| 3314 |
Some people get too used to writing things like: |
| 3315 |
.PP |
| 3316 |
.Vb 1 |
| 3317 |
\& $pattern =~ s/(\eW)/\e\e\e1/g; |
| 3318 |
.Ve |
| 3319 |
.PP |
| 3320 |
This is grandfathered (for \e1 to \e9) for the RHS of a substitute to avoid |
| 3321 |
shocking the |
| 3322 |
\&\fBsed\fR addicts, but it's a dirty habit to get into. That's because in |
| 3323 |
PerlThink, the righthand side of an \f(CW\*(C`s///\*(C'\fR is a double-quoted string. \f(CW\*(C`\e1\*(C'\fR in |
| 3324 |
the usual double-quoted string means a control-A. The customary Unix |
| 3325 |
meaning of \f(CW\*(C`\e1\*(C'\fR is kludged in for \f(CW\*(C`s///\*(C'\fR. However, if you get into the habit |
| 3326 |
of doing that, you get yourself into trouble if you then add an \f(CW\*(C`/e\*(C'\fR |
| 3327 |
modifier. |
| 3328 |
.PP |
| 3329 |
.Vb 1 |
| 3330 |
\& s/(\ed+)/ \e1 + 1 /eg; # causes warning under \-w |
| 3331 |
.Ve |
| 3332 |
.PP |
| 3333 |
Or if you try to do |
| 3334 |
.PP |
| 3335 |
.Vb 1 |
| 3336 |
\& s/(\ed+)/\e1000/; |
| 3337 |
.Ve |
| 3338 |
.PP |
| 3339 |
You can't disambiguate that by saying \f(CW\*(C`\e{1}000\*(C'\fR, whereas you can fix it with |
| 3340 |
\&\f(CW\*(C`${1}000\*(C'\fR. The operation of interpolation should not be confused |
| 3341 |
with the operation of matching a backreference. Certainly they mean two |
| 3342 |
different things on the \fIleft\fR side of the \f(CW\*(C`s///\*(C'\fR. |
| 3343 |
.SS "Repeated Patterns Matching a Zero-length Substring" |
| 3344 |
.IX Subsection "Repeated Patterns Matching a Zero-length Substring" |
| 3345 |
\&\fBWARNING\fR: Difficult material (and prose) ahead. This section needs a rewrite. |
| 3346 |
.PP |
| 3347 |
Regular expressions provide a terse and powerful programming language. As |
| 3348 |
with most other power tools, power comes together with the ability |
| 3349 |
to wreak havoc. |
| 3350 |
.PP |
| 3351 |
A common abuse of this power stems from the ability to make infinite |
| 3352 |
loops using regular expressions, with something as innocuous as: |
| 3353 |
.PP |
| 3354 |
.Vb 1 |
| 3355 |
\& \*(Aqfoo\*(Aq =~ m{ ( o? )* }x; |
| 3356 |
.Ve |
| 3357 |
.PP |
| 3358 |
The \f(CW\*(C`o?\*(C'\fR matches at the beginning of "\f(CW\*(C`foo\*(C'\fR", and since the position |
| 3359 |
in the string is not moved by the match, \f(CW\*(C`o?\*(C'\fR would match again and again |
| 3360 |
because of the \f(CW"*"\fR quantifier. Another common way to create a similar cycle |
| 3361 |
is with the looping modifier \f(CW\*(C`/g\*(C'\fR: |
| 3362 |
.PP |
| 3363 |
.Vb 1 |
| 3364 |
\& @matches = ( \*(Aqfoo\*(Aq =~ m{ o? }xg ); |
| 3365 |
.Ve |
| 3366 |
.PP |
| 3367 |
or |
| 3368 |
.PP |
| 3369 |
.Vb 1 |
| 3370 |
\& print "match: <$&>\en" while \*(Aqfoo\*(Aq =~ m{ o? }xg; |
| 3371 |
.Ve |
| 3372 |
.PP |
| 3373 |
or the loop implied by \f(CWsplit()\fR. |
| 3374 |
.PP |
| 3375 |
However, long experience has shown that many programming tasks may |
| 3376 |
be significantly simplified by using repeated subexpressions that |
| 3377 |
may match zero-length substrings. Here's a simple example being: |
| 3378 |
.PP |
| 3379 |
.Vb 2 |
| 3380 |
\& @chars = split //, $string; # // is not magic in split |
| 3381 |
\& ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// / |
| 3382 |
.Ve |
| 3383 |
.PP |
| 3384 |
Thus Perl allows such constructs, by \fIforcefully breaking |
| 3385 |
the infinite loop\fR. The rules for this are different for lower-level |
| 3386 |
loops given by the greedy quantifiers \f(CW\*(C`*+{}\*(C'\fR, and for higher-level |
| 3387 |
ones like the \f(CW\*(C`/g\*(C'\fR modifier or \f(CWsplit()\fR operator. |
| 3388 |
.PP |
| 3389 |
The lower-level loops are \fIinterrupted\fR (that is, the loop is |
| 3390 |
broken) when Perl detects that a repeated expression matched a |
| 3391 |
zero-length substring. Thus |
| 3392 |
.PP |
| 3393 |
.Vb 1 |
| 3394 |
\& m{ (?: NON_ZERO_LENGTH | ZERO_LENGTH )* }x; |
| 3395 |
.Ve |
| 3396 |
.PP |
| 3397 |
is made equivalent to |
| 3398 |
.PP |
| 3399 |
.Vb 1 |
| 3400 |
\& m{ (?: NON_ZERO_LENGTH )* (?: ZERO_LENGTH )? }x; |
| 3401 |
.Ve |
| 3402 |
.PP |
| 3403 |
For example, this program |
| 3404 |
.PP |
| 3405 |
.Vb 12 |
| 3406 |
\& #!perl \-l |
| 3407 |
\& "aaaaab" =~ / |
| 3408 |
\& (?: |
| 3409 |
\& a # non\-zero |
| 3410 |
\& | # or |
| 3411 |
\& (?{print "hello"}) # print hello whenever this |
| 3412 |
\& # branch is tried |
| 3413 |
\& (?=(b)) # zero\-width assertion |
| 3414 |
\& )* # any number of times |
| 3415 |
\& /x; |
| 3416 |
\& print $&; |
| 3417 |
\& print $1; |
| 3418 |
.Ve |
| 3419 |
.PP |
| 3420 |
prints |
| 3421 |
.PP |
| 3422 |
.Vb 3 |
| 3423 |
\& hello |
| 3424 |
\& aaaaa |
| 3425 |
\& b |
| 3426 |
.Ve |
| 3427 |
.PP |
| 3428 |
Notice that "hello" is only printed once, as when Perl sees that the sixth |
| 3429 |
iteration of the outermost \f(CW\*(C`(?:)*\*(C'\fR matches a zero-length string, it stops |
| 3430 |
the \f(CW"*"\fR. |
| 3431 |
.PP |
| 3432 |
The higher-level loops preserve an additional state between iterations: |
| 3433 |
whether the last match was zero-length. To break the loop, the following |
| 3434 |
match after a zero-length match is prohibited to have a length of zero. |
| 3435 |
This prohibition interacts with backtracking (see "Backtracking"), |
| 3436 |
and so the \fIsecond best\fR match is chosen if the \fIbest\fR match is of |
| 3437 |
zero length. |
| 3438 |
.PP |
| 3439 |
For example: |
| 3440 |
.PP |
| 3441 |
.Vb 2 |
| 3442 |
\& $_ = \*(Aqbar\*(Aq; |
| 3443 |
\& s/\ew??/<$&>/g; |
| 3444 |
.Ve |
| 3445 |
.PP |
| 3446 |
results in \f(CW\*(C`<><b><><a><><r><>\*(C'\fR. At each position of the string the best |
| 3447 |
match given by non-greedy \f(CW\*(C`??\*(C'\fR is the zero-length match, and the \fIsecond |
| 3448 |
best\fR match is what is matched by \f(CW\*(C`\ew\*(C'\fR. Thus zero-length matches |
| 3449 |
alternate with one-character-long matches. |
| 3450 |
.PP |
| 3451 |
Similarly, for repeated \f(CW\*(C`m/()/g\*(C'\fR the second-best match is the match at the |
| 3452 |
position one notch further in the string. |
| 3453 |
.PP |
| 3454 |
The additional state of being \fImatched with zero-length\fR is associated with |
| 3455 |
the matched string, and is reset by each assignment to \f(CWpos()\fR. |
| 3456 |
Zero-length matches at the end of the previous match are ignored |
| 3457 |
during \f(CW\*(C`split\*(C'\fR. |
| 3458 |
.SS "Combining RE Pieces" |
| 3459 |
.IX Subsection "Combining RE Pieces" |
| 3460 |
Each of the elementary pieces of regular expressions which were described |
| 3461 |
before (such as \f(CW\*(C`ab\*(C'\fR or \f(CW\*(C`\eZ\*(C'\fR) could match at most one substring |
| 3462 |
at the given position of the input string. However, in a typical regular |
| 3463 |
expression these elementary pieces are combined into more complicated |
| 3464 |
patterns using combining operators \f(CW\*(C`ST\*(C'\fR, \f(CW\*(C`S|T\*(C'\fR, \f(CW\*(C`S*\*(C'\fR \fIetc\fR. |
| 3465 |
(in these examples \f(CW"S"\fR and \f(CW"T"\fR are regular subexpressions). |
| 3466 |
.PP |
| 3467 |
Such combinations can include alternatives, leading to a problem of choice: |
| 3468 |
if we match a regular expression \f(CW\*(C`a|ab\*(C'\fR against \f(CW"abc"\fR, will it match |
| 3469 |
substring \f(CW"a"\fR or \f(CW"ab"\fR? One way to describe which substring is |
| 3470 |
actually matched is the concept of backtracking (see "Backtracking"). |
| 3471 |
However, this description is too low-level and makes you think |
| 3472 |
in terms of a particular implementation. |
| 3473 |
.PP |
| 3474 |
Another description starts with notions of "better"/"worse". All the |
| 3475 |
substrings which may be matched by the given regular expression can be |
| 3476 |
sorted from the "best" match to the "worst" match, and it is the "best" |
| 3477 |
match which is chosen. This substitutes the question of "what is chosen?" |
| 3478 |
by the question of "which matches are better, and which are worse?". |
| 3479 |
.PP |
| 3480 |
Again, for elementary pieces there is no such question, since at most |
| 3481 |
one match at a given position is possible. This section describes the |
| 3482 |
notion of better/worse for combining operators. In the description |
| 3483 |
below \f(CW"S"\fR and \f(CW"T"\fR are regular subexpressions. |
| 3484 |
.ie n .IP """ST""" 4 |
| 3485 |
.el .IP \f(CWST\fR 4 |
| 3486 |
.IX Item "ST" |
| 3487 |
Consider two possible matches, \f(CW\*(C`AB\*(C'\fR and \f(CW\*(C`A\*(AqB\*(Aq\*(C'\fR, \f(CW"A"\fR and \f(CW\*(C`A\*(Aq\*(C'\fR are |
| 3488 |
substrings which can be matched by \f(CW"S"\fR, \f(CW"B"\fR and \f(CW\*(C`B\*(Aq\*(C'\fR are substrings |
| 3489 |
which can be matched by \f(CW"T"\fR. |
| 3490 |
.Sp |
| 3491 |
If \f(CW"A"\fR is a better match for \f(CW"S"\fR than \f(CW\*(C`A\*(Aq\*(C'\fR, \f(CW\*(C`AB\*(C'\fR is a better |
| 3492 |
match than \f(CW\*(C`A\*(AqB\*(Aq\*(C'\fR. |
| 3493 |
.Sp |
| 3494 |
If \f(CW"A"\fR and \f(CW\*(C`A\*(Aq\*(C'\fR coincide: \f(CW\*(C`AB\*(C'\fR is a better match than \f(CW\*(C`AB\*(Aq\*(C'\fR if |
| 3495 |
\&\f(CW"B"\fR is a better match for \f(CW"T"\fR than \f(CW\*(C`B\*(Aq\*(C'\fR. |
| 3496 |
.ie n .IP """S|T""" 4 |
| 3497 |
.el .IP \f(CWS|T\fR 4 |
| 3498 |
.IX Item "S|T" |
| 3499 |
When \f(CW"S"\fR can match, it is a better match than when only \f(CW"T"\fR can match. |
| 3500 |
.Sp |
| 3501 |
Ordering of two matches for \f(CW"S"\fR is the same as for \f(CW"S"\fR. Similar for |
| 3502 |
two matches for \f(CW"T"\fR. |
| 3503 |
.ie n .IP """S{REPEAT_COUNT}""" 4 |
| 3504 |
.el .IP \f(CWS{REPEAT_COUNT}\fR 4 |
| 3505 |
.IX Item "S{REPEAT_COUNT}" |
| 3506 |
Matches as \f(CW\*(C`SSS...S\*(C'\fR (repeated as many times as necessary). |
| 3507 |
.ie n .IP """S{min,max}""" 4 |
| 3508 |
.el .IP \f(CWS{min,max}\fR 4 |
| 3509 |
.IX Item "S{min,max}" |
| 3510 |
Matches as \f(CW\*(C`S{max}|S{max\-1}|...|S{min+1}|S{min}\*(C'\fR. |
| 3511 |
.ie n .IP """S{min,max}?""" 4 |
| 3512 |
.el .IP \f(CWS{min,max}?\fR 4 |
| 3513 |
.IX Item "S{min,max}?" |
| 3514 |
Matches as \f(CW\*(C`S{min}|S{min+1}|...|S{max\-1}|S{max}\*(C'\fR. |
| 3515 |
.ie n .IP """S?"", ""S*"", ""S+""" 4 |
| 3516 |
.el .IP "\f(CWS?\fR, \f(CWS*\fR, \f(CWS+\fR" 4 |
| 3517 |
.IX Item "S?, S*, S+" |
| 3518 |
Same as \f(CW\*(C`S{0,1}\*(C'\fR, \f(CW\*(C`S{0,BIG_NUMBER}\*(C'\fR, \f(CW\*(C`S{1,BIG_NUMBER}\*(C'\fR respectively. |
| 3519 |
.ie n .IP """S??"", ""S*?"", ""S+?""" 4 |
| 3520 |
.el .IP "\f(CWS??\fR, \f(CWS*?\fR, \f(CWS+?\fR" 4 |
| 3521 |
.IX Item "S??, S*?, S+?" |
| 3522 |
Same as \f(CW\*(C`S{0,1}?\*(C'\fR, \f(CW\*(C`S{0,BIG_NUMBER}?\*(C'\fR, \f(CW\*(C`S{1,BIG_NUMBER}?\*(C'\fR respectively. |
| 3523 |
.ie n .IP """(?>S)""" 4 |
| 3524 |
.el .IP \f(CW(?>S)\fR 4 |
| 3525 |
.IX Item "(?>S)" |
| 3526 |
Matches the best match for \f(CW"S"\fR and only that. |
| 3527 |
.ie n .IP """(?=S)"", ""(?<=S)""" 4 |
| 3528 |
.el .IP "\f(CW(?=S)\fR, \f(CW(?<=S)\fR" 4 |
| 3529 |
.IX Item "(?=S), (?<=S)" |
| 3530 |
Only the best match for \f(CW"S"\fR is considered. (This is important only if |
| 3531 |
\&\f(CW"S"\fR has capturing parentheses, and backreferences are used somewhere |
| 3532 |
else in the whole regular expression.) |
| 3533 |
.ie n .IP """(?!S)"", ""(?<!S)""" 4 |
| 3534 |
.el .IP "\f(CW(?!S)\fR, \f(CW(?<!S)\fR" 4 |
| 3535 |
.IX Item "(?!S), (?<!S)" |
| 3536 |
For this grouping operator there is no need to describe the ordering, since |
| 3537 |
only whether or not \f(CW"S"\fR can match is important. |
| 3538 |
.ie n .IP """(??{ \fIEXPR\fR })"", ""(?\fIPARNO\fR)""" 4 |
| 3539 |
.el .IP "\f(CW(??{ \fR\f(CIEXPR\fR\f(CW })\fR, \f(CW(?\fR\f(CIPARNO\fR\f(CW)\fR" 4 |
| 3540 |
.IX Item "(??{ EXPR }), (?PARNO)" |
| 3541 |
The ordering is the same as for the regular expression which is |
| 3542 |
the result of \fIEXPR\fR, or the pattern contained by capture group \fIPARNO\fR. |
| 3543 |
.ie n .IP """(?(\fIcondition\fR)\fIyes\-pattern\fR|\fIno\-pattern\fR)""" 4 |
| 3544 |
.el .IP \f(CW(?(\fR\f(CIcondition\fR\f(CW)\fR\f(CIyes\-pattern\fR\f(CW|\fR\f(CIno\-pattern\fR\f(CW)\fR 4 |
| 3545 |
.IX Item "(?(condition)yes-pattern|no-pattern)" |
| 3546 |
Recall that which of \fIyes-pattern\fR or \fIno-pattern\fR actually matches is |
| 3547 |
already determined. The ordering of the matches is the same as for the |
| 3548 |
chosen subexpression. |
| 3549 |
.PP |
| 3550 |
The above recipes describe the ordering of matches \fIat a given position\fR. |
| 3551 |
One more rule is needed to understand how a match is determined for the |
| 3552 |
whole regular expression: a match at an earlier position is always better |
| 3553 |
than a match at a later position. |
| 3554 |
.SS "Creating Custom RE Engines" |
| 3555 |
.IX Subsection "Creating Custom RE Engines" |
| 3556 |
As of Perl 5.10.0, one can create custom regular expression engines. This |
| 3557 |
is not for the faint of heart, as they have to plug in at the C level. See |
| 3558 |
perlreapi for more details. |
| 3559 |
.PP |
| 3560 |
As an alternative, overloaded constants (see overload) provide a simple |
| 3561 |
way to extend the functionality of the RE engine, by substituting one |
| 3562 |
pattern for another. |
| 3563 |
.PP |
| 3564 |
Suppose that we want to enable a new RE escape-sequence \f(CW\*(C`\eY|\*(C'\fR which |
| 3565 |
matches at a boundary between whitespace characters and non-whitespace |
| 3566 |
characters. Note that \f(CW\*(C`(?=\eS)(?<!\eS)|(?!\eS)(?<=\eS)\*(C'\fR matches exactly |
| 3567 |
at these positions, so we want to have each \f(CW\*(C`\eY|\*(C'\fR in the place of the |
| 3568 |
more complicated version. We can create a module \f(CW\*(C`customre\*(C'\fR to do |
| 3569 |
this: |
| 3570 |
.PP |
| 3571 |
.Vb 2 |
| 3572 |
\& package customre; |
| 3573 |
\& use overload; |
| 3574 |
\& |
| 3575 |
\& sub import { |
| 3576 |
\& shift; |
| 3577 |
\& die "No argument to customre::import allowed" if @_; |
| 3578 |
\& overload::constant \*(Aqqr\*(Aq => \e&convert; |
| 3579 |
\& } |
| 3580 |
\& |
| 3581 |
\& sub invalid { die "/$_[0]/: invalid escape \*(Aq\e\e$_[1]\*(Aq"} |
| 3582 |
\& |
| 3583 |
\& # We must also take care of not escaping the legitimate \e\eY| |
| 3584 |
\& # sequence, hence the presence of \*(Aq\e\e\*(Aq in the conversion rules. |
| 3585 |
\& my %rules = ( \*(Aq\e\e\*(Aq => \*(Aq\e\e\e\e\*(Aq, |
| 3586 |
\& \*(AqY|\*(Aq => qr/(?=\eS)(?<!\eS)|(?!\eS)(?<=\eS)/ ); |
| 3587 |
\& sub convert { |
| 3588 |
\& my $re = shift; |
| 3589 |
\& $re =~ s{ |
| 3590 |
\& \e\e ( \e\e | Y . ) |
| 3591 |
\& } |
| 3592 |
\& { $rules{$1} or invalid($re,$1) }sgex; |
| 3593 |
\& return $re; |
| 3594 |
\& } |
| 3595 |
.Ve |
| 3596 |
.PP |
| 3597 |
Now \f(CW\*(C`use customre\*(C'\fR enables the new escape in constant regular |
| 3598 |
expressions, \fIi.e.\fR, those without any runtime variable interpolations. |
| 3599 |
As documented in overload, this conversion will work only over |
| 3600 |
literal parts of regular expressions. For \f(CW\*(C`\eY|$re\eY|\*(C'\fR the variable |
| 3601 |
part of this regular expression needs to be converted explicitly |
| 3602 |
(but only if the special meaning of \f(CW\*(C`\eY|\*(C'\fR should be enabled inside \f(CW$re\fR): |
| 3603 |
.PP |
| 3604 |
.Vb 5 |
| 3605 |
\& use customre; |
| 3606 |
\& $re = <>; |
| 3607 |
\& chomp $re; |
| 3608 |
\& $re = customre::convert $re; |
| 3609 |
\& /\eY|$re\eY|/; |
| 3610 |
.Ve |
| 3611 |
.SS "Embedded Code Execution Frequency" |
| 3612 |
.IX Subsection "Embedded Code Execution Frequency" |
| 3613 |
The exact rules for how often \f(CW\*(C`(?{})\*(C'\fR and \f(CW\*(C`(??{})\*(C'\fR are executed in a pattern |
| 3614 |
are unspecified, and this is even more true of \f(CW\*(C`(*{})\*(C'\fR. |
| 3615 |
In the case of a successful match you can assume that they DWIM and |
| 3616 |
will be executed in left to right order the appropriate number of times in the |
| 3617 |
accepting path of the pattern as would any other meta-pattern. How non\- |
| 3618 |
accepting pathways and match failures affect the number of times a pattern is |
| 3619 |
executed is specifically unspecified and may vary depending on what |
| 3620 |
optimizations can be applied to the pattern and is likely to change from |
| 3621 |
version to version. |
| 3622 |
.PP |
| 3623 |
For instance in |
| 3624 |
.PP |
| 3625 |
.Vb 1 |
| 3626 |
\& "aaabcdeeeee"=~/a(?{print "a"})b(?{print "b"})cde/; |
| 3627 |
.Ve |
| 3628 |
.PP |
| 3629 |
the exact number of times "a" or "b" are printed out is unspecified for |
| 3630 |
failure, but you may assume they will be printed at least once during |
| 3631 |
a successful match, additionally you may assume that if "b" is printed, |
| 3632 |
it will be preceded by at least one "a". |
| 3633 |
.PP |
| 3634 |
In the case of branching constructs like the following: |
| 3635 |
.PP |
| 3636 |
.Vb 1 |
| 3637 |
\& /a(b|(?{ print "a" }))c(?{ print "c" })/; |
| 3638 |
.Ve |
| 3639 |
.PP |
| 3640 |
you can assume that the input "ac" will output "ac", and that "abc" |
| 3641 |
will output only "c". |
| 3642 |
.PP |
| 3643 |
When embedded code is quantified, successful matches will call the |
| 3644 |
code once for each matched iteration of the quantifier. For |
| 3645 |
example: |
| 3646 |
.PP |
| 3647 |
.Vb 1 |
| 3648 |
\& "good" =~ /g(?:o(?{print "o"}))*d/; |
| 3649 |
.Ve |
| 3650 |
.PP |
| 3651 |
will output "o" twice. |
| 3652 |
.PP |
| 3653 |
For historical and consistency reasons the use of normal code blocks |
| 3654 |
anywhere in a pattern will disable certain optimisations. As of 5.37.7 |
| 3655 |
you can use an "optimistic" codeblock, \f(CW\*(C`(*{ ... })\*(C'\fR as a replacement |
| 3656 |
for \f(CW\*(C`(?{ ... })\*(C'\fR, if you do *not* wish to disable these optimisations. |
| 3657 |
This may result in the code block being called less often than it might |
| 3658 |
have been had they not been optimistic. |
| 3659 |
.SS "PCRE/Python Support" |
| 3660 |
.IX Subsection "PCRE/Python Support" |
| 3661 |
As of Perl 5.10.0, Perl supports several Python/PCRE\-specific extensions |
| 3662 |
to the regex syntax. While Perl programmers are encouraged to use the |
| 3663 |
Perl-specific syntax, the following are also accepted: |
| 3664 |
.ie n .IP """(?P<\fINAME\fR>\fIpattern\fR)""" 4 |
| 3665 |
.el .IP \f(CW(?P<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\fR 4 |
| 3666 |
.IX Item "(?P<NAME>pattern)" |
| 3667 |
Define a named capture group. Equivalent to \f(CW\*(C`(?<\fR\f(CINAME\fR\f(CW>\fR\f(CIpattern\fR\f(CW)\*(C'\fR. |
| 3668 |
.ie n .IP """(?P=\fINAME\fR)""" 4 |
| 3669 |
.el .IP \f(CW(?P=\fR\f(CINAME\fR\f(CW)\fR 4 |
| 3670 |
.IX Item "(?P=NAME)" |
| 3671 |
Backreference to a named capture group. Equivalent to \f(CW\*(C`\eg{\fR\f(CINAME\fR\f(CW}\*(C'\fR. |
| 3672 |
.ie n .IP """(?P>\fINAME\fR)""" 4 |
| 3673 |
.el .IP \f(CW(?P>\fR\f(CINAME\fR\f(CW)\fR 4 |
| 3674 |
.IX Item "(?P>NAME)" |
| 3675 |
Subroutine call to a named capture group. Equivalent to \f(CW\*(C`(?&\fR\f(CINAME\fR\f(CW)\*(C'\fR. |
| 3676 |
.SH BUGS |
| 3677 |
.IX Header "BUGS" |
| 3678 |
There are a number of issues with regard to case-insensitive matching |
| 3679 |
in Unicode rules. See \f(CW"i"\fR under "Modifiers" above. |
| 3680 |
.PP |
| 3681 |
This document varies from difficult to understand to completely |
| 3682 |
and utterly opaque. The wandering prose riddled with jargon is |
| 3683 |
hard to fathom in several places. |
| 3684 |
.PP |
| 3685 |
This document needs a rewrite that separates the tutorial content |
| 3686 |
from the reference content. |
| 3687 |
.SH "SEE ALSO" |
| 3688 |
.IX Header "SEE ALSO" |
| 3689 |
The syntax of patterns used in Perl pattern matching evolved from those |
| 3690 |
supplied in the Bell Labs Research Unix 8th Edition (Version 8) regex |
| 3691 |
routines. (The code is actually derived (distantly) from Henry |
| 3692 |
Spencer's freely redistributable reimplementation of those V8 routines.) |
| 3693 |
.PP |
| 3694 |
perlrequick. |
| 3695 |
.PP |
| 3696 |
perlretut. |
| 3697 |
.PP |
| 3698 |
"Regexp Quote-Like Operators" in perlop. |
| 3699 |
.PP |
| 3700 |
"Gory details of parsing quoted constructs" in perlop. |
| 3701 |
.PP |
| 3702 |
perlfaq6. |
| 3703 |
.PP |
| 3704 |
"pos" in perlfunc. |
| 3705 |
.PP |
| 3706 |
perllocale. |
| 3707 |
.PP |
| 3708 |
perlebcdic. |
| 3709 |
.PP |
| 3710 |
\&\fIMastering Regular Expressions\fR by Jeffrey Friedl, published |
| 3711 |
by O'Reilly and Associates. |