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.pod3215
1 files changed, 0 insertions, 3215 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlop.pod b/Master/tlpkg/tlperl/lib/pods/perlop.pod
deleted file mode 100644
index 7b2d0a3acd0..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlop.pod
+++ /dev/null
@@ -1,3215 +0,0 @@
-=head1 NAME
-X<operator>
-
-perlop - Perl operators and precedence
-
-=head1 DESCRIPTION
-
-=head2 Operator Precedence and Associativity
-X<operator, precedence> X<precedence> X<associativity>
-
-Operator precedence and associativity work in Perl more or less like
-they do in mathematics.
-
-I<Operator precedence> means some operators are evaluated before
-others. For example, in C<2 + 4 * 5>, the multiplication has higher
-precedence so C<4 * 5> is evaluated first yielding C<2 + 20 ==
-22> and not C<6 * 5 == 30>.
-
-I<Operator associativity> defines what happens if a sequence of the
-same operators is used one after another: whether the evaluator will
-evaluate the left operations first or the right. For example, in C<8
-- 4 - 2>, subtraction is left associative so Perl evaluates the
-expression left to right. C<8 - 4> is evaluated first making the
-expression C<4 - 2 == 2> and not C<8 - 2 == 6>.
-
-Perl operators have the following associativity and precedence,
-listed from highest precedence to lowest. Operators borrowed from
-C keep the same precedence relationship with each other, even where
-C's precedence is slightly screwy. (This makes learning Perl easier
-for C folks.) With very few exceptions, these all operate on scalar
-values only, not array values.
-
- left terms and list operators (leftward)
- left ->
- nonassoc ++ --
- right **
- right ! ~ \ and unary + and -
- left =~ !~
- left * / % x
- left + - .
- left << >>
- nonassoc named unary operators
- nonassoc < > <= >= lt gt le ge
- nonassoc == != <=> eq ne cmp ~~
- left &
- left | ^
- left &&
- left || //
- nonassoc .. ...
- right ?:
- right = += -= *= etc.
- left , =>
- nonassoc list operators (rightward)
- right not
- left and
- left or xor
-
-In the following sections, these operators are covered in precedence order.
-
-Many operators can be overloaded for objects. See L<overload>.
-
-=head2 Terms and List Operators (Leftward)
-X<list operator> X<operator, list> X<term>
-
-A TERM has the highest precedence in Perl. They include variables,
-quote and quote-like operators, any expression in parentheses,
-and any function whose arguments are parenthesized. Actually, there
-aren't really functions in this sense, just list operators and unary
-operators behaving as functions because you put parentheses around
-the arguments. These are all documented in L<perlfunc>.
-
-If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
-is followed by a left parenthesis as the next token, the operator and
-arguments within parentheses are taken to be of highest precedence,
-just like a normal function call.
-
-In the absence of parentheses, the precedence of list operators such as
-C<print>, C<sort>, or C<chmod> is either very high or very low depending on
-whether you are looking at the left side or the right side of the operator.
-For example, in
-
- @ary = (1, 3, sort 4, 2);
- print @ary; # prints 1324
-
-the commas on the right of the sort are evaluated before the sort,
-but the commas on the left are evaluated after. In other words,
-list operators tend to gobble up all arguments that follow, and
-then act like a simple TERM with regard to the preceding expression.
-Be careful with parentheses:
-
- # These evaluate exit before doing the print:
- print($foo, exit); # Obviously not what you want.
- print $foo, exit; # Nor is this.
-
- # These do the print before evaluating exit:
- (print $foo), exit; # This is what you want.
- print($foo), exit; # Or this.
- print ($foo), exit; # Or even this.
-
-Also note that
-
- print ($foo & 255) + 1, "\n";
-
-probably doesn't do what you expect at first glance. The parentheses
-enclose the argument list for C<print> which is evaluated (printing
-the result of C<$foo & 255>). Then one is added to the return value
-of C<print> (usually 1). The result is something like this:
-
- 1 + 1, "\n"; # Obviously not what you meant.
-
-To do what you meant properly, you must write:
-
- print(($foo & 255) + 1, "\n");
-
-See L<Named Unary Operators> for more discussion of this.
-
-Also parsed as terms are the C<do {}> and C<eval {}> constructs, as
-well as subroutine and method calls, and the anonymous
-constructors C<[]> and C<{}>.
-
-See also L<Quote and Quote-like Operators> toward the end of this section,
-as well as L</"I/O Operators">.
-
-=head2 The Arrow Operator
-X<arrow> X<dereference> X<< -> >>
-
-"C<< -> >>" is an infix dereference operator, just as it is in C
-and C++. If the right side is either a C<[...]>, C<{...}>, or a
-C<(...)> subscript, then the left side must be either a hard or
-symbolic reference to an array, a hash, or a subroutine respectively.
-(Or technically speaking, a location capable of holding a hard
-reference, if it's an array or hash reference being used for
-assignment.) See L<perlreftut> and L<perlref>.
-
-Otherwise, the right side is a method name or a simple scalar
-variable containing either the method name or a subroutine reference,
-and the left side must be either an object (a blessed reference)
-or a class name (that is, a package name). See L<perlobj>.
-
-=head2 Auto-increment and Auto-decrement
-X<increment> X<auto-increment> X<++> X<decrement> X<auto-decrement> X<-->
-
-"++" and "--" work as in C. That is, if placed before a variable,
-they increment or decrement the variable by one before returning the
-value, and if placed after, increment or decrement after returning the
-value.
-
- $i = 0; $j = 0;
- print $i++; # prints 0
- print ++$j; # prints 1
-
-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 behavior.
-Avoid statements like:
-
- $i = $i ++;
- print ++ $i + $i ++;
-
-Perl will not guarantee what the result of the above statements is.
-
-The auto-increment operator has a little extra builtin magic to it. If
-you increment a variable that is numeric, or that has ever been used in
-a numeric context, you get a normal increment. If, however, the
-variable has been used in only string contexts since it was set, and
-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"
-
-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
-will return C<0> rather than C<undef>).
-
-The auto-decrement operator is not magical.
-
-=head2 Exponentiation
-X<**> X<exponentiation> X<power>
-
-Binary "**" is the exponentiation operator. It binds even more
-tightly than unary minus, so -2**4 is -(2**4), not (-2)**4. (This is
-implemented using C's pow(3) function, which actually works on doubles
-internally.)
-
-=head2 Symbolic Unary Operators
-X<unary operator> X<operator, unary>
-
-Unary "!" performs logical negation, that is, "not". See also C<not> for a lower
-precedence version of this.
-X<!>
-
-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
-string cannot be cleanly converted to a numeric, Perl will give the warning
-B<Argument "the string" isn't numeric in negation (-) at ...>.
-X<-> X<negation, arithmetic>
-
-Unary "~" performs bitwise negation, that is, 1's complement. For
-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.
-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
-arguments. (See examples above under L<Terms and List Operators (Leftward)>.)
-X<+>
-
-Unary "\" creates a reference to whatever follows it. See L<perlreftut>
-and L<perlref>. Do not confuse this behavior with the behavior of
-backslash within a string, although both forms do convey the notion
-of protecting the next thing from interpolation.
-X<\> X<reference> X<backslash>
-
-=head2 Binding Operators
-X<binding> X<operator, binding> X<=~> X<!~>
-
-Binary "=~" binds a scalar expression to a pattern match. Certain operations
-search or modify the string $_ by default. This operator makes that kind
-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. 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
-time. Note that this means that its contents will be interpolated twice, so
-
- '\\' =~ q'\\';
-
-is not ok, as the regex engine will end up trying to compile the
-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>
-
-Binary "*" multiplies two numbers.
-X<*>
-
-Binary "/" divides two numbers.
-X</> X<slash>
-
-Binary "%" is the modulo operator, which computes the division
-remainder of its first argument with respect to its second argument.
-Given integer
-operands C<$a> and C<$b>: If C<$b> is positive, then C<$a % $b> is
-C<$a> minus the largest multiple of C<$b> less than or equal to
-C<$a>. If C<$b> is negative, then C<$a % $b> is C<$a> minus the
-smallest multiple of C<$b> that is not less than C<$a> (that is, the
-result will be less than or equal to zero). If the operands
-C<$a> and C<$b> are floating point values and the absolute value of
-C<$b> (that is C<abs($b)>) is less than C<(UV_MAX + 1)>, only
-the integer portion of C<$a> and C<$b> will be used in the operation
-(Note: here C<UV_MAX> means the maximum of the unsigned integer type).
-If the absolute value of the right operand (C<abs($b)>) is greater than
-or equal to C<(UV_MAX + 1)>, "%" computes the floating-point remainder
-C<$r> in the equation C<($r = $a - $i*$b)> where C<$i> is a certain
-integer that makes C<$r> have the same sign as the right operand
-C<$b> (B<not> as the left operand C<$a> like C function C<fmod()>)
-and the absolute value less than that of C<$b>.
-Note that when C<use integer> is in scope, "%" gives you direct access
-to the modulo operator as implemented by your C compiler. This
-operator is not as well defined for negative operands, but it will
-execute faster.
-X<%> X<remainder> X<modulo> X<mod>
-
-Binary "x" is the repetition operator. In scalar context or if the left
-operand is not enclosed in parentheses, it returns a string consisting
-of the left operand repeated the number of times specified by the right
-operand. In list context, if the left operand is enclosed in
-parentheses or is a list formed by C<qw/STRING/>, it repeats the list.
-If the right operand is zero or negative, it returns an empty string
-or an empty list, depending on the context.
-X<x>
-
- print '-' x 80; # print row of dashes
-
- print "\t" x ($tab/8), ' ' x ($tab%8); # tab over
-
- @ones = (1) x 80; # a list of 80 1's
- @ones = (5) x @ones; # set all elements to 5
-
-
-=head2 Additive Operators
-X<operator, additive>
-
-Binary C<+> returns the sum of two numbers.
-X<+>
-
-Binary C<-> returns the difference of two numbers.
-X<->
-
-Binary C<.> concatenates two strings.
-X<string, concatenation> X<concatenation>
-X<cat> X<concat> X<concatenate> X<.>
-
-=head2 Shift Operators
-X<shift operator> X<operator, shift> X<<< << >>>
-X<<< >> >>> X<right shift> X<left shift> X<bitwise shift>
-X<shl> X<shr> X<shift, right> X<shift, left>
-
-Binary C<<< << >>> returns the value of its left argument shifted left by the
-number of bits specified by the right argument. Arguments should be
-integers. (See also L<Integer Arithmetic>.)
-
-Binary C<<< >> >>> returns the value of its left argument shifted right by
-the number of bits specified by the right argument. Arguments should
-be integers. (See also L<Integer Arithmetic>.)
-
-Note that both C<<< << >>> and C<<< >> >>> in Perl are implemented directly using
-C<<< << >>> and C<<< >> >>> in C. If C<use integer> (see L<Integer Arithmetic>) is
-in force then signed C integers are used, else unsigned C integers are
-used. Either way, the implementation isn't going to generate results
-larger than the size of the integer type Perl was built with (32 bits
-or 64 bits).
-
-The result of overflowing the range of the integers is undefined
-because it is undefined also in C. In other words, using 32-bit
-integers, C<< 1 << 32 >> is undefined. Shifting by a negative number
-of bits is also undefined.
-
-If you get tired of being subject to your platform's native integers,
-the C<use bigint> pragma neatly sidesteps the issue altogether:
-
- print 20 << 20; # 20971520
- print 20 << 40; # 5120 on 32-bit machines,
- # 21990232555520 on 64-bit machines
- use bigint;
- print 20 << 100; # 25353012004564588029934064107520
-
-=head2 Named Unary Operators
-X<operator, named unary>
-
-The various named unary operators are treated as functions with one
-argument, with optional parentheses.
-
-If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
-is followed by a left parenthesis as the next token, the operator and
-arguments within parentheses are taken to be of highest precedence,
-just like a normal function call. For example,
-because named unary operators are higher precedence than C<||>:
-
- chdir $foo || die; # (chdir $foo) || die
- chdir($foo) || die; # (chdir $foo) || die
- chdir ($foo) || die; # (chdir $foo) || die
- chdir +($foo) || die; # (chdir $foo) || die
-
-but, because * is higher precedence than named operators:
-
- chdir $foo * 20; # chdir ($foo * 20)
- chdir($foo) * 20; # (chdir $foo) * 20
- chdir ($foo) * 20; # (chdir $foo) * 20
- chdir +($foo) * 20; # chdir ($foo * 20)
-
- rand 10 * 20; # rand (10 * 20)
- rand(10) * 20; # (rand 10) * 20
- rand (10) * 20; # (rand 10) * 20
- rand +(10) * 20; # rand (10 * 20)
-
-Regarding precedence, the filetest operators, like C<-f>, C<-M>, etc. are
-treated like named unary operators, but they don't follow this functional
-parenthesis rule. That means, for example, that C<-f($file).".bak"> is
-equivalent to C<-f "$file.bak">.
-X<-X> X<filetest> X<operator, filetest>
-
-See also L<"Terms and List Operators (Leftward)">.
-
-=head2 Relational Operators
-X<relational operator> X<operator, relational>
-
-Perl operators that return true or false generally return values
-that can be safely used as numbers. For example, the relational
-operators in this section and the equality operators in the next
-one return C<1> for true and a special version of the defined empty
-string, C<"">, which counts as a zero but is exempt from warnings
-about improper numeric conversions, just as C<"0 but true"> is.
-
-Binary "<" returns true if the left argument is numerically less than
-the right argument.
-X<< < >>
-
-Binary ">" returns true if the left argument is numerically greater
-than the right argument.
-X<< > >>
-
-Binary "<=" returns true if the left argument is numerically less than
-or equal to the right argument.
-X<< <= >>
-
-Binary ">=" returns true if the left argument is numerically greater
-than or equal to the right argument.
-X<< >= >>
-
-Binary "lt" returns true if the left argument is stringwise less than
-the right argument.
-X<< lt >>
-
-Binary "gt" returns true if the left argument is stringwise greater
-than the right argument.
-X<< gt >>
-
-Binary "le" returns true if the left argument is stringwise less than
-or equal to the right argument.
-X<< le >>
-
-Binary "ge" returns true if the left argument is stringwise greater
-than or equal to the right argument.
-X<< ge >>
-
-=head2 Equality Operators
-X<equality> X<equal> X<equals> X<operator, equality>
-
-Binary "==" returns true if the left argument is numerically equal to
-the right argument.
-X<==>
-
-Binary "!=" returns true if the left argument is numerically not equal
-to the right argument.
-X<!=>
-
-Binary "<=>" returns -1, 0, or 1 depending on whether the left
-argument is numerically less than, equal to, or greater than the right
-argument. If your platform supports NaNs (not-a-numbers) as numeric
-values, using them with "<=>" returns undef. NaN is not "<", "==", ">",
-"<=" or ">=" anything (even NaN), so those 5 return false. NaN != NaN
-returns true, as does NaN != anything else. If your platform doesn't
-support NaNs then NaN is just a string with numeric value 0.
-X<< <=> >> X<spaceship>
-
- $ perl -le '$a = "NaN"; print "No NaN support here" if $a == $a'
- $ perl -le '$a = "NaN"; print "NaN support here" if $a != $a'
-
-(Note that the L<bigint>, L<bigrat>, and L<bignum> pragmas all
-support "NaN".)
-
-Binary "eq" returns true if the left argument is stringwise equal to
-the right argument.
-X<eq>
-
-Binary "ne" returns true if the left argument is stringwise not equal
-to the right argument.
-X<ne>
-
-Binary "cmp" returns -1, 0, or 1 depending on whether the left
-argument is stringwise less than, equal to, or greater than the right
-argument.
-X<cmp>
-
-Binary "~~" does a smartmatch between its arguments. Smart matching
-is described in the next section.
-X<~~>
-
-"lt", "le", "ge", "gt" and "cmp" use the collation (sort) order specified
-by the current locale if a legacy C<use locale> (but not
-C<use locale ':not_characters'>) is in effect. See
-L<perllocale>. Do not mix these with Unicode, only with legacy binary
-encodings. The standard L<Unicode::Collate> and
-L<Unicode::Collate::Locale> modules offer much more powerful solutions to
-collation issues.
-
-=head2 Smartmatch Operator
-
-First available in Perl 5.10.1 (the 5.10.0 version behaved differently),
-binary C<~~> does a "smartmatch" between its arguments. This is mostly
-used implicitly in the C<when> construct described in L<perlsyn>, although
-not all C<when> clauses call the smartmatch operator. Unique among all of
-Perl's operators, the smartmatch operator can recurse.
-
-It is also unique in that all other Perl operators impose a context
-(usually string or numeric context) on their operands, autoconverting
-those operands to those imposed contexts. In contrast, smartmatch
-I<infers> contexts from the actual types of its operands and uses that
-type information to select a suitable comparison mechanism.
-
-The C<~~> operator compares its operands "polymorphically", determining how
-to compare them according to their actual types (numeric, string, array,
-hash, etc.) Like the equality operators with which it shares the same
-precedence, C<~~> returns 1 for true and C<""> for false. It is often best
-read aloud as "in", "inside of", or "is contained in", because the left
-operand is often looked for I<inside> the right operand. That makes the
-order of the operands to the smartmatch operand often opposite that of
-the regular match operator. In other words, the "smaller" thing is usually
-placed in the left operand and the larger one in the right.
-
-The behavior of a smartmatch depends on what type of things its arguments
-are, as determined by the following table. The first row of the table
-whose types apply determines the smartmatch behavior. Because what
-actually happens is mostly determined by the type of the second operand,
-the table is sorted on the right operand instead of on the left.
-
- Left Right Description and pseudocode
- ===============================================================
- Any undef check whether Any is undefined
- like: !defined Any
-
- Any Object invoke ~~ overloading on Object, or die
-
- Right operand is an ARRAY:
-
- Left Right Description and pseudocode
- ===============================================================
- ARRAY1 ARRAY2 recurse on paired elements of ARRAY1 and ARRAY2[2]
- like: (ARRAY1[0] ~~ ARRAY2[0])
- && (ARRAY1[1] ~~ ARRAY2[1]) && ...
- HASH ARRAY any ARRAY elements exist as HASH keys
- like: grep { exists HASH->{$_} } ARRAY
- Regexp ARRAY any ARRAY elements pattern match Regexp
- like: grep { /Regexp/ } ARRAY
- undef ARRAY undef in ARRAY
- like: grep { !defined } ARRAY
- Any ARRAY smartmatch each ARRAY element[3]
- like: grep { Any ~~ $_ } ARRAY
-
- Right operand is a HASH:
-
- Left Right Description and pseudocode
- ===============================================================
- HASH1 HASH2 all same keys in both HASHes
- like: keys HASH1 ==
- grep { exists HASH2->{$_} } keys HASH1
- ARRAY HASH any ARRAY elements exist as HASH keys
- like: grep { exists HASH->{$_} } ARRAY
- Regexp HASH any HASH keys pattern match Regexp
- like: grep { /Regexp/ } keys HASH
- undef HASH always false (undef can't be a key)
- like: 0 == 1
- Any HASH HASH key existence
- like: exists HASH->{Any}
-
- Right operand is CODE:
-
- Left Right Description and pseudocode
- ===============================================================
- ARRAY CODE sub returns true on all ARRAY elements[1]
- like: !grep { !CODE->($_) } ARRAY
- HASH CODE sub returns true on all HASH keys[1]
- like: !grep { !CODE->($_) } keys HASH
- Any CODE sub passed Any returns true
- like: CODE->(Any)
-
-Right operand is a Regexp:
-
- Left Right Description and pseudocode
- ===============================================================
- ARRAY Regexp any ARRAY elements match Regexp
- like: grep { /Regexp/ } ARRAY
- HASH Regexp any HASH keys match Regexp
- like: grep { /Regexp/ } keys HASH
- Any Regexp pattern match
- like: Any =~ /Regexp/
-
- Other:
-
- Left Right Description and pseudocode
- ===============================================================
- Object Any invoke ~~ overloading on Object,
- or fall back to...
-
- Any Num numeric equality
- like: Any == Num
- Num nummy[4] numeric equality
- like: Num == nummy
- undef Any check whether undefined
- like: !defined(Any)
- Any Any string equality
- like: Any eq Any
-
-
-Notes:
-
-=over
-
-=item 1.
-Empty hashes or arrays match.
-
-=item 2.
-That is, each element smartmatches the element of the same index in the other array.[3]
-
-=item 3.
-If a circular reference is found, fall back to referential equality.
-
-=item 4.
-Either an actual number, or a string that looks like one.
-
-=back
-
-The smartmatch implicitly dereferences any non-blessed hash or array
-reference, so the C<I<HASH>> and C<I<ARRAY>> entries apply in those cases.
-For blessed references, the C<I<Object>> entries apply. Smartmatches
-involving hashes only consider hash keys, never hash values.
-
-The "like" code entry is not always an exact rendition. For example, the
-smartmatch operator short-circuits whenever possible, but C<grep> does
-not. Also, C<grep> in scalar context returns the number of matches, but
-C<~~> returns only true or false.
-
-Unlike most operators, the smartmatch operator knows to treat C<undef>
-specially:
-
- use v5.10.1;
- @array = (1, 2, 3, undef, 4, 5);
- say "some elements undefined" if undef ~~ @array;
-
-Each operand is considered in a modified scalar context, the modification
-being that array and hash variables are passed by reference to the
-operator, which implicitly dereferences them. Both elements
-of each pair are the same:
-
- use v5.10.1;
-
- my %hash = (red => 1, blue => 2, green => 3,
- orange => 4, yellow => 5, purple => 6,
- black => 7, grey => 8, white => 9);
-
- my @array = qw(red blue green);
-
- say "some array elements in hash keys" if @array ~~ %hash;
- say "some array elements in hash keys" if \@array ~~ \%hash;
-
- say "red in array" if "red" ~~ @array;
- say "red in array" if "red" ~~ \@array;
-
- say "some keys end in e" if /e$/ ~~ %hash;
- say "some keys end in e" if /e$/ ~~ \%hash;
-
-Two arrays smartmatch if each element in the first array smartmatches
-(that is, is "in") the corresponding element in the second array,
-recursively.
-
- use v5.10.1;
- my @little = qw(red blue green);
- my @bigger = ("red", "blue", [ "orange", "green" ] );
- if (@little ~~ @bigger) { # true!
- say "little is contained in bigger";
- }
-
-Because the smartmatch operator recurses on nested arrays, this
-will still report that "red" is in the array.
-
- use v5.10.1;
- my @array = qw(red blue green);
- my $nested_array = [[[[[[[ @array ]]]]]]];
- say "red in array" if "red" ~~ $nested_array;
-
-If two arrays smartmatch each other, then they are deep
-copies of each others' values, as this example reports:
-
- use v5.12.0;
- my @a = (0, 1, 2, [3, [4, 5], 6], 7);
- my @b = (0, 1, 2, [3, [4, 5], 6], 7);
-
- if (@a ~~ @b && @b ~~ @a) {
- say "a and b are deep copies of each other";
- }
- elsif (@a ~~ @b) {
- say "a smartmatches in b";
- }
- elsif (@b ~~ @a) {
- say "b smartmatches in a";
- }
- else {
- say "a and b don't smartmatch each other at all";
- }
-
-
-If you were to set C<$b[3] = 4>, then instead of reporting that "a and b
-are deep copies of each other", it now reports that "b smartmatches in a".
-That because the corresponding position in C<@a> contains an array that
-(eventually) has a 4 in it.
-
-Smartmatching one hash against another reports whether both contain the
-same keys, no more and no less. This could be used to see whether two
-records have the same field names, without caring what values those fields
-might have. For example:
-
- use v5.10.1;
- sub make_dogtag {
- state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
-
- my ($class, $init_fields) = @_;
-
- die "Must supply (only) name, rank, and serial number"
- unless $init_fields ~~ $REQUIRED_FIELDS;
-
- ...
- }
-
-or, if other non-required fields are allowed, use ARRAY ~~ HASH:
-
- use v5.10.1;
- sub make_dogtag {
- state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
-
- my ($class, $init_fields) = @_;
-
- die "Must supply (at least) name, rank, and serial number"
- unless [keys %{$init_fields}] ~~ $REQUIRED_FIELDS;
-
- ...
- }
-
-The smartmatch operator is most often used as the implicit operator of a
-C<when> clause. See the section on "Switch Statements" in L<perlsyn>.
-
-=head3 Smartmatching of Objects
-
-To avoid relying on an object's underlying representation, if the
-smartmatch's right operand is an object that doesn't overload C<~~>,
-it raises the exception "C<Smartmatching a non-overloaded object
-breaks encapsulation>". That's because one has no business digging
-around to see whether something is "in" an object. These are all
-illegal on objects without a C<~~> overload:
-
- %hash ~~ $object
- 42 ~~ $object
- "fred" ~~ $object
-
-However, you can change the way an object is smartmatched by overloading
-the C<~~> operator. This is allowed to extend the usual smartmatch semantics.
-For objects that do have an C<~~> overload, see L<overload>.
-
-Using an object as the left operand is allowed, although not very useful.
-Smartmatching rules take precedence over overloading, so even if the
-object in the left operand has smartmatch overloading, this will be
-ignored. A left operand that is a non-overloaded object falls back on a
-string or numeric comparison of whatever the C<ref> operator returns. That
-means that
-
- $object ~~ X
-
-does I<not> invoke the overload method with C<I<X>> as an argument.
-Instead the above table is consulted as normal, and based on the type of
-C<I<X>>, overloading may or may not be invoked. For simple strings or
-numbers, in becomes equivalent to this:
-
- $object ~~ $number ref($object) == $number
- $object ~~ $string ref($object) eq $string
-
-For example, this reports that the handle smells IOish
-(but please don't really do this!):
-
- use IO::Handle;
- my $fh = IO::Handle->new();
- if ($fh ~~ /\bIO\b/) {
- say "handle smells IOish";
- }
-
-That's because it treats C<$fh> as a string like
-C<"IO::Handle=GLOB(0x8039e0)">, then pattern matches against that.
-
-=head2 Bitwise And
-X<operator, bitwise, and> X<bitwise and> X<&>
-
-Binary "&" returns its operands ANDed together bit by bit.
-(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
-
-Note that "&" has lower priority than relational operators, so for example
-the parentheses are essential in a test like
-
- print "Even\n" if ($x & 1) == 0;
-
-=head2 Bitwise Or and Exclusive Or
-X<operator, bitwise, or> X<bitwise or> X<|> X<operator, bitwise, xor>
-X<bitwise xor> X<^>
-
-Binary "|" returns its operands ORed together bit by bit.
-(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
-
-Binary "^" returns its operands XORed together bit by bit.
-(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
-
-Note that "|" and "^" have lower priority than relational operators, so
-for example the brackets are essential in a test like
-
- print "false\n" if (8 | 2) != 10;
-
-=head2 C-style Logical And
-X<&&> X<logical and> X<operator, logical, and>
-
-Binary "&&" performs a short-circuit logical AND operation. That is,
-if the left operand is false, the right operand is not even evaluated.
-Scalar or list context propagates down to the right operand if it
-is evaluated.
-
-=head2 C-style Logical Or
-X<||> X<operator, logical, or>
-
-Binary "||" performs a short-circuit logical OR operation. That is,
-if the left operand is true, the right operand is not even evaluated.
-Scalar or list context propagates down to the right operand if it
-is evaluated.
-
-=head2 Logical Defined-Or
-X<//> X<operator, logical, defined-or>
-
-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<< EXPR1 // EXPR2 >> returns the value of C<< EXPR1 >> if it's defined,
-otherwise, the value of C<< EXPR2 >> is returned. (C<< EXPR1 >> is evaluated
-in scalar context, C<< EXPR2 >> in the context of C<< // >> itself). Usually,
-this is the same result as C<< defined(EXPR1) ? EXPR1 : EXPR2 >> (except that
-the ternary-operator form can be used as a lvalue, while C<< EXPR1 // EXPR2 >>
-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";
-
-In particular, this means that you shouldn't use this
-for selecting between two aggregates for assignment:
-
- @a = @b || @c; # this is wrong
- @a = scalar(@b) || @c; # really meant this
- @a = @b ? @b : @c; # this works fine, though
-
-As alternatives to C<&&> and C<||> when used for
-control flow, Perl provides the C<and> and C<or> operators (see below).
-The short-circuit behavior is identical. The precedence of "and"
-and "or" is much lower, however, so that you can safely use them after a
-list operator without the need for parentheses:
-
- unlink "alpha", "beta", "gamma"
- or gripe(), next LINE;
-
-With the C-style operators that would have been written like this:
-
- unlink("alpha", "beta", "gamma")
- || (gripe(), next LINE);
-
-It would be even more readable to write that this way:
-
- unless(unlink("alpha", "beta", "gamma")) {
- gripe();
- next LINE;
- }
-
-Using "or" for assignment is unlikely to do what you want; see below.
-
-=head2 Range Operators
-X<operator, range> X<range> X<..> X<...>
-
-Binary ".." is the range operator, which is really two different
-operators depending on the context. In list context, it returns a
-list of values counting (up by ones) from the left value to the right
-value. If the left value is greater than the right value then it
-returns the empty list. The range operator is useful for writing
-C<foreach (1..10)> loops and for doing slice operations on arrays. In
-the current implementation, no temporary array is created when the
-range operator is used as the expression in C<foreach> loops, but older
-versions of Perl might burn a lot of memory when you write something
-like this:
-
- for (1 .. 1_000_000) {
- # code
- }
-
-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<sed>, B<awk>, 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<AFTER> 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<awk>), but it still returns
-true once. If you don't want it to test the right operand until the
-next evaluation, as in B<sed>, 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.
-
-If either operand of scalar ".." is a constant expression,
-that operand is considered true if it is equal (C<==>) to the current
-input line number (the C<$.> variable).
-
-To be pedantic, the comparison is actually C<int(EXPR) == int(EXPR)>,
-but that is only an issue if you use a floating point expression; when
-implicitly using C<$.> as described in the previous paragraph, the
-comparison is C<int(EXPR) == int($.)> which is only an issue when C<$.>
-is set to a floating point value and you are not reading from a file.
-Furthermore, C<"span" .. "spat"> or C<2.18 .. 3.14> will not do what
-you want in scalar context because each of the operands are evaluated
-using their integer representation.
-
-Examples:
-
-As a scalar operator:
-
- if (101 .. 200) { print; } # print 2nd hundred lines, short for
- # if ($. == 101 .. $. == 200) { print; }
-
- next LINE if (1 .. /^$/); # skip header lines, short for
- # next LINE if ($. == 1 .. /^$/);
- # (typically in a loop labeled LINE)
-
- s/^/> / if (/^$/ .. eof()); # quote body
-
- # parse mail messages
- while (<>) {
- $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
- }
-
-Here's a simple example to illustrate the difference between
-the two range operators:
-
- @lines = (" - Foo",
- "01 - Bar",
- "1 - Baz",
- " - Quux");
-
- foreach (@lines) {
- if (/0/ .. /1/) {
- print "$_\n";
- }
- }
-
-This program will print only the line containing "Bar". If
-the range operator is changed to C<...>, it will also print the
-"Baz" line.
-
-And now some examples as a list operator:
-
- for (101 .. 200) { print } # print $_ 100 times
- @foo = @foo[0 .. $#foo]; # an expensive no-op
- @foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items
-
-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");
-
-to get all normal letters of the English alphabet, or
-
- $hexdigit = (0 .. 9, "a" .. "f")[$num & 15];
-
-to get a hexadecimal digit, or
-
- @z2 = ("01" .. "31");
- print $z2[$mday];
-
-to get dates with leading zeros.
-
-If the final value specified is not in the sequence that the magical
-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 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";
- my @greek_small = ("\N{alpha}" .. "\N{omega}");
-
-To get the 25 traditional lowercase Greek letters, including both sigmas,
-you could use this instead:
-
- 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.
-
- @list = (2.18 .. 3.14); # same as @list = (2 .. 3);
-
-=head2 Conditional Operator
-X<operator, conditional> X<operator, ternary> X<ternary> X<?:>
-
-Ternary "?:" is the conditional operator, just as in C. It works much
-like an if-then-else. If the argument before the ? is true, the
-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";
-
-Scalar or list context propagates downward into the 2nd
-or 3rd argument, whichever is selected.
-
- $a = $ok ? $b : $c; # get a scalar
- @a = $ok ? @b : @c; # get an array
- $a = $ok ? @b : @c; # oops, that's just a count!
-
-The operator may be assigned to if both the 2nd and 3rd arguments are
-legal lvalues (meaning that you can assign to them):
-
- ($a_or_b ? $a : $b) = $c;
-
-Because this operator produces an assignable result, using assignments
-without parentheses will get you in trouble. For example, this:
-
- $a % 2 ? $a += 10 : $a += 2
-
-Really means this:
-
- (($a % 2) ? ($a += 10) : $a) += 2
-
-Rather than this:
-
- ($a % 2) ? ($a += 10) : ($a += 2)
-
-That should probably be written more simply as:
-
- $a += ($a % 2) ? 10 : 2;
-
-=head2 Assignment Operators
-X<assignment> X<operator, assignment> X<=> X<**=> X<+=> X<*=> X<&=>
-X<<< <<= >>> X<&&=> X<-=> X</=> X<|=> X<<< >>= >>> X<||=> X<//=> X<.=>
-X<%=> X<^=> X<x=>
-
-"=" is the ordinary assignment operator.
-
-Assignment operators work as in C. That is,
-
- $a += 2;
-
-is equivalent to
-
- $a = $a + 2;
-
-although without duplicating any side effects that dereferencing the lvalue
-might trigger, such as from tie(). Other assignment operators work similarly.
-The following are recognized:
-
- **= += *= &= <<= &&=
- -= /= |= >>= ||=
- .= %= ^= //=
- x=
-
-Although these are grouped by family, they all have the precedence
-of assignment.
-
-Unlike in C, the scalar assignment operator produces a valid lvalue.
-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/13579/24680/;
-
-Although as of 5.14, that can be also be accomplished this way:
-
- use v5.14;
- $tmp = ($global =~ tr/13579/24680/r);
-
-Likewise,
-
- ($a += 2) *= 3;
-
-is equivalent to
-
- $a += 2;
- $a *= 3;
-
-Similarly, a list assignment in list context produces the list of
-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 Comma Operator
-X<comma> X<operator, comma> X<,>
-
-Binary "," is the comma operator. In scalar context it evaluates
-its left argument, throws that value away, then evaluates its right
-argument and returns that value. This is just like C's comma operator.
-
-In list context, it's just the list argument separator, and inserts
-both its arguments into the list. These arguments are also evaluated
-from left to right.
-
-The C<< => >> operator is a synonym for the comma except that it causes a
-word on its left 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 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.
-
-For example:
-
- use constant FOO => "something";
-
- my %h = ( FOO => 23 );
-
-is equivalent to:
-
- my %h = ("FOO", 23);
-
-It is I<NOT>:
-
- my %h = ("something", 23);
-
-The C<< => >> operator is helpful in documenting the correspondence
-between keys and values in hashes, and other paired elements in lists.
-
- %hash = ( $key => $value );
- login( $username => $password );
-
-The special quoting behavior ignores precedence, and hence may apply to
-I<part> of the left operand:
-
- print time.shift => "bbb";
-
-That example prints something like "1314363215shiftbbb", because the
-C<< => >> implicitly quotes the C<shift> immediately on its left, ignoring
-the fact that C<time.shift> is the entire left operand.
-
-=head2 List Operators (Rightward)
-X<operator, list, rightward> X<list operator>
-
-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 parentheses:
-
- open HANDLE, "< :utf8", "filename" or die "Can't open: $!\n";
-
-However, some people find that code harder to read than writing
-it with parentheses:
-
- open(HANDLE, "< :utf8", "filename") or die "Can't open: $!\n";
-
-in which case you might as well just use the more customary "||" operator:
-
- open(HANDLE, "< :utf8", "filename") || die "Can't open: $!\n";
-
-See also discussion of list operators in L<Terms and List Operators (Leftward)>.
-
-=head2 Logical Not
-X<operator, logical, not> X<not>
-
-Unary "not" returns the logical negation of the expression to its right.
-It's the equivalent of "!" except for the very low precedence.
-
-=head2 Logical And
-X<operator, logical, and> X<and>
-
-Binary "and" returns the logical conjunction of the two surrounding
-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 and Exclusive Or
-X<operator, logical, or> X<operator, logical, xor>
-X<operator, logical, exclusive or>
-X<or> X<xor>
-
-Binary "or" returns the logical disjunction of the two surrounding
-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: 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
-C<||> for control flow, you probably need "or" so that the assignment
-takes higher precedence.
-
- @info = stat($file) || die; # oops, scalar sense of stat!
- @info = stat($file) or die; # better, now @info gets its due
-
-Then again, you could always use parentheses.
-
-Binary C<xor> returns the exclusive-OR of the two surrounding expressions.
-It cannot short-circuit (of course).
-
-There is no low precedence operator for defined-OR.
-
-=head2 C Operators Missing From Perl
-X<operator, missing from perl> X<&> X<*>
-X<typecasting> X<(TYPE)>
-
-Here is what C has that Perl doesn't:
-
-=over 8
-
-=item unary &
-
-Address-of operator. (But see the "\" operator for taking a reference.)
-
-=item unary *
-
-Dereference-address operator. (Perl's prefix dereferencing
-operators are typed: $, @, %, and &.)
-
-=item (TYPE)
-
-Type-casting operator.
-
-=back
-
-=head2 Quote and Quote-like Operators
-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
-for these behaviors, but also provides a way for you to choose your
-quote character for any of them. In the following table, a C<{}> represents
-any pair of delimiters you choose.
-
- Customary Generic Meaning Interpolates
- '' q{} Literal no
- "" qq{} Literal yes
- `` qx{} Command yes*
- qw{} Word list no
- // m{} Pattern match yes*
- 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 ASCII brackets (round, angle, square, curly) all nest, which means
-that
-
- q{foo{bar}baz}
-
-is the same as
-
- 'foo{bar}baz'
-
-Note, however, that this does not always work for quoting Perl code:
-
- $s = q{ if($a eq "}") ... }; # WRONG
-
-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.
-C<q#foo#> is parsed as the string C<foo>, while C<q #foo#> is the
-operator C<q> followed by a comment. Its argument will be taken
-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> 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)
-
-In other words, it's the character whose code point has had 64 xor'd with
-its uppercase. C<\c?> is DELETE because C<ord("@") ^ 64> is 127, and
-C<\c@> is NULL because the ord of "@" is 64, so xor'ing 64 itself produces 0.
-
-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 a later Perl version. What happens for any of these
-other characters currently though, is that the value is derived by xor'ing
-with the seventh bit, which is 64.
-
-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, in a regular expression it may be confused with a backreference;
-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. If C<"\n8"> is what you want, you can
-avoid this warning by padding 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 256th position (indexed by 0) in Unicode is
-C<LATIN CAPITAL LETTER A WITH MACRON>.
-
-There are a couple of exceptions to the above rule. S<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>
-does have meaning in regular expression patterns in Perl, see L<perlre>.)
-
-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> X<\F>
-
- \l lowercase next character only
- \u titlecase (not uppercase!) next character only
- \L lowercase all characters till \E or end of string
- \U uppercase all characters till \E or end of string
- \F foldcase all characters till \E or end of string
- \Q quote (disable) pattern metacharacters till \E or
- end of string
- \E end either case modification or quoted section
- (whichever was last seen)
-
-See L<perlfunc/quotemeta> for the exact definition of characters that
-are quoted by C<\Q>.
-
-C<\L>, C<\U>, C<\F>, 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 (but not C<use locale ':not_characters'>),
-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 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.
-Under C<use locale>, C<\F> produces the same results as C<\L>.
-
-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 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,
-and although they often accept just C<"\012">, they seldom tolerate just
-C<"\015">. If you get in the habit of using C<"\n"> for networking,
-you may be burned some day.
-X<newline> X<line terminator> X<eol> X<end of line>
-X<\n> X<\r> X<\r\n>
-
-For constructs that do interpolate, variables beginning with "C<$>"
-or "C<@>" are interpolated. Subscripted variables such as C<$a[3]> or
-C<< $href->{key}[0] >> are also interpolated, as are array and hash slices.
-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 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.
-
- "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
-interpolated, so that regular expressions may be incorporated into the
-pattern from the variables. If this is not what you want, use C<\Q> to
-interpolate a variable literally.
-
-Apart from the behavior described above, Perl does not expand
-multiple levels of interpolation. In particular, contrary to the
-expectations of shell programmers, back-quotes do I<NOT> interpolate
-within double quotes, nor do single quotes impede evaluation of
-variables when used within double quotes.
-
-=head2 Regexp Quote-Like Operators
-X<operator, regexp>
-
-Here are the quote-like operators that apply to pattern
-matching and related activities.
-
-=over 8
-
-=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/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";
-however, dereferencing it is not well defined (you currently get the
-normalized version of the original pattern, but this may change).
-
-
-For example,
-
- $rex = qr/my.STRING/is;
- print $rex; # prints (?si-xm:my.STRING)
- s/$rex/foo/;
-
-is equivalent to
-
- s/my.STRING/foo/is;
-
-The result may be used as a subpattern in a match:
-
- $re = qr/$pattern/;
- $string =~ /foo${re}bar/; # can be interpolated in other patterns
- $string =~ $re; # or used standalone
- $string =~ /$re/; # or this way
-
-Since Perl may compile the pattern at the moment of execution of the qr()
-operator, using qr() may have speed advantages in some situations,
-notably if the result of qr() is used standalone:
-
- sub match {
- my $patterns = shift;
- my @compiled = map qr/$_/i, @$patterns;
- grep {
- my $success = 0;
- foreach my $pat (@compiled) {
- $success = 1, last if /$pat/;
- }
- $success;
- } @_;
- }
-
-Precompilation of the pattern into an internal representation at
-the moment of qr() avoids a need to recompile the pattern every
-time a match C</$pat/> is attempted. (Perl has many other internal
-optimizations, but none would be triggered in the above example if
-we did not use qr() operator.)
-
-Options (specified by the following modifiers) are:
-
- m Treat string as multiple lines.
- s Treat string as single line. (Make . match a newline)
- i Do case-insensitive pattern matching.
- x Use extended regular expressions.
- p When matching preserve a copy of the matched string so
- that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined.
- o Compile pattern only once.
- a ASCII-restrict: 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
- l Use the locale
- u Use Unicode rules
- 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 "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, but C</a> is the only one you are likely
-to want to specify explicitly; the other three are selected
-automatically by various pragmas.
-
-See L<perlre> for additional information on valid syntax for STRING, and
-for a detailed look at the semantics of regular expressions. In
-particular, all modifiers except the largely obsolete C</o> are further
-explained in L<perlre/Modifiers>. C</o> is described in the next section.
-
-=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/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>.
-
-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.
-
-If "/" is the delimiter then the initial C<m> is optional. With the C<m>
-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 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
-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.)
-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 do 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
-
-The bottom line is that using C</o> is almost never a good idea.
-
-=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 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).
-
-Note that it's possible to confuse Perl into thinking C<//> (the empty
-regex) is really C<//> (the defined-or operator). Perl is usually pretty
-good about this, but some pathological cases might trigger this, such as
-C<$a///> (is that C<($a) / (//)> or C<$a // />?) and C<print $fh //>
-(C<print $fh(//> or C<print($fh //>?). In all of these examples, Perl
-will assume you meant defined-or. If you meant the empty regex, just
-use parentheses or spaces to disambiguate, or even prefix the empty
-regex with an C<m> (so C<//> becomes C<m//>).
-
-=item Matching in list context
-
-If the C</g> option is not used, C<m//> in list context returns a
-list consisting of the subexpressions matched by the parentheses in the
-pattern, that is, (C<$1>, C<$2>, C<$3>...). (Note that here C<$1> etc. are
-also set, and that this differs from Perl 4's behavior.) When there are
-no parentheses in the pattern, the return value is the list C<(1)> for
-success. With or without parentheses, an empty list is returned upon
-failure.
-
-Examples:
-
- open(TTY, "+</dev/tty")
- || die "can't access /dev/tty: $!";
-
- <TTY> =~ /^y/i && foo(); # do foo if desired
-
- if (/Version: *([0-9.]*)/) { $version = $1; }
-
- next if m#^/usr/spool/uucp#;
-
- # poor man's grep
- $arg = shift;
- while (<>) {
- 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; 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
-substrings matched by any capturing parentheses in the regular
-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 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 (for example, 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 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:
-
- # list context
- ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
-
- # scalar context
- local $/ = "";
- while ($paragraph = <>) {
- while ($paragraph =~ /\p{Ll}['")]*[.!?]+['")]*\s/g) {
- $sentences++;
- }
- }
- 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>:
-
- $_ = "ppooqppqq";
- while ($i++ < 2) {
- print "1: '";
- print $1 while /(o)/gc; print "', pos=", pos, "\n";
- print "2: '";
- print $1 if /\G(q)/gc; print "', pos=", pos, "\n";
- print "3: '";
- print $1 while /(p)/gc; print "', pos=", pos, "\n";
- }
- print "Final: '$1', pos=",pos,"\n" if /\G(.)/;
-
-The last example should print:
-
- 1: 'oo', pos=4
- 2: 'q', pos=5
- 3: 'pp', pos=7
- 1: '', pos=7
- 2: 'q', pos=8
- 3: '', pos=8
- Final: 'q', pos=8
-
-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 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,
-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";
- EOL
-
- 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 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 m?PATTERN?msixpodualgc
-X<?> X<operator, match-once>
-
-=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<m??>
-patterns local to the current package are reset.
-
- while (<>) {
- if (m?^$?) {
- # blank line between header and body
- }
- } continue {
- reset if eof; # clear m?? status for next file
- }
-
-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/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</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. 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
-PATTERN contains a $ that looks like a variable rather than an
-end-of-string test, the variable will be interpolated into the pattern
-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.
-
-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.
- 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
-are used, no interpretation is done on the replacement string (the C</e>
-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, for example,
-C<s(foo)(bar)> or C<< s<foo>/bar/ >>. A C</e> 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
-compile-time. A second C<e> modifier will cause the replacement portion
-to be C<eval>ed before being run as a Perl expression.
-
-Examples:
-
- s/\bgreen\b/mauve/g; # don't change wintergreen
-
- $path =~ s|/usr/bin|/usr/local/bin|;
-
- 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
-
- $_ = 'abc123xyz';
- s/\d+/$&*2/e; # yields 'abc246xyz'
- s/\d+/sprintf("%5d",$&)/e; # yields 'abc 246xyz'
- s/\w/$& x 2/eg; # yields 'aabbcc 224466xxyyzz'
-
- s/%(.)/$percent{$1}/g; # change percent escapes; no /e
- 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;
-
- # 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
- s/(\$\w+)/$1/eeg;
-
- # Delete (most) C comments.
- $program =~ s {
- /\* # Match the opening delimiter.
- .*? # Match a minimal number of characters.
- \*/ # Match the closing delimiter.
- } []gsx;
-
- s/^\s*(.*?)\s*$/$1/; # trim whitespace in $_, expensively
-
- for ($variable) { # trim whitespace in $variable, cheap
- s/^\s+//;
- s/\s+$//;
- }
-
- s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
-
-Note the use of $ instead of \ in the last example. Unlike
-B<sed>, we use the \<I<digit>> form in only the left hand side.
-Anywhere else it's $<I<digit>>.
-
-Occasionally, you can't use just a C</g> to get all the changes
-to occur that you might want. Here are two common cases:
-
- # put commas in the right places in an integer
- 1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g;
-
- # 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
-X<operator, quote-like>
-
-=over 4
-
-=item q/STRING/
-X<q> X<quote, single> X<'> X<''>
-
-=item 'STRING'
-
-A single-quoted, literal string. A backslash represents a backslash
-unless followed by the delimiter or another backslash, in which case
-the delimiter or backslash is interpolated.
-
- $foo = q!I said, "You said, 'She said it.'"!;
- $bar = q('This is it.');
- $baz = '\n'; # a two-character string
-
-=item qq/STRING/
-X<qq> X<quote, double> X<"> X<"">
-
-=item "STRING"
-
-A double-quoted, interpolated string.
-
- $_ .= qq
- (*** The previous line contains the naughty word "$1".\n)
- if /\b(tcl|java|python)\b/i; # :-)
- $baz = "\n"; # a one-character string
-
-=item qx/STRING/
-X<qx> X<`> X<``> X<backtick>
-
-=item `STRING`
-
-A string which is (possibly) interpolated and then executed as a
-system command with C</bin/sh> or its equivalent. Shell wildcards,
-pipes, and redirections will be honored. The collected standard
-output of the command is returned; standard error is unaffected. In
-scalar context, it comes back as a single (potentially multi-line)
-string, or undef if the command failed. In list context, returns a
-list of lines (however you've defined lines with $/ or
-$INPUT_RECORD_SEPARATOR), or an empty list if the command failed.
-
-Because backticks do not affect standard error, use shell file descriptor
-syntax (assuming the shell supports this) if you care to address this.
-To capture a command's STDERR and STDOUT together:
-
- $output = `cmd 2>&1`;
-
-To capture a command's STDOUT but discard its STDERR:
-
- $output = `cmd 2>/dev/null`;
-
-To capture a command's STDERR but discard its STDOUT (ordering is
-important here):
-
- $output = `cmd 2>&1 1>/dev/null`;
-
-To exchange a command's STDOUT and STDERR in order to capture the STDERR
-but leave its STDOUT to come out the old STDERR:
-
- $output = `cmd 3>&1 1>&2 2>&3 3>&-`;
-
-To read both a command's STDOUT and its STDERR separately, it's easiest
-to redirect them separately to files, and then read from those files
-when the program is done:
-
- system("program args 1>program.stdout 2>program.stderr");
-
-The STDIN filehandle used by the command is inherited from Perl's STDIN.
-For example:
-
- 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 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:
-
- $perl_info = qx(ps $$); # that's Perl's $$
- $shell_info = qx'ps $$'; # that's the new shell's $$
-
-How that string gets evaluated is entirely subject to the command
-interpreter on your system. On most platforms, you will have to protect
-shell metacharacters if you want them treated literally. This is in
-practice difficult to do, as it's unclear how to escape which characters.
-See L<perlsec> for a clean and safe example of a manual fork() and exec()
-to emulate backticks safely.
-
-On some platforms (notably DOS-like ones), the shell may not be
-capable of dealing with multiline commands, so putting newlines in
-the string may not get you what you want. You may be able to evaluate
-multiple commands in a single line by separating them with the command
-separator character, if your shell supports that (for example, C<;> on
-many Unix shells and C<&> on the Windows NT C<cmd> shell).
-
-Beginning with v5.6.0, Perl will attempt to flush all files opened for
-output before starting the child process, but this may not be supported
-on some platforms (see L<perlport>). To be safe, you may need to set
-C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
-C<IO::Handle> on any open handles.
-
-Beware that some command shells may place restrictions on the length
-of the command line. You must ensure your strings don't exceed this
-limit after any necessary interpolations. See the platform-specific
-release notes for more details about your particular environment.
-
-Using this operator can lead to programs that are difficult to port,
-because the shell commands called vary between systems, and may in
-fact not be present at all. As one example, the C<type> command under
-the POSIX shell is very different from the C<type> command under DOS.
-That doesn't mean you should go out of your way to avoid backticks
-when they're the right way to get something done. Perl was made to be
-a glue language, and one of the things it glues together is commands.
-Just understand what you're getting yourself into.
-
-See L</"I/O Operators"> for more discussion.
-
-=item qw/STRING/
-X<qw> X<quote, list> X<quote, words>
-
-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/);
-
-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
-this expression:
-
- qw(foo bar baz)
-
-is semantically equivalent to the list:
-
- "foo", "bar", "baz"
-
-Some frequently seen examples:
-
- use POSIX qw( setlocale localeconv )
- @EXPORT = qw( foo bar baz );
-
-A common mistake is to try to separate the words with comma or to
-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/cdsr
-X<tr> X<y> X<transliterate> X</c> X</d> X</s>
-
-=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 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;
-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
-you probably didn't expect. A sound principle is to use only ranges
-that begin from and end at either alphabets of equal case (a-e, A-E),
-or digits (0-4). Anything else is unsafe. If in doubt, spell out the
-character sets in full.
-
-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
-specified by SEARCHLIST not found in REPLACEMENTLIST are deleted.
-(Note that this is slightly more flexible than the behavior of some
-B<tr> programs, which delete anything they find in the SEARCHLIST,
-period.) If the C</s> modifier is specified, sequences of characters
-that were transliterated to the same character are squashed down
-to a single instance of the character.
-
-If the C</d> modifier is used, the REPLACEMENTLIST is always interpreted
-exactly as specified. Otherwise, if the REPLACEMENTLIST is shorter
-than the SEARCHLIST, the final character is replicated till it is long
-enough. If the REPLACEMENTLIST is empty, the SEARCHLIST is replicated.
-This latter is useful for counting characters in a class or for
-squashing character sequences in a class.
-
-Examples:
-
- $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case ASCII
-
- $cnt = tr/*/*/; # count the stars in $_
-
- $cnt = $sky =~ tr/*/*/; # count the stars in $sky
-
- $cnt = tr/0-9//; # count the digits in $_
-
- 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]; # wickedly delete 8th bit
-
-If multiple transliterations are given for a character, only the
-first one is used:
-
- tr/AAA/XYZ/
-
-will transliterate any A to X.
-
-Because the transliteration table is built at compile time, neither
-the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote
-interpolation. That means that if you want to use variables, you
-must use an eval():
-
- eval "tr/$oldlist/$newlist/";
- die $@ if $@;
-
- eval "tr/$oldlist/$newlist/, 1" or die $@;
-
-=item <<EOF
-X<here-doc> X<heredoc> X<here-document> X<<< << >>>
-
-A line-oriented form of quoting is based on the shell "here-document"
-syntax. Following a C<< << >> you specify a string to terminate
-the quoted material, and all lines following the current line down to
-the terminating string are the value of the item.
-
-The terminating string may be either an identifier (a word), or some
-quoted text. An unquoted identifier works like double quotes.
-There may not be a space between the C<< << >> and the identifier,
-unless the identifier is explicitly quoted. (If you put a space it
-will be treated as a null identifier, which is valid, and matches the
-first empty line.) The terminating string must appear by itself
-(unquoted and with no surrounding whitespace) on the terminating line.
-
-If the terminating string is quoted, the type of quotes used determine
-the treatment of the text.
-
-=over 4
-
-=item Double Quotes
-
-Double quotes indicate that the text will be interpolated using exactly
-the same rules as normal double quoted strings.
-
- print <<EOF;
- The price is $Price.
- EOF
-
- print << "EOF"; # same as above
- The price is $Price.
- EOF
-
-
-=item Single Quotes
-
-Single quotes indicate the text is to be treated literally with no
-interpolation of its content. This is similar to single quoted
-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.
-
-=item Backticks
-
-The content of the here doc is treated just as it would be if the
-string were embedded in backticks. Thus the content is interpolated
-as though it were double quoted and then executed via the shell, with
-the results of the execution returned.
-
- print << `EOC`; # execute command and get results
- echo hi there
- EOC
-
-=back
-
-It is possible to stack multiple here-docs in a row:
-
- print <<"foo", <<"bar"; # you can stack them
- I said foo.
- foo
- I said bar.
- bar
-
- myfunc(<< "THIS", 23, <<'THAT');
- Here's a line
- or two.
- THIS
- and here's another.
- THAT
-
-Just don't forget that you have to put a semicolon on the end
-to finish the statement, as Perl doesn't know you're not going to
-try to do this:
-
- print <<ABC
- 179231
- ABC
- + 20;
-
-If you want to remove the line terminator from your here-docs,
-use C<chomp()>.
-
- chomp($string = <<'END');
- This is a string.
- END
-
-If you want your here-docs to be indented with the rest of the code,
-you'll need to remove leading whitespace from each line manually:
-
- ($quote = <<'FINIS') =~ s/^\s+//gm;
- The Road goes ever on and on,
- down from the door where it began.
- FINIS
-
-If you use a here-doc within a delimited construct, such as in C<s///eg>,
-the quoted material must come on the lines following the final delimiter.
-So instead of
-
- s/this/<<E . 'that'
- the other
- E
- . 'more '/eg;
-
-you have to write
-
- s/this/<<E . 'that'
- . 'more '/eg;
- the other
- E
-
-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, 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:
-
- print << "abc\"def";
- testing...
- abc"def
-
-Finally, quoted strings cannot span multiple lines. The general rule is
-that the identifier must be a string literal. Stick with that, and you
-should be safe.
-
-=back
-
-=head2 Gory details of parsing quoted constructs
-X<quote, gory details>
-
-When presented with something that might have several different
-interpretations, Perl uses the B<DWIM> (that's "Do What I Mean")
-principle to pick the most probable interpretation. This strategy
-is so successful that Perl programmers often do not suspect the
-ambivalence of what they write. But from time to time, Perl's
-notions differ substantially from what the author honestly meant.
-
-This section hopes to clarify how Perl handles quoted constructs.
-Although the most common reason to learn this is to unravel labyrinthine
-regular expressions, because the initial steps of parsing are the
-same for all quoting operators, they are all discussed together.
-
-The most important Perl parsing rule is the first one discussed
-below: when processing a quoted construct, Perl first finds the end
-of that construct, then interprets its contents. If you understand
-this rule, you may skip the rest of this section on the first
-reading. The other rules are likely to contradict the user's
-expectations much less frequently than this first one.
-
-Some passes discussed below are performed concurrently, but because
-their results are the same, we consider them individually. For different
-quoting constructs, Perl performs different numbers of passes, from
-one to four, but these passes are always performed in the same order.
-
-=over 4
-
-=item Finding the end
-
-The first pass is finding the end of the quoted construct, where
-the information about the delimiters is used in parsing.
-During this search, text between the starting and ending delimiters
-is copied to a safe location. The text copied gets delimiter-independent.
-
-If the construct is a here-doc, the ending delimiter is a line
-that has a terminating string as the content. Therefore C<<<EOF> is
-terminated by C<EOF> immediately followed by C<"\n"> and starting
-from the first column of the terminating line.
-When searching for the terminating line of a here-doc, nothing
-is skipped. In other words, lines after the here-doc syntax
-are compared with the terminating string line by line.
-
-For the constructs except here-docs, single characters are used as starting
-and ending delimiters. If the starting delimiter is an opening punctuation
-(that is C<(>, C<[>, C<{>, or C<< < >>), the ending delimiter is the
-corresponding closing punctuation (that is C<)>, C<]>, C<}>, or C<< > >>).
-If the starting delimiter is an unpaired character like C</> or a closing
-punctuation, the ending delimiter is same as the starting delimiter.
-Therefore a C</> terminates a C<qq//> construct, while a C<]> terminates
-C<qq[]> and C<qq]]> constructs.
-
-When searching for single-character delimiters, escaped delimiters
-and C<\\> are skipped. For example, while searching for terminating C</>,
-combinations of C<\\> and C<\/> are skipped. If the delimiters are
-bracketing, nested pairs are also skipped. For example, while searching
-for closing C<]> paired with the opening C<[>, combinations of C<\\>, C<\]>,
-and C<\[> are all skipped, and nested C<[> and C<]> are skipped as well.
-However, when backslashes are used as the delimiters (like C<qq\\> and
-C<tr\\\>), nothing is skipped.
-During the search for the end, backslashes that escape delimiters or
-backslashes are removed (exactly speaking, they are not copied to the
-safe location).
-
-For constructs with three-part delimiters (C<s///>, C<y///>, and
-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 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, whitespace
-and comments are allowed between both parts, though the comment must follow
-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:
-
- "$hash{"$foo/$bar"}"
-
-or:
-
- m/
- bar # NOT a comment, this slash / terminated m//!
- /x
-
-do not form legal quoted expressions. The quoted part ends on the
-first C<"> and C</>, and the rest happens to be a syntax error.
-Because the slash that terminated C<m//> was followed by a C<SPACE>,
-the example above is not C<m//x>, but rather C<m//> with no C</x>
-modifier. So the embedded C<#> is interpreted as a literal C<#>.
-
-Also no attention is paid to C<\c\> (multichar control char syntax) during
-this search. Thus the second C<\> in C<qq/\c\/> is interpreted as a part
-of C<\/>, and the following C</> is not recognized as a delimiter.
-Instead, use C<\034> or C<\x1c> at the end of quoted constructs.
-
-=item Interpolation
-X<interpolation>
-
-The next step is interpolation in the text obtained, which is now
-delimiter-independent. There are multiple cases.
-
-=over 4
-
-=item C<<<'EOF'>
-
-No interpolation is performed.
-Note that the combination C<\\> is left intact, since escaped delimiters
-are not available for here-docs.
-
-=item C<m''>, the pattern of C<s'''>
-
-No interpolation is performed at this stage.
-Any backslashed sequences including C<\\> are treated at the stage
-to L</"parsing regular expressions">.
-
-=item C<''>, C<q//>, C<tr'''>, C<y'''>, the replacement of C<s'''>
-
-The only interpolation is removal of C<\> from pairs of C<\\>.
-Therefore C<-> in C<tr'''> and C<y'''> is treated literally
-as a hyphen and no character range is available.
-C<\1> in the replacement of C<s'''> does not work as C<$1>.
-
-=item C<tr///>, C<y///>
-
-No variable interpolation occurs. String modifying combinations for
-case and quoting such as C<\Q>, C<\U>, and C<\E> are not recognized.
-The other escape sequences such as C<\200> and C<\t> and backslashed
-characters such as C<\\> and C<\-> are converted to appropriate literals.
-The character C<-> is treated specially and therefore C<\-> is treated
-as a literal C<->.
-
-=item C<"">, C<``>, C<qq//>, C<qx//>, C<< <file*glob> >>, C<<<"EOF">
-
-C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F> (possibly paired with C<\E>) are
-converted to corresponding Perl constructs. Thus, C<"$foo\Qbaz$bar">
-is converted to C<$foo . (quotemeta("baz" . $bar))> internally.
-The other escape sequences such as C<\200> and C<\t> and backslashed
-characters such as C<\\> and C<\-> are replaced with appropriate
-expansions.
-
-Let it be stressed that I<whatever falls between C<\Q> and C<\E>>
-is interpolated in the usual way. Something like C<"\Q\\E"> has
-no C<\E> inside. instead, it has C<\Q>, C<\\>, and C<E>, so the
-result is the same as for C<"\\\\E">. As a general rule, backslashes
-between C<\Q> and C<\E> may lead to counterintuitive results. So,
-C<"\Q\t\E"> is converted to C<quotemeta("\t")>, which is the same
-as C<"\\\t"> (since TAB is not alphanumeric). Note also that:
-
- $str = '\t';
- return "\Q$str";
-
-may be closer to the conjectural I<intention> of the writer of C<"\Q\t\E">.
-
-Interpolated scalars and arrays are converted internally to the C<join> and
-C<.> catenation operations. Thus, C<"$foo XXX '@arr'"> becomes:
-
- $foo . " XXX '" . (join $", @arr) . "'";
-
-All operations above are performed simultaneously, left to right.
-
-Because the result of C<"\Q STRING \E"> has all metacharacters
-quoted, there is no way to insert a literal C<$> or C<@> inside a
-C<\Q\E> pair. If protected by C<\>, C<$> will be quoted to became
-C<"\\\$">; if not, it is interpreted as the start of an interpolated
-scalar.
-
-Note also that the interpolation code needs to make a decision on
-where the interpolated scalar ends. For instance, whether
-C<< "a $b -> {c}" >> really means:
-
- "a " . $b . " -> {c}";
-
-or:
-
- "a " . $b -> {c};
-
-Most of the time, the longest possible text that does not include
-spaces between components and which contains matching braces or
-brackets. because the outcome may be determined by voting based
-on heuristic estimators, the result is not strictly predictable.
-Fortunately, it's usually correct for ambiguous cases.
-
-=item the replacement of C<s///>
-
-Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F> and interpolation
-happens as with C<qq//> constructs.
-
-It is at this step that C<\1> is begrudgingly converted to C<$1> in
-the replacement text of C<s///>, in order to correct the incorrigible
-I<sed> hackers who haven't picked up the saner idiom yet. A warning
-is emitted if the C<use warnings> pragma or the B<-w> command-line flag
-(that is, the C<$^W> variable) was set.
-
-=item C<RE> in C<?RE?>, C</RE/>, C<m/RE/>, C<s/RE/foo/>,
-
-Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F>, C<\E>,
-and interpolation happens (almost) as with C<qq//> constructs.
-
-Processing of C<\N{...}> is also done here, and compiled into an intermediate
-form for the regex compiler. (This is because, as mentioned below, the regex
-compilation may be done at execution time, and C<\N{...}> is a compile-time
-construct.)
-
-However any other combinations of C<\> followed by a character
-are not substituted but only skipped, in order to parse them
-as regular expressions at the following step.
-As C<\c> is skipped at this step, C<@> of C<\c@> in RE is possibly
-treated as an array symbol (for example C<@foo>),
-even though the same text in C<qq//> gives interpolation of C<\c@>.
-
-Moreover, inside C<(?{BLOCK})>, C<(?# comment )>, and
-a C<#>-comment in a C<//x>-regular expression, no processing is
-performed whatsoever. This is the first step at which the presence
-of the C<//x> modifier is relevant.
-
-Interpolation in patterns has several quirks: C<$|>, C<$(>, C<$)>, C<@+>
-and C<@-> are not interpolated, and constructs C<$var[SOMETHING]> are
-voted (by several different estimators) to be either an array element
-or C<$var> followed by an RE alternative. This is where the notation
-C<${arr[$bar]}> comes handy: C</${arr[0-9]}/> is interpreted as
-array element C<-9>, not as a regular expression from the variable
-C<$arr> followed by a digit, which would be the interpretation of
-C</$arr[0-9]/>. Since voting among different estimators may occur,
-the result is not predictable.
-
-The lack of processing of C<\\> creates specific restrictions on
-the post-processed text. If the delimiter is C</>, one cannot get
-the combination C<\/> into the result of this step. C</> will
-finish the regular expression, C<\/> will be stripped to C</> on
-the previous step, and C<\\/> will be left as is. Because C</> is
-equivalent to C<\/> inside a regular expression, this does not
-matter unless the delimiter happens to be character special to the
-RE engine, such as in C<s*foo*bar*>, C<m[foo]>, or C<?foo?>; or an
-alphanumeric char, as in:
-
- m m ^ a \s* b mmx;
-
-In the RE above, which is intentionally obfuscated for illustration, the
-delimiter is C<m>, the modifier is C<mx>, and after delimiter-removal the
-RE is the same as for C<m/ ^ a \s* b /mx>. There's more than one
-reason you're encouraged to restrict your delimiters to non-alphanumeric,
-non-whitespace choices.
-
-=back
-
-This step is the last one for all constructs except regular expressions,
-which are processed further.
-
-=item parsing regular expressions
-X<regexp, parse>
-
-Previous steps were performed during the compilation of Perl code,
-but this one happens at run time, although it may be optimized to
-be calculated at compile time if appropriate. After preprocessing
-described above, and possibly after evaluation if concatenation,
-joining, casing translation, or metaquoting are involved, the
-resulting I<string> is passed to the RE engine for compilation.
-
-Whatever happens in the RE engine might be better discussed in L<perlre>,
-but for the sake of continuity, we shall do so here.
-
-This is another step where the presence of the C<//x> modifier is
-relevant. The RE engine scans the string from left to right and
-converts it to a finite automaton.
-
-Backslashed characters are either replaced with corresponding
-literal strings (as with C<\{>), or else they generate special nodes
-in the finite automaton (as with C<\b>). Characters special to the
-RE engine (such as C<|>) generate corresponding nodes or groups of
-nodes. C<(?#...)> comments are ignored. All the rest is either
-converted to literal strings to match, or else is ignored (as is
-whitespace and C<#>-style comments if C<//x> is present).
-
-Parsing of the bracketed character class construct, C<[...]>, is
-rather different than the rule used for the rest of the pattern.
-The terminator of this construct is found using the same rules as
-for finding the terminator of a C<{}>-delimited construct, the only
-exception being that C<]> immediately following C<[> is treated as
-though preceded by a backslash. Similarly, the terminator of
-C<(?{...})> is found using the same rules as for finding the
-terminator of a C<{}>-delimited construct.
-
-It is possible to inspect both the string given to RE engine and the
-resulting finite automaton. See the arguments C<debug>/C<debugcolor>
-in the C<use L<re>> pragma, as well as Perl's B<-Dr> command-line
-switch documented in L<perlrun/"Command Switches">.
-
-=item Optimization of regular expressions
-X<regexp, optimization>
-
-This step is listed for completeness only. Since it does not change
-semantics, details of this step are not documented and are subject
-to change without notice. This step is performed over the finite
-automaton that was generated during the previous pass.
-
-It is at this stage that C<split()> silently optimizes C</^/> to
-mean C</^/m>.
-
-=back
-
-=head2 I/O Operators
-X<operator, i/o> X<operator, io> X<io> X<while> X<filehandle>
-X<< <> >> X<@ARGV>
-
-There are several I/O operators you should know about.
-
-A string enclosed by backticks (grave accents) first undergoes
-double-quote interpolation. It is then interpreted as an external
-command, and the output of that command is the value of the
-backtick string, like in a shell. In scalar context, a single string
-consisting of all output is returned. In list context, a list of
-values is returned, one per line of output. (You can set C<$/> to use
-a different line terminator.) The command is executed each time the
-pseudo-literal is evaluated. The status value of the command is
-returned in C<$?> (see L<perlvar> for the interpretation of C<$?>).
-Unlike in B<csh>, no translation is done on the return data--newlines
-remain newlines. Unlike in any of the shells, single quotes do not
-hide variable names in the command from interpretation. To pass a
-literal dollar-sign through to the shell you need to hide it with a
-backslash. The generalized form of backticks is C<qx//>. (Because
-backticks always undergo shell expansion as well, see L<perlsec> for
-security concerns.)
-X<qx> X<`> X<``> X<backtick> X<glob>
-
-In scalar context, evaluating a filehandle in angle brackets yields
-the next line from that file (the newline, if any, included), or
-C<undef> at end-of-file or on error. When C<$/> is set to C<undef>
-(sometimes known as file-slurp mode) and the file is empty, it
-returns C<''> the first time, followed by C<undef> subsequently.
-
-Ordinarily you must assign the returned value to a variable, but
-there is one situation where an automatic assignment happens. If
-and only if the input symbol is the only thing inside the conditional
-of a C<while> statement (even if disguised as a C<for(;;)> loop),
-the value is automatically assigned to the global variable $_,
-destroying whatever was there previously. (This may seem like an
-odd thing to you, but you'll use the construct in almost every Perl
-script you write.) The $_ variable is not implicitly localized.
-You'll have to put a C<local $_;> before the loop if you want that
-to happen.
-
-The following lines are equivalent:
-
- while (defined($_ = <STDIN>)) { print; }
- while ($_ = <STDIN>) { print; }
- while (<STDIN>) { print; }
- for (;<STDIN>;) { print; }
- print while defined($_ = <STDIN>);
- print while ($_ = <STDIN>);
- print while <STDIN>;
-
-This also behaves similarly, but assigns to a lexical variable
-instead of to C<$_>:
-
- while (my $line = <STDIN>) { print $line }
-
-In these loop constructs, the assigned value (whether assignment
-is automatic or explicit) is then tested to see whether it is
-defined. The defined test avoids problems where the line has a string
-value that would be treated as false by Perl; for example a "" or
-a "0" with no trailing newline. If you really mean for such values
-to terminate the loop, they should be tested for explicitly:
-
- while (($_ = <STDIN>) ne '0') { ... }
- while (<STDIN>) { last unless $_; ... }
-
-In other boolean contexts, C<< <FILEHANDLE> >> without an
-explicit C<defined> test or comparison elicits a warning if the
-C<use warnings> pragma or the B<-w>
-command-line switch (the C<$^W> variable) is in effect.
-
-The filehandles STDIN, STDOUT, and STDERR are predefined. (The
-filehandles C<stdin>, C<stdout>, and C<stderr> will also work except
-in packages, where they would be interpreted as local identifiers
-rather than global.) Additional filehandles may be created with
-the open() function, amongst others. See L<perlopentut> and
-L<perlfunc/open> for details on this.
-X<stdin> X<stdout> X<sterr>
-
-If a <FILEHANDLE> is used in a context that is looking for
-a list, a list comprising all input lines is returned, one line per
-list element. It's easy to grow to a rather large data space this
-way, so use with care.
-
-<FILEHANDLE> may also be spelled C<readline(*FILEHANDLE)>.
-See L<perlfunc/readline>.
-
-The null filehandle <> is special: it can be used to emulate the
-behavior of B<sed> and B<awk>, and any other Unix filter program
-that takes a list of filenames, doing the same to each line
-of input from all of them. Input from <> comes either from
-standard input, or from each file listed on the command line. Here's
-how it works: the first time <> is evaluated, the @ARGV array is
-checked, and if it is empty, C<$ARGV[0]> is set to "-", which when opened
-gives you standard input. The @ARGV array is then processed as a list
-of filenames. The loop
-
- while (<>) {
- ... # code for each line
- }
-
-is equivalent to the following Perl-like pseudo code:
-
- unshift(@ARGV, '-') unless @ARGV;
- while ($ARGV = shift) {
- open(ARGV, $ARGV);
- while (<ARGV>) {
- ... # code for each line
- }
- }
-
-except that it isn't so cumbersome to say, and will actually work.
-It really does shift the @ARGV array and put the current filename
-into the $ARGV variable. It also uses filehandle I<ARGV>
-internally. <> is just a synonym for <ARGV>, which
-is magical. (The pseudo code above doesn't work because it treats
-<ARGV> as non-magical.)
-
-Since the null filehandle uses the two argument form of L<perlfunc/open>
-it interprets special characters, so if you have a script like this:
-
- while (<>) {
- print;
- }
-
-and call it with C<perl dangerous.pl 'rm -rfv *|'>, it actually opens a
-pipe, executes the C<rm> command and reads C<rm>'s output from that pipe.
-If you want all items in C<@ARGV> to be interpreted as file names, you
-can use the module C<ARGV::readonly> from CPAN.
-
-You can modify @ARGV before the first <> as long as the array ends up
-containing the list of filenames you really want. Line numbers (C<$.>)
-continue as though the input were one big happy file. See the example
-in L<perlfunc/eof> for how to reset line numbers on each file.
-
-If you want to set @ARGV to your own list of files, go right ahead.
-This sets @ARGV to all plain text files if no @ARGV was given:
-
- @ARGV = grep { -f && -T } glob('*') unless @ARGV;
-
-You can even set them to pipe commands. For example, this automatically
-filters compressed arguments through B<gzip>:
-
- @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc < $_ |" : $_ } @ARGV;
-
-If you want to pass switches into your script, you can use one of the
-Getopts modules or put a loop on the front like this:
-
- while ($_ = $ARGV[0], /^-/) {
- shift;
- last if /^--$/;
- if (/^-D(.*)/) { $debug = $1 }
- if (/^-v/) { $verbose++ }
- # ... # other switches
- }
-
- while (<>) {
- # ... # code for each line
- }
-
-The <> symbol will return C<undef> for end-of-file only once.
-If you call it again after this, it will assume you are processing another
-@ARGV list, and if you haven't set @ARGV, will read input from STDIN.
-
-If what the angle brackets contain is a simple scalar variable (for example,
-<$foo>), then that variable contains the name of the
-filehandle to input from, or its typeglob, or a reference to the
-same. For example:
-
- $fh = \*STDIN;
- $line = <$fh>;
-
-If what's within the angle brackets is neither a filehandle nor a simple
-scalar variable containing a filehandle name, typeglob, or typeglob
-reference, it is interpreted as a filename pattern to be globbed, and
-either a list of filenames or the next filename in the list is returned,
-depending on context. This distinction is determined on syntactic
-grounds alone. That means C<< <$x> >> is always a readline() from
-an indirect handle, but C<< <$hash{key}> >> is always a glob().
-That's because $x is a simple scalar variable, but C<$hash{key}> is
-not--it's a hash element. Even C<< <$x > >> (note the extra space)
-is treated as C<glob("$x ")>, not C<readline($x)>.
-
-One level of double-quote interpretation is done first, but you can't
-say C<< <$foo> >> because that's an indirect filehandle as explained
-in the previous paragraph. (In older versions of Perl, programmers
-would insert curly brackets to force interpretation as a filename glob:
-C<< <${foo}> >>. These days, it's considered cleaner to call the
-internal function directly as C<glob($foo)>, which is probably the right
-way to have done it in the first place.) For example:
-
- while (<*.c>) {
- chmod 0644, $_;
- }
-
-is roughly equivalent to:
-
- open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|");
- while (<FOO>) {
- chomp;
- chmod 0644, $_;
- }
-
-except that the globbing is actually done internally using the standard
-C<File::Glob> extension. Of course, the shortest way to do the above is:
-
- chmod 0644, <*.c>;
-
-A (file)glob evaluates its (embedded) argument only when it is
-starting a new list. All values must be read before it will start
-over. In list context, this isn't important because you automatically
-get them all anyway. However, in scalar context the operator returns
-the next value each time it's called, or C<undef> when the list has
-run out. As with filehandle reads, an automatic C<defined> is
-generated when the glob occurs in the test part of a C<while>,
-because legal glob returns (for example,
-a file called F<0>) would otherwise
-terminate the loop. Again, C<undef> is returned only once. So if
-you're expecting a single value from a glob, it is much better to
-say
-
- ($file) = <blurch*>;
-
-than
-
- $file = <blurch*>;
-
-because the latter will alternate between returning a filename and
-returning false.
-
-If you're trying to do variable interpolation, it's definitely better
-to use the glob() function, because the older notation can cause people
-to become confused with the indirect filehandle notation.
-
- @files = glob("$dir/*.[ch]");
- @files = glob($files[$i]);
-
-=head2 Constant Folding
-X<constant folding> X<folding>
-
-Like C, Perl does a certain amount of expression evaluation at
-compile time whenever it determines that all arguments to an
-operator are static and have no side effects. In particular, string
-concatenation happens at compile time between literals that don't do
-variable substitution. Backslash interpolation also happens at
-compile time. You can say
-
- 'Now is the time for all'
- . "\n"
- . 'good men to come to.'
-
-and this all reduces to one string internally. Likewise, if
-you say
-
- foreach $file (@filenames) {
- if (-s $file > 5 + 100 * 2**16) { }
- }
-
-the compiler precomputes the number which that expression
-represents so that the interpreter won't have to.
-
-=head2 No-ops
-X<no-op> X<nop>
-
-Perl doesn't officially have a no-op operator, but the bare constants
-C<0> and C<1> are special-cased not to produce a warning in void
-context, so you can for example safely do
-
- 1 while foo();
-
-=head2 Bitwise String Operators
-X<operator, bitwise, string>
-
-Bitstrings of any size may be manipulated by the bitwise operators
-(C<~ | & ^>).
-
-If the operands to a binary bitwise op are strings of different
-sizes, B<|> and B<^> ops act as though the shorter operand had
-additional zero bits on the right, while the B<&> op acts as though
-the longer operand were truncated to the length of the shorter.
-The granularity for such extension or truncation is one or more
-bytes.
-
- # ASCII-based examples
- print "j p \n" ^ " a h"; # prints "JAPH\n"
- print "JA" | " ph\n"; # prints "japh\n"
- print "japh\nJunk" & '_____'; # prints "JAPH\n";
- print 'p N$' ^ " E<H\n"; # prints "Perl\n";
-
-If you are intending to manipulate bitstrings, be certain that
-you're supplying bitstrings: If an operand is a number, that will imply
-a B<numeric> bitwise operation. You may explicitly show which type of
-operation you intend by using C<""> or C<0+>, as in the examples below.
-
- $foo = 150 | 105; # yields 255 (0x96 | 0x69 is 0xFF)
- $foo = '150' | 105; # yields 255
- $foo = 150 | '105'; # yields 255
- $foo = '150' | '105'; # yields string '155' (under ASCII)
-
- $baz = 0+$foo & 0+$bar; # both ops explicitly numeric
- $biz = "$foo" ^ "$bar"; # both ops explicitly stringy
-
-See L<perlfunc/vec> for information on how to manipulate individual bits
-in a bit vector.
-
-=head2 Integer Arithmetic
-X<integer>
-
-By default, Perl assumes that it must do most of its arithmetic in
-floating point. But by saying
-
- use integer;
-
-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 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
-L<Bitwise String Operators>.) However, C<use integer> still has meaning for
-them. By default, their results are interpreted as unsigned integers, but
-if C<use integer> is in effect, their results are interpreted
-as signed integers. For example, C<~0> usually evaluates to a large
-integral value. However, C<use integer; ~0> is C<-1> on two's-complement
-machines.
-
-=head2 Floating-point Arithmetic
-
-X<floating-point> X<floating point> X<float> X<real>
-
-While C<use integer> provides integer-only arithmetic, there is no
-analogous mechanism to provide automatic rounding or truncation to a
-certain number of decimal places. For rounding to a certain number
-of digits, sprintf() or printf() is usually the easiest route.
-See L<perlfaq4>.
-
-Floating-point numbers are only approximations to what a mathematician
-would call real numbers. There are infinitely more reals than floats,
-so some corners must be cut. For example:
-
- printf "%.20g\n", 123456789123456789;
- # produces 123456789123456784
-
-Testing for exact floating-point equality or inequality is not a
-good idea. Here's a (relatively expensive) work-around to compare
-whether two floating-point numbers are equal to a particular number of
-decimal places. See Knuth, volume II, for a more robust treatment of
-this topic.
-
- sub fp_equal {
- my ($X, $Y, $POINTS) = @_;
- my ($tX, $tY);
- $tX = sprintf("%.${POINTS}g", $X);
- $tY = sprintf("%.${POINTS}g", $Y);
- return $tX eq $tY;
- }
-
-The POSIX module (part of the standard perl distribution) implements
-ceil(), floor(), and other mathematical and trigonometric functions.
-The Math::Complex module (part of the standard perl distribution)
-defines mathematical functions that work on both the reals and the
-imaginary numbers. Math::Complex not as efficient as POSIX, but
-POSIX can't work with complex numbers.
-
-Rounding in financial applications can have serious implications, and
-the rounding method used should be specified precisely. In these
-cases, it probably pays not to trust whichever system rounding is
-being used by Perl, but to instead implement the rounding function you
-need yourself.
-
-=head2 Bigger Numbers
-X<number, arbitrary precision>
-
-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 5.010;
- use bigint; # easy interface to Math::BigInt
- $x = 123456789123456789;
- say $x * $x;
- +15241578780673678515622620750190521
-
-Or with rationals:
-
- 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
-
-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
-
-Choose wisely.
-
-=cut