more pod updates from Tom Christiansen; regen perltoc

p4raw-id: //depot/perl@3462

1 files changed, 133 insertions, 117 deletions

diff --git a/pod/perlre.pod b/pod/perlre.pod
index 98d7b35066..ca95638605 100644
--- a/pod/perlre.pod
+++ b/pod/perlre.pod
@@ -27,7 +27,7 @@ locale.  See L<perllocale>.
 =item m
 
 Treat string as multiple lines.  That is, change "^" and "$" from matching
-at only the very start or end of the string to the start or end of any
+the start or end of the string to matching the start or end of any
 line anywhere within the string.
 
 =item s
@@ -50,9 +50,9 @@ Extend your pattern's legibility by permitting whitespace and comments.
 =back
 
 These are usually written as "the C</x> modifier", even though the delimiter
-in question might not actually be a slash.  In fact, any of these
+in question might not really be a slash.  Any of these
 modifiers may also be embedded within the regular expression itself using
-the new C<(?...)> construct.  See below.
+the C<(?...)> construct.  See below.
 
 The C</x> modifier itself needs a little more explanation.  It tells
 the regular expression parser to ignore whitespace that is neither
@@ -60,7 +60,7 @@ backslashed nor within a character class.  You can use this to break up
 your regular expression into (slightly) more readable parts.  The C<#>
 character is also treated as a metacharacter introducing a comment,
 just as in ordinary Perl code.  This also means that if you want real
-whitespace or C<#> characters in the pattern (outside of a character
+whitespace or C<#> characters in the pattern (outside a character
 class, where they are unaffected by C</x>), that you'll either have to 
 escape them or encode them using octal or hex escapes.  Taken together,
 these features go a long way towards making Perl's regular expressions
@@ -72,7 +72,7 @@ in L<perlop>.
 =head2 Regular Expressions
 
 The patterns used in Perl pattern matching derive from supplied in
