pod/perlretut.pod

   1 =head1 NAME
   2
   3 perlretut - Perl regular expressions tutorial
   4
   5 =head1 DESCRIPTION
   6
   7 This page provides a basic tutorial on understanding, creating and
   8 using regular expressions in Perl.  It serves as a complement to the
   9 reference page on regular expressions L<perlre>.  Regular expressions
  10 are an integral part of the C<m//>, C<s///>, C<qr//> and C<split>
  11 operators and so this tutorial also overlaps with
  12 L<perlop/"Regexp Quote-Like Operators"> and L<perlfunc/split>.
  13
  14 Perl is widely renowned for excellence in text processing, and regular
  15 expressions are one of the big factors behind this fame.  Perl regular
  16 expressions display an efficiency and flexibility unknown in most
  17 other computer languages.  Mastering even the basics of regular
  18 expressions will allow you to manipulate text with surprising ease.
  19
  20 What is a regular expression?  A regular expression is simply a string
  21 that describes a pattern.  Patterns are in common use these days;
  22 examples are the patterns typed into a search engine to find web pages
  23 and the patterns used to list files in a directory, e.g., C<ls *.txt>
  24 or C<dir *.*>.  In Perl, the patterns described by regular expressions
  25 are used to search strings, extract desired parts of strings, and to
  26 do search and replace operations.
  27
  28 Regular expressions have the undeserved reputation of being abstract
  29 and difficult to understand.  Regular expressions are constructed using
  30 simple concepts like conditionals and loops and are no more difficult
  31 to understand than the corresponding C<if> conditionals and C<while>
  32 loops in the Perl language itself.  In fact, the main challenge in
  33 learning regular expressions is just getting used to the terse
  34 notation used to express these concepts.
  35
  36 This tutorial flattens the learning curve by discussing regular
  37 expression concepts, along with their notation, one at a time and with
  38 many examples.  The first part of the tutorial will progress from the
  39 simplest word searches to the basic regular expression concepts.  If
  40 you master the first part, you will have all the tools needed to solve
  41 about 98% of your needs.  The second part of the tutorial is for those
  42 comfortable with the basics and hungry for more power tools.  It
  43 discusses the more advanced regular expression operators and
  44 introduces the latest cutting edge innovations in 5.6.0.
  45
  46 A note: to save time, 'regular expression' is often abbreviated as
  47 regexp or regex.  Regexp is a more natural abbreviation than regex, but
  48 is harder to pronounce.  The Perl pod documentation is evenly split on
  49 regexp vs regex; in Perl, there is more than one way to abbreviate it.
  50 We'll use regexp in this tutorial.
  51
  52 =head1 Part 1: The basics
  53
  54 =head2 Simple word matching
  55
  56 The simplest regexp is simply a word, or more generally, a string of
  57 characters.  A regexp consisting of a word matches any string that
  58 contains that word:
  59
  60     "Hello World" =~ /World/;  # matches
  61
  62 What is this perl statement all about? C<"Hello World"> is a simple
  63 double quoted string.  C<World> is the regular expression and the
  64 C<//> enclosing C</World/> tells perl to search a string for a match.
  65 The operator C<=~> associates the string with the regexp match and
  66 produces a true value if the regexp matched, or false if the regexp
  67 did not match.  In our case, C<World> matches the second word in
  68 C<"Hello World">, so the expression is true.  Expressions like this
  69 are useful in conditionals:
  70
  71     if ("Hello World" =~ /World/) {
  72         print "It matches\n";
  73     }
  74     else {
  75         print "It doesn't match\n";
  76     }
  77
  78 There are useful variations on this theme.  The sense of the match can
  79 be reversed by using C<!~> operator:
  80
  81     if ("Hello World" !~ /World/) {
  82         print "It doesn't match\n";
  83     }
  84     else {
  85         print "It matches\n";
  86     }
  87
  88 The literal string in the regexp can be replaced by a variable:
  89
  90     $greeting = "World";
  91     if ("Hello World" =~ /$greeting/) {
  92         print "It matches\n";
  93     }
  94     else {
  95         print "It doesn't match\n";
  96     }
  97
  98 If you're matching against the special default variable C<$_>, the
  99 C<$_ =~> part can be omitted:
 100
 101     $_ = "Hello World";
 102     if (/World/) {
 103         print "It matches\n";
 104     }
 105     else {
 106         print "It doesn't match\n";
 107     }
 108
 109 And finally, the C<//> default delimiters for a match can be changed
 110 to arbitrary delimiters by putting an C<'m'> out front:
 111
 112     "Hello World" =~ m!World!;   # matches, delimited by '!'
 113     "Hello World" =~ m{World};   # matches, note the matching '{}'
 114     "/usr/bin/perl" =~ m"/perl"; # matches after '/usr/bin',
 115                                  # '/' becomes an ordinary char
 116
 117 C</World/>, C<m!World!>, and C<m{World}> all represent the
 118 same thing.  When, e.g., C<""> is used as a delimiter, the forward
 119 slash C<'/'> becomes an ordinary character and can be used in a regexp
 120 without trouble.
 121
 122 Let's consider how different regexps would match C<"Hello World">:
 123
 124     "Hello World" =~ /world/;  # doesn't match
 125     "Hello World" =~ /o W/;    # matches
 126     "Hello World" =~ /oW/;     # doesn't match
 127     "Hello World" =~ /World /; # doesn't match
 128
 129 The first regexp C<world> doesn't match because regexps are
 130 case-sensitive.  The second regexp matches because the substring
 131 S<C<'o W'> > occurs in the string S<C<"Hello World"> >.  The space
 132 character ' ' is treated like any other character in a regexp and is
 133 needed to match in this case.  The lack of a space character is the
 134 reason the third regexp C<'oW'> doesn't match.  The fourth regexp
 135 C<'World '> doesn't match because there is a space at the end of the
 136 regexp, but not at the end of the string.  The lesson here is that
 137 regexps must match a part of the string I<exactly> in order for the
 138 statement to be true.
 139
 140 If a regexp matches in more than one place in the string, perl will
 141 always match at the earliest possible point in the string:
 142
 143     "Hello World" =~ /o/;       # matches 'o' in 'Hello'
 144     "That hat is red" =~ /hat/; # matches 'hat' in 'That'
 145
 146 With respect to character matching, there are a few more points you
 147 need to know about.   First of all, not all characters can be used 'as
 148 is' in a match.  Some characters, called B<metacharacters>, are reserved
 149 for use in regexp notation.  The metacharacters are
 150
 151     {}[]()^$.|*+?\
 152
 153 The significance of each of these will be explained
 154 in the rest of the tutorial, but for now, it is important only to know
 155 that a metacharacter can be matched by putting a backslash before it:
 156
 157     "2+2=4" =~ /2+2/;    # doesn't match, + is a metacharacter
 158     "2+2=4" =~ /2\+2/;   # matches, \+ is treated like an ordinary +
 159     "The interval is [0,1)." =~ /[0,1)./     # is a syntax error!
 160     "The interval is [0,1)." =~ /\[0,1\)\./  # matches
 161     "/usr/bin/perl" =~ /\/usr\/local\/bin\/perl/;  # matches
 162
 163 In the last regexp, the forward slash C<'/'> is also backslashed,
 164 because it is used to delimit the regexp.  This can lead to LTS
 165 (leaning toothpick syndrome), however, and it is often more readable
 166 to change delimiters.
 167
 168
 169 The backslash character C<'\'> is a metacharacter itself and needs to
 170 be backslashed:
 171
 172     'C:\WIN32' =~ /C:\\WIN/;   # matches
 173
 174 In addition to the metacharacters, there are some ASCII characters
 175 which don't have printable character equivalents and are instead
 176 represented by B<escape sequences>.  Common examples are C<\t> for a
 177 tab, C<\n> for a newline, C<\r> for a carriage return and C<\a> for a
 178 bell.  If your string is better thought of as a sequence of arbitrary
 179 bytes, the octal escape sequence, e.g., C<\033>, or hexadecimal escape
 180 sequence, e.g., C<\x1B> may be a more natural representation for your
 181 bytes.  Here are some examples of escapes:
 182
 183     "1000\t2000" =~ m(0\t2)   # matches
 184     "1000\n2000" =~ /0\n20/   # matches
 185     "1000\t2000" =~ /\000\t2/ # doesn't match, "0" ne "\000"
 186     "cat"        =~ /\143\x61\x74/ # matches, but a weird way to spell cat
 187
 188 If you've been around Perl a while, all this talk of escape sequences
 189 may seem familiar.  Similar escape sequences are used in double-quoted
 190 strings and in fact the regexps in Perl are mostly treated as
 191 double-quoted strings.  This means that variables can be used in
 192 regexps as well.  Just like double-quoted strings, the values of the
 193 variables in the regexp will be substituted in before the regexp is
 194 evaluated for matching purposes.  So we have:
 195
 196     $foo = 'house';
 197     'housecat' =~ /$foo/;      # matches
 198     'cathouse' =~ /cat$foo/;   # matches
 199     'housecat' =~ /${foo}cat/; # matches
 200
 201 So far, so good.  With the knowledge above you can already perform
 202 searches with just about any literal string regexp you can dream up.
 203 Here is a I<very simple> emulation of the Unix grep program:
 204
 205     % cat > simple_grep
 206     #!/usr/bin/perl
 207     $regexp = shift;
 208     while (<>) {
 209         print if /$regexp/;
 210     }
 211     ^D
 212
 213     % chmod +x simple_grep
 214
 215     % simple_grep abba /usr/dict/words
 216     Babbage
 217     cabbage
 218     cabbages
 219     sabbath
 220     Sabbathize
 221     Sabbathizes
 222     sabbatical
 223     scabbard
 224     scabbards
 225
 226 This program is easy to understand.  C<#!/usr/bin/perl> is the standard
 227 way to invoke a perl program from the shell.
 228 S<C<$regexp = shift;> > saves the first command line argument as the
 229 regexp to be used, leaving the rest of the command line arguments to
 230 be treated as files.  S<C<< while (<>) >> > loops over all the lines in
 231 all the files.  For each line, S<C<print if /$regexp/;> > prints the
 232 line if the regexp matches the line.  In this line, both C<print> and
 233 C</$regexp/> use the default variable C<$_> implicitly.
 234
 235 With all of the regexps above, if the regexp matched anywhere in the
 236 string, it was considered a match.  Sometimes, however, we'd like to
 237 specify I<where> in the string the regexp should try to match.  To do
 238 this, we would use the B<anchor> metacharacters C<^> and C<$>.  The
 239 anchor C<^> means match at the beginning of the string and the anchor
 240 C<$> means match at the end of the string, or before a newline at the
 241 end of the string.  Here is how they are used:
 242
 243     "housekeeper" =~ /keeper/;    # matches
 244     "housekeeper" =~ /^keeper/;   # doesn't match
 245     "housekeeper" =~ /keeper$/;   # matches
 246     "housekeeper\n" =~ /keeper$/; # matches
 247
 248 The second regexp doesn't match because C<^> constrains C<keeper> to
 249 match only at the beginning of the string, but C<"housekeeper"> has
 250 keeper starting in the middle.  The third regexp does match, since the
 251 C<$> constrains C<keeper> to match only at the end of the string.
 252
 253 When both C<^> and C<$> are used at the same time, the regexp has to
 254 match both the beginning and the end of the string, i.e., the regexp
 255 matches the whole string.  Consider
 256
 257     "keeper" =~ /^keep$/;      # doesn't match
 258     "keeper" =~ /^keeper$/;    # matches
 259     ""       =~ /^$/;          # ^$ matches an empty string
 260
 261 The first regexp doesn't match because the string has more to it than
 262 C<keep>.  Since the second regexp is exactly the string, it
 263 matches.  Using both C<^> and C<$> in a regexp forces the complete
 264 string to match, so it gives you complete control over which strings
 265 match and which don't.  Suppose you are looking for a fellow named
 266 bert, off in a string by himself:
 267
 268     "dogbert" =~ /bert/;   # matches, but not what you want
 269
 270     "dilbert" =~ /^bert/;  # doesn't match, but ..
 271     "bertram" =~ /^bert/;  # matches, so still not good enough
 272
 273     "bertram" =~ /^bert$/; # doesn't match, good
 274     "dilbert" =~ /^bert$/; # doesn't match, good
 275     "bert"    =~ /^bert$/; # matches, perfect
 276
 277 Of course, in the case of a literal string, one could just as easily
 278 use the string equivalence S<C<$string eq 'bert'> > and it would be
 279 more efficient.   The  C<^...$> regexp really becomes useful when we
 280 add in the more powerful regexp tools below.
 281
 282 =head2 Using character classes
 283
 284 Although one can already do quite a lot with the literal string
 285 regexps above, we've only scratched the surface of regular expression
 286 technology.  In this and subsequent sections we will introduce regexp
 287 concepts (and associated metacharacter notations) that will allow a
 288 regexp to not just represent a single character sequence, but a I<whole
 289 class> of them.
 290
 291 One such concept is that of a B<character class>.  A character class
 292 allows a set of possible characters, rather than just a single
 293 character, to match at a particular point in a regexp.  Character
 294 classes are denoted by brackets C<[...]>, with the set of characters
 295 to be possibly matched inside.  Here are some examples:
 296
 297     /cat/;       # matches 'cat'
 298     /[bcr]at/;   # matches 'bat, 'cat', or 'rat'
 299     /item[0123456789]/;  # matches 'item0' or ... or 'item9'
 300     "abc" =~ /[cab]/;    # matches 'a'
 301
 302 In the last statement, even though C<'c'> is the first character in
 303 the class, C<'a'> matches because the first character position in the
 304 string is the earliest point at which the regexp can match.
 305
 306     /[yY][eE][sS]/;      # match 'yes' in a case-insensitive way
 307                          # 'yes', 'Yes', 'YES', etc.
 308
 309 This regexp displays a common task: perform a case-insensitive
 310 match.  Perl provides away of avoiding all those brackets by simply
 311 appending an C<'i'> to the end of the match.  Then C</[yY][eE][sS]/;>
 312 can be rewritten as C</yes/i;>.  The C<'i'> stands for
 313 case-insensitive and is an example of a B<modifier> of the matching
 314 operation.  We will meet other modifiers later in the tutorial.
 315
 316 We saw in the section above that there were ordinary characters, which
 317 represented themselves, and special characters, which needed a
 318 backslash C<\> to represent themselves.  The same is true in a
 319 character class, but the sets of ordinary and special characters
 320 inside a character class are different than those outside a character
 321 class.  The special characters for a character class are C<-]\^$>.  C<]>
 322 is special because it denotes the end of a character class.  C<$> is
 323 special because it denotes a scalar variable.  C<\> is special because
 324 it is used in escape sequences, just like above.  Here is how the
 325 special characters C<]$\> are handled:
 326
 327    /[\]c]def/; # matches ']def' or 'cdef'
 328    $x = 'bcr';
 329    /[$x]at/;   # matches 'bat', 'cat', or 'rat'
 330    /[\$x]at/;  # matches '$at' or 'xat'
 331    /[\\$x]at/; # matches '\at', 'bat, 'cat', or 'rat'
 332
 333 The last two are a little tricky.  in C<[\$x]>, the backslash protects
 334 the dollar sign, so the character class has two members C<$> and C<x>.
 335 In C<[\\$x]>, the backslash is protected, so C<$x> is treated as a
 336 variable and substituted in double quote fashion.
 337
 338 The special character C<'-'> acts as a range operator within character
 339 classes, so that a contiguous set of characters can be written as a
 340 range.  With ranges, the unwieldy C<[0123456789]> and C<[abc...xyz]>
 341 become the svelte C<[0-9]> and C<[a-z]>.  Some examples are
 342
 343     /item[0-9]/;  # matches 'item0' or ... or 'item9'
 344     /[0-9bx-z]aa/;  # matches '0aa', ..., '9aa',
 345                     # 'baa', 'xaa', 'yaa', or 'zaa'
 346     /[0-9a-fA-F]/;  # matches a hexadecimal digit
 347     /[0-9a-zA-Z_]/; # matches a "word" character,
 348                     # like those in a perl variable name
 349
 350 If C<'-'> is the first or last character in a character class, it is
 351 treated as an ordinary character; C<[-ab]>, C<[ab-]> and C<[a\-b]> are
 352 all equivalent.
 353
 354 The special character C<^> in the first position of a character class
 355 denotes a B<negated character class>, which matches any character but
 356 those in the brackets.  Both C<[...]> and C<[^...]> must match a
 357 character, or the match fails.  Then
 358
 359     /[^a]at/;  # doesn't match 'aat' or 'at', but matches
 360                # all other 'bat', 'cat, '0at', '%at', etc.
 361     /[^0-9]/;  # matches a non-numeric character
 362     /[a^]at/;  # matches 'aat' or '^at'; here '^' is ordinary
 363
 364 Now, even C<[0-9]> can be a bother the write multiple times, so in the
 365 interest of saving keystrokes and making regexps more readable, Perl
 366 has several abbreviations for common character classes:
 367
 368 =over 4
 369
 370 =item *
 371
 372 \d is a digit and represents [0-9]
 373
 374 =item *
 375
 376 \s is a whitespace character and represents [\ \t\r\n\f]
 377
 378 =item *
 379
 380 \w is a word character (alphanumeric or _) and represents [0-9a-zA-Z_]
 381
 382 =item *
 383
 384 \D is a negated \d; it represents any character but a digit [^0-9]
 385
 386 =item *
 387
 388 \S is a negated \s; it represents any non-whitespace character [^\s]
 389
 390 =item *
 391
 392 \W is a negated \w; it represents any non-word character [^\w]
 393
 394 =item *
 395
 396 The period '.' matches any character but "\n"
 397
 398 =back
 399
 400 The C<\d\s\w\D\S\W> abbreviations can be used both inside and outside
 401 of character classes.  Here are some in use:
 402
 403     /\d\d:\d\d:\d\d/; # matches a hh:mm:ss time format
 404     /[\d\s]/;         # matches any digit or whitespace character
 405     /\w\W\w/;         # matches a word char, followed by a
 406                       # non-word char, followed by a word char
 407     /..rt/;           # matches any two chars, followed by 'rt'
 408     /end\./;          # matches 'end.'
 409     /end[.]/;         # same thing, matches 'end.'
 410
 411 Because a period is a metacharacter, it needs to be escaped to match
 412 as an ordinary period. Because, for example, C<\d> and C<\w> are sets
 413 of characters, it is incorrect to think of C<[^\d\w]> as C<[\D\W]>; in
 414 fact C<[^\d\w]> is the same as C<[^\w]>, which is the same as
 415 C<[\W]>. Think DeMorgan's laws.
 416
 417 An anchor useful in basic regexps is the S<B<word anchor> >
 418 C<\b>.  This matches a boundary between a word character and a non-word
 419 character C<\w\W> or C<\W\w>:
 420
 421     $x = "Housecat catenates house and cat";
 422     $x =~ /cat/;    # matches cat in 'housecat'
 423     $x =~ /\bcat/;  # matches cat in 'catenates'
 424     $x =~ /cat\b/;  # matches cat in 'housecat'
 425     $x =~ /\bcat\b/;  # matches 'cat' at end of string
 426
 427 Note in the last example, the end of the string is considered a word
 428 boundary.
 429
 430 You might wonder why C<'.'> matches everything but C<"\n"> - why not
 431 every character? The reason is that often one is matching against
 432 lines and would like to ignore the newline characters.  For instance,
 433 while the string C<"\n"> represents one line, we would like to think
 434 of as empty.  Then
 435
 436     ""   =~ /^$/;    # matches
 437     "\n" =~ /^$/;    # matches, "\n" is ignored
 438
 439     ""   =~ /./;      # doesn't match; it needs a char
 440     ""   =~ /^.$/;    # doesn't match; it needs a char
 441     "\n" =~ /^.$/;    # doesn't match; it needs a char other than "\n"
 442     "a"  =~ /^.$/;    # matches
 443     "a\n"  =~ /^.$/;  # matches, ignores the "\n"
 444
 445 This behavior is convenient, because we usually want to ignore
 446 newlines when we count and match characters in a line.  Sometimes,
 447 however, we want to keep track of newlines.  We might even want C<^>
 448 and C<$> to anchor at the beginning and end of lines within the
 449 string, rather than just the beginning and end of the string.  Perl
 450 allows us to choose between ignoring and paying attention to newlines
 451 by using the C<//s> and C<//m> modifiers.  C<//s> and C<//m> stand for
 452 single line and multi-line and they determine whether a string is to
 453 be treated as one continuous string, or as a set of lines.  The two
 454 modifiers affect two aspects of how the regexp is interpreted: 1) how
 455 the C<'.'> character class is defined, and 2) where the anchors C<^>
 456 and C<$> are able to match.  Here are the four possible combinations:
 457
 458 =over 4
 459
 460 =item *
 461
 462 no modifiers (//): Default behavior.  C<'.'> matches any character
 463 except C<"\n">.  C<^> matches only at the beginning of the string and
 464 C<$> matches only at the end or before a newline at the end.
 465
 466 =item *
 467
 468 s modifier (//s): Treat string as a single long line.  C<'.'> matches
 469 any character, even C<"\n">.  C<^> matches only at the beginning of
 470 the string and C<$> matches only at the end or before a newline at the
 471 end.
 472
 473 =item *
 474
 475 m modifier (//m): Treat string as a set of multiple lines.  C<'.'>
 476 matches any character except C<"\n">.  C<^> and C<$> are able to match
 477 at the start or end of I<any> line within the string.
 478
 479 =item *
 480
 481 both s and m modifiers (//sm): Treat string as a single long line, but
 482 detect multiple lines.  C<'.'> matches any character, even
 483 C<"\n">.  C<^> and C<$>, however, are able to match at the start or end
 484 of I<any> line within the string.
 485
 486 =back
 487
 488 Here are examples of C<//s> and C<//m> in action:
 489
 490     $x = "There once was a girl\nWho programmed in Perl\n";
 491
 492     $x =~ /^Who/;   # doesn't match, "Who" not at start of string
 493     $x =~ /^Who/s;  # doesn't match, "Who" not at start of string
 494     $x =~ /^Who/m;  # matches, "Who" at start of second line
 495     $x =~ /^Who/sm; # matches, "Who" at start of second line
 496
 497     $x =~ /girl.Who/;   # doesn't match, "." doesn't match "\n"
 498     $x =~ /girl.Who/s;  # matches, "." matches "\n"
 499     $x =~ /girl.Who/m;  # doesn't match, "." doesn't match "\n"
 500     $x =~ /girl.Who/sm; # matches, "." matches "\n"
 501
 502 Most of the time, the default behavior is what is want, but C<//s> and
 503 C<//m> are occasionally very useful.  If C<//m> is being used, the start
 504 of the string can still be matched with C<\A> and the end of string
 505 can still be matched with the anchors C<\Z> (matches both the end and
 506 the newline before, like C<$>), and C<\z> (matches only the end):
 507
 508     $x =~ /^Who/m;   # matches, "Who" at start of second line
 509     $x =~ /\AWho/m;  # doesn't match, "Who" is not at start of string
 510
 511     $x =~ /girl$/m;  # matches, "girl" at end of first line
 512     $x =~ /girl\Z/m; # doesn't match, "girl" is not at end of string
 513
 514     $x =~ /Perl\Z/m; # matches, "Perl" is at newline before end
 515     $x =~ /Perl\z/m; # doesn't match, "Perl" is not at end of string
 516
 517 We now know how to create choices among classes of characters in a
 518 regexp.  What about choices among words or character strings? Such
 519 choices are described in the next section.
 520
 521 =head2 Matching this or that
 522
 523 Sometimes we would like to our regexp to be able to match different
 524 possible words or character strings.  This is accomplished by using
 525 the B<alternation> metacharacter C<|>.  To match C<dog> or C<cat>, we
 526 form the regexp C<dog|cat>.  As before, perl will try to match the
 527 regexp at the earliest possible point in the string.  At each
 528 character position, perl will first try to match the first
 529 alternative, C<dog>.  If C<dog> doesn't match, perl will then try the
 530 next alternative, C<cat>.  If C<cat> doesn't match either, then the
 531 match fails and perl moves to the next position in the string.  Some
 532 examples:
 533
 534     "cats and dogs" =~ /cat|dog|bird/;  # matches "cat"
 535     "cats and dogs" =~ /dog|cat|bird/;  # matches "cat"
 536
 537 Even though C<dog> is the first alternative in the second regexp,
 538 C<cat> is able to match earlier in the string.
 539
 540     "cats"          =~ /c|ca|cat|cats/; # matches "c"
 541     "cats"          =~ /cats|cat|ca|c/; # matches "cats"
 542
 543 Here, all the alternatives match at the first string position, so the
 544 first alternative is the one that matches.  If some of the
 545 alternatives are truncations of the others, put the longest ones first
 546 to give them a chance to match.
 547
 548     "cab" =~ /a|b|c/ # matches "c"
 549                      # /a|b|c/ == /[abc]/
 550
 551 The last example points out that character classes are like
 552 alternations of characters.  At a given character position, the first
 553 alternative that allows the regexp match to succeed will be the one
 554 that matches.
 555
 556 =head2 Grouping things and hierarchical matching
 557
 558 Alternation allows a regexp to choose among alternatives, but by
 559 itself it unsatisfying.  The reason is that each alternative is a whole
 560 regexp, but sometime we want alternatives for just part of a
 561 regexp.  For instance, suppose we want to search for housecats or
 562 housekeepers.  The regexp C<housecat|housekeeper> fits the bill, but is
 563 inefficient because we had to type C<house> twice.  It would be nice to
 564 have parts of the regexp be constant, like C<house>, and some
 565 parts have alternatives, like C<cat|keeper>.
 566
 567 The B<grouping> metacharacters C<()> solve this problem.  Grouping
 568 allows parts of a regexp to be treated as a single unit.  Parts of a
 569 regexp are grouped by enclosing them in parentheses.  Thus we could solve
 570 the C<housecat|housekeeper> by forming the regexp as
 571 C<house(cat|keeper)>.  The regexp C<house(cat|keeper)> means match
 572 C<house> followed by either C<cat> or C<keeper>.  Some more examples
 573 are
 574
 575     /(a|b)b/;    # matches 'ab' or 'bb'
 576     /(ac|b)b/;   # matches 'acb' or 'bb'
 577     /(^a|b)c/;   # matches 'ac' at start of string or 'bc' anywhere
 578     /(a|[bc])d/; # matches 'ad', 'bd', or 'cd'
 579
 580     /house(cat|)/;  # matches either 'housecat' or 'house'
 581     /house(cat(s|)|)/;  # matches either 'housecats' or 'housecat' or
 582                         # 'house'.  Note groups can be nested.
 583
 584     /(19|20|)\d\d/;  # match years 19xx, 20xx, or the Y2K problem, xx
 585     "20" =~ /(19|20|)\d\d/;  # matches the null alternative '()\d\d',
 586                              # because '20\d\d' can't match
 587
 588 Alternations behave the same way in groups as out of them: at a given
 589 string position, the leftmost alternative that allows the regexp to
 590 match is taken.  So in the last example at the first string position,
 591 C<"20"> matches the second alternative, but there is nothing left over
 592 to match the next two digits C<\d\d>.  So perl moves on to the next
 593 alternative, which is the null alternative and that works, since
 594 C<"20"> is two digits.
 595
 596 The process of trying one alternative, seeing if it matches, and
 597 moving on to the next alternative if it doesn't, is called
 598 B<backtracking>.  The term 'backtracking' comes from the idea that
 599 matching a regexp is like a walk in the woods.  Successfully matching
 600 a regexp is like arriving at a destination.  There are many possible
 601 trailheads, one for each string position, and each one is tried in
 602 order, left to right.  From each trailhead there may be many paths,
 603 some of which get you there, and some which are dead ends.  When you
 604 walk along a trail and hit a dead end, you have to backtrack along the
 605 trail to an earlier point to try another trail.  If you hit your
 606 destination, you stop immediately and forget about trying all the
 607 other trails.  You are persistent, and only if you have tried all the
 608 trails from all the trailheads and not arrived at your destination, do
 609 you declare failure.  To be concrete, here is a step-by-step analysis
 610 of what perl does when it tries to match the regexp
 611
 612     "abcde" =~ /(abd|abc)(df|d|de)/;
 613
 614 =over 4
 615
 616 =item 0
 617
 618 Start with the first letter in the string 'a'.
 619
 620 =item 1
 621
 622 Try the first alternative in the first group 'abd'.
 623
 624 =item 2
 625
 626 Match 'a' followed by 'b'. So far so good.
 627
 628 =item 3
 629
 630 'd' in the regexp doesn't match 'c' in the string - a dead
 631 end.  So backtrack two characters and pick the second alternative in
 632 the first group 'abc'.
 633
 634 =item 4
 635
 636 Match 'a' followed by 'b' followed by 'c'.  We are on a roll
 637 and have satisfied the first group. Set $1 to 'abc'.
 638
 639 =item 5
 640
 641 Move on to the second group and pick the first alternative
 642 'df'.
 643
 644 =item 6
 645
 646 Match the 'd'.
 647
 648 =item 7
 649
 650 'f' in the regexp doesn't match 'e' in the string, so a dead
 651 end.  Backtrack one character and pick the second alternative in the
 652 second group 'd'.
 653
 654 =item 8
 655
 656 'd' matches. The second grouping is satisfied, so set $2 to
 657 'd'.
 658
 659 =item 9
 660
 661 We are at the end of the regexp, so we are done! We have
 662 matched 'abcd' out of the string "abcde".
 663
 664 =back
 665
 666 There are a couple of things to note about this analysis.  First, the
 667 third alternative in the second group 'de' also allows a match, but we
 668 stopped before we got to it - at a given character position, leftmost
 669 wins.  Second, we were able to get a match at the first character
 670 position of the string 'a'.  If there were no matches at the first
 671 position, perl would move to the second character position 'b' and
 672 attempt the match all over again.  Only when all possible paths at all
 673 possible character positions have been exhausted does perl give
 674 up and declare S<C<$string =~ /(abd|abc)(df|d|de)/;> > to be false.
 675
 676 Even with all this work, regexp matching happens remarkably fast.  To
 677 speed things up, during compilation stage, perl compiles the regexp
 678 into a compact sequence of opcodes that can often fit inside a
 679 processor cache.  When the code is executed, these opcodes can then run
 680 at full throttle and search very quickly.
 681
 682 =head2 Extracting matches
 683
 684 The grouping metacharacters C<()> also serve another completely
 685 different function: they allow the extraction of the parts of a string
 686 that matched.  This is very useful to find out what matched and for
 687 text processing in general.  For each grouping, the part that matched
 688 inside goes into the special variables C<$1>, C<$2>, etc.  They can be
 689 used just as ordinary variables:
 690
 691     # extract hours, minutes, seconds
 692     $time =~ /(\d\d):(\d\d):(\d\d)/;  # match hh:mm:ss format
 693     $hours = $1;
 694     $minutes = $2;
 695     $seconds = $3;
 696
 697 Now, we know that in scalar context,
 698 S<C<$time =~ /(\d\d):(\d\d):(\d\d)/> > returns a true or false
 699 value.  In list context, however, it returns the list of matched values
 700 C<($1,$2,$3)>.  So we could write the code more compactly as
 701
 702     # extract hours, minutes, seconds
 703     ($hours, $minutes, $second) = ($time =~ /(\d\d):(\d\d):(\d\d)/);
 704
 705 If the groupings in a regexp are nested, C<$1> gets the group with the
 706 leftmost opening parenthesis, C<$2> the next opening parenthesis,
 707 etc.  For example, here is a complex regexp and the matching variables
 708 indicated below it:
 709
 710     /(ab(cd|ef)((gi)|j))/;
 711      1  2      34
 712
 713 so that if the regexp matched, e.g., C<$2> would contain 'cd' or 'ef'. For
 714 convenience, perl sets C<$+> to the string held by the highest numbered
 715 C<$1>, C<$2>, ... that got assigned (and, somewhat related, C<$^N> to the
 716 value of the C<$1>, C<$2>, ... most-recently assigned; i.e. the C<$1>,
 717 C<$2>, ... associated with the rightmost closing parenthesis used in the
 718 match).
 719
 720 Closely associated with the matching variables C<$1>, C<$2>, ... are
 721 the B<backreferences> C<\1>, C<\2>, ... .  Backreferences are simply
 722 matching variables that can be used I<inside> a regexp.  This is a
 723 really nice feature - what matches later in a regexp can depend on
 724 what matched earlier in the regexp.  Suppose we wanted to look
 725 for doubled words in text, like 'the the'.  The following regexp finds
 726 all 3-letter doubles with a space in between:
 727
 728     /(\w\w\w)\s\1/;
 729
 730 The grouping assigns a value to \1, so that the same 3 letter sequence
 731 is used for both parts.  Here are some words with repeated parts:
 732
 733     % simple_grep '^(\w\w\w\w|\w\w\w|\w\w|\w)\1$' /usr/dict/words
 734     beriberi
 735     booboo
 736     coco
 737     mama
 738     murmur
 739     papa
 740
 741 The regexp has a single grouping which considers 4-letter
 742 combinations, then 3-letter combinations, etc.  and uses C<\1> to look for
 743 a repeat.  Although C<$1> and C<\1> represent the same thing, care should be
 744 taken to use matched variables C<$1>, C<$2>, ... only outside a regexp
 745 and backreferences C<\1>, C<\2>, ... only inside a regexp; not doing
 746 so may lead to surprising and/or undefined results.
 747
 748 In addition to what was matched, Perl 5.6.0 also provides the
 749 positions of what was matched with the C<@-> and C<@+>
 750 arrays. C<$-[0]> is the position of the start of the entire match and
 751 C<$+[0]> is the position of the end. Similarly, C<$-[n]> is the
 752 position of the start of the C<$n> match and C<$+[n]> is the position
 753 of the end. If C<$n> is undefined, so are C<$-[n]> and C<$+[n]>. Then
 754 this code
 755
 756     $x = "Mmm...donut, thought Homer";
 757     $x =~ /^(Mmm|Yech)\.\.\.(donut|peas)/; # matches
 758     foreach $expr (1..$#-) {
 759         print "Match $expr: '${$expr}' at position ($-[$expr],$+[$expr])\n";
 760     }
 761
 762 prints
 763
 764     Match 1: 'Mmm' at position (0,3)
 765     Match 2: 'donut' at position (6,11)
 766
 767 Even if there are no groupings in a regexp, it is still possible to
 768 find out what exactly matched in a string.  If you use them, perl
 769 will set C<$`> to the part of the string before the match, will set C<$&>
 770 to the part of the string that matched, and will set C<$'> to the part
 771 of the string after the match.  An example:
 772
 773     $x = "the cat caught the mouse";
 774     $x =~ /cat/;  # $` = 'the ', $& = 'cat', $' = ' caught the mouse'
 775     $x =~ /the/;  # $` = '', $& = 'the', $' = ' cat caught the mouse'
 776
 777 In the second match, S<C<$` = ''> > because the regexp matched at the
 778 first character position in the string and stopped, it never saw the
 779 second 'the'.  It is important to note that using C<$`> and C<$'>
 780 slows down regexp matching quite a bit, and C< $& > slows it down to a
 781 lesser extent, because if they are used in one regexp in a program,
 782 they are generated for <all> regexps in the program.  So if raw
 783 performance is a goal of your application, they should be avoided.
 784 If you need them, use C<@-> and C<@+> instead:
 785
 786     $` is the same as substr( $x, 0, $-[0] )
 787     $& is the same as substr( $x, $-[0], $+[0]-$-[0] )
 788     $' is the same as substr( $x, $+[0] )
 789
 790 =head2 Matching repetitions
 791
 792 The examples in the previous section display an annoying weakness.  We
 793 were only matching 3-letter words, or syllables of 4 letters or
 794 less.  We'd like to be able to match words or syllables of any length,
 795 without writing out tedious alternatives like
 796 C<\w\w\w\w|\w\w\w|\w\w|\w>.
 797
 798 This is exactly the problem the B<quantifier> metacharacters C<?>,
 799 C<*>, C<+>, and C<{}> were created for.  They allow us to determine the
 800 number of repeats of a portion of a regexp we consider to be a
 801 match.  Quantifiers are put immediately after the character, character
 802 class, or grouping that we want to specify.  They have the following
 803 meanings:
 804
 805 =over 4
 806
 807 =item *
 808
 809 C<a?> = match 'a' 1 or 0 times
 810
 811 =item *
 812
 813 C<a*> = match 'a' 0 or more times, i.e., any number of times
 814
 815 =item *
 816
 817 C<a+> = match 'a' 1 or more times, i.e., at least once
 818
 819 =item *
 820
 821 C<a{n,m}> = match at least C<n> times, but not more than C<m>
 822 times.
 823
 824 =item *
 825
 826 C<a{n,}> = match at least C<n> or more times
 827
 828 =item *
 829
 830 C<a{n}> = match exactly C<n> times
 831
 832 =back
 833
 834 Here are some examples:
 835
 836     /[a-z]+\s+\d*/;  # match a lowercase word, at least some space, and
 837                      # any number of digits
 838     /(\w+)\s+\1/;    # match doubled words of arbitrary length
 839     /y(es)?/i;       # matches 'y', 'Y', or a case-insensitive 'yes'
 840     $year =~ /\d{2,4}/;  # make sure year is at least 2 but not more
 841                          # than 4 digits
 842     $year =~ /\d{4}|\d{2}/;    # better match; throw out 3 digit dates
 843     $year =~ /\d{2}(\d{2})?/;  # same thing written differently. However,
 844                                # this produces $1 and the other does not.
 845
 846     % simple_grep '^(\w+)\1$' /usr/dict/words   # isn't this easier?
 847     beriberi
 848     booboo
 849     coco
 850     mama
 851     murmur
 852     papa
 853
 854 For all of these quantifiers, perl will try to match as much of the
 855 string as possible, while still allowing the regexp to succeed.  Thus
 856 with C</a?.../>, perl will first try to match the regexp with the C<a>
 857 present; if that fails, perl will try to match the regexp without the
 858 C<a> present.  For the quantifier C<*>, we get the following:
 859
 860     $x = "the cat in the hat";
 861     $x =~ /^(.*)(cat)(.*)$/; # matches,
 862                              # $1 = 'the '
 863                              # $2 = 'cat'
 864                              # $3 = ' in the hat'
 865
 866 Which is what we might expect, the match finds the only C<cat> in the
 867 string and locks onto it.  Consider, however, this regexp:
 868
 869     $x =~ /^(.*)(at)(.*)$/; # matches,
 870                             # $1 = 'the cat in the h'
 871                             # $2 = 'at'
 872                             # $3 = ''   (0 matches)
 873
 874 One might initially guess that perl would find the C<at> in C<cat> and
 875 stop there, but that wouldn't give the longest possible string to the
 876 first quantifier C<.*>.  Instead, the first quantifier C<.*> grabs as
 877 much of the string as possible while still having the regexp match.  In
 878 this example, that means having the C<at> sequence with the final C<at>
 879 in the string.  The other important principle illustrated here is that
 880 when there are two or more elements in a regexp, the I<leftmost>
 881 quantifier, if there is one, gets to grab as much the string as
 882 possible, leaving the rest of the regexp to fight over scraps.  Thus in
 883 our example, the first quantifier C<.*> grabs most of the string, while
 884 the second quantifier C<.*> gets the empty string.   Quantifiers that
 885 grab as much of the string as possible are called B<maximal match> or
 886 B<greedy> quantifiers.
 887
 888 When a regexp can match a string in several different ways, we can use
 889 the principles above to predict which way the regexp will match:
 890
 891 =over 4
 892
 893 =item *
 894
 895 Principle 0: Taken as a whole, any regexp will be matched at the
 896 earliest possible position in the string.
 897
 898 =item *
 899
 900 Principle 1: In an alternation C<a|b|c...>, the leftmost alternative
 901 that allows a match for the whole regexp will be the one used.
 902
 903 =item *
 904
 905 Principle 2: The maximal matching quantifiers C<?>, C<*>, C<+> and
 906 C<{n,m}> will in general match as much of the string as possible while
 907 still allowing the whole regexp to match.
 908
 909 =item *
 910
 911 Principle 3: If there are two or more elements in a regexp, the
 912 leftmost greedy quantifier, if any, will match as much of the string
 913 as possible while still allowing the whole regexp to match.  The next
 914 leftmost greedy quantifier, if any, will try to match as much of the
 915 string remaining available to it as possible, while still allowing the
 916 whole regexp to match.  And so on, until all the regexp elements are
 917 satisfied.
 918
 919 =back
 920
 921 As we have seen above, Principle 0 overrides the others - the regexp
 922 will be matched as early as possible, with the other principles
 923 determining how the regexp matches at that earliest character
 924 position.
 925
 926 Here is an example of these principles in action:
 927
 928     $x = "The programming republic of Perl";
 929     $x =~ /^(.+)(e|r)(.*)$/;  # matches,
 930                               # $1 = 'The programming republic of Pe'
 931                               # $2 = 'r'
 932                               # $3 = 'l'
 933
 934 This regexp matches at the earliest string position, C<'T'>.  One
 935 might think that C<e>, being leftmost in the alternation, would be
 936 matched, but C<r> produces the longest string in the first quantifier.
 937
 938     $x =~ /(m{1,2})(.*)$/;  # matches,
 939                             # $1 = 'mm'
 940                             # $2 = 'ing republic of Perl'
 941
 942 Here, The earliest possible match is at the first C<'m'> in
 943 C<programming>. C<m{1,2}> is the first quantifier, so it gets to match
 944 a maximal C<mm>.
 945
 946     $x =~ /.*(m{1,2})(.*)$/;  # matches,
 947                               # $1 = 'm'
 948                               # $2 = 'ing republic of Perl'
 949
 950 Here, the regexp matches at the start of the string. The first
 951 quantifier C<.*> grabs as much as possible, leaving just a single
 952 C<'m'> for the second quantifier C<m{1,2}>.
 953
 954     $x =~ /(.?)(m{1,2})(.*)$/;  # matches,
 955                                 # $1 = 'a'
 956                                 # $2 = 'mm'
 957                                 # $3 = 'ing republic of Perl'
 958
 959 Here, C<.?> eats its maximal one character at the earliest possible
 960 position in the string, C<'a'> in C<programming>, leaving C<m{1,2}>
 961 the opportunity to match both C<m>'s. Finally,
 962
 963     "aXXXb" =~ /(X*)/; # matches with $1 = ''
 964
 965 because it can match zero copies of C<'X'> at the beginning of the
 966 string.  If you definitely want to match at least one C<'X'>, use
 967 C<X+>, not C<X*>.
 968
 969 Sometimes greed is not good.  At times, we would like quantifiers to
 970 match a I<minimal> piece of string, rather than a maximal piece.  For
 971 this purpose, Larry Wall created the S<B<minimal match> > or
 972 B<non-greedy> quantifiers C<??>,C<*?>, C<+?>, and C<{}?>.  These are
 973 the usual quantifiers with a C<?> appended to them.  They have the
 974 following meanings:
 975
 976 =over 4
 977
 978 =item *
 979
 980 C<a??> = match 'a' 0 or 1 times. Try 0 first, then 1.
 981
 982 =item *
 983
 984 C<a*?> = match 'a' 0 or more times, i.e., any number of times,
 985 but as few times as possible
 986
 987 =item *
 988
 989 C<a+?> = match 'a' 1 or more times, i.e., at least once, but
 990 as few times as possible
 991
 992 =item *
 993
 994 C<a{n,m}?> = match at least C<n> times, not more than C<m>
 995 times, as few times as possible
 996
 997 =item *
 998
 999 C<a{n,}?> = match at least C<n> times, but as few times as
1000 possible
1001
1002 =item *
1003
1004 C<a{n}?> = match exactly C<n> times.  Because we match exactly
1005 C<n> times, C<a{n}?> is equivalent to C<a{n}> and is just there for
1006 notational consistency.
1007
1008 =back
1009
1010 Let's look at the example above, but with minimal quantifiers:
1011
1012     $x = "The programming republic of Perl";
1013     $x =~ /^(.+?)(e|r)(.*)$/; # matches,
1014                               # $1 = 'Th'
1015                               # $2 = 'e'
1016                               # $3 = ' programming republic of Perl'
1017
1018 The minimal string that will allow both the start of the string C<^>
1019 and the alternation to match is C<Th>, with the alternation C<e|r>
1020 matching C<e>.  The second quantifier C<.*> is free to gobble up the
1021 rest of the string.
1022
1023     $x =~ /(m{1,2}?)(.*?)$/;  # matches,
1024                               # $1 = 'm'
1025                               # $2 = 'ming republic of Perl'
1026
1027 The first string position that this regexp can match is at the first
1028 C<'m'> in C<programming>. At this position, the minimal C<m{1,2}?>
1029 matches just one C<'m'>.  Although the second quantifier C<.*?> would
1030 prefer to match no characters, it is constrained by the end-of-string
1031 anchor C<$> to match the rest of the string.
1032
1033     $x =~ /(.*?)(m{1,2}?)(.*)$/;  # matches,
1034                                   # $1 = 'The progra'
1035                                   # $2 = 'm'
1036                                   # $3 = 'ming republic of Perl'
1037
1038 In this regexp, you might expect the first minimal quantifier C<.*?>
1039 to match the empty string, because it is not constrained by a C<^>
1040 anchor to match the beginning of the word.  Principle 0 applies here,
1041 however.  Because it is possible for the whole regexp to match at the
1042 start of the string, it I<will> match at the start of the string.  Thus
1043 the first quantifier has to match everything up to the first C<m>.  The
1044 second minimal quantifier matches just one C<m> and the third
1045 quantifier matches the rest of the string.
1046
1047     $x =~ /(.??)(m{1,2})(.*)$/;  # matches,
1048                                  # $1 = 'a'
1049                                  # $2 = 'mm'
1050                                  # $3 = 'ing republic of Perl'
1051
1052 Just as in the previous regexp, the first quantifier C<.??> can match
1053 earliest at position C<'a'>, so it does.  The second quantifier is
1054 greedy, so it matches C<mm>, and the third matches the rest of the
1055 string.
1056
1057 We can modify principle 3 above to take into account non-greedy
1058 quantifiers:
1059
1060 =over 4
1061
1062 =item *
1063
1064 Principle 3: If there are two or more elements in a regexp, the
1065 leftmost greedy (non-greedy) quantifier, if any, will match as much
1066 (little) of the string as possible while still allowing the whole
1067 regexp to match.  The next leftmost greedy (non-greedy) quantifier, if
1068 any, will try to match as much (little) of the string remaining
1069 available to it as possible, while still allowing the whole regexp to
1070 match.  And so on, until all the regexp elements are satisfied.
1071
1072 =back
1073
1074 Just like alternation, quantifiers are also susceptible to
1075 backtracking.  Here is a step-by-step analysis of the example
1076
1077     $x = "the cat in the hat";
1078     $x =~ /^(.*)(at)(.*)$/; # matches,
1079                             # $1 = 'the cat in the h'
1080                             # $2 = 'at'
1081                             # $3 = ''   (0 matches)
1082
1083 =over 4
1084
1085 =item 0
1086
1087 Start with the first letter in the string 't'.
1088
1089 =item 1
1090
1091 The first quantifier '.*' starts out by matching the whole
1092 string 'the cat in the hat'.
1093
1094 =item 2
1095
1096 'a' in the regexp element 'at' doesn't match the end of the
1097 string.  Backtrack one character.
1098
1099 =item 3
1100
1101 'a' in the regexp element 'at' still doesn't match the last
1102 letter of the string 't', so backtrack one more character.
1103
1104 =item 4
1105
1106 Now we can match the 'a' and the 't'.
1107
1108 =item 5
1109
1110 Move on to the third element '.*'.  Since we are at the end of
1111 the string and '.*' can match 0 times, assign it the empty string.
1112
1113 =item 6
1114
1115 We are done!
1116
1117 =back
1118
1119 Most of the time, all this moving forward and backtracking happens
1120 quickly and searching is fast.   There are some pathological regexps,
1121 however, whose execution time exponentially grows with the size of the
1122 string.  A typical structure that blows up in your face is of the form
1123
1124     /(a|b+)*/;
1125
1126 The problem is the nested indeterminate quantifiers.  There are many
1127 different ways of partitioning a string of length n between the C<+>
1128 and C<*>: one repetition with C<b+> of length n, two repetitions with
1129 the first C<b+> length k and the second with length n-k, m repetitions
1130 whose bits add up to length n, etc.  In fact there are an exponential
1131 number of ways to partition a string as a function of length.  A
1132 regexp may get lucky and match early in the process, but if there is
1133 no match, perl will try I<every> possibility before giving up.  So be
1134 careful with nested C<*>'s, C<{n,m}>'s, and C<+>'s.  The book
1135 I<Mastering regular expressions> by Jeffrey Friedl gives a wonderful
1136 discussion of this and other efficiency issues.
1137
1138 =head2 Building a regexp
1139
1140 At this point, we have all the basic regexp concepts covered, so let's
1141 give a more involved example of a regular expression.  We will build a
1142 regexp that matches numbers.
1143
1144 The first task in building a regexp is to decide what we want to match
1145 and what we want to exclude.  In our case, we want to match both
1146 integers and floating point numbers and we want to reject any string
1147 that isn't a number.
1148
1149 The next task is to break the problem down into smaller problems that
1150 are easily converted into a regexp.
1151
1152 The simplest case is integers.  These consist of a sequence of digits,
1153 with an optional sign in front.  The digits we can represent with
1154 C<\d+> and the sign can be matched with C<[+-]>.  Thus the integer
1155 regexp is
1156
1157     /[+-]?\d+/;  # matches integers
1158
1159 A floating point number potentially has a sign, an integral part, a
1160 decimal point, a fractional part, and an exponent.  One or more of these
1161 parts is optional, so we need to check out the different
1162 possibilities.  Floating point numbers which are in proper form include
1163 123., 0.345, .34, -1e6, and 25.4E-72.  As with integers, the sign out
1164 front is completely optional and can be matched by C<[+-]?>.  We can
1165 see that if there is no exponent, floating point numbers must have a
1166 decimal point, otherwise they are integers.  We might be tempted to
1167 model these with C<\d*\.\d*>, but this would also match just a single
1168 decimal point, which is not a number.  So the three cases of floating
1169 point number sans exponent are
1170
1171    /[+-]?\d+\./;  # 1., 321., etc.
1172    /[+-]?\.\d+/;  # .1, .234, etc.
1173    /[+-]?\d+\.\d+/;  # 1.0, 30.56, etc.
1174
1175 These can be combined into a single regexp with a three-way alternation:
1176
1177    /[+-]?(\d+\.\d+|\d+\.|\.\d+)/;  # floating point, no exponent
1178
1179 In this alternation, it is important to put C<'\d+\.\d+'> before
1180 C<'\d+\.'>.  If C<'\d+\.'> were first, the regexp would happily match that
1181 and ignore the fractional part of the number.
1182
1183 Now consider floating point numbers with exponents.  The key
1184 observation here is that I<both> integers and numbers with decimal
1185 points are allowed in front of an exponent.  Then exponents, like the
1186 overall sign, are independent of whether we are matching numbers with
1187 or without decimal points, and can be 'decoupled' from the
1188 mantissa.  The overall form of the regexp now becomes clear:
1189
1190     /^(optional sign)(integer | f.p. mantissa)(optional exponent)$/;
1191
1192 The exponent is an C<e> or C<E>, followed by an integer.  So the
1193 exponent regexp is
1194
1195    /[eE][+-]?\d+/;  # exponent
1196
1197 Putting all the parts together, we get a regexp that matches numbers:
1198
1199    /^[+-]?(\d+\.\d+|\d+\.|\.\d+|\d+)([eE][+-]?\d+)?$/;  # Ta da!
1200
1201 Long regexps like this may impress your friends, but can be hard to
1202 decipher.  In complex situations like this, the C<//x> modifier for a
1203 match is invaluable.  It allows one to put nearly arbitrary whitespace
1204 and comments into a regexp without affecting their meaning.  Using it,
1205 we can rewrite our 'extended' regexp in the more pleasing form
1206
1207    /^
1208       [+-]?         # first, match an optional sign
1209       (             # then match integers or f.p. mantissas:
1210           \d+\.\d+  # mantissa of the form a.b
1211          |\d+\.     # mantissa of the form a.
1212          |\.\d+     # mantissa of the form .b
1213          |\d+       # integer of the form a
1214       )
1215       ([eE][+-]?\d+)?  # finally, optionally match an exponent
1216    $/x;
1217
1218 If whitespace is mostly irrelevant, how does one include space
1219 characters in an extended regexp? The answer is to backslash it
1220 S<C<'\ '> > or put it in a character class S<C<[ ]> >.  The same thing
1221 goes for pound signs, use C<\#> or C<[#]>.  For instance, Perl allows
1222 a space between the sign and the mantissa/integer, and we could add
1223 this to our regexp as follows:
1224
1225    /^
1226       [+-]?\ *      # first, match an optional sign *and space*
1227       (             # then match integers or f.p. mantissas:
1228           \d+\.\d+  # mantissa of the form a.b
1229          |\d+\.     # mantissa of the form a.
1230          |\.\d+     # mantissa of the form .b
1231          |\d+       # integer of the form a
1232       )
1233       ([eE][+-]?\d+)?  # finally, optionally match an exponent
1234    $/x;
1235
1236 In this form, it is easier to see a way to simplify the
1237 alternation.  Alternatives 1, 2, and 4 all start with C<\d+>, so it
1238 could be factored out:
1239
1240    /^
1241       [+-]?\ *      # first, match an optional sign
1242       (             # then match integers or f.p. mantissas:
1243           \d+       # start out with a ...
1244           (
1245               \.\d* # mantissa of the form a.b or a.
1246           )?        # ? takes care of integers of the form a
1247          |\.\d+     # mantissa of the form .b
1248       )
1249       ([eE][+-]?\d+)?  # finally, optionally match an exponent
1250    $/x;
1251
1252 or written in the compact form,
1253
1254     /^[+-]?\ *(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
1255
1256 This is our final regexp.  To recap, we built a regexp by
1257
1258 =over 4
1259
1260 =item *
1261
1262 specifying the task in detail,
1263
1264 =item *
1265
1266 breaking down the problem into smaller parts,
1267
1268 =item *
1269
1270 translating the small parts into regexps,
1271
1272 =item *
1273
1274 combining the regexps,
1275
1276 =item *
1277
1278 and optimizing the final combined regexp.
1279
1280 =back
1281
1282 These are also the typical steps involved in writing a computer
1283 program.  This makes perfect sense, because regular expressions are
1284 essentially programs written a little computer language that specifies
1285 patterns.
1286
1287 =head2 Using regular expressions in Perl
1288
1289 The last topic of Part 1 briefly covers how regexps are used in Perl
1290 programs.  Where do they fit into Perl syntax?
1291
1292 We have already introduced the matching operator in its default
1293 C</regexp/> and arbitrary delimiter C<m!regexp!> forms.  We have used
1294 the binding operator C<=~> and its negation C<!~> to test for string
1295 matches.  Associated with the matching operator, we have discussed the
1296 single line C<//s>, multi-line C<//m>, case-insensitive C<//i> and
1297 extended C<//x> modifiers.
1298
1299 There are a few more things you might want to know about matching
1300 operators.  First, we pointed out earlier that variables in regexps are
1301 substituted before the regexp is evaluated:
1302
1303     $pattern = 'Seuss';
1304     while (<>) {
1305         print if /$pattern/;
1306     }
1307
1308 This will print any lines containing the word C<Seuss>.  It is not as
1309 efficient as it could be, however, because perl has to re-evaluate
1310 C<$pattern> each time through the loop.  If C<$pattern> won't be
1311 changing over the lifetime of the script, we can add the C<//o>
1312 modifier, which directs perl to only perform variable substitutions
1313 once:
1314
1315     #!/usr/bin/perl
1316     #    Improved simple_grep
1317     $regexp = shift;
1318     while (<>) {
1319         print if /$regexp/o;  # a good deal faster
1320     }
1321
1322 If you change C<$pattern> after the first substitution happens, perl
1323 will ignore it.  If you don't want any substitutions at all, use the
1324 special delimiter C<m''>:
1325
1326     $pattern = 'Seuss';
1327     while (<>) {
1328         print if m'$pattern';  # matches '$pattern', not 'Seuss'
1329     }
1330
1331 C<m''> acts like single quotes on a regexp; all other C<m> delimiters
1332 act like double quotes.  If the regexp evaluates to the empty string,
1333 the regexp in the I<last successful match> is used instead.  So we have
1334
1335     "dog" =~ /d/;  # 'd' matches
1336     "dogbert =~ //;  # this matches the 'd' regexp used before
1337
1338 The final two modifiers C<//g> and C<//c> concern multiple matches.
1339 The modifier C<//g> stands for global matching and allows the
1340 matching operator to match within a string as many times as possible.
1341 In scalar context, successive invocations against a string will have
1342 `C<//g> jump from match to match, keeping track of position in the
1343 string as it goes along.  You can get or set the position with the
1344 C<pos()> function.
1345
1346 The use of C<//g> is shown in the following example.  Suppose we have
1347 a string that consists of words separated by spaces.  If we know how
1348 many words there are in advance, we could extract the words using
1349 groupings:
1350
1351     $x = "cat dog house"; # 3 words
1352     $x =~ /^\s*(\w+)\s+(\w+)\s+(\w+)\s*$/; # matches,
1353                                            # $1 = 'cat'
1354                                            # $2 = 'dog'
1355                                            # $3 = 'house'
1356
1357 But what if we had an indeterminate number of words? This is the sort
1358 of task C<//g> was made for.  To extract all words, form the simple
1359 regexp C<(\w+)> and loop over all matches with C</(\w+)/g>:
1360
1361     while ($x =~ /(\w+)/g) {
1362         print "Word is $1, ends at position ", pos $x, "\n";
1363     }
1364
1365 prints
1366
1367     Word is cat, ends at position 3
1368     Word is dog, ends at position 7
1369     Word is house, ends at position 13
1370
1371 A failed match or changing the target string resets the position.  If
1372 you don't want the position reset after failure to match, add the
1373 C<//c>, as in C</regexp/gc>.  The current position in the string is
1374 associated with the string, not the regexp.  This means that different
1375 strings have different positions and their respective positions can be
1376 set or read independently.
1377
1378 In list context, C<//g> returns a list of matched groupings, or if
1379 there are no groupings, a list of matches to the whole regexp.  So if
1380 we wanted just the words, we could use
1381
1382     @words = ($x =~ /(\w+)/g);  # matches,
1383                                 # $word[0] = 'cat'
1384                                 # $word[1] = 'dog'
1385                                 # $word[2] = 'house'
1386
1387 Closely associated with the C<//g> modifier is the C<\G> anchor.  The
1388 C<\G> anchor matches at the point where the previous C<//g> match left
1389 off.  C<\G> allows us to easily do context-sensitive matching:
1390
1391     $metric = 1;  # use metric units
1392     ...
1393     $x = <FILE>;  # read in measurement
1394     $x =~ /^([+-]?\d+)\s*/g;  # get magnitude
1395     $weight = $1;
1396     if ($metric) { # error checking
1397         print "Units error!" unless $x =~ /\Gkg\./g;
1398     }
1399     else {
1400         print "Units error!" unless $x =~ /\Glbs\./g;
1401     }
1402     $x =~ /\G\s+(widget|sprocket)/g;  # continue processing
1403
1404 The combination of C<//g> and C<\G> allows us to process the string a
1405 bit at a time and use arbitrary Perl logic to decide what to do next.
1406
1407 C<\G> is also invaluable in processing fixed length records with
1408 regexps.  Suppose we have a snippet of coding region DNA, encoded as
1409 base pair letters C<ATCGTTGAAT...> and we want to find all the stop
1410 codons C<TGA>.  In a coding region, codons are 3-letter sequences, so
1411 we can think of the DNA snippet as a sequence of 3-letter records.  The
1412 naive regexp
1413
1414     # expanded, this is "ATC GTT GAA TGC AAA TGA CAT GAC"
1415     $dna = "ATCGTTGAATGCAAATGACATGAC";
1416     $dna =~ /TGA/;
1417
1418 doesn't work; it may match a C<TGA>, but there is no guarantee that
1419 the match is aligned with codon boundaries, e.g., the substring
1420 S<C<GTT GAA> > gives a match.  A better solution is
1421
1422     while ($dna =~ /(\w\w\w)*?TGA/g) {  # note the minimal *?
1423         print "Got a TGA stop codon at position ", pos $dna, "\n";
1424     }
1425
1426 which prints
1427
1428     Got a TGA stop codon at position 18
1429     Got a TGA stop codon at position 23
1430
1431 Position 18 is good, but position 23 is bogus.  What happened?
1432
1433 The answer is that our regexp works well until we get past the last
1434 real match.  Then the regexp will fail to match a synchronized C<TGA>
1435 and start stepping ahead one character position at a time, not what we
1436 want.  The solution is to use C<\G> to anchor the match to the codon
1437 alignment:
1438
1439     while ($dna =~ /\G(\w\w\w)*?TGA/g) {
1440         print "Got a TGA stop codon at position ", pos $dna, "\n";
1441     }
1442
1443 This prints
1444
1445     Got a TGA stop codon at position 18
1446
1447 which is the correct answer.  This example illustrates that it is
1448 important not only to match what is desired, but to reject what is not
1449 desired.
1450
1451 B<search and replace>
1452
1453 Regular expressions also play a big role in B<search and replace>
1454 operations in Perl.  Search and replace is accomplished with the
1455 C<s///> operator.  The general form is
1456 C<s/regexp/replacement/modifiers>, with everything we know about
1457 regexps and modifiers applying in this case as well.  The
1458 C<replacement> is a Perl double quoted string that replaces in the
1459 string whatever is matched with the C<regexp>.  The operator C<=~> is
1460 also used here to associate a string with C<s///>.  If matching
1461 against C<$_>, the S<C<$_ =~> > can be dropped.  If there is a match,
1462 C<s///> returns the number of substitutions made, otherwise it returns
1463 false.  Here are a few examples:
1464
1465     $x = "Time to feed the cat!";
1466     $x =~ s/cat/hacker/;   # $x contains "Time to feed the hacker!"
1467     if ($x =~ s/^(Time.*hacker)!$/$1 now!/) {
1468         $more_insistent = 1;
1469     }
1470     $y = "'quoted words'";
1471     $y =~ s/^'(.*)'$/$1/;  # strip single quotes,
1472                            # $y contains "quoted words"
1473
1474 In the last example, the whole string was matched, but only the part
1475 inside the single quotes was grouped.  With the C<s///> operator, the
1476 matched variables C<$1>, C<$2>, etc.  are immediately available for use
1477 in the replacement expression, so we use C<$1> to replace the quoted
1478 string with just what was quoted.  With the global modifier, C<s///g>
1479 will search and replace all occurrences of the regexp in the string:
1480
1481     $x = "I batted 4 for 4";
1482     $x =~ s/4/four/;   # doesn't do it all:
1483                        # $x contains "I batted four for 4"
1484     $x = "I batted 4 for 4";
1485     $x =~ s/4/four/g;  # does it all:
1486                        # $x contains "I batted four for four"
1487
1488 If you prefer 'regex' over 'regexp' in this tutorial, you could use
1489 the following program to replace it:
1490
1491     % cat > simple_replace
1492     #!/usr/bin/perl
1493     $regexp = shift;
1494     $replacement = shift;
1495     while (<>) {
1496         s/$regexp/$replacement/go;
1497         print;
1498     }
1499     ^D
1500
1501     % simple_replace regexp regex perlretut.pod
1502
1503 In C<simple_replace> we used the C<s///g> modifier to replace all
1504 occurrences of the regexp on each line and the C<s///o> modifier to
1505 compile the regexp only once.  As with C<simple_grep>, both the
1506 C<print> and the C<s/$regexp/$replacement/go> use C<$_> implicitly.
1507
1508 A modifier available specifically to search and replace is the
1509 C<s///e> evaluation modifier.  C<s///e> wraps an C<eval{...}> around
1510 the replacement string and the evaluated result is substituted for the
1511 matched substring.  C<s///e> is useful if you need to do a bit of
1512 computation in the process of replacing text.  This example counts
1513 character frequencies in a line:
1514
1515     $x = "Bill the cat";
1516     $x =~ s/(.)/$chars{$1}++;$1/eg;  # final $1 replaces char with itself
1517     print "frequency of '$_' is $chars{$_}\n"
1518         foreach (sort {$chars{$b} <=> $chars{$a}} keys %chars);
1519
1520 This prints
1521
1522     frequency of ' ' is 2
1523     frequency of 't' is 2
1524     frequency of 'l' is 2
1525     frequency of 'B' is 1
1526     frequency of 'c' is 1
1527     frequency of 'e' is 1
1528     frequency of 'h' is 1
1529     frequency of 'i' is 1
1530     frequency of 'a' is 1
1531
1532 As with the match C<m//> operator, C<s///> can use other delimiters,
1533 such as C<s!!!> and C<s{}{}>, and even C<s{}//>.  If single quotes are
1534 used C<s'''>, then the regexp and replacement are treated as single
1535 quoted strings and there are no substitutions.  C<s///> in list context
1536 returns the same thing as in scalar context, i.e., the number of
1537 matches.
1538
1539 B<The split operator>
1540
1541 The B<C<split> > function can also optionally use a matching operator
1542 C<m//> to split a string.  C<split /regexp/, string, limit> splits
1543 C<string> into a list of substrings and returns that list.  The regexp
1544 is used to match the character sequence that the C<string> is split
1545 with respect to.  The C<limit>, if present, constrains splitting into
1546 no more than C<limit> number of strings.  For example, to split a
1547 string into words, use
1548
1549     $x = "Calvin and Hobbes";
1550     @words = split /\s+/, $x;  # $word[0] = 'Calvin'
1551                                # $word[1] = 'and'
1552                                # $word[2] = 'Hobbes'
1553
1554 If the empty regexp C<//> is used, the regexp always matches and
1555 the string is split into individual characters.  If the regexp has
1556 groupings, then list produced contains the matched substrings from the
1557 groupings as well.  For instance,
1558
1559     $x = "/usr/bin/perl";
1560     @dirs = split m!/!, $x;  # $dirs[0] = ''
1561                              # $dirs[1] = 'usr'
1562                              # $dirs[2] = 'bin'
1563                              # $dirs[3] = 'perl'
1564     @parts = split m!(/)!, $x;  # $parts[0] = ''
1565                                 # $parts[1] = '/'
1566                                 # $parts[2] = 'usr'
1567                                 # $parts[3] = '/'
1568                                 # $parts[4] = 'bin'
1569                                 # $parts[5] = '/'
1570                                 # $parts[6] = 'perl'
1571
1572 Since the first character of $x matched the regexp, C<split> prepended
1573 an empty initial element to the list.
1574
1575 If you have read this far, congratulations! You now have all the basic
1576 tools needed to use regular expressions to solve a wide range of text
1577 processing problems.  If this is your first time through the tutorial,
1578 why not stop here and play around with regexps a while...  S<Part 2>
1579 concerns the more esoteric aspects of regular expressions and those
1580 concepts certainly aren't needed right at the start.
1581
1582 =head1 Part 2: Power tools
1583
1584 OK, you know the basics of regexps and you want to know more.  If
1585 matching regular expressions is analogous to a walk in the woods, then
1586 the tools discussed in Part 1 are analogous to topo maps and a
1587 compass, basic tools we use all the time.  Most of the tools in part 2
1588 are analogous to flare guns and satellite phones.  They aren't used
1589 too often on a hike, but when we are stuck, they can be invaluable.
1590
1591 What follows are the more advanced, less used, or sometimes esoteric
1592 capabilities of perl regexps.  In Part 2, we will assume you are
1593 comfortable with the basics and concentrate on the new features.
1594
1595 =head2 More on characters, strings, and character classes
1596
1597 There are a number of escape sequences and character classes that we
1598 haven't covered yet.
1599
1600 There are several escape sequences that convert characters or strings
1601 between upper and lower case.  C<\l> and C<\u> convert the next
1602 character to lower or upper case, respectively:
1603
1604     $x = "perl";
1605     $string =~ /\u$x/;  # matches 'Perl' in $string
1606     $x = "M(rs?|s)\\."; # note the double backslash
1607     $string =~ /\l$x/;  # matches 'mr.', 'mrs.', and 'ms.',
1608
1609 C<\L> and C<\U> converts a whole substring, delimited by C<\L> or
1610 C<\U> and C<\E>, to lower or upper case:
1611
1612     $x = "This word is in lower case:\L SHOUT\E";
1613     $x =~ /shout/;       # matches
1614     $x = "I STILL KEYPUNCH CARDS FOR MY 360"
1615     $x =~ /\Ukeypunch/;  # matches punch card string
1616
1617 If there is no C<\E>, case is converted until the end of the
1618 string. The regexps C<\L\u$word> or C<\u\L$word> convert the first
1619 character of C<$word> to uppercase and the rest of the characters to
1620 lowercase.
1621
1622 Control characters can be escaped with C<\c>, so that a control-Z
1623 character would be matched with C<\cZ>.  The escape sequence
1624 C<\Q>...C<\E> quotes, or protects most non-alphabetic characters.   For
1625 instance,
1626
1627     $x = "\QThat !^*&%~& cat!";
1628     $x =~ /\Q!^*&%~&\E/;  # check for rough language
1629
1630 It does not protect C<$> or C<@>, so that variables can still be
1631 substituted.
1632
1633 With the advent of 5.6.0, perl regexps can handle more than just the
1634 standard ASCII character set.  Perl now supports B<Unicode>, a standard
1635 for encoding the character sets from many of the world's written
1636 languages.  Unicode does this by allowing characters to be more than
1637 one byte wide.  Perl uses the UTF-8 encoding, in which ASCII characters
1638 are still encoded as one byte, but characters greater than C<chr(127)>
1639 may be stored as two or more bytes.
1640
1641 What does this mean for regexps? Well, regexp users don't need to know
1642 much about perl's internal representation of strings.  But they do need
1643 to know 1) how to represent Unicode characters in a regexp and 2) when
1644 a matching operation will treat the string to be searched as a
1645 sequence of bytes (the old way) or as a sequence of Unicode characters
1646 (the new way).  The answer to 1) is that Unicode characters greater
1647 than C<chr(127)> may be represented using the C<\x{hex}> notation,
1648 with C<hex> a hexadecimal integer:
1649
1650     /\x{263a}/;  # match a Unicode smiley face :)
1651
1652 Unicode characters in the range of 128-255 use two hexadecimal digits
1653 with braces: C<\x{ab}>.  Note that this is different than C<\xab>,
1654 which is just a hexadecimal byte with no Unicode significance.
1655
1656 B<NOTE>: in Perl 5.6.0 it used to be that one needed to say C<use
1657 utf8> to use any Unicode features.  This is no more the case: for
1658 almost all Unicode processing, the explicit C<utf8> pragma is not
1659 needed.  (The only case where it matters is if your Perl script is in
1660 Unicode and encoded in UTF-8, then an explicit C<use utf8> is needed.)
1661
1662 Figuring out the hexadecimal sequence of a Unicode character you want
1663 or deciphering someone else's hexadecimal Unicode regexp is about as
1664 much fun as programming in machine code.  So another way to specify
1665 Unicode characters is to use the S<B<named character> > escape
1666 sequence C<\N{name}>.  C<name> is a name for the Unicode character, as
1667 specified in the Unicode standard.  For instance, if we wanted to
1668 represent or match the astrological sign for the planet Mercury, we
1669 could use
1670
1671     use charnames ":full"; # use named chars with Unicode full names
1672     $x = "abc\N{MERCURY}def";
1673     $x =~ /\N{MERCURY}/;   # matches
1674
1675 One can also use short names or restrict names to a certain alphabet:
1676
1677     use charnames ':full';
1678     print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n";
1679
1680     use charnames ":short";
1681     print "\N{greek:Sigma} is an upper-case sigma.\n";
1682
1683     use charnames qw(greek);
1684     print "\N{sigma} is Greek sigma\n";
1685
1686 A list of full names is found in the file Names.txt in the
1687 lib/perl5/5.X.X/unicore directory.
1688
1689 The answer to requirement 2), as of 5.6.0, is that if a regexp
1690 contains Unicode characters, the string is searched as a sequence of
1691 Unicode characters.  Otherwise, the string is searched as a sequence of
1692 bytes.  If the string is being searched as a sequence of Unicode
1693 characters, but matching a single byte is required, we can use the C<\C>
1694 escape sequence.  C<\C> is a character class akin to C<.> except that
1695 it matches I<any> byte 0-255.  So
1696
1697     use charnames ":full"; # use named chars with Unicode full names
1698     $x = "a";
1699     $x =~ /\C/;  # matches 'a', eats one byte
1700     $x = "";
1701     $x =~ /\C/;  # doesn't match, no bytes to match
1702     $x = "\N{MERCURY}";  # two-byte Unicode character
1703     $x =~ /\C/;  # matches, but dangerous!
1704
1705 The last regexp matches, but is dangerous because the string
1706 I<character> position is no longer synchronized to the string I<byte>
1707 position.  This generates the warning 'Malformed UTF-8
1708 character'.  C<\C> is best used for matching the binary data in strings
1709 with binary data intermixed with Unicode characters.
1710
1711 Let us now discuss the rest of the character classes.  Just as with
1712 Unicode characters, there are named Unicode character classes
1713 represented by the C<\p{name}> escape sequence.  Closely associated is
1714 the C<\P{name}> character class, which is the negation of the
1715 C<\p{name}> class.  For example, to match lower and uppercase
1716 characters,
1717
1718     use charnames ":full"; # use named chars with Unicode full names
1719     $x = "BOB";
1720     $x =~ /^\p{IsUpper}/;   # matches, uppercase char class
1721     $x =~ /^\P{IsUpper}/;   # doesn't match, char class sans uppercase
1722     $x =~ /^\p{IsLower}/;   # doesn't match, lowercase char class
1723     $x =~ /^\P{IsLower}/;   # matches, char class sans lowercase
1724
1725 Here is the association between some Perl named classes and the
1726 traditional Unicode classes:
1727
1728     Perl class name  Unicode class name or regular expression
1729
1730     IsAlpha          /^[LM]/
1731     IsAlnum          /^[LMN]/
1732     IsASCII          $code <= 127
1733     IsCntrl          /^C/
1734     IsBlank          $code =~ /^(0020|0009)$/ || /^Z[^lp]/
1735     IsDigit          Nd
1736     IsGraph          /^([LMNPS]|Co)/
1737     IsLower          Ll
1738     IsPrint          /^([LMNPS]|Co|Zs)/
1739     IsPunct          /^P/
1740     IsSpace          /^Z/ || ($code =~ /^(0009|000A|000B|000C|000D)$/
1741     IsSpacePerl      /^Z/ || ($code =~ /^(0009|000A|000C|000D|0085|2028|2029)$/
1742     IsUpper          /^L[ut]/
1743     IsWord           /^[LMN]/ || $code eq "005F"
1744     IsXDigit         $code =~ /^00(3[0-9]|[46][1-6])$/
1745
1746 You can also use the official Unicode class names with the C<\p> and
1747 C<\P>, like C<\p{L}> for Unicode 'letters', or C<\p{Lu}> for uppercase
1748 letters, or C<\P{Nd}> for non-digits.  If a C<name> is just one
1749 letter, the braces can be dropped.  For instance, C<\pM> is the
1750 character class of Unicode 'marks', for example accent marks.
1751 For the full list see L<perlunicode>.
1752
1753 The Unicode has also been separated into various sets of charaters
1754 which you can test with C<\p{In...}> (in) and C<\P{In...}> (not in),
1755 for example C<\p{InLatin}>, C<\p{InGreek}>, or C<\P{InKatakana}>.
1756 For the full list see L<perlunicode>.
1757
1758 C<\X> is an abbreviation for a character class sequence that includes
1759 the Unicode 'combining character sequences'.  A 'combining character
1760 sequence' is a base character followed by any number of combining
1761 characters.  An example of a combining character is an accent.   Using
1762 the Unicode full names, e.g., S<C<A + COMBINING RING> > is a combining
1763 character sequence with base character C<A> and combining character
1764 S<C<COMBINING RING> >, which translates in Danish to A with the circle
1765 atop it, as in the word Angstrom.  C<\X> is equivalent to C<\PM\pM*}>,
1766 i.e., a non-mark followed by one or more marks.
1767
1768 For the full and latest information about Unicode see the latest
1769 Unicode standard, or the Unicode Consortium's website http://www.unicode.org/
1770
1771 As if all those classes weren't enough, Perl also defines POSIX style
1772 character classes.  These have the form C<[:name:]>, with C<name> the
1773 name of the POSIX class.  The POSIX classes are C<alpha>, C<alnum>,
1774 C<ascii>, C<cntrl>, C<digit>, C<graph>, C<lower>, C<print>, C<punct>,
1775 C<space>, C<upper>, and C<xdigit>, and two extensions, C<word> (a Perl
1776 extension to match C<\w>), and C<blank> (a GNU extension).  If C<utf8>
1777 is being used, then these classes are defined the same as their
1778 corresponding perl Unicode classes: C<[:upper:]> is the same as
1779 C<\p{IsUpper}>, etc.  The POSIX character classes, however, don't
1780 require using C<utf8>.  The C<[:digit:]>, C<[:word:]>, and
1781 C<[:space:]> correspond to the familiar C<\d>, C<\w>, and C<\s>
1782 character classes.  To negate a POSIX class, put a C<^> in front of
1783 the name, so that, e.g., C<[:^digit:]> corresponds to C<\D> and under
1784 C<utf8>, C<\P{IsDigit}>.  The Unicode and POSIX character classes can
1785 be used just like C<\d>, both inside and outside of character classes:
1786
1787     /\s+[abc[:digit:]xyz]\s*/;  # match a,b,c,x,y,z, or a digit
1788     /^=item\s[:digit:]/;        # match '=item',
1789                                 # followed by a space and a digit
1790     use charnames ":full";
1791     /\s+[abc\p{IsDigit}xyz]\s+/;  # match a,b,c,x,y,z, or a digit
1792     /^=item\s\p{IsDigit}/;        # match '=item',
1793                                   # followed by a space and a digit
1794
1795 Whew! That is all the rest of the characters and character classes.
1796
1797 =head2 Compiling and saving regular expressions
1798
1799 In Part 1 we discussed the C<//o> modifier, which compiles a regexp
1800 just once.  This suggests that a compiled regexp is some data structure
1801 that can be stored once and used again and again.  The regexp quote
1802 C<qr//> does exactly that: C<qr/string/> compiles the C<string> as a
1803 regexp and transforms the result into a form that can be assigned to a
1804 variable:
1805
1806     $reg = qr/foo+bar?/;  # reg contains a compiled regexp
1807
1808 Then C<$reg> can be used as a regexp:
1809
1810     $x = "fooooba";
1811     $x =~ $reg;     # matches, just like /foo+bar?/
1812     $x =~ /$reg/;   # same thing, alternate form
1813
1814 C<$reg> can also be interpolated into a larger regexp:
1815
1816     $x =~ /(abc)?$reg/;  # still matches
1817
1818 As with the matching operator, the regexp quote can use different
1819 delimiters, e.g., C<qr!!>, C<qr{}> and C<qr~~>.  The single quote
1820 delimiters C<qr''> prevent any interpolation from taking place.
1821
1822 Pre-compiled regexps are useful for creating dynamic matches that
1823 don't need to be recompiled each time they are encountered.  Using
1824 pre-compiled regexps, C<simple_grep> program can be expanded into a
1825 program that matches multiple patterns:
1826
1827     % cat > multi_grep
1828     #!/usr/bin/perl
1829     # multi_grep - match any of <number> regexps
1830     # usage: multi_grep <number> regexp1 regexp2 ... file1 file2 ...
1831
1832     $number = shift;
1833     $regexp[$_] = shift foreach (0..$number-1);
1834     @compiled = map qr/$_/, @regexp;
1835     while ($line = <>) {
1836         foreach $pattern (@compiled) {
1837             if ($line =~ /$pattern/) {
1838                 print $line;
1839                 last;  # we matched, so move onto the next line
1840             }
1841         }
1842     }
1843     ^D
1844
1845     % multi_grep 2 last for multi_grep
1846         $regexp[$_] = shift foreach (0..$number-1);
1847             foreach $pattern (@compiled) {
1848                     last;
1849
1850 Storing pre-compiled regexps in an array C<@compiled> allows us to
1851 simply loop through the regexps without any recompilation, thus gaining
1852 flexibility without sacrificing speed.
1853
1854 =head2 Embedding comments and modifiers in a regular expression
1855
1856 Starting with this section, we will be discussing Perl's set of
1857 B<extended patterns>.  These are extensions to the traditional regular
1858 expression syntax that provide powerful new tools for pattern
1859 matching.  We have already seen extensions in the form of the minimal
1860 matching constructs C<??>, C<*?>, C<+?>, C<{n,m}?>, and C<{n,}?>.  The
1861 rest of the extensions below have the form C<(?char...)>, where the
1862 C<char> is a character that determines the type of extension.
1863
1864 The first extension is an embedded comment C<(?#text)>.  This embeds a
1865 comment into the regular expression without affecting its meaning.  The
1866 comment should not have any closing parentheses in the text.  An
1867 example is
1868
1869     /(?# Match an integer:)[+-]?\d+/;
1870
1871 This style of commenting has been largely superseded by the raw,
1872 freeform commenting that is allowed with the C<//x> modifier.
1873
1874 The modifiers C<//i>, C<//m>, C<//s>, and C<//x> can also embedded in
1875 a regexp using C<(?i)>, C<(?m)>, C<(?s)>, and C<(?x)>.  For instance,
1876
1877     /(?i)yes/;  # match 'yes' case insensitively
1878     /yes/i;     # same thing
1879     /(?x)(          # freeform version of an integer regexp
1880              [+-]?  # match an optional sign
1881              \d+    # match a sequence of digits
1882          )
1883     /x;
1884
1885 Embedded modifiers can have two important advantages over the usual
1886 modifiers.  Embedded modifiers allow a custom set of modifiers to
1887 I<each> regexp pattern.  This is great for matching an array of regexps
1888 that must have different modifiers:
1889
1890     $pattern[0] = '(?i)doctor';
1891     $pattern[1] = 'Johnson';
1892     ...
1893     while (<>) {
1894         foreach $patt (@pattern) {
1895             print if /$patt/;
1896         }
1897     }
1898
1899 The second advantage is that embedded modifiers only affect the regexp
1900 inside the group the embedded modifier is contained in.  So grouping
1901 can be used to localize the modifier's effects:
1902
1903     /Answer: ((?i)yes)/;  # matches 'Answer: yes', 'Answer: YES', etc.
1904
1905 Embedded modifiers can also turn off any modifiers already present
1906 by using, e.g., C<(?-i)>.  Modifiers can also be combined into
1907 a single expression, e.g., C<(?s-i)> turns on single line mode and
1908 turns off case insensitivity.
1909
1910 =head2 Non-capturing groupings
1911
1912 We noted in Part 1 that groupings C<()> had two distinct functions: 1)
1913 group regexp elements together as a single unit, and 2) extract, or
1914 capture, substrings that matched the regexp in the
1915 grouping.  Non-capturing groupings, denoted by C<(?:regexp)>, allow the
1916 regexp to be treated as a single unit, but don't extract substrings or
1917 set matching variables C<$1>, etc.  Both capturing and non-capturing
1918 groupings are allowed to co-exist in the same regexp.  Because there is
1919 no extraction, non-capturing groupings are faster than capturing
1920 groupings.  Non-capturing groupings are also handy for choosing exactly
1921 which parts of a regexp are to be extracted to matching variables:
1922
1923     # match a number, $1-$4 are set, but we only want $1
1924     /([+-]?\ *(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?)/;
1925
1926     # match a number faster , only $1 is set
1927     /([+-]?\ *(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)/;
1928
1929     # match a number, get $1 = whole number, $2 = exponent
1930     /([+-]?\ *(?:\d+(?:\.\d*)?|\.\d+)(?:[eE]([+-]?\d+))?)/;
1931
1932 Non-capturing groupings are also useful for removing nuisance
1933 elements gathered from a split operation:
1934
1935     $x = '12a34b5';
1936     @num = split /(a|b)/, $x;    # @num = ('12','a','34','b','5')
1937     @num = split /(?:a|b)/, $x;  # @num = ('12','34','5')
1938
1939 Non-capturing groupings may also have embedded modifiers:
1940 C<(?i-m:regexp)> is a non-capturing grouping that matches C<regexp>
1941 case insensitively and turns off multi-line mode.
1942
1943 =head2 Looking ahead and looking behind
1944
1945 This section concerns the lookahead and lookbehind assertions.  First,
1946 a little background.
1947
1948 In Perl regular expressions, most regexp elements 'eat up' a certain
1949 amount of string when they match.  For instance, the regexp element
1950 C<[abc}]> eats up one character of the string when it matches, in the
1951 sense that perl moves to the next character position in the string
1952 after the match.  There are some elements, however, that don't eat up
1953 characters (advance the character position) if they match.  The examples
1954 we have seen so far are the anchors.  The anchor C<^> matches the
1955 beginning of the line, but doesn't eat any characters.  Similarly, the
1956 word boundary anchor C<\b> matches, e.g., if the character to the left
1957 is a word character and the character to the right is a non-word
1958 character, but it doesn't eat up any characters itself.  Anchors are
1959 examples of 'zero-width assertions'.  Zero-width, because they consume
1960 no characters, and assertions, because they test some property of the
1961 string.  In the context of our walk in the woods analogy to regexp
1962 matching, most regexp elements move us along a trail, but anchors have
1963 us stop a moment and check our surroundings.  If the local environment
1964 checks out, we can proceed forward.  But if the local environment
1965 doesn't satisfy us, we must backtrack.
1966
1967 Checking the environment entails either looking ahead on the trail,
1968 looking behind, or both.  C<^> looks behind, to see that there are no
1969 characters before.  C<$> looks ahead, to see that there are no
1970 characters after.  C<\b> looks both ahead and behind, to see if the
1971 characters on either side differ in their 'word'-ness.
1972
1973 The lookahead and lookbehind assertions are generalizations of the
1974 anchor concept.  Lookahead and lookbehind are zero-width assertions
1975 that let us specify which characters we want to test for.  The
1976 lookahead assertion is denoted by C<(?=regexp)> and the lookbehind
1977 assertion is denoted by C<< (?<=fixed-regexp) >>.  Some examples are
1978
1979     $x = "I catch the housecat 'Tom-cat' with catnip";
1980     $x =~ /cat(?=\s+)/;  # matches 'cat' in 'housecat'
1981     @catwords = ($x =~ /(?<=\s)cat\w+/g);  # matches,
1982                                            # $catwords[0] = 'catch'
1983                                            # $catwords[1] = 'catnip'
1984     $x =~ /\bcat\b/;  # matches 'cat' in 'Tom-cat'
1985     $x =~ /(?<=\s)cat(?=\s)/; # doesn't match; no isolated 'cat' in
1986                               # middle of $x
1987
1988 Note that the parentheses in C<(?=regexp)> and C<< (?<=regexp) >> are
1989 non-capturing, since these are zero-width assertions.  Thus in the
1990 second regexp, the substrings captured are those of the whole regexp
1991 itself.  Lookahead C<(?=regexp)> can match arbitrary regexps, but
1992 lookbehind C<< (?<=fixed-regexp) >> only works for regexps of fixed
1993 width, i.e., a fixed number of characters long.  Thus
1994 C<< (?<=(ab|bc)) >> is fine, but C<< (?<=(ab)*) >> is not.  The
1995 negated versions of the lookahead and lookbehind assertions are
1996 denoted by C<(?!regexp)> and C<< (?<!fixed-regexp) >> respectively.
1997 They evaluate true if the regexps do I<not> match:
1998
1999     $x = "foobar";
2000     $x =~ /foo(?!bar)/;  # doesn't match, 'bar' follows 'foo'
2001     $x =~ /foo(?!baz)/;  # matches, 'baz' doesn't follow 'foo'
2002     $x =~ /(?<!\s)foo/;  # matches, there is no \s before 'foo'
2003
2004 =head2 Using independent subexpressions to prevent backtracking
2005
2006 The last few extended patterns in this tutorial are experimental as of
2007 5.6.0.  Play with them, use them in some code, but don't rely on them
2008 just yet for production code.
2009
2010 S<B<Independent subexpressions> > are regular expressions, in the
2011 context of a larger regular expression, that function independently of
2012 the larger regular expression.  That is, they consume as much or as
2013 little of the string as they wish without regard for the ability of
2014 the larger regexp to match.  Independent subexpressions are represented
2015 by C<< (?>regexp) >>.  We can illustrate their behavior by first
2016 considering an ordinary regexp:
2017
2018     $x = "ab";
2019     $x =~ /a*ab/;  # matches
2020
2021 This obviously matches, but in the process of matching, the
2022 subexpression C<a*> first grabbed the C<a>.  Doing so, however,
2023 wouldn't allow the whole regexp to match, so after backtracking, C<a*>
2024 eventually gave back the C<a> and matched the empty string.  Here, what
2025 C<a*> matched was I<dependent> on what the rest of the regexp matched.
2026
2027 Contrast that with an independent subexpression:
2028
2029     $x =~ /(?>a*)ab/;  # doesn't match!
2030
2031 The independent subexpression C<< (?>a*) >> doesn't care about the rest
2032 of the regexp, so it sees an C<a> and grabs it.  Then the rest of the
2033 regexp C<ab> cannot match.  Because C<< (?>a*) >> is independent, there
2034 is no backtracking and the independent subexpression does not give
2035 up its C<a>.  Thus the match of the regexp as a whole fails.  A similar
2036 behavior occurs with completely independent regexps:
2037
2038     $x = "ab";
2039     $x =~ /a*/g;   # matches, eats an 'a'
2040     $x =~ /\Gab/g; # doesn't match, no 'a' available
2041
2042 Here C<//g> and C<\G> create a 'tag team' handoff of the string from
2043 one regexp to the other.  Regexps with an independent subexpression are
2044 much like this, with a handoff of the string to the independent
2045 subexpression, and a handoff of the string back to the enclosing
2046 regexp.
2047
2048 The ability of an independent subexpression to prevent backtracking
2049 can be quite useful.  Suppose we want to match a non-empty string
2050 enclosed in parentheses up to two levels deep.  Then the following
2051 regexp matches:
2052
2053     $x = "abc(de(fg)h";  # unbalanced parentheses
2054     $x =~ /\( ( [^()]+ | \([^()]*\) )+ \)/x;
2055
2056 The regexp matches an open parenthesis, one or more copies of an
2057 alternation, and a close parenthesis.  The alternation is two-way, with
2058 the first alternative C<[^()]+> matching a substring with no
2059 parentheses and the second alternative C<\([^()]*\)>  matching a
2060 substring delimited by parentheses.  The problem with this regexp is
2061 that it is pathological: it has nested indeterminate quantifiers
2062 of the form C<(a+|b)+>.  We discussed in Part 1 how nested quantifiers
2063 like this could take an exponentially long time to execute if there
2064 was no match possible.  To prevent the exponential blowup, we need to
2065 prevent useless backtracking at some point.  This can be done by
2066 enclosing the inner quantifier as an independent subexpression:
2067
2068     $x =~ /\( ( (?>[^()]+) | \([^()]*\) )+ \)/x;
2069
2070 Here, C<< (?>[^()]+) >> breaks the degeneracy of string partitioning
2071 by gobbling up as much of the string as possible and keeping it.   Then
2072 match failures fail much more quickly.
2073
2074 =head2 Conditional expressions
2075
2076 A S<B<conditional expression> > is a form of if-then-else statement
2077 that allows one to choose which patterns are to be matched, based on
2078 some condition.  There are two types of conditional expression:
2079 C<(?(condition)yes-regexp)> and
2080 C<(?(condition)yes-regexp|no-regexp)>.  C<(?(condition)yes-regexp)> is
2081 like an S<C<'if () {}'> > statement in Perl.  If the C<condition> is true,
2082 the C<yes-regexp> will be matched.  If the C<condition> is false, the
2083 C<yes-regexp> will be skipped and perl will move onto the next regexp
2084 element.  The second form is like an S<C<'if () {} else {}'> > statement
2085 in Perl.  If the C<condition> is true, the C<yes-regexp> will be
2086 matched, otherwise the C<no-regexp> will be matched.
2087
2088 The C<condition> can have two forms.  The first form is simply an
2089 integer in parentheses C<(integer)>.  It is true if the corresponding
2090 backreference C<\integer> matched earlier in the regexp.  The second
2091 form is a bare zero width assertion C<(?...)>, either a
2092 lookahead, a lookbehind, or a code assertion (discussed in the next
2093 section).
2094
2095 The integer form of the C<condition> allows us to choose, with more
2096 flexibility, what to match based on what matched earlier in the
2097 regexp. This searches for words of the form C<"$x$x"> or
2098 C<"$x$y$y$x">:
2099
2100     % simple_grep '^(\w+)(\w+)?(?(2)\2\1|\1)$' /usr/dict/words
2101     beriberi
2102     coco
2103     couscous
2104     deed
2105     ...
2106     toot
2107     toto
2108     tutu
2109
2110 The lookbehind C<condition> allows, along with backreferences,
2111 an earlier part of the match to influence a later part of the
2112 match.  For instance,
2113
2114     /[ATGC]+(?(?<=AA)G|C)$/;
2115
2116 matches a DNA sequence such that it either ends in C<AAG>, or some
2117 other base pair combination and C<C>.  Note that the form is
2118 C<< (?(?<=AA)G|C) >> and not C<< (?((?<=AA))G|C) >>; for the
2119 lookahead, lookbehind or code assertions, the parentheses around the
2120 conditional are not needed.
2121
2122 =head2 A bit of magic: executing Perl code in a regular expression
2123
2124 Normally, regexps are a part of Perl expressions.
2125 S<B<Code evaluation> > expressions turn that around by allowing
2126 arbitrary Perl code to be a part of a regexp.  A code evaluation
2127 expression is denoted C<(?{code})>, with C<code> a string of Perl
2128 statements.
2129
2130 Code expressions are zero-width assertions, and the value they return
2131 depends on their environment.  There are two possibilities: either the
2132 code expression is used as a conditional in a conditional expression
2133 C<(?(condition)...)>, or it is not.  If the code expression is a
2134 conditional, the code is evaluated and the result (i.e., the result of
2135 the last statement) is used to determine truth or falsehood.  If the
2136 code expression is not used as a conditional, the assertion always
2137 evaluates true and the result is put into the special variable
2138 C<$^R>.  The variable C<$^R> can then be used in code expressions later
2139 in the regexp.  Here are some silly examples:
2140
2141     $x = "abcdef";
2142     $x =~ /abc(?{print "Hi Mom!";})def/; # matches,
2143                                          # prints 'Hi Mom!'
2144     $x =~ /aaa(?{print "Hi Mom!";})def/; # doesn't match,
2145                                          # no 'Hi Mom!'
2146
2147 Pay careful attention to the next example:
2148
2149     $x =~ /abc(?{print "Hi Mom!";})ddd/; # doesn't match,
2150                                          # no 'Hi Mom!'
2151                                          # but why not?
2152
2153 At first glance, you'd think that it shouldn't print, because obviously
2154 the C<ddd> isn't going to match the target string. But look at this
2155 example:
2156
2157     $x =~ /abc(?{print "Hi Mom!";})[d]dd/; # doesn't match,
2158                                            # but _does_ print
2159
2160 Hmm. What happened here? If you've been following along, you know that
2161 the above pattern should be effectively the same as the last one --
2162 enclosing the d in a character class isn't going to change what it
2163 matches. So why does the first not print while the second one does?
2164
2165 The answer lies in the optimizations the REx engine makes. In the first
2166 case, all the engine sees are plain old characters (aside from the
2167 C<?{}> construct). It's smart enough to realize that the string 'ddd'
2168 doesn't occur in our target string before actually running the pattern
2169 through. But in the second case, we've tricked it into thinking that our
2170 pattern is more complicated than it is. It takes a look, sees our
2171 character class, and decides that it will have to actually run the
2172 pattern to determine whether or not it matches, and in the process of
2173 running it hits the print statement before it discovers that we don't
2174 have a match.
2175
2176 To take a closer look at how the engine does optimizations, see the
2177 section L<"Pragmas and debugging"> below.
2178
2179 More fun with C<?{}>:
2180
2181     $x =~ /(?{print "Hi Mom!";})/;       # matches,
2182                                          # prints 'Hi Mom!'
2183     $x =~ /(?{$c = 1;})(?{print "$c";})/;  # matches,
2184                                            # prints '1'
2185     $x =~ /(?{$c = 1;})(?{print "$^R";})/; # matches,
2186                                            # prints '1'
2187
2188 The bit of magic mentioned in the section title occurs when the regexp
2189 backtracks in the process of searching for a match.  If the regexp
2190 backtracks over a code expression and if the variables used within are
2191 localized using C<local>, the changes in the variables produced by the
2192 code expression are undone! Thus, if we wanted to count how many times
2193 a character got matched inside a group, we could use, e.g.,
2194
2195     $x = "aaaa";
2196     $count = 0;  # initialize 'a' count
2197     $c = "bob";  # test if $c gets clobbered
2198     $x =~ /(?{local $c = 0;})         # initialize count
2199            ( a                        # match 'a'
2200              (?{local $c = $c + 1;})  # increment count
2201            )*                         # do this any number of times,
2202            aa                         # but match 'aa' at the end
2203            (?{$count = $c;})          # copy local $c var into $count
2204           /x;
2205     print "'a' count is $count, \$c variable is '$c'\n";
2206
2207 This prints
2208
2209     'a' count is 2, $c variable is 'bob'
2210
2211 If we replace the S<C< (?{local $c = $c + 1;})> > with
2212 S<C< (?{$c = $c + 1;})> >, the variable changes are I<not> undone
2213 during backtracking, and we get
2214
2215     'a' count is 4, $c variable is 'bob'
2216
2217 Note that only localized variable changes are undone.  Other side
2218 effects of code expression execution are permanent.  Thus
2219
2220     $x = "aaaa";
2221     $x =~ /(a(?{print "Yow\n";}))*aa/;
2222
2223 produces
2224
2225    Yow
2226    Yow
2227    Yow
2228    Yow
2229
2230 The result C<$^R> is automatically localized, so that it will behave
2231 properly in the presence of backtracking.
2232
2233 This example uses a code expression in a conditional to match the
2234 article 'the' in either English or German:
2235
2236     $lang = 'DE';  # use German
2237     ...
2238     $text = "das";
2239     print "matched\n"
2240         if $text =~ /(?(?{
2241                           $lang eq 'EN'; # is the language English?
2242                          })
2243                        the |             # if so, then match 'the'
2244                        (die|das|der)     # else, match 'die|das|der'
2245                      )
2246                     /xi;
2247
2248 Note that the syntax here is C<(?(?{...})yes-regexp|no-regexp)>, not
2249 C<(?((?{...}))yes-regexp|no-regexp)>.  In other words, in the case of a
2250 code expression, we don't need the extra parentheses around the
2251 conditional.
2252
2253 If you try to use code expressions with interpolating variables, perl
2254 may surprise you:
2255
2256     $bar = 5;
2257     $pat = '(?{ 1 })';
2258     /foo(?{ $bar })bar/; # compiles ok, $bar not interpolated
2259     /foo(?{ 1 })$bar/;   # compile error!
2260     /foo${pat}bar/;      # compile error!
2261
2262     $pat = qr/(?{ $foo = 1 })/;  # precompile code regexp
2263     /foo${pat}bar/;      # compiles ok
2264
2265 If a regexp has (1) code expressions and interpolating variables,or
2266 (2) a variable that interpolates a code expression, perl treats the
2267 regexp as an error. If the code expression is precompiled into a
2268 variable, however, interpolating is ok. The question is, why is this
2269 an error?
2270
2271 The reason is that variable interpolation and code expressions
2272 together pose a security risk.  The combination is dangerous because
2273 many programmers who write search engines often take user input and
2274 plug it directly into a regexp:
2275
2276     $regexp = <>;       # read user-supplied regexp
2277     $chomp $regexp;     # get rid of possible newline
2278     $text =~ /$regexp/; # search $text for the $regexp
2279
2280 If the C<$regexp> variable contains a code expression, the user could
2281 then execute arbitrary Perl code.  For instance, some joker could
2282 search for S<C<system('rm -rf *');> > to erase your files.  In this
2283 sense, the combination of interpolation and code expressions B<taints>
2284 your regexp.  So by default, using both interpolation and code
2285 expressions in the same regexp is not allowed.  If you're not
2286 concerned about malicious users, it is possible to bypass this
2287 security check by invoking S<C<use re 'eval'> >:
2288
2289     use re 'eval';       # throw caution out the door
2290     $bar = 5;
2291     $pat = '(?{ 1 })';
2292     /foo(?{ 1 })$bar/;   # compiles ok
2293     /foo${pat}bar/;      # compiles ok
2294
2295 Another form of code expression is the S<B<pattern code expression> >.
2296 The pattern code expression is like a regular code expression, except
2297 that the result of the code evaluation is treated as a regular
2298 expression and matched immediately.  A simple example is
2299
2300     $length = 5;
2301     $char = 'a';
2302     $x = 'aaaaabb';
2303     $x =~ /(??{$char x $length})/x; # matches, there are 5 of 'a'
2304
2305
2306 This final example contains both ordinary and pattern code
2307 expressions.   It detects if a binary string C<1101010010001...> has a
2308 Fibonacci spacing 0,1,1,2,3,5,...  of the C<1>'s:
2309
2310     $s0 = 0; $s1 = 1; # initial conditions
2311     $x = "1101010010001000001";
2312     print "It is a Fibonacci sequence\n"
2313         if $x =~ /^1         # match an initial '1'
2314                     (
2315                        (??{'0' x $s0}) # match $s0 of '0'
2316                        1               # and then a '1'
2317                        (?{
2318                           $largest = $s0;   # largest seq so far
2319                           $s2 = $s1 + $s0;  # compute next term
2320                           $s0 = $s1;        # in Fibonacci sequence
2321                           $s1 = $s2;
2322                          })
2323                     )+   # repeat as needed
2324                   $      # that is all there is
2325                  /x;
2326     print "Largest sequence matched was $largest\n";
2327
2328 This prints
2329
2330     It is a Fibonacci sequence
2331     Largest sequence matched was 5
2332
2333 Ha! Try that with your garden variety regexp package...
2334
2335 Note that the variables C<$s0> and C<$s1> are not substituted when the
2336 regexp is compiled, as happens for ordinary variables outside a code
2337 expression.  Rather, the code expressions are evaluated when perl
2338 encounters them during the search for a match.
2339
2340 The regexp without the C<//x> modifier is
2341
2342     /^1((??{'0'x$s0})1(?{$largest=$s0;$s2=$s1+$s0$s0=$s1;$s1=$s2;}))+$/;
2343
2344 and is a great start on an Obfuscated Perl entry :-) When working with
2345 code and conditional expressions, the extended form of regexps is
2346 almost necessary in creating and debugging regexps.
2347
2348 =head2 Pragmas and debugging
2349
2350 Speaking of debugging, there are several pragmas available to control
2351 and debug regexps in Perl.  We have already encountered one pragma in
2352 the previous section, S<C<use re 'eval';> >, that allows variable
2353 interpolation and code expressions to coexist in a regexp.  The other
2354 pragmas are
2355
2356     use re 'taint';
2357     $tainted = <>;
2358     @parts = ($tainted =~ /(\w+)\s+(\w+)/; # @parts is now tainted
2359
2360 The C<taint> pragma causes any substrings from a match with a tainted
2361 variable to be tainted as well.  This is not normally the case, as
2362 regexps are often used to extract the safe bits from a tainted
2363 variable.  Use C<taint> when you are not extracting safe bits, but are
2364 performing some other processing.  Both C<taint> and C<eval> pragmas
2365 are lexically scoped, which means they are in effect only until
2366 the end of the block enclosing the pragmas.
2367
2368     use re 'debug';
2369     /^(.*)$/s;       # output debugging info
2370
2371     use re 'debugcolor';
2372     /^(.*)$/s;       # output debugging info in living color
2373
2374 The global C<debug> and C<debugcolor> pragmas allow one to get
2375 detailed debugging info about regexp compilation and
2376 execution.  C<debugcolor> is the same as debug, except the debugging
2377 information is displayed in color on terminals that can display
2378 termcap color sequences.  Here is example output:
2379
2380     % perl -e 'use re "debug"; "abc" =~ /a*b+c/;'
2381     Compiling REx `a*b+c'
2382     size 9 first at 1
2383        1: STAR(4)
2384        2:   EXACT <a>(0)
2385        4: PLUS(7)
2386        5:   EXACT <b>(0)
2387        7: EXACT <c>(9)
2388        9: END(0)
2389     floating `bc' at 0..2147483647 (checking floating) minlen 2
2390     Guessing start of match, REx `a*b+c' against `abc'...
2391     Found floating substr `bc' at offset 1...
2392     Guessed: match at offset 0
2393     Matching REx `a*b+c' against `abc'
2394       Setting an EVAL scope, savestack=3
2395        0 <> <abc>             |  1:  STAR
2396                                EXACT <a> can match 1 times out of 32767...
2397       Setting an EVAL scope, savestack=3
2398        1 <a> <bc>             |  4:    PLUS
2399                                EXACT <b> can match 1 times out of 32767...
2400       Setting an EVAL scope, savestack=3
2401        2 <ab> <c>             |  7:      EXACT <c>
2402        3 <abc> <>             |  9:      END
2403     Match successful!
2404     Freeing REx: `a*b+c'
2405
2406 If you have gotten this far into the tutorial, you can probably guess
2407 what the different parts of the debugging output tell you.  The first
2408 part
2409
2410     Compiling REx `a*b+c'
2411     size 9 first at 1
2412        1: STAR(4)
2413        2:   EXACT <a>(0)
2414        4: PLUS(7)
2415        5:   EXACT <b>(0)
2416        7: EXACT <c>(9)
2417        9: END(0)
2418
2419 describes the compilation stage.  C<STAR(4)> means that there is a
2420 starred object, in this case C<'a'>, and if it matches, goto line 4,
2421 i.e., C<PLUS(7)>.  The middle lines describe some heuristics and
2422 optimizations performed before a match:
2423
2424     floating `bc' at 0..2147483647 (checking floating) minlen 2
2425     Guessing start of match, REx `a*b+c' against `abc'...
2426     Found floating substr `bc' at offset 1...
2427     Guessed: match at offset 0
2428
2429 Then the match is executed and the remaining lines describe the
2430 process:
2431
2432     Matching REx `a*b+c' against `abc'
2433       Setting an EVAL scope, savestack=3
2434        0 <> <abc>             |  1:  STAR
2435                                EXACT <a> can match 1 times out of 32767...
2436       Setting an EVAL scope, savestack=3
2437        1 <a> <bc>             |  4:    PLUS
2438                                EXACT <b> can match 1 times out of 32767...
2439       Setting an EVAL scope, savestack=3
2440        2 <ab> <c>             |  7:      EXACT <c>
2441        3 <abc> <>             |  9:      END
2442     Match successful!
2443     Freeing REx: `a*b+c'
2444
2445 Each step is of the form S<C<< n <x> <y> >> >, with C<< <x> >> the
2446 part of the string matched and C<< <y> >> the part not yet
2447 matched.  The S<C<< |  1:  STAR >> > says that perl is at line number 1
2448 n the compilation list above.  See
2449 L<perldebguts/"Debugging regular expressions"> for much more detail.
2450
2451 An alternative method of debugging regexps is to embed C<print>
2452 statements within the regexp.  This provides a blow-by-blow account of
2453 the backtracking in an alternation:
2454
2455     "that this" =~ m@(?{print "Start at position ", pos, "\n";})
2456                      t(?{print "t1\n";})
2457                      h(?{print "h1\n";})
2458                      i(?{print "i1\n";})
2459                      s(?{print "s1\n";})
2460                          |
2461                      t(?{print "t2\n";})
2462                      h(?{print "h2\n";})
2463                      a(?{print "a2\n";})
2464                      t(?{print "t2\n";})
2465                      (?{print "Done at position ", pos, "\n";})
2466                     @x;
2467
2468 prints
2469
2470     Start at position 0
2471     t1
2472     h1
2473     t2
2474     h2
2475     a2
2476     t2
2477     Done at position 4
2478
2479 =head1 BUGS
2480
2481 Code expressions, conditional expressions, and independent expressions
2482 are B<experimental>.  Don't use them in production code.  Yet.
2483
2484 =head1 SEE ALSO
2485
2486 This is just a tutorial.  For the full story on perl regular
2487 expressions, see the L<perlre> regular expressions reference page.
2488
2489 For more information on the matching C<m//> and substitution C<s///>
2490 operators, see L<perlop/"Regexp Quote-Like Operators">.  For
2491 information on the C<split> operation, see L<perlfunc/split>.
2492
2493 For an excellent all-around resource on the care and feeding of
2494 regular expressions, see the book I<Mastering Regular Expressions> by
2495 Jeffrey Friedl (published by O'Reilly, ISBN 1556592-257-3).
2496
2497 =head1 AUTHOR AND COPYRIGHT
2498
2499 Copyright (c) 2000 Mark Kvale
2500 All rights reserved.
2501
2502 This document may be distributed under the same terms as Perl itself.
2503
2504 =head2 Acknowledgments
2505
2506 The inspiration for the stop codon DNA example came from the ZIP
2507 code example in chapter 7 of I<Mastering Regular Expressions>.
2508
2509 The author would like to thank Jeff Pinyan, Andrew Johnson, Peter
2510 Haworth, Ronald J Kimball, and Joe Smith for all their helpful
2511 comments.
2512
2513 =cut
2514