This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlop: improve tr/// documentation
[perl5.git] / pod / perlop.pod
CommitLineData
a0d0e21e 1=head1 NAME
d74e8afc 2X<operator>
a0d0e21e
LW
3
4perlop - Perl operators and precedence
5
d042e63d
MS
6=head1 DESCRIPTION
7
ae3f7391 8In Perl, the operator determines what operation is performed,
ba7f043c 9independent of the type of the operands. For example S<C<$x + $y>>
db691027 10is always a numeric addition, and if C<$x> or C<$y> do not contain
ae3f7391
ML
11numbers, an attempt is made to convert them to numbers first.
12
13This is in contrast to many other dynamic languages, where the
46f8a5ea 14operation is determined by the type of the first argument. It also
ae3f7391 15means that Perl has two versions of some operators, one for numeric
ba7f043c
KW
16and one for string comparison. For example S<C<$x == $y>> compares
17two numbers for equality, and S<C<$x eq $y>> compares two strings.
ae3f7391
ML
18
19There are a few exceptions though: C<x> can be either string
20repetition or list repetition, depending on the type of the left
0b55efd7 21operand, and C<&>, C<|>, C<^> and C<~> can be either string or numeric bit
ae3f7391
ML
22operations.
23
89d205f2 24=head2 Operator Precedence and Associativity
d74e8afc 25X<operator, precedence> X<precedence> X<associativity>
d042e63d
MS
26
27Operator precedence and associativity work in Perl more or less like
28they do in mathematics.
29
3c0dbbba
Z
30I<Operator precedence> means some operators group more tightly than others.
31For example, in C<2 + 4 * 5>, the multiplication has higher precedence, so C<4
32* 5> is grouped together as the right-hand operand of the addition, rather
33than C<2 + 4> being grouped together as the left-hand operand of the
34multiplication. It is as if the expression were written C<2 + (4 * 5)>, not
35C<(2 + 4) * 5>. So the expression yields C<2 + 20 == 22>, rather than
36C<6 * 5 == 30>.
d042e63d 37
3c0dbbba
Z
38I<Operator associativity> defines what happens if a sequence of the same
39operators is used one after another: whether they will be grouped at the left
40or the right. For example, in C<9 - 3 - 2>, subtraction is left associative,
41so C<9 - 3> is grouped together as the left-hand operand of the second
42subtraction, rather than C<3 - 2> being grouped together as the right-hand
43operand of the first subtraction. It is as if the expression were written
44C<(9 - 3) - 2>, not C<9 - (3 - 2)>. So the expression yields C<6 - 2 == 4>,
45rather than C<9 - 1 == 8>.
46
47For simple operators that evaluate all their operands and then combine the
48values in some way, precedence and associativity (and parentheses) imply some
49ordering requirements on those combining operations. For example, in C<2 + 4 *
505>, the grouping implied by precedence means that the multiplication of 4 and
515 must be performed before the addition of 2 and 20, simply because the result
52of that multiplication is required as one of the operands of the addition. But
53the order of operations is not fully determined by this: in C<2 * 2 + 4 * 5>
54both multiplications must be performed before the addition, but the grouping
55does not say anything about the order in which the two multiplications are
56performed. In fact Perl has a general rule that the operands of an operator
57are evaluated in left-to-right order. A few operators such as C<&&=> have
58special evaluation rules that can result in an operand not being evaluated at
59all; in general, the top-level operator in an expression has control of
60operand evaluation.
a0d0e21e
LW
61
62Perl operators have the following associativity and precedence,
19799a22
GS
63listed from highest precedence to lowest. Operators borrowed from
64C keep the same precedence relationship with each other, even where
65C's precedence is slightly screwy. (This makes learning Perl easier
66for C folks.) With very few exceptions, these all operate on scalar
67values only, not array values.
a0d0e21e
LW
68
69 left terms and list operators (leftward)
70 left ->
71 nonassoc ++ --
72 right **
73 right ! ~ \ and unary + and -
54310121 74 left =~ !~
a0d0e21e
LW
75 left * / % x
76 left + - .
77 left << >>
78 nonassoc named unary operators
79 nonassoc < > <= >= lt gt le ge
0d863452 80 nonassoc == != <=> eq ne cmp ~~
a0d0e21e
LW
81 left &
82 left | ^
83 left &&
c963b151 84 left || //
137443ea 85 nonassoc .. ...
a0d0e21e 86 right ?:
2ba1f20a 87 right = += -= *= etc. goto last next redo dump
a0d0e21e
LW
88 left , =>
89 nonassoc list operators (rightward)
a5f75d66 90 right not
a0d0e21e 91 left and
f23102e2 92 left or xor
a0d0e21e 93
3df91f1a
DM
94In the following sections, these operators are covered in detail, in the
95same order in which they appear in the table above.
a0d0e21e 96
5a964f20
TC
97Many operators can be overloaded for objects. See L<overload>.
98
a0d0e21e 99=head2 Terms and List Operators (Leftward)
d74e8afc 100X<list operator> X<operator, list> X<term>
a0d0e21e 101
62c18ce2 102A TERM has the highest precedence in Perl. They include variables,
5f05dabc 103quote and quote-like operators, any expression in parentheses,
a0d0e21e
LW
104and any function whose arguments are parenthesized. Actually, there
105aren't really functions in this sense, just list operators and unary
106operators behaving as functions because you put parentheses around
107the arguments. These are all documented in L<perlfunc>.
108
ba7f043c 109If any list operator (C<print()>, etc.) or any unary operator (C<chdir()>, etc.)
a0d0e21e
LW
110is followed by a left parenthesis as the next token, the operator and
111arguments within parentheses are taken to be of highest precedence,
112just like a normal function call.
113
114In the absence of parentheses, the precedence of list operators such as
115C<print>, C<sort>, or C<chmod> is either very high or very low depending on
54310121 116whether you are looking at the left side or the right side of the operator.
a0d0e21e
LW
117For example, in
118
119 @ary = (1, 3, sort 4, 2);
120 print @ary; # prints 1324
121
ba7f043c 122the commas on the right of the C<sort> are evaluated before the C<sort>,
19799a22
GS
123but the commas on the left are evaluated after. In other words,
124list operators tend to gobble up all arguments that follow, and
a0d0e21e 125then act like a simple TERM with regard to the preceding expression.
19799a22 126Be careful with parentheses:
a0d0e21e
LW
127
128 # These evaluate exit before doing the print:
129 print($foo, exit); # Obviously not what you want.
130 print $foo, exit; # Nor is this.
131
132 # These do the print before evaluating exit:
133 (print $foo), exit; # This is what you want.
134 print($foo), exit; # Or this.
135 print ($foo), exit; # Or even this.
136
137Also note that
138
139 print ($foo & 255) + 1, "\n";
140
d042e63d
MS
141probably doesn't do what you expect at first glance. The parentheses
142enclose the argument list for C<print> which is evaluated (printing
ba7f043c 143the result of S<C<$foo & 255>>). Then one is added to the return value
d042e63d
MS
144of C<print> (usually 1). The result is something like this:
145
146 1 + 1, "\n"; # Obviously not what you meant.
147
148To do what you meant properly, you must write:
149
150 print(($foo & 255) + 1, "\n");
151
5a0de581 152See L</Named Unary Operators> for more discussion of this.
a0d0e21e 153
ba7f043c 154Also parsed as terms are the S<C<do {}>> and S<C<eval {}>> constructs, as
54310121 155well as subroutine and method calls, and the anonymous
a0d0e21e
LW
156constructors C<[]> and C<{}>.
157
5a0de581 158See also L</Quote and Quote-like Operators> toward the end of this section,
da87341d 159as well as L</"I/O Operators">.
a0d0e21e
LW
160
161=head2 The Arrow Operator
d74e8afc 162X<arrow> X<dereference> X<< -> >>
a0d0e21e 163
35f2feb0 164"C<< -> >>" is an infix dereference operator, just as it is in C
19799a22
GS
165and C++. If the right side is either a C<[...]>, C<{...}>, or a
166C<(...)> subscript, then the left side must be either a hard or
167symbolic reference to an array, a hash, or a subroutine respectively.
168(Or technically speaking, a location capable of holding a hard
169reference, if it's an array or hash reference being used for
170assignment.) See L<perlreftut> and L<perlref>.
a0d0e21e 171
19799a22
GS
172Otherwise, the right side is a method name or a simple scalar
173variable containing either the method name or a subroutine reference,
174and the left side must be either an object (a blessed reference)
175or a class name (that is, a package name). See L<perlobj>.
a0d0e21e 176
821361b6 177The dereferencing cases (as opposed to method-calling cases) are
2ad792cd 178somewhat extended by the C<postderef> feature. For the
821361b6
RS
179details of that feature, consult L<perlref/Postfix Dereference Syntax>.
180
5f05dabc 181=head2 Auto-increment and Auto-decrement
d74e8afc 182X<increment> X<auto-increment> X<++> X<decrement> X<auto-decrement> X<-->
a0d0e21e 183
ba7f043c 184C<"++"> and C<"--"> work as in C. That is, if placed before a variable,
d042e63d
MS
185they increment or decrement the variable by one before returning the
186value, and if placed after, increment or decrement after returning the
187value.
188
189 $i = 0; $j = 0;
190 print $i++; # prints 0
191 print ++$j; # prints 1
a0d0e21e 192
b033823e 193Note that just as in C, Perl doesn't define B<when> the variable is
46f8a5ea
FC
194incremented or decremented. You just know it will be done sometime
195before or after the value is returned. This also means that modifying
c543c01b 196a variable twice in the same statement will lead to undefined behavior.
b033823e
A
197Avoid statements like:
198
199 $i = $i ++;
200 print ++ $i + $i ++;
201
202Perl will not guarantee what the result of the above statements is.
203
54310121 204The auto-increment operator has a little extra builtin magic to it. If
a0d0e21e
LW
205you increment a variable that is numeric, or that has ever been used in
206a numeric context, you get a normal increment. If, however, the
5f05dabc 207variable has been used in only string contexts since it was set, and
5a964f20 208has a value that is not the empty string and matches the pattern
9c0670e1 209C</^[a-zA-Z]*[0-9]*\z/>, the increment is done as a string, preserving each
a0d0e21e
LW
210character within its range, with carry:
211
c543c01b
TC
212 print ++($foo = "99"); # prints "100"
213 print ++($foo = "a0"); # prints "a1"
214 print ++($foo = "Az"); # prints "Ba"
215 print ++($foo = "zz"); # prints "aaa"
a0d0e21e 216
6a61d433
HS
217C<undef> is always treated as numeric, and in particular is changed
218to C<0> before incrementing (so that a post-increment of an undef value
219will return C<0> rather than C<undef>).
220
5f05dabc 221The auto-decrement operator is not magical.
a0d0e21e
LW
222
223=head2 Exponentiation
d74e8afc 224X<**> X<exponentiation> X<power>
a0d0e21e 225
ba7f043c
KW
226Binary C<"**"> is the exponentiation operator. It binds even more
227tightly than unary minus, so C<-2**4> is C<-(2**4)>, not C<(-2)**4>.
228(This is
229implemented using C's C<pow(3)> function, which actually works on doubles
cb1a09d0 230internally.)
a0d0e21e 231
44a465b3
JH
232Note that certain exponentiation expressions are ill-defined:
233these include C<0**0>, C<1**Inf>, and C<Inf**0>. Do not expect
234any particular results from these special cases, the results
235are platform-dependent.
236
a0d0e21e 237=head2 Symbolic Unary Operators
d74e8afc 238X<unary operator> X<operator, unary>
a0d0e21e 239
4b05bc8e
KW
240Unary C<"!"> performs logical negation, that is, "not". See also
241L<C<not>|/Logical Not> for a lower precedence version of this.
d74e8afc 242X<!>
a0d0e21e 243
ba7f043c 244Unary C<"-"> performs arithmetic negation if the operand is numeric,
da2f94c5
FC
245including any string that looks like a number. If the operand is
246an identifier, a string consisting of a minus sign concatenated
247with the identifier is returned. Otherwise, if the string starts
248with a plus or minus, a string starting with the opposite sign is
ba7f043c
KW
249returned. One effect of these rules is that C<-bareword> is equivalent
250to the string C<"-bareword">. If, however, the string begins with a
251non-alphabetic character (excluding C<"+"> or C<"-">), Perl will attempt
252to convert
253the string to a numeric, and the arithmetic negation is performed. If the
06705523
SP
254string cannot be cleanly converted to a numeric, Perl will give the warning
255B<Argument "the string" isn't numeric in negation (-) at ...>.
d74e8afc 256X<-> X<negation, arithmetic>
a0d0e21e 257
ba7f043c 258Unary C<"~"> performs bitwise negation, that is, 1's complement. For
5a0de581
LM
259example, S<C<0666 & ~027>> is 0640. (See also L</Integer Arithmetic> and
260L</Bitwise String Operators>.) Note that the width of the result is
ba7f043c 261platform-dependent: C<~0> is 32 bits wide on a 32-bit platform, but 64
972b05a9 262bits wide on a 64-bit platform, so if you are expecting a certain bit
ba7f043c 263width, remember to use the C<"&"> operator to mask off the excess bits.
d74e8afc 264X<~> X<negation, binary>
a0d0e21e 265
fac71630
KW
266Starting in Perl 5.28, it is a fatal error to try to complement a string
267containing a character with an ordinal value above 255.
f113cf86 268
193789ac
FC
269If the "bitwise" feature is enabled via S<C<use
270feature 'bitwise'>> or C<use v5.28>, then unary
271C<"~"> always treats its argument as a number, and an
ba7f043c 272alternate form of the operator, C<"~.">, always treats its argument as a
fb7054ba 273string. So C<~0> and C<~"0"> will both give 2**32-1 on 32-bit platforms,
193789ac
FC
274whereas C<~.0> and C<~."0"> will both yield C<"\xff">. Until Perl 5.28,
275this feature produced a warning in the C<"experimental::bitwise"> category.
fb7054ba 276
ba7f043c 277Unary C<"+"> has no effect whatsoever, even on strings. It is useful
a0d0e21e
LW
278syntactically for separating a function name from a parenthesized expression
279that would otherwise be interpreted as the complete list of function
a95b3d6a 280arguments. (See examples above under L</Terms and List Operators (Leftward)>.)
d74e8afc 281X<+>
a0d0e21e 282
39dc9d14
Z
283Unary C<"\"> creates references. If its operand is a single sigilled
284thing, it creates a reference to that object. If its operand is a
285parenthesised list, then it creates references to the things mentioned
286in the list. Otherwise it puts its operand in list context, and creates
287a list of references to the scalars in the list provided by the operand.
288See L<perlreftut>
19799a22
GS
289and L<perlref>. Do not confuse this behavior with the behavior of
290backslash within a string, although both forms do convey the notion
291of protecting the next thing from interpolation.
d74e8afc 292X<\> X<reference> X<backslash>
a0d0e21e
LW
293
294=head2 Binding Operators
d74e8afc 295X<binding> X<operator, binding> X<=~> X<!~>
a0d0e21e 296
ba7f043c
KW
297Binary C<"=~"> binds a scalar expression to a pattern match. Certain operations
298search or modify the string C<$_> by default. This operator makes that kind
cb1a09d0 299of operation work on some other string. The right argument is a search
2c268ad5
TP
300pattern, substitution, or transliteration. The left argument is what is
301supposed to be searched, substituted, or transliterated instead of the default
ba7f043c
KW
302C<$_>. When used in scalar context, the return value generally indicates the
303success of the operation. The exceptions are substitution (C<s///>)
304and transliteration (C<y///>) with the C</r> (non-destructive) option,
8ff32507
FC
305which cause the B<r>eturn value to be the result of the substitution.
306Behavior in list context depends on the particular operator.
000c65fc
DG
307See L</"Regexp Quote-Like Operators"> for details and L<perlretut> for
308examples using these operators.
f8bab1e9
GS
309
310If the right argument is an expression rather than a search pattern,
2c268ad5 311substitution, or transliteration, it is interpreted as a search pattern at run
46f8a5ea
FC
312time. Note that this means that its
313contents will be interpolated twice, so
89d205f2 314
1ca345ed 315 '\\' =~ q'\\';
89d205f2
YO
316
317is not ok, as the regex engine will end up trying to compile the
318pattern C<\>, which it will consider a syntax error.
a0d0e21e 319
ba7f043c 320Binary C<"!~"> is just like C<"=~"> except the return value is negated in
a0d0e21e
LW
321the logical sense.
322
ba7f043c
KW
323Binary C<"!~"> with a non-destructive substitution (C<s///r>) or transliteration
324(C<y///r>) is a syntax error.
4f4d7508 325
a0d0e21e 326=head2 Multiplicative Operators
d74e8afc 327X<operator, multiplicative>
a0d0e21e 328
ba7f043c 329Binary C<"*"> multiplies two numbers.
d74e8afc 330X<*>
a0d0e21e 331
ba7f043c 332Binary C<"/"> divides two numbers.
d74e8afc 333X</> X<slash>
a0d0e21e 334
ba7f043c 335Binary C<"%"> is the modulo operator, which computes the division
f7918450
KW
336remainder of its first argument with respect to its second argument.
337Given integer
ba7f043c 338operands C<$m> and C<$n>: If C<$n> is positive, then S<C<$m % $n>> is
db691027 339C<$m> minus the largest multiple of C<$n> less than or equal to
ba7f043c 340C<$m>. If C<$n> is negative, then S<C<$m % $n>> is C<$m> minus the
db691027 341smallest multiple of C<$n> that is not less than C<$m> (that is, the
89b4f0ad 342result will be less than or equal to zero). If the operands
db691027 343C<$m> and C<$n> are floating point values and the absolute value of
ba7f043c 344C<$n> (that is C<abs($n)>) is less than S<C<(UV_MAX + 1)>>, only
db691027 345the integer portion of C<$m> and C<$n> will be used in the operation
4848a83b 346(Note: here C<UV_MAX> means the maximum of the unsigned integer type).
db691027 347If the absolute value of the right operand (C<abs($n)>) is greater than
ba7f043c
KW
348or equal to S<C<(UV_MAX + 1)>>, C<"%"> computes the floating-point remainder
349C<$r> in the equation S<C<($r = $m - $i*$n)>> where C<$i> is a certain
f7918450 350integer that makes C<$r> have the same sign as the right operand
db691027
SF
351C<$n> (B<not> as the left operand C<$m> like C function C<fmod()>)
352and the absolute value less than that of C<$n>.
ba7f043c 353Note that when S<C<use integer>> is in scope, C<"%"> gives you direct access
f7918450 354to the modulo operator as implemented by your C compiler. This
55d729e4
GS
355operator is not as well defined for negative operands, but it will
356execute faster.
f7918450 357X<%> X<remainder> X<modulo> X<mod>
55d729e4 358
e509fc38
Z
359Binary C<x> is the repetition operator. In scalar context, or if the
360left operand is neither enclosed in parentheses nor a C<qw//> list,
361it performs a string repetition. In that case it supplies scalar
362context to the left operand, and returns a string consisting of the
363left operand string repeated the number of times specified by the right
364operand. If the C<x> is in list context, and the left operand is either
365enclosed in parentheses or a C<qw//> list, it performs a list repetition.
366In that case it supplies list context to the left operand, and returns
367a list consisting of the left operand list repeated the number of times
368specified by the right operand.
31201a8e
KW
369If the right operand is zero or negative (raising a warning on
370negative), it returns an empty string
3585017f 371or an empty list, depending on the context.
d74e8afc 372X<x>
a0d0e21e
LW
373
374 print '-' x 80; # print row of dashes
375
376 print "\t" x ($tab/8), ' ' x ($tab%8); # tab over
377
378 @ones = (1) x 80; # a list of 80 1's
379 @ones = (5) x @ones; # set all elements to 5
380
381
382=head2 Additive Operators
d74e8afc 383X<operator, additive>
a0d0e21e 384
ba7f043c 385Binary C<"+"> returns the sum of two numbers.
d74e8afc 386X<+>
a0d0e21e 387
ba7f043c 388Binary C<"-"> returns the difference of two numbers.
d74e8afc 389X<->
a0d0e21e 390
ba7f043c 391Binary C<"."> concatenates two strings.
d74e8afc
ITB
392X<string, concatenation> X<concatenation>
393X<cat> X<concat> X<concatenate> X<.>
a0d0e21e
LW
394
395=head2 Shift Operators
d74e8afc
ITB
396X<shift operator> X<operator, shift> X<<< << >>>
397X<<< >> >>> X<right shift> X<left shift> X<bitwise shift>
398X<shl> X<shr> X<shift, right> X<shift, left>
a0d0e21e 399
ba7f043c 400Binary C<<< "<<" >>> returns the value of its left argument shifted left by the
55497cff 401number of bits specified by the right argument. Arguments should be
5a0de581 402integers. (See also L</Integer Arithmetic>.)
a0d0e21e 403
ba7f043c 404Binary C<<< ">>" >>> returns the value of its left argument shifted right by
55497cff 405the number of bits specified by the right argument. Arguments should
5a0de581 406be integers. (See also L</Integer Arithmetic>.)
a0d0e21e 407
5a0de581 408If S<C<use integer>> (see L</Integer Arithmetic>) is in force then
a63df121
JH
409signed C integers are used (I<arithmetic shift>), otherwise unsigned C
410integers are used (I<logical shift>), even for negative shiftees.
411In arithmetic right shift the sign bit is replicated on the left,
412in logical shift zero bits come in from the left.
413
414Either way, the implementation isn't going to generate results larger
415than the size of the integer type Perl was built with (32 bits or 64 bits).
416
417Shifting by negative number of bits means the reverse shift: left
418shift becomes right shift, right shift becomes left shift. This is
419unlike in C, where negative shift is undefined.
420
421Shifting by more bits than the size of the integers means most of the
422time zero (all bits fall off), except that under S<C<use integer>>
423right overshifting a negative shiftee results in -1. This is unlike
424in C, where shifting by too many bits is undefined. A common C
425behavior is "shift by modulo wordbits", so that for example
426
427 1 >> 64 == 1 >> (64 % 64) == 1 >> 0 == 1 # Common C behavior.
428
429but that is completely accidental.
b16cf6df 430
1ca345ed 431If you get tired of being subject to your platform's native integers,
ba7f043c 432the S<C<use bigint>> pragma neatly sidesteps the issue altogether:
1ca345ed
TC
433
434 print 20 << 20; # 20971520
a727cfac 435 print 20 << 40; # 5120 on 32-bit machines,
1ca345ed
TC
436 # 21990232555520 on 64-bit machines
437 use bigint;
438 print 20 << 100; # 25353012004564588029934064107520
439
a0d0e21e 440=head2 Named Unary Operators
d74e8afc 441X<operator, named unary>
a0d0e21e
LW
442
443The various named unary operators are treated as functions with one
568e6d8b 444argument, with optional parentheses.
a0d0e21e 445
ba7f043c 446If any list operator (C<print()>, etc.) or any unary operator (C<chdir()>, etc.)
a0d0e21e
LW
447is followed by a left parenthesis as the next token, the operator and
448arguments within parentheses are taken to be of highest precedence,
3981b0eb 449just like a normal function call. For example,
1ca345ed 450because named unary operators are higher precedence than C<||>:
a0d0e21e
LW
451
452 chdir $foo || die; # (chdir $foo) || die
453 chdir($foo) || die; # (chdir $foo) || die
454 chdir ($foo) || die; # (chdir $foo) || die
455 chdir +($foo) || die; # (chdir $foo) || die
456
ba7f043c 457but, because C<"*"> is higher precedence than named operators:
a0d0e21e
LW
458
459 chdir $foo * 20; # chdir ($foo * 20)
460 chdir($foo) * 20; # (chdir $foo) * 20
461 chdir ($foo) * 20; # (chdir $foo) * 20
462 chdir +($foo) * 20; # chdir ($foo * 20)
463
464 rand 10 * 20; # rand (10 * 20)
465 rand(10) * 20; # (rand 10) * 20
466 rand (10) * 20; # (rand 10) * 20
467 rand +(10) * 20; # rand (10 * 20)
468
568e6d8b
RGS
469Regarding precedence, the filetest operators, like C<-f>, C<-M>, etc. are
470treated like named unary operators, but they don't follow this functional
471parenthesis rule. That means, for example, that C<-f($file).".bak"> is
ba7f043c 472equivalent to S<C<-f "$file.bak">>.
d74e8afc 473X<-X> X<filetest> X<operator, filetest>
568e6d8b 474
5a0de581 475See also L</"Terms and List Operators (Leftward)">.
a0d0e21e
LW
476
477=head2 Relational Operators
d74e8afc 478X<relational operator> X<operator, relational>
a0d0e21e 479
a727cfac 480Perl operators that return true or false generally return values
1ca345ed
TC
481that can be safely used as numbers. For example, the relational
482operators in this section and the equality operators in the next
483one return C<1> for true and a special version of the defined empty
484string, C<"">, which counts as a zero but is exempt from warnings
ba7f043c 485about improper numeric conversions, just as S<C<"0 but true">> is.
1ca345ed 486
ba7f043c 487Binary C<< "<" >> returns true if the left argument is numerically less than
a0d0e21e 488the right argument.
d74e8afc 489X<< < >>
a0d0e21e 490
ba7f043c 491Binary C<< ">" >> returns true if the left argument is numerically greater
a0d0e21e 492than the right argument.
d74e8afc 493X<< > >>
a0d0e21e 494
ba7f043c 495Binary C<< "<=" >> returns true if the left argument is numerically less than
a0d0e21e 496or equal to the right argument.
d74e8afc 497X<< <= >>
a0d0e21e 498
ba7f043c 499Binary C<< ">=" >> returns true if the left argument is numerically greater
a0d0e21e 500than or equal to the right argument.
d74e8afc 501X<< >= >>
a0d0e21e 502
ba7f043c 503Binary C<"lt"> returns true if the left argument is stringwise less than
a0d0e21e 504the right argument.
d74e8afc 505X<< lt >>
a0d0e21e 506
ba7f043c 507Binary C<"gt"> returns true if the left argument is stringwise greater
a0d0e21e 508than the right argument.
d74e8afc 509X<< gt >>
a0d0e21e 510
ba7f043c 511Binary C<"le"> returns true if the left argument is stringwise less than
a0d0e21e 512or equal to the right argument.
d74e8afc 513X<< le >>
a0d0e21e 514
ba7f043c 515Binary C<"ge"> returns true if the left argument is stringwise greater
a0d0e21e 516than or equal to the right argument.
d74e8afc 517X<< ge >>
a0d0e21e
LW
518
519=head2 Equality Operators
d74e8afc 520X<equality> X<equal> X<equals> X<operator, equality>
a0d0e21e 521
ba7f043c 522Binary C<< "==" >> returns true if the left argument is numerically equal to
a0d0e21e 523the right argument.
d74e8afc 524X<==>
a0d0e21e 525
ba7f043c 526Binary C<< "!=" >> returns true if the left argument is numerically not equal
a0d0e21e 527to the right argument.
d74e8afc 528X<!=>
a0d0e21e 529
ba7f043c 530Binary C<< "<=>" >> returns -1, 0, or 1 depending on whether the left
6ee5d4e7 531argument is numerically less than, equal to, or greater than the right
ba7f043c
KW
532argument. If your platform supports C<NaN>'s (not-a-numbers) as numeric
533values, using them with C<< "<=>" >> returns undef. C<NaN> is not
534C<< "<" >>, C<< "==" >>, C<< ">" >>, C<< "<=" >> or C<< ">=" >> anything
535(even C<NaN>), so those 5 return false. S<C<< NaN != NaN >>> returns
536true, as does S<C<NaN !=> I<anything else>>. If your platform doesn't
537support C<NaN>'s then C<NaN> is just a string with numeric value 0.
538X<< <=> >>
539X<spaceship>
7d3a9d88 540
db691027
SF
541 $ perl -le '$x = "NaN"; print "No NaN support here" if $x == $x'
542 $ perl -le '$x = "NaN"; print "NaN support here" if $x != $x'
1ca345ed 543
db691027 544(Note that the L<bigint>, L<bigrat>, and L<bignum> pragmas all
ba7f043c 545support C<"NaN">.)
a0d0e21e 546
ba7f043c 547Binary C<"eq"> returns true if the left argument is stringwise equal to
a0d0e21e 548the right argument.
d74e8afc 549X<eq>
a0d0e21e 550
ba7f043c 551Binary C<"ne"> returns true if the left argument is stringwise not equal
a0d0e21e 552to the right argument.
d74e8afc 553X<ne>
a0d0e21e 554
ba7f043c 555Binary C<"cmp"> returns -1, 0, or 1 depending on whether the left
d4ad863d
JH
556argument is stringwise less than, equal to, or greater than the right
557argument.
d74e8afc 558X<cmp>
a0d0e21e 559
ba7f043c 560Binary C<"~~"> does a smartmatch between its arguments. Smart matching
1ca345ed 561is described in the next section.
0d863452
RH
562X<~~>
563
ba7f043c
KW
564C<"lt">, C<"le">, C<"ge">, C<"gt"> and C<"cmp"> use the collation (sort)
565order specified by the current C<LC_COLLATE> locale if a S<C<use
566locale>> form that includes collation is in effect. See L<perllocale>.
567Do not mix these with Unicode,
568only use them with legacy 8-bit locale encodings.
569The standard C<L<Unicode::Collate>> and
570C<L<Unicode::Collate::Locale>> modules offer much more powerful
571solutions to collation issues.
1ca345ed 572
82365311
DG
573For case-insensitive comparisions, look at the L<perlfunc/fc> case-folding
574function, available in Perl v5.16 or later:
575
576 if ( fc($x) eq fc($y) ) { ... }
577
1ca345ed
TC
578=head2 Smartmatch Operator
579
7896dde7
Z
580First available in Perl 5.10.1 (the 5.10.0 version behaved differently),
581binary C<~~> does a "smartmatch" between its arguments. This is mostly
582used implicitly in the C<when> construct described in L<perlsyn>, although
583not all C<when> clauses call the smartmatch operator. Unique among all of
584Perl's operators, the smartmatch operator can recurse. The smartmatch
cc08d69f 585operator is L<experimental|perlpolicy/experimental> and its behavior is
7896dde7
Z
586subject to change.
587
588It is also unique in that all other Perl operators impose a context
589(usually string or numeric context) on their operands, autoconverting
590those operands to those imposed contexts. In contrast, smartmatch
591I<infers> contexts from the actual types of its operands and uses that
592type information to select a suitable comparison mechanism.
593
594The C<~~> operator compares its operands "polymorphically", determining how
595to compare them according to their actual types (numeric, string, array,
596hash, etc.) Like the equality operators with which it shares the same
597precedence, C<~~> returns 1 for true and C<""> for false. It is often best
598read aloud as "in", "inside of", or "is contained in", because the left
599operand is often looked for I<inside> the right operand. That makes the
600order of the operands to the smartmatch operand often opposite that of
601the regular match operator. In other words, the "smaller" thing is usually
602placed in the left operand and the larger one in the right.
603
604The behavior of a smartmatch depends on what type of things its arguments
605are, as determined by the following table. The first row of the table
606whose types apply determines the smartmatch behavior. Because what
607actually happens is mostly determined by the type of the second operand,
608the table is sorted on the right operand instead of on the left.
609
610 Left Right Description and pseudocode
611 ===============================================================
612 Any undef check whether Any is undefined
613 like: !defined Any
614
615 Any Object invoke ~~ overloading on Object, or die
616
617 Right operand is an ARRAY:
618
619 Left Right Description and pseudocode
620 ===============================================================
621 ARRAY1 ARRAY2 recurse on paired elements of ARRAY1 and ARRAY2[2]
622 like: (ARRAY1[0] ~~ ARRAY2[0])
623 && (ARRAY1[1] ~~ ARRAY2[1]) && ...
624 HASH ARRAY any ARRAY elements exist as HASH keys
625 like: grep { exists HASH->{$_} } ARRAY
626 Regexp ARRAY any ARRAY elements pattern match Regexp
627 like: grep { /Regexp/ } ARRAY
628 undef ARRAY undef in ARRAY
629 like: grep { !defined } ARRAY
630 Any ARRAY smartmatch each ARRAY element[3]
631 like: grep { Any ~~ $_ } ARRAY
632
633 Right operand is a HASH:
634
635 Left Right Description and pseudocode
636 ===============================================================
637 HASH1 HASH2 all same keys in both HASHes
638 like: keys HASH1 ==
639 grep { exists HASH2->{$_} } keys HASH1
640 ARRAY HASH any ARRAY elements exist as HASH keys
641 like: grep { exists HASH->{$_} } ARRAY
642 Regexp HASH any HASH keys pattern match Regexp
643 like: grep { /Regexp/ } keys HASH
644 undef HASH always false (undef can't be a key)
645 like: 0 == 1
646 Any HASH HASH key existence
647 like: exists HASH->{Any}
648
649 Right operand is CODE:
650
651 Left Right Description and pseudocode
652 ===============================================================
653 ARRAY CODE sub returns true on all ARRAY elements[1]
654 like: !grep { !CODE->($_) } ARRAY
655 HASH CODE sub returns true on all HASH keys[1]
656 like: !grep { !CODE->($_) } keys HASH
657 Any CODE sub passed Any returns true
658 like: CODE->(Any)
659
660Right operand is a Regexp:
661
662 Left Right Description and pseudocode
663 ===============================================================
664 ARRAY Regexp any ARRAY elements match Regexp
665 like: grep { /Regexp/ } ARRAY
666 HASH Regexp any HASH keys match Regexp
667 like: grep { /Regexp/ } keys HASH
668 Any Regexp pattern match
669 like: Any =~ /Regexp/
670
671 Other:
672
673 Left Right Description and pseudocode
674 ===============================================================
675 Object Any invoke ~~ overloading on Object,
676 or fall back to...
677
678 Any Num numeric equality
679 like: Any == Num
680 Num nummy[4] numeric equality
681 like: Num == nummy
682 undef Any check whether undefined
683 like: !defined(Any)
684 Any Any string equality
685 like: Any eq Any
686
687
688Notes:
689
690=over
691
692=item 1.
693Empty hashes or arrays match.
694
695=item 2.
696That is, each element smartmatches the element of the same index in the other array.[3]
697
698=item 3.
699If a circular reference is found, fall back to referential equality.
700
701=item 4.
702Either an actual number, or a string that looks like one.
703
704=back
705
706The smartmatch implicitly dereferences any non-blessed hash or array
707reference, so the C<I<HASH>> and C<I<ARRAY>> entries apply in those cases.
708For blessed references, the C<I<Object>> entries apply. Smartmatches
709involving hashes only consider hash keys, never hash values.
710
711The "like" code entry is not always an exact rendition. For example, the
712smartmatch operator short-circuits whenever possible, but C<grep> does
713not. Also, C<grep> in scalar context returns the number of matches, but
714C<~~> returns only true or false.
715
716Unlike most operators, the smartmatch operator knows to treat C<undef>
717specially:
718
719 use v5.10.1;
720 @array = (1, 2, 3, undef, 4, 5);
721 say "some elements undefined" if undef ~~ @array;
722
723Each operand is considered in a modified scalar context, the modification
724being that array and hash variables are passed by reference to the
725operator, which implicitly dereferences them. Both elements
726of each pair are the same:
727
728 use v5.10.1;
729
730 my %hash = (red => 1, blue => 2, green => 3,
731 orange => 4, yellow => 5, purple => 6,
732 black => 7, grey => 8, white => 9);
733
734 my @array = qw(red blue green);
735
736 say "some array elements in hash keys" if @array ~~ %hash;
737 say "some array elements in hash keys" if \@array ~~ \%hash;
738
739 say "red in array" if "red" ~~ @array;
740 say "red in array" if "red" ~~ \@array;
741
742 say "some keys end in e" if /e$/ ~~ %hash;
743 say "some keys end in e" if /e$/ ~~ \%hash;
744
745Two arrays smartmatch if each element in the first array smartmatches
746(that is, is "in") the corresponding element in the second array,
747recursively.
748
749 use v5.10.1;
750 my @little = qw(red blue green);
751 my @bigger = ("red", "blue", [ "orange", "green" ] );
752 if (@little ~~ @bigger) { # true!
753 say "little is contained in bigger";
754 }
755
756Because the smartmatch operator recurses on nested arrays, this
757will still report that "red" is in the array.
758
759 use v5.10.1;
760 my @array = qw(red blue green);
761 my $nested_array = [[[[[[[ @array ]]]]]]];
762 say "red in array" if "red" ~~ $nested_array;
763
764If two arrays smartmatch each other, then they are deep
765copies of each others' values, as this example reports:
766
767 use v5.12.0;
768 my @a = (0, 1, 2, [3, [4, 5], 6], 7);
769 my @b = (0, 1, 2, [3, [4, 5], 6], 7);
770
771 if (@a ~~ @b && @b ~~ @a) {
772 say "a and b are deep copies of each other";
773 }
774 elsif (@a ~~ @b) {
775 say "a smartmatches in b";
776 }
777 elsif (@b ~~ @a) {
778 say "b smartmatches in a";
779 }
780 else {
781 say "a and b don't smartmatch each other at all";
782 }
783
784
785If you were to set S<C<$b[3] = 4>>, then instead of reporting that "a and b
786are deep copies of each other", it now reports that C<"b smartmatches in a">.
787That's because the corresponding position in C<@a> contains an array that
788(eventually) has a 4 in it.
789
790Smartmatching one hash against another reports whether both contain the
791same keys, no more and no less. This could be used to see whether two
792records have the same field names, without caring what values those fields
793might have. For example:
794
795 use v5.10.1;
796 sub make_dogtag {
797 state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
798
799 my ($class, $init_fields) = @_;
800
801 die "Must supply (only) name, rank, and serial number"
802 unless $init_fields ~~ $REQUIRED_FIELDS;
803
804 ...
805 }
806
807However, this only does what you mean if C<$init_fields> is indeed a hash
808reference. The condition C<$init_fields ~~ $REQUIRED_FIELDS> also allows the
809strings C<"name">, C<"rank">, C<"serial_num"> as well as any array reference
810that contains C<"name"> or C<"rank"> or C<"serial_num"> anywhere to pass
811through.
812
813The smartmatch operator is most often used as the implicit operator of a
814C<when> clause. See the section on "Switch Statements" in L<perlsyn>.
815
816=head3 Smartmatching of Objects
817
818To avoid relying on an object's underlying representation, if the
819smartmatch's right operand is an object that doesn't overload C<~~>,
820it raises the exception "C<Smartmatching a non-overloaded object
821breaks encapsulation>". That's because one has no business digging
822around to see whether something is "in" an object. These are all
823illegal on objects without a C<~~> overload:
824
825 %hash ~~ $object
826 42 ~~ $object
827 "fred" ~~ $object
828
829However, you can change the way an object is smartmatched by overloading
830the C<~~> operator. This is allowed to
831extend the usual smartmatch semantics.
832For objects that do have an C<~~> overload, see L<overload>.
833
834Using an object as the left operand is allowed, although not very useful.
835Smartmatching rules take precedence over overloading, so even if the
836object in the left operand has smartmatch overloading, this will be
837ignored. A left operand that is a non-overloaded object falls back on a
838string or numeric comparison of whatever the C<ref> operator returns. That
839means that
840
841 $object ~~ X
842
843does I<not> invoke the overload method with C<I<X>> as an argument.
844Instead the above table is consulted as normal, and based on the type of
845C<I<X>>, overloading may or may not be invoked. For simple strings or
846numbers, "in" becomes equivalent to this:
847
848 $object ~~ $number ref($object) == $number
849 $object ~~ $string ref($object) eq $string
850
851For example, this reports that the handle smells IOish
852(but please don't really do this!):
853
854 use IO::Handle;
855 my $fh = IO::Handle->new();
856 if ($fh ~~ /\bIO\b/) {
857 say "handle smells IOish";
858 }
859
860That's because it treats C<$fh> as a string like
861C<"IO::Handle=GLOB(0x8039e0)">, then pattern matches against that.
a034a98d 862
a0d0e21e 863=head2 Bitwise And
d74e8afc 864X<operator, bitwise, and> X<bitwise and> X<&>
a0d0e21e 865
ba7f043c 866Binary C<"&"> returns its operands ANDed together bit by bit. Although no
c791a246
KW
867warning is currently raised, the result is not well defined when this operation
868is performed on operands that aren't either numbers (see
5a0de581 869L</Integer Arithmetic>) nor bitstrings (see L</Bitwise String Operators>).
a0d0e21e 870
ba7f043c 871Note that C<"&"> has lower priority than relational operators, so for example
1ca345ed 872the parentheses are essential in a test like
2cdc098b 873
1ca345ed 874 print "Even\n" if ($x & 1) == 0;
2cdc098b 875
193789ac
FC
876If the "bitwise" feature is enabled via S<C<use feature 'bitwise'>> or
877C<use v5.28>, then this operator always treats its operands as numbers.
878Before Perl 5.28 this feature produced a warning in the
879C<"experimental::bitwise"> category.
fb7054ba 880
a0d0e21e 881=head2 Bitwise Or and Exclusive Or
d74e8afc
ITB
882X<operator, bitwise, or> X<bitwise or> X<|> X<operator, bitwise, xor>
883X<bitwise xor> X<^>
a0d0e21e 884
ba7f043c 885Binary C<"|"> returns its operands ORed together bit by bit.
a0d0e21e 886
ba7f043c 887Binary C<"^"> returns its operands XORed together bit by bit.
c791a246
KW
888
889Although no warning is currently raised, the results are not well
890defined when these operations are performed on operands that aren't either
5a0de581 891numbers (see L</Integer Arithmetic>) nor bitstrings (see L</Bitwise String
c791a246 892Operators>).
a0d0e21e 893
ba7f043c
KW
894Note that C<"|"> and C<"^"> have lower priority than relational operators, so
895for example the parentheses are essential in a test like
2cdc098b 896
1ca345ed 897 print "false\n" if (8 | 2) != 10;
2cdc098b 898
193789ac
FC
899If the "bitwise" feature is enabled via S<C<use feature 'bitwise'>> or
900C<use v5.28>, then this operator always treats its operands as numbers.
901Before Perl 5.28. this feature produced a warning in the
902C<"experimental::bitwise"> category.
fb7054ba 903
a0d0e21e 904=head2 C-style Logical And
d74e8afc 905X<&&> X<logical and> X<operator, logical, and>
a0d0e21e 906
ba7f043c 907Binary C<"&&"> performs a short-circuit logical AND operation. That is,
a0d0e21e
LW
908if the left operand is false, the right operand is not even evaluated.
909Scalar or list context propagates down to the right operand if it
910is evaluated.
911
912=head2 C-style Logical Or
d74e8afc 913X<||> X<operator, logical, or>
a0d0e21e 914
ba7f043c 915Binary C<"||"> performs a short-circuit logical OR operation. That is,
a0d0e21e
LW
916if the left operand is true, the right operand is not even evaluated.
917Scalar or list context propagates down to the right operand if it
918is evaluated.
919
26d9d83b 920=head2 Logical Defined-Or
d74e8afc 921X<//> X<operator, logical, defined-or>
c963b151
BD
922
923Although it has no direct equivalent in C, Perl's C<//> operator is related
ba7f043c 924to its C-style "or". In fact, it's exactly the same as C<||>, except that it
95bee9ba 925tests the left hand side's definedness instead of its truth. Thus,
ba7f043c 926S<C<< EXPR1 // EXPR2 >>> returns the value of C<< EXPR1 >> if it's defined,
46f8a5ea
FC
927otherwise, the value of C<< EXPR2 >> is returned.
928(C<< EXPR1 >> is evaluated in scalar context, C<< EXPR2 >>
929in the context of C<< // >> itself). Usually,
ba7f043c
KW
930this is the same result as S<C<< defined(EXPR1) ? EXPR1 : EXPR2 >>> (except that
931the ternary-operator form can be used as a lvalue, while S<C<< EXPR1 // EXPR2 >>>
46f8a5ea 932cannot). This is very useful for
bdc7923b 933providing default values for variables. If you actually want to test if
ba7f043c 934at least one of C<$x> and C<$y> is defined, use S<C<defined($x // $y)>>.
c963b151 935
d042e63d 936The C<||>, C<//> and C<&&> operators return the last value evaluated
46f8a5ea 937(unlike C's C<||> and C<&&>, which return 0 or 1). Thus, a reasonably
d042e63d 938portable way to find out the home directory might be:
a0d0e21e 939
c543c01b
TC
940 $home = $ENV{HOME}
941 // $ENV{LOGDIR}
942 // (getpwuid($<))[7]
943 // die "You're homeless!\n";
a0d0e21e 944
5a964f20
TC
945In particular, this means that you shouldn't use this
946for selecting between two aggregates for assignment:
947
bf55d65d
LTC
948 @a = @b || @c; # This doesn't do the right thing
949 @a = scalar(@b) || @c; # because it really means this.
950 @a = @b ? @b : @c; # This works fine, though.
5a964f20 951
1ca345ed 952As alternatives to C<&&> and C<||> when used for
f23102e2 953control flow, Perl provides the C<and> and C<or> operators (see below).
ba7f043c
KW
954The short-circuit behavior is identical. The precedence of C<"and">
955and C<"or"> is much lower, however, so that you can safely use them after a
5a964f20 956list operator without the need for parentheses:
a0d0e21e
LW
957
958 unlink "alpha", "beta", "gamma"
959 or gripe(), next LINE;
960
961With the C-style operators that would have been written like this:
962
963 unlink("alpha", "beta", "gamma")
964 || (gripe(), next LINE);
965
1ca345ed
TC
966It would be even more readable to write that this way:
967
968 unless(unlink("alpha", "beta", "gamma")) {
969 gripe();
970 next LINE;
a727cfac 971 }
1ca345ed 972
ba7f043c 973Using C<"or"> for assignment is unlikely to do what you want; see below.
5a964f20
TC
974
975=head2 Range Operators
d74e8afc 976X<operator, range> X<range> X<..> X<...>
a0d0e21e 977
ba7f043c 978Binary C<".."> is the range operator, which is really two different
fb53bbb2 979operators depending on the context. In list context, it returns a
54ae734e 980list of values counting (up by ones) from the left value to the right
2cdbc966 981value. If the left value is greater than the right value then it
fb53bbb2 982returns the empty list. The range operator is useful for writing
ba7f043c 983S<C<foreach (1..10)>> loops and for doing slice operations on arrays. In
2cdbc966
JD
984the current implementation, no temporary array is created when the
985range operator is used as the expression in C<foreach> loops, but older
986versions of Perl might burn a lot of memory when you write something
987like this:
a0d0e21e
LW
988
989 for (1 .. 1_000_000) {
990 # code
54310121 991 }
a0d0e21e 992
8f0f46f8 993The range operator also works on strings, using the magical
994auto-increment, see below.
54ae734e 995
ba7f043c 996In scalar context, C<".."> returns a boolean value. The operator is
8f0f46f8 997bistable, like a flip-flop, and emulates the line-range (comma)
ba7f043c 998operator of B<sed>, B<awk>, and various editors. Each C<".."> operator
8f0f46f8 999maintains its own boolean state, even across calls to a subroutine
46f8a5ea 1000that contains it. It is false as long as its left operand is false.
a0d0e21e
LW
1001Once the left operand is true, the range operator stays true until the
1002right operand is true, I<AFTER> which the range operator becomes false
8f0f46f8 1003again. It doesn't become false till the next time the range operator
1004is evaluated. It can test the right operand and become false on the
1005same evaluation it became true (as in B<awk>), but it still returns
46f8a5ea 1006true once. If you don't want it to test the right operand until the
ba7f043c
KW
1007next evaluation, as in B<sed>, just use three dots (C<"...">) instead of
1008two. In all other regards, C<"..."> behaves just like C<".."> does.
19799a22
GS
1009
1010The right operand is not evaluated while the operator is in the
1011"false" state, and the left operand is not evaluated while the
1012operator is in the "true" state. The precedence is a little lower
1013than || and &&. The value returned is either the empty string for
8f0f46f8 1014false, or a sequence number (beginning with 1) for true. The sequence
1015number is reset for each range encountered. The final sequence number
ba7f043c 1016in a range has the string C<"E0"> appended to it, which doesn't affect
8f0f46f8 1017its numeric value, but gives you something to search for if you want
1018to exclude the endpoint. You can exclude the beginning point by
1019waiting for the sequence number to be greater than 1.
df5f8116 1020
ba7f043c 1021If either operand of scalar C<".."> is a constant expression,
df5f8116
CW
1022that operand is considered true if it is equal (C<==>) to the current
1023input line number (the C<$.> variable).
1024
ba7f043c 1025To be pedantic, the comparison is actually S<C<int(EXPR) == int(EXPR)>>,
df5f8116
CW
1026but that is only an issue if you use a floating point expression; when
1027implicitly using C<$.> as described in the previous paragraph, the
ba7f043c 1028comparison is S<C<int(EXPR) == int($.)>> which is only an issue when C<$.>
df5f8116 1029is set to a floating point value and you are not reading from a file.
ba7f043c 1030Furthermore, S<C<"span" .. "spat">> or S<C<2.18 .. 3.14>> will not do what
df5f8116
CW
1031you want in scalar context because each of the operands are evaluated
1032using their integer representation.
1033
1034Examples:
a0d0e21e
LW
1035
1036As a scalar operator:
1037
df5f8116 1038 if (101 .. 200) { print; } # print 2nd hundred lines, short for
950b09ed 1039 # if ($. == 101 .. $. == 200) { print; }
9f10b797
RGS
1040
1041 next LINE if (1 .. /^$/); # skip header lines, short for
f343f960 1042 # next LINE if ($. == 1 .. /^$/);
9f10b797
RGS
1043 # (typically in a loop labeled LINE)
1044
1045 s/^/> / if (/^$/ .. eof()); # quote body
a0d0e21e 1046
5a964f20
TC
1047 # parse mail messages
1048 while (<>) {
1049 $in_header = 1 .. /^$/;
df5f8116
CW
1050 $in_body = /^$/ .. eof;
1051 if ($in_header) {
f343f960 1052 # do something
df5f8116 1053 } else { # in body
f343f960 1054 # do something else
df5f8116 1055 }
5a964f20 1056 } continue {
df5f8116 1057 close ARGV if eof; # reset $. each file
5a964f20
TC
1058 }
1059
acf31ca5
SF
1060Here's a simple example to illustrate the difference between
1061the two range operators:
1062
1063 @lines = (" - Foo",
1064 "01 - Bar",
1065 "1 - Baz",
1066 " - Quux");
1067
9f10b797
RGS
1068 foreach (@lines) {
1069 if (/0/ .. /1/) {
acf31ca5
SF
1070 print "$_\n";
1071 }
1072 }
1073
46f8a5ea 1074This program will print only the line containing "Bar". If
9f10b797 1075the range operator is changed to C<...>, it will also print the
acf31ca5
SF
1076"Baz" line.
1077
1078And now some examples as a list operator:
a0d0e21e 1079
1ca345ed
TC
1080 for (101 .. 200) { print } # print $_ 100 times
1081 @foo = @foo[0 .. $#foo]; # an expensive no-op
1082 @foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items
a0d0e21e 1083
5a964f20 1084The range operator (in list context) makes use of the magical
5f05dabc 1085auto-increment algorithm if the operands are strings. You
a0d0e21e
LW
1086can say
1087
c543c01b 1088 @alphabet = ("A" .. "Z");
a0d0e21e 1089
54ae734e 1090to get all normal letters of the English alphabet, or
a0d0e21e 1091
c543c01b 1092 $hexdigit = (0 .. 9, "a" .. "f")[$num & 15];
a0d0e21e
LW
1093
1094to get a hexadecimal digit, or
1095
1ca345ed
TC
1096 @z2 = ("01" .. "31");
1097 print $z2[$mday];
a0d0e21e 1098
ea4f5703
YST
1099to get dates with leading zeros.
1100
1101If the final value specified is not in the sequence that the magical
1102increment would produce, the sequence goes until the next value would
1103be longer than the final value specified.
1104
d6c970c7
AC
1105As of Perl 5.26, the list-context range operator on strings works as expected
1106in the scope of L<< S<C<"use feature 'unicode_strings">>|feature/The
1107'unicode_strings' feature >>. In previous versions, and outside the scope of
1108that feature, it exhibits L<perlunicode/The "Unicode Bug">: its behavior
1109depends on the internal encoding of the range endpoint.
1110
ea4f5703 1111If the initial value specified isn't part of a magical increment
c543c01b 1112sequence (that is, a non-empty string matching C</^[a-zA-Z]*[0-9]*\z/>),
ea4f5703
YST
1113only the initial value will be returned. So the following will only
1114return an alpha:
1115
c543c01b 1116 use charnames "greek";
ea4f5703
YST
1117 my @greek_small = ("\N{alpha}" .. "\N{omega}");
1118
c543c01b
TC
1119To get the 25 traditional lowercase Greek letters, including both sigmas,
1120you could use this instead:
ea4f5703 1121
c543c01b 1122 use charnames "greek";
a727cfac 1123 my @greek_small = map { chr } ( ord("\N{alpha}")
1ca345ed 1124 ..
a727cfac 1125 ord("\N{omega}")
1ca345ed 1126 );
c543c01b
TC
1127
1128However, because there are I<many> other lowercase Greek characters than
1129just those, to match lowercase Greek characters in a regular expression,
47c56cc8
KW
1130you could use the pattern C</(?:(?=\p{Greek})\p{Lower})+/> (or the
1131L<experimental feature|perlrecharclass/Extended Bracketed Character
1132Classes> C<S</(?[ \p{Greek} & \p{Lower} ])+/>>).
a0d0e21e 1133
ba7f043c 1134Because each operand is evaluated in integer form, S<C<2.18 .. 3.14>> will
df5f8116
CW
1135return two elements in list context.
1136
1137 @list = (2.18 .. 3.14); # same as @list = (2 .. 3);
1138
a0d0e21e 1139=head2 Conditional Operator
d74e8afc 1140X<operator, conditional> X<operator, ternary> X<ternary> X<?:>
a0d0e21e 1141
ba7f043c
KW
1142Ternary C<"?:"> is the conditional operator, just as in C. It works much
1143like an if-then-else. If the argument before the C<?> is true, the
1144argument before the C<:> is returned, otherwise the argument after the
1145C<:> is returned. For example:
cb1a09d0 1146
54310121 1147 printf "I have %d dog%s.\n", $n,
c543c01b 1148 ($n == 1) ? "" : "s";
cb1a09d0
AD
1149
1150Scalar or list context propagates downward into the 2nd
54310121 1151or 3rd argument, whichever is selected.
cb1a09d0 1152
db691027
SF
1153 $x = $ok ? $y : $z; # get a scalar
1154 @x = $ok ? @y : @z; # get an array
1155 $x = $ok ? @y : @z; # oops, that's just a count!
cb1a09d0
AD
1156
1157The operator may be assigned to if both the 2nd and 3rd arguments are
1158legal lvalues (meaning that you can assign to them):
a0d0e21e 1159
db691027 1160 ($x_or_y ? $x : $y) = $z;
a0d0e21e 1161
5a964f20
TC
1162Because this operator produces an assignable result, using assignments
1163without parentheses will get you in trouble. For example, this:
1164
db691027 1165 $x % 2 ? $x += 10 : $x += 2
5a964f20
TC
1166
1167Really means this:
1168
db691027 1169 (($x % 2) ? ($x += 10) : $x) += 2
5a964f20
TC
1170
1171Rather than this:
1172
db691027 1173 ($x % 2) ? ($x += 10) : ($x += 2)
5a964f20 1174
19799a22
GS
1175That should probably be written more simply as:
1176
db691027 1177 $x += ($x % 2) ? 10 : 2;
19799a22 1178
4633a7c4 1179=head2 Assignment Operators
d74e8afc 1180X<assignment> X<operator, assignment> X<=> X<**=> X<+=> X<*=> X<&=>
5ac3b81c 1181X<<< <<= >>> X<&&=> X<-=> X</=> X<|=> X<<< >>= >>> X<||=> X<//=> X<.=>
fb7054ba 1182X<%=> X<^=> X<x=> X<&.=> X<|.=> X<^.=>
a0d0e21e 1183
ba7f043c 1184C<"="> is the ordinary assignment operator.
a0d0e21e
LW
1185
1186Assignment operators work as in C. That is,
1187
db691027 1188 $x += 2;
a0d0e21e
LW
1189
1190is equivalent to
1191
db691027 1192 $x = $x + 2;
a0d0e21e
LW
1193
1194although without duplicating any side effects that dereferencing the lvalue
ba7f043c 1195might trigger, such as from C<tie()>. Other assignment operators work similarly.
54310121 1196The following are recognized:
a0d0e21e 1197
fb7054ba
FC
1198 **= += *= &= &.= <<= &&=
1199 -= /= |= |.= >>= ||=
1200 .= %= ^= ^.= //=
9f10b797 1201 x=
a0d0e21e 1202
19799a22 1203Although these are grouped by family, they all have the precedence
82848c10
FC
1204of assignment. These combined assignment operators can only operate on
1205scalars, whereas the ordinary assignment operator can assign to arrays,
1206hashes, lists and even references. (See L<"Context"|perldata/Context>
1207and L<perldata/List value constructors>, and L<perlref/Assigning to
1208References>.)
a0d0e21e 1209
b350dd2f
GS
1210Unlike in C, the scalar assignment operator produces a valid lvalue.
1211Modifying an assignment is equivalent to doing the assignment and
1212then modifying the variable that was assigned to. This is useful
1213for modifying a copy of something, like this:
a0d0e21e 1214
1ca345ed
TC
1215 ($tmp = $global) =~ tr/13579/24680/;
1216
1217Although as of 5.14, that can be also be accomplished this way:
1218
1219 use v5.14;
1220 $tmp = ($global =~ tr/13579/24680/r);
a0d0e21e
LW
1221
1222Likewise,
1223
db691027 1224 ($x += 2) *= 3;
a0d0e21e
LW
1225
1226is equivalent to
1227
db691027
SF
1228 $x += 2;
1229 $x *= 3;
a0d0e21e 1230
b350dd2f
GS
1231Similarly, a list assignment in list context produces the list of
1232lvalues assigned to, and a list assignment in scalar context returns
1233the number of elements produced by the expression on the right hand
1234side of the assignment.
1235
ba7f043c 1236The three dotted bitwise assignment operators (C<&.=> C<|.=> C<^.=>) are new in
193789ac 1237Perl 5.22. See L</Bitwise String Operators>.
fb7054ba 1238
748a9306 1239=head2 Comma Operator
d74e8afc 1240X<comma> X<operator, comma> X<,>
a0d0e21e 1241
ba7f043c 1242Binary C<","> is the comma operator. In scalar context it evaluates
a0d0e21e
LW
1243its left argument, throws that value away, then evaluates its right
1244argument and returns that value. This is just like C's comma operator.
1245
5a964f20 1246In list context, it's just the list argument separator, and inserts
ed5c6d31
PJ
1247both its arguments into the list. These arguments are also evaluated
1248from left to right.
a0d0e21e 1249
ba7f043c
KW
1250The C<< => >> operator (sometimes pronounced "fat comma") is a synonym
1251for the comma except that it causes a
4e1988c6 1252word on its left to be interpreted as a string if it begins with a letter
344f2c40
IG
1253or underscore and is composed only of letters, digits and underscores.
1254This includes operands that might otherwise be interpreted as operators,
46f8a5ea 1255constants, single number v-strings or function calls. If in doubt about
c543c01b 1256this behavior, the left operand can be quoted explicitly.
344f2c40
IG
1257
1258Otherwise, the C<< => >> operator behaves exactly as the comma operator
1259or list argument separator, according to context.
1260
1261For example:
a44e5664
MS
1262
1263 use constant FOO => "something";
1264
1265 my %h = ( FOO => 23 );
1266
1267is equivalent to:
1268
1269 my %h = ("FOO", 23);
1270
1271It is I<NOT>:
1272
1273 my %h = ("something", 23);
1274
719b43e8
RGS
1275The C<< => >> operator is helpful in documenting the correspondence
1276between keys and values in hashes, and other paired elements in lists.
748a9306 1277
a12b8f3c
FC
1278 %hash = ( $key => $value );
1279 login( $username => $password );
a44e5664 1280
4e1988c6
FC
1281The special quoting behavior ignores precedence, and hence may apply to
1282I<part> of the left operand:
1283
1284 print time.shift => "bbb";
1285
ba7f043c 1286That example prints something like C<"1314363215shiftbbb">, because the
4e1988c6
FC
1287C<< => >> implicitly quotes the C<shift> immediately on its left, ignoring
1288the fact that C<time.shift> is the entire left operand.
1289
a0d0e21e 1290=head2 List Operators (Rightward)
d74e8afc 1291X<operator, list, rightward> X<list operator>
a0d0e21e 1292
c543c01b 1293On the right side of a list operator, the comma has very low precedence,
a0d0e21e
LW
1294such that it controls all comma-separated expressions found there.
1295The only operators with lower precedence are the logical operators
ba7f043c 1296C<"and">, C<"or">, and C<"not">, which may be used to evaluate calls to list
1ca345ed
TC
1297operators without the need for parentheses:
1298
a8980281
P
1299 open HANDLE, "< :encoding(UTF-8)", "filename"
1300 or die "Can't open: $!\n";
1ca345ed
TC
1301
1302However, some people find that code harder to read than writing
1303it with parentheses:
1304
a8980281
P
1305 open(HANDLE, "< :encoding(UTF-8)", "filename")
1306 or die "Can't open: $!\n";
1ca345ed 1307
ba7f043c 1308in which case you might as well just use the more customary C<"||"> operator:
a0d0e21e 1309
a8980281
P
1310 open(HANDLE, "< :encoding(UTF-8)", "filename")
1311 || die "Can't open: $!\n";
a0d0e21e 1312
a95b3d6a 1313See also discussion of list operators in L</Terms and List Operators (Leftward)>.
a0d0e21e
LW
1314
1315=head2 Logical Not
d74e8afc 1316X<operator, logical, not> X<not>
a0d0e21e 1317
ba7f043c
KW
1318Unary C<"not"> returns the logical negation of the expression to its right.
1319It's the equivalent of C<"!"> except for the very low precedence.
a0d0e21e
LW
1320
1321=head2 Logical And
d74e8afc 1322X<operator, logical, and> X<and>
a0d0e21e 1323
ba7f043c 1324Binary C<"and"> returns the logical conjunction of the two surrounding
c543c01b
TC
1325expressions. It's equivalent to C<&&> except for the very low
1326precedence. This means that it short-circuits: the right
a0d0e21e
LW
1327expression is evaluated only if the left expression is true.
1328
59ab9d6e 1329=head2 Logical or and Exclusive Or
f23102e2 1330X<operator, logical, or> X<operator, logical, xor>
59ab9d6e 1331X<operator, logical, exclusive or>
f23102e2 1332X<or> X<xor>
a0d0e21e 1333
ba7f043c 1334Binary C<"or"> returns the logical disjunction of the two surrounding
c543c01b
TC
1335expressions. It's equivalent to C<||> except for the very low precedence.
1336This makes it useful for control flow:
5a964f20
TC
1337
1338 print FH $data or die "Can't write to FH: $!";
1339
c543c01b
TC
1340This means that it short-circuits: the right expression is evaluated
1341only if the left expression is false. Due to its precedence, you must
1342be careful to avoid using it as replacement for the C<||> operator.
1343It usually works out better for flow control than in assignments:
5a964f20 1344
db691027
SF
1345 $x = $y or $z; # bug: this is wrong
1346 ($x = $y) or $z; # really means this
1347 $x = $y || $z; # better written this way
5a964f20 1348
19799a22 1349However, when it's a list-context assignment and you're trying to use
ba7f043c 1350C<||> for control flow, you probably need C<"or"> so that the assignment
5a964f20
TC
1351takes higher precedence.
1352
1353 @info = stat($file) || die; # oops, scalar sense of stat!
1354 @info = stat($file) or die; # better, now @info gets its due
1355
c963b151
BD
1356Then again, you could always use parentheses.
1357
ba7f043c 1358Binary C<"xor"> returns the exclusive-OR of the two surrounding expressions.
c543c01b 1359It cannot short-circuit (of course).
a0d0e21e 1360
59ab9d6e
MB
1361There is no low precedence operator for defined-OR.
1362
a0d0e21e 1363=head2 C Operators Missing From Perl
d74e8afc
ITB
1364X<operator, missing from perl> X<&> X<*>
1365X<typecasting> X<(TYPE)>
a0d0e21e
LW
1366
1367Here is what C has that Perl doesn't:
1368
1369=over 8
1370
1371=item unary &
1372
ba7f043c 1373Address-of operator. (But see the C<"\"> operator for taking a reference.)
a0d0e21e
LW
1374
1375=item unary *
1376
46f8a5ea 1377Dereference-address operator. (Perl's prefix dereferencing
ba7f043c 1378operators are typed: C<$>, C<@>, C<%>, and C<&>.)
a0d0e21e
LW
1379
1380=item (TYPE)
1381
19799a22 1382Type-casting operator.
a0d0e21e
LW
1383
1384=back
1385
5f05dabc 1386=head2 Quote and Quote-like Operators
89d205f2 1387X<operator, quote> X<operator, quote-like> X<q> X<qq> X<qx> X<qw> X<m>
d74e8afc
ITB
1388X<qr> X<s> X<tr> X<'> X<''> X<"> X<""> X<//> X<`> X<``> X<<< << >>>
1389X<escape sequence> X<escape>
1390
a0d0e21e
LW
1391While we usually think of quotes as literal values, in Perl they
1392function as operators, providing various kinds of interpolating and
1393pattern matching capabilities. Perl provides customary quote characters
1394for these behaviors, but also provides a way for you to choose your
1395quote character for any of them. In the following table, a C<{}> represents
9f10b797 1396any pair of delimiters you choose.
a0d0e21e 1397
2c268ad5
TP
1398 Customary Generic Meaning Interpolates
1399 '' q{} Literal no
1400 "" qq{} Literal yes
af9219ee 1401 `` qx{} Command yes*
2c268ad5 1402 qw{} Word list no
af9219ee
MG
1403 // m{} Pattern match yes*
1404 qr{} Pattern yes*
1405 s{}{} Substitution yes*
2c268ad5 1406 tr{}{} Transliteration no (but see below)
c543c01b 1407 y{}{} Transliteration no (but see below)
7e3b091d 1408 <<EOF here-doc yes*
a0d0e21e 1409
af9219ee
MG
1410 * unless the delimiter is ''.
1411
87275199 1412Non-bracketing delimiters use the same character fore and aft, but the four
c543c01b 1413sorts of ASCII brackets (round, angle, square, curly) all nest, which means
9f10b797 1414that
87275199 1415
c543c01b 1416 q{foo{bar}baz}
35f2feb0 1417
9f10b797 1418is the same as
87275199 1419
c543c01b 1420 'foo{bar}baz'
87275199
GS
1421
1422Note, however, that this does not always work for quoting Perl code:
1423
db691027 1424 $s = q{ if($x eq "}") ... }; # WRONG
87275199 1425
ba7f043c 1426is a syntax error. The C<L<Text::Balanced>> module (standard as of v5.8,
c543c01b 1427and from CPAN before then) is able to do this properly.
87275199 1428
841bfb48
KW
1429There can (and in some cases, must) be whitespace between the operator
1430and the quoting
fb73857a 1431characters, except when C<#> is being used as the quoting character.
ba7f043c 1432C<q#foo#> is parsed as the string C<foo>, while S<C<q #foo#>> is the
19799a22
GS
1433operator C<q> followed by a comment. Its argument will be taken
1434from the next line. This allows you to write:
fb73857a
PP
1435
1436 s {foo} # Replace foo
1437 {bar} # with bar.
1438
841bfb48
KW
1439The cases where whitespace must be used are when the quoting character
1440is a word character (meaning it matches C</\w/>):
1441
1442 q XfooX # Works: means the string 'foo'
1443 qXfooX # WRONG!
1444
c543c01b
TC
1445The following escape sequences are available in constructs that interpolate,
1446and in transliterations:
5691ca5f 1447X<\t> X<\n> X<\r> X<\f> X<\b> X<\a> X<\e> X<\x> X<\0> X<\c> X<\N> X<\N{}>
04341565 1448X<\o{}>
5691ca5f 1449
2c4c1ff2
KW
1450 Sequence Note Description
1451 \t tab (HT, TAB)
1452 \n newline (NL)
1453 \r return (CR)
1454 \f form feed (FF)
1455 \b backspace (BS)
1456 \a alarm (bell) (BEL)
1457 \e escape (ESC)
c543c01b 1458 \x{263A} [1,8] hex char (example: SMILEY)
2c4c1ff2 1459 \x1b [2,8] restricted range hex char (example: ESC)
fb121860 1460 \N{name} [3] named Unicode character or character sequence
2c4c1ff2
KW
1461 \N{U+263D} [4,8] Unicode character (example: FIRST QUARTER MOON)
1462 \c[ [5] control char (example: chr(27))
1463 \o{23072} [6,8] octal char (example: SMILEY)
1464 \033 [7,8] restricted range octal char (example: ESC)
5691ca5f
KW
1465
1466=over 4
1467
1468=item [1]
1469
2c4c1ff2
KW
1470The result is the character specified by the hexadecimal number between
1471the braces. See L</[8]> below for details on which character.
96448467 1472
46f8a5ea 1473Only hexadecimal digits are valid between the braces. If an invalid
96448467
DG
1474character is encountered, a warning will be issued and the invalid
1475character and all subsequent characters (valid or invalid) within the
1476braces will be discarded.
1477
1478If there are no valid digits between the braces, the generated character is
1479the NULL character (C<\x{00}>). However, an explicit empty brace (C<\x{}>)
c543c01b 1480will not cause a warning (currently).
40687185
KW
1481
1482=item [2]
1483
2c4c1ff2
KW
1484The result is the character specified by the hexadecimal number in the range
14850x00 to 0xFF. See L</[8]> below for details on which character.
96448467
DG
1486
1487Only hexadecimal digits are valid following C<\x>. When C<\x> is followed
2c4c1ff2 1488by fewer than two valid digits, any valid digits will be zero-padded. This
ba7f043c 1489means that C<\x7> will be interpreted as C<\x07>, and a lone C<"\x"> will be
2c4c1ff2 1490interpreted as C<\x00>. Except at the end of a string, having fewer than
c543c01b 1491two valid digits will result in a warning. Note that although the warning
96448467
DG
1492says the illegal character is ignored, it is only ignored as part of the
1493escape and will still be used as the subsequent character in the string.
1494For example:
1495
1496 Original Result Warns?
1497 "\x7" "\x07" no
1498 "\x" "\x00" no
1499 "\x7q" "\x07q" yes
1500 "\xq" "\x00q" yes
1501
40687185
KW
1502=item [3]
1503
fb121860 1504The result is the Unicode character or character sequence given by I<name>.
2c4c1ff2 1505See L<charnames>.
40687185
KW
1506
1507=item [4]
1508
ba7f043c 1509S<C<\N{U+I<hexadecimal number>}>> means the Unicode character whose Unicode code
2c4c1ff2 1510point is I<hexadecimal number>.
40687185
KW
1511
1512=item [5]
1513
5691ca5f
KW
1514The character following C<\c> is mapped to some other character as shown in the
1515table:
1516
1517 Sequence Value
1518 \c@ chr(0)
1519 \cA chr(1)
1520 \ca chr(1)
1521 \cB chr(2)
1522 \cb chr(2)
1523 ...
1524 \cZ chr(26)
1525 \cz chr(26)
1526 \c[ chr(27)
ba7f043c 1527 # See below for chr(28)
5691ca5f
KW
1528 \c] chr(29)
1529 \c^ chr(30)
c3e9d7a9 1530 \c_ chr(31)
ba7f043c
KW
1531 \c? chr(127) # (on ASCII platforms; see below for link to
1532 # EBCDIC discussion)
5691ca5f 1533
d813941f 1534In other words, it's the character whose code point has had 64 xor'd with
c3e9d7a9
KW
1535its uppercase. C<\c?> is DELETE on ASCII platforms because
1536S<C<ord("?") ^ 64>> is 127, and
ba7f043c 1537C<\c@> is NULL because the ord of C<"@"> is 64, so xor'ing 64 itself produces 0.
d813941f 1538
ba7f043c 1539Also, C<\c\I<X>> yields S<C< chr(28) . "I<X>">> for any I<X>, but cannot come at the
5691ca5f
KW
1540end of a string, because the backslash would be parsed as escaping the end
1541quote.
1542
1543On ASCII platforms, the resulting characters from the list above are the
1544complete set of ASCII controls. This isn't the case on EBCDIC platforms; see
c3e9d7a9
KW
1545L<perlebcdic/OPERATOR DIFFERENCES> for a full discussion of the
1546differences between these for ASCII versus EBCDIC platforms.
5691ca5f 1547
c3e9d7a9 1548Use of any other character following the C<"c"> besides those listed above is
63a63d81
KW
1549discouraged, and as of Perl v5.20, the only characters actually allowed
1550are the printable ASCII ones, minus the left brace C<"{">. What happens
1551for any of the allowed other characters is that the value is derived by
1552xor'ing with the seventh bit, which is 64, and a warning raised if
1553enabled. Using the non-allowed characters generates a fatal error.
5691ca5f
KW
1554
1555To get platform independent controls, you can use C<\N{...}>.
1556
40687185
KW
1557=item [6]
1558
2c4c1ff2
KW
1559The result is the character specified by the octal number between the braces.
1560See L</[8]> below for details on which character.
04341565
DG
1561
1562If a character that isn't an octal digit is encountered, a warning is raised,
1563and the value is based on the octal digits before it, discarding it and all
1564following characters up to the closing brace. It is a fatal error if there are
1565no octal digits at all.
1566
1567=item [7]
1568
c543c01b 1569The result is the character specified by the three-digit octal number in the
2c4c1ff2
KW
1570range 000 to 777 (but best to not use above 077, see next paragraph). See
1571L</[8]> below for details on which character.
1572
1573Some contexts allow 2 or even 1 digit, but any usage without exactly
40687185 1574three digits, the first being a zero, may give unintended results. (For
5db3e519
FC
1575example, in a regular expression it may be confused with a backreference;
1576see L<perlrebackslash/Octal escapes>.) Starting in Perl 5.14, you may
c543c01b 1577use C<\o{}> instead, which avoids all these problems. Otherwise, it is best to
04341565
DG
1578use this construct only for ordinals C<\077> and below, remembering to pad to
1579the left with zeros to make three digits. For larger ordinals, either use
ba7f043c
KW
1580C<\o{}>, or convert to something else, such as to hex and use C<\N{U+}>
1581(which is portable between platforms with different character sets) or
1582C<\x{}> instead.
40687185 1583
2c4c1ff2
KW
1584=item [8]
1585
c543c01b 1586Several constructs above specify a character by a number. That number
2c4c1ff2 1587gives the character's position in the character set encoding (indexed from 0).
c543c01b 1588This is called synonymously its ordinal, code position, or code point. Perl
2c4c1ff2
KW
1589works on platforms that have a native encoding currently of either ASCII/Latin1
1590or EBCDIC, each of which allow specification of 256 characters. In general, if
1591the number is 255 (0xFF, 0377) or below, Perl interprets this in the platform's
1592native encoding. If the number is 256 (0x100, 0400) or above, Perl interprets
c543c01b 1593it as a Unicode code point and the result is the corresponding Unicode
2c4c1ff2
KW
1594character. For example C<\x{50}> and C<\o{120}> both are the number 80 in
1595decimal, which is less than 256, so the number is interpreted in the native
1596character set encoding. In ASCII the character in the 80th position (indexed
ba7f043c 1597from 0) is the letter C<"P">, and in EBCDIC it is the ampersand symbol C<"&">.
2c4c1ff2
KW
1598C<\x{100}> and C<\o{400}> are both 256 in decimal, so the number is interpreted
1599as a Unicode code point no matter what the native encoding is. The name of the
9fef6a0d 1600character in the 256th position (indexed by 0) in Unicode is
2c4c1ff2
KW
1601C<LATIN CAPITAL LETTER A WITH MACRON>.
1602
2dc9bc84 1603An exception to the above rule is that S<C<\N{U+I<hex number>}>> is
ba7f043c 1604always interpreted as a Unicode code point, so that C<\N{U+0050}> is C<"P"> even
2dc9bc84 1605on EBCDIC platforms.
2c4c1ff2 1606
5691ca5f 1607=back
4c77eaa2 1608
e526e8bb 1609B<NOTE>: Unlike C and other languages, Perl has no C<\v> escape sequence for
8b312c40 1610the vertical tab (VT, which is 11 in both ASCII and EBCDIC), but you may
ba7f043c 1611use C<\N{VT}>, C<\ck>, C<\N{U+0b}>, or C<\x0b>. (C<\v>
e526e8bb
KW
1612does have meaning in regular expression patterns in Perl, see L<perlre>.)
1613
1614The following escape sequences are available in constructs that interpolate,
904501ec 1615but not in transliterations.
628253b8 1616X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q> X<\F>
904501ec 1617
c543c01b
TC
1618 \l lowercase next character only
1619 \u titlecase (not uppercase!) next character only
e4d34742
EB
1620 \L lowercase all characters till \E or end of string
1621 \U uppercase all characters till \E or end of string
628253b8 1622 \F foldcase all characters till \E or end of string
736fe711
KW
1623 \Q quote (disable) pattern metacharacters till \E or
1624 end of string
7e31b643 1625 \E end either case modification or quoted section
c543c01b
TC
1626 (whichever was last seen)
1627
736fe711
KW
1628See L<perlfunc/quotemeta> for the exact definition of characters that
1629are quoted by C<\Q>.
1630
628253b8 1631C<\L>, C<\U>, C<\F>, and C<\Q> can stack, in which case you need one
c543c01b
TC
1632C<\E> for each. For example:
1633
9fef6a0d
KW
1634 say"This \Qquoting \ubusiness \Uhere isn't quite\E done yet,\E is it?";
1635 This quoting\ Business\ HERE\ ISN\'T\ QUITE\ done\ yet\, is it?
a0d0e21e 1636
ba7f043c
KW
1637If a S<C<use locale>> form that includes C<LC_CTYPE> is in effect (see
1638L<perllocale>), the case map used by C<\l>, C<\L>, C<\u>, and C<\U> is
1639taken from the current locale. If Unicode (for example, C<\N{}> or code
1640points of 0x100 or beyond) is being used, the case map used by C<\l>,
1641C<\L>, C<\u>, and C<\U> is as defined by Unicode. That means that
1642case-mapping a single character can sometimes produce a sequence of
1643several characters.
1644Under S<C<use locale>>, C<\F> produces the same results as C<\L>
31f05a37
KW
1645for all locales but a UTF-8 one, where it instead uses the Unicode
1646definition.
a034a98d 1647
5a964f20
TC
1648All systems use the virtual C<"\n"> to represent a line terminator,
1649called a "newline". There is no such thing as an unvarying, physical
19799a22 1650newline character. It is only an illusion that the operating system,
5a964f20
TC
1651device drivers, C libraries, and Perl all conspire to preserve. Not all
1652systems read C<"\r"> as ASCII CR and C<"\n"> as ASCII LF. For example,
c543c01b 1653on the ancient Macs (pre-MacOS X) of yesteryear, these used to be reversed,
ba7f043c 1654and on systems without a line terminator,
c543c01b 1655printing C<"\n"> might emit no actual data. In general, use C<"\n"> when
5a964f20
TC
1656you mean a "newline" for your system, but use the literal ASCII when you
1657need an exact character. For example, most networking protocols expect
2a380090 1658and prefer a CR+LF (C<"\015\012"> or C<"\cM\cJ">) for line terminators,
5a964f20
TC
1659and although they often accept just C<"\012">, they seldom tolerate just
1660C<"\015">. If you get in the habit of using C<"\n"> for networking,
1661you may be burned some day.
d74e8afc
ITB
1662X<newline> X<line terminator> X<eol> X<end of line>
1663X<\n> X<\r> X<\r\n>
5a964f20 1664
904501ec
MG
1665For constructs that do interpolate, variables beginning with "C<$>"
1666or "C<@>" are interpolated. Subscripted variables such as C<$a[3]> or
ad0f383a
A
1667C<< $href->{key}[0] >> are also interpolated, as are array and hash slices.
1668But method calls such as C<< $obj->meth >> are not.
af9219ee
MG
1669
1670Interpolating an array or slice interpolates the elements in order,
1671separated by the value of C<$">, so is equivalent to interpolating
ba7f043c 1672S<C<join $", @array>>. "Punctuation" arrays such as C<@*> are usually
c543c01b
TC
1673interpolated only if the name is enclosed in braces C<@{*}>, but the
1674arrays C<@_>, C<@+>, and C<@-> are interpolated even without braces.
af9219ee 1675
bc7b91c6
EB
1676For double-quoted strings, the quoting from C<\Q> is applied after
1677interpolation and escapes are processed.
1678
1679 "abc\Qfoo\tbar$s\Exyz"
1680
1681is equivalent to
1682
1683 "abc" . quotemeta("foo\tbar$s") . "xyz"
1684
1685For the pattern of regex operators (C<qr//>, C<m//> and C<s///>),
1686the quoting from C<\Q> is applied after interpolation is processed,
46f8a5ea
FC
1687but before escapes are processed. This allows the pattern to match
1688literally (except for C<$> and C<@>). For example, the following matches:
bc7b91c6
EB
1689
1690 '\s\t' =~ /\Q\s\t/
1691
1692Because C<$> or C<@> trigger interpolation, you'll need to use something
1693like C</\Quser\E\@\Qhost/> to match them literally.
1d2dff63 1694
a0d0e21e
LW
1695Patterns are subject to an additional level of interpretation as a
1696regular expression. This is done as a second pass, after variables are
1697interpolated, so that regular expressions may be incorporated into the
1698pattern from the variables. If this is not what you want, use C<\Q> to
1699interpolate a variable literally.
1700
19799a22
GS
1701Apart from the behavior described above, Perl does not expand
1702multiple levels of interpolation. In particular, contrary to the
1703expectations of shell programmers, back-quotes do I<NOT> interpolate
1704within double quotes, nor do single quotes impede evaluation of
1705variables when used within double quotes.
a0d0e21e 1706
5f05dabc 1707=head2 Regexp Quote-Like Operators
d74e8afc 1708X<operator, regexp>
cb1a09d0 1709
5f05dabc 1710Here are the quote-like operators that apply to pattern
cb1a09d0
AD
1711matching and related activities.
1712
a0d0e21e
LW
1713=over 8
1714
ba7f043c 1715=item C<qr/I<STRING>/msixpodualn>
01c6f5f4 1716X<qr> X</i> X</m> X</o> X</s> X</x> X</p>
a0d0e21e 1717
87e95b7f
YO
1718This operator quotes (and possibly compiles) its I<STRING> as a regular
1719expression. I<STRING> is interpolated the same way as I<PATTERN>
6d314683
YO
1720in C<m/I<PATTERN>/>. If C<"'"> is used as the delimiter, no variable
1721interpolation is done. Returns a Perl value which may be used instead of the
ba7f043c 1722corresponding C</I<STRING>/msixpodualn> expression. The returned value is a
46f8a5ea 1723normalized version of the original pattern. It magically differs from
1c8ee595 1724a string containing the same characters: C<ref(qr/x/)> returns "Regexp";
a727cfac 1725however, dereferencing it is not well defined (you currently get the
1c8ee595
CO
1726normalized version of the original pattern, but this may change).
1727
a0d0e21e 1728
87e95b7f
YO
1729For example,
1730
1731 $rex = qr/my.STRING/is;
85dd5c8b 1732 print $rex; # prints (?si-xm:my.STRING)
87e95b7f
YO
1733 s/$rex/foo/;
1734
1735is equivalent to
1736
1737 s/my.STRING/foo/is;
1738
1739The result may be used as a subpattern in a match:
1740
1741 $re = qr/$pattern/;
7188ca43
KW
1742 $string =~ /foo${re}bar/; # can be interpolated in other
1743 # patterns
87e95b7f
YO
1744 $string =~ $re; # or used standalone
1745 $string =~ /$re/; # or this way
1746
ba7f043c
KW
1747Since Perl may compile the pattern at the moment of execution of the C<qr()>
1748operator, using C<qr()> may have speed advantages in some situations,
1749notably if the result of C<qr()> is used standalone:
87e95b7f
YO
1750
1751 sub match {
1752 my $patterns = shift;
1753 my @compiled = map qr/$_/i, @$patterns;
1754 grep {
1755 my $success = 0;
1756 foreach my $pat (@compiled) {
1757 $success = 1, last if /$pat/;
1758 }
1759 $success;
1760 } @_;
5a964f20
TC
1761 }
1762
87e95b7f 1763Precompilation of the pattern into an internal representation at
ba7f043c 1764the moment of C<qr()> avoids the need to recompile the pattern every
87e95b7f
YO
1765time a match C</$pat/> is attempted. (Perl has many other internal
1766optimizations, but none would be triggered in the above example if
ba7f043c 1767we did not use C<qr()> operator.)
87e95b7f 1768
765fa144 1769Options (specified by the following modifiers) are:
87e95b7f
YO
1770
1771 m Treat string as multiple lines.
1772 s Treat string as single line. (Make . match a newline)
1773 i Do case-insensitive pattern matching.
77c8f263
KW
1774 x Use extended regular expressions; specifying two
1775 x's means \t and the SPACE character are ignored within
1776 square-bracketed character classes
87e95b7f 1777 p When matching preserve a copy of the matched string so
7188ca43 1778 that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be
ba7f043c 1779 defined (ignored starting in v5.20) as these are always
1a8aad5a 1780 defined starting in that release
87e95b7f 1781 o Compile pattern only once.
8ef45c18
KW
1782 a ASCII-restrict: Use ASCII for \d, \s, \w and [[:posix:]]
1783 character classes; specifying two a's adds the further
1784 restriction that no ASCII character will match a
1785 non-ASCII one under /i.
ba7f043c 1786 l Use the current run-time locale's rules.
48cbae4f
SK
1787 u Use Unicode rules.
1788 d Use Unicode or native charset, as in 5.12 and earlier.
33be4c61 1789 n Non-capture mode. Don't let () fill in $1, $2, etc...
87e95b7f
YO
1790
1791If a precompiled pattern is embedded in a larger pattern then the effect
ba7f043c
KW
1792of C<"msixpluadn"> will be propagated appropriately. The effect that the
1793C</o> modifier has is not propagated, being restricted to those patterns
87e95b7f
YO
1794explicitly using it.
1795
d6c0a908 1796The C</a>, C</d>, C</l>, and C</u> modifiers (added in Perl 5.14)
850b7ec9 1797control the character set rules, but C</a> is the only one you are likely
18509dec
KW
1798to want to specify explicitly; the other three are selected
1799automatically by various pragmas.
da392a17 1800
ba7f043c 1801See L<perlre> for additional information on valid syntax for I<STRING>, and
5e2aa8f5 1802for a detailed look at the semantics of regular expressions. In
1ca345ed
TC
1803particular, all modifiers except the largely obsolete C</o> are further
1804explained in L<perlre/Modifiers>. C</o> is described in the next section.
a0d0e21e 1805
ba7f043c 1806=item C<m/I<PATTERN>/msixpodualngc>
89d205f2
YO
1807X<m> X<operator, match>
1808X<regexp, options> X<regexp> X<regex, options> X<regex>
01c6f5f4 1809X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c>
a0d0e21e 1810
ba7f043c 1811=item C</I<PATTERN>/msixpodualngc>
a0d0e21e 1812
5a964f20 1813Searches a string for a pattern match, and in scalar context returns
19799a22 1814true if it succeeds, false if it fails. If no string is specified
ba7f043c 1815via the C<=~> or C<!~> operator, the C<$_> string is searched. (The
19799a22
GS
1816string specified with C<=~> need not be an lvalue--it may be the
1817result of an expression evaluation, but remember the C<=~> binds
006671a6 1818rather tightly.) See also L<perlre>.
a0d0e21e 1819
f6050459 1820Options are as described in C<qr//> above; in addition, the following match
01c6f5f4 1821process modifiers are available:
a0d0e21e 1822
950b09ed 1823 g Match globally, i.e., find all occurrences.
7188ca43
KW
1824 c Do not reset search position on a failed match when /g is
1825 in effect.
a0d0e21e 1826
ba7f043c 1827If C<"/"> is the delimiter then the initial C<m> is optional. With the C<m>
c543c01b 1828you can use any pair of non-whitespace (ASCII) characters
725a61d7 1829as delimiters. This is particularly useful for matching path names
ba7f043c 1830that contain C<"/">, to avoid LTS (leaning toothpick syndrome). If C<"?"> is
725a61d7 1831the delimiter, then a match-only-once rule applies,
ba7f043c 1832described in C<m?I<PATTERN>?> below. If C<"'"> (single quote) is the delimiter,
6d314683 1833no variable interpolation is performed on the I<PATTERN>.
ba7f043c 1834When using a delimiter character valid in an identifier, whitespace is required
ed02a3bf 1835after the C<m>.
a0d0e21e 1836
ba7f043c 1837I<PATTERN> may contain variables, which will be interpolated
532c9e80 1838every time the pattern search is evaluated, except
1f247705
GS
1839for when the delimiter is a single quote. (Note that C<$(>, C<$)>, and
1840C<$|> are not interpolated because they look like end-of-string tests.)
532c9e80
KW
1841Perl will not recompile the pattern unless an interpolated
1842variable that it contains changes. You can force Perl to skip the
1843test and never recompile by adding a C</o> (which stands for "once")
1844after the trailing delimiter.
1845Once upon a time, Perl would recompile regular expressions
1846unnecessarily, and this modifier was useful to tell it not to do so, in the
5cc41653 1847interests of speed. But now, the only reasons to use C</o> are one of:
532c9e80
KW
1848
1849=over
1850
1851=item 1
1852
1853The variables are thousands of characters long and you know that they
1854don't change, and you need to wring out the last little bit of speed by
1855having Perl skip testing for that. (There is a maintenance penalty for
1856doing this, as mentioning C</o> constitutes a promise that you won't
18509dec 1857change the variables in the pattern. If you do change them, Perl won't
532c9e80
KW
1858even notice.)
1859
1860=item 2
1861
1862you want the pattern to use the initial values of the variables
1863regardless of whether they change or not. (But there are saner ways
1864of accomplishing this than using C</o>.)
1865
fa9b8686
DM
1866=item 3
1867
1868If the pattern contains embedded code, such as
1869
1870 use re 'eval';
1871 $code = 'foo(?{ $x })';
1872 /$code/
1873
1874then perl will recompile each time, even though the pattern string hasn't
1875changed, to ensure that the current value of C<$x> is seen each time.
1876Use C</o> if you want to avoid this.
1877
532c9e80 1878=back
a0d0e21e 1879
18509dec
KW
1880The bottom line is that using C</o> is almost never a good idea.
1881
ba7f043c 1882=item The empty pattern C<//>
e9d89077 1883
ba7f043c 1884If the I<PATTERN> evaluates to the empty string, the last
46f8a5ea 1885I<successfully> matched regular expression is used instead. In this
c543c01b 1886case, only the C<g> and C<c> flags on the empty pattern are honored;
46f8a5ea 1887the other flags are taken from the original pattern. If no match has
d65afb4b
HS
1888previously succeeded, this will (silently) act instead as a genuine
1889empty pattern (which will always match).
a0d0e21e 1890
89d205f2
YO
1891Note that it's possible to confuse Perl into thinking C<//> (the empty
1892regex) is really C<//> (the defined-or operator). Perl is usually pretty
1893good about this, but some pathological cases might trigger this, such as
ba7f043c
KW
1894C<$x///> (is that S<C<($x) / (//)>> or S<C<$x // />>?) and S<C<print $fh //>>
1895(S<C<print $fh(//>> or S<C<print($fh //>>?). In all of these examples, Perl
89d205f2
YO
1896will assume you meant defined-or. If you meant the empty regex, just
1897use parentheses or spaces to disambiguate, or even prefix the empty
c963b151
BD
1898regex with an C<m> (so C<//> becomes C<m//>).
1899
e9d89077
DN
1900=item Matching in list context
1901
19799a22 1902If the C</g> option is not used, C<m//> in list context returns a
a0d0e21e 1903list consisting of the subexpressions matched by the parentheses in the
3ff8ecf9
BF
1904pattern, that is, (C<$1>, C<$2>, C<$3>...) (Note that here C<$1> etc. are
1905also set). When there are no parentheses in the pattern, the return
a727cfac 1906value is the list C<(1)> for success.
3ff8ecf9 1907With or without parentheses, an empty list is returned upon failure.
a0d0e21e
LW
1908
1909Examples:
1910
7188ca43
KW
1911 open(TTY, "+</dev/tty")
1912 || die "can't access /dev/tty: $!";
c543c01b 1913
7188ca43 1914 <TTY> =~ /^y/i && foo(); # do foo if desired
a0d0e21e 1915
7188ca43 1916 if (/Version: *([0-9.]*)/) { $version = $1; }
a0d0e21e 1917
7188ca43 1918 next if m#^/usr/spool/uucp#;
a0d0e21e 1919
7188ca43
KW
1920 # poor man's grep
1921 $arg = shift;
1922 while (<>) {
1923 print if /$arg/o; # compile only once (no longer needed!)
1924 }
a0d0e21e 1925
7188ca43 1926 if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
a0d0e21e 1927
ba7f043c
KW
1928This last example splits C<$foo> into the first two words and the
1929remainder of the line, and assigns those three fields to C<$F1>, C<$F2>, and
1930C<$Etc>. The conditional is true if any variables were assigned; that is,
c543c01b 1931if the pattern matched.
a0d0e21e 1932
19799a22 1933The C</g> modifier specifies global pattern matching--that is,
46f8a5ea
FC
1934matching as many times as possible within the string. How it behaves
1935depends on the context. In list context, it returns a list of the
19799a22 1936substrings matched by any capturing parentheses in the regular
46f8a5ea 1937expression. If there are no parentheses, it returns a list of all
19799a22
GS
1938the matched strings, as if there were parentheses around the whole
1939pattern.
a0d0e21e 1940
7e86de3e 1941In scalar context, each execution of C<m//g> finds the next match,
19799a22 1942returning true if it matches, and false if there is no further match.
3dd93342 1943The position after the last match can be read or set using the C<pos()>
46f8a5ea 1944function; see L<perlfunc/pos>. A failed match normally resets the
7e86de3e 1945search position to the beginning of the string, but you can avoid that
46f8a5ea 1946by adding the C</c> modifier (for example, C<m//gc>). Modifying the target
7e86de3e 1947string also resets the search position.
c90c0ff4 1948
ba7f043c 1949=item C<\G I<assertion>>
e9d89077 1950
c90c0ff4 1951You can intermix C<m//g> matches with C<m/\G.../g>, where C<\G> is a
3dd93342 1952zero-width assertion that matches the exact position where the
46f8a5ea 1953previous C<m//g>, if any, left off. Without the C</g> modifier, the
3dd93342 1954C<\G> assertion still anchors at C<pos()> as it was at the start of
1955the operation (see L<perlfunc/pos>), but the match is of course only
46f8a5ea 1956attempted once. Using C<\G> without C</g> on a target string that has
3dd93342 1957not previously had a C</g> match applied to it is the same as using
1958the C<\A> assertion to match the beginning of the string. Note also
1959that, currently, C<\G> is only properly supported when anchored at the
1960very beginning of the pattern.
c90c0ff4
PP
1961
1962Examples:
a0d0e21e
LW
1963
1964 # list context
1965 ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
1966
1967 # scalar context
c543c01b
TC
1968 local $/ = "";
1969 while ($paragraph = <>) {
1970 while ($paragraph =~ /\p{Ll}['")]*[.!?]+['")]*\s/g) {
19799a22 1971 $sentences++;
a0d0e21e
LW
1972 }
1973 }
c543c01b
TC
1974 say $sentences;
1975
1976Here's another way to check for sentences in a paragraph:
1977
7188ca43
KW
1978 my $sentence_rx = qr{
1979 (?: (?<= ^ ) | (?<= \s ) ) # after start-of-string or
1980 # whitespace
1981 \p{Lu} # capital letter
1982 .*? # a bunch of anything
1983 (?<= \S ) # that ends in non-
1984 # whitespace
1985 (?<! \b [DMS]r ) # but isn't a common abbr.
1986 (?<! \b Mrs )
1987 (?<! \b Sra )
1988 (?<! \b St )
1989 [.?!] # followed by a sentence
1990 # ender
1991 (?= $ | \s ) # in front of end-of-string
1992 # or whitespace
1993 }sx;
1994 local $/ = "";
1995 while (my $paragraph = <>) {
1996 say "NEW PARAGRAPH";
1997 my $count = 0;
1998 while ($paragraph =~ /($sentence_rx)/g) {
1999 printf "\tgot sentence %d: <%s>\n", ++$count, $1;
c543c01b 2000 }
7188ca43 2001 }
c543c01b
TC
2002
2003Here's how to use C<m//gc> with C<\G>:
a0d0e21e 2004
137443ea 2005 $_ = "ppooqppqq";
44a8e56a
PP
2006 while ($i++ < 2) {
2007 print "1: '";
c90c0ff4 2008 print $1 while /(o)/gc; print "', pos=", pos, "\n";
44a8e56a 2009 print "2: '";
c90c0ff4 2010 print $1 if /\G(q)/gc; print "', pos=", pos, "\n";
44a8e56a 2011 print "3: '";
c90c0ff4 2012 print $1 while /(p)/gc; print "', pos=", pos, "\n";
44a8e56a 2013 }
5d43e42d 2014 print "Final: '$1', pos=",pos,"\n" if /\G(.)/;
44a8e56a
PP
2015
2016The last example should print:
2017
2018 1: 'oo', pos=4
137443ea 2019 2: 'q', pos=5
44a8e56a
PP
2020 3: 'pp', pos=7
2021 1: '', pos=7
137443ea
PP
2022 2: 'q', pos=8
2023 3: '', pos=8
5d43e42d
DC
2024 Final: 'q', pos=8
2025
2026Notice that the final match matched C<q> instead of C<p>, which a match
46f8a5ea
FC
2027without the C<\G> anchor would have done. Also note that the final match
2028did not update C<pos>. C<pos> is only updated on a C</g> match. If the
7b0ac457
AB
2029final match did indeed match C<p>, it's a good bet that you're running an
2030ancient (pre-5.6.0) version of Perl.
44a8e56a 2031
c90c0ff4 2032A useful idiom for C<lex>-like scanners is C</\G.../gc>. You can
e7ea3e70 2033combine several regexps like this to process a string part-by-part,
c90c0ff4
PP
2034doing different actions depending on which regexp matched. Each
2035regexp tries to match where the previous one leaves off.
e7ea3e70 2036
3fe9a6f1 2037 $_ = <<'EOL';
7188ca43
KW
2038 $url = URI::URL->new( "http://example.com/" );
2039 die if $url eq "xXx";
3fe9a6f1 2040 EOL
c543c01b
TC
2041
2042 LOOP: {
950b09ed 2043 print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc;
7188ca43
KW
2044 print(" lowercase"), redo LOOP
2045 if /\G\p{Ll}+\b[,.;]?\s*/gc;
2046 print(" UPPERCASE"), redo LOOP
2047 if /\G\p{Lu}+\b[,.;]?\s*/gc;
2048 print(" Capitalized"), redo LOOP
2049 if /\G\p{Lu}\p{Ll}+\b[,.;]?\s*/gc;
c543c01b 2050 print(" MiXeD"), redo LOOP if /\G\pL+\b[,.;]?\s*/gc;
7188ca43
KW
2051 print(" alphanumeric"), redo LOOP
2052 if /\G[\p{Alpha}\pN]+\b[,.;]?\s*/gc;
c543c01b 2053 print(" line-noise"), redo LOOP if /\G\W+/gc;
950b09ed 2054 print ". That's all!\n";
c543c01b 2055 }
e7ea3e70
IZ
2056
2057Here is the output (split into several lines):
2058
7188ca43
KW
2059 line-noise lowercase line-noise UPPERCASE line-noise UPPERCASE
2060 line-noise lowercase line-noise lowercase line-noise lowercase
2061 lowercase line-noise lowercase lowercase line-noise lowercase
2062 lowercase line-noise MiXeD line-noise. That's all!
44a8e56a 2063
ba7f043c 2064=item C<m?I<PATTERN>?msixpodualngc>
725a61d7 2065X<?> X<operator, match-once>
87e95b7f 2066
ba7f043c
KW
2067This is just like the C<m/I<PATTERN>/> search, except that it matches
2068only once between calls to the C<reset()> operator. This is a useful
87e95b7f 2069optimization when you want to see only the first occurrence of
ceb131e8 2070something in each file of a set of files, for instance. Only C<m??>
87e95b7f
YO
2071patterns local to the current package are reset.
2072
2073 while (<>) {
ceb131e8 2074 if (m?^$?) {
87e95b7f
YO
2075 # blank line between header and body
2076 }
2077 } continue {
725a61d7 2078 reset if eof; # clear m?? status for next file
87e95b7f
YO
2079 }
2080
c543c01b
TC
2081Another example switched the first "latin1" encoding it finds
2082to "utf8" in a pod file:
2083
2084 s//utf8/ if m? ^ =encoding \h+ \K latin1 ?x;
2085
2086The match-once behavior is controlled by the match delimiter being
4932eeca 2087C<?>; with any other delimiter this is the normal C<m//> operator.
725a61d7 2088
ba7f043c 2089In the past, the leading C<m> in C<m?I<PATTERN>?> was optional, but omitting it
0381ecf1
MH
2090would produce a deprecation warning. As of v5.22.0, omitting it produces a
2091syntax error. If you encounter this construct in older code, you can just add
2092C<m>.
87e95b7f 2093
ba7f043c 2094=item C<s/I<PATTERN>/I<REPLACEMENT>/msixpodualngcer>
0a31ee11 2095X<s> X<substitute> X<substitution> X<replace> X<regexp, replace>
4f4d7508 2096X<regexp, substitute> X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c> X</e> X</r>
87e95b7f
YO
2097
2098Searches a string for a pattern, and if found, replaces that pattern
2099with the replacement text and returns the number of substitutions
e792e8c0
LM
2100made. Otherwise it returns false (a value that is both an empty string (C<"">)
2101and numeric zero (C<0>) as described in L</Relational Operators>).
87e95b7f 2102
c543c01b 2103If the C</r> (non-destructive) option is used then it runs the
679563bb
KW
2104substitution on a copy of the string and instead of returning the
2105number of substitutions, it returns the copy whether or not a
c543c01b
TC
2106substitution occurred. The original string is never changed when
2107C</r> is used. The copy will always be a plain string, even if the
2108input is an object or a tied variable.
4f4d7508 2109
87e95b7f 2110If no string is specified via the C<=~> or C<!~> operator, the C<$_>
c543c01b
TC
2111variable is searched and modified. Unless the C</r> option is used,
2112the string specified must be a scalar variable, an array element, a
2113hash element, or an assignment to one of those; that is, some sort of
2114scalar lvalue.
87e95b7f 2115
6d314683 2116If the delimiter chosen is a single quote, no variable interpolation is
ba7f043c
KW
2117done on either the I<PATTERN> or the I<REPLACEMENT>. Otherwise, if the
2118I<PATTERN> contains a C<$> that looks like a variable rather than an
87e95b7f
YO
2119end-of-string test, the variable will be interpolated into the pattern
2120at run-time. If you want the pattern compiled only once the first time
2121the variable is interpolated, use the C</o> option. If the pattern
2122evaluates to the empty string, the last successfully executed regular
2123expression is used instead. See L<perlre> for further explanation on these.
87e95b7f 2124
ba7f043c 2125Options are as with C<m//> with the addition of the following replacement
87e95b7f
YO
2126specific options:
2127
2128 e Evaluate the right side as an expression.
7188ca43
KW
2129 ee Evaluate the right side as a string then eval the
2130 result.
2131 r Return substitution and leave the original string
2132 untouched.
87e95b7f 2133
ed02a3bf
DN
2134Any non-whitespace delimiter may replace the slashes. Add space after
2135the C<s> when using a character allowed in identifiers. If single quotes
2136are used, no interpretation is done on the replacement string (the C</e>
3ff8ecf9 2137modifier overrides this, however). Note that Perl treats backticks
ed02a3bf 2138as normal delimiters; the replacement text is not evaluated as a command.
ba7f043c 2139If the I<PATTERN> is delimited by bracketing quotes, the I<REPLACEMENT> has
1ca345ed 2140its own pair of quotes, which may or may not be bracketing quotes, for example,
87e95b7f
YO
2141C<s(foo)(bar)> or C<< s<foo>/bar/ >>. A C</e> will cause the
2142replacement portion to be treated as a full-fledged Perl expression
2143and evaluated right then and there. It is, however, syntax checked at
46f8a5ea 2144compile-time. A second C<e> modifier will cause the replacement portion
87e95b7f
YO
2145to be C<eval>ed before being run as a Perl expression.
2146
2147Examples:
2148
7188ca43 2149 s/\bgreen\b/mauve/g; # don't change wintergreen
87e95b7f
YO
2150
2151 $path =~ s|/usr/bin|/usr/local/bin|;
2152
2153 s/Login: $foo/Login: $bar/; # run-time pattern
2154
7188ca43
KW
2155 ($foo = $bar) =~ s/this/that/; # copy first, then
2156 # change
2157 ($foo = "$bar") =~ s/this/that/; # convert to string,
2158 # copy, then change
4f4d7508
DC
2159 $foo = $bar =~ s/this/that/r; # Same as above using /r
2160 $foo = $bar =~ s/this/that/r
7188ca43
KW
2161 =~ s/that/the other/r; # Chained substitutes
2162 # using /r
2163 @foo = map { s/this/that/r } @bar # /r is very useful in
2164 # maps
87e95b7f 2165
7188ca43 2166 $count = ($paragraph =~ s/Mister\b/Mr./g); # get change-cnt
87e95b7f
YO
2167
2168 $_ = 'abc123xyz';
2169 s/\d+/$&*2/e; # yields 'abc246xyz'
2170 s/\d+/sprintf("%5d",$&)/e; # yields 'abc 246xyz'
2171 s/\w/$& x 2/eg; # yields 'aabbcc 224466xxyyzz'
2172
2173 s/%(.)/$percent{$1}/g; # change percent escapes; no /e
2174 s/%(.)/$percent{$1} || $&/ge; # expr now, so /e
2175 s/^=(\w+)/pod($1)/ge; # use function call
2176
4f4d7508 2177 $_ = 'abc123xyz';
db691027 2178 $x = s/abc/def/r; # $x is 'def123xyz' and
4f4d7508
DC
2179 # $_ remains 'abc123xyz'.
2180
87e95b7f
YO
2181 # expand variables in $_, but dynamics only, using
2182 # symbolic dereferencing
2183 s/\$(\w+)/${$1}/g;
2184
2185 # Add one to the value of any numbers in the string
2186 s/(\d+)/1 + $1/eg;
2187
c543c01b
TC
2188 # Titlecase words in the last 30 characters only
2189 substr($str, -30) =~ s/\b(\p{Alpha}+)\b/\u\L$1/g;
2190
87e95b7f
YO
2191 # This will expand any embedded scalar variable
2192 # (including lexicals) in $_ : First $1 is interpolated
2193 # to the variable name, and then evaluated
2194 s/(\$\w+)/$1/eeg;
2195
2196 # Delete (most) C comments.
2197 $program =~ s {
2198 /\* # Match the opening delimiter.
2199 .*? # Match a minimal number of characters.
2200 \*/ # Match the closing delimiter.
2201 } []gsx;
2202
7188ca43
KW
2203 s/^\s*(.*?)\s*$/$1/; # trim whitespace in $_,
2204 # expensively
87e95b7f 2205
7188ca43
KW
2206 for ($variable) { # trim whitespace in $variable,
2207 # cheap
87e95b7f
YO
2208 s/^\s+//;
2209 s/\s+$//;
2210 }
2211
2212 s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
2213
ba7f043c
KW
2214Note the use of C<$> instead of C<\> in the last example. Unlike
2215B<sed>, we use the \<I<digit>> form only in the left hand side.
87e95b7f
YO
2216Anywhere else it's $<I<digit>>.
2217
2218Occasionally, you can't use just a C</g> to get all the changes
2219to occur that you might want. Here are two common cases:
2220
2221 # put commas in the right places in an integer
2222 1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g;
2223
2224 # expand tabs to 8-column spacing
2225 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
2226
2227=back
2228
2229=head2 Quote-Like Operators
2230X<operator, quote-like>
2231
01c6f5f4
RGS
2232=over 4
2233
ba7f043c 2234=item C<q/I<STRING>/>
5d44bfff 2235X<q> X<quote, single> X<'> X<''>
a0d0e21e 2236
ba7f043c 2237=item C<'I<STRING>'>
a0d0e21e 2238
19799a22 2239A single-quoted, literal string. A backslash represents a backslash
68dc0745
PP
2240unless followed by the delimiter or another backslash, in which case
2241the delimiter or backslash is interpolated.
a0d0e21e
LW
2242
2243 $foo = q!I said, "You said, 'She said it.'"!;
2244 $bar = q('This is it.');
68dc0745 2245 $baz = '\n'; # a two-character string
a0d0e21e 2246
ba7f043c 2247=item C<qq/I<STRING>/>
d74e8afc 2248X<qq> X<quote, double> X<"> X<"">
a0d0e21e 2249
ba7f043c 2250=item "I<STRING>"
a0d0e21e
LW
2251
2252A double-quoted, interpolated string.
2253
2254 $_ .= qq
2255 (*** The previous line contains the naughty word "$1".\n)
19799a22 2256 if /\b(tcl|java|python)\b/i; # :-)
68dc0745 2257 $baz = "\n"; # a one-character string
a0d0e21e 2258
ba7f043c 2259=item C<qx/I<STRING>/>
d74e8afc 2260X<qx> X<`> X<``> X<backtick>
a0d0e21e 2261
ba7f043c 2262=item C<`I<STRING>`>
a0d0e21e 2263
43dd4d21 2264A string which is (possibly) interpolated and then executed as a
f703fc96 2265system command with F</bin/sh> or its equivalent. Shell wildcards,
43dd4d21
JH
2266pipes, and redirections will be honored. The collected standard
2267output of the command is returned; standard error is unaffected. In
2268scalar context, it comes back as a single (potentially multi-line)
ba7f043c
KW
2269string, or C<undef> if the command failed. In list context, returns a
2270list of lines (however you've defined lines with C<$/> or
2271C<$INPUT_RECORD_SEPARATOR>), or an empty list if the command failed.
5a964f20
TC
2272
2273Because backticks do not affect standard error, use shell file descriptor
2274syntax (assuming the shell supports this) if you care to address this.
2275To capture a command's STDERR and STDOUT together:
a0d0e21e 2276
5a964f20
TC
2277 $output = `cmd 2>&1`;
2278
2279To capture a command's STDOUT but discard its STDERR:
2280
2281 $output = `cmd 2>/dev/null`;
2282
2283To capture a command's STDERR but discard its STDOUT (ordering is
2284important here):
2285
2286 $output = `cmd 2>&1 1>/dev/null`;
2287
2288To exchange a command's STDOUT and STDERR in order to capture the STDERR
2289but leave its STDOUT to come out the old STDERR:
2290
2291 $output = `cmd 3>&1 1>&2 2>&3 3>&-`;
2292
2293To read both a command's STDOUT and its STDERR separately, it's easiest
2359510d
SD
2294to redirect them separately to files, and then read from those files
2295when the program is done:
5a964f20 2296
2359510d 2297 system("program args 1>program.stdout 2>program.stderr");
5a964f20 2298
30398227
SP
2299The STDIN filehandle used by the command is inherited from Perl's STDIN.
2300For example:
2301
c543c01b
TC
2302 open(SPLAT, "stuff") || die "can't open stuff: $!";
2303 open(STDIN, "<&SPLAT") || die "can't dupe SPLAT: $!";
40bbb707 2304 print STDOUT `sort`;
30398227 2305
40bbb707 2306will print the sorted contents of the file named F<"stuff">.
30398227 2307
5a964f20
TC
2308Using single-quote as a delimiter protects the command from Perl's
2309double-quote interpolation, passing it on to the shell instead:
2310
2311 $perl_info = qx(ps $$); # that's Perl's $$
2312 $shell_info = qx'ps $$'; # that's the new shell's $$
2313
19799a22 2314How that string gets evaluated is entirely subject to the command
5a964f20
TC
2315interpreter on your system. On most platforms, you will have to protect
2316shell metacharacters if you want them treated literally. This is in
2317practice difficult to do, as it's unclear how to escape which characters.
ba7f043c 2318See L<perlsec> for a clean and safe example of a manual C<fork()> and C<exec()>
5a964f20 2319to emulate backticks safely.
a0d0e21e 2320
bb32b41a
GS
2321On some platforms (notably DOS-like ones), the shell may not be
2322capable of dealing with multiline commands, so putting newlines in
2323the string may not get you what you want. You may be able to evaluate
2324multiple commands in a single line by separating them with the command
a727cfac 2325separator character, if your shell supports that (for example, C<;> on
1ca345ed 2326many Unix shells and C<&> on the Windows NT C<cmd> shell).
bb32b41a 2327
3ff8ecf9 2328Perl will attempt to flush all files opened for
0f897271
GS
2329output before starting the child process, but this may not be supported
2330on some platforms (see L<perlport>). To be safe, you may need to set
ba7f043c
KW
2331C<$|> (C<$AUTOFLUSH> in C<L<English>>) or call the C<autoflush()> method of
2332C<L<IO::Handle>> on any open handles.
0f897271 2333
bb32b41a
GS
2334Beware that some command shells may place restrictions on the length
2335of the command line. You must ensure your strings don't exceed this
2336limit after any necessary interpolations. See the platform-specific
2337release notes for more details about your particular environment.
2338
5a964f20
TC
2339Using this operator can lead to programs that are difficult to port,
2340because the shell commands called vary between systems, and may in
2341fact not be present at all. As one example, the C<type> command under
2342the POSIX shell is very different from the C<type> command under DOS.
2343That doesn't mean you should go out of your way to avoid backticks
2344when they're the right way to get something done. Perl was made to be
2345a glue language, and one of the things it glues together is commands.
2346Just understand what you're getting yourself into.
bb32b41a 2347
7cf4dd3e
DB
2348Like C<system>, backticks put the child process exit code in C<$?>.
2349If you'd like to manually inspect failure, you can check all possible
2350failure modes by inspecting C<$?> like this:
2351
2352 if ($? == -1) {
2353 print "failed to execute: $!\n";
2354 }
2355 elsif ($? & 127) {
2356 printf "child died with signal %d, %s coredump\n",
2357 ($? & 127), ($? & 128) ? 'with' : 'without';
2358 }
2359 else {
2360 printf "child exited with value %d\n", $? >> 8;
2361 }
2362
fe43a9cc
TC
2363Use the L<open> pragma to control the I/O layers used when reading the
2364output of the command, for example:
2365
2366 use open IN => ":encoding(UTF-8)";
2367 my $x = `cmd-producing-utf-8`;
2368
da87341d 2369See L</"I/O Operators"> for more discussion.
a0d0e21e 2370
ba7f043c 2371=item C<qw/I<STRING>/>
d74e8afc 2372X<qw> X<quote, list> X<quote, words>
945c54fd 2373
ba7f043c 2374Evaluates to a list of the words extracted out of I<STRING>, using embedded
945c54fd
JH
2375whitespace as the word delimiters. It can be understood as being roughly
2376equivalent to:
2377
c543c01b 2378 split(" ", q/STRING/);
945c54fd 2379
5a9c3bf4
Z
2380the differences being that it only splits on ASCII whitespace,
2381generates a real list at compile time, and
efb1e162 2382in scalar context it returns the last element in the list. So
945c54fd
JH
2383this expression:
2384
2385 qw(foo bar baz)
2386
2387is semantically equivalent to the list:
2388
c543c01b 2389 "foo", "bar", "baz"
945c54fd
JH
2390
2391Some frequently seen examples:
2392
2393 use POSIX qw( setlocale localeconv )
2394 @EXPORT = qw( foo bar baz );
2395
ba7f043c 2396A common mistake is to try to separate the words with commas or to
945c54fd 2397put comments into a multi-line C<qw>-string. For this reason, the
ba7f043c
KW
2398S<C<use warnings>> pragma and the B<-w> switch (that is, the C<$^W> variable)
2399produces warnings if the I<STRING> contains the C<","> or the C<"#"> character.
945c54fd 2400
ba7f043c 2401=item C<tr/I<SEARCHLIST>/I<REPLACEMENTLIST>/cdsr>
d74e8afc 2402X<tr> X<y> X<transliterate> X</c> X</d> X</s>
a0d0e21e 2403
ba7f043c 2404=item C<y/I<SEARCHLIST>/I<REPLACEMENTLIST>/cdsr>
a0d0e21e 2405
2c268ad5 2406Transliterates all occurrences of the characters found in the search list
a0d0e21e
LW
2407with the corresponding character in the replacement list. It returns
2408the number of characters replaced or deleted. If no string is
ba7f043c 2409specified via the C<=~> or C<!~> operator, the C<$_> string is transliterated.
c543c01b
TC
2410
2411If the C</r> (non-destructive) option is present, a new copy of the string
2412is made and its characters transliterated, and this copy is returned no
2413matter whether it was modified or not: the original string is always
2414left unchanged. The new copy is always a plain string, even if the input
2415string is an object or a tied variable.
8ada0baa 2416
c543c01b
TC
2417Unless the C</r> option is used, the string specified with C<=~> must be a
2418scalar variable, an array element, a hash element, or an assignment to one
2419of those; in other words, an lvalue.
8ff32507 2420
89d205f2 2421A character range may be specified with a hyphen, so C<tr/A-J/0-9/>
2c268ad5 2422does the same replacement as C<tr/ACEGIBDFHJ/0246813579/>.
54310121 2423For B<sed> devotees, C<y> is provided as a synonym for C<tr>. If the
af2cbe4d
KW
2424I<SEARCHLIST> is delimited by bracketing quotes, the I<REPLACEMENTLIST>
2425must have its own pair of quotes, which may or may not be bracketing
2426quotes; for example, C<tr[aeiouy][yuoiea]> or C<tr(+\-*/)/ABCD/>.
c543c01b 2427
ba7f043c 2428Characters may be literals or any of the escape sequences accepted in
6d314683
YO
2429double-quoted strings. But there is no variable interpolation, so C<"$">
2430and C<"@"> are treated as literals. A hyphen at the beginning or end, or
ba7f043c
KW
2431preceded by a backslash is considered a literal. Escape sequence
2432details are in L<the table near the beginning of this section|/Quote and
f4240379 2433Quote-like Operators>.
ba7f043c 2434
c543c01b 2435Note that C<tr> does B<not> do regular expression character classes such as
ba7f043c 2436C<\d> or C<\pL>. The C<tr> operator is not equivalent to the C<L<tr(1)>>
af2cbe4d
KW
2437utility. C<tr[a-z][A-Z]> will uppercase the 26 letters "a" through "z",
2438but for case changing not confined to ASCII, use
2439L<C<lc>|perlfunc/lc>, L<C<uc>|perlfunc/uc>,
2440L<C<lcfirst>|perlfunc/lcfirst>, L<C<ucfirst>|perlfunc/ucfirst>
2441(all documented in L<perlfunc>), or the
2442L<substitution operator C<sE<sol>I<PATTERN>E<sol>I<REPLACEMENT>E<sol>>|/sE<sol>PATTERNE<sol>REPLACEMENTE<sol>msixpodualngcer>
2443(with C<\U>, C<\u>, C<\L>, and C<\l> string-interpolation escapes in the
2444I<REPLACEMENT> portion).
cc255d5f 2445
f4240379
KW
2446Most ranges are unportable between character sets, but certain ones
2447signal Perl to do special handling to make them portable. There are two
2448classes of portable ranges. The first are any subsets of the ranges
2449C<A-Z>, C<a-z>, and C<0-9>, when expressed as literal characters.
2450
2451 tr/h-k/H-K/
2452
2453capitalizes the letters C<"h">, C<"i">, C<"j">, and C<"k"> and nothing
2454else, no matter what the platform's character set is. In contrast, all
2455of
2456
2457 tr/\x68-\x6B/\x48-\x4B/
2458 tr/h-\x6B/H-\x4B/
2459 tr/\x68-k/\x48-K/
2460
2461do the same capitalizations as the previous example when run on ASCII
2462platforms, but something completely different on EBCDIC ones.
2463
2464The second class of portable ranges is invoked when one or both of the
2465range's end points are expressed as C<\N{...}>
2466
2467 $string =~ tr/\N{U+20}-\N{U+7E}//d;
2468
2469removes from C<$string> all the platform's characters which are
2470equivalent to any of Unicode U+0020, U+0021, ... U+007D, U+007E. This
2471is a portable range, and has the same effect on every platform it is
2472run on. It turns out that in this example, these are the ASCII
2473printable characters. So after this is run, C<$string> has only
2474controls and characters which have no ASCII equivalents.
2475
2476But, even for portable ranges, it is not generally obvious what is
2477included without having to look things up. A sound principle is to use
2478only ranges that begin from and end at either ASCII alphabetics of equal
8df98a27 2479case (C<b-e>, C<B-E>), or digits (C<1-4>). Anything else is unclear
f4240379 2480(and unportable unless C<\N{...}> is used). If in doubt, spell out the
8ada0baa
JH
2481character sets in full.
2482
a0d0e21e
LW
2483Options:
2484
2485 c Complement the SEARCHLIST.
2486 d Delete found but unreplaced characters.
2487 s Squash duplicate replaced characters.
8ff32507
FC
2488 r Return the modified string and leave the original string
2489 untouched.
a0d0e21e 2490
ba7f043c 2491If the C</c> modifier is specified, the I<SEARCHLIST> character set
d503fd62
DM
2492is complemented. So for example these two are equivalent (the exact
2493maximum number will depend on your platform):
2494
2495 tr/\x00-\xfd/ABCD/c
2496 tr/\xfe-\x{7fffffff}/ABCD/
2497
2498If the C</d> modifier is specified, any characters
ba7f043c 2499specified by I<SEARCHLIST> not found in I<REPLACEMENTLIST> are deleted.
19799a22 2500(Note that this is slightly more flexible than the behavior of some
ba7f043c 2501B<tr> programs, which delete anything they find in the I<SEARCHLIST>,
d503fd62
DM
2502period.)
2503
2504If the C</s> modifier is specified, runs of the same character in the
2505result, where each those characters were substituted by the
2506transliteration, are squashed down to a single instance of the character.
a0d0e21e 2507
ba7f043c
KW
2508If the C</d> modifier is used, the I<REPLACEMENTLIST> is always interpreted
2509exactly as specified. Otherwise, if the I<REPLACEMENTLIST> is shorter
2510than the I<SEARCHLIST>, the final character is replicated till it is long
2511enough. If the I<REPLACEMENTLIST> is empty, the I<SEARCHLIST> is replicated.
a0d0e21e 2512This latter is useful for counting characters in a class or for
d503fd62
DM
2513squashing character sequences in a class. For example, each of these pairs
2514are equivalent:
a0d0e21e 2515
d503fd62
DM
2516 tr/abcd// tr/abcd/abcd/
2517 tr/abcd/AB/ tr/abcd/ABBB/
2518 tr/abcd//d s/[abcd]//g
2519 tr/abcd/AB/d (tr/ab/AB/ + s/[cd]//g) - but run together
2520
2521Some examples:
a0d0e21e 2522
c543c01b 2523 $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case ASCII
a0d0e21e
LW
2524
2525 $cnt = tr/*/*/; # count the stars in $_
2526
2527 $cnt = $sky =~ tr/*/*/; # count the stars in $sky
2528
2529 $cnt = tr/0-9//; # count the digits in $_
2530
2531 tr/a-zA-Z//s; # bookkeeper -> bokeper
2532
2533 ($HOST = $host) =~ tr/a-z/A-Z/;
c543c01b 2534 $HOST = $host =~ tr/a-z/A-Z/r; # same thing
8ff32507 2535
c543c01b 2536 $HOST = $host =~ tr/a-z/A-Z/r # chained with s///r
8ff32507 2537 =~ s/:/ -p/r;
a0d0e21e
LW
2538
2539 tr/a-zA-Z/ /cs; # change non-alphas to single space
2540
8ff32507
FC
2541 @stripped = map tr/a-zA-Z/ /csr, @original;
2542 # /r with map
2543
a0d0e21e 2544 tr [\200-\377]
c543c01b 2545 [\000-\177]; # wickedly delete 8th bit
a0d0e21e 2546
19799a22
GS
2547If multiple transliterations are given for a character, only the
2548first one is used:
748a9306
LW
2549
2550 tr/AAA/XYZ/
2551
2c268ad5 2552will transliterate any A to X.
748a9306 2553
19799a22 2554Because the transliteration table is built at compile time, neither
ba7f043c 2555the I<SEARCHLIST> nor the I<REPLACEMENTLIST> are subjected to double quote
19799a22 2556interpolation. That means that if you want to use variables, you
ba7f043c 2557must use an C<eval()>:
a0d0e21e
LW
2558
2559 eval "tr/$oldlist/$newlist/";
2560 die $@ if $@;
2561
2562 eval "tr/$oldlist/$newlist/, 1" or die $@;
2563
ba7f043c 2564=item C<< <<I<EOF> >>
d74e8afc 2565X<here-doc> X<heredoc> X<here-document> X<<< << >>>
7e3b091d
DA
2566
2567A line-oriented form of quoting is based on the shell "here-document"
2568syntax. Following a C<< << >> you specify a string to terminate
2569the quoted material, and all lines following the current line down to
89d205f2
YO
2570the terminating string are the value of the item.
2571
47eb4411
MH
2572Prefixing the terminating string with a C<~> specifies that you
2573want to use L</Indented Here-docs> (see below).
2574
89d205f2
YO
2575The terminating string may be either an identifier (a word), or some
2576quoted text. An unquoted identifier works like double quotes.
2577There may not be a space between the C<< << >> and the identifier,
2578unless the identifier is explicitly quoted. (If you put a space it
2579will be treated as a null identifier, which is valid, and matches the
2580first empty line.) The terminating string must appear by itself
2581(unquoted and with no surrounding whitespace) on the terminating line.
2582
2583If the terminating string is quoted, the type of quotes used determine
2584the treatment of the text.
2585
2586=over 4
2587
2588=item Double Quotes
2589
2590Double quotes indicate that the text will be interpolated using exactly
2591the same rules as normal double quoted strings.
7e3b091d
DA
2592
2593 print <<EOF;
2594 The price is $Price.
2595 EOF
2596
2597 print << "EOF"; # same as above
2598 The price is $Price.
2599 EOF
2600
89d205f2
YO
2601
2602=item Single Quotes
2603
2604Single quotes indicate the text is to be treated literally with no
46f8a5ea 2605interpolation of its content. This is similar to single quoted
89d205f2
YO
2606strings except that backslashes have no special meaning, with C<\\>
2607being treated as two backslashes and not one as they would in every
2608other quoting construct.
2609
c543c01b
TC
2610Just as in the shell, a backslashed bareword following the C<<< << >>>
2611means the same thing as a single-quoted string does:
2612
2613 $cost = <<'VISTA'; # hasta la ...
2614 That'll be $10 please, ma'am.
2615 VISTA
2616
2617 $cost = <<\VISTA; # Same thing!
2618 That'll be $10 please, ma'am.
2619 VISTA
2620
89d205f2
YO
2621This is the only form of quoting in perl where there is no need
2622to worry about escaping content, something that code generators
2623can and do make good use of.
2624
2625=item Backticks
2626
2627The content of the here doc is treated just as it would be if the
46f8a5ea 2628string were embedded in backticks. Thus the content is interpolated
89d205f2
YO
2629as though it were double quoted and then executed via the shell, with
2630the results of the execution returned.
2631
2632 print << `EOC`; # execute command and get results
7e3b091d 2633 echo hi there
7e3b091d
DA
2634 EOC
2635
89d205f2
YO
2636=back
2637
47eb4411
MH
2638=over 4
2639
2640=item Indented Here-docs
2641
2642The here-doc modifier C<~> allows you to indent your here-docs to make
2643the code more readable:
2644
2645 if ($some_var) {
2646 print <<~EOF;
2647 This is a here-doc
2648 EOF
2649 }
2650
2651This will print...
2652
2653 This is a here-doc
2654
2655...with no leading whitespace.
2656
2657The delimiter is used to determine the B<exact> whitespace to
2658remove from the beginning of each line. All lines B<must> have
2659at least the same starting whitespace (except lines only
2660containing a newline) or perl will croak. Tabs and spaces can
2661be mixed, but are matched exactly. One tab will not be equal to
26628 spaces!
2663
2664Additional beginning whitespace (beyond what preceded the
2665delimiter) will be preserved:
2666
2667 print <<~EOF;
2668 This text is not indented
2669 This text is indented with two spaces
2670 This text is indented with two tabs
2671 EOF
2672
2673Finally, the modifier may be used with all of the forms
2674mentioned above:
2675
2676 <<~\EOF;
2677 <<~'EOF'
2678 <<~"EOF"
2679 <<~`EOF`
2680
2681And whitespace may be used between the C<~> and quoted delimiters:
2682
2683 <<~ 'EOF'; # ... "EOF", `EOF`
2684
2685=back
2686
89d205f2
YO
2687It is possible to stack multiple here-docs in a row:
2688
7e3b091d
DA
2689 print <<"foo", <<"bar"; # you can stack them
2690 I said foo.
2691 foo
2692 I said bar.
2693 bar
2694
2695 myfunc(<< "THIS", 23, <<'THAT');
2696 Here's a line
2697 or two.
2698 THIS
2699 and here's another.
2700 THAT
2701
2702Just don't forget that you have to put a semicolon on the end
2703to finish the statement, as Perl doesn't know you're not going to
2704try to do this:
2705
2706 print <<ABC
2707 179231
2708 ABC
2709 + 20;
2710
872d7e53
ST
2711If you want to remove the line terminator from your here-docs,
2712use C<chomp()>.
2713
2714 chomp($string = <<'END');
2715 This is a string.
2716 END
2717
2718If you want your here-docs to be indented with the rest of the code,
377a7450 2719use the C<<< <<~FOO >>> construct described under L</Indented Here-docs>:
7e3b091d 2720
377a7450 2721 $quote = <<~'FINIS';
89d205f2 2722 The Road goes ever on and on,
7e3b091d 2723 down from the door where it began.
377a7450 2724 FINIS
7e3b091d
DA
2725
2726If you use a here-doc within a delimited construct, such as in C<s///eg>,
1bf48760
FC
2727the quoted material must still come on the line following the
2728C<<< <<FOO >>> marker, which means it may be inside the delimited
2729construct:
7e3b091d
DA
2730
2731 s/this/<<E . 'that'
2732 the other
2733 E
2734 . 'more '/eg;
2735
1bf48760
FC
2736It works this way as of Perl 5.18. Historically, it was inconsistent, and
2737you would have to write
7e3b091d 2738
89d205f2
YO
2739 s/this/<<E . 'that'
2740 . 'more '/eg;
2741 the other
2742 E
7e3b091d 2743
1bf48760
FC
2744outside of string evals.
2745
c543c01b 2746Additionally, quoting rules for the end-of-string identifier are
46f8a5ea 2747unrelated to Perl's quoting rules. C<q()>, C<qq()>, and the like are not
89d205f2
YO
2748supported in place of C<''> and C<"">, and the only interpolation is for
2749backslashing the quoting character:
7e3b091d
DA
2750
2751 print << "abc\"def";
2752 testing...
2753 abc"def
2754
2755Finally, quoted strings cannot span multiple lines. The general rule is
2756that the identifier must be a string literal. Stick with that, and you
2757should be safe.
2758
a0d0e21e
LW
2759=back
2760
75e14d17 2761=head2 Gory details of parsing quoted constructs
d74e8afc 2762X<quote, gory details>
75e14d17 2763
19799a22
GS
2764When presented with something that might have several different
2765interpretations, Perl uses the B<DWIM> (that's "Do What I Mean")
2766principle to pick the most probable interpretation. This strategy
2767is so successful that Perl programmers often do not suspect the
2768ambivalence of what they write. But from time to time, Perl's
2769notions differ substantially from what the author honestly meant.
2770
2771This section hopes to clarify how Perl handles quoted constructs.
2772Although the most common reason to learn this is to unravel labyrinthine
2773regular expressions, because the initial steps of parsing are the
2774same for all quoting operators, they are all discussed together.
2775
2776The most important Perl parsing rule is the first one discussed
2777below: when processing a quoted construct, Perl first finds the end
2778of that construct, then interprets its contents. If you understand
2779this rule, you may skip the rest of this section on the first
2780reading. The other rules are likely to contradict the user's
2781expectations much less frequently than this first one.
2782
2783Some passes discussed below are performed concurrently, but because
2784their results are the same, we consider them individually. For different
2785quoting constructs, Perl performs different numbers of passes, from
6deea57f 2786one to four, but these passes are always performed in the same order.
75e14d17 2787
13a2d996 2788=over 4
75e14d17
IZ
2789
2790=item Finding the end
2791
ba7f043c
KW
2792The first pass is finding the end of the quoted construct. This results
2793in saving to a safe location a copy of the text (between the starting
2794and ending delimiters), normalized as necessary to avoid needing to know
2795what the original delimiters were.
6deea57f
ST
2796
2797If the construct is a here-doc, the ending delimiter is a line
46f8a5ea 2798that has a terminating string as the content. Therefore C<<<EOF> is
6deea57f
ST
2799terminated by C<EOF> immediately followed by C<"\n"> and starting
2800from the first column of the terminating line.
2801When searching for the terminating line of a here-doc, nothing
46f8a5ea 2802is skipped. In other words, lines after the here-doc syntax
6deea57f
ST
2803are compared with the terminating string line by line.
2804
2805For the constructs except here-docs, single characters are used as starting
46f8a5ea 2806and ending delimiters. If the starting delimiter is an opening punctuation
6deea57f
ST
2807(that is C<(>, C<[>, C<{>, or C<< < >>), the ending delimiter is the
2808corresponding closing punctuation (that is C<)>, C<]>, C<}>, or C<< > >>).
2809If the starting delimiter is an unpaired character like C</> or a closing
ba7f043c 2810punctuation, the ending delimiter is the same as the starting delimiter.
6deea57f 2811Therefore a C</> terminates a C<qq//> construct, while a C<]> terminates
fc693347 2812both C<qq[]> and C<qq]]> constructs.
6deea57f
ST
2813
2814When searching for single-character delimiters, escaped delimiters
1ca345ed 2815and C<\\> are skipped. For example, while searching for terminating C</>,
6deea57f
ST
2816combinations of C<\\> and C<\/> are skipped. If the delimiters are
2817bracketing, nested pairs are also skipped. For example, while searching
ba7f043c 2818for a closing C<]> paired with the opening C<[>, combinations of C<\\>, C<\]>,
6deea57f
ST
2819and C<\[> are all skipped, and nested C<[> and C<]> are skipped as well.
2820However, when backslashes are used as the delimiters (like C<qq\\> and
2821C<tr\\\>), nothing is skipped.
32581033 2822During the search for the end, backslashes that escape delimiters or
7188ca43 2823other backslashes are removed (exactly speaking, they are not copied to the
32581033 2824safe location).
75e14d17 2825
19799a22
GS
2826For constructs with three-part delimiters (C<s///>, C<y///>, and
2827C<tr///>), the search is repeated once more.
fc693347 2828If the first delimiter is not an opening punctuation, the three delimiters must
d74605e5
FC
2829be the same, such as C<s!!!> and C<tr)))>,
2830in which case the second delimiter
6deea57f 2831terminates the left part and starts the right part at once.
b6538e4f 2832If the left part is delimited by bracketing punctuation (that is C<()>,
6deea57f 2833C<[]>, C<{}>, or C<< <> >>), the right part needs another pair of
b6538e4f 2834delimiters such as C<s(){}> and C<tr[]//>. In these cases, whitespace
ba7f043c 2835and comments are allowed between the two parts, although the comment must follow
a727cfac 2836at least one whitespace character; otherwise a character expected as the
b6538e4f 2837start of the comment may be regarded as the starting delimiter of the right part.
75e14d17 2838
19799a22
GS
2839During this search no attention is paid to the semantics of the construct.
2840Thus:
75e14d17
IZ
2841
2842 "$hash{"$foo/$bar"}"
2843
2a94b7ce 2844or:
75e14d17 2845
89d205f2 2846 m/
2a94b7ce 2847 bar # NOT a comment, this slash / terminated m//!
75e14d17
IZ
2848 /x
2849
19799a22
GS
2850do not form legal quoted expressions. The quoted part ends on the
2851first C<"> and C</>, and the rest happens to be a syntax error.
2852Because the slash that terminated C<m//> was followed by a C<SPACE>,
2853the example above is not C<m//x>, but rather C<m//> with no C</x>
2854modifier. So the embedded C<#> is interpreted as a literal C<#>.
75e14d17 2855
89d205f2 2856Also no attention is paid to C<\c\> (multichar control char syntax) during
46f8a5ea 2857this search. Thus the second C<\> in C<qq/\c\/> is interpreted as a part
89d205f2 2858of C<\/>, and the following C</> is not recognized as a delimiter.
0d594e51
ST
2859Instead, use C<\034> or C<\x1c> at the end of quoted constructs.
2860
75e14d17 2861=item Interpolation
d74e8afc 2862X<interpolation>
75e14d17 2863
19799a22 2864The next step is interpolation in the text obtained, which is now
89d205f2 2865delimiter-independent. There are multiple cases.
75e14d17 2866
13a2d996 2867=over 4
75e14d17 2868
89d205f2 2869=item C<<<'EOF'>
75e14d17
IZ
2870
2871No interpolation is performed.
6deea57f
ST
2872Note that the combination C<\\> is left intact, since escaped delimiters
2873are not available for here-docs.
75e14d17 2874
6deea57f 2875=item C<m''>, the pattern of C<s'''>
89d205f2 2876
6deea57f
ST
2877No interpolation is performed at this stage.
2878Any backslashed sequences including C<\\> are treated at the stage
2879to L</"parsing regular expressions">.
89d205f2 2880
6deea57f 2881=item C<''>, C<q//>, C<tr'''>, C<y'''>, the replacement of C<s'''>
75e14d17 2882
89d205f2 2883The only interpolation is removal of C<\> from pairs of C<\\>.
ba7f043c 2884Therefore C<"-"> in C<tr'''> and C<y'''> is treated literally
6deea57f
ST
2885as a hyphen and no character range is available.
2886C<\1> in the replacement of C<s'''> does not work as C<$1>.
89d205f2
YO
2887
2888=item C<tr///>, C<y///>
2889
6deea57f
ST
2890No variable interpolation occurs. String modifying combinations for
2891case and quoting such as C<\Q>, C<\U>, and C<\E> are not recognized.
2892The other escape sequences such as C<\200> and C<\t> and backslashed
2893characters such as C<\\> and C<\-> are converted to appropriate literals.
ba7f043c
KW
2894The character C<"-"> is treated specially and therefore C<\-> is treated
2895as a literal C<"-">.
75e14d17 2896
89d205f2 2897=item C<"">, C<``>, C<qq//>, C<qx//>, C<< <file*glob> >>, C<<<"EOF">
75e14d17 2898
628253b8 2899C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F> (possibly paired with C<\E>) are
19799a22 2900converted to corresponding Perl constructs. Thus, C<"$foo\Qbaz$bar">
ba7f043c 2901is converted to S<C<$foo . (quotemeta("baz" . $bar))>> internally.
6deea57f
ST
2902The other escape sequences such as C<\200> and C<\t> and backslashed
2903characters such as C<\\> and C<\-> are replaced with appropriate
2904expansions.
2a94b7ce 2905
19799a22
GS
2906Let it be stressed that I<whatever falls between C<\Q> and C<\E>>
2907is interpolated in the usual way. Something like C<"\Q\\E"> has
48cbae4f 2908no C<\E> inside. Instead, it has C<\Q>, C<\\>, and C<E>, so the
19799a22
GS
2909result is the same as for C<"\\\\E">. As a general rule, backslashes
2910between C<\Q> and C<\E> may lead to counterintuitive results. So,
2911C<"\Q\t\E"> is converted to C<quotemeta("\t")>, which is the same
2912as C<"\\\t"> (since TAB is not alphanumeric). Note also that:
2a94b7ce
IZ
2913
2914 $str = '\t';
2915 return "\Q$str";
2916
2917may be closer to the conjectural I<intention> of the writer of C<"\Q\t\E">.
2918
19799a22 2919Interpolated scalars and arrays are converted internally to the C<join> and
ba7f043c 2920C<"."> catenation operations. Thus, S<C<"$foo XXX '@arr'">> becomes:
75e14d17 2921
19799a22 2922 $foo . " XXX '" . (join $", @arr) . "'";
75e14d17 2923
19799a22 2924All operations above are performed simultaneously, left to right.
75e14d17 2925
ba7f043c 2926Because the result of S<C<"\Q I<STRING> \E">> has all metacharacters
19799a22 2927quoted, there is no way to insert a literal C<$> or C<@> inside a
ba7f043c 2928C<\Q\E> pair. If protected by C<\>, C<$> will be quoted to become
19799a22
GS
2929C<"\\\$">; if not, it is interpreted as the start of an interpolated
2930scalar.
75e14d17 2931
19799a22 2932Note also that the interpolation code needs to make a decision on
89d205f2 2933where the interpolated scalar ends. For instance, whether
ba7f043c 2934S<C<< "a $x -> {c}" >>> really means:
75e14d17 2935
db691027 2936 "a " . $x . " -> {c}";
75e14d17 2937
2a94b7ce 2938or:
75e14d17 2939
db691027 2940 "a " . $x -> {c};
75e14d17 2941
19799a22
GS
2942Most of the time, the longest possible text that does not include
2943spaces between components and which contains matching braces or
2944brackets. because the outcome may be determined by voting based
2945on heuristic estimators, the result is not strictly predictable.
2946Fortunately, it's usually correct for ambiguous cases.
75e14d17 2947
6deea57f 2948=item the replacement of C<s///>
75e14d17 2949
628253b8 2950Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F> and interpolation
6deea57f
ST
2951happens as with C<qq//> constructs.
2952
2953It is at this step that C<\1> is begrudgingly converted to C<$1> in
2954the replacement text of C<s///>, in order to correct the incorrigible
2955I<sed> hackers who haven't picked up the saner idiom yet. A warning
ba7f043c 2956is emitted if the S<C<use warnings>> pragma or the B<-w> command-line flag
6deea57f
ST
2957(that is, the C<$^W> variable) was set.
2958
9c6deb98 2959=item C<RE> in C<m?RE?>, C</RE/>, C<m/RE/>, C<s/RE/foo/>,
6deea57f 2960
628253b8 2961Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F>, C<\E>,
cc74c5bd
ST
2962and interpolation happens (almost) as with C<qq//> constructs.
2963
5d03b57c
KW
2964Processing of C<\N{...}> is also done here, and compiled into an intermediate
2965form for the regex compiler. (This is because, as mentioned below, the regex
2966compilation may be done at execution time, and C<\N{...}> is a compile-time
2967construct.)
2968
cc74c5bd
ST
2969However any other combinations of C<\> followed by a character
2970are not substituted but only skipped, in order to parse them
2971as regular expressions at the following step.
6deea57f 2972As C<\c> is skipped at this step, C<@> of C<\c@> in RE is possibly
1749ea0d 2973treated as an array symbol (for example C<@foo>),
6deea57f 2974even though the same text in C<qq//> gives interpolation of C<\c@>.
6deea57f 2975
e128ab2c
DM
2976Code blocks such as C<(?{BLOCK})> are handled by temporarily passing control
2977back to the perl parser, in a similar way that an interpolated array
2978subscript expression such as C<"foo$array[1+f("[xyz")]bar"> would be.
2979
ba7f043c
KW
2980Moreover, inside C<(?{BLOCK})>, S<C<(?# comment )>>, and
2981a C<#>-comment in a C</x>-regular expression, no processing is
19799a22 2982performed whatsoever. This is the first step at which the presence
ba7f043c 2983of the C</x> modifier is relevant.
19799a22 2984
1749ea0d
ST
2985Interpolation in patterns has several quirks: C<$|>, C<$(>, C<$)>, C<@+>
2986and C<@-> are not interpolated, and constructs C<$var[SOMETHING]> are
2987voted (by several different estimators) to be either an array element
2988or C<$var> followed by an RE alternative. This is where the notation
19799a22
GS
2989C<${arr[$bar]}> comes handy: C</${arr[0-9]}/> is interpreted as
2990array element C<-9>, not as a regular expression from the variable
2991C<$arr> followed by a digit, which would be the interpretation of
2992C</$arr[0-9]/>. Since voting among different estimators may occur,
2993the result is not predictable.
2994
19799a22
GS
2995The lack of processing of C<\\> creates specific restrictions on
2996the post-processed text. If the delimiter is C</>, one cannot get
2997the combination C<\/> into the result of this step. C</> will
2998finish the regular expression, C<\/> will be stripped to C</> on
2999the previous step, and C<\\/> will be left as is. Because C</> is
3000equivalent to C<\/> inside a regular expression, this does not
3001matter unless the delimiter happens to be character special to the
9c6deb98 3002RE engine, such as in C<s*foo*bar*>, C<m[foo]>, or C<m?foo?>; or an
19799a22 3003alphanumeric char, as in:
2a94b7ce
IZ
3004
3005 m m ^ a \s* b mmx;
3006
19799a22 3007In the RE above, which is intentionally obfuscated for illustration, the
6deea57f 3008delimiter is C<m>, the modifier is C<mx>, and after delimiter-removal the
ba7f043c 3009RE is the same as for S<C<m/ ^ a \s* b /mx>>. There's more than one
19799a22
GS
3010reason you're encouraged to restrict your delimiters to non-alphanumeric,
3011non-whitespace choices.
75e14d17
IZ
3012
3013=back
3014
19799a22 3015This step is the last one for all constructs except regular expressions,
75e14d17
IZ
3016which are processed further.
3017
6deea57f
ST
3018=item parsing regular expressions
3019X<regexp, parse>
75e14d17 3020
19799a22 3021Previous steps were performed during the compilation of Perl code,
ac036724 3022but this one happens at run time, although it may be optimized to
19799a22 3023be calculated at compile time if appropriate. After preprocessing
6deea57f 3024described above, and possibly after evaluation if concatenation,
19799a22
GS
3025joining, casing translation, or metaquoting are involved, the
3026resulting I<string> is passed to the RE engine for compilation.
3027
3028Whatever happens in the RE engine might be better discussed in L<perlre>,
3029but for the sake of continuity, we shall do so here.
3030
ba7f043c 3031This is another step where the presence of the C</x> modifier is
19799a22 3032relevant. The RE engine scans the string from left to right and
ba7f043c 3033converts it into a finite automaton.
19799a22
GS
3034
3035Backslashed characters are either replaced with corresponding
3036literal strings (as with C<\{>), or else they generate special nodes
3037in the finite automaton (as with C<\b>). Characters special to the
3038RE engine (such as C<|>) generate corresponding nodes or groups of
3039nodes. C<(?#...)> comments are ignored. All the rest is either
3040converted to literal strings to match, or else is ignored (as is
ba7f043c 3041whitespace and C<#>-style comments if C</x> is present).
19799a22
GS
3042
3043Parsing of the bracketed character class construct, C<[...]>, is
3044rather different than the rule used for the rest of the pattern.
3045The terminator of this construct is found using the same rules as
3046for finding the terminator of a C<{}>-delimited construct, the only
3047exception being that C<]> immediately following C<[> is treated as
e128ab2c
DM
3048though preceded by a backslash.
3049
3050The terminator of runtime C<(?{...})> is found by temporarily switching
3051control to the perl parser, which should stop at the point where the
3052logically balancing terminating C<}> is found.
19799a22
GS
3053
3054It is possible to inspect both the string given to RE engine and the
3055resulting finite automaton. See the arguments C<debug>/C<debugcolor>
ba7f043c 3056in the S<C<use L<re>>> pragma, as well as Perl's B<-Dr> command-line
4a4eefd0 3057switch documented in L<perlrun/"Command Switches">.
75e14d17
IZ
3058
3059=item Optimization of regular expressions
d74e8afc 3060X<regexp, optimization>
75e14d17 3061
7522fed5 3062This step is listed for completeness only. Since it does not change
75e14d17 3063semantics, details of this step are not documented and are subject
19799a22
GS
3064to change without notice. This step is performed over the finite
3065automaton that was generated during the previous pass.
2a94b7ce 3066
19799a22
GS
3067It is at this stage that C<split()> silently optimizes C</^/> to
3068mean C</^/m>.
75e14d17
IZ
3069
3070=back
3071
a0d0e21e 3072=head2 I/O Operators
d74e8afc 3073X<operator, i/o> X<operator, io> X<io> X<while> X<filehandle>
80a96bfc 3074X<< <> >> X<< <<>> >> X<@ARGV>
a0d0e21e 3075
54310121 3076There are several I/O operators you should know about.
fbad3eb5 3077
7b8d334a 3078A string enclosed by backticks (grave accents) first undergoes
19799a22
GS
3079double-quote interpolation. It is then interpreted as an external
3080command, and the output of that command is the value of the
e9c56f9b
JH
3081backtick string, like in a shell. In scalar context, a single string
3082consisting of all output is returned. In list context, a list of
3083values is returned, one per line of output. (You can set C<$/> to use
3084a different line terminator.) The command is executed each time the
3085pseudo-literal is evaluated. The status value of the command is
3086returned in C<$?> (see L<perlvar> for the interpretation of C<$?>).
3087Unlike in B<csh>, no translation is done on the return data--newlines
3088remain newlines. Unlike in any of the shells, single quotes do not
3089hide variable names in the command from interpretation. To pass a
3090literal dollar-sign through to the shell you need to hide it with a
3091backslash. The generalized form of backticks is C<qx//>. (Because
3092backticks always undergo shell expansion as well, see L<perlsec> for
3093security concerns.)
d74e8afc 3094X<qx> X<`> X<``> X<backtick> X<glob>
19799a22
GS
3095
3096In scalar context, evaluating a filehandle in angle brackets yields
3097the next line from that file (the newline, if any, included), or
3098C<undef> at end-of-file or on error. When C<$/> is set to C<undef>
3099(sometimes known as file-slurp mode) and the file is empty, it
3100returns C<''> the first time, followed by C<undef> subsequently.
3101
3102Ordinarily you must assign the returned value to a variable, but
3103there is one situation where an automatic assignment happens. If
3104and only if the input symbol is the only thing inside the conditional
3105of a C<while> statement (even if disguised as a C<for(;;)> loop),
ba7f043c 3106the value is automatically assigned to the global variable C<$_>,
19799a22
GS
3107destroying whatever was there previously. (This may seem like an
3108odd thing to you, but you'll use the construct in almost every Perl
ba7f043c
KW
3109script you write.) The C<$_> variable is not implicitly localized.
3110You'll have to put a S<C<local $_;>> before the loop if you want that
5e979393
Z
3111to happen. Furthermore, if the input symbol or an explicit assignment
3112of the input symbol to a scalar is used as a C<while>/C<for> condition,
3113then the condition actually tests for definedness of the expression's
3114value, not for its regular truth value.
19799a22 3115
5e979393 3116Thus the following lines are equivalent:
a0d0e21e 3117
748a9306 3118 while (defined($_ = <STDIN>)) { print; }
7b8d334a 3119 while ($_ = <STDIN>) { print; }
a0d0e21e
LW
3120 while (<STDIN>) { print; }
3121 for (;<STDIN>;) { print; }
748a9306 3122 print while defined($_ = <STDIN>);
7b8d334a 3123 print while ($_ = <STDIN>);
a0d0e21e
LW
3124 print while <STDIN>;
3125
a727cfac 3126This also behaves similarly, but assigns to a lexical variable
1ca345ed 3127instead of to C<$_>:
7b8d334a 3128
89d205f2 3129 while (my $line = <STDIN>) { print $line }
7b8d334a 3130
19799a22
GS
3131In these loop constructs, the assigned value (whether assignment
3132is automatic or explicit) is then tested to see whether it is
1ca345ed
TC
3133defined. The defined test avoids problems where the line has a string
3134value that would be treated as false by Perl; for example a "" or
ba7f043c 3135a C<"0"> with no trailing newline. If you really mean for such values
19799a22 3136to terminate the loop, they should be tested for explicitly:
7b8d334a
GS
3137
3138 while (($_ = <STDIN>) ne '0') { ... }
3139 while (<STDIN>) { last unless $_; ... }
3140
ba7f043c 3141In other boolean contexts, C<< <I<FILEHANDLE>> >> without an
5ef4d93e 3142explicit C<defined> test or comparison elicits a warning if the
ba7f043c 3143S<C<use warnings>> pragma or the B<-w>
19799a22 3144command-line switch (the C<$^W> variable) is in effect.
7b8d334a 3145
5f05dabc 3146The filehandles STDIN, STDOUT, and STDERR are predefined. (The
19799a22
GS
3147filehandles C<stdin>, C<stdout>, and C<stderr> will also work except
3148in packages, where they would be interpreted as local identifiers
3149rather than global.) Additional filehandles may be created with
ba7f043c 3150the C<open()> function, amongst others. See L<perlopentut> and
19799a22 3151L<perlfunc/open> for details on this.
d74e8afc 3152X<stdin> X<stdout> X<sterr>
a0d0e21e 3153
ba7f043c 3154If a C<< <I<FILEHANDLE>> >> is used in a context that is looking for
19799a22
GS
3155a list, a list comprising all input lines is returned, one line per
3156list element. It's easy to grow to a rather large data space this
3157way, so use with care.
a0d0e21e 3158
ba7f043c 3159C<< <I<FILEHANDLE>> >> may also be spelled C<readline(*I<FILEHANDLE>)>.
19799a22 3160See L<perlfunc/readline>.
fbad3eb5 3161
ba7f043c 3162The null filehandle C<< <> >> is special: it can be used to emulate the
1ca345ed
TC
3163behavior of B<sed> and B<awk>, and any other Unix filter program
3164that takes a list of filenames, doing the same to each line
ba7f043c 3165of input from all of them. Input from C<< <> >> comes either from
a0d0e21e 3166standard input, or from each file listed on the command line. Here's
ba7f043c
KW
3167how it works: the first time C<< <> >> is evaluated, the C<@ARGV> array is
3168checked, and if it is empty, C<$ARGV[0]> is set to C<"-">, which when opened
3169gives you standard input. The C<@ARGV> array is then processed as a list
a0d0e21e
LW
3170of filenames. The loop
3171
3172 while (<>) {
3173 ... # code for each line
3174 }
3175
3176is equivalent to the following Perl-like pseudo code:
3177
3e3baf6d 3178 unshift(@ARGV, '-') unless @ARGV;
a0d0e21e
LW
3179 while ($ARGV = shift) {
3180 open(ARGV, $ARGV);
3181 while (<ARGV>) {
3182 ... # code for each line
3183 }
3184 }
3185
19799a22 3186except that it isn't so cumbersome to say, and will actually work.
ba7f043c
KW
3187It really does shift the C<@ARGV> array and put the current filename
3188into the C<$ARGV> variable. It also uses filehandle I<ARGV>
3189internally. C<< <> >> is just a synonym for C<< <ARGV> >>, which
19799a22 3190is magical. (The pseudo code above doesn't work because it treats
ba7f043c 3191C<< <ARGV> >> as non-magical.)
a0d0e21e 3192
48ab5743
ML
3193Since the null filehandle uses the two argument form of L<perlfunc/open>
3194it interprets special characters, so if you have a script like this:
3195
3196 while (<>) {
3197 print;
3198 }
3199
ba7f043c 3200and call it with S<C<perl dangerous.pl 'rm -rfv *|'>>, it actually opens a
48ab5743
ML
3201pipe, executes the C<rm> command and reads C<rm>'s output from that pipe.
3202If you want all items in C<@ARGV> to be interpreted as file names, you
1033ba6e
PM
3203can use the module C<ARGV::readonly> from CPAN, or use the double bracket:
3204
3205 while (<<>>) {
3206 print;
3207 }
3208
3209Using double angle brackets inside of a while causes the open to use the
3210three argument form (with the second argument being C<< < >>), so all
ba7f043c
KW
3211arguments in C<ARGV> are treated as literal filenames (including C<"-">).
3212(Note that for convenience, if you use C<< <<>> >> and if C<@ARGV> is
80a96bfc 3213empty, it will still read from the standard input.)
48ab5743 3214
ba7f043c 3215You can modify C<@ARGV> before the first C<< <> >> as long as the array ends up
a0d0e21e 3216containing the list of filenames you really want. Line numbers (C<$.>)
19799a22
GS
3217continue as though the input were one big happy file. See the example
3218in L<perlfunc/eof> for how to reset line numbers on each file.
5a964f20 3219
ba7f043c
KW
3220If you want to set C<@ARGV> to your own list of files, go right ahead.
3221This sets C<@ARGV> to all plain text files if no C<@ARGV> was given:
5a964f20
TC
3222
3223 @ARGV = grep { -f && -T } glob('*') unless @ARGV;
a0d0e21e 3224
5a964f20
TC
3225You can even set them to pipe commands. For example, this automatically
3226filters compressed arguments through B<gzip>:
3227
3228 @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc < $_ |" : $_ } @ARGV;
3229
3230If you want to pass switches into your script, you can use one of the
ba7f043c 3231C<Getopts> modules or put a loop on the front like this:
a0d0e21e
LW
3232
3233 while ($_ = $ARGV[0], /^-/) {
3234 shift;
3235 last if /^--$/;
3236 if (/^-D(.*)/) { $debug = $1 }
3237 if (/^-v/) { $verbose++ }
5a964f20 3238 # ... # other switches
a0d0e21e 3239 }
5a964f20 3240
a0d0e21e 3241 while (<>) {
5a964f20 3242 # ... # code for each line
a0d0e21e
LW
3243 }
3244
ba7f043c 3245The C<< <> >> symbol will return C<undef> for end-of-file only once.
89d205f2 3246If you call it again after this, it will assume you are processing another
ba7f043c 3247C<@ARGV> list, and if you haven't set C<@ARGV>, will read input from STDIN.
a0d0e21e 3248
1ca345ed 3249If what the angle brackets contain is a simple scalar variable (for example,
ba7f043c 3250C<$foo>), then that variable contains the name of the
19799a22
GS
3251filehandle to input from, or its typeglob, or a reference to the
3252same. For example:
cb1a09d0
AD
3253
3254 $fh = \*STDIN;
3255 $line = <$fh>;
a0d0e21e 3256
5a964f20
TC
3257If what's within the angle brackets is neither a filehandle nor a simple
3258scalar variable containing a filehandle name, typeglob, or typeglob
3259reference, it is interpreted as a filename pattern to be globbed, and
3260either a list of filenames or the next filename in the list is returned,
19799a22 3261depending on context. This distinction is determined on syntactic
ba7f043c
KW
3262grounds alone. That means C<< <$x> >> is always a C<readline()> from
3263an indirect handle, but C<< <$hash{key}> >> is always a C<glob()>.
3264That's because C<$x> is a simple scalar variable, but C<$hash{key}> is
ef191992
YST
3265not--it's a hash element. Even C<< <$x > >> (note the extra space)
3266is treated as C<glob("$x ")>, not C<readline($x)>.
5a964f20
TC
3267
3268One level of double-quote interpretation is done first, but you can't
35f2feb0 3269say C<< <$foo> >> because that's an indirect filehandle as explained
5a964f20
TC
3270in the previous paragraph. (In older versions of Perl, programmers
3271would insert curly brackets to force interpretation as a filename glob:
35f2feb0 3272C<< <${foo}> >>. These days, it's considered cleaner to call the
5a964f20 3273internal function directly as C<glob($foo)>, which is probably the right
19799a22 3274way to have done it in the first place.) For example:
a0d0e21e
LW
3275
3276 while (<*.c>) {