X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlop.pod;h=0acf7b902d73c7b76be2e64be18bd5d32a3b4bd1;hb=4f4d7508b0c2c114e5f52420e0e87a853c5f642a;hp=23f62e09ab6729f7b675070fa6dad790e6709da1;hpb=678ae90b5bfdcb408a7a5c2767d230d736624a6c;p=p5sagit%2Fp5-mst-13.2.git
diff --git a/pod/perlop.pod b/pod/perlop.pod
index 23f62e0..0acf7b9 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -235,9 +235,11 @@ of operation work on some other string. The right argument is a search
pattern, substitution, or transliteration. The left argument is what is
supposed to be searched, substituted, or transliterated instead of the default
$_. When used in scalar context, the return value generally indicates the
-success of the operation. Behavior in list context depends on the particular
-operator. See L"Regexp Quote-Like Operators"> for details and
-L for examples using these operators.
+success of the operation. Not always though: the non-destructive substitution
+option (C) causes the return value to be the result of the substition, for
+example. Behavior in list context depends on the particular operator. See
+L"Regexp Quote-Like Operators"> for details and L for examples
+using these operators.
If the right argument is an expression rather than a search pattern,
substitution, or transliteration, it is interpreted as a search pattern at run
@@ -251,6 +253,8 @@ pattern C<\>, which it will consider a syntax error.
Binary "!~" is just like "=~" except the return value is negated in
the logical sense.
+Binary "!~" is not permitted to bind to a non-destructive substitute (s///r).
+
=head2 Multiplicative Operators
X
@@ -556,33 +560,33 @@ like this:
# code
}
-The range operator also works on strings, using the magical auto-increment,
-see below.
+The range operator also works on strings, using the magical
+auto-increment, see below.
In scalar context, ".." returns a boolean value. The operator is
-bistable, like a flip-flop, and emulates the line-range (comma) operator
-of B, B, and various editors. Each ".." operator maintains its
-own boolean state. It is false as long as its left operand is false.
+bistable, like a flip-flop, and emulates the line-range (comma)
+operator of B, B, and various editors. Each ".." operator
+maintains its own boolean state, even across calls to a subroutine
+that contains it. It is false as long as its left operand is false.
Once the left operand is true, the range operator stays true until the
right operand is true, I which the range operator becomes false
-again. It doesn't become false till the next time the range operator is
-evaluated. It can test the right operand and become false on the same
-evaluation it became true (as in B), but it still returns true once.
-If you don't want it to test the right operand until the next
-evaluation, as in B, just use three dots ("...") instead of
+again. It doesn't become false till the next time the range operator
+is evaluated. It can test the right operand and become false on the
+same evaluation it became true (as in B), but it still returns
+true once. If you don't want it to test the right operand until the
+next evaluation, as in B, just use three dots ("...") instead of
two. In all other regards, "..." behaves just like ".." does.
The right operand is not evaluated while the operator is in the
"false" state, and the left operand is not evaluated while the
operator is in the "true" state. The precedence is a little lower
than || and &&. The value returned is either the empty string for
-false, or a sequence number (beginning with 1) for true. The
-sequence number is reset for each range encountered. The final
-sequence number in a range has the string "E0" appended to it, which
-doesn't affect its numeric value, but gives you something to search
-for if you want to exclude the endpoint. You can exclude the
-beginning point by waiting for the sequence number to be greater
-than 1.
+false, or a sequence number (beginning with 1) for true. The sequence
+number is reset for each range encountered. The final sequence number
+in a range has the string "E0" appended to it, which doesn't affect
+its numeric value, but gives you something to search for if you want
+to exclude the endpoint. You can exclude the beginning point by
+waiting for the sequence number to be greater than 1.
If either operand of scalar ".." is a constant expression,
that operand is considered true if it is equal (C<==>) to the current
@@ -602,10 +606,10 @@ Examples:
As a scalar operator:
if (101 .. 200) { print; } # print 2nd hundred lines, short for
- # if ($. == 101 .. $. == 200) ...
+ # if ($. == 101 .. $. == 200) { print; }
next LINE if (1 .. /^$/); # skip header lines, short for
- # ... if ($. == 1 .. /^$/);
+ # next LINE if ($. == 1 .. /^$/);
# (typically in a loop labeled LINE)
s/^/> / if (/^$/ .. eof()); # quote body
@@ -615,9 +619,9 @@ As a scalar operator:
$in_header = 1 .. /^$/;
$in_body = /^$/ .. eof;
if ($in_header) {
- # ...
+ # do something
} else { # in body
- # ...
+ # do something else
}
} continue {
close ARGV if eof; # reset $. each file
@@ -677,7 +681,8 @@ return an alpha:
To get lower-case greek letters, use this instead:
- my @greek_small = map { chr } ( ord("\N{alpha}") .. ord("\N{omega}") );
+ my @greek_small = map { chr } ( ord("\N{alpha}") ..
+ ord("\N{omega}") );
Because each operand is evaluated in integer form, C<2.18 .. 3.14> will
return two elements in list context.
@@ -816,16 +821,63 @@ between keys and values in hashes, and other paired elements in lists.
=head2 Yada Yada Operator
X<...> X<... operator> X
-The yada yada operator (noted C<...>) is a placeholder for code.
-It parses without error, but when executed it throws an exception
-with the text C:
-
- sub foo { ... }
- foo();
-
- Unimplemented at line .
-
-It takes no argument.
+The yada yada operator (noted C<...>) is a placeholder for code. Perl
+parses it without error, but when you try to execute a yada yada, it
+throws an exception with the text C:
+
+ sub unimplemented { ... }
+
+ eval { unimplemented() };
+ if( $@ eq 'Unimplemented' ) {
+ print "I found the yada yada!\n";
+ }
+
+You can only use the yada yada to stand in for a complete statement.
+These examples of the yada yada work:
+
+ { ... }
+
+ sub foo { ... }
+
+ ...;
+
+ eval { ... };
+
+ sub foo {
+ my( $self ) = shift;
+
+ ...;
+ }
+
+ do { my $n; ...; print 'Hurrah!' };
+
+The yada yada cannot stand in for an expression that is part of a
+larger statement since the C<...> is also the three-dot version of the
+range operator (see L). These examples of the yada
+yada are still syntax errors:
+
+ print ...;
+
+ open my($fh), '>', '/dev/passwd' or ...;
+
+ if( $condition && ... ) { print "Hello\n" };
+
+There are some cases where Perl can't immediately tell the difference
+between an expression and a statement. For instance, the syntax for a
+block and an anonymous hash reference constructor look the same unless
+there's something in the braces that give Perl a hint. The yada yada
+is a syntax error if Perl doesn't guess that the C<{ ... }> is a
+block. In that case, it doesn't think the C<...> is the yada yada
+because it's expecting an expression instead of a statement:
+
+ my @transformed = map { ... } @input; # syntax error
+
+You can use a C<;> inside your block to denote that the C<{ ... }> is
+a block and not a hash reference constructor. Now the yada yada works:
+
+ my @transformed = map {; ... } @input; # ; disambiguates
+
+ my @transformed = map { ...; } @input; # ; disambiguates
=head2 List Operators (Rightward)
X X
@@ -964,33 +1016,76 @@ from the next line. This allows you to write:
The following escape sequences are available in constructs that interpolate
and in transliterations.
-X<\t> X<\n> X<\r> X<\f> X<\b> X<\a> X<\e> X<\x> X<\0> X<\c> X<\N>
-
- \t tab (HT, TAB)
- \n newline (NL)
- \r return (CR)
- \f form feed (FF)
- \b backspace (BS)
- \a alarm (bell) (BEL)
- \e escape (ESC)
- \033 octal char (example: ESC)
- \x1b hex char (example: ESC)
- \x{263a} wide hex char (example: SMILEY)
- \c[ control char (example: ESC)
- \N{name} named Unicode character
-
-The character following C<\c> is mapped to some other character by
-converting letters to upper case and then (on ASCII systems) by inverting
-the 7th bit (0x40). The most interesting range is from '@' to '_'
-(0x40 through 0x5F), resulting in a control character from 0x00
-through 0x1F. A '?' maps to the DEL character. On EBCDIC systems only
-'@', the letters, '[', '\', ']', '^', '_' and '?' will work, resulting
-in 0x00 through 0x1F and 0x7F.
-
-B: Unlike C and other languages, Perl has no \v escape sequence for
-the vertical tab (VT - ASCII 11), but you may use C<\ck> or C<\x0b>.
+X<\t> X<\n> X<\r> X<\f> X<\b> X<\a> X<\e> X<\x> X<\0> X<\c> X<\N> X<\N{}>
+
+ Sequence Note Description
+ \t tab (HT, TAB)
+ \n newline (NL)
+ \r return (CR)
+ \f form feed (FF)
+ \b backspace (BS)
+ \a alarm (bell) (BEL)
+ \e escape (ESC)
+ \033 octal char (example: ESC)
+ \x1b hex char (example: ESC)
+ \x{263a} wide hex char (example: SMILEY)
+ \c[ [1] control char (example: chr(27))
+ \N{name} [2] named Unicode character
+ \N{U+263D} [3] Unicode character (example: FIRST QUARTER MOON)
-The following escape sequences are available in constructs that interpolate
+=over 4
+
+=item [1]
+
+The character following C<\c> is mapped to some other character as shown in the
+table:
+
+ Sequence Value
+ \c@ chr(0)
+ \cA chr(1)
+ \ca chr(1)
+ \cB chr(2)
+ \cb chr(2)
+ ...
+ \cZ chr(26)
+ \cz chr(26)
+ \c[ chr(27)
+ \c] chr(29)
+ \c^ chr(30)
+ \c? chr(127)
+
+Also, C<\c\I> yields C< chr(28) . "I"> for any I, but cannot come at the
+end of a string, because the backslash would be parsed as escaping the end
+quote.
+
+On ASCII platforms, the resulting characters from the list above are the
+complete set of ASCII controls. This isn't the case on EBCDIC platforms; see
+L for the complete list of what these
+sequences mean on both ASCII and EBCDIC platforms.
+
+Use of any other character following the "c" besides those listed above is
+discouraged, and may become deprecated or forbidden. What happens for those
+other characters currently though, is that the value is derived by inverting
+the 7th bit (0x40).
+
+To get platform independent controls, you can use C<\N{...}>.
+
+=item [2]
+
+For documentation of C<\N{name}>, see L.
+
+=item [3]
+
+C<\N{U+I}> means the Unicode character whose Unicode ordinal
+number is I.
+
+=back
+
+B: Unlike C and other languages, Perl has no C<\v> escape sequence for
+the vertical tab (VT - ASCII 11), but you may use C<\ck> or C<\x0b>. (C<\v>
+does have meaning in regular expression patterns in Perl, see L.)
+
+The following escape sequences are available in constructs that interpolate,
but not in transliterations.
X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q>
@@ -1005,8 +1100,7 @@ If C X
X X X X
+X X X X X X X X X X X
Searches a string for a pattern, and if found, replaces that pattern
with the replacement text and returns the number of substitutions
made. Otherwise it returns false (specifically, the empty string).
+If the C (non-destructive) option is used then it will perform the
+substitution on a copy of the string and return the copy whether or not a
+substitution occurred. The original string will always remain unchanged in
+this case. The copy will always be a plain string, even If the input is an
+object or a tied variable.
+
If no string is specified via the C<=~> or C operator, the C<$_>
variable is searched and modified. (The string specified with C<=~> must
be scalar variable, an array element, a hash element, or an assignment
@@ -1364,15 +1466,16 @@ Options are as with m// with the addition of the following replacement
specific options:
e Evaluate the right side as an expression.
- ee Evaluate the right side as a string then eval the result
-
-Any non-alphanumeric, non-whitespace delimiter may replace the
-slashes. If single quotes are used, no interpretation is done on the
-replacement string (the C modifier overrides this, however). Unlike
-Perl 4, Perl 5 treats backticks as normal delimiters; the replacement
-text is not evaluated as a command. If the
-PATTERN is delimited by bracketing quotes, the REPLACEMENT has its own
-pair of quotes, which may or may not be bracketing quotes, e.g.,
+ ee Evaluate the right side as a string then eval the result.
+ r Return substitution and leave the original string untouched.
+
+Any non-whitespace delimiter may replace the slashes. Add space after
+the C when using a character allowed in identifiers. If single quotes
+are used, no interpretation is done on the replacement string (the C
+modifier overrides this, however). Unlike Perl 4, Perl 5 treats backticks
+as normal delimiters; the replacement text is not evaluated as a command.
+If the PATTERN is delimited by bracketing quotes, the REPLACEMENT has
+its own pair of quotes, which may or may not be bracketing quotes, e.g.,
C or C<< s/bar/ >>. A C will cause the
replacement portion to be treated as a full-fledged Perl expression
and evaluated right then and there. It is, however, syntax checked at
@@ -1388,6 +1491,11 @@ Examples:
s/Login: $foo/Login: $bar/; # run-time pattern
($foo = $bar) =~ s/this/that/; # copy first, then change
+ ($foo = "$bar") =~ s/this/that/; # convert to string, copy, then change
+ $foo = $bar =~ s/this/that/r; # Same as above using /r
+ $foo = $bar =~ s/this/that/r
+ =~ s/that/the other/r; # Chained substitutes using /r
+ @foo = map { s/this/that/r } @bar # /r is very useful in maps
$count = ($paragraph =~ s/Mister\b/Mr./g); # get change-count
@@ -1400,6 +1508,10 @@ Examples:
s/%(.)/$percent{$1} || $&/ge; # expr now, so /e
s/^=(\w+)/pod($1)/ge; # use function call
+ $_ = 'abc123xyz';
+ $a = s/abc/def/r; # $a is 'def123xyz' and
+ # $_ remains 'abc123xyz'.
+
# expand variables in $_, but dynamics only, using
# symbolic dereferencing
s/\$(\w+)/${$1}/g;
@@ -1804,7 +1916,7 @@ must be sure there is a newline after it; otherwise, Perl will give the
warning B.
Additionally, the quoting rules for the end of string identifier are not
-related to Perl's quoting rules -- C, C, and the like are not
+related to Perl's quoting rules. C, C, and the like are not
supported in place of C<''> and C<"">, and the only interpolation is for
backslashing the quoting character:
@@ -2019,6 +2131,11 @@ is emitted if the C