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