-the Version 8 regex routines.  (In fact, the routines are derived
+the Version 8 regex routines.  (The routines are derived
 (distantly) from Henry Spencer's freely redistributable reimplementation
 of the V8 routines.)  See L<Version 8 Regular Expressions> for
 details.
@@ -88,9 +88,9 @@ meanings:
     ()	Grouping
     []	Character class
 
-By default, the "^" character is guaranteed to match at only the
-beginning of the string, the "$" character at only the end (or before the
-newline at the end) and Perl does certain optimizations with the
+By default, the "^" character is guaranteed to match only the
+beginning of the string, the "$" character only the end (or before the
+newline at the end), and Perl does certain optimizations with the
 assumption that the string contains only one line.  Embedded newlines
 will not be matched by "^" or "$".  You may, however, wish to treat a
 string as a multi-line buffer, such that the "^" will match after any
@@ -99,7 +99,7 @@ cost of a little more overhead, you can do this by using the /m modifier
 on the pattern match operator.  (Older programs did this by setting C<$*>,
 but this practice is now deprecated.)
 
-To facilitate multi-line substitutions, the "." character never matches a
+To simplify multi-line substitutions, the "." character never matches a
 newline unless you use the C</s> modifier, which in effect tells Perl to pretend
 the string is a single line--even if it isn't.  The C</s> modifier also
 overrides the setting of C<$*>, in case you have some (badly behaved) older
@@ -179,12 +179,12 @@ In addition, Perl defines the following:
     \C	Match a single C char (octet) even under utf8.
 
 A C<\w> matches a single alphanumeric character, not a whole word.
-To match a word you'd need to say C<\w+>.  If C<use locale> is in
-effect, the list of alphabetic characters generated by C<\w> is
-taken from the current locale.  See L<perllocale>. You may use
-C<\w>, C<\W>, C<\s>, C<\S>, C<\d>, and C<\D> within character classes
-(though not as either end of a range).  See L<utf8> for details
-about C<\pP>, C<\PP>, and C<\X>.
+Use C<\w+> to match a string of Perl-identifier characters (which isn't 
+the same as matching an English word).  If C<use locale> is in effect, the
+list of alphabetic characters generated by C<\w> is taken from the
+current locale.  See L<perllocale>.  You may use C<\w>, C<\W>, C<\s>, C<\S>,
+C<\d>, and C<\D> within character classes (though not as either end of
+a range).  See L<utf8> for details about C<\pP>, C<\PP>, and C<\X>.
 
 Perl defines the following zero-width assertions:
 
@@ -195,7 +195,7 @@ Perl defines the following zero-width assertions:
     \z	Match only at end of string
     \G	Match only where previous m//g left off (works only with /g)
 
-A word boundary (C<\b>) is defined as a spot between two characters
+A word boundary (C<\b>) is a spot between two characters
 that has a C<\w> on one side of it and a C<\W> on the other side
 of it (in either order), counting the imaginary characters off the
 beginning and end of the string as matching a C<\W>.  (Within
@@ -214,51 +214,63 @@ several patterns that you want to match against consequent substrings
 of your string, see the previous reference.  The actual location
 where C<\G> will match can also be influenced by using C<pos()> as
 an lvalue.  See L<perlfunc/pos>.
-
-When the bracketing construct C<( ... )> is used to create a capture
-buffer, \E<lt>digitE<gt> matches the digit'th substring.  Outside
-of the pattern, always use "$" instead of "\" in front of the digit.
-(While the \E<lt>digitE<gt> notation can on rare occasion work
-outside the current pattern, this should not be relied upon.  See
-the WARNING below.)  The scope of $E<lt>digitE<gt> (and C<$`>,
-C<$&>, and C<$'>) extends to the end of the enclosing BLOCK or eval
-string, or to the next successful pattern match, whichever comes
-first.  If you want to use parentheses to delimit a subpattern
-(e.g., a set of alternatives) without saving it as a subpattern,
-follow the ( with a ?:.
-
-You may have as many parentheses as you wish.  If you have more
-than 9 captured substrings, the variables $10, $11, ... refer to
-the corresponding substring.  Within the pattern, \10, \11, etc.
-refer back to substrings if there have been at least that many left
-parentheses before the backreference.  Otherwise (for backward
-compatibility) \10 is the same as \010, a backspace, and \11 the
-same as \011, a tab.  And so on.  (\1 through \9 are always
-backreferences.)
-
-C<$+> returns whatever the last bracket match matched.  C<$&> returns the
-entire matched string.  (C<$0> used to return the same thing, but not any
-more.)  C<$`> returns everything before the matched string.  C<$'> returns
-everything after the matched string.  Examples:
+  
+The bracketing construct C<( ... )> creates capture buffers.  To
+refer to the digit'th buffer use \E<lt>digitE<gt> within the
+match.  Outside the match use "$" instead of "\".  (The
+\E<lt>digitE<gt> notation works in certain circumstances outside 
+the match.  See the warning below about \1 vs $1 for details.)
+Referring back to another part of the match is called a
+I<backreference>.
+
+There is no limit to the number of captured substrings that you may
+use.  However Perl also uses \10, \11, etc. as aliases for \010,
+\011, etc.  (Recall that 0 means octal, so \011 is the 9'th ASCII
+character, a tab.)  Perl resolves this ambiguity by interpreting
+\10 as a backreference only if at least 10 left parentheses have
+opened before it.  Likewise \11 is a backreference only if at least
+11 left parentheses have opened before it.  And so on.  \1 through
+\9 are always interpreted as backreferences."
+
+Examples:
 
     s/^([^ ]*) *([^ ]*)/$2 $1/;     # swap first two words
 
-    if (/Time: (..):(..):(..)/) {
+     if (/(.)\1/) {                 # find first doubled char
+         print "'$1' is the first doubled character\n";
+     }
+ 
+    if (/Time: (..):(..):(..)/) {   # parse out values
 	$hours = $1;
 	$minutes = $2;
 	$seconds = $3;
     }
-
-Once Perl sees that you need one of C<$&>, C<$`> or C<$'> anywhere in
-the program, it has to provide them on each and every pattern match.
-This can slow your program down.  The same mechanism that handles
-these provides for the use of $1, $2, etc., so you pay the same price
-for each pattern that contains capturing parentheses.  But if you never
-use $&, etc., in your script, then patterns I<without> capturing
-parentheses won't be penalized.  So avoid $&, $', and $` if you can,
-but if you can't (and some algorithms really appreciate them), once
-you've used them once, use them at will, because you've already paid
-the price.  As of 5.005, $& is not so costly as the other two.
+  
+Several special variables also refer back to portions of the previous
+match.  C<$+> returns whatever the last bracket match matched.
+C<$&> returns the entire matched string.  (At one point C<$0> did
+also, but now it returns the name of the program.)  C<$`> returns
+everything before the matched string.  And C<$'> returns everything
+after the matched string.
+
+The numbered variables ($1, $2, $3, etc.) and the related punctuation
+set (C<<$+>, C<$&>, C<$`>, and C<$'>) are all dynamically scoped
+until the end of the enclosing block or until the next successful
+match, whichever comes first.  (See L<perlsyn/"Compound Statements">.)
+
+B<WARNING>: Once Perl sees that you need one of C<$&>, C<$`>, or
+C<$'> anywhere in the program, it has to provide them for every
+pattern match.  This may substantially slow your program.  Perl
+uses the same mechanism to produce $1, $2, etc, so you also pay a
+price for each pattern that contains capturing parentheses.  (To
+avoid this cost while retaining the grouping behaviour, use the
+extended regular expression C<(?: ... )> instead.)  But if you never
+use C<$&>, C<$`> or C<$'>, then patterns I<without> capturing
+parentheses will not be penalized.  So avoid C<$&>, C<$'>, and C<$`>
+if you can, but if you can't (and some algorithms really appreciate
+them), once you've used them once, use them at will, because you've
+already paid the price.  As of 5.005, C<$&> is not so costly as the
+other two.
 
 Backslashed metacharacters in Perl are alphanumeric, such as C<\b>,
 C<\w>, C<\n>.  Unlike some other regular expression languages, there
@@ -271,36 +283,36 @@ use for a pattern. Simply quote all non-alphanumeric characters:
 
     $pattern =~ s/(\W)/\\$1/g;
 
-In modern days, it is more common to see either the quotemeta()
-function or the C<\Q> metaquoting escape sequence used to disable
-all metacharacters' special meanings like this:
+Today it is more common to use the quotemeta() function or the C<\Q>
+metaquoting escape sequence to disable all metacharacters' special
+meanings like this:
 
     /$unquoted\Q$quoted\E$unquoted/
 
 =head2 Extended Patterns
 
-For those situations where simple regular expression patterns are
-not enough, Perl defines a consistent extension syntax for venturing
-beyond simple patterns such as are found in standard tools like
-B<awk> and B<lex>.  That syntax is a pair of parentheses with a
-question mark as the first thing within the parentheses (this was
-a syntax error in older versions of Perl).  The character after the
-question mark gives the function of the extension.  
+Perl also defines a consistent extension syntax for features not
+found in standard tools like B<awk> and B<lex>.  The syntax is a
+pair of parentheses with a question mark as the first thing within
+the parentheses.  The character after the question mark indicates
+the extension.
 
-Many extensions are already supported, some for almost five years
-now.  Other, more exotic forms are very new, and should be considered
-highly experimental, and are so marked.
+The stability of these extensions varies widely.  Some have been
+part of the core language for many years.  Others are experimental
+and may change without warning or be completely removed.  Check
+the documentation on an individual feature to verify its current
+status.
 
-A question mark was chosen for this and for the new minimal-matching
-construct because 1) question mark is pretty rare in older regular
-expressions, and 2) whenever you see one, you should stop and "question"
-exactly what is going on.  That's psychology...
+A question mark was chosen for this and for the minimal-matching
+construct because 1) question marks are rare in older regular
+expressions, and 2) whenever you see one, you should stop and
+"question" exactly what is going on.  That's psychology...
 
 =over 10
 
 =item C<(?#text)>
 
-A comment.  The text is ignored.  If the C</x> modifier is used to enable
+A comment.  The text is ignored.  If the C</x> modifier enables
 whitespace formatting, a simple C<#> will suffice.  Note that Perl closes
 the comment as soon as it sees a C<)>, so there is no way to put a literal
 C<)> in the comment.
