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