diff options
Diffstat (limited to 'pod/perlre.pod')
| -rw-r--r-- | pod/perlre.pod | 250 |
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. |