@@ -328,7 +340,7 @@ localized inside an enclosing group (if any).  For example,
     ( (?i) blah ) \s+ \1
 
 will match a repeated (I<including the case>!) word C<blah> in any
-case, assuming C<x> modifier, and no C<i> modifier outside of this
+case, assuming C<x> modifier, and no C<i> modifier outside this
 group.
 
 =item C<(?:pattern)>
@@ -352,7 +364,7 @@ C<(?imsx-imsx)>.  For example,
 
     /(?s-i:more.*than).*million/i
 
-is equivalent to more verbose
+is equivalent to the more verbose
 
     /(?:(?s-i)more.*than).*million/i
 
@@ -420,7 +432,7 @@ C<local>ization are undone, so that
    >x;
 
 will set C<$res = 4>.  Note that after the match, $cnt returns to the globally
-introduced value, since the scopes which restrict C<local> operators
+introduced value, because the scopes that restrict C<local> operators
 are unwound.
 
 This assertion may be used as a C<(?(condition)yes-pattern|no-pattern)>
@@ -439,20 +451,20 @@ perilous C<use re 'eval'> pragma has been used (see L<re>), or the
 variables contain results of C<qr//> operator (see
 L<perlop/"qr/STRING/imosx">).  
 
-This restriction is due to the wide-spread and remarkably convenient
+This restriction is because of the wide-spread and remarkably convenient
 custom of using run-time determined strings as patterns.  For example:
 
     $re = <>;
     chomp $re;
     $string =~ /$re/;
 
