pod/perlfaq6.pod

   1 =head1 NAME
   2
   3 perlfaq6 - Regular Expressions ($Revision: 1.20 $, $Date: 2003/01/03 20:05:28 $)
   4
   5 =head1 DESCRIPTION
   6
   7 This section is surprisingly small because the rest of the FAQ is
   8 littered with answers involving regular expressions.  For example,
   9 decoding a URL and checking whether something is a number are handled
  10 with regular expressions, but those answers are found elsewhere in
  11 this document (in L<perlfaq9>: ``How do I decode or create those %-encodings
  12 on the web'' and L<perlfaq4>: ``How do I determine whether a scalar is
  13 a number/whole/integer/float'', to be precise).
  14
  15 =head2 How can I hope to use regular expressions without creating illegible and unmaintainable code?
  16
  17 Three techniques can make regular expressions maintainable and
  18 understandable.
  19
  20 =over 4
  21
  22 =item Comments Outside the Regex
  23
  24 Describe what you're doing and how you're doing it, using normal Perl
  25 comments.
  26
  27     # turn the line into the first word, a colon, and the
  28     # number of characters on the rest of the line
  29     s/^(\w+)(.*)/ lc($1) . ":" . length($2) /meg;
  30
  31 =item Comments Inside the Regex
  32
  33 The C</x> modifier causes whitespace to be ignored in a regex pattern
  34 (except in a character class), and also allows you to use normal
  35 comments there, too.  As you can imagine, whitespace and comments help
  36 a lot.
  37
  38 C</x> lets you turn this:
  39
  40     s{<(?:[^>'"]*|".*?"|'.*?')+>}{}gs;
  41
  42 into this:
  43
  44     s{ <                    # opening angle bracket
  45         (?:                 # Non-backreffing grouping paren
  46              [^>'"] *       # 0 or more things that are neither > nor ' nor "
  47                 |           #    or else
  48              ".*?"          # a section between double quotes (stingy match)
  49                 |           #    or else
  50              '.*?'          # a section between single quotes (stingy match)
  51         ) +                 #   all occurring one or more times
  52        >                    # closing angle bracket
  53     }{}gsx;                 # replace with nothing, i.e. delete
  54
  55 It's still not quite so clear as prose, but it is very useful for
  56 describing the meaning of each part of the pattern.
  57
  58 =item Different Delimiters
  59
  60 While we normally think of patterns as being delimited with C</>
  61 characters, they can be delimited by almost any character.  L<perlre>
  62 describes this.  For example, the C<s///> above uses braces as
  63 delimiters.  Selecting another delimiter can avoid quoting the
  64 delimiter within the pattern:
  65
  66     s/\/usr\/local/\/usr\/share/g;      # bad delimiter choice
  67     s#/usr/local#/usr/share#g;          # better
  68
  69 =back
  70
  71 =head2 I'm having trouble matching over more than one line.  What's wrong?
  72
  73 Either you don't have more than one line in the string you're looking
  74 at (probably), or else you aren't using the correct modifier(s) on
  75 your pattern (possibly).
  76
  77 There are many ways to get multiline data into a string.  If you want
  78 it to happen automatically while reading input, you'll want to set $/
  79 (probably to '' for paragraphs or C<undef> for the whole file) to
  80 allow you to read more than one line at a time.
  81
  82 Read L<perlre> to help you decide which of C</s> and C</m> (or both)
  83 you might want to use: C</s> allows dot to include newline, and C</m>
  84 allows caret and dollar to match next to a newline, not just at the
  85 end of the string.  You do need to make sure that you've actually
  86 got a multiline string in there.
  87
  88 For example, this program detects duplicate words, even when they span
  89 line breaks (but not paragraph ones).  For this example, we don't need
  90 C</s> because we aren't using dot in a regular expression that we want
  91 to cross line boundaries.  Neither do we need C</m> because we aren't
  92 wanting caret or dollar to match at any point inside the record next
  93 to newlines.  But it's imperative that $/ be set to something other
  94 than the default, or else we won't actually ever have a multiline
  95 record read in.
  96
  97     $/ = '';            # read in more whole paragraph, not just one line
  98     while ( <> ) {
  99         while ( /\b([\w'-]+)(\s+\1)+\b/gi ) {   # word starts alpha
 100             print "Duplicate $1 at paragraph $.\n";
 101         }
 102     }
 103
 104 Here's code that finds sentences that begin with "From " (which would
 105 be mangled by many mailers):
 106
 107     $/ = '';            # read in more whole paragraph, not just one line
 108     while ( <> ) {
 109         while ( /^From /gm ) { # /m makes ^ match next to \n
 110             print "leading from in paragraph $.\n";
 111         }
 112     }
 113
 114 Here's code that finds everything between START and END in a paragraph:
 115
 116     undef $/;           # read in whole file, not just one line or paragraph
 117     while ( <> ) {
 118         while ( /START(.*?)END/sgm ) { # /s makes . cross line boundaries
 119             print "$1\n";
 120         }
 121     }
 122
 123 =head2 How can I pull out lines between two patterns that are themselves on different lines?
 124
 125 You can use Perl's somewhat exotic C<..> operator (documented in
 126 L<perlop>):
 127
 128     perl -ne 'print if /START/ .. /END/' file1 file2 ...
 129
 130 If you wanted text and not lines, you would use
 131
 132     perl -0777 -ne 'print "$1\n" while /START(.*?)END/gs' file1 file2 ...
 133
 134 But if you want nested occurrences of C<START> through C<END>, you'll
 135 run up against the problem described in the question in this section
 136 on matching balanced text.
 137
 138 Here's another example of using C<..>:
 139
 140     while (<>) {
 141         $in_header =   1  .. /^$/;
 142         $in_body   = /^$/ .. eof();
 143         # now choose between them
 144     } continue {
 145         reset if eof();         # fix $.
 146     }
 147
 148 =head2 I put a regular expression into $/ but it didn't work. What's wrong?
 149
 150 Up to Perl 5.8.0, $/ has to be a string.  This may change in 5.10,
 151 but don't get your hopes up. Until then, you can use these examples
 152 if you really need to do this.
 153
 154 Use the four argument form of sysread to continually add to
 155 a buffer.  After you add to the buffer, you check if you have a
 156 complete line (using your regular expression).
 157
 158        local $_ = "";
 159        while( sysread FH, $_, 8192, length ) {
 160           while( s/^((?s).*?)your_pattern/ ) {
 161              my $record = $1;
 162              # do stuff here.
 163           }
 164        }
 165
 166  You can do the same thing with foreach and a match using the
 167  c flag and the \G anchor, if you do not mind your entire file
 168  being in memory at the end.
 169
 170        local $_ = "";
 171        while( sysread FH, $_, 8192, length ) {
 172           foreach my $record ( m/\G((?s).*?)your_pattern/gc ) {
 173              # do stuff here.
 174           }
 175           substr( $_, 0, pos ) = "" if pos;
 176        }
 177
 178
 179 =head2 How do I substitute case insensitively on the LHS while preserving case on the RHS?
 180
 181 Here's a lovely Perlish solution by Larry Rosler.  It exploits
 182 properties of bitwise xor on ASCII strings.
 183
 184     $_= "this is a TEsT case";
 185
 186     $old = 'test';
 187     $new = 'success';
 188
 189     s{(\Q$old\E)}
 190      { uc $new | (uc $1 ^ $1) .
 191         (uc(substr $1, -1) ^ substr $1, -1) x
 192             (length($new) - length $1)
 193      }egi;
 194
 195     print;
 196
 197 And here it is as a subroutine, modeled after the above:
 198
 199     sub preserve_case($$) {
 200         my ($old, $new) = @_;
 201         my $mask = uc $old ^ $old;
 202
 203         uc $new | $mask .
 204             substr($mask, -1) x (length($new) - length($old))
 205     }
 206
 207     $a = "this is a TEsT case";
 208     $a =~ s/(test)/preserve_case($1, "success")/egi;
 209     print "$a\n";
 210
 211 This prints:
 212
 213     this is a SUcCESS case
 214
 215 As an alternative, to keep the case of the replacement word if it is
 216 longer than the original, you can use this code, by Jeff Pinyan:
 217
 218   sub preserve_case {
 219     my ($from, $to) = @_;
 220     my ($lf, $lt) = map length, @_;
 221
 222     if ($lt < $lf) { $from = substr $from, 0, $lt }
 223     else { $from .= substr $to, $lf }
 224
 225     return uc $to | ($from ^ uc $from);
 226   }
 227
 228 This changes the sentence to "this is a SUcCess case."
 229
 230 Just to show that C programmers can write C in any programming language,
 231 if you prefer a more C-like solution, the following script makes the
 232 substitution have the same case, letter by letter, as the original.
 233 (It also happens to run about 240% slower than the Perlish solution runs.)
 234 If the substitution has more characters than the string being substituted,
 235 the case of the last character is used for the rest of the substitution.
 236
 237     # Original by Nathan Torkington, massaged by Jeffrey Friedl
 238     #
 239     sub preserve_case($$)
 240     {
 241         my ($old, $new) = @_;
 242         my ($state) = 0; # 0 = no change; 1 = lc; 2 = uc
 243         my ($i, $oldlen, $newlen, $c) = (0, length($old), length($new));
 244         my ($len) = $oldlen < $newlen ? $oldlen : $newlen;
 245
 246         for ($i = 0; $i < $len; $i++) {
 247             if ($c = substr($old, $i, 1), $c =~ /[\W\d_]/) {
 248                 $state = 0;
 249             } elsif (lc $c eq $c) {
 250                 substr($new, $i, 1) = lc(substr($new, $i, 1));
 251                 $state = 1;
 252             } else {
 253                 substr($new, $i, 1) = uc(substr($new, $i, 1));
 254                 $state = 2;
 255             }
 256         }
 257         # finish up with any remaining new (for when new is longer than old)
 258         if ($newlen > $oldlen) {
 259             if ($state == 1) {
 260                 substr($new, $oldlen) = lc(substr($new, $oldlen));
 261             } elsif ($state == 2) {
 262                 substr($new, $oldlen) = uc(substr($new, $oldlen));
 263             }
 264         }
 265         return $new;
 266     }
 267
 268 =head2 How can I make C<\w> match national character sets?
 269
 270 Put C<use locale;> in your script.  The \w character class is taken
 271 from the current locale.
 272
 273 See L<perllocale> for details.
 274
 275 =head2 How can I match a locale-smart version of C</[a-zA-Z]/>?
 276
 277 You can use the POSIX character class syntax C</[[:alpha:]]/>
 278 documented in L<perlre>.
 279
 280 No matter which locale you are in, the alphabetic characters are
 281 the characters in \w without the digits and the underscore.
 282 As a regex, that looks like C</[^\W\d_]/>.  Its complement,
 283 the non-alphabetics, is then everything in \W along with
 284 the digits and the underscore, or C</[\W\d_]/>.
 285
 286 =head2 How can I quote a variable to use in a regex?
 287
 288 The Perl parser will expand $variable and @variable references in
 289 regular expressions unless the delimiter is a single quote.  Remember,
 290 too, that the right-hand side of a C<s///> substitution is considered
 291 a double-quoted string (see L<perlop> for more details).  Remember
 292 also that any regex special characters will be acted on unless you
 293 precede the substitution with \Q.  Here's an example:
 294
 295     $string = "Placido P. Octopus";
 296     $regex  = "P.";
 297
 298     $string =~ s/$regex/Polyp/;
 299     # $string is now "Polypacido P. Octopus"
 300
 301 Because C<.> is special in regular expressions, and can match any
 302 single character, the regex C<P.> here has matched the <Pl> in the
 303 original string.
 304
 305 To escape the special meaning of C<.>, we use C<\Q>:
 306
 307     $string = "Placido P. Octopus";
 308     $regex  = "P.";
 309
 310     $string =~ s/\Q$regex/Polyp/;
 311     # $string is now "Placido Polyp Octopus"
 312
 313 The use of C<\Q> causes the <.> in the regex to be treated as a
 314 regular character, so that C<P.> matches a C<P> followed by a dot.
 315
 316 =head2 What is C</o> really for?
 317
 318 Using a variable in a regular expression match forces a re-evaluation
 319 (and perhaps recompilation) each time the regular expression is
 320 encountered.  The C</o> modifier locks in the regex the first time
 321 it's used.  This always happens in a constant regular expression, and
 322 in fact, the pattern was compiled into the internal format at the same
 323 time your entire program was.
 324
 325 Use of C</o> is irrelevant unless variable interpolation is used in
 326 the pattern, and if so, the regex engine will neither know nor care
 327 whether the variables change after the pattern is evaluated the I<very
 328 first> time.
 329
 330 C</o> is often used to gain an extra measure of efficiency by not
 331 performing subsequent evaluations when you know it won't matter
 332 (because you know the variables won't change), or more rarely, when
 333 you don't want the regex to notice if they do.
 334
 335 For example, here's a "paragrep" program:
 336
 337     $/ = '';  # paragraph mode
 338     $pat = shift;
 339     while (<>) {
 340         print if /$pat/o;
 341     }
 342
 343 =head2 How do I use a regular expression to strip C style comments from a file?
 344
 345 While this actually can be done, it's much harder than you'd think.
 346 For example, this one-liner
 347
 348     perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c
 349
 350 will work in many but not all cases.  You see, it's too simple-minded for
 351 certain kinds of C programs, in particular, those with what appear to be
 352 comments in quoted strings.  For that, you'd need something like this,
 353 created by Jeffrey Friedl and later modified by Fred Curtis.
 354
 355     $/ = undef;
 356     $_ = <>;
 357     s#/\*[^*]*\*+([^/*][^*]*\*+)*/|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#$2#gs
 358     print;
 359
 360 This could, of course, be more legibly written with the C</x> modifier, adding
 361 whitespace and comments.  Here it is expanded, courtesy of Fred Curtis.
 362
 363     s{
 364        /\*         ##  Start of /* ... */ comment
 365        [^*]*\*+    ##  Non-* followed by 1-or-more *'s
 366        (
 367          [^/*][^*]*\*+
 368        )*          ##  0-or-more things which don't start with /
 369                    ##    but do end with '*'
 370        /           ##  End of /* ... */ comment
 371
 372      |         ##     OR  various things which aren't comments:
 373
 374        (
 375          "           ##  Start of " ... " string
 376          (
 377            \\.           ##  Escaped char
 378          |               ##    OR
 379            [^"\\]        ##  Non "\
 380          )*
 381          "           ##  End of " ... " string
 382
 383        |         ##     OR
 384
 385          '           ##  Start of ' ... ' string
 386          (
 387            \\.           ##  Escaped char
 388          |               ##    OR
 389            [^'\\]        ##  Non '\
 390          )*
 391          '           ##  End of ' ... ' string
 392
 393        |         ##     OR
 394
 395          .           ##  Anything other char
 396          [^/"'\\]*   ##  Chars which doesn't start a comment, string or escape
 397        )
 398      }{$2}gxs;
 399
 400 A slight modification also removes C++ comments:
 401
 402     s#/\*[^*]*\*+([^/*][^*]*\*+)*/|//[^\n]*|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#$2#gs;
 403
 404 =head2 Can I use Perl regular expressions to match balanced text?
 405
 406 Historically, Perl regular expressions were not capable of matching
 407 balanced text.  As of more recent versions of perl including 5.6.1
 408 experimental features have been added that make it possible to do this.
 409 Look at the documentation for the (??{ }) construct in recent perlre manual
 410 pages to see an example of matching balanced parentheses.  Be sure to take
 411 special notice of the  warnings present in the manual before making use
 412 of this feature.
 413
 414 CPAN contains many modules that can be useful for matching text
 415 depending on the context.  Damian Conway provides some useful
 416 patterns in Regexp::Common.  The module Text::Balanced provides a
 417 general solution to this problem.
 418
 419 One of the common applications of balanced text matching is working
 420 with XML and HTML.  There are many modules available that support
 421 these needs.  Two examples are HTML::Parser and XML::Parser. There
 422 are many others.
 423
 424 An elaborate subroutine (for 7-bit ASCII only) to pull out balanced
 425 and possibly nested single chars, like C<`> and C<'>, C<{> and C<}>,
 426 or C<(> and C<)> can be found in
 427 http://www.cpan.org/authors/id/TOMC/scripts/pull_quotes.gz .
 428
 429 The C::Scan module from CPAN also contains such subs for internal use,
 430 but they are undocumented.
 431
 432 =head2 What does it mean that regexes are greedy?  How can I get around it?
 433
 434 Most people mean that greedy regexes match as much as they can.
 435 Technically speaking, it's actually the quantifiers (C<?>, C<*>, C<+>,
 436 C<{}>) that are greedy rather than the whole pattern; Perl prefers local
 437 greed and immediate gratification to overall greed.  To get non-greedy
 438 versions of the same quantifiers, use (C<??>, C<*?>, C<+?>, C<{}?>).
 439
 440 An example:
 441
 442         $s1 = $s2 = "I am very very cold";
 443         $s1 =~ s/ve.*y //;      # I am cold
 444         $s2 =~ s/ve.*?y //;     # I am very cold
 445
 446 Notice how the second substitution stopped matching as soon as it
 447 encountered "y ".  The C<*?> quantifier effectively tells the regular
 448 expression engine to find a match as quickly as possible and pass
 449 control on to whatever is next in line, like you would if you were
 450 playing hot potato.
 451
 452 =head2 How do I process each word on each line?
 453
 454 Use the split function:
 455
 456     while (<>) {
 457         foreach $word ( split ) {
 458             # do something with $word here
 459         }
 460     }
 461
 462 Note that this isn't really a word in the English sense; it's just
 463 chunks of consecutive non-whitespace characters.
 464
 465 To work with only alphanumeric sequences (including underscores), you
 466 might consider
 467
 468     while (<>) {
 469         foreach $word (m/(\w+)/g) {
 470             # do something with $word here
 471         }
 472     }
 473
 474 =head2 How can I print out a word-frequency or line-frequency summary?
 475
 476 To do this, you have to parse out each word in the input stream.  We'll
 477 pretend that by word you mean chunk of alphabetics, hyphens, or
 478 apostrophes, rather than the non-whitespace chunk idea of a word given
 479 in the previous question:
 480
 481     while (<>) {
 482         while ( /(\b[^\W_\d][\w'-]+\b)/g ) {   # misses "`sheep'"
 483             $seen{$1}++;
 484         }
 485     }
 486     while ( ($word, $count) = each %seen ) {
 487         print "$count $word\n";
 488     }
 489
 490 If you wanted to do the same thing for lines, you wouldn't need a
 491 regular expression:
 492
 493     while (<>) {
 494         $seen{$_}++;
 495     }
 496     while ( ($line, $count) = each %seen ) {
 497         print "$count $line";
 498     }
 499
 500 If you want these output in a sorted order, see L<perlfaq4>: ``How do I
 501 sort a hash (optionally by value instead of key)?''.
 502
 503 =head2 How can I do approximate matching?
 504
 505 See the module String::Approx available from CPAN.
 506
 507 =head2 How do I efficiently match many regular expressions at once?
 508
 509 The following is extremely inefficient:
 510
 511     # slow but obvious way
 512     @popstates = qw(CO ON MI WI MN);
 513     while (defined($line = <>)) {
 514         for $state (@popstates) {
 515             if ($line =~ /\b$state\b/i) {
 516                 print $line;
 517                 last;
 518             }
 519         }
 520     }
 521
 522 That's because Perl has to recompile all those patterns for each of
 523 the lines of the file.  As of the 5.005 release, there's a much better
 524 approach, one which makes use of the new C<qr//> operator:
 525
 526     # use spiffy new qr// operator, with /i flag even
 527     use 5.005;
 528     @popstates = qw(CO ON MI WI MN);
 529     @poppats   = map { qr/\b$_\b/i } @popstates;
 530     while (defined($line = <>)) {
 531         for $patobj (@poppats) {
 532             print $line if $line =~ /$patobj/;
 533         }
 534     }
 535
 536 =head2 Why don't word-boundary searches with C<\b> work for me?
 537
 538 Two common misconceptions are that C<\b> is a synonym for C<\s+> and
 539 that it's the edge between whitespace characters and non-whitespace
 540 characters.  Neither is correct.  C<\b> is the place between a C<\w>
 541 character and a C<\W> character (that is, C<\b> is the edge of a
 542 "word").  It's a zero-width assertion, just like C<^>, C<$>, and all
 543 the other anchors, so it doesn't consume any characters.  L<perlre>
 544 describes the behavior of all the regex metacharacters.
 545
 546 Here are examples of the incorrect application of C<\b>, with fixes:
 547
 548     "two words" =~ /(\w+)\b(\w+)/;          # WRONG
 549     "two words" =~ /(\w+)\s+(\w+)/;         # right
 550
 551     " =matchless= text" =~ /\b=(\w+)=\b/;   # WRONG
 552     " =matchless= text" =~ /=(\w+)=/;       # right
 553
 554 Although they may not do what you thought they did, C<\b> and C<\B>
 555 can still be quite useful.  For an example of the correct use of
 556 C<\b>, see the example of matching duplicate words over multiple
 557 lines.
 558
 559 An example of using C<\B> is the pattern C<\Bis\B>.  This will find
 560 occurrences of "is" on the insides of words only, as in "thistle", but
 561 not "this" or "island".
 562
 563 =head2 Why does using $&, $`, or $' slow my program down?
 564
 565 Once Perl sees that you need one of these variables anywhere in
 566 the program, it provides them on each and every pattern match.
 567 The same mechanism that handles these provides for the use of $1, $2,
 568 etc., so you pay the same price for each regex that contains capturing
 569 parentheses.  If you never use $&, etc., in your script, then regexes
 570 I<without> capturing parentheses won't be penalized. So avoid $&, $',
 571 and $` if you can, but if you can't, once you've used them at all, use
 572 them at will because you've already paid the price.  Remember that some
 573 algorithms really appreciate them.  As of the 5.005 release.  the $&
 574 variable is no longer "expensive" the way the other two are.
 575
 576 =head2 What good is C<\G> in a regular expression?
 577
 578 You use the C<\G> anchor to start the next match on the same
 579 string where the last match left off.  The regular
 580 expression engine cannot skip over any characters to find
 581 the next match with this anchor, so C<\G> is similar to the
 582 beginning of string anchor, C<^>.  The C<\G> anchor is typically
 583 used with the C<g> flag.  It uses the value of pos()
 584 as the position to start the next match.  As the match
 585 operator makes successive matches, it updates pos() with the
 586 position of the next character past the last match (or the
 587 first character of the next match, depending on how you like
 588 to look at it). Each string has its own pos() value.
 589
 590 Suppose you want to match all of consective pairs of digits
 591 in a string like "1122a44" and stop matching when you
 592 encounter non-digits.  You want to match C<11> and C<22> but
 593 the letter <a> shows up between C<22> and C<44> and you want
 594 to stop at C<a>. Simply matching pairs of digits skips over
 595 the C<a> and still matches C<44>.
 596
 597         $_ = "1122a44";
 598         my @pairs = m/(\d\d)/g;   # qw( 11 22 44 )
 599
 600 If you use the \G anchor, you force the match after C<22> to
 601 start with the C<a>.  The regular expression cannot match
 602 there since it does not find a digit, so the next match
 603 fails and the match operator returns the pairs it already
 604 found.
 605
 606         $_ = "1122a44";
 607         my @pairs = m/\G(\d\d)/g; # qw( 11 22 )
 608
 609 You can also use the C<\G> anchor in scalar context. You
 610 still need the C<g> flag.
 611
 612         $_ = "1122a44";
 613         while( m/\G(\d\d)/g )
 614                 {
 615                 print "Found $1\n";
 616                 }
 617
 618 After the match fails at the letter C<a>, perl resets pos()
 619 and the next match on the same string starts at the beginning.
 620
 621         $_ = "1122a44";
 622         while( m/\G(\d\d)/g )
 623                 {
 624                 print "Found $1\n";
 625                 }
 626
 627         print "Found $1 after while" if m/(\d\d)/g; # finds "11"
 628
 629 You can disable pos() resets on fail with the C<c> flag.
 630 Subsequent matches start where the last successful match
 631 ended (the value of pos()) even if a match on the same
 632 string as failed in the meantime. In this case, the match
 633 after the while() loop starts at the C<a> (where the last
 634 match stopped), and since it does not use any anchor it can
 635 skip over the C<a> to find "44".
 636
 637         $_ = "1122a44";
 638         while( m/\G(\d\d)/gc )
 639                 {
 640                 print "Found $1\n";
 641                 }
 642
 643         print "Found $1 after while" if m/(\d\d)/g; # finds "44"
 644
 645 Typically you use the C<\G> anchor with the C<c> flag
 646 when you want to try a different match if one fails,
 647 such as in a tokenizer. Jeffrey Friedl offers this example
 648 which works in 5.004 or later.
 649
 650     while (<>) {
 651       chomp;
 652       PARSER: {
 653            m/ \G( \d+\b    )/gcx   && do { print "number: $1\n";  redo; };
 654            m/ \G( \w+      )/gcx   && do { print "word:   $1\n";  redo; };
 655            m/ \G( \s+      )/gcx   && do { print "space:  $1\n";  redo; };
 656            m/ \G( [^\w\d]+ )/gcx   && do { print "other:  $1\n";  redo; };
 657       }
 658     }
 659
 660 For each line, the PARSER loop first tries to match a series
 661 of digits followed by a word boundary.  This match has to
 662 start at the place the last match left off (or the beginning
 663 of the string on the first match). Since C<m/ \G( \d+\b
 664 )/gcx> uses the C<c> flag, if the string does not match that
 665 regular expression, perl does not reset pos() and the next
 666 match starts at the same position to try a different
 667 pattern.
 668
 669 =head2 Are Perl regexes DFAs or NFAs?  Are they POSIX compliant?
 670
 671 While it's true that Perl's regular expressions resemble the DFAs
 672 (deterministic finite automata) of the egrep(1) program, they are in
 673 fact implemented as NFAs (non-deterministic finite automata) to allow
 674 backtracking and backreferencing.  And they aren't POSIX-style either,
 675 because those guarantee worst-case behavior for all cases.  (It seems
 676 that some people prefer guarantees of consistency, even when what's
 677 guaranteed is slowness.)  See the book "Mastering Regular Expressions"
 678 (from O'Reilly) by Jeffrey Friedl for all the details you could ever
 679 hope to know on these matters (a full citation appears in
 680 L<perlfaq2>).
 681
 682 =head2 What's wrong with using grep in a void context?
 683
 684 The problem is that grep builds a return list, regardless of the context.
 685 This means you're making Perl go to the trouble of building a list that
 686 you then just throw away. If the list is large, you waste both time and space.
 687 If your intent is to iterate over the list, then use a for loop for this
 688 purpose.
 689
 690 In perls older than 5.8.1, map suffers from this problem as well.
 691 But since 5.8.1, this has been fixed, and map is context aware - in void
 692 context, no lists are constructed.
 693
 694 =head2 How can I match strings with multibyte characters?
 695
 696 Starting from Perl 5.6 Perl has had some level of multibyte character
 697 support.  Perl 5.8 or later is recommended.  Supported multibyte
 698 character repertoires include Unicode, and legacy encodings
 699 through the Encode module.  See L<perluniintro>, L<perlunicode>,
 700 and L<Encode>.
 701
 702 If you are stuck with older Perls, you can do Unicode with the
 703 C<Unicode::String> module, and character conversions using the
 704 C<Unicode::Map8> and C<Unicode::Map> modules.  If you are using
 705 Japanese encodings, you might try using the jperl 5.005_03.
 706
 707 Finally, the following set of approaches was offered by Jeffrey
 708 Friedl, whose article in issue #5 of The Perl Journal talks about
 709 this very matter.
 710
 711 Let's suppose you have some weird Martian encoding where pairs of
 712 ASCII uppercase letters encode single Martian letters (i.e. the two
 713 bytes "CV" make a single Martian letter, as do the two bytes "SG",
 714 "VS", "XX", etc.). Other bytes represent single characters, just like
 715 ASCII.
 716
 717 So, the string of Martian "I am CVSGXX!" uses 12 bytes to encode the
 718 nine characters 'I', ' ', 'a', 'm', ' ', 'CV', 'SG', 'XX', '!'.
 719
 720 Now, say you want to search for the single character C</GX/>. Perl
 721 doesn't know about Martian, so it'll find the two bytes "GX" in the "I
 722 am CVSGXX!"  string, even though that character isn't there: it just
 723 looks like it is because "SG" is next to "XX", but there's no real
 724 "GX".  This is a big problem.
 725
 726 Here are a few ways, all painful, to deal with it:
 727
 728    $martian =~ s/([A-Z][A-Z])/ $1 /g; # Make sure adjacent ``martian''
 729                                       # bytes are no longer adjacent.
 730    print "found GX!\n" if $martian =~ /GX/;
 731
 732 Or like this:
 733
 734    @chars = $martian =~ m/([A-Z][A-Z]|[^A-Z])/g;
 735    # above is conceptually similar to:     @chars = $text =~ m/(.)/g;
 736    #
 737    foreach $char (@chars) {
 738        print "found GX!\n", last if $char eq 'GX';
 739    }
 740
 741 Or like this:
 742
 743    while ($martian =~ m/\G([A-Z][A-Z]|.)/gs) {  # \G probably unneeded
 744        print "found GX!\n", last if $1 eq 'GX';
 745    }
 746
 747 Here's another, slightly less painful, way to do it from Benjamin
 748 Goldberg:
 749
 750         $martian =~ m/
 751            (?!<[A-Z])
 752            (?:[A-Z][A-Z])*?
 753            GX
 754         /x;
 755
 756 This succeeds if the "martian" character GX is in the string, and fails
 757 otherwise.  If you don't like using (?!<), you can replace (?!<[A-Z])
 758 with (?:^|[^A-Z]).
 759
 760 It does have the drawback of putting the wrong thing in $-[0] and $+[0],
 761 but this usually can be worked around.
 762
 763 =head2 How do I match a pattern that is supplied by the user?
 764
 765 Well, if it's really a pattern, then just use
 766
 767     chomp($pattern = <STDIN>);
 768     if ($line =~ /$pattern/) { }
 769
 770 Alternatively, since you have no guarantee that your user entered
 771 a valid regular expression, trap the exception this way:
 772
 773     if (eval { $line =~ /$pattern/ }) { }
 774
 775 If all you really want to search for a string, not a pattern,
 776 then you should either use the index() function, which is made for
 777 string searching, or if you can't be disabused of using a pattern
 778 match on a non-pattern, then be sure to use C<\Q>...C<\E>, documented
 779 in L<perlre>.
 780
 781     $pattern = <STDIN>;
 782
 783     open (FILE, $input) or die "Couldn't open input $input: $!; aborting";
 784     while (<FILE>) {
 785         print if /\Q$pattern\E/;
 786     }
 787     close FILE;
 788
 789 =head1 AUTHOR AND COPYRIGHT
 790
 791 Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington.
 792 All rights reserved.
 793
 794 This documentation is free; you can redistribute it and/or modify it
 795 under the same terms as Perl itself.
 796
 797 Irrespective of its distribution, all code examples in this file
 798 are hereby placed into the public domain.  You are permitted and
 799 encouraged to use this code in your own programs for fun
 800 or for profit as you see fit.  A simple comment in the code giving
 801 credit would be courteous but is not required.