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