summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/pods/perlop.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlop.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlop.pod914
1 files changed, 617 insertions, 297 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlop.pod b/Master/tlpkg/tlperl/lib/pods/perlop.pod
index ebe32fb3102..665a6b58aba 100644
--- a/Master/tlpkg/tlperl/lib/pods/perlop.pod
+++ b/Master/tlpkg/tlperl/lib/pods/perlop.pod
@@ -152,7 +152,7 @@ value.
Note that just as in C, Perl doesn't define B<when> the variable is
incremented or decremented. You just know it will be done sometime
before or after the value is returned. This also means that modifying
-a variable twice in the same statement will lead to undefined behaviour.
+a variable twice in the same statement will lead to undefined behavior.
Avoid statements like:
$i = $i ++;
@@ -168,10 +168,10 @@ has a value that is not the empty string and matches the pattern
C</^[a-zA-Z]*[0-9]*\z/>, the increment is done as a string, preserving each
character within its range, with carry:
- print ++($foo = '99'); # prints '100'
- print ++($foo = 'a0'); # prints 'a1'
- print ++($foo = 'Az'); # prints 'Ba'
- print ++($foo = 'zz'); # prints 'aaa'
+ print ++($foo = "99"); # prints "100"
+ print ++($foo = "a0"); # prints "a1"
+ print ++($foo = "Az"); # prints "Ba"
+ print ++($foo = "zz"); # prints "aaa"
C<undef> is always treated as numeric, and in particular is changed
to C<0> before incrementing (so that a post-increment of an undef value
@@ -194,11 +194,12 @@ Unary "!" performs logical negation, i.e., "not". See also C<not> for a lower
precedence version of this.
X<!>
-Unary "-" performs arithmetic negation if the operand is numeric. If
-the operand is an identifier, a string consisting of a minus sign
-concatenated with the identifier is returned. Otherwise, if the string
-starts with a plus or minus, a string starting with the opposite sign
-is returned. One effect of these rules is that -bareword is equivalent
+Unary "-" performs arithmetic negation if the operand is numeric,
+including any string that looks like a number. If the operand is
+an identifier, a string consisting of a minus sign concatenated
+with the identifier is returned. Otherwise, if the string starts
+with a plus or minus, a string starting with the opposite sign is
+returned. One effect of these rules is that -bareword is equivalent
to the string "-bareword". If, however, the string begins with a
non-alphabetic character (excluding "+" or "-"), Perl will attempt to convert
the string to a numeric and the arithmetic negation is performed. If the
@@ -211,9 +212,15 @@ example, C<0666 & ~027> is 0640. (See also L<Integer Arithmetic> and
L<Bitwise String Operators>.) Note that the width of the result is
platform-dependent: ~0 is 32 bits wide on a 32-bit platform, but 64
bits wide on a 64-bit platform, so if you are expecting a certain bit
-width, remember to use the & operator to mask off the excess bits.
+width, remember to use the "&" operator to mask off the excess bits.
X<~> X<negation, binary>
+When complementing strings, if all characters have ordinal values under
+256, then their complements will, also. But if they do not, all
+characters will be in either 32- or 64-bit complements, depending on your
+architecture. So for example, C<~"\x{3B1}"> is C<"\x{FFFF_FC4E}"> on
+32-bit machines and C<"\x{FFFF_FFFF_FFFF_FC4E}"> on 64-bit machines.
+
Unary "+" has no effect whatsoever, even on strings. It is useful
syntactically for separating a function name from a parenthesized expression
that would otherwise be interpreted as the complete list of function
@@ -235,9 +242,12 @@ 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<perlretut> for examples using these operators.
+success of the operation. The exceptions are substitution (s///)
+and transliteration (y///) with the C</r> (non-destructive) option,
+which cause the B<r>eturn value to be the result of the substitution.
+Behavior in list context depends on the particular operator.
+See L</"Regexp Quote-Like Operators"> for details and L<perlretut> 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 +261,9 @@ pattern C<\>, which it will consider a syntax error.
Binary "!~" is just like "=~" except the return value is negated in
the logical sense.
+Binary "!~" with a non-destructive substitution (s///r) or transliteration
+(y///r) is a syntax error.
+
=head2 Multiplicative Operators
X<operator, multiplicative>
@@ -503,17 +516,20 @@ Although it has no direct equivalent in C, Perl's C<//> operator is related
to its C-style or. In fact, it's exactly the same as C<||>, except that it
tests the left hand side's definedness instead of its truth. Thus, C<$a // $b>
is similar to C<defined($a) || $b> (except that it returns the value of C<$a>
-rather than the value of C<defined($a)>) and is exactly equivalent to
-C<defined($a) ? $a : $b>. This is very useful for providing default values
-for variables. If you actually want to test if at least one of C<$a> and
-C<$b> is defined, use C<defined($a // $b)>.
+rather than the value of C<defined($a)>) and yields the same result as
+C<defined($a) ? $a : $b> (except that the ternary-operator form can be
+used as a lvalue, while C<$a // $b> cannot). This is very useful for
+providing default values for variables. If you actually want to test if
+at least one of C<$a> and C<$b> is defined, use C<defined($a // $b)>.
The C<||>, C<//> and C<&&> operators return the last value evaluated
(unlike C's C<||> and C<&&>, which return 0 or 1). Thus, a reasonably
portable way to find out the home directory might be:
- $home = $ENV{'HOME'} // $ENV{'LOGDIR'} //
- (getpwuid($<))[7] // die "You're homeless!\n";
+ $home = $ENV{HOME}
+ // $ENV{LOGDIR}
+ // (getpwuid($<))[7]
+ // die "You're homeless!\n";
In particular, this means that you shouldn't use this
for selecting between two aggregates for assignment:
@@ -602,7 +618,7 @@ Examples:
As a scalar operator:
if (101 .. 200) { print; } # print 2nd hundred lines, short for
- # if ($. == 101 .. $. == 200) { print; }
+ # if ($. == 101 .. $. == 200) { print; }
next LINE if (1 .. /^$/); # skip header lines, short for
# next LINE if ($. == 1 .. /^$/);
@@ -651,15 +667,15 @@ The range operator (in list context) makes use of the magical
auto-increment algorithm if the operands are strings. You
can say
- @alphabet = ('A' .. 'Z');
+ @alphabet = ("A" .. "Z");
to get all normal letters of the English alphabet, or
- $hexdigit = (0 .. 9, 'a' .. 'f')[$num & 15];
+ $hexdigit = (0 .. 9, "a" .. "f")[$num & 15];
to get a hexadecimal digit, or
- @z2 = ('01' .. '31'); print $z2[$mday];
+ @z2 = ("01" .. "31"); print $z2[$mday];
to get dates with leading zeros.
@@ -668,16 +684,23 @@ increment would produce, the sequence goes until the next value would
be longer than the final value specified.
If the initial value specified isn't part of a magical increment
-sequence (that is, a non-empty string matching "/^[a-zA-Z]*[0-9]*\z/"),
+sequence (that is, a non-empty string matching C</^[a-zA-Z]*[0-9]*\z/>),
only the initial value will be returned. So the following will only
return an alpha:
- use charnames 'greek';
+ use charnames "greek";
my @greek_small = ("\N{alpha}" .. "\N{omega}");
-To get lower-case greek letters, use this instead:
+To get the 25 traditional lowercase Greek letters, including both sigmas,
+you could use this instead:
- my @greek_small = map { chr } ( ord("\N{alpha}") .. ord("\N{omega}") );
+ use charnames "greek";
+ my @greek_small = map { chr }
+ ord "\N{alpha}" .. ord "\N{omega}";
+
+However, because there are I<many> other lowercase Greek characters than
+just those, to match lowercase Greek characters in a regular expression,
+you would use the pattern C</(?:(?=\p{Greek})\p{Lower})+/>.
Because each operand is evaluated in integer form, C<2.18 .. 3.14> will
return two elements in list context.
@@ -693,7 +716,7 @@ argument before the : is returned, otherwise the argument after the :
is returned. For example:
printf "I have %d dog%s.\n", $n,
- ($n == 1) ? '' : "s";
+ ($n == 1) ? "" : "s";
Scalar or list context propagates downward into the 2nd
or 3rd argument, whichever is selected.
@@ -756,7 +779,7 @@ Modifying an assignment is equivalent to doing the assignment and
then modifying the variable that was assigned to. This is useful
for modifying a copy of something, like this:
- ($tmp = $global) =~ tr [A-Z] [a-z];
+ ($tmp = $global) =~ tr [0-9] [a-j];
Likewise,
@@ -772,6 +795,72 @@ lvalues assigned to, and a list assignment in scalar context returns
the number of elements produced by the expression on the right hand
side of the assignment.
+=head2 The Triple-Dot Operator
+X<...> X<... operator> X<yada-yada operator> X<whatever operator>
+X<triple-dot operator>
+
+The triple-dot operator, C<...>, sometimes called the "whatever operator", the
+"yada-yada operator", or the "I<et cetera>" operator, is a placeholder for
+code. Perl parses it without error, but when you try to execute a whatever,
+it throws an exception with the text C<Unimplemented>:
+
+ sub unimplemented { ... }
+
+ eval { unimplemented() };
+ if ($@ eq "Unimplemented" ) {
+ say "Oh look, an exception--whatever.";
+ }
+
+You can only use the triple-dot operator to stand in for a complete statement.
+These examples of the triple-dot work:
+
+ { ... }
+
+ sub foo { ... }
+
+ ...;
+
+ eval { ... };
+
+ sub foo {
+ my ($self) = shift;
+ ...;
+ }
+
+ do {
+ my $variable;
+ ...;
+ say "Hurrah!";
+ } while $cheering;
+
+The yada-yada--or whatever--cannot stand in for an expression that is
+part of a larger statement since the C<...> is also the three-dot version
+of the binary range operator (see L<Range Operators>). These examples of
+the whatever operator are still syntax errors:
+
+ print ...;
+
+ open(PASSWD, ">", "/dev/passwd") or ...;
+
+ if ($condition && ...) { say "Hello" }
+
+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 whatever
+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 whatever
+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 whatever works:
+
+ my @transformed = map {; ... } @input; # ; disambiguates
+
+ my @transformed = map { ...; } @input; # ; disambiguates
+
=head2 Comma Operator
X<comma> X<operator, comma> X<,>
@@ -788,7 +877,7 @@ its left operand to be interpreted as a string if it begins with a letter
or underscore and is composed only of letters, digits and underscores.
This includes operands that might otherwise be interpreted as operators,
constants, single number v-strings or function calls. If in doubt about
-this behaviour, the left operand can be quoted explicitly.
+this behavior, the left operand can be quoted explicitly.
Otherwise, the C<< => >> operator behaves exactly as the comma operator
or list argument separator, according to context.
@@ -813,78 +902,17 @@ between keys and values in hashes, and other paired elements in lists.
%hash = ( $key => $value );
login( $username => $password );
-=head2 Yada Yada Operator
-X<...> X<... operator> X<yada yada operator>
-
-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<Unimplemented>:
-
- 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<Range Operators>). 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<operator, list, rightward> X<list operator>
-On the right side of a list operator, it has very low precedence,
+On the right side of a list operator, the comma has very low precedence,
such that it controls all comma-separated expressions found there.
The only operators with lower precedence are the logical operators
"and", "or", and "not", which may be used to evaluate calls to list
operators without the need for extra parentheses:
- open HANDLE, "filename"
- or die "Can't open: $!\n";
+ open HANDLE, "< $file"
+ or die "Can't open $file: $!\n";
See also discussion of list operators in L<Terms and List Operators (Leftward)>.
@@ -898,8 +926,8 @@ It's the equivalent of "!" except for the very low precedence.
X<operator, logical, and> X<and>
Binary "and" returns the logical conjunction of the two surrounding
-expressions. It's equivalent to && except for the very low
-precedence. This means that it short-circuits: i.e., the right
+expressions. It's equivalent to C<&&> except for the very low
+precedence. This means that it short-circuits: the right
expression is evaluated only if the left expression is true.
=head2 Logical or, Defined or, and Exclusive Or
@@ -908,21 +936,22 @@ X<operator, logical, defined or> X<operator, logical, exclusive or>
X<or> X<xor>
Binary "or" returns the logical disjunction of the two surrounding
-expressions. It's equivalent to || except for the very low precedence.
-This makes it useful for control flow
+expressions. It's equivalent to C<||> except for the very low precedence.
+This makes it useful for control flow:
print FH $data or die "Can't write to FH: $!";
-This means that it short-circuits: i.e., the right expression is evaluated
-only if the left expression is false. Due to its precedence, you should
-probably avoid using this for assignment, only for control flow.
+This means that it short-circuits: the right expression is evaluated
+only if the left expression is false. Due to its precedence, you must
+be careful to avoid using it as replacement for the C<||> operator.
+It usually works out better for flow control than in assignments:
$a = $b or $c; # bug: this is wrong
($a = $b) or $c; # really means this
$a = $b || $c; # better written this way
However, when it's a list-context assignment and you're trying to use
-"||" for control flow, you probably need "or" so that the assignment
+C<||> for control flow, you probably need "or" so that the assignment
takes higher precedence.
@info = stat($file) || die; # oops, scalar sense of stat!
@@ -931,7 +960,7 @@ takes higher precedence.
Then again, you could always use parentheses.
Binary "xor" returns the exclusive-OR of the two surrounding expressions.
-It cannot short circuit, of course.
+It cannot short-circuit (of course).
=head2 C Operators Missing From Perl
X<operator, missing from perl> X<&> X<*>
@@ -961,7 +990,6 @@ X<operator, quote> X<operator, quote-like> X<q> X<qq> X<qx> X<qw> X<m>
X<qr> X<s> X<tr> X<'> X<''> X<"> X<""> X<//> X<`> X<``> X<<< << >>>
X<escape sequence> X<escape>
-
While we usually think of quotes as literal values, in Perl they
function as operators, providing various kinds of interpolating and
pattern matching capabilities. Perl provides customary quote characters
@@ -978,27 +1006,27 @@ any pair of delimiters you choose.
qr{} Pattern yes*
s{}{} Substitution yes*
tr{}{} Transliteration no (but see below)
+ y{}{} Transliteration no (but see below)
<<EOF here-doc yes*
* unless the delimiter is ''.
Non-bracketing delimiters use the same character fore and aft, but the four
-sorts of brackets (round, angle, square, curly) will all nest, which means
+sorts of ASCII brackets (round, angle, square, curly) all nest, which means
that
- q{foo{bar}baz}
+ q{foo{bar}baz}
is the same as
- 'foo{bar}baz'
+ 'foo{bar}baz'
Note, however, that this does not always work for quoting Perl code:
- $s = q{ if($a eq "}") ... }; # WRONG
+ $s = q{ if($a eq "}") ... }; # WRONG
-is a syntax error. The C<Text::Balanced> module (from CPAN, and
-starting from Perl 5.8 part of the standard distribution) is able
-to do this properly.
+is a syntax error. The C<Text::Balanced> module (standard as of v5.8,
+and from CPAN before then) is able to do this properly.
There can be whitespace between the operator and the quoting
characters, except when C<#> is being used as the quoting character.
@@ -1009,35 +1037,167 @@ from the next line. This allows you to write:
s {foo} # Replace foo
{bar} # with bar.
-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
- \N{U+263D} Unicode character (example: FIRST QUARTER MOON)
-
-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.
-
-C<\N{U+I<wide hex char>}> means the Unicode character whose Unicode ordinal
-number is I<wide hex char>.
-For documentation of C<\N{name}>, see L<charnames>.
+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> X<\N{}>
+X<\o{}>
+
+ 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)
+ \x{263A} [1,8] hex char (example: SMILEY)
+ \x1b [2,8] restricted range hex char (example: ESC)
+ \N{name} [3] named Unicode character or character sequence
+ \N{U+263D} [4,8] Unicode character (example: FIRST QUARTER MOON)
+ \c[ [5] control char (example: chr(27))
+ \o{23072} [6,8] octal char (example: SMILEY)
+ \033 [7,8] restricted range octal char (example: ESC)
+
+=over 4
+
+=item [1]
+
+The result is the character specified by the hexadecimal number between
+the braces. See L</[8]> below for details on which character.
+
+Only hexadecimal digits are valid between the braces. If an invalid
+character is encountered, a warning will be issued and the invalid
+character and all subsequent characters (valid or invalid) within the
+braces will be discarded.
+
+If there are no valid digits between the braces, the generated character is
+the NULL character (C<\x{00}>). However, an explicit empty brace (C<\x{}>)
+will not cause a warning (currently).
+
+=item [2]
+
+The result is the character specified by the hexadecimal number in the range
+0x00 to 0xFF. See L</[8]> below for details on which character.
+
+Only hexadecimal digits are valid following C<\x>. When C<\x> is followed
+by fewer than two valid digits, any valid digits will be zero-padded. This
+means that C<\x7> will be interpreted as C<\x07>, and a lone <\x> will be
+interpreted as C<\x00>. Except at the end of a string, having fewer than
+two valid digits will result in a warning. Note that although the warning
+says the illegal character is ignored, it is only ignored as part of the
+escape and will still be used as the subsequent character in the string.
+For example:
+
+ Original Result Warns?
+ "\x7" "\x07" no
+ "\x" "\x00" no
+ "\x7q" "\x07q" yes
+ "\xq" "\x00q" yes
+
+=item [3]
+
+The result is the Unicode character or character sequence given by I<name>.
+See L<charnames>.
+
+=item [4]
+
+C<\N{U+I<hexadecimal number>}> means the Unicode character whose Unicode code
+point is I<hexadecimal number>.
+
+=item [5]
+
+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<X>> yields C< chr(28) . "I<X>"> for any I<X>, 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<perlebcdic/OPERATOR DIFFERENCES> 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 some are deprecated with the intention of removing
+those in Perl 5.16. What happens for any of these
+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 [6]
+
+The result is the character specified by the octal number between the braces.
+See L</[8]> below for details on which character.
+
+If a character that isn't an octal digit is encountered, a warning is raised,
+and the value is based on the octal digits before it, discarding it and all
+following characters up to the closing brace. It is a fatal error if there are
+no octal digits at all.
+
+=item [7]
+
+The result is the character specified by the three-digit octal number in the
+range 000 to 777 (but best to not use above 077, see next paragraph). See
+L</[8]> below for details on which character.
+
+Some contexts allow 2 or even 1 digit, but any usage without exactly
+three digits, the first being a zero, may give unintended results. (For
+example, see L<perlrebackslash/Octal escapes>.) Starting in Perl 5.14, you may
+use C<\o{}> instead, which avoids all these problems. Otherwise, it is best to
+use this construct only for ordinals C<\077> and below, remembering to pad to
+the left with zeros to make three digits. For larger ordinals, either use
+C<\o{}> , or convert to something else, such as to hex and use C<\x{}>
+instead.
+
+Having fewer than 3 digits may lead to a misleading warning message that says
+that what follows is ignored. For example, C<"\128"> in the ASCII character set
+is equivalent to the two characters C<"\n8">, but the warning C<Illegal octal
+digit '8' ignored> will be thrown. To avoid this warning, make sure to pad
+your octal number with C<0>'s: C<"\0128">.
+
+=item [8]
+
+Several constructs above specify a character by a number. That number
+gives the character's position in the character set encoding (indexed from 0).
+This is called synonymously its ordinal, code position, or code point. Perl
+works on platforms that have a native encoding currently of either ASCII/Latin1
+or EBCDIC, each of which allow specification of 256 characters. In general, if
+the number is 255 (0xFF, 0377) or below, Perl interprets this in the platform's
+native encoding. If the number is 256 (0x100, 0400) or above, Perl interprets
+it as a Unicode code point and the result is the corresponding Unicode
+character. For example C<\x{50}> and C<\o{120}> both are the number 80 in
+decimal, which is less than 256, so the number is interpreted in the native
+character set encoding. In ASCII the character in the 80th position (indexed
+from 0) is the letter "P", and in EBCDIC it is the ampersand symbol "&".
+C<\x{100}> and C<\o{400}> are both 256 in decimal, so the number is interpreted
+as a Unicode code point no matter what the native encoding is. The name of the
+character in the 100th position (indexed by 0) in Unicode is
+C<LATIN CAPITAL LETTER A WITH MACRON>.
+
+There are a couple of exceptions to the above rule. C<\N{U+I<hex number>}> is
+always interpreted as a Unicode code point, so that C<\N{U+0050}> is "P" even
+on EBCDIC platforms. And if L<C<S<use encoding>>|encoding> is in effect, the
+number is considered to be in that encoding, and is translated from that into
+the platform's native encoding if there is a corresponding native character;
+otherwise to Unicode.
+
+=back
B<NOTE>: 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>
@@ -1047,26 +1207,35 @@ 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>
- \l lowercase next char
- \u uppercase next char
- \L lowercase till \E
- \U uppercase till \E
- \E end case modification
+ \l lowercase next character only
+ \u titlecase (not uppercase!) next character only
+ \L lowercase all characters till \E seen
+ \U uppercase all characters till \E seen
\Q quote non-word characters till \E
+ \E end either case modification or quoted section
+ (whichever was last seen)
+
+C<\L>, C<\U>, and C<\Q> can stack, in which case you need one
+C<\E> for each. For example:
+
+ say "This \Qquoting \ubusiness \Uhere isn't quite\E done yet,\E is it?";
+ This quoting\ Business\ HERE\ ISN\'T\ QUITE\ done\ yet\, is it?
If C<use locale> is in effect, the case map used by C<\l>, C<\L>,
-C<\u> and C<\U> is taken from the current locale. See L<perllocale>.
-If Unicode (for example, C<\N{}> or wide hex characters of 0x100 or
-beyond) is being used, the case map used by C<\l>, C<\L>, C<\u> and
-C<\U> is as defined by Unicode.
+C<\u>, and C<\U> is taken from the current locale. See L<perllocale>.
+If Unicode (for example, C<\N{}> or code points of 0x100 or
+beyond) is being used, the case map used by C<\l>, C<\L>, C<\u>, and
+C<\U> is as defined by Unicode. That means that case-mapping
+a single character can sometimes produce several characters.
All systems use the virtual C<"\n"> to represent a line terminator,
called a "newline". There is no such thing as an unvarying, physical
newline character. It is only an illusion that the operating system,
device drivers, C libraries, and Perl all conspire to preserve. Not all
systems read C<"\r"> as ASCII CR and C<"\n"> as ASCII LF. For example,
-on a Mac, these are reversed, and on systems without line terminator,
-printing C<"\n"> may emit no actual data. In general, use C<"\n"> when
+on the ancient Macs (pre-MacOS X) of yesteryear, these used to be reversed,
+and on systems without line terminator,
+printing C<"\n"> might emit no actual data. In general, use C<"\n"> when
you mean a "newline" for your system, but use the literal ASCII when you
need an exact character. For example, most networking protocols expect
and prefer a CR+LF (C<"\015\012"> or C<"\cM\cJ">) for line terminators,
@@ -1083,14 +1252,28 @@ But method calls such as C<< $obj->meth >> are not.
Interpolating an array or slice interpolates the elements in order,
separated by the value of C<$">, so is equivalent to interpolating
-C<join $", @array>. "Punctuation" arrays such as C<@*> are only
-interpolated if the name is enclosed in braces C<@{*}>, but special
-arrays C<@_>, C<@+>, and C<@-> are interpolated, even without braces.
+C<join $", @array>. "Punctuation" arrays such as C<@*> are usually
+interpolated only if the name is enclosed in braces C<@{*}>, but the
+arrays C<@_>, C<@+>, and C<@-> are interpolated even without braces.
+
+For double-quoted strings, the quoting from C<\Q> is applied after
+interpolation and escapes are processed.
-You cannot include a literal C<$> or C<@> within a C<\Q> sequence.
-An unescaped C<$> or C<@> interpolates the corresponding variable,
-while escaping will cause the literal string C<\$> to be inserted.
-You'll need to write something like C<m/\Quser\E\@\Qhost/>.
+ "abc\Qfoo\tbar$s\Exyz"
+
+is equivalent to
+
+ "abc" . quotemeta("foo\tbar$s") . "xyz"
+
+For the pattern of regex operators (C<qr//>, C<m//> and C<s///>),
+the quoting from C<\Q> is applied after interpolation is processed,
+but before escapes are processed. This allows the pattern to match
+literally (except for C<$> and C<@>). For example, the following matches:
+
+ '\s\t' =~ /\Q\s\t/
+
+Because C<$> or C<@> trigger interpolation, you'll need to use something
+like C</\Quser\E\@\Qhost/> to match them literally.
Patterns are subject to an additional level of interpretation as a
regular expression. This is done as a second pass, after variables are
@@ -1112,14 +1295,14 @@ matching and related activities.
=over 8
-=item qr/STRING/msixpo
+=item qr/STRING/msixpodual
X<qr> X</i> X</m> X</o> X</s> X</x> X</p>
This operator quotes (and possibly compiles) its I<STRING> as a regular
expression. I<STRING> is interpolated the same way as I<PATTERN>
in C<m/PATTERN/>. If "'" is used as the delimiter, no interpolation
is done. Returns a Perl value which may be used instead of the
-corresponding C</STRING/msixpo> expression. The returned value is a
+corresponding C</STRING/msixpodual> expression. The returned value is a
normalized version of the original pattern. It magically differs from
a string containing the same characters: C<ref(qr/x/)> returns "Regexp",
even though dereferencing the result returns undef.
@@ -1141,7 +1324,7 @@ The result may be used as a subpattern in a match:
$string =~ $re; # or used standalone
$string =~ /$re/; # or this way
-Since Perl may compile the pattern at the moment of execution of qr()
+Since Perl may compile the pattern at the moment of execution of the qr()
operator, using qr() may have speed advantages in some situations,
notably if the result of qr() is used standalone:
@@ -1163,7 +1346,7 @@ time a match C</$pat/> is attempted. (Perl has many other internal
optimizations, but none would be triggered in the above example if
we did not use qr() operator.)
-Options are:
+Options (specified by the following modifiers) are:
m Treat string as multiple lines.
s Treat string as single line. (Make . match a newline)
@@ -1172,62 +1355,92 @@ Options are:
p When matching preserve a copy of the matched string so
that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined.
o Compile pattern only once.
+ l Use the locale
+ u Use Unicode rules
+ a Use ASCII for \d, \s, \w; specifying two a's further restricts
+ /i matching so that no ASCII character will match a non-ASCII
+ one
+ d Use Unicode or native charset, as in 5.12 and earlier
If a precompiled pattern is embedded in a larger pattern then the effect
-of 'msixp' will be propagated appropriately. The effect of the 'o'
+of "msixpluad" will be propagated appropriately. The effect the "o"
modifier has is not propagated, being restricted to those patterns
explicitly using it.
+The last four modifiers listed above, added in Perl 5.14,
+control the character set semantics.
+
See L<perlre> for additional information on valid syntax for STRING, and
-for a detailed look at the semantics of regular expressions.
+for a detailed look at the semantics of regular expressions. In
+particular, all the modifiers execpt C</o> are further explained in
+L<perlre/Modifiers>. C</o> is described in the next section.
-=item m/PATTERN/msixpogc
+=item m/PATTERN/msixpodualgc
X<m> X<operator, match>
X<regexp, options> X<regexp> X<regex, options> X<regex>
X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c>
-=item /PATTERN/msixpogc
+=item /PATTERN/msixpodualgc
Searches a string for a pattern match, and in scalar context returns
true if it succeeds, false if it fails. If no string is specified
via the C<=~> or C<!~> operator, the $_ string is searched. (The
string specified with C<=~> need not be an lvalue--it may be the
result of an expression evaluation, but remember the C<=~> binds
-rather tightly.) See also L<perlre>. See L<perllocale> for
-discussion of additional considerations that apply when C<use locale>
-is in effect.
+rather tightly.) See also L<perlre>.
-Options are as described in C<qr//>; in addition, the following match
+Options are as described in C<qr//> above; in addition, the following match
process modifiers are available:
- g Match globally, i.e., find all occurrences.
- c Do not reset search position on a failed match when /g is in effect.
+ g Match globally, i.e., find all occurrences.
+ c Do not reset search position on a failed match when /g is in effect.
If "/" is the delimiter then the initial C<m> is optional. With the C<m>
-you can use any pair of non-whitespace characters
+you can use any pair of non-whitespace (ASCII) characters
as delimiters. This is particularly useful for matching path names
that contain "/", to avoid LTS (leaning toothpick syndrome). If "?" is
-the delimiter, then the match-only-once rule of C<?PATTERN?> applies.
+the delimiter, then a match-only-once rule applies,
+described in C<m?PATTERN?> below.
If "'" is the delimiter, no interpolation is performed on the PATTERN.
When using a character valid in an identifier, whitespace is required
after the C<m>.
-PATTERN may contain variables, which will be interpolated (and the
-pattern recompiled) every time the pattern search is evaluated, except
+PATTERN may contain variables, which will be interpolated
+every time the pattern search is evaluated, except
for when the delimiter is a single quote. (Note that C<$(>, C<$)>, and
C<$|> are not interpolated because they look like end-of-string tests.)
-If you want such a pattern to be compiled only once, add a C</o> after
-the trailing delimiter. This avoids expensive run-time recompilations,
-and is useful when the value you are interpolating won't change over
-the life of the script. However, mentioning C</o> constitutes a promise
-that you won't change the variables in the pattern. If you change them,
-Perl won't even notice. See also L<"qr/STRING/msixpo">.
+Perl will not recompile the pattern unless an interpolated
+variable that it contains changes. You can force Perl to skip the
+test and never recompile by adding a C</o> (which stands for "once")
+after the trailing delimiter.
+Once upon a time, Perl would recompile regular expressions
+unnecessarily, and this modifier was useful to tell it not to do so, in the
+interests of speed. But now, the only reasons to use C</o> are either:
+
+=over
+
+=item 1
+
+The variables are thousands of characters long and you know that they
+don't change, and you need to wring out the last little bit of speed by
+having Perl skip testing for that. (There is a maintenance penalty for
+doing this, as mentioning C</o> constitutes a promise that you won't
+change the variables in the pattern. If you change them, Perl won't
+even notice.)
+
+=item 2
+
+you want the pattern to use the initial values of the variables
+regardless of whether they change or not. (But there are saner ways
+of accomplishing this than using C</o>.)
+
+=back
=item The empty pattern //
If the PATTERN evaluates to the empty string, the last
I<successfully> matched regular expression is used instead. In this
-case, only the C<g> and C<c> flags on the empty pattern is honoured -
+case, only the C<g> and C<c> flags on the empty pattern are honored;
the other flags are taken from the original pattern. If no match has
previously succeeded, this will (silently) act instead as a genuine
empty pattern (which will always match).
@@ -1253,7 +1466,9 @@ failure.
Examples:
- open(TTY, '/dev/tty');
+ open(TTY, "+>/dev/tty")
+ || die "can't access /dev/tty: $!";
+
<TTY> =~ /^y/i && foo(); # do foo if desired
if (/Version: *([0-9.]*)/) { $version = $1; }
@@ -1263,42 +1478,44 @@ Examples:
# poor man's grep
$arg = shift;
while (<>) {
- print if /$arg/o; # compile only once
+ print if /$arg/o; # compile only once (no longer needed!)
}
if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
This last example splits $foo into the first two words and the
remainder of the line, and assigns those three fields to $F1, $F2, and
-$Etc. The conditional is true if any variables were assigned, i.e., if
-the pattern matched.
+$Etc. The conditional is true if any variables were assigned; that is,
+if the pattern matched.
The C</g> modifier specifies global pattern matching--that is,
-matching as many times as possible within the string. How it behaves
-depends on the context. In list context, it returns a list of the
+matching as many times as possible within the string. How it behaves
+depends on the context. In list context, it returns a list of the
substrings matched by any capturing parentheses in the regular
-expression. If there are no parentheses, it returns a list of all
+expression. If there are no parentheses, it returns a list of all
the matched strings, as if there were parentheses around the whole
pattern.
In scalar context, each execution of C<m//g> finds the next match,
returning true if it matches, and false if there is no further match.
-The position after the last match can be read or set using the pos()
-function; see L<perlfunc/pos>. A failed match normally resets the
+The position after the last match can be read or set using the C<pos()>
+function; see L<perlfunc/pos>. A failed match normally resets the
search position to the beginning of the string, but you can avoid that
-by adding the C</c> modifier (e.g. C<m//gc>). Modifying the target
+by adding the C</c> modifier (e.g. C<m//gc>). Modifying the target
string also resets the search position.
=item \G assertion
You can intermix C<m//g> matches with C<m/\G.../g>, where C<\G> is a
-zero-width assertion that matches the exact position where the previous
-C<m//g>, if any, left off. Without the C</g> modifier, the C<\G> assertion
-still anchors at pos(), but the match is of course only attempted once.
-Using C<\G> without C</g> on a target string that has not previously had a
-C</g> match applied to it is the same as using the C<\A> assertion to match
-the beginning of the string. Note also that, currently, C<\G> is only
-properly supported when anchored at the very beginning of the pattern.
+zero-width assertion that matches the exact position where the
+previous C<m//g>, if any, left off. Without the C</g> modifier, the
+C<\G> assertion still anchors at C<pos()> as it was at the start of
+the operation (see L<perlfunc/pos>), but the match is of course only
+attempted once. Using C<\G> without C</g> on a target string that has
+not previously had a C</g> match applied to it is the same as using
+the C<\A> assertion to match the beginning of the string. Note also
+that, currently, C<\G> is only properly supported when anchored at the
+very beginning of the pattern.
Examples:
@@ -1306,15 +1523,39 @@ Examples:
($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
# scalar context
- $/ = "";
- while (defined($paragraph = <>)) {
- while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) {
+ local $/ = "";
+ while ($paragraph = <>) {
+ while ($paragraph =~ /\p{Ll}['")]*[.!?]+['")]*\s/g) {
$sentences++;
}
}
- print "$sentences\n";
+ say $sentences;
+
+Here's another way to check for sentences in a paragraph:
+
+ my $sentence_rx = qr{
+ (?: (?<= ^ ) | (?<= \s ) ) # after start-of-string or whitespace
+ \p{Lu} # capital letter
+ .*? # a bunch of anything
+ (?<= \S ) # that ends in non-whitespace
+ (?<! \b [DMS]r ) # but isn't a common abbreviation
+ (?<! \b Mrs )
+ (?<! \b Sra )
+ (?<! \b St )
+ [.?!] # followed by a sentence ender
+ (?= $ | \s ) # in front of end-of-string or whitespace
+ }sx;
+ local $/ = "";
+ while (my $paragraph = <>) {
+ say "NEW PARAGRAPH";
+ my $count = 0;
+ while ($paragraph =~ /($sentence_rx)/g) {
+ printf "\tgot sentence %d: <%s>\n", ++$count, $1;
+ }
+ }
+
+Here's how to use C<m//gc> with C<\G>:
- # using m//gc with \G
$_ = "ppooqppqq";
while ($i++ < 2) {
print "1: '";
@@ -1339,8 +1580,8 @@ The last example should print:
Notice that the final match matched C<q> instead of C<p>, which a match
without the C<\G> anchor would have done. Also note that the final match
did not update C<pos>. C<pos> is only updated on a C</g> match. If the
-final match did indeed match C<p>, it's a good bet that you're running an
-older (pre-5.6.0) Perl.
+final match did indeed match C<p>, it's a good bet that you're running a
+very old (pre-5.6.0) version of Perl.
A useful idiom for C<lex>-like scanners is C</\G.../gc>. You can
combine several regexps like this to process a string part-by-part,
@@ -1348,60 +1589,79 @@ doing different actions depending on which regexp matched. Each
regexp tries to match where the previous one leaves off.
$_ = <<'EOL';
- $url = URI::URL->new( "http://example.com/" ); die if $url eq "xXx";
+ $url = URI::URL->new( "http://example.com/" ); die if $url eq "xXx";
EOL
- LOOP:
- {
- print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc;
- print(" lowercase"), redo LOOP if /\G[a-z]+\b[,.;]?\s*/gc;
- print(" UPPERCASE"), redo LOOP if /\G[A-Z]+\b[,.;]?\s*/gc;
- print(" Capitalized"), redo LOOP if /\G[A-Z][a-z]+\b[,.;]?\s*/gc;
- print(" MiXeD"), redo LOOP if /\G[A-Za-z]+\b[,.;]?\s*/gc;
- print(" alphanumeric"), redo LOOP if /\G[A-Za-z0-9]+\b[,.;]?\s*/gc;
- print(" line-noise"), redo LOOP if /\G[^A-Za-z0-9]+/gc;
- print ". That's all!\n";
- }
+
+ LOOP: {
+ print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc;
+ print(" lowercase"), redo LOOP if /\G\p{Ll}+\b[,.;]?\s*/gc;
+ print(" UPPERCASE"), redo LOOP if /\G\p{Lu}+\b[,.;]?\s*/gc;
+ print(" Capitalized"), redo LOOP if /\G\p{Lu}\p{Ll}+\b[,.;]?\s*/gc;
+ print(" MiXeD"), redo LOOP if /\G\pL+\b[,.;]?\s*/gc;
+ print(" alphanumeric"), redo LOOP if /\G[\p{Alpha}\pN]+\b[,.;]?\s*/gc;
+ print(" line-noise"), redo LOOP if /\G\W+/gc;
+ print ". That's all!\n";
+ }
Here is the output (split into several lines):
- line-noise lowercase line-noise lowercase UPPERCASE line-noise
- UPPERCASE line-noise lowercase line-noise lowercase line-noise
- lowercase lowercase line-noise lowercase lowercase line-noise
- MiXeD line-noise. That's all!
+ line-noise lowercase line-noise UPPERCASE line-noise UPPERCASE
+ line-noise lowercase line-noise lowercase line-noise lowercase
+ lowercase line-noise lowercase lowercase line-noise lowercase
+ lowercase line-noise MiXeD line-noise. That's all!
-=item ?PATTERN?
-X<?>
+=item m?PATTERN?msixpodualgc
+X<?> X<operator, match-once>
-This is just like the C</pattern/> search, except that it matches only
-once between calls to the reset() operator. This is a useful
+=item ?PATTERN?msixpodualgc
+
+This is just like the C<m/PATTERN/> search, except that it matches
+only once between calls to the reset() operator. This is a useful
optimization when you want to see only the first occurrence of
-something in each file of a set of files, for instance. Only C<??>
+something in each file of a set of files, for instance. Only C<m??>
patterns local to the current package are reset.
while (<>) {
- if (?^$?) {
+ if (m?^$?) {
# blank line between header and body
}
} continue {
- reset if eof; # clear ?? status for next file
+ reset if eof; # clear m?? status for next file
}
-This usage is vaguely deprecated, which means it just might possibly
-be removed in some distant future version of Perl, perhaps somewhere
-around the year 2168.
+Another example switched the first "latin1" encoding it finds
+to "utf8" in a pod file:
+
+ s//utf8/ if m? ^ =encoding \h+ \K latin1 ?x;
+
+The match-once behavior is controlled by the match delimiter being
+C<?>; with any other delimiter this is the normal C<m//> operator.
+
+For historical reasons, the leading C<m> in C<m?PATTERN?> is optional,
+but the resulting C<?PATTERN?> syntax is deprecated, will warn on
+usage and might be removed from a future stable release of Perl (without
+further notice!).
-=item s/PATTERN/REPLACEMENT/msixpogce
+=item s/PATTERN/REPLACEMENT/msixpodualgcer
X<substitute> X<substitution> X<replace> X<regexp, replace>
-X<regexp, substitute> X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c> X</e>
+X<regexp, substitute> X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c> X</e> X</r>
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</r> (non-destructive) option is used then it runs the
+substitution on a copy of the string and instead of returning the
+number of substitutions, it returns the copy whether or not a
+substitution occurred. The original string is never changed when
+C</r> is used. 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
-to one of those, i.e., an lvalue.)
+variable is searched and modified. Unless the C</r> option is used,
+the string specified must be a scalar variable, an array element, a
+hash element, or an assignment to one of those; that is, some sort of
+scalar lvalue.
If the delimiter chosen is a single quote, no interpolation is
done on either the PATTERN or the REPLACEMENT. Otherwise, if the
@@ -1411,14 +1671,13 @@ at run-time. If you want the pattern compiled only once the first time
the variable is interpolated, use the C</o> option. If the pattern
evaluates to the empty string, the last successfully executed regular
expression is used instead. See L<perlre> for further explanation on these.
-See L<perllocale> for discussion of additional considerations that apply
-when C<use locale> is in effect.
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
+ 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<s> when using a character allowed in identifiers. If single quotes
@@ -1442,6 +1701,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
@@ -1454,6 +1718,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;
@@ -1461,6 +1729,9 @@ Examples:
# Add one to the value of any numbers in the string
s/(\d+)/1 + $1/eg;
+ # Titlecase words in the last 30 characters only
+ substr($str, -30) =~ s/\b(\p{Alpha}+)\b/\u\L$1/g;
+
# This will expand any embedded scalar variable
# (including lexicals) in $_ : First $1 is interpolated
# to the variable name, and then evaluated
@@ -1495,6 +1766,14 @@ to occur that you might want. Here are two common cases:
# expand tabs to 8-column spacing
1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
+C<s///le> is treated as a substitution followed by the C<le> operator, not
+the C</le> flags. This may change in a future version of Perl. It
+produces a warning if warnings are enabled. To disambiguate, use a space
+or change the order of the flags:
+
+ s/foo/bar/ le 5; # "le" infix operator
+ s/foo/bar/el; # "e" and "l" flags
+
=back
=head2 Quote-Like Operators
@@ -1570,11 +1849,11 @@ when the program is done:
The STDIN filehandle used by the command is inherited from Perl's STDIN.
For example:
- open BLAM, "blam" || die "Can't open: $!";
- open STDIN, "<&BLAM";
- print `sort`;
+ open(SPLAT, "stuff") || die "can't open stuff: $!";
+ open(STDIN, "<&SPLAT") || die "can't dupe SPLAT: $!";
+ print STDOUT `sort`;
-will print the sorted contents of the file "blam".
+will print the sorted contents of the file named F<"stuff">.
Using single-quote as a delimiter protects the command from Perl's
double-quote interpolation, passing it on to the shell instead:
@@ -1625,7 +1904,7 @@ Evaluates to a list of the words extracted out of STRING, using embedded
whitespace as the word delimiters. It can be understood as being roughly
equivalent to:
- split(' ', q/STRING/);
+ split(" ", q/STRING/);
the differences being that it generates a real list at compile time, and
in scalar context it returns the last element in the list. So
@@ -1635,7 +1914,7 @@ this expression:
is semantically equivalent to the list:
- 'foo', 'bar', 'baz'
+ "foo", "bar", "baz"
Some frequently seen examples:
@@ -1647,31 +1926,41 @@ put comments into a multi-line C<qw>-string. For this reason, the
C<use warnings> pragma and the B<-w> switch (that is, the C<$^W> variable)
produces warnings if the STRING contains the "," or the "#" character.
-
-=item tr/SEARCHLIST/REPLACEMENTLIST/cds
+=item tr/SEARCHLIST/REPLACEMENTLIST/cdsr
X<tr> X<y> X<transliterate> X</c> X</d> X</s>
-=item y/SEARCHLIST/REPLACEMENTLIST/cds
+=item y/SEARCHLIST/REPLACEMENTLIST/cdsr
Transliterates all occurrences of the characters found in the search list
with the corresponding character in the replacement list. It returns
the number of characters replaced or deleted. If no string is
-specified via the =~ or !~ operator, the $_ string is transliterated. (The
-string specified with =~ must be a scalar variable, an array element, a
-hash element, or an assignment to one of those, i.e., an lvalue.)
+specified via the C<=~> or C<!~> operator, the $_ string is transliterated.
+
+If the C</r> (non-destructive) option is present, a new copy of the string
+is made and its characters transliterated, and this copy is returned no
+matter whether it was modified or not: the original string is always
+left unchanged. The new copy is always a plain string, even if the input
+string is an object or a tied variable.
+
+Unless the C</r> option is used, the string specified with C<=~> must be a
+scalar variable, an array element, a hash element, or an assignment to one
+of those; in other words, an lvalue.
A character range may be specified with a hyphen, so C<tr/A-J/0-9/>
does the same replacement as C<tr/ACEGIBDFHJ/0246813579/>.
For B<sed> devotees, C<y> is provided as a synonym for C<tr>. If the
SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has
-its own pair of quotes, which may or may not be bracketing quotes,
-e.g., C<tr[A-Z][a-z]> or C<tr(+\-*/)/ABCD/>.
-
-Note that C<tr> does B<not> do regular expression character classes
-such as C<\d> or C<[:lower:]>. The C<tr> operator is not equivalent to
-the tr(1) utility. If you want to map strings between lower/upper
-cases, see L<perlfunc/lc> and L<perlfunc/uc>, and in general consider
-using the C<s> operator if you need regular expressions.
+its own pair of quotes, which may or may not be bracketing quotes;
+for example, C<tr[aeiouy][yuoiea]> or C<tr(+\-*/)/ABCD/>.
+
+Note that C<tr> does B<not> do regular expression character classes such as
+C<\d> or C<\pL>. The C<tr> operator is not equivalent to the tr(1)
+utility. If you want to map strings between lower/upper cases, see
+L<perlfunc/lc> and L<perlfunc/uc>, and in general consider using the C<s>
+operator if you need regular expressions. The C<\U>, C<\u>, C<\L>, and
+C<\l> string-interpolation escapes on the right side of a substitution
+operator will perform correct case-mappings, but C<tr[a-z][A-Z]> will not
+(except sometimes on legacy 7-bit data).
Note also that the whole range idea is rather unportable between
character sets--and even within character sets they may cause results
@@ -1685,6 +1974,8 @@ Options:
c Complement the SEARCHLIST.
d Delete found but unreplaced characters.
s Squash duplicate replaced characters.
+ r Return the modified string and leave the original string
+ untouched.
If the C</c> modifier is specified, the SEARCHLIST character set
is complemented. If the C</d> modifier is specified, any characters
@@ -1704,7 +1995,7 @@ squashing character sequences in a class.
Examples:
- $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case
+ $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case ASCII
$cnt = tr/*/*/; # count the stars in $_
@@ -1715,11 +2006,18 @@ Examples:
tr/a-zA-Z//s; # bookkeeper -> bokeper
($HOST = $host) =~ tr/a-z/A-Z/;
+ $HOST = $host =~ tr/a-z/A-Z/r; # same thing
+
+ $HOST = $host =~ tr/a-z/A-Z/r # chained with s///r
+ =~ s/:/ -p/r;
tr/a-zA-Z/ /cs; # change non-alphas to single space
+ @stripped = map tr/a-zA-Z/ /csr, @original;
+ # /r with map
+
tr [\200-\377]
- [\000-\177]; # delete 8th bit
+ [\000-\177]; # wickedly delete 8th bit
If multiple transliterations are given for a character, only the
first one is used:
@@ -1781,6 +2079,17 @@ strings except that backslashes have no special meaning, with C<\\>
being treated as two backslashes and not one as they would in every
other quoting construct.
+Just as in the shell, a backslashed bareword following the C<<< << >>>
+means the same thing as a single-quoted string does:
+
+ $cost = <<'VISTA'; # hasta la ...
+ That'll be $10 please, ma'am.
+ VISTA
+
+ $cost = <<\VISTA; # Same thing!
+ That'll be $10 please, ma'am.
+ VISTA
+
This is the only form of quoting in perl where there is no need
to worry about escaping content, something that code generators
can and do make good use of.
@@ -1857,8 +2166,8 @@ If the terminating identifier is on the last line of the program, you
must be sure there is a newline after it; otherwise, Perl will give the
warning B<Can't find string terminator "END" anywhere before EOF...>.
-Additionally, the quoting rules for the end of string identifier are not
-related to Perl's quoting rules. C<q()>, C<qq()>, and the like are not
+Additionally, quoting rules for the end-of-string identifier are
+unrelated to Perl's quoting rules. C<q()>, C<qq()>, and the like are not
supported in place of C<''> and C<"">, and the only interpolation is for
backslashing the quoting character:
@@ -1941,12 +2250,12 @@ C<tr///>), the search is repeated once more.
If the first delimiter is not an opening punctuation, three delimiters must
be same such as C<s!!!> and C<tr)))>, in which case the second delimiter
terminates the left part and starts the right part at once.
-If the left part is delimited by bracketing punctuations (that is C<()>,
+If the left part is delimited by bracketing punctuation (that is C<()>,
C<[]>, C<{}>, or C<< <> >>), the right part needs another pair of
-delimiters such as C<s(){}> and C<tr[]//>. In these cases, whitespaces
+delimiters such as C<s(){}> and C<tr[]//>. In these cases, whitespace
and comments are allowed between both parts, though the comment must follow
-at least one whitespace; otherwise a character expected as the start of
-the comment may be regarded as the starting delimiter of the right part.
+at least one whitespace character; otherwise a character expected as the
+start of the comment may be regarded as the starting delimiter of the right part.
During this search no attention is paid to the semantics of the construct.
Thus:
@@ -2483,17 +2792,17 @@ floating point. But by saying
use integer;
-you may tell the compiler that it's okay to use integer operations
-(if it feels like it) from here to the end of the enclosing BLOCK.
-An inner BLOCK may countermand this by saying
+you may tell the compiler to use integer operations
+(see L<integer> for a detailed explanation) from here to the end of
+the enclosing BLOCK. An inner BLOCK may countermand this by saying
no integer;
which lasts until the end of that BLOCK. Note that this doesn't
-mean everything is only an integer, merely that Perl may use integer
-operations if it is so inclined. For example, even under C<use
-integer>, if you take the C<sqrt(2)>, you'll still get C<1.4142135623731>
-or so.
+mean everything is an integer, merely that Perl will use integer
+operations for arithmetic, comparison, and bitwise operators. For
+example, even under C<use integer>, if you take the C<sqrt(2)>, you'll
+still get C<1.4142135623731> or so.
Used on numbers, the bitwise operators ("&", "|", "^", "~", "<<",
and ">>") always produce integral results. (But see also
@@ -2550,36 +2859,47 @@ need yourself.
=head2 Bigger Numbers
X<number, arbitrary precision>
-The standard Math::BigInt and Math::BigFloat modules provide
+The standard C<Math::BigInt>, C<Math::BigRat>, and C<Math::BigFloat> modules,
+along with the C<bigint>, C<bigrat>, and C<bitfloat> pragmas, provide
variable-precision arithmetic and overloaded operators, although
they're currently pretty slow. At the cost of some space and
considerable speed, they avoid the normal pitfalls associated with
limited-precision representations.
- use Math::BigInt;
- $x = Math::BigInt->new('123456789123456789');
- print $x * $x;
+ use 5.010;
+ use bigint; # easy interface to Math::BigInt
+ $x = 123456789123456789;
+ say $x * $x;
+ +15241578780673678515622620750190521
+
+Or with rationals:
- # prints +15241578780673678515622620750190521
+ use 5.010;
+ use bigrat;
+ $a = 3/22;
+ $b = 4/6;
+ say "a/b is ", $a/$b;
+ say "a*b is ", $a*$b;
+ a/b is 9/44
+ a*b is 1/11
-There are several modules that let you calculate with (bound only by
-memory and cpu-time) unlimited or fixed precision. There are also
-some non-standard modules that provide faster implementations via
-external C libraries.
+Several modules let you calculate with (bound only by memory and CPU time)
+unlimited or fixed precision. There are also some non-standard modules that
+provide faster implementations via external C libraries.
Here is a short, but incomplete summary:
- Math::Fraction big, unlimited fractions like 9973 / 12967
- Math::String treat string sequences like numbers
- Math::FixedPrecision calculate with a fixed precision
- Math::Currency for currency calculations
- Bit::Vector manipulate bit vectors fast (uses C)
- Math::BigIntFast Bit::Vector wrapper for big numbers
- Math::Pari provides access to the Pari C library
- Math::BigInteger uses an external C library
- Math::Cephes uses external Cephes C library (no big numbers)
- Math::Cephes::Fraction fractions via the Cephes library
- Math::GMP another one using an external C library
+ Math::Fraction big, unlimited fractions like 9973 / 12967
+ Math::String treat string sequences like numbers
+ Math::FixedPrecision calculate with a fixed precision
+ Math::Currency for currency calculations
+ Bit::Vector manipulate bit vectors fast (uses C)
+ Math::BigIntFast Bit::Vector wrapper for big numbers
+ Math::Pari provides access to the Pari C library
+ Math::BigInteger uses an external C library
+ Math::Cephes uses external Cephes C library (no big numbers)
+ Math::Cephes::Fraction fractions via the Cephes library
+ Math::GMP another one using an external C library
Choose wisely.