-Prior to the execution of code in a pattern, this was completely
-safe from a security point of view, although it could of course
-raise an exception from an illegal pattern.  If you turn on the
-C<use re 'eval'>, though, it is no longer secure, so you should
-only do so if you are also using taint checking.  Better yet, use
-the carefully constrained evaluation within a Safe module.  See
-L<perlsec> for details about both these mechanisms.
+Before Perl knew how to execute interpolated code within a pattern,
+this operation was completely safe from a security point of view,
+although it could raise an exception from an illegal pattern.  If
+you turn on the C<use re 'eval'>, though, it is no longer secure,
+so you should only do so if you are also using taint checking.
+Better yet, use the carefully constrained evaluation within a Safe
+module.  See L<perlsec> for details about both these mechanisms.
 
 =item C<(?p{ code })>
 
@@ -486,7 +498,7 @@ highly experimental, and may be changed or deleted without notice.
 
 An "independent" subexpression, one which matches the substring
 that a I<standalone> C<pattern> would match if anchored at the given
-position -- but it matches no more than this substring.  This
+position--but it matches no more than this substring.  This
 construct is useful for optimizations of what would otherwise be
 "eternal" matches, because it will not backtrack (see L<"Backtracking">).
 
@@ -527,7 +539,7 @@ to a subpattern of the above pattern.  Consider how the pattern
 above detects no-match on C<((()aaaaaaaaaaaaaaaaaa> in several
 seconds, but that each extra letter doubles this time.  This
 exponential performance will make it appear that your program has
-hung.  However, a tiny modification of this pattern
+hung.  However, a tiny change to this pattern
 
     m{ \( 
 	  ( 
@@ -615,7 +627,7 @@ Which perhaps unexpectedly yields:
   got <d is under the bar in the >
 
 That's because C<.*> was greedy, so you get everything between the
-I<first> "foo" and the I<last> "bar".  In this case, it's more effective
+I<first> "foo" and the I<last> "bar".  Here it's more effective
 to use minimal matching to make sure you get the text between a "foo"
 and the first "bar" thereafter.
 
@@ -714,8 +726,9 @@ that you've asked "Is it true that at the start of $x, following 0 or more
 non-digits, you have something that's not 123?"  If the pattern matcher had
 let C<\D*> expand to "ABC", this would have caused the whole pattern to
 fail.
+
 The search engine will initially match C<\D*> with "ABC".  Then it will
-try to match C<(?!123> with "123", which of course fails.  But because
+try to match C<(?!123> with "123", which fails.  But because
 a quantifier (C<\D*>) has been used in the regular expression, the
 search engine can backtrack and retry the match differently
 in the hope of matching the complete regular expression.
@@ -723,13 +736,13 @@ in the hope of matching the complete regular expression.
 The pattern really, I<really> wants to succeed, so it uses the
 standard pattern back-off-and-retry and lets C<\D*> expand to just "AB" this
 time.  Now there's indeed something following "AB" that is not
-"123".  It's in fact "C123", which suffices.
+"123".  It's "C123", which suffices.
 
-We can deal with this by using both an assertion and a negation.  We'll
-say that the first part in $1 must be followed by a digit, and in fact, it
-must also be followed by something that's not "123".  Remember that the
-look-aheads are zero-width expressions--they only look, but don't consume
-any of the string in their match.  So rewriting this way produces what
+We can deal with this by using both an assertion and a negation.
+We'll say that the first part in $1 must be followed both by a digit
+and by something that's not "123".  Remember that the look-aheads
+are zero-width expressions--they only look, but don't consume any
+of the string in their match.  So rewriting this way produces what
 you'd expect; that is, case 5 will fail, but case 6 succeeds:
 
     print "5: got $1\n" if $x =~ /^(\D*)(?=\d)(?!123)/ ;
@@ -747,20 +760,20 @@ although the attempted matches are made at different positions because "a"
 is not a zero-width assertion, but a one-width assertion.
 
 B<WARNING>: particularly complicated regular expressions can take
-exponential time to solve due to the immense number of possible
+exponential time to solve because of the immense number of possible
 ways they can use backtracking to try match.  For example, this will
-take a very long time to run
+take a painfully long time to run
 
     /((a{0,5}){0,5}){0,5}/
 
-And if you used C<*>'s instead of limiting it to 0 through 5 matches, then
-it would take literally forever--or until you ran out of stack space.
+And if you used C<*>'s instead of limiting it to 0 through 5 matches,
+then it would take forever--or until you ran out of stack space.
 
 A powerful tool for optimizing such beasts is "independent" groups,
 which do not backtrace (see L<C<(?E<gt>pattern)>>).  Note also that
 zero-length look-ahead/look-behind assertions will not backtrace to make
-the tail match, since they are in "logical" context: only the fact
-whether they match or not is considered relevant.  For an example
+the tail match, since they are in "logical" context: only 
+whether they match is considered relevant.  For an example
 where side-effects of a look-ahead I<might> have influenced the
 following match, see L<C<(?E<gt>pattern)>>.
 
@@ -780,7 +793,7 @@ would match "blurfl" in the target string.
 You can specify a character class, by enclosing a list of characters
 in C<[]>, which will match any one character from the list.  If the
 first character after the "[" is "^", the class matches any character not
-in the list.  Within a list, the "-" character is used to specify a
+in the list.  Within a list, the "-" character specifies a
 range, so that C<a-z> represents all characters between "a" and "z",
 inclusive.  If you want "-" itself to be a member of a class, put it
 at the start or end of the list, or escape it with a backslash.  (The
@@ -810,8 +823,8 @@ or "foe" in the target string (as would C<f(e|i|o)e>).  The
 first alternative includes everything from the last pattern delimiter
 ("(", "[", or the beginning of the pattern) up to the first "|", and
 the last alternative contains everything from the last "|" to the next
-pattern delimiter.  For this reason, it's common practice to include
-alternatives in parentheses, to minimize confusion about where they
+pattern delimiter.  That's why it's common practice to include
+alternatives in parentheses: to minimize confusion about where they
 start and end.
 
 Alternatives are tried from left to right, so the first
@@ -825,16 +838,16 @@ important when you are capturing matched text using parentheses.)
 Also remember that "|" is interpreted as a literal within square brackets,
 so if you write C<[fee|fie|foe]> you're really only matching C<[feio|]>.
 
-Within a pattern, you may designate subpatterns for later reference by
-enclosing them in parentheses, and you may refer back to the I<n>th
-subpattern later in the pattern using the metacharacter \I<n>.
-Subpatterns are numbered based on the left to right order of their
-opening parenthesis.  A backreference matches whatever
-actually matched the subpattern in the string being examined, not the
-rules for that subpattern.  Therefore, C<(0|0x)\d*\s\1\d*> will
-match "0x1234 0x4321", but not "0x1234 01234", because subpattern 1
-actually matched "0x", even though the rule C<0|0x> could
-potentially match the leading 0 in the second number.
+Within a pattern, you may designate subpatterns for later reference
+by enclosing them in parentheses, and you may refer back to the
+I<n>th subpattern later in the pattern using the metacharacter
+\I<n>.  Subpatterns are numbered based on the left to right order
+of their opening parenthesis.  A backreference matches whatever
+actually matched the subpattern in the string being examined, not
+the rules for that subpattern.  Therefore, C<(0|0x)\d*\s\1\d*> will
+match "0x1234 0x4321", but not "0x1234 01234", because subpattern
+1 matched "0x", even though the rule C<0|0x> could potentially match
+the leading 0 in the second number.
 
 =head2 Warning on \1 vs $1
 
@@ -857,7 +870,7 @@ Or if you try to do
     s/(\d+)/\1000/;
 
 You can't disambiguate that by saying C<\{1}000>, whereas you can fix it with
-C<${1}000>.  Basically, the operation of interpolation should not be confused
+C<${1}000>.  The operation of interpolation should not be confused
 with the operation of matching a backreference.  Certainly they mean two
 different things on the I<left> side of the C<s///>.
 
@@ -876,7 +889,7 @@ loops using regular expressions, with something as innocuous as:
 
 The C<o?> can match at the beginning of C<'foo'>, and since the position
 in the string is not moved by the match, C<o?> would match again and again
-due to the C<*> modifier.  Another common way to create a similar cycle
+because of the C<*> modifier.  Another common way to create a similar cycle
 is with the looping modifier C<//g>:
 
     @matches = ( 'foo' =~ m{ o? }xg );
@@ -888,8 +901,8 @@ or
 or the loop implied by split().
 
 However, long experience has shown that many programming tasks may
-be significantly simplified by using repeated subexpressions which
-may match zero-length substrings, with a simple example being:
+be significantly simplified by using repeated subexpressions that
+may match zero-length substrings.  Here's a simple example being:
 
     @chars = split //, $string;		  # // is not magic in split
     ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// /
@@ -993,8 +1006,11 @@ L<perlop/"Regexp Quote-Like Operators">.
 
 L<perlop/"Gory details of parsing quoted constructs">.
 
+L<perlfaq6>.
+
 L<perlfunc/pos>.
 
 L<perllocale>.
 
-I<Mastering Regular Expressions> by Jeffrey Friedl.
+I<Mastering Regular Expressions> by Jeffrey Friedl, published
+by O'Reilly and Associates.