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 interpreted as a literal string. 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; avail experimentally starting in 5.28 238 (?!...) Zero-width negative lookahead assertion 239 (?*nla:...) Same; avail experimentally starting in 5.28 240 (?<=...) Zero-width positive lookbehind assertion 241 (?*plb:...) Same; avail experimentally starting in 5.28 242 (?<!...) Zero-width negative lookbehind assertion 243 (?*nlb:...) Same; avail experimentally starting in 5.28 244 (?>...) Grab what we can, prohibit backtracking 245 (?*atomic:...) Same; avail experimentally starting in 5.28 246 (?|...) Branch reset 247 (?<name>...) Named capture 248 (?'name'...) Named capture 249 (?P<name>...) Named capture (python syntax) 250 (?[...]) Extended bracketed character class 251 (?{ code }) Embedded code, return value becomes $^R 252 (??{ code }) Dynamic regex, return value used as regex 253 (?N) Recurse into subpattern number N 254 (?-N), (?+N) Recurse into Nth previous/next subpattern 255 (?R), (?0) Recurse at the beginning of the whole pattern 256 (?&name) Recurse into a named subpattern 257 (?P>name) Recurse into a named subpattern (python syntax) 258 (?(cond)yes|no) 259 (?(cond)yes) Conditional expression, where "(cond)" can be: 260 (?=pat) lookahead 261 (?!pat) negative lookahead 262 (?<=pat) lookbehind 263 (?<!pat) negative lookbehind 264 (N) subpattern N has matched something 265 (<name>) named subpattern has matched something 266 ('name') named subpattern has matched something 267 (?{code}) code condition 268 (R) true if recursing 269 (RN) true if recursing into Nth subpattern 270 (R&name) true if recursing into named subpattern 271 (DEFINE) always false, no no-pattern allowed 272 273=head2 VARIABLES 274 275 $_ Default variable for operators to use 276 277 $` Everything prior to matched string 278 $& Entire matched string 279 $' Everything after to matched string 280 281 ${^PREMATCH} Everything prior to matched string 282 ${^MATCH} Entire matched string 283 ${^POSTMATCH} Everything after to matched string 284 285Note to those still using Perl 5.18 or earlier: 286The use of C<$`>, C<$&> or C<$'> will slow down B<all> regex use 287within your program. Consult L<perlvar> for C<@-> 288to see equivalent expressions that won't cause slow down. 289See also L<Devel::SawAmpersand>. Starting with Perl 5.10, you 290can also use the equivalent variables C<${^PREMATCH}>, C<${^MATCH}> 291and C<${^POSTMATCH}>, but for them to be defined, you have to 292specify the C</p> (preserve) modifier on your regular expression. 293In Perl 5.20, the use of C<$`>, C<$&> and C<$'> makes no speed difference. 294 295 $1, $2 ... hold the Xth captured expr 296 $+ Last parenthesized pattern match 297 $^N Holds the most recently closed capture 298 $^R Holds the result of the last (?{...}) expr 299 @- Offsets of starts of groups. $-[0] holds start of whole match 300 @+ Offsets of ends of groups. $+[0] holds end of whole match 301 %+ Named capture groups 302 %- Named capture groups, as array refs 303 304Captured groups are numbered according to their I<opening> paren. 305 306=head2 FUNCTIONS 307 308 lc Lowercase a string 309 lcfirst Lowercase first char of a string 310 uc Uppercase a string 311 ucfirst Titlecase first char of a string 312 fc Foldcase a string 313 314 pos Return or set current match position 315 quotemeta Quote metacharacters 316 reset Reset m?pattern? status 317 study Analyze string for optimizing matching 318 319 split Use a regex to split a string into parts 320 321The first five of these are like the escape sequences C<\L>, C<\l>, 322C<\U>, C<\u>, and C<\F>. For Titlecase, see L</Titlecase>; For 323Foldcase, see L</Foldcase>. 324 325=head2 TERMINOLOGY 326 327=head3 Titlecase 328 329Unicode concept which most often is equal to uppercase, but for 330certain characters like the German "sharp s" there is a difference. 331 332=head3 Foldcase 333 334Unicode form that is useful when comparing strings regardless of case, 335as certain characters have complex one-to-many case mappings. Primarily a 336variant of lowercase. 337 338=head1 AUTHOR 339 340Iain Truskett. Updated by the Perl 5 Porters. 341 342This document may be distributed under the same terms as Perl itself. 343 344=head1 SEE ALSO 345 346=over 4 347 348=item * 349 350L<perlretut> for a tutorial on regular expressions. 351 352=item * 353 354L<perlrequick> for a rapid tutorial. 355 356=item * 357 358L<perlre> for more details. 359 360=item * 361 362L<perlvar> for details on the variables. 363 364=item * 365 366L<perlop> for details on the operators. 367 368=item * 369 370L<perlfunc> for details on the functions. 371 372=item * 373 374L<perlfaq6> for FAQs on regular expressions. 375 376=item * 377 378L<perlrebackslash> for a reference on backslash sequences. 379 380=item * 381 382L<perlrecharclass> for a reference on character classes. 383 384=item * 385 386The L<re> module to alter behaviour and aid 387debugging. 388 389=item * 390 391L<perldebug/"Debugging Regular Expressions"> 392 393=item * 394 395L<perluniintro>, L<perlunicode>, L<charnames> and L<perllocale> 396for details on regexes and internationalisation. 397 398=item * 399 400I<Mastering Regular Expressions> by Jeffrey Friedl 401(L<http://oreilly.com/catalog/9780596528126/>) for a thorough grounding and 402reference on the topic. 403 404=back 405 406=head1 THANKS 407 408David P.C. Wollmann, 409Richard Soderberg, 410Sean M. Burke, 411Tom Christiansen, 412Jim Cromie, 413and 414Jeffrey Goff 415for useful advice. 416 417=cut 418