1PERLREQUICK(1)         Perl Programmers Reference Guide         PERLREQUICK(1)
2
3
4

NAME

6       perlrequick - Perl regular expressions quick start
7

DESCRIPTION

9       This page covers the very basics of understanding, creating and using
10       regular expressions ('regexes') in Perl.
11

The Guide

13       This page assumes you already know things, like what a "pattern" is,
14       and the basic syntax of using them.  If you don't, see perlretut.
15
16   Simple word matching
17       The simplest regex is simply a word, or more generally, a string of
18       characters.  A regex consisting of a word matches any string that
19       contains that word:
20
21           "Hello World" =~ /World/;  # matches
22
23       In this statement, "World" is a regex and the "//" enclosing "/World/"
24       tells Perl to search a string for a match.  The operator "=~"
25       associates the string with the regex match and produces a true value if
26       the regex matched, or false if the regex did not match.  In our case,
27       "World" matches the second word in "Hello World", so the expression is
28       true.  This idea has several variations.
29
30       Expressions like this are useful in conditionals:
31
32           print "It matches\n" if "Hello World" =~ /World/;
33
34       The sense of the match can be reversed by using "!~" operator:
35
36           print "It doesn't match\n" if "Hello World" !~ /World/;
37
38       The literal string in the regex can be replaced by a variable:
39
40           $greeting = "World";
41           print "It matches\n" if "Hello World" =~ /$greeting/;
42
43       If you're matching against $_, the "$_ =~" part can be omitted:
44
45           $_ = "Hello World";
46           print "It matches\n" if /World/;
47
48       Finally, the "//" default delimiters for a match can be changed to
49       arbitrary delimiters by putting an 'm' out front:
50
51           "Hello World" =~ m!World!;   # matches, delimited by '!'
52           "Hello World" =~ m{World};   # matches, note the matching '{}'
53           "/usr/bin/perl" =~ m"/perl"; # matches after '/usr/bin',
54                                        # '/' becomes an ordinary char
55
56       Regexes must match a part of the string exactly in order for the
57       statement to be true:
58
59           "Hello World" =~ /world/;  # doesn't match, case sensitive
60           "Hello World" =~ /o W/;    # matches, ' ' is an ordinary char
61           "Hello World" =~ /World /; # doesn't match, no ' ' at end
62
63       Perl will always match at the earliest possible point in the string:
64
65           "Hello World" =~ /o/;       # matches 'o' in 'Hello'
66           "That hat is red" =~ /hat/; # matches 'hat' in 'That'
67
68       Not all characters can be used 'as is' in a match.  Some characters,
69       called metacharacters, are considered special, and reserved for use in
70       regex notation.  The metacharacters are
71
72           {}[]()^$.|*+?\
73
74       A metacharacter can be matched literally by putting a backslash before
75       it:
76
77           "2+2=4" =~ /2+2/;    # doesn't match, + is a metacharacter
78           "2+2=4" =~ /2\+2/;   # matches, \+ is treated like an ordinary +
79           'C:\WIN32' =~ /C:\\WIN/;                       # matches
80           "/usr/bin/perl" =~ /\/usr\/bin\/perl/;  # matches
81
82       In the last regex, the forward slash '/' is also backslashed, because
83       it is used to delimit the regex.
84
85       Most of the metacharacters aren't always special, and other characters
86       (such as the ones delimitting the pattern) become special under various
87       circumstances.  This can be confusing and lead to unexpected results.
88       "use re 'strict'" can notify you of potential pitfalls.
89
90       Non-printable ASCII characters are represented by escape sequences.
91       Common examples are "\t" for a tab, "\n" for a newline, and "\r" for a
92       carriage return.  Arbitrary bytes are represented by octal escape
93       sequences, e.g., "\033", or hexadecimal escape sequences, e.g., "\x1B":
94
95           "1000\t2000" =~ m(0\t2)  # matches
96           "cat" =~ /\143\x61\x74/  # matches in ASCII, but
97                                    # a weird way to spell cat
98
99       Regexes are treated mostly as double-quoted strings, so variable
100       substitution works:
101
102           $foo = 'house';
103           'cathouse' =~ /cat$foo/;   # matches
104           'housecat' =~ /${foo}cat/; # matches
105
106       With all of the regexes above, if the regex matched anywhere in the
107       string, it was considered a match.  To specify where it should match,
108       we would use the anchor metacharacters "^" and "$".  The anchor "^"
109       means match at the beginning of the string and the anchor "$" means
110       match at the end of the string, or before a newline at the end of the
111       string.  Some examples:
112
113           "housekeeper" =~ /keeper/;         # matches
114           "housekeeper" =~ /^keeper/;        # doesn't match
115           "housekeeper" =~ /keeper$/;        # matches
116           "housekeeper\n" =~ /keeper$/;      # matches
117           "housekeeper" =~ /^housekeeper$/;  # matches
118
119   Using character classes
120       A character class allows a set of possible characters, rather than just
121       a single character, to match at a particular point in a regex.  There
122       are a number of different types of character classes, but usually when
123       people use this term, they are referring to the type described in this
124       section, which are technically called "Bracketed character classes",
125       because they are denoted by brackets "[...]", with the set of
126       characters to be possibly matched inside.  But we'll drop the
127       "bracketed" below to correspond with common usage.  Here are some
128       examples of (bracketed) character classes:
129
130           /cat/;            # matches 'cat'
131           /[bcr]at/;        # matches 'bat', 'cat', or 'rat'
132           "abc" =~ /[cab]/; # matches 'a'
133
134       In the last statement, even though 'c' is the first character in the
135       class, the earliest point at which the regex can match is 'a'.
136
137           /[yY][eE][sS]/; # match 'yes' in a case-insensitive way
138                           # 'yes', 'Yes', 'YES', etc.
139           /yes/i;         # also match 'yes' in a case-insensitive way
140
141       The last example shows a match with an 'i' modifier, which makes the
142       match case-insensitive.
143
144       Character classes also have ordinary and special characters, but the
145       sets of ordinary and special characters inside a character class are
146       different than those outside a character class.  The special characters
147       for a character class are "-]\^$" and are matched using an escape:
148
149          /[\]c]def/; # matches ']def' or 'cdef'
150          $x = 'bcr';
151          /[$x]at/;   # matches 'bat, 'cat', or 'rat'
152          /[\$x]at/;  # matches '$at' or 'xat'
153          /[\\$x]at/; # matches '\at', 'bat, 'cat', or 'rat'
154
155       The special character '-' acts as a range operator within character
156       classes, so that the unwieldy "[0123456789]" and "[abc...xyz]" become
157       the svelte "[0-9]" and "[a-z]":
158
159           /item[0-9]/;  # matches 'item0' or ... or 'item9'
160           /[0-9a-fA-F]/;  # matches a hexadecimal digit
161
162       If '-' is the first or last character in a character class, it is
163       treated as an ordinary character.
164
165       The special character "^" in the first position of a character class
166       denotes a negated character class, which matches any character but
167       those in the brackets.  Both "[...]" and "[^...]" must match a
168       character, or the match fails.  Then
169
170           /[^a]at/;  # doesn't match 'aat' or 'at', but matches
171                      # all other 'bat', 'cat, '0at', '%at', etc.
172           /[^0-9]/;  # matches a non-numeric character
173           /[a^]at/;  # matches 'aat' or '^at'; here '^' is ordinary
174
175       Perl has several abbreviations for common character classes. (These
176       definitions are those that Perl uses in ASCII-safe mode with the "/a"
177       modifier.  Otherwise they could match many more non-ASCII Unicode
178       characters as well.  See "Backslash sequences" in perlrecharclass for
179       details.)
180
181       ·   \d is a digit and represents
182
183               [0-9]
184
185       ·   \s is a whitespace character and represents
186
187               [\ \t\r\n\f]
188
189       ·   \w is a word character (alphanumeric or _) and represents
190
191               [0-9a-zA-Z_]
192
193       ·   \D is a negated \d; it represents any character but a digit
194
195               [^0-9]
196
197       ·   \S is a negated \s; it represents any non-whitespace character
198
199               [^\s]
200
201       ·   \W is a negated \w; it represents any non-word character
202
203               [^\w]
204
205       ·   The period '.' matches any character but "\n"
206
207       The "\d\s\w\D\S\W" abbreviations can be used both inside and outside of
208       character classes.  Here are some in use:
209
210           /\d\d:\d\d:\d\d/; # matches a hh:mm:ss time format
211           /[\d\s]/;         # matches any digit or whitespace character
212           /\w\W\w/;         # matches a word char, followed by a
213                             # non-word char, followed by a word char
214           /..rt/;           # matches any two chars, followed by 'rt'
215           /end\./;          # matches 'end.'
216           /end[.]/;         # same thing, matches 'end.'
217
218       The word anchor  "\b" matches a boundary between a word character and a
219       non-word character "\w\W" or "\W\w":
220
221           $x = "Housecat catenates house and cat";
222           $x =~ /\bcat/;  # matches cat in 'catenates'
223           $x =~ /cat\b/;  # matches cat in 'housecat'
224           $x =~ /\bcat\b/;  # matches 'cat' at end of string
225
226       In the last example, the end of the string is considered a word
227       boundary.
228
229       For natural language processing (so that, for example, apostrophes are
230       included in words), use instead "\b{wb}"
231
232           "don't" =~ / .+? \b{wb} /x;  # matches the whole string
233
234   Matching this or that
235       We can match different character strings with the alternation
236       metacharacter '|'.  To match "dog" or "cat", we form the regex
237       "dog|cat".  As before, Perl will try to match the regex at the earliest
238       possible point in the string.  At each character position, Perl will
239       first try to match the first alternative, "dog".  If "dog" doesn't
240       match, Perl will then try the next alternative, "cat".  If "cat"
241       doesn't match either, then the match fails and Perl moves to the next
242       position in the string.  Some examples:
243
244           "cats and dogs" =~ /cat|dog|bird/;  # matches "cat"
245           "cats and dogs" =~ /dog|cat|bird/;  # matches "cat"
246
247       Even though "dog" is the first alternative in the second regex, "cat"
248       is able to match earlier in the string.
249
250           "cats"          =~ /c|ca|cat|cats/; # matches "c"
251           "cats"          =~ /cats|cat|ca|c/; # matches "cats"
252
253       At a given character position, the first alternative that allows the
254       regex match to succeed will be the one that matches. Here, all the
255       alternatives match at the first string position, so the first matches.
256
257   Grouping things and hierarchical matching
258       The grouping metacharacters "()" allow a part of a regex to be treated
259       as a single unit.  Parts of a regex are grouped by enclosing them in
260       parentheses.  The regex "house(cat|keeper)" means match "house"
261       followed by either "cat" or "keeper".  Some more examples are
262
263           /(a|b)b/;    # matches 'ab' or 'bb'
264           /(^a|b)c/;   # matches 'ac' at start of string or 'bc' anywhere
265
266           /house(cat|)/;  # matches either 'housecat' or 'house'
267           /house(cat(s|)|)/;  # matches either 'housecats' or 'housecat' or
268                               # 'house'.  Note groups can be nested.
269
270           "20" =~ /(19|20|)\d\d/;  # matches the null alternative '()\d\d',
271                                    # because '20\d\d' can't match
272
273   Extracting matches
274       The grouping metacharacters "()" also allow the extraction of the parts
275       of a string that matched.  For each grouping, the part that matched
276       inside goes into the special variables $1, $2, etc.  They can be used
277       just as ordinary variables:
278
279           # extract hours, minutes, seconds
280           $time =~ /(\d\d):(\d\d):(\d\d)/;  # match hh:mm:ss format
281           $hours = $1;
282           $minutes = $2;
283           $seconds = $3;
284
285       In list context, a match "/regex/" with groupings will return the list
286       of matched values "($1,$2,...)".  So we could rewrite it as
287
288           ($hours, $minutes, $second) = ($time =~ /(\d\d):(\d\d):(\d\d)/);
289
290       If the groupings in a regex are nested, $1 gets the group with the
291       leftmost opening parenthesis, $2 the next opening parenthesis, etc.
292       For example, here is a complex regex and the matching variables
293       indicated below it:
294
295           /(ab(cd|ef)((gi)|j))/;
296            1  2      34
297
298       Associated with the matching variables $1, $2, ... are the
299       backreferences "\g1", "\g2", ...  Backreferences are matching variables
300       that can be used inside a regex:
301
302           /(\w\w\w)\s\g1/; # find sequences like 'the the' in string
303
304       $1, $2, ... should only be used outside of a regex, and "\g1", "\g2",
305       ... only inside a regex.
306
307   Matching repetitions
308       The quantifier metacharacters "?", "*", "+", and "{}" allow us to
309       determine the number of repeats of a portion of a regex we consider to
310       be a match.  Quantifiers are put immediately after the character,
311       character class, or grouping that we want to specify.  They have the
312       following meanings:
313
314       ·   "a?" = match 'a' 1 or 0 times
315
316       ·   "a*" = match 'a' 0 or more times, i.e., any number of times
317
318       ·   "a+" = match 'a' 1 or more times, i.e., at least once
319
320       ·   "a{n,m}" = match at least "n" times, but not more than "m" times.
321
322       ·   "a{n,}" = match at least "n" or more times
323
324       ·   "a{n}" = match exactly "n" times
325
326       Here are some examples:
327
328           /[a-z]+\s+\d*/;  # match a lowercase word, at least some space, and
329                            # any number of digits
330           /(\w+)\s+\g1/;    # match doubled words of arbitrary length
331           $year =~ /^\d{2,4}$/;  # make sure year is at least 2 but not more
332                                  # than 4 digits
333           $year =~ /^\d{4}$|^\d{2}$/; # better match; throw out 3 digit dates
334
335       These quantifiers will try to match as much of the string as possible,
336       while still allowing the regex to match.  So we have
337
338           $x = 'the cat in the hat';
339           $x =~ /^(.*)(at)(.*)$/; # matches,
340                                   # $1 = 'the cat in the h'
341                                   # $2 = 'at'
342                                   # $3 = ''   (0 matches)
343
344       The first quantifier ".*" grabs as much of the string as possible while
345       still having the regex match. The second quantifier ".*" has no string
346       left to it, so it matches 0 times.
347
348   More matching
349       There are a few more things you might want to know about matching
350       operators.  The global modifier "/g" allows the matching operator to
351       match within a string as many times as possible.  In scalar context,
352       successive matches against a string will have "/g" jump from match to
353       match, keeping track of position in the string as it goes along.  You
354       can get or set the position with the "pos()" function.  For example,
355
356           $x = "cat dog house"; # 3 words
357           while ($x =~ /(\w+)/g) {
358               print "Word is $1, ends at position ", pos $x, "\n";
359           }
360
361       prints
362
363           Word is cat, ends at position 3
364           Word is dog, ends at position 7
365           Word is house, ends at position 13
366
367       A failed match or changing the target string resets the position.  If
368       you don't want the position reset after failure to match, add the "/c",
369       as in "/regex/gc".
370
371       In list context, "/g" returns a list of matched groupings, or if there
372       are no groupings, a list of matches to the whole regex.  So
373
374           @words = ($x =~ /(\w+)/g);  # matches,
375                                       # $word[0] = 'cat'
376                                       # $word[1] = 'dog'
377                                       # $word[2] = 'house'
378
379   Search and replace
380       Search and replace is performed using "s/regex/replacement/modifiers".
381       The "replacement" is a Perl double-quoted string that replaces in the
382       string whatever is matched with the "regex".  The operator "=~" is also
383       used here to associate a string with "s///".  If matching against $_,
384       the "$_ =~" can be dropped.  If there is a match, "s///" returns the
385       number of substitutions made; otherwise it returns false.  Here are a
386       few examples:
387
388           $x = "Time to feed the cat!";
389           $x =~ s/cat/hacker/;   # $x contains "Time to feed the hacker!"
390           $y = "'quoted words'";
391           $y =~ s/^'(.*)'$/$1/;  # strip single quotes,
392                                  # $y contains "quoted words"
393
394       With the "s///" operator, the matched variables $1, $2, etc.  are
395       immediately available for use in the replacement expression. With the
396       global modifier, "s///g" will search and replace all occurrences of the
397       regex in the string:
398
399           $x = "I batted 4 for 4";
400           $x =~ s/4/four/;   # $x contains "I batted four for 4"
401           $x = "I batted 4 for 4";
402           $x =~ s/4/four/g;  # $x contains "I batted four for four"
403
404       The non-destructive modifier "s///r" causes the result of the
405       substitution to be returned instead of modifying $_ (or whatever
406       variable the substitute was bound to with "=~"):
407
408           $x = "I like dogs.";
409           $y = $x =~ s/dogs/cats/r;
410           print "$x $y\n"; # prints "I like dogs. I like cats."
411
412           $x = "Cats are great.";
413           print $x =~ s/Cats/Dogs/r =~ s/Dogs/Frogs/r =~
414               s/Frogs/Hedgehogs/r, "\n";
415           # prints "Hedgehogs are great."
416
417           @foo = map { s/[a-z]/X/r } qw(a b c 1 2 3);
418           # @foo is now qw(X X X 1 2 3)
419
420       The evaluation modifier "s///e" wraps an "eval{...}" around the
421       replacement string and the evaluated result is substituted for the
422       matched substring.  Some examples:
423
424           # reverse all the words in a string
425           $x = "the cat in the hat";
426           $x =~ s/(\w+)/reverse $1/ge;   # $x contains "eht tac ni eht tah"
427
428           # convert percentage to decimal
429           $x = "A 39% hit rate";
430           $x =~ s!(\d+)%!$1/100!e;       # $x contains "A 0.39 hit rate"
431
432       The last example shows that "s///" can use other delimiters, such as
433       "s!!!" and "s{}{}", and even "s{}//".  If single quotes are used
434       "s'''", then the regex and replacement are treated as single-quoted
435       strings.
436
437   The split operator
438       "split /regex/, string" splits "string" into a list of substrings and
439       returns that list.  The regex determines the character sequence that
440       "string" is split with respect to.  For example, to split a string into
441       words, use
442
443           $x = "Calvin and Hobbes";
444           @word = split /\s+/, $x;  # $word[0] = 'Calvin'
445                                     # $word[1] = 'and'
446                                     # $word[2] = 'Hobbes'
447
448       To extract a comma-delimited list of numbers, use
449
450           $x = "1.618,2.718,   3.142";
451           @const = split /,\s*/, $x;  # $const[0] = '1.618'
452                                       # $const[1] = '2.718'
453                                       # $const[2] = '3.142'
454
455       If the empty regex "//" is used, the string is split into individual
456       characters.  If the regex has groupings, then the list produced
457       contains the matched substrings from the groupings as well:
458
459           $x = "/usr/bin";
460           @parts = split m!(/)!, $x;  # $parts[0] = ''
461                                       # $parts[1] = '/'
462                                       # $parts[2] = 'usr'
463                                       # $parts[3] = '/'
464                                       # $parts[4] = 'bin'
465
466       Since the first character of $x matched the regex, "split" prepended an
467       empty initial element to the list.
468
469   "use re 'strict'"
470       New in v5.22, this applies stricter rules than otherwise when compiling
471       regular expression patterns.  It can find things that, while legal, may
472       not be what you intended.
473
474       See 'strict' in re.
475

BUGS

477       None.
478

SEE ALSO

480       This is just a quick start guide.  For a more in-depth tutorial on
481       regexes, see perlretut and for the reference page, see perlre.
482
484       Copyright (c) 2000 Mark Kvale All rights reserved.
485
486       This document may be distributed under the same terms as Perl itself.
487
488   Acknowledgments
489       The author would like to thank Mark-Jason Dominus, Tom Christiansen,
490       Ilya Zakharevich, Brad Hughes, and Mike Giroux for all their helpful
491       comments.
492
493
494
495perl v5.32.1                      2021-03-31                    PERLREQUICK(1)
Impressum