This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
typo fix for reref pod
[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
278The use of C<$`>, C<$&> or C<$'> will slow down B<all> regex use
e1fd4132
DM
279within your program. Consult L<perlvar> for C<@->
280to see equivalent expressions that won't cause slow down.
281See also L<Devel::SawAmpersand>. Starting with Perl 5.10, you
e17472c5
RGS
282can also use the equivalent variables C<${^PREMATCH}>, C<${^MATCH}>
283and C<${^POSTMATCH}>, but for them to be defined, you have to
284specify the C</p> (preserve) modifier on your regular expression.
30487ceb
RGS
285
286 $1, $2 ... hold the Xth captured expr
287 $+ Last parenthesized pattern match
288 $^N Holds the most recently closed capture
289 $^R Holds the result of the last (?{...}) expr
6d014f17
JH
290 @- Offsets of starts of groups. $-[0] holds start of whole match
291 @+ Offsets of ends of groups. $+[0] holds end of whole match
c27a5cfe
KW
292 %+ Named capture groups
293 %- Named capture groups, as array refs
30487ceb 294
6d014f17 295Captured groups are numbered according to their I<opening> paren.
30487ceb 296
a5365663 297=head2 FUNCTIONS
30487ceb
RGS
298
299 lc Lowercase a string
300 lcfirst Lowercase first char of a string
301 uc Uppercase a string
47e8a552 302 ucfirst Titlecase first char of a string
628253b8 303 fc Foldcase a string
47e8a552 304
30487ceb
RGS
305 pos Return or set current match position
306 quotemeta Quote metacharacters
307 reset Reset ?pattern? status
308 study Analyze string for optimizing matching
309
e17472c5 310 split Use a regex to split a string into parts
30487ceb 311
628253b8
BF
312The first five of these are like the escape sequences C<\L>, C<\l>,
313C<\U>, C<\u>, and C<\F>. For Titlecase, see L</Titlecase>; For
314Foldcase, see L</Foldcase>.
47e8a552 315
1501d360 316=head2 TERMINOLOGY
47e8a552 317
a5365663 318=head3 Titlecase
47e8a552
IT
319
320Unicode concept which most often is equal to uppercase, but for
321certain characters like the German "sharp s" there is a difference.
322
628253b8
BF
323=head3 Foldcase
324
325Unicode form that is useful when comparing strings regardless of case,
211f3bbf 326as certain characters have complex one-to-many case mappings. Primarily a
628253b8
BF
327variant of lowercase.
328
40506b5d 329=head1 AUTHOR
30487ceb 330
64c5a566 331Iain Truskett. Updated by the Perl 5 Porters.
30487ceb
RGS
332
333This document may be distributed under the same terms as Perl itself.
334
40506b5d 335=head1 SEE ALSO
30487ceb
RGS
336
337=over 4
338
339=item *
340
341L<perlretut> for a tutorial on regular expressions.
342
343=item *
344
345L<perlrequick> for a rapid tutorial.
346
347=item *
348
349L<perlre> for more details.
350
351=item *
352
353L<perlvar> for details on the variables.
354
355=item *
356
357L<perlop> for details on the operators.
358
359=item *
360
361L<perlfunc> for details on the functions.
362
363=item *
364
365L<perlfaq6> for FAQs on regular expressions.
366
367=item *
368
64c5a566
RGS
369L<perlrebackslash> for a reference on backslash sequences.
370
371=item *
372
373L<perlrecharclass> for a reference on character classes.
374
375=item *
376
30487ceb
RGS
377The L<re> module to alter behaviour and aid
378debugging.
379
380=item *
381
57e8c15d 382L<perldebug/"Debugging Regular Expressions">
30487ceb
RGS
383
384=item *
385
e17472c5 386L<perluniintro>, L<perlunicode>, L<charnames> and L<perllocale>
30487ceb
RGS
387for details on regexes and internationalisation.
388
389=item *
390
391I<Mastering Regular Expressions> by Jeffrey Friedl
08d7a6b2 392(F<http://oreilly.com/catalog/9780596528126/>) for a thorough grounding and
30487ceb
RGS
393reference on the topic.
394
395=back
396
40506b5d 397=head1 THANKS
30487ceb
RGS
398
399David P.C. Wollmann,
400Richard Soderberg,
401Sean M. Burke,
402Tom Christiansen,
e5a7b003 403Jim Cromie,
30487ceb
RGS
404and
405Jeffrey Goff
406for useful advice.
6d014f17
JH
407
408=cut