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