This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl 5.002beta2 patch: toke.c
[perl5.git] / pod / perlre.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlre - Perl regular expressions
4
5=head1 DESCRIPTION
6
cb1a09d0
AD
7This page describes the syntax of regular expressions in Perl. For a
8description of how to actually I<use> regular expressions in matching
9operations, plus various examples of the same, see C<m//> and C<s///> in
10L<perlop>.
11
12The matching operations can
a0d0e21e
LW
13have various modifiers, some of which relate to the interpretation of
14the regular expression inside. These are:
15
16 i Do case-insensitive pattern matching.
17 m Treat string as multiple lines.
18 s Treat string as single line.
cb1a09d0 19 x Extend your pattern's legibilty with whitespace and comments.
a0d0e21e
LW
20
21These are usually written as "the C</x> modifier", even though the delimiter
22in question might not actually be a slash. In fact, any of these
23modifiers may also be embedded within the regular expression itself using
24the new C<(?...)> construct. See below.
25
4633a7c4
LW
26The C</x> modifier itself needs a little more explanation. It tells
27the regular expression parser to ignore whitespace that is not
28backslashed or within a character class. You can use this to break up
29your regular expression into (slightly) more readable parts. The C<#>
30character is also treated as a metacharacter introducing a comment,
31just as in ordinary Perl code. Taken together, these features go a
32long way towards making Perl 5 a readable language. See the C comment
a0d0e21e
LW
33deletion code in L<perlop>.
34
35=head2 Regular Expressions
36
37The patterns used in pattern matching are regular expressions such as
38those supplied in the Version 8 regexp routines. (In fact, the
39routines are derived (distantly) from Henry Spencer's freely
40redistributable reimplementation of the V8 routines.)
41See L<Version 8 Regular Expressions> for details.
42
43In particular the following metacharacters have their standard I<egrep>-ish
44meanings:
45
46 \ Quote the next metacharacter
47 ^ Match the beginning of the line
48 . Match any character (except newline)
49 $ Match the end of the line
50 | Alternation
51 () Grouping
52 [] Character class
53
54By default, the "^" character is guaranteed to match only at the
55beginning of the string, the "$" character only at the end (or before the
56newline at the end) and Perl does certain optimizations with the
57assumption that the string contains only one line. Embedded newlines
58will not be matched by "^" or "$". You may, however, wish to treat a
59string as a multi-line buffer, such that the "^" will match after any
60newline within the string, and "$" will match before any newline. At the
61cost of a little more overhead, you can do this by using the /m modifier
62on the pattern match operator. (Older programs did this by setting C<$*>,
63but this practice is deprecated in Perl 5.)
64
65To facilitate multi-line substitutions, the "." character never matches a
66newline unless you use the C</s> modifier, which tells Perl to pretend
67the string is a single line--even if it isn't. The C</s> modifier also
68overrides the setting of C<$*>, in case you have some (badly behaved) older
69code that sets it in another module.
70
71The following standard quantifiers are recognized:
72
73 * Match 0 or more times
74 + Match 1 or more times
75 ? Match 1 or 0 times
76 {n} Match exactly n times
77 {n,} Match at least n times
78 {n,m} Match at least n but not more than m times
79
80(If a curly bracket occurs in any other context, it is treated
81as a regular character.) The "*" modifier is equivalent to C<{0,}>, the "+"
25f94b33
AD
82modifier to C<{1,}>, and the "?" modifier to C<{0,1}>. n and m are limited
83to integral values less than 65536.
a0d0e21e
LW
84
85By default, a quantified subpattern is "greedy", that is, it will match as
86many times as possible without causing the rest pattern not to match. The
87standard quantifiers are all "greedy", in that they match as many
88occurrences as possible (given a particular starting location) without
89causing the pattern to fail. If you want it to match the minimum number
90of times possible, follow the quantifier with a "?" after any of them.
91Note that the meanings don't change, just the "gravity":
92
93 *? Match 0 or more times
94 +? Match 1 or more times
95 ?? Match 0 or 1 time
96 {n}? Match exactly n times
97 {n,}? Match at least n times
98 {n,m}? Match at least n but not more than m times
99
100Since patterns are processed as double quoted strings, the following
101also work:
102
103 \t tab
104 \n newline
105 \r return
106 \f form feed
107 \v vertical tab, whatever that is
108 \a alarm (bell)
cb1a09d0
AD
109 \e escape (think troff)
110 \033 octal char (think of a PDP-11)
111 \x1B hex char
a0d0e21e 112 \c[ control char
cb1a09d0
AD
113 \l lowercase next char (think vi)
114 \u uppercase next char (think vi)
115 \L lowercase till \E (think vi)
116 \U uppercase till \E (think vi)
117 \E end case modification (think vi)
a0d0e21e
LW
118 \Q quote regexp metacharacters till \E
119
120In addition, Perl defines the following:
121
122 \w Match a "word" character (alphanumeric plus "_")
123 \W Match a non-word character
124 \s Match a whitespace character
125 \S Match a non-whitespace character
126 \d Match a digit character
127 \D Match a non-digit character
128
129Note that C<\w> matches a single alphanumeric character, not a whole
cb1a09d0
AD
130word. To match a word you'd need to say C<\w+>. You may use C<\w>,
131C<\W>, C<\s>, C<\S>, C<\d> and C<\D> within character classes (though not
132as either end of a range).
a0d0e21e
LW
133
134Perl defines the following zero-width assertions:
135
136 \b Match a word boundary
137 \B Match a non-(word boundary)
138 \A Match only at beginning of string
139 \Z Match only at end of string
140 \G Match only where previous m//g left off
141
142A word boundary (C<\b>) is defined as a spot between two characters that
143has a C<\w> on one side of it and and a C<\W> on the other side of it (in
144either order), counting the imaginary characters off the beginning and
145end of the string as matching a C<\W>. (Within character classes C<\b>
146represents backspace rather than a word boundary.) The C<\A> and C<\Z> are
147just like "^" and "$" except that they won't match multiple times when the
148C</m> modifier is used, while "^" and "$" will match at every internal line
149boundary.
150
151When the bracketing construct C<( ... )> is used, \<digit> matches the
cb1a09d0
AD
152digit'th substring. Outside of the pattern, always use "$" instead of "\"
153in front of the digit. (The \<digit> notation can on rare occasion work
154outside the current pattern, this should not be relied upon. See the
155WARNING below.) The scope of $<digit> (and C<$`>, C<$&>, and C<$')>
156extends to the end of the enclosing BLOCK or eval string, or to the next
157successful pattern match, whichever comes first. If you want to use
158parentheses to delimit subpattern (e.g. a set of alternatives) without
a0d0e21e 159saving it as a subpattern, follow the ( with a ?.
cb1a09d0
AD
160
161You may have as many parentheses as you wish. If you have more
a0d0e21e
LW
162than 9 substrings, the variables $10, $11, ... refer to the
163corresponding substring. Within the pattern, \10, \11, etc. refer back
164to substrings if there have been at least that many left parens before
165the backreference. Otherwise (for backward compatibilty) \10 is the
166same as \010, a backspace, and \11 the same as \011, a tab. And so
167on. (\1 through \9 are always backreferences.)
168
169C<$+> returns whatever the last bracket match matched. C<$&> returns the
170entire matched string. ($0 used to return the same thing, but not any
171more.) C<$`> returns everything before the matched string. C<$'> returns
172everything after the matched string. Examples:
173
174 s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two words
175
176 if (/Time: (..):(..):(..)/) {
177 $hours = $1;
178 $minutes = $2;
179 $seconds = $3;
180 }
181
182You will note that all backslashed metacharacters in Perl are
183alphanumeric, such as C<\b>, C<\w>, C<\n>. Unlike some other regular expression
184languages, there are no backslashed symbols that aren't alphanumeric.
185So anything that looks like \\, \(, \), \<, \>, \{, or \} is always
186interpreted as a literal character, not a metacharacter. This makes it
187simple to quote a string that you want to use for a pattern but that
188you are afraid might contain metacharacters. Simply quote all the
189non-alphanumeric characters:
190
191 $pattern =~ s/(\W)/\\$1/g;
192
193You can also use the built-in quotemeta() function to do this.
194An even easier way to quote metacharacters right in the match operator
195is to say
196
197 /$unquoted\Q$quoted\E$unquoted/
198
199Perl 5 defines a consistent extension syntax for regular expressions.
200The syntax is a pair of parens with a question mark as the first thing
201within the parens (this was a syntax error in Perl 4). The character
202after the question mark gives the function of the extension. Several
203extensions are already supported:
204
205=over 10
206
207=item (?#text)
208
cb1a09d0
AD
209A comment. The text is ignored. If the C</x> switch is used to enable
210whitespace formatting, a simple C<#> will suffice.
a0d0e21e
LW
211
212=item (?:regexp)
213
214This groups things like "()" but doesn't make backrefences like "()" does. So
215
216 split(/\b(?:a|b|c)\b/)
217
218is like
219
220 split(/\b(a|b|c)\b/)
221
222but doesn't spit out extra fields.
223
224=item (?=regexp)
225
226A zero-width positive lookahead assertion. For example, C</\w+(?=\t)/>
227matches a word followed by a tab, without including the tab in C<$&>.
228
229=item (?!regexp)
230
231A zero-width negative lookahead assertion. For example C</foo(?!bar)/>
232matches any occurrence of "foo" that isn't followed by "bar". Note
233however that lookahead and lookbehind are NOT the same thing. You cannot
234use this for lookbehind: C</(?!foo)bar/> will not find an occurrence of
235"bar" that is preceded by something which is not "foo". That's because
236the C<(?!foo)> is just saying that the next thing cannot be "foo"--and
237it's not, it's a "bar", so "foobar" will match. You would have to do
238something like C</(?foo)...bar/> for that. We say "like" because there's
239the case of your "bar" not having three characters before it. You could
240cover that this way: C</(?:(?!foo)...|^..?)bar/>. Sometimes it's still
241easier just to say:
242
243 if (/foo/ && $` =~ /bar$/)
244
245
246=item (?imsx)
247
248One or more embedded pattern-match modifiers. This is particularly
249useful for patterns that are specified in a table somewhere, some of
250which want to be case sensitive, and some of which don't. The case
251insensitive ones merely need to include C<(?i)> at the front of the
252pattern. For example:
253
254 $pattern = "foobar";
255 if ( /$pattern/i )
256
257 # more flexible:
258
259 $pattern = "(?i)foobar";
260 if ( /$pattern/ )
261
262=back
263
264The specific choice of question mark for this and the new minimal
265matching construct was because 1) question mark is pretty rare in older
266regular expressions, and 2) whenever you see one, you should stop
267and "question" exactly what is going on. That's psychology...
268
269=head2 Version 8 Regular Expressions
270
271In case you're not familiar with the "regular" Version 8 regexp
272routines, here are the pattern-matching rules not described above.
273
274Any single character matches itself, unless it is a I<metacharacter>
275with a special meaning described here or above. You can cause
276characters which normally function as metacharacters to be interpreted
277literally by prefixing them with a "\" (e.g. "\." matches a ".", not any
278character; "\\" matches a "\"). A series of characters matches that
279series of characters in the target string, so the pattern C<blurfl>
280would match "blurfl" in the target string.
281
282You can specify a character class, by enclosing a list of characters
283in C<[]>, which will match any one of the characters in the list. If the
284first character after the "[" is "^", the class matches any character not
285in the list. Within a list, the "-" character is used to specify a
286range, so that C<a-z> represents all the characters between "a" and "z",
287inclusive.
288
289Characters may be specified using a metacharacter syntax much like that
290used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return,
291"\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string
292of octal digits, matches the character whose ASCII value is I<nnn>.
293Similarly, \xI<nn>, where I<nn> are hexidecimal digits, matches the
294character whose ASCII value is I<nn>. The expression \cI<x> matches the
295ASCII character control-I<x>. Finally, the "." metacharacter matches any
296character except "\n" (unless you use C</s>).
297
298You can specify a series of alternatives for a pattern using "|" to
299separate them, so that C<fee|fie|foe> will match any of "fee", "fie",
300or "foe" in the target string (as would C<f(e|i|o)e>). Note that the
301first alternative includes everything from the last pattern delimiter
302("(", "[", or the beginning of the pattern) up to the first "|", and
303the last alternative contains everything from the last "|" to the next
304pattern delimiter. For this reason, it's common practice to include
305alternatives in parentheses, to minimize confusion about where they
748a9306
LW
306start and end. Note however that "|" is interpreted as a literal with
307square brackets, so if you write C<[fee|fie|foe]> you're really only
308matching C<[feio|]>.
a0d0e21e
LW
309
310Within a pattern, you may designate subpatterns for later reference by
311enclosing them in parentheses, and you may refer back to the I<n>th
312subpattern later in the pattern using the metacharacter \I<n>.
313Subpatterns are numbered based on the left to right order of their
314opening parenthesis. Note that a backreference matches whatever
315actually matched the subpattern in the string being examined, not the
748a9306 316rules for that subpattern. Therefore, C<(0|0x)\d*\s\1\d*> will
a0d0e21e 317match "0x1234 0x4321",but not "0x1234 01234", since subpattern 1
748a9306 318actually matched "0x", even though the rule C<0|0x> could
a0d0e21e 319potentially match the leading 0 in the second number.
cb1a09d0
AD
320
321=head2 WARNING on \1 vs $1
322
323Some people get too used to writing things like
324
325 $pattern =~ s/(\W)/\\\1/g;
326
327This is grandfathered for the RHS of a substitute to avoid shocking the
328B<sed> addicts, but it's a dirty habit to get into. That's because in
329PerlThink, the right-hand side of a C<s///> is a double-quoted string. C<\1> in
330the usual double-quoted string means a control-A. The customary Unix
331meaning of C<\1> is kludged in for C<s///>. However, if you get into the habit
332of doing that, you get yourself into trouble if you then add an C</e>
333modifier.
334
335 s/(\d+)/ \1 + 1 /eg;
336
337Or if you try to do
338
339 s/(\d+)/\1000/;
340
341You can't disambiguate that by saying C<\{1}000>, whereas you can fix it with
342C<${1}000>. Basically, the operation of interpolation should not be confused
343with the operation of matching a backreference. Certainly they mean two
344different things on the I<left> side of the C<s///>.