pod/perlfaq6.pod

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