Debian Codegraph @

upstream/debian-unstable/man1/perlrequick.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLREQUICK 1"
58 .TH PERLREQUICK 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perlrequick \- Perl regular expressions quick start
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 This page covers the very basics of understanding, creating and
68 using regular expressions ('regexes') in Perl.
69 .SH "The Guide"
70 .IX Header "The Guide"
71 This page assumes you already know things, like what a "pattern" is, and
72 the basic syntax of using them. If you don't, see perlretut.
73 .SS "Simple word matching"
74 .IX Subsection "Simple word matching"
75 The simplest regex is simply a word, or more generally, a string of
76 characters. A regex consisting of a word matches any string that
77 contains that word:
78 .PP
79 .Vb 1
80 \& "Hello World" =~ /World/; # matches
81 .Ve
82 .PP
83 In this statement, \f(CW\*(C`World\*(C'\fR is a regex and the \f(CW\*(C`//\*(C'\fR enclosing
84 \&\f(CW\*(C`/World/\*(C'\fR tells Perl to search a string for a match. The operator
85 \&\f(CW\*(C`=~\*(C'\fR associates the string with the regex match and produces a true
86 value if the regex matched, or false if the regex did not match. In
87 our case, \f(CW\*(C`World\*(C'\fR matches the second word in \f(CW"Hello World"\fR, so the
88 expression is true. This idea has several variations.
89 .PP
90 Expressions like this are useful in conditionals:
91 .PP
92 .Vb 1
93 \& print "It matches\en" if "Hello World" =~ /World/;
94 .Ve
95 .PP
96 The sense of the match can be reversed by using \f(CW\*(C`!~\*(C'\fR operator:
97 .PP
98 .Vb 1
99 \& print "It doesn\*(Aqt match\en" if "Hello World" !~ /World/;
100 .Ve
101 .PP
102 The literal string in the regex can be replaced by a variable:
103 .PP
104 .Vb 2
105 \& $greeting = "World";
106 \& print "It matches\en" if "Hello World" =~ /$greeting/;
107 .Ve
108 .PP
109 If you're matching against \f(CW$_\fR, the \f(CW\*(C`$_ =~\*(C'\fR part can be omitted:
110 .PP
111 .Vb 2
112 \& $_ = "Hello World";
113 \& print "It matches\en" if /World/;
114 .Ve
115 .PP
116 Finally, the \f(CW\*(C`//\*(C'\fR default delimiters for a match can be changed to
117 arbitrary delimiters by putting an \f(CW\*(Aqm\*(Aq\fR out front:
118 .PP
119 .Vb 4
120 \& "Hello World" =~ m!World!; # matches, delimited by \*(Aq!\*(Aq
121 \& "Hello World" =~ m{World}; # matches, note the matching \*(Aq{}\*(Aq
122 \& "/usr/bin/perl" =~ m"/perl"; # matches after \*(Aq/usr/bin\*(Aq,
123 \& # \*(Aq/\*(Aq becomes an ordinary char
124 .Ve
125 .PP
126 Regexes must match a part of the string \fIexactly\fR in order for the
127 statement to be true:
128 .PP
129 .Vb 3
130 \& "Hello World" =~ /world/; # doesn\*(Aqt match, case sensitive
131 \& "Hello World" =~ /o W/; # matches, \*(Aq \*(Aq is an ordinary char
132 \& "Hello World" =~ /World /; # doesn\*(Aqt match, no \*(Aq \*(Aq at end
133 .Ve
134 .PP
135 Perl will always match at the earliest possible point in the string:
136 .PP
137 .Vb 2
138 \& "Hello World" =~ /o/; # matches \*(Aqo\*(Aq in \*(AqHello\*(Aq
139 \& "That hat is red" =~ /hat/; # matches \*(Aqhat\*(Aq in \*(AqThat\*(Aq
140 .Ve
141 .PP
142 Not all characters can be used 'as is' in a match. Some characters,
143 called \fBmetacharacters\fR, are considered special, and reserved for use
144 in regex notation. The metacharacters are
145 .PP
146 .Vb 1
147 \& {}[]()^$.|*+?\e
148 .Ve
149 .PP
150 A metacharacter can be matched literally by putting a backslash before
151 it:
152 .PP
153 .Vb 4
154 \& "2+2=4" =~ /2+2/; # doesn\*(Aqt match, + is a metacharacter
155 \& "2+2=4" =~ /2\e+2/; # matches, \e+ is treated like an ordinary +
156 \& \*(AqC:\eWIN32\*(Aq =~ /C:\e\eWIN/; # matches
157 \& "/usr/bin/perl" =~ /\e/usr\e/bin\e/perl/; # matches
158 .Ve
159 .PP
160 In the last regex, the forward slash \f(CW\*(Aq/\*(Aq\fR is also backslashed,
161 because it is used to delimit the regex.
162 .PP
163 Most of the metacharacters aren't always special, and other characters
164 (such as the ones delimiting the pattern) become special under various
165 circumstances. This can be confusing and lead to unexpected results.
166 \&\f(CW\*(C`use\ re\ \*(Aqstrict\*(Aq\*(C'\fR can notify you of potential
167 pitfalls.
168 .PP
169 Non-printable ASCII characters are represented by \fBescape sequences\fR.
170 Common examples are \f(CW\*(C`\et\*(C'\fR for a tab, \f(CW\*(C`\en\*(C'\fR for a newline, and \f(CW\*(C`\er\*(C'\fR
171 for a carriage return. Arbitrary bytes are represented by octal
172 escape sequences, e.g., \f(CW\*(C`\e033\*(C'\fR, or hexadecimal escape sequences,
173 e.g., \f(CW\*(C`\ex1B\*(C'\fR:
174 .PP
175 .Vb 3
176 \& "1000\et2000" =~ m(0\et2) # matches
177 \& "cat" =~ /\e143\ex61\ex74/ # matches in ASCII, but
178 \& # a weird way to spell cat
179 .Ve
180 .PP
181 Regexes are treated mostly as double-quoted strings, so variable
182 substitution works:
183 .PP
184 .Vb 3
185 \& $foo = \*(Aqhouse\*(Aq;
186 \& \*(Aqcathouse\*(Aq =~ /cat$foo/; # matches
187 \& \*(Aqhousecat\*(Aq =~ /${foo}cat/; # matches
188 .Ve
189 .PP
190 With all of the regexes above, if the regex matched anywhere in the
191 string, it was considered a match. To specify \fIwhere\fR it should
192 match, we would use the \fBanchor\fR metacharacters \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR. The
193 anchor \f(CW\*(C`^\*(C'\fR means match at the beginning of the string and the anchor
194 \&\f(CW\*(C`$\*(C'\fR means match at the end of the string, or before a newline at the
195 end of the string. Some examples:
196 .PP
197 .Vb 5
198 \& "housekeeper" =~ /keeper/; # matches
199 \& "housekeeper" =~ /^keeper/; # doesn\*(Aqt match
200 \& "housekeeper" =~ /keeper$/; # matches
201 \& "housekeeper\en" =~ /keeper$/; # matches
202 \& "housekeeper" =~ /^housekeeper$/; # matches
203 .Ve
204 .SS "Using character classes"
205 .IX Subsection "Using character classes"
206 A \fBcharacter class\fR allows a set of possible characters, rather than
207 just a single character, to match at a particular point in a regex.
208 There are a number of different types of character classes, but usually
209 when people use this term, they are referring to the type described in
210 this section, which are technically called "Bracketed character
211 classes", because they are denoted by brackets \f(CW\*(C`[...]\*(C'\fR, with the set of
212 characters to be possibly matched inside. But we'll drop the "bracketed"
213 below to correspond with common usage. Here are some examples of
214 (bracketed) character classes:
215 .PP
216 .Vb 3
217 \& /cat/; # matches \*(Aqcat\*(Aq
218 \& /[bcr]at/; # matches \*(Aqbat\*(Aq, \*(Aqcat\*(Aq, or \*(Aqrat\*(Aq
219 \& "abc" =~ /[cab]/; # matches \*(Aqa\*(Aq
220 .Ve
221 .PP
222 In the last statement, even though \f(CW\*(Aqc\*(Aq\fR is the first character in
223 the class, the earliest point at which the regex can match is \f(CW\*(Aqa\*(Aq\fR.
224 .PP
225 .Vb 3
226 \& /[yY][eE][sS]/; # match \*(Aqyes\*(Aq in a case\-insensitive way
227 \& # \*(Aqyes\*(Aq, \*(AqYes\*(Aq, \*(AqYES\*(Aq, etc.
228 \& /yes/i; # also match \*(Aqyes\*(Aq in a case\-insensitive way
229 .Ve
230 .PP
231 The last example shows a match with an \f(CW\*(Aqi\*(Aq\fR \fBmodifier\fR, which makes
232 the match case-insensitive.
233 .PP
234 Character classes also have ordinary and special characters, but the
235 sets of ordinary and special characters inside a character class are
236 different than those outside a character class. The special
237 characters for a character class are \f(CW\*(C`\-]\e^$\*(C'\fR and are matched using an
238 escape:
239 .PP
240 .Vb 5
241 \& /[\e]c]def/; # matches \*(Aq]def\*(Aq or \*(Aqcdef\*(Aq
242 \& $x = \*(Aqbcr\*(Aq;
243 \& /[$x]at/; # matches \*(Aqbat, \*(Aqcat\*(Aq, or \*(Aqrat\*(Aq
244 \& /[\e$x]at/; # matches \*(Aq$at\*(Aq or \*(Aqxat\*(Aq
245 \& /[\e\e$x]at/; # matches \*(Aq\eat\*(Aq, \*(Aqbat, \*(Aqcat\*(Aq, or \*(Aqrat\*(Aq
246 .Ve
247 .PP
248 The special character \f(CW\*(Aq\-\*(Aq\fR acts as a range operator within character
249 classes, so that the unwieldy \f(CW\*(C`[0123456789]\*(C'\fR and \f(CW\*(C`[abc...xyz]\*(C'\fR
250 become the svelte \f(CW\*(C`[0\-9]\*(C'\fR and \f(CW\*(C`[a\-z]\*(C'\fR:
251 .PP
252 .Vb 2
253 \& /item[0\-9]/; # matches \*(Aqitem0\*(Aq or ... or \*(Aqitem9\*(Aq
254 \& /[0\-9a\-fA\-F]/; # matches a hexadecimal digit
255 .Ve
256 .PP
257 If \f(CW\*(Aq\-\*(Aq\fR is the first or last character in a character class, it is
258 treated as an ordinary character.
259 .PP
260 The special character \f(CW\*(C`^\*(C'\fR in the first position of a character class
261 denotes a \fBnegated character class\fR, which matches any character but
262 those in the brackets. Both \f(CW\*(C`[...]\*(C'\fR and \f(CW\*(C`[^...]\*(C'\fR must match a
263 character, or the match fails. Then
264 .PP
265 .Vb 4
266 \& /[^a]at/; # doesn\*(Aqt match \*(Aqaat\*(Aq or \*(Aqat\*(Aq, but matches
267 \& # all other \*(Aqbat\*(Aq, \*(Aqcat, \*(Aq0at\*(Aq, \*(Aq%at\*(Aq, etc.
268 \& /[^0\-9]/; # matches a non\-numeric character
269 \& /[a^]at/; # matches \*(Aqaat\*(Aq or \*(Aq^at\*(Aq; here \*(Aq^\*(Aq is ordinary
270 .Ve
271 .PP
272 Perl has several abbreviations for common character classes. (These
273 definitions are those that Perl uses in ASCII-safe mode with the \f(CW\*(C`/a\*(C'\fR modifier.
274 Otherwise they could match many more non-ASCII Unicode characters as
275 well. See "Backslash sequences" in perlrecharclass for details.)
276 .IP \(bu 4
277 \&\ed is a digit and represents
278 .Sp
279 .Vb 1
280 \& [0\-9]
281 .Ve
282 .IP \(bu 4
283 \&\es is a whitespace character and represents
284 .Sp
285 .Vb 1
286 \& [\e \et\er\en\ef]
287 .Ve
288 .IP \(bu 4
289 \&\ew is a word character (alphanumeric or _) and represents
290 .Sp
291 .Vb 1
292 \& [0\-9a\-zA\-Z_]
293 .Ve
294 .IP \(bu 4
295 \&\eD is a negated \ed; it represents any character but a digit
296 .Sp
297 .Vb 1
298 \& [^0\-9]
299 .Ve
300 .IP \(bu 4
301 \&\eS is a negated \es; it represents any non-whitespace character
302 .Sp
303 .Vb 1
304 \& [^\es]
305 .Ve
306 .IP \(bu 4
307 \&\eW is a negated \ew; it represents any non-word character
308 .Sp
309 .Vb 1
310 \& [^\ew]
311 .Ve
312 .IP \(bu 4
313 The period '.' matches any character but "\en"
314 .PP
315 The \f(CW\*(C`\ed\es\ew\eD\eS\eW\*(C'\fR abbreviations can be used both inside and outside
316 of character classes. Here are some in use:
317 .PP
318 .Vb 7
319 \& /\ed\ed:\ed\ed:\ed\ed/; # matches a hh:mm:ss time format
320 \& /[\ed\es]/; # matches any digit or whitespace character
321 \& /\ew\eW\ew/; # matches a word char, followed by a
322 \& # non\-word char, followed by a word char
323 \& /..rt/; # matches any two chars, followed by \*(Aqrt\*(Aq
324 \& /end\e./; # matches \*(Aqend.\*(Aq
325 \& /end[.]/; # same thing, matches \*(Aqend.\*(Aq
326 .Ve
327 .PP
328 The \fBword\ anchor\fR\ \f(CW\*(C`\eb\*(C'\fR matches a boundary between a word
329 character and a non-word character \f(CW\*(C`\ew\eW\*(C'\fR or \f(CW\*(C`\eW\ew\*(C'\fR:
330 .PP
331 .Vb 4
332 \& $x = "Housecat catenates house and cat";
333 \& $x =~ /\ebcat/; # matches cat in \*(Aqcatenates\*(Aq
334 \& $x =~ /cat\eb/; # matches cat in \*(Aqhousecat\*(Aq
335 \& $x =~ /\ebcat\eb/; # matches \*(Aqcat\*(Aq at end of string
336 .Ve
337 .PP
338 In the last example, the end of the string is considered a word
339 boundary.
340 .PP
341 For natural language processing (so that, for example, apostrophes are
342 included in words), use instead \f(CW\*(C`\eb{wb}\*(C'\fR
343 .PP
344 .Vb 1
345 \& "don\*(Aqt" =~ / .+? \eb{wb} /x; # matches the whole string
346 .Ve
347 .SS "Matching this or that"
348 .IX Subsection "Matching this or that"
349 We can match different character strings with the \fBalternation\fR
350 metacharacter \f(CW\*(Aq|\*(Aq\fR. To match \f(CW\*(C`dog\*(C'\fR or \f(CW\*(C`cat\*(C'\fR, we form the regex
351 \&\f(CW\*(C`dog|cat\*(C'\fR. As before, Perl will try to match the regex at the
352 earliest possible point in the string. At each character position,
353 Perl will first try to match the first alternative, \f(CW\*(C`dog\*(C'\fR. If
354 \&\f(CW\*(C`dog\*(C'\fR doesn't match, Perl will then try the next alternative, \f(CW\*(C`cat\*(C'\fR.
355 If \f(CW\*(C`cat\*(C'\fR doesn't match either, then the match fails and Perl moves to
356 the next position in the string. Some examples:
357 .PP
358 .Vb 2
359 \& "cats and dogs" =~ /cat|dog|bird/; # matches "cat"
360 \& "cats and dogs" =~ /dog|cat|bird/; # matches "cat"
361 .Ve
362 .PP
363 Even though \f(CW\*(C`dog\*(C'\fR is the first alternative in the second regex,
364 \&\f(CW\*(C`cat\*(C'\fR is able to match earlier in the string.
365 .PP
366 .Vb 2
367 \& "cats" =~ /c|ca|cat|cats/; # matches "c"
368 \& "cats" =~ /cats|cat|ca|c/; # matches "cats"
369 .Ve
370 .PP
371 At a given character position, the first alternative that allows the
372 regex match to succeed will be the one that matches. Here, all the
373 alternatives match at the first string position, so the first matches.
374 .SS "Grouping things and hierarchical matching"
375 .IX Subsection "Grouping things and hierarchical matching"
376 The \fBgrouping\fR metacharacters \f(CW\*(C`()\*(C'\fR allow a part of a regex to be
377 treated as a single unit. Parts of a regex are grouped by enclosing
378 them in parentheses. The regex \f(CWhouse(cat|keeper)\fR means match
379 \&\f(CW\*(C`house\*(C'\fR followed by either \f(CW\*(C`cat\*(C'\fR or \f(CW\*(C`keeper\*(C'\fR. Some more examples
380 are
381 .PP
382 .Vb 2
383 \& /(a|b)b/; # matches \*(Aqab\*(Aq or \*(Aqbb\*(Aq
384 \& /(^a|b)c/; # matches \*(Aqac\*(Aq at start of string or \*(Aqbc\*(Aq anywhere
385 \&
386 \& /house(cat|)/; # matches either \*(Aqhousecat\*(Aq or \*(Aqhouse\*(Aq
387 \& /house(cat(s|)|)/; # matches either \*(Aqhousecats\*(Aq or \*(Aqhousecat\*(Aq or
388 \& # \*(Aqhouse\*(Aq. Note groups can be nested.
389 \&
390 \& "20" =~ /(19|20|)\ed\ed/; # matches the null alternative \*(Aq()\ed\ed\*(Aq,
391 \& # because \*(Aq20\ed\ed\*(Aq can\*(Aqt match
392 .Ve
393 .SS "Extracting matches"
394 .IX Subsection "Extracting matches"
395 The grouping metacharacters \f(CW\*(C`()\*(C'\fR also allow the extraction of the
396 parts of a string that matched. For each grouping, the part that
397 matched inside goes into the special variables \f(CW$1\fR, \f(CW$2\fR, etc.
398 They can be used just as ordinary variables:
399 .PP
400 .Vb 5
401 \& # extract hours, minutes, seconds
402 \& $time =~ /(\ed\ed):(\ed\ed):(\ed\ed)/; # match hh:mm:ss format
403 \& $hours = $1;
404 \& $minutes = $2;
405 \& $seconds = $3;
406 .Ve
407 .PP
408 In list context, a match \f(CW\*(C`/regex/\*(C'\fR with groupings will return the
409 list of matched values \f(CW\*(C`($1,$2,...)\*(C'\fR. So we could rewrite it as
410 .PP
411 .Vb 1
412 \& ($hours, $minutes, $second) = ($time =~ /(\ed\ed):(\ed\ed):(\ed\ed)/);
413 .Ve
414 .PP
415 If the groupings in a regex are nested, \f(CW$1\fR gets the group with the
416 leftmost opening parenthesis, \f(CW$2\fR the next opening parenthesis,
417 etc. For example, here is a complex regex and the matching variables
418 indicated below it:
419 .PP
420 .Vb 2
421 \& /(ab(cd|ef)((gi)|j))/;
422 \& 1 2 34
423 .Ve
424 .PP
425 Associated with the matching variables \f(CW$1\fR, \f(CW$2\fR, ... are
426 the \fBbackreferences\fR \f(CW\*(C`\eg1\*(C'\fR, \f(CW\*(C`\eg2\*(C'\fR, ... Backreferences are
427 matching variables that can be used \fIinside\fR a regex:
428 .PP
429 .Vb 1
430 \& /(\ew\ew\ew)\es\eg1/; # find sequences like \*(Aqthe the\*(Aq in string
431 .Ve
432 .PP
433 \&\f(CW$1\fR, \f(CW$2\fR, ... should only be used outside of a regex, and \f(CW\*(C`\eg1\*(C'\fR,
434 \&\f(CW\*(C`\eg2\*(C'\fR, ... only inside a regex.
435 .SS "Matching repetitions"
436 .IX Subsection "Matching repetitions"
437 The \fBquantifier\fR metacharacters \f(CW\*(C`?\*(C'\fR, \f(CW\*(C`*\*(C'\fR, \f(CW\*(C`+\*(C'\fR, and \f(CW\*(C`{}\*(C'\fR allow us
438 to determine the number of repeats of a portion of a regex we
439 consider to be a match. Quantifiers are put immediately after the
440 character, character class, or grouping that we want to specify. They
441 have the following meanings:
442 .IP \(bu 4
443 \&\f(CW\*(C`a?\*(C'\fR = match 'a' 1 or 0 times
444 .IP \(bu 4
445 \&\f(CW\*(C`a*\*(C'\fR = match 'a' 0 or more times, i.e., any number of times
446 .IP \(bu 4
447 \&\f(CW\*(C`a+\*(C'\fR = match 'a' 1 or more times, i.e., at least once
448 .IP \(bu 4
449 \&\f(CW\*(C`a{n,m}\*(C'\fR = match at least \f(CW\*(C`n\*(C'\fR times, but not more than \f(CW\*(C`m\*(C'\fR
450 times.
451 .IP \(bu 4
452 \&\f(CW\*(C`a{n,}\*(C'\fR = match at least \f(CW\*(C`n\*(C'\fR or more times
453 .IP \(bu 4
454 \&\f(CW\*(C`a{,n}\*(C'\fR = match \f(CW\*(C`n\*(C'\fR times or fewer (Added in v5.34)
455 .IP \(bu 4
456 \&\f(CW\*(C`a{n}\*(C'\fR = match exactly \f(CW\*(C`n\*(C'\fR times
457 .PP
458 Here are some examples:
459 .PP
460 .Vb 6
461 \& /[a\-z]+\es+\ed*/; # match a lowercase word, at least some space, and
462 \& # any number of digits
463 \& /(\ew+)\es+\eg1/; # match doubled words of arbitrary length
464 \& $year =~ /^\ed{2,4}$/; # make sure year is at least 2 but not more
465 \& # than 4 digits
466 \& $year =~ /^\ed{ 4 }$|^\ed{2}$/; # better match; throw out 3 digit dates
467 .Ve
468 .PP
469 These quantifiers will try to match as much of the string as possible,
470 while still allowing the regex to match. So we have
471 .PP
472 .Vb 5
473 \& $x = \*(Aqthe cat in the hat\*(Aq;
474 \& $x =~ /^(.*)(at)(.*)$/; # matches,
475 \& # $1 = \*(Aqthe cat in the h\*(Aq
476 \& # $2 = \*(Aqat\*(Aq
477 \& # $3 = \*(Aq\*(Aq (0 matches)
478 .Ve
479 .PP
480 The first quantifier \f(CW\*(C`.*\*(C'\fR grabs as much of the string as possible
481 while still having the regex match. The second quantifier \f(CW\*(C`.*\*(C'\fR has
482 no string left to it, so it matches 0 times.
483 .SS "More matching"
484 .IX Subsection "More matching"
485 There are a few more things you might want to know about matching
486 operators.
487 The global modifier \f(CW\*(C`/g\*(C'\fR allows the matching operator to match
488 within a string as many times as possible. In scalar context,
489 successive matches against a string will have \f(CW\*(C`/g\*(C'\fR jump from match
490 to match, keeping track of position in the string as it goes along.
491 You can get or set the position with the \f(CWpos()\fR function.
492 For example,
493 .PP
494 .Vb 4
495 \& $x = "cat dog house"; # 3 words
496 \& while ($x =~ /(\ew+)/g) {
497 \& print "Word is $1, ends at position ", pos $x, "\en";
498 \& }
499 .Ve
500 .PP
501 prints
502 .PP
503 .Vb 3
504 \& Word is cat, ends at position 3
505 \& Word is dog, ends at position 7
506 \& Word is house, ends at position 13
507 .Ve
508 .PP
509 A failed match or changing the target string resets the position. If
510 you don't want the position reset after failure to match, add the
511 \&\f(CW\*(C`/c\*(C'\fR, as in \f(CW\*(C`/regex/gc\*(C'\fR.
512 .PP
513 In list context, \f(CW\*(C`/g\*(C'\fR returns a list of matched groupings, or if
514 there are no groupings, a list of matches to the whole regex. So
515 .PP
516 .Vb 4
517 \& @words = ($x =~ /(\ew+)/g); # matches,
518 \& # $word[0] = \*(Aqcat\*(Aq
519 \& # $word[1] = \*(Aqdog\*(Aq
520 \& # $word[2] = \*(Aqhouse\*(Aq
521 .Ve
522 .SS "Search and replace"
523 .IX Subsection "Search and replace"
524 Search and replace is performed using \f(CW\*(C`s/regex/replacement/modifiers\*(C'\fR.
525 The \f(CW\*(C`replacement\*(C'\fR is a Perl double-quoted string that replaces in the
526 string whatever is matched with the \f(CW\*(C`regex\*(C'\fR. The operator \f(CW\*(C`=~\*(C'\fR is
527 also used here to associate a string with \f(CW\*(C`s///\*(C'\fR. If matching
528 against \f(CW$_\fR, the \f(CW\*(C`$_\ =~\*(C'\fR can be dropped. If there is a match,
529 \&\f(CW\*(C`s///\*(C'\fR returns the number of substitutions made; otherwise it returns
530 false. Here are a few examples:
531 .PP
532 .Vb 5
533 \& $x = "Time to feed the cat!";
534 \& $x =~ s/cat/hacker/; # $x contains "Time to feed the hacker!"
535 \& $y = "\*(Aqquoted words\*(Aq";
536 \& $y =~ s/^\*(Aq(.*)\*(Aq$/$1/; # strip single quotes,
537 \& # $y contains "quoted words"
538 .Ve
539 .PP
540 With the \f(CW\*(C`s///\*(C'\fR operator, the matched variables \f(CW$1\fR, \f(CW$2\fR, etc.
541 are immediately available for use in the replacement expression. With
542 the global modifier, \f(CW\*(C`s///g\*(C'\fR will search and replace all occurrences
543 of the regex in the string:
544 .PP
545 .Vb 4
546 \& $x = "I batted 4 for 4";
547 \& $x =~ s/4/four/; # $x contains "I batted four for 4"
548 \& $x = "I batted 4 for 4";
549 \& $x =~ s/4/four/g; # $x contains "I batted four for four"
550 .Ve
551 .PP
552 The non-destructive modifier \f(CW\*(C`s///r\*(C'\fR causes the result of the substitution
553 to be returned instead of modifying \f(CW$_\fR (or whatever variable the
554 substitute was bound to with \f(CW\*(C`=~\*(C'\fR):
555 .PP
556 .Vb 3
557 \& $x = "I like dogs.";
558 \& $y = $x =~ s/dogs/cats/r;
559 \& print "$x $y\en"; # prints "I like dogs. I like cats."
560 \&
561 \& $x = "Cats are great.";
562 \& print $x =~ s/Cats/Dogs/r =~ s/Dogs/Frogs/r =~
563 \& s/Frogs/Hedgehogs/r, "\en";
564 \& # prints "Hedgehogs are great."
565 \&
566 \& @foo = map { s/[a\-z]/X/r } qw(a b c 1 2 3);
567 \& # @foo is now qw(X X X 1 2 3)
568 .Ve
569 .PP
570 The evaluation modifier \f(CW\*(C`s///e\*(C'\fR wraps an \f(CW\*(C`eval{...}\*(C'\fR around the
571 replacement string and the evaluated result is substituted for the
572 matched substring. Some examples:
573 .PP
574 .Vb 3
575 \& # reverse all the words in a string
576 \& $x = "the cat in the hat";
577 \& $x =~ s/(\ew+)/reverse $1/ge; # $x contains "eht tac ni eht tah"
578 \&
579 \& # convert percentage to decimal
580 \& $x = "A 39% hit rate";
581 \& $x =~ s!(\ed+)%!$1/100!e; # $x contains "A 0.39 hit rate"
582 .Ve
583 .PP
584 The last example shows that \f(CW\*(C`s///\*(C'\fR can use other delimiters, such as
585 \&\f(CW\*(C`s!!!\*(C'\fR and \f(CW\*(C`s{}{}\*(C'\fR, and even \f(CW\*(C`s{}//\*(C'\fR. If single quotes are used
586 \&\f(CW\*(C`s\*(Aq\*(Aq\*(Aq\*(C'\fR, then the regex and replacement are treated as single-quoted
587 strings.
588 .SS "The split operator"
589 .IX Subsection "The split operator"
590 \&\f(CW\*(C`split /regex/, string\*(C'\fR splits \f(CW\*(C`string\*(C'\fR into a list of substrings
591 and returns that list. The regex determines the character sequence
592 that \f(CW\*(C`string\*(C'\fR is split with respect to. For example, to split a
593 string into words, use
594 .PP
595 .Vb 4
596 \& $x = "Calvin and Hobbes";
597 \& @word = split /\es+/, $x; # $word[0] = \*(AqCalvin\*(Aq
598 \& # $word[1] = \*(Aqand\*(Aq
599 \& # $word[2] = \*(AqHobbes\*(Aq
600 .Ve
601 .PP
602 To extract a comma-delimited list of numbers, use
603 .PP
604 .Vb 4
605 \& $x = "1.618,2.718, 3.142";
606 \& @const = split /,\es*/, $x; # $const[0] = \*(Aq1.618\*(Aq
607 \& # $const[1] = \*(Aq2.718\*(Aq
608 \& # $const[2] = \*(Aq3.142\*(Aq
609 .Ve
610 .PP
611 If the empty regex \f(CW\*(C`//\*(C'\fR is used, the string is split into individual
612 characters. If the regex has groupings, then the list produced contains
613 the matched substrings from the groupings as well:
614 .PP
615 .Vb 6
616 \& $x = "/usr/bin";
617 \& @parts = split m!(/)!, $x; # $parts[0] = \*(Aq\*(Aq
618 \& # $parts[1] = \*(Aq/\*(Aq
619 \& # $parts[2] = \*(Aqusr\*(Aq
620 \& # $parts[3] = \*(Aq/\*(Aq
621 \& # $parts[4] = \*(Aqbin\*(Aq
622 .Ve
623 .PP
624 Since the first character of \f(CW$x\fR matched the regex, \f(CW\*(C`split\*(C'\fR prepended
625 an empty initial element to the list.
626 .ie n .SS """use re \*(Aqstrict\*(Aq"""
627 .el .SS "\f(CWuse re \*(Aqstrict\*(Aq\fP"
628 .IX Subsection "use re strict"
629 New in v5.22, this applies stricter rules than otherwise when compiling
630 regular expression patterns. It can find things that, while legal, may
631 not be what you intended.
632 .PP
633 See 'strict' in re.
634 .SH BUGS
635 .IX Header "BUGS"
636 None.
637 .SH "SEE ALSO"
638 .IX Header "SEE ALSO"
639 This is just a quick start guide. For a more in-depth tutorial on
640 regexes, see perlretut and for the reference page, see perlre.
641 .SH "AUTHOR AND COPYRIGHT"
642 .IX Header "AUTHOR AND COPYRIGHT"
643 Copyright (c) 2000 Mark Kvale
644 All rights reserved.
645 .PP
646 This document may be distributed under the same terms as Perl itself.
647 .SS Acknowledgments
648 .IX Subsection "Acknowledgments"
649 The author would like to thank Mark-Jason Dominus, Tom Christiansen,
650 Ilya Zakharevich, Brad Hughes, and Mike Giroux for all their helpful
651 comments.