additional documentation for qr//

	Message-Id: <199811260751.CAA24560@monk.mps.ohio-state.edu>
	Subject: [PATCH 5.005_*] Documentation (fwd)

p4raw-id: //depot/perl@2366

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 58d372a..370353b 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2804,7 +2804,7 @@ but is more efficient.  Returns the new number of elements in the array.
 
 =item qw/STRING/
 
-Generalized quotes.  See L<perlop>.
+Generalized quotes.  See L<perlop/"Regexp Quote-Like Operators">.
 
 =item quotemeta EXPR
 

diff --git a/pod/perlop.pod b/pod/perlop.pod
index 8e50ec3..857b951 100644 (file)
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -910,12 +910,47 @@ A double-quoted, interpolated string.
 
 =item qr/STRING/imosx
 
-A string which is (possibly) interpolated and then compiled as a
-regular expression. The result may be used as a pattern in a match
+Quote-as-a-regular-expression operator.  I<STRING> is interpolated the
+same way as I<PATTERN> in C<m/PATTERN/>.  Returns a Perl value which
+may be used instead of the corresponding C</STRING/imosx> expression.
+
+For example,
+
+    $rex = qr/my.STRING/is;
+    s/$rex/foo/;
+
+is equivalent to
+
+    s/my.STRING/foo/is;
+
+The result may be used as a subpattern in a match:
 
     $re = qr/$pattern/;
     $string =~ /foo${re}bar/;  # can be interpolated in other patterns
     $string =~ $re;            # or used standalone
+    $string =~ /$re/;          # or this way
+
+Since Perl may compile the pattern at the moment of execution of qr()
+operator, using qr() may have speed advantages in I<some> situations,
+notably if the result of qr() is used standalone:
+
+    sub match {
+       my $patterns = shift;
+       my @compiled = map qr/$_/i, @$patterns;
+       grep {
+           my $success = 0;
+           foreach my $pat @compiled {
+               $success = 1, last if /$pat/;
+           }
+           $success;
+       } @_;
+    }
+
+Precompilation of the pattern into an internal representation at the
+moment of qr() avoids a need to recompile the pattern every time a
+match C</$pat/> is attempted.  (Note that Perl has many other
+internal optimizations, but none would be triggered in the above
+example if we did not use qr() operator.)
 
 Options are:
 
@@ -925,19 +960,6 @@ Options are:
     s  Treat string as single line.
     x  Use extended regular expressions.
 
-The benefit from this is that the pattern is precompiled into an internal
-representation, and does not need to be recompiled every time a match
-is attempted.  This makes it very efficient to do something like:
-
-    foreach $pattern (@pattern_list) {
-       my $re = qr/$pattern/;
-       foreach $line (@lines) {
-           if($line =~ /$re/) {
-               do_something($line);
-           }
-       }
-    }
-
 See L<perlre> for additional information on valid syntax for STRING, and
 for a detailed look at the semantics of regular expressions.
 

diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index d20d62d..7fa8290 100644 (file)
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -171,7 +171,8 @@ here and in commands:
                                        (the quotes are optional)
                    L</"sec">           ditto
                same as above but only 'text' is used for output.
-               (Text can not contain the characters '|' or '>')
+               (Text can not contain the characters '/' and '|', 
+               and should contain matched '<' or '>')
                    L<text|name>
                    L<text|name/ident>
                    L<text|name/"sec">
@@ -184,6 +185,8 @@ here and in commands:
     E<escape>   A named character (very similar to HTML escapes)
                    E<lt>               A literal <
                    E<gt>               A literal >
+                   E<sol>              A literal /
+                   E<verbar>           A literal |
                    (these are optional except in other interior
                     sequences and when preceded by a capital letter)
                    E<n>                Character number n (probably in ASCII)