1=head1 NAME 2 3perlreref - Perl Regular Expressions Reference 4 5=head1 DESCRIPTION 6 7This is a quick reference to Perl's regular expressions. 8For full information see L<perlre> and L<perlop>, as well 9as the L</"SEE ALSO"> section in this document. 10 11=head2 OPERATORS 12 13C<=~> determines to which variable the regex is applied. 14In its absence, $_ is used. 15 16 $var =~ /foo/; 17 18C<!~> determines to which variable the regex is applied, 19and negates the result of the match; it returns 20false if the match succeeds, and true if it fails. 21 22 $var !~ /foo/; 23 24C<m/pattern/msixpogcdualn> searches a string for a pattern match, 25applying the given options. 26 27 m Multiline mode - ^ and $ match internal lines 28 s match as a Single line - . matches \n 29 i case-Insensitive 30 x eXtended legibility - free whitespace and comments 31 p Preserve a copy of the matched string - 32 ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined. 33 o compile pattern Once 34 g Global - all occurrences 35 c don't reset pos on failed matches when using /g 36 a restrict \d, \s, \w and [:posix:] to match ASCII only 37 aa (two a's) also /i matches exclude ASCII/non-ASCII 38 l match according to current locale 39 u match according to Unicode rules 40 d match according to native rules unless something indicates 41 Unicode 42 n Non-capture mode. Don't let () fill in $1, $2, etc... 43 44If 'pattern' is an empty string, the last I<successfully> matched 45regex is used. Delimiters other than '/' may be used for both this 46operator and the following ones. The leading C<m> can be omitted 47if the delimiter is '/'. 48 49C<qr/pattern/msixpodualn> lets you store a regex in a variable, 50or pass one around. Modifiers as for C<m//>, and are stored 51within the regex. 52 53C<s/pattern/replacement/msixpogcedual> substitutes matches of 54'pattern' with 'replacement'. Modifiers as for C<m//>, 55with two additions: 56 57 e Evaluate 'replacement' as an expression 58 r Return substitution and leave the original string untouched. 59 60'e' may be specified multiple times. 'replacement' is interpreted 61as a double quoted string unless a single-quote (C<'>) is the delimiter. 62 63C<m?pattern?> is like C<m/pattern/> but matches only once. No alternate 64delimiters can be used. Must be reset with reset(). 65 66=head2 SYNTAX 67 68 \ Escapes the character immediately following it 69 . Matches any single character except a newline (unless /s is 70 used) 71 ^ Matches at the beginning of the string (or line, if /m is used) 72 $ Matches at the end of the string (or line, if /m is used) 73 * Matches the preceding element 0 or more times 74 + Matches the preceding element 1 or more times 75 ? Matches the preceding element 0 or 1 times 76 {...} Specifies a range of occurrences for the element preceding it 77 [...] Matches any one of the characters contained within the brackets 78 (...) Groups subexpressions for capturing to $1, $2... 79 (?:...) Groups subexpressions without capturing (cluster) 80 | Matches either the subexpression preceding or following it 81 \g1 or \g{1}, \g2 ... Matches the text from the Nth group 82 \1, \2, \3 ... Matches the text from the Nth group 83 \g-1 or \g{-1}, \g-2 ... Matches the text from the Nth previous group 84 \g{name} Named backreference 85 \k<name> Named backreference 86 \k'name' Named backreference 87 (?P=name) Named backreference (python syntax) 88 89=head2 ESCAPE SEQUENCES 90 91These work as in normal strings. 92 93 \a Alarm (beep) 94 \e Escape 95 \f Formfeed 96 \n Newline 97 \r Carriage return 98 \t Tab 99 \037 Char whose ordinal is the 3 octal digits, max \777 100 \o{2307} Char whose ordinal is the octal number, unrestricted 101 \x7f Char whose ordinal is the 2 hex digits, max \xFF 102 \x{263a} Char whose ordinal is the hex number, unrestricted 103 \cx Control-x 104 \N{name} A named Unicode character or character sequence 105 \N{U+263D} A Unicode character by hex ordinal 106 107 \l Lowercase next character 108 \u Titlecase next character 109 \L Lowercase until \E 110 \U Uppercase until \E 111 \F Foldcase until \E 112 \Q Disable pattern metacharacters until \E 113 \E End modification 114 115For Titlecase, see L</Titlecase>. 116 117This one works differently from normal strings: 118 119 \b An assertion, not backspace, except in a character class 120 121=head2 CHARACTER CLASSES 122 123 [amy] Match 'a', 'm' or 'y' 124 [f-j] Dash specifies "range" 125 [f-j-] Dash escaped or at start or end means 'dash' 126 [^f-j] Caret indicates "match any character _except_ these" 127 128The following sequences (except C<\N>) work within or without a character class. 129The first six are locale aware, all are Unicode aware. See L<perllocale> 130and L<perlunicode> for details. 131 132 \d A digit 133 \D A nondigit 134 \w A word character 135 \W A non-word character 136 \s A whitespace character 137 \S A non-whitespace character 138 \h A horizontal whitespace 139 \H A non horizontal whitespace 140 \N A non newline (when not followed by '{NAME}';; 141 not valid in a character class; equivalent to [^\n]; it's 142 like '.' without /s modifier) 143 \v A vertical whitespace 144 \V A non vertical whitespace 145 \R A generic newline (?>\v|\x0D\x0A) 146 147 \pP Match P-named (Unicode) property 148 \p{...} Match Unicode property with name longer than 1 character 149 \PP Match non-P 150 \P{...} Match lack of Unicode property with name longer than 1 char 151 \X Match Unicode extended grapheme cluster 152 153POSIX character classes and their Unicode and Perl equivalents: 154 155 ASCII- Full- 156 POSIX range range backslash 157 [[:...:]] \p{...} \p{...} sequence Description 158 159 ----------------------------------------------------------------------- 160 alnum PosixAlnum XPosixAlnum 'alpha' plus 'digit' 161 alpha PosixAlpha XPosixAlpha Alphabetic characters 162 ascii ASCII Any ASCII character 163 blank PosixBlank XPosixBlank \h Horizontal whitespace; 164 full-range also 165 written as 166 \p{HorizSpace} (GNU 167 extension) 168 cntrl PosixCntrl XPosixCntrl Control characters 169 digit PosixDigit XPosixDigit \d Decimal digits 170 graph PosixGraph XPosixGraph 'alnum' plus 'punct' 171 lower PosixLower XPosixLower Lowercase characters 172 print PosixPrint XPosixPrint 'graph' plus 'space', 173 but not any Controls 174 punct PosixPunct XPosixPunct Punctuation and Symbols 175 in ASCII-range; just 176 punct outside it 177 space PosixSpace XPosixSpace \s Whitespace 178 upper PosixUpper XPosixUpper Uppercase characters 179 word PosixWord XPosixWord \w 'alnum' + Unicode marks 180 + connectors, like 181 '_' (Perl extension) 182 xdigit ASCII_Hex_Digit XPosixDigit Hexadecimal digit, 183 ASCII-range is 184 [0-9A-Fa-f] 185 186Also, various synonyms like C<\p{Alpha}> for C<\p{XPosixAlpha}>; all listed 187in L<perluniprops/Properties accessible through \p{} and \P{}> 188 189Within a character class: 190 191 POSIX traditional Unicode 192 [:digit:] \d \p{Digit} 193 [:^digit:] \D \P{Digit} 194 195=head2 ANCHORS 196 197All are zero-width assertions. 198 199 ^ Match string start (or line, if /m is used) 200 $ Match string end (or line, if /m is used) or before newline 201 \b{} Match boundary of type specified within the braces 202 \B{} Match wherever \b{} doesn't match 203 \b Match word boundary (between \w and \W) 204 \B Match except at word boundary (between \w and \w or \W and \W) 205 \A Match string start (regardless of /m) 206 \Z Match string end (before optional newline) 207 \z Match absolute string end 208 \G Match where previous m//g left off 209 \K Keep the stuff left of the \K, don't include it in $& 210 211=head2 QUANTIFIERS 212 213Quantifiers are greedy by default and match the B<longest> leftmost. 214 215 Maximal Minimal Possessive Allowed range 216 ------- ------- ---------- ------------- 217 {n,m} {n,m}? {n,m}+ Must occur at least n times 218 but no more than m times 219 {n,} {n,}? {n,}+ Must occur at least n times 220 {n} {n}? {n}+ Must occur exactly n times 221 * *? *+ 0 or more times (same as {0,}) 222 + +? ++ 1 or more times (same as {1,}) 223 ? ?? ?+ 0 or 1 time (same as {0,1}) 224 225The possessive forms (new in Perl 5.10) prevent backtracking: what gets 226matched by a pattern with a possessive quantifier will not be backtracked 227into, even if that causes the whole match to fail. 228 229There is no quantifier C<{,n}>. That's currently illegal. 230 231=head2 EXTENDED CONSTRUCTS 232 233 (?#text) A comment 234 (?:...) Groups subexpressions without capturing (cluster) 235 (?pimsx-imsx:...) Enable/disable option (as per m// modifiers) 236 (?=...) Zero-width positive lookahead assertion 237 (*pla:...) Same, starting in 5.32; experimentally in 5.28 238 (*positive_lookahead:...) Same, same versions as *pla 239 (?!...) Zero-width negative lookahead assertion 240 (*nla:...) Same, starting in 5.32; experimentally in 5.28 241 (*negative_lookahead:...) Same, same versions as *nla 242 (?<=...) Zero-width positive lookbehind assertion 243 (*plb:...) Same, starting in 5.32; experimentally in 5.28 244 (*positive_lookbehind:...) Same, same versions as *plb 245 (?<!...) Zero-width negative lookbehind assertion 246 (*nlb:...) Same, starting in 5.32; experimentally in 5.28 247 (*negative_lookbehind:...) Same, same versions as *plb 248 (?>...) Grab what we can, prohibit backtracking 249 (*atomic:...) Same, starting in 5.32; experimentally in 5.28 250 (?|...) Branch reset 251 (?<name>...) Named capture 252 (?'name'...) Named capture 253 (?P<name>...) Named capture (python syntax) 254 (?[...]) Extended bracketed character class 255 (?{ code }) Embedded code, return value becomes $^R 256 (??{ code }) Dynamic regex, return value used as regex 257 (?N) Recurse into subpattern number N 258 (?-N), (?+N) Recurse into Nth previous/next subpattern 259 (?R), (?0) Recurse at the beginning of the whole pattern 260 (?&name) Recurse into a named subpattern 261 (?P>name) Recurse into a named subpattern (python syntax) 262 (?(cond)yes|no) 263 (?(cond)yes) Conditional expression, where "(cond)" can be: 264 (?=pat) lookahead; also (*pla:pat) 265 (*positive_lookahead:pat) 266 (?!pat) negative lookahead; also (*nla:pat) 267 (*negative_lookahead:pat) 268 (?<=pat) lookbehind; also (*plb:pat) 269 (*lookbehind:pat) 270 (?<!pat) negative lookbehind; also (*nlb:pat) 271 (*negative_lookbehind:pat) 272 (N) subpattern N has matched something 273 (<name>) named subpattern has matched something 274 ('name') named subpattern has matched something 275 (?{code}) code condition 276 (R) true if recursing 277 (RN) true if recursing into Nth subpattern 278 (R&name) true if recursing into named subpattern 279 (DEFINE) always false, no no-pattern allowed 280 281=head2 VARIABLES 282 283 $_ Default variable for operators to use 284 285 $` Everything prior to matched string 286 $& Entire matched string 287 $' Everything after to matched string 288 289 ${^PREMATCH} Everything prior to matched string 290 ${^MATCH} Entire matched string 291 ${^POSTMATCH} Everything after to matched string 292 293Note to those still using Perl 5.18 or earlier: 294The use of C<$`>, C<$&> or C<$'> will slow down B<all> regex use 295within your program. Consult L<perlvar> for C<@-> 296to see equivalent expressions that won't cause slow down. 297See also L<Devel::SawAmpersand>. Starting with Perl 5.10, you 298can also use the equivalent variables C<${^PREMATCH}>, C<${^MATCH}> 299and C<${^POSTMATCH}>, but for them to be defined, you have to 300specify the C</p> (preserve) modifier on your regular expression. 301In Perl 5.20, the use of C<$`>, C<$&> and C<$'> makes no speed difference. 302 303 $1, $2 ... hold the Xth captured expr 304 $+ Last parenthesized pattern match 305 $^N Holds the most recently closed capture 306 $^R Holds the result of the last (?{...}) expr 307 @- Offsets of starts of groups. $-[0] holds start of whole match 308 @+ Offsets of ends of groups. $+[0] holds end of whole match 309 %+ Named capture groups 310 %- Named capture groups, as array refs 311 312Captured groups are numbered according to their I<opening> paren. 313 314=head2 FUNCTIONS 315 316 lc Lowercase a string 317 lcfirst Lowercase first char of a string 318 uc Uppercase a string 319 ucfirst Titlecase first char of a string 320 fc Foldcase a string 321 322 pos Return or set current match position 323 quotemeta Quote metacharacters 324 reset Reset m?pattern? status 325 study Analyze string for optimizing matching 326 327 split Use a regex to split a string into parts 328 329The first five of these are like the escape sequences C<\L>, C<\l>, 330C<\U>, C<\u>, and C<\F>. For Titlecase, see L</Titlecase>; For 331Foldcase, see L</Foldcase>. 332 333=head2 TERMINOLOGY 334 335=head3 Titlecase 336 337Unicode concept which most often is equal to uppercase, but for 338certain characters like the German "sharp s" there is a difference. 339 340=head3 Foldcase 341 342Unicode form that is useful when comparing strings regardless of case, 343as certain characters have complex one-to-many case mappings. Primarily a 344variant of lowercase. 345 346=head1 AUTHOR 347 348Iain Truskett. Updated by the Perl 5 Porters. 349 350This document may be distributed under the same terms as Perl itself. 351 352=head1 SEE ALSO 353 354=over 4 355 356=item * 357 358L<perlretut> for a tutorial on regular expressions. 359 360=item * 361 362L<perlrequick> for a rapid tutorial. 363 364=item * 365 366L<perlre> for more details. 367 368=item * 369 370L<perlvar> for details on the variables. 371 372=item * 373 374L<perlop> for details on the operators. 375 376=item * 377 378L<perlfunc> for details on the functions. 379 380=item * 381 382L<perlfaq6> for FAQs on regular expressions. 383 384=item * 385 386L<perlrebackslash> for a reference on backslash sequences. 387 388=item * 389 390L<perlrecharclass> for a reference on character classes. 391 392=item * 393 394The L<re> module to alter behaviour and aid 395debugging. 396 397=item * 398 399L<perldebug/"Debugging Regular Expressions"> 400 401=item * 402 403L<perluniintro>, L<perlunicode>, L<charnames> and L<perllocale> 404for details on regexes and internationalisation. 405 406=item * 407 408I<Mastering Regular Expressions> by Jeffrey Friedl 409(L<http://oreilly.com/catalog/9780596528126/>) for a thorough grounding and 410reference on the topic. 411 412=back 413 414=head1 THANKS 415 416David P.C. Wollmann, 417Richard Soderberg, 418Sean M. Burke, 419Tom Christiansen, 420Jim Cromie, 421and 422Jeffrey Goff 423for useful advice. 424 425=cut 426