pod/perlfaq6.pod

   1 =head1 NAME
   2
   3 perlfaq6 - Regular Expressions ($Revision: 8539 $)
   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                 $. = 0 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, regular expressions> X<compile, regular expressions>
 342
 343 (contributed by brian d foy)
 344
 345 The C</o> option for regular expressions (documented in L<perlop> and
 346 L<perlreref>) tells Perl to compile the regular expression only once.
 347 This is only useful when the pattern contains a variable. Perls 5.6
 348 and later handle this automatically if the pattern does not change.
 349
 350 Since the match operator C<m//>, the substitution operator C<s///>,
 351 and the regular expression quoting operator C<qr//> are double-quotish
 352 constructs, you can interpolate variables into the pattern. See the
 353 answer to "How can I quote a variable to use in a regex?" for more
 354 details.
 355
 356 This example takes a regular expression from the argument list and
 357 prints the lines of input that match it:
 358
 359         my $pattern = shift @ARGV;
 360
 361         while( <> ) {
 362                 print if m/$pattern/;
 363                 }
 364
 365 Versions of Perl prior to 5.6 would recompile the regular expression
 366 for each iteration, even if C<$pattern> had not changed. The C</o>
 367 would prevent this by telling Perl to compile the pattern the first
 368 time, then reuse that for subsequent iterations:
 369
 370         my $pattern = shift @ARGV;
 371
 372         while( <> ) {
 373                 print if m/$pattern/o; # useful for Perl < 5.6
 374                 }
 375
 376 In versions 5.6 and later, Perl won't recompile the regular expression
 377 if the variable hasn't changed, so you probably don't need the C</o>
 378 option. It doesn't hurt, but it doesn't help either. If you want any
 379 version of Perl to compile the regular expression only once even if
 380 the variable changes (thus, only using its initial value), you still
 381 need the C</o>.
 382
 383 You can watch Perl's regular expression engine at work to verify for
 384 yourself if Perl is recompiling a regular expression. The C<use re
 385 'debug'> pragma (comes with Perl 5.005 and later) shows the details.
 386 With Perls before 5.6, you should see C<re> reporting that its
 387 compiling the regular expression on each iteration. With Perl 5.6 or
 388 later, you should only see C<re> report that for the first iteration.
 389
 390         use re 'debug';
 391
 392         $regex = 'Perl';
 393         foreach ( qw(Perl Java Ruby Python) ) {
 394                 print STDERR "-" x 73, "\n";
 395                 print STDERR "Trying $_...\n";
 396                 print STDERR "\t$_ is good!\n" if m/$regex/;
 397                 }
 398
 399 =head2 How do I use a regular expression to strip C style comments from a file?
 400
 401 While this actually can be done, it's much harder than you'd think.
 402 For example, this one-liner
 403
 404         perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c
 405
 406 will work in many but not all cases.  You see, it's too simple-minded for
 407 certain kinds of C programs, in particular, those with what appear to be
 408 comments in quoted strings.  For that, you'd need something like this,
 409 created by Jeffrey Friedl and later modified by Fred Curtis.
 410
 411         $/ = undef;
 412         $_ = <>;
 413         s#/\*[^*]*\*+([^/*][^*]*\*+)*/|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#defined $2 ? $2 : ""#gse;
 414         print;
 415
 416 This could, of course, be more legibly written with the C</x> modifier, adding
 417 whitespace and comments.  Here it is expanded, courtesy of Fred Curtis.
 418
 419     s{
 420        /\*         ##  Start of /* ... */ comment
 421        [^*]*\*+    ##  Non-* followed by 1-or-more *'s
 422        (
 423          [^/*][^*]*\*+
 424        )*          ##  0-or-more things which don't start with /
 425                    ##    but do end with '*'
 426        /           ##  End of /* ... */ comment
 427
 428      |         ##     OR  various things which aren't comments:
 429
 430        (
 431          "           ##  Start of " ... " string
 432          (
 433            \\.           ##  Escaped char
 434          |               ##    OR
 435            [^"\\]        ##  Non "\
 436          )*
 437          "           ##  End of " ... " string
 438
 439        |         ##     OR
 440
 441          '           ##  Start of ' ... ' string
 442          (
 443            \\.           ##  Escaped char
 444          |               ##    OR
 445            [^'\\]        ##  Non '\
 446          )*
 447          '           ##  End of ' ... ' string
 448
 449        |         ##     OR
 450
 451          .           ##  Anything other char
 452          [^/"'\\]*   ##  Chars which doesn't start a comment, string or escape
 453        )
 454      }{defined $2 ? $2 : ""}gxse;
 455
 456 A slight modification also removes C++ comments, as long as they are not
 457 spread over multiple lines using a continuation character):
 458
 459         s#/\*[^*]*\*+([^/*][^*]*\*+)*/|//[^\n]*|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#defined $2 ? $2 : ""#gse;
 460
 461 =head2 Can I use Perl regular expressions to match balanced text?
 462 X<regex, matching balanced test> X<regexp, matching balanced test>
 463 X<regular expression, matching balanced test>
 464
 465 Historically, Perl regular expressions were not capable of matching
 466 balanced text.  As of more recent versions of perl including 5.6.1
 467 experimental features have been added that make it possible to do this.
 468 Look at the documentation for the (??{ }) construct in recent perlre manual
 469 pages to see an example of matching balanced parentheses.  Be sure to take
 470 special notice of the  warnings present in the manual before making use
 471 of this feature.
 472
 473 CPAN contains many modules that can be useful for matching text
 474 depending on the context.  Damian Conway provides some useful
 475 patterns in Regexp::Common.  The module Text::Balanced provides a
 476 general solution to this problem.
 477
 478 One of the common applications of balanced text matching is working
 479 with XML and HTML.  There are many modules available that support
 480 these needs.  Two examples are HTML::Parser and XML::Parser. There
 481 are many others.
 482
 483 An elaborate subroutine (for 7-bit ASCII only) to pull out balanced
 484 and possibly nested single chars, like C<`> and C<'>, C<{> and C<}>,
 485 or C<(> and C<)> can be found in
 486 http://www.cpan.org/authors/id/TOMC/scripts/pull_quotes.gz .
 487
 488 The C::Scan module from CPAN also contains such subs for internal use,
 489 but they are undocumented.
 490
 491 =head2 What does it mean that regexes are greedy?  How can I get around it?
 492 X<greedy> X<greediness>
 493
 494 Most people mean that greedy regexes match as much as they can.
 495 Technically speaking, it's actually the quantifiers (C<?>, C<*>, C<+>,
 496 C<{}>) that are greedy rather than the whole pattern; Perl prefers local
 497 greed and immediate gratification to overall greed.  To get non-greedy
 498 versions of the same quantifiers, use (C<??>, C<*?>, C<+?>, C<{}?>).
 499
 500 An example:
 501
 502         $s1 = $s2 = "I am very very cold";
 503         $s1 =~ s/ve.*y //;      # I am cold
 504         $s2 =~ s/ve.*?y //;     # I am very cold
 505
 506 Notice how the second substitution stopped matching as soon as it
 507 encountered "y ".  The C<*?> quantifier effectively tells the regular
 508 expression engine to find a match as quickly as possible and pass
 509 control on to whatever is next in line, like you would if you were
 510 playing hot potato.
 511
 512 =head2 How do I process each word on each line?
 513 X<word>
 514
 515 Use the split function:
 516
 517         while (<>) {
 518                 foreach $word ( split ) {
 519                         # do something with $word here
 520                 }
 521         }
 522
 523 Note that this isn't really a word in the English sense; it's just
 524 chunks of consecutive non-whitespace characters.
 525
 526 To work with only alphanumeric sequences (including underscores), you
 527 might consider
 528
 529         while (<>) {
 530                 foreach $word (m/(\w+)/g) {
 531                         # do something with $word here
 532                 }
 533         }
 534
 535 =head2 How can I print out a word-frequency or line-frequency summary?
 536
 537 To do this, you have to parse out each word in the input stream.  We'll
 538 pretend that by word you mean chunk of alphabetics, hyphens, or
 539 apostrophes, rather than the non-whitespace chunk idea of a word given
 540 in the previous question:
 541
 542         while (<>) {
 543                 while ( /(\b[^\W_\d][\w'-]+\b)/g ) {   # misses "`sheep'"
 544                         $seen{$1}++;
 545                 }
 546         }
 547
 548         while ( ($word, $count) = each %seen ) {
 549                 print "$count $word\n";
 550                 }
 551
 552 If you wanted to do the same thing for lines, you wouldn't need a
 553 regular expression:
 554
 555         while (<>) {
 556                 $seen{$_}++;
 557                 }
 558
 559         while ( ($line, $count) = each %seen ) {
 560                 print "$count $line";
 561         }
 562
 563 If you want these output in a sorted order, see L<perlfaq4>: "How do I
 564 sort a hash (optionally by value instead of key)?".
 565
 566 =head2 How can I do approximate matching?
 567 X<match, approximate> X<matching, approximate>
 568
 569 See the module String::Approx available from CPAN.
 570
 571 =head2 How do I efficiently match many regular expressions at once?
 572 X<regex, efficiency> X<regexp, efficiency>
 573 X<regular expression, efficiency>
 574
 575 ( contributed by brian d foy )
 576
 577 Avoid asking Perl to compile a regular expression every time
 578 you want to match it.  In this example, perl must recompile
 579 the regular expression for every iteration of the foreach()
 580 loop since it has no way to know what $pattern will be.
 581
 582         @patterns = qw( foo bar baz );
 583
 584         LINE: while( <DATA> )
 585                 {
 586                 foreach $pattern ( @patterns )
 587                         {
 588                         if( /\b$pattern\b/i )
 589                                 {
 590                                 print;
 591                                 next LINE;
 592                                 }
 593                         }
 594                 }
 595
 596 The qr// operator showed up in perl 5.005.  It compiles a
 597 regular expression, but doesn't apply it.  When you use the
 598 pre-compiled version of the regex, perl does less work. In
 599 this example, I inserted a map() to turn each pattern into
 600 its pre-compiled form.  The rest of the script is the same,
 601 but faster.
 602
 603         @patterns = map { qr/\b$_\b/i } qw( foo bar baz );
 604
 605         LINE: while( <> )
 606                 {
 607                 foreach $pattern ( @patterns )
 608                         {
 609                         print if /\b$pattern\b/i;
 610                         next LINE;
 611                         }
 612                 }
 613
 614 In some cases, you may be able to make several patterns into
 615 a single regular expression.  Beware of situations that require
 616 backtracking though.
 617
 618         $regex = join '|', qw( foo bar baz );
 619
 620         LINE: while( <> )
 621                 {
 622                 print if /\b(?:$regex)\b/i;
 623                 }
 624
 625 For more details on regular expression efficiency, see Mastering
 626 Regular Expressions by Jeffrey Freidl.  He explains how regular
 627 expressions engine work and why some patterns are surprisingly
 628 inefficient.  Once you understand how perl applies regular
 629 expressions, you can tune them for individual situations.
 630
 631 =head2 Why don't word-boundary searches with C<\b> work for me?
 632 X<\b>
 633
 634 (contributed by brian d foy)
 635
 636 Ensure that you know what \b really does: it's the boundary between a
 637 word character, \w, and something that isn't a word character. That
 638 thing that isn't a word character might be \W, but it can also be the
 639 start or end of the string.
 640
 641 It's not (not!) the boundary between whitespace and non-whitespace,
 642 and it's not the stuff between words we use to create sentences.
 643
 644 In regex speak, a word boundary (\b) is a "zero width assertion",
 645 meaning that it doesn't represent a character in the string, but a
 646 condition at a certain position.
 647
 648 For the regular expression, /\bPerl\b/, there has to be a word
 649 boundary before the "P" and after the "l".  As long as something other
 650 than a word character precedes the "P" and succeeds the "l", the
 651 pattern will match. These strings match /\bPerl\b/.
 652
 653         "Perl"    # no word char before P or after l
 654         "Perl "   # same as previous (space is not a word char)
 655         "'Perl'"  # the ' char is not a word char
 656         "Perl's"  # no word char before P, non-word char after "l"
 657
 658 These strings do not match /\bPerl\b/.
 659
 660         "Perl_"   # _ is a word char!
 661         "Perler"  # no word char before P, but one after l
 662
 663 You don't have to use \b to match words though.  You can look for
 664 non-word characters surrounded by word characters.  These strings
 665 match the pattern /\b'\b/.
 666
 667         "don't"   # the ' char is surrounded by "n" and "t"
 668         "qep'a'"  # the ' char is surrounded by "p" and "a"
 669
 670 These strings do not match /\b'\b/.
 671
 672         "foo'"    # there is no word char after non-word '
 673
 674 You can also use the complement of \b, \B, to specify that there
 675 should not be a word boundary.
 676
 677 In the pattern /\Bam\B/, there must be a word character before the "a"
 678 and after the "m". These patterns match /\Bam\B/:
 679
 680         "llama"   # "am" surrounded by word chars
 681         "Samuel"  # same
 682
 683 These strings do not match /\Bam\B/
 684
 685         "Sam"      # no word boundary before "a", but one after "m"
 686         "I am Sam" # "am" surrounded by non-word chars
 687
 688
 689 =head2 Why does using $&, $`, or $' slow my program down?
 690 X<$MATCH> X<$&> X<$POSTMATCH> X<$'> X<$PREMATCH> X<$`>
 691
 692 (contributed by Anno Siegel)
 693
 694 Once Perl sees that you need one of these variables anywhere in the
 695 program, it provides them on each and every pattern match. That means
 696 that on every pattern match the entire string will be copied, part of it
 697 to $`, part to $&, and part to $'. Thus the penalty is most severe with
 698 long strings and patterns that match often. Avoid $&, $', and $` if you
 699 can, but if you can't, once you've used them at all, use them at will
 700 because you've already paid the price. Remember that some algorithms
 701 really appreciate them. As of the 5.005 release, the $& variable is no
 702 longer "expensive" the way the other two are.
 703
 704 Since Perl 5.6.1 the special variables @- and @+ can functionally replace
 705 $`, $& and $'.  These arrays contain pointers to the beginning and end
 706 of each match (see perlvar for the full story), so they give you
 707 essentially the same information, but without the risk of excessive
 708 string copying.
 709
 710 =head2 What good is C<\G> in a regular expression?
 711 X<\G>
 712
 713 You use the C<\G> anchor to start the next match on the same
 714 string where the last match left off.  The regular
 715 expression engine cannot skip over any characters to find
 716 the next match with this anchor, so C<\G> is similar to the
 717 beginning of string anchor, C<^>.  The C<\G> anchor is typically
 718 used with the C<g> flag.  It uses the value of C<pos()>
 719 as the position to start the next match.  As the match
 720 operator makes successive matches, it updates C<pos()> with the
 721 position of the next character past the last match (or the
 722 first character of the next match, depending on how you like
 723 to look at it). Each string has its own C<pos()> value.
 724
 725 Suppose you want to match all of consecutive pairs of digits
 726 in a string like "1122a44" and stop matching when you
 727 encounter non-digits.  You want to match C<11> and C<22> but
 728 the letter <a> shows up between C<22> and C<44> and you want
 729 to stop at C<a>. Simply matching pairs of digits skips over
 730 the C<a> and still matches C<44>.
 731
 732         $_ = "1122a44";
 733         my @pairs = m/(\d\d)/g;   # qw( 11 22 44 )
 734
 735 If you use the C<\G> anchor, you force the match after C<22> to
 736 start with the C<a>.  The regular expression cannot match
 737 there since it does not find a digit, so the next match
 738 fails and the match operator returns the pairs it already
 739 found.
 740
 741         $_ = "1122a44";
 742         my @pairs = m/\G(\d\d)/g; # qw( 11 22 )
 743
 744 You can also use the C<\G> anchor in scalar context. You
 745 still need the C<g> flag.
 746
 747         $_ = "1122a44";
 748         while( m/\G(\d\d)/g )
 749                 {
 750                 print "Found $1\n";
 751                 }
 752
 753 After the match fails at the letter C<a>, perl resets C<pos()>
 754 and the next match on the same string starts at the beginning.
 755
 756         $_ = "1122a44";
 757         while( m/\G(\d\d)/g )
 758                 {
 759                 print "Found $1\n";
 760                 }
 761
 762         print "Found $1 after while" if m/(\d\d)/g; # finds "11"
 763
 764 You can disable C<pos()> resets on fail with the C<c> flag, documented
 765 in L<perlop> and L<perlreref>. Subsequent matches start where the last
 766 successful match ended (the value of C<pos()>) even if a match on the
 767 same string has failed in the meantime. In this case, the match after
 768 the C<while()> loop starts at the C<a> (where the last match stopped),
 769 and since it does not use any anchor it can skip over the C<a> to find
 770 C<44>.
 771
 772         $_ = "1122a44";
 773         while( m/\G(\d\d)/gc )
 774                 {
 775                 print "Found $1\n";
 776                 }
 777
 778         print "Found $1 after while" if m/(\d\d)/g; # finds "44"
 779
 780 Typically you use the C<\G> anchor with the C<c> flag
 781 when you want to try a different match if one fails,
 782 such as in a tokenizer. Jeffrey Friedl offers this example
 783 which works in 5.004 or later.
 784
 785         while (<>) {
 786                 chomp;
 787                 PARSER: {
 788                         m/ \G( \d+\b    )/gcx   && do { print "number: $1\n";  redo; };
 789                         m/ \G( \w+      )/gcx   && do { print "word:   $1\n";  redo; };
 790                         m/ \G( \s+      )/gcx   && do { print "space:  $1\n";  redo; };
 791                         m/ \G( [^\w\d]+ )/gcx   && do { print "other:  $1\n";  redo; };
 792                 }
 793         }
 794
 795 For each line, the C<PARSER> loop first tries to match a series
 796 of digits followed by a word boundary.  This match has to
 797 start at the place the last match left off (or the beginning
 798 of the string on the first match). Since C<m/ \G( \d+\b
 799 )/gcx> uses the C<c> flag, if the string does not match that
 800 regular expression, perl does not reset pos() and the next
 801 match starts at the same position to try a different
 802 pattern.
 803
 804 =head2 Are Perl regexes DFAs or NFAs?  Are they POSIX compliant?
 805 X<DFA> X<NFA> X<POSIX>
 806
 807 While it's true that Perl's regular expressions resemble the DFAs
 808 (deterministic finite automata) of the egrep(1) program, they are in
 809 fact implemented as NFAs (non-deterministic finite automata) to allow
 810 backtracking and backreferencing.  And they aren't POSIX-style either,
 811 because those guarantee worst-case behavior for all cases.  (It seems
 812 that some people prefer guarantees of consistency, even when what's
 813 guaranteed is slowness.)  See the book "Mastering Regular Expressions"
 814 (from O'Reilly) by Jeffrey Friedl for all the details you could ever
 815 hope to know on these matters (a full citation appears in
 816 L<perlfaq2>).
 817
 818 =head2 What's wrong with using grep in a void context?
 819 X<grep>
 820
 821 The problem is that grep builds a return list, regardless of the context.
 822 This means you're making Perl go to the trouble of building a list that
 823 you then just throw away. If the list is large, you waste both time and space.
 824 If your intent is to iterate over the list, then use a for loop for this
 825 purpose.
 826
 827 In perls older than 5.8.1, map suffers from this problem as well.
 828 But since 5.8.1, this has been fixed, and map is context aware - in void
 829 context, no lists are constructed.
 830
 831 =head2 How can I match strings with multibyte characters?
 832 X<regex, and multibyte characters> X<regexp, and multibyte characters>
 833 X<regular expression, and multibyte characters> X<martian> X<encoding, Martian>
 834
 835 Starting from Perl 5.6 Perl has had some level of multibyte character
 836 support.  Perl 5.8 or later is recommended.  Supported multibyte
 837 character repertoires include Unicode, and legacy encodings
 838 through the Encode module.  See L<perluniintro>, L<perlunicode>,
 839 and L<Encode>.
 840
 841 If you are stuck with older Perls, you can do Unicode with the
 842 C<Unicode::String> module, and character conversions using the
 843 C<Unicode::Map8> and C<Unicode::Map> modules.  If you are using
 844 Japanese encodings, you might try using the jperl 5.005_03.
 845
 846 Finally, the following set of approaches was offered by Jeffrey
 847 Friedl, whose article in issue #5 of The Perl Journal talks about
 848 this very matter.
 849
 850 Let's suppose you have some weird Martian encoding where pairs of
 851 ASCII uppercase letters encode single Martian letters (i.e. the two
 852 bytes "CV" make a single Martian letter, as do the two bytes "SG",
 853 "VS", "XX", etc.). Other bytes represent single characters, just like
 854 ASCII.
 855
 856 So, the string of Martian "I am CVSGXX!" uses 12 bytes to encode the
 857 nine characters 'I', ' ', 'a', 'm', ' ', 'CV', 'SG', 'XX', '!'.
 858
 859 Now, say you want to search for the single character C</GX/>. Perl
 860 doesn't know about Martian, so it'll find the two bytes "GX" in the "I
 861 am CVSGXX!"  string, even though that character isn't there: it just
 862 looks like it is because "SG" is next to "XX", but there's no real
 863 "GX".  This is a big problem.
 864
 865 Here are a few ways, all painful, to deal with it:
 866
 867         # Make sure adjacent "martian" bytes are no longer adjacent.
 868         $martian =~ s/([A-Z][A-Z])/ $1 /g;
 869
 870         print "found GX!\n" if $martian =~ /GX/;
 871
 872 Or like this:
 873
 874         @chars = $martian =~ m/([A-Z][A-Z]|[^A-Z])/g;
 875         # above is conceptually similar to:     @chars = $text =~ m/(.)/g;
 876         #
 877         foreach $char (@chars) {
 878         print "found GX!\n", last if $char eq 'GX';
 879         }
 880
 881 Or like this:
 882
 883         while ($martian =~ m/\G([A-Z][A-Z]|.)/gs) {  # \G probably unneeded
 884                 print "found GX!\n", last if $1 eq 'GX';
 885                 }
 886
 887 Here's another, slightly less painful, way to do it from Benjamin
 888 Goldberg, who uses a zero-width negative look-behind assertion.
 889
 890         print "found GX!\n" if  $martian =~ m/
 891                 (?<![A-Z])
 892                 (?:[A-Z][A-Z])*?
 893                 GX
 894                 /x;
 895
 896 This succeeds if the "martian" character GX is in the string, and fails
 897 otherwise.  If you don't like using (?<!), a zero-width negative
 898 look-behind assertion, you can replace (?<![A-Z]) with (?:^|[^A-Z]).
 899
 900 It does have the drawback of putting the wrong thing in $-[0] and $+[0],
 901 but this usually can be worked around.
 902
 903 =head2 How do I match a regular expression that's in a variable?
 904 X<regex, in variable> X<eval> X<regex> X<quotemeta> X<\Q, regex>
 905 X<\E, regex>, X<qr//>
 906
 907 (contributed by brian d foy)
 908
 909 We don't have to hard-code patterns into the match operator (or
 910 anything else that works with regular expressions). We can put the
 911 pattern in a variable for later use.
 912
 913 The match operator is a double quote context, so you can interpolate
 914 your variable just like a double quoted string. In this case, you
 915 read the regular expression as user input and store it in C<$regex>.
 916 Once you have the pattern in C<$regex>, you use that variable in the
 917 match operator.
 918
 919         chomp( my $regex = <STDIN> );
 920
 921         if( $string =~ m/$regex/ ) { ... }
 922
 923 Any regular expression special characters in C<$regex> are still
 924 special, and the pattern still has to be valid or Perl will complain.
 925 For instance, in this pattern there is an unpaired parenthesis.
 926
 927         my $regex = "Unmatched ( paren";
 928
 929         "Two parens to bind them all" =~ m/$regex/;
 930
 931 When Perl compiles the regular expression, it treats the parenthesis
 932 as the start of a memory match. When it doesn't find the closing
 933 parenthesis, it complains:
 934
 935         Unmatched ( in regex; marked by <-- HERE in m/Unmatched ( <-- HERE  paren/ at script line 3.
 936
 937 You can get around this in several ways depending on our situation.
 938 First, if you don't want any of the characters in the string to be
 939 special, you can escape them with C<quotemeta> before you use the string.
 940
 941         chomp( my $regex = <STDIN> );
 942         $regex = quotemeta( $regex );
 943
 944         if( $string =~ m/$regex/ ) { ... }
 945
 946 You can also do this directly in the match operator using the C<\Q>
 947 and C<\E> sequences. The C<\Q> tells Perl where to start escaping
 948 special characters, and the C<\E> tells it where to stop (see L<perlop>
 949 for more details).
 950
 951         chomp( my $regex = <STDIN> );
 952
 953         if( $string =~ m/\Q$regex\E/ ) { ... }
 954
 955 Alternately, you can use C<qr//>, the regular expression quote operator (see
 956 L<perlop> for more details).  It quotes and perhaps compiles the pattern,
 957 and you can apply regular expression flags to the pattern.
 958
 959         chomp( my $input = <STDIN> );
 960
 961         my $regex = qr/$input/is;
 962
 963         $string =~ m/$regex/  # same as m/$input/is;
 964
 965 You might also want to trap any errors by wrapping an C<eval> block
 966 around the whole thing.
 967
 968         chomp( my $input = <STDIN> );
 969
 970         eval {
 971                 if( $string =~ m/\Q$input\E/ ) { ... }
 972                 };
 973         warn $@ if $@;
 974
 975 Or...
 976
 977         my $regex = eval { qr/$input/is };
 978         if( defined $regex ) {
 979                 $string =~ m/$regex/;
 980                 }
 981         else {
 982                 warn $@;
 983                 }
 984
 985 =head1 REVISION
 986
 987 Revision: $Revision: 8539 $
 988
 989 Date: $Date: 2007-01-11 00:07:14 +0100 (Thu, 11 Jan 2007) $
 990
 991 See L<perlfaq> for source control details and availability.
 992
 993 =head1 AUTHOR AND COPYRIGHT
 994
 995 Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and
 996 other authors as noted. All rights reserved.
 997
 998 This documentation is free; you can redistribute it and/or modify it
 999 under the same terms as Perl itself.
1000
1001 Irrespective of its distribution, all code examples in this file
1002 are hereby placed into the public domain.  You are permitted and
1003 encouraged to use this code in your own programs for fun
1004 or for profit as you see fit.  A simple comment in the code giving
1005 credit would be courteous but is not required.