This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add indented here-docs.
[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
1077If the initial value specified isn't part of a magical increment
c543c01b 1078sequence (that is, a non-empty string matching C</^[a-zA-Z]*[0-9]*\z/>),
ea4f5703
YST
1079only the initial value will be returned. So the following will only
1080return an alpha:
1081
c543c01b 1082 use charnames "greek";
ea4f5703
YST
1083 my @greek_small = ("\N{alpha}" .. "\N{omega}");
1084
c543c01b
TC
1085To get the 25 traditional lowercase Greek letters, including both sigmas,
1086you could use this instead:
ea4f5703 1087
c543c01b 1088 use charnames "greek";
1ca345ed
TC
1089 my @greek_small = map { chr } ( ord("\N{alpha}")
1090 ..
1091 ord("\N{omega}")
1092 );
c543c01b
TC
1093
1094However, because there are I<many> other lowercase Greek characters than
1095just those, to match lowercase Greek characters in a regular expression,
47c56cc8
KW
1096you could use the pattern C</(?:(?=\p{Greek})\p{Lower})+/> (or the
1097L<experimental feature|perlrecharclass/Extended Bracketed Character
1098Classes> C<S</(?[ \p{Greek} & \p{Lower} ])+/>>).
a0d0e21e 1099
ba7f043c 1100Because each operand is evaluated in integer form, S<C<2.18 .. 3.14>> will
df5f8116
CW
1101return two elements in list context.
1102
1103 @list = (2.18 .. 3.14); # same as @list = (2 .. 3);
1104
a0d0e21e 1105=head2 Conditional Operator
d74e8afc 1106X<operator, conditional> X<operator, ternary> X<ternary> X<?:>
a0d0e21e 1107
ba7f043c
KW
1108Ternary C<"?:"> is the conditional operator, just as in C. It works much
1109like an if-then-else. If the argument before the C<?> is true, the
1110argument before the C<:> is returned, otherwise the argument after the
1111C<:> is returned. For example:
cb1a09d0 1112
54310121 1113 printf "I have %d dog%s.\n", $n,
c543c01b 1114 ($n == 1) ? "" : "s";
cb1a09d0
AD
1115
1116Scalar or list context propagates downward into the 2nd
54310121 1117or 3rd argument, whichever is selected.
cb1a09d0 1118
db691027
SF
1119 $x = $ok ? $y : $z; # get a scalar
1120 @x = $ok ? @y : @z; # get an array
1121 $x = $ok ? @y : @z; # oops, that's just a count!
cb1a09d0
AD
1122
1123The operator may be assigned to if both the 2nd and 3rd arguments are
1124legal lvalues (meaning that you can assign to them):
a0d0e21e 1125
db691027 1126 ($x_or_y ? $x : $y) = $z;
a0d0e21e 1127
5a964f20
TC
1128Because this operator produces an assignable result, using assignments
1129without parentheses will get you in trouble. For example, this:
1130
db691027 1131 $x % 2 ? $x += 10 : $x += 2
5a964f20
TC
1132
1133Really means this:
1134
db691027 1135 (($x % 2) ? ($x += 10) : $x) += 2
5a964f20
TC
1136
1137Rather than this:
1138
db691027 1139 ($x % 2) ? ($x += 10) : ($x += 2)
5a964f20 1140
19799a22
GS
1141That should probably be written more simply as:
1142
db691027 1143 $x += ($x % 2) ? 10 : 2;
19799a22 1144
4633a7c4 1145=head2 Assignment Operators
d74e8afc 1146X<assignment> X<operator, assignment> X<=> X<**=> X<+=> X<*=> X<&=>
5ac3b81c 1147X<<< <<= >>> X<&&=> X<-=> X</=> X<|=> X<<< >>= >>> X<||=> X<//=> X<.=>
fb7054ba 1148X<%=> X<^=> X<x=> X<&.=> X<|.=> X<^.=>
a0d0e21e 1149
ba7f043c 1150C<"="> is the ordinary assignment operator.
a0d0e21e
LW
1151
1152Assignment operators work as in C. That is,
1153
db691027 1154 $x += 2;
a0d0e21e
LW
1155
1156is equivalent to
1157
db691027 1158 $x = $x + 2;
a0d0e21e
LW
1159
1160although without duplicating any side effects that dereferencing the lvalue
ba7f043c 1161might trigger, such as from C<tie()>. Other assignment operators work similarly.
54310121 1162The following are recognized:
a0d0e21e 1163
fb7054ba
FC
1164 **= += *= &= &.= <<= &&=
1165 -= /= |= |.= >>= ||=
1166 .= %= ^= ^.= //=
9f10b797 1167 x=
a0d0e21e 1168
19799a22 1169Although these are grouped by family, they all have the precedence
82848c10
FC
1170of assignment. These combined assignment operators can only operate on
1171scalars, whereas the ordinary assignment operator can assign to arrays,
1172hashes, lists and even references. (See L<"Context"|perldata/Context>
1173and L<perldata/List value constructors>, and L<perlref/Assigning to
1174References>.)
a0d0e21e 1175
b350dd2f
GS
1176Unlike in C, the scalar assignment operator produces a valid lvalue.
1177Modifying an assignment is equivalent to doing the assignment and
1178then modifying the variable that was assigned to. This is useful
1179for modifying a copy of something, like this:
a0d0e21e 1180
1ca345ed
TC
1181 ($tmp = $global) =~ tr/13579/24680/;
1182
1183Although as of 5.14, that can be also be accomplished this way:
1184
1185 use v5.14;
1186 $tmp = ($global =~ tr/13579/24680/r);
a0d0e21e
LW
1187
1188Likewise,
1189
db691027 1190 ($x += 2) *= 3;
a0d0e21e
LW
1191
1192is equivalent to
1193
db691027
SF
1194 $x += 2;
1195 $x *= 3;
a0d0e21e 1196
b350dd2f
GS
1197Similarly, a list assignment in list context produces the list of
1198lvalues assigned to, and a list assignment in scalar context returns
1199the number of elements produced by the expression on the right hand
1200side of the assignment.
1201
ba7f043c 1202The three dotted bitwise assignment operators (C<&.=> C<|.=> C<^.=>) are new in
fb7054ba
FC
1203Perl 5.22 and experimental. See L</Bitwise String Operators>.
1204
748a9306 1205=head2 Comma Operator
d74e8afc 1206X<comma> X<operator, comma> X<,>
a0d0e21e 1207
ba7f043c 1208Binary C<","> is the comma operator. In scalar context it evaluates
a0d0e21e
LW
1209its left argument, throws that value away, then evaluates its right
1210argument and returns that value. This is just like C's comma operator.
1211
5a964f20 1212In list context, it's just the list argument separator, and inserts
ed5c6d31
PJ
1213both its arguments into the list. These arguments are also evaluated
1214from left to right.
a0d0e21e 1215
ba7f043c
KW
1216The C<< => >> operator (sometimes pronounced "fat comma") is a synonym
1217for the comma except that it causes a
4e1988c6 1218word on its left to be interpreted as a string if it begins with a letter
344f2c40
IG
1219or underscore and is composed only of letters, digits and underscores.
1220This includes operands that might otherwise be interpreted as operators,
46f8a5ea 1221constants, single number v-strings or function calls. If in doubt about
c543c01b 1222this behavior, the left operand can be quoted explicitly.
344f2c40
IG
1223
1224Otherwise, the C<< => >> operator behaves exactly as the comma operator
1225or list argument separator, according to context.
1226
1227For example:
a44e5664
MS
1228
1229 use constant FOO => "something";
1230
1231 my %h = ( FOO => 23 );
1232
1233is equivalent to:
1234
1235 my %h = ("FOO", 23);
1236
1237It is I<NOT>:
1238
1239 my %h = ("something", 23);
1240
719b43e8
RGS
1241The C<< => >> operator is helpful in documenting the correspondence
1242between keys and values in hashes, and other paired elements in lists.
748a9306 1243
a12b8f3c
FC
1244 %hash = ( $key => $value );
1245 login( $username => $password );
a44e5664 1246
4e1988c6
FC
1247The special quoting behavior ignores precedence, and hence may apply to
1248I<part> of the left operand:
1249
1250 print time.shift => "bbb";
1251
ba7f043c 1252That example prints something like C<"1314363215shiftbbb">, because the
4e1988c6
FC
1253C<< => >> implicitly quotes the C<shift> immediately on its left, ignoring
1254the fact that C<time.shift> is the entire left operand.
1255
a0d0e21e 1256=head2 List Operators (Rightward)
d74e8afc 1257X<operator, list, rightward> X<list operator>
a0d0e21e 1258
c543c01b 1259On the right side of a list operator, the comma has very low precedence,
a0d0e21e
LW
1260such that it controls all comma-separated expressions found there.
1261The only operators with lower precedence are the logical operators
ba7f043c 1262C<"and">, C<"or">, and C<"not">, which may be used to evaluate calls to list
1ca345ed
TC
1263operators without the need for parentheses:
1264
1265 open HANDLE, "< :utf8", "filename" or die "Can't open: $!\n";
1266
1267However, some people find that code harder to read than writing
1268it with parentheses:
1269
1270 open(HANDLE, "< :utf8", "filename") or die "Can't open: $!\n";
1271
ba7f043c 1272in which case you might as well just use the more customary C<"||"> operator:
a0d0e21e 1273
1ca345ed 1274 open(HANDLE, "< :utf8", "filename") || die "Can't open: $!\n";
a0d0e21e 1275
a95b3d6a 1276See also discussion of list operators in L</Terms and List Operators (Leftward)>.
a0d0e21e
LW
1277
1278=head2 Logical Not
d74e8afc 1279X<operator, logical, not> X<not>
a0d0e21e 1280
ba7f043c
KW
1281Unary C<"not"> returns the logical negation of the expression to its right.
1282It's the equivalent of C<"!"> except for the very low precedence.
a0d0e21e
LW
1283
1284=head2 Logical And
d74e8afc 1285X<operator, logical, and> X<and>
a0d0e21e 1286
ba7f043c 1287Binary C<"and"> returns the logical conjunction of the two surrounding
c543c01b
TC
1288expressions. It's equivalent to C<&&> except for the very low
1289precedence. This means that it short-circuits: the right
a0d0e21e
LW
1290expression is evaluated only if the left expression is true.
1291
59ab9d6e 1292=head2 Logical or and Exclusive Or
f23102e2 1293X<operator, logical, or> X<operator, logical, xor>
59ab9d6e 1294X<operator, logical, exclusive or>
f23102e2 1295X<or> X<xor>
a0d0e21e 1296
ba7f043c 1297Binary C<"or"> returns the logical disjunction of the two surrounding
c543c01b
TC
1298expressions. It's equivalent to C<||> except for the very low precedence.
1299This makes it useful for control flow:
5a964f20
TC
1300
1301 print FH $data or die "Can't write to FH: $!";
1302
c543c01b
TC
1303This means that it short-circuits: the right expression is evaluated
1304only if the left expression is false. Due to its precedence, you must
1305be careful to avoid using it as replacement for the C<||> operator.
1306It usually works out better for flow control than in assignments:
5a964f20 1307
db691027
SF
1308 $x = $y or $z; # bug: this is wrong
1309 ($x = $y) or $z; # really means this
1310 $x = $y || $z; # better written this way
5a964f20 1311
19799a22 1312However, when it's a list-context assignment and you're trying to use
ba7f043c 1313C<||> for control flow, you probably need C<"or"> so that the assignment
5a964f20
TC
1314takes higher precedence.
1315
1316 @info = stat($file) || die; # oops, scalar sense of stat!
1317 @info = stat($file) or die; # better, now @info gets its due
1318
c963b151
BD
1319Then again, you could always use parentheses.
1320
ba7f043c 1321Binary C<"xor"> returns the exclusive-OR of the two surrounding expressions.
c543c01b 1322It cannot short-circuit (of course).
a0d0e21e 1323
59ab9d6e
MB
1324There is no low precedence operator for defined-OR.
1325
a0d0e21e 1326=head2 C Operators Missing From Perl
d74e8afc
ITB
1327X<operator, missing from perl> X<&> X<*>
1328X<typecasting> X<(TYPE)>
a0d0e21e
LW
1329
1330Here is what C has that Perl doesn't:
1331
1332=over 8
1333
1334=item unary &
1335
ba7f043c 1336Address-of operator. (But see the C<"\"> operator for taking a reference.)
a0d0e21e
LW
1337
1338=item unary *
1339
46f8a5ea 1340Dereference-address operator. (Perl's prefix dereferencing
ba7f043c 1341operators are typed: C<$>, C<@>, C<%>, and C<&>.)
a0d0e21e
LW
1342
1343=item (TYPE)
1344
19799a22 1345Type-casting operator.
a0d0e21e
LW
1346
1347=back
1348
5f05dabc 1349=head2 Quote and Quote-like Operators
89d205f2 1350X<operator, quote> X<operator, quote-like> X<q> X<qq> X<qx> X<qw> X<m>
d74e8afc
ITB
1351X<qr> X<s> X<tr> X<'> X<''> X<"> X<""> X<//> X<`> X<``> X<<< << >>>
1352X<escape sequence> X<escape>
1353
a0d0e21e
LW
1354While we usually think of quotes as literal values, in Perl they
1355function as operators, providing various kinds of interpolating and
1356pattern matching capabilities. Perl provides customary quote characters
1357for these behaviors, but also provides a way for you to choose your
1358quote character for any of them. In the following table, a C<{}> represents
9f10b797 1359any pair of delimiters you choose.
a0d0e21e 1360
2c268ad5
TP
1361 Customary Generic Meaning Interpolates
1362 '' q{} Literal no
1363 "" qq{} Literal yes
af9219ee 1364 `` qx{} Command yes*
2c268ad5 1365 qw{} Word list no
af9219ee
MG
1366 // m{} Pattern match yes*
1367 qr{} Pattern yes*
1368 s{}{} Substitution yes*
2c268ad5 1369 tr{}{} Transliteration no (but see below)
c543c01b 1370 y{}{} Transliteration no (but see below)
7e3b091d 1371 <<EOF here-doc yes*
a0d0e21e 1372
af9219ee
MG
1373 * unless the delimiter is ''.
1374
87275199 1375Non-bracketing delimiters use the same character fore and aft, but the four
c543c01b 1376sorts of ASCII brackets (round, angle, square, curly) all nest, which means
9f10b797 1377that
87275199 1378
c543c01b 1379 q{foo{bar}baz}
35f2feb0 1380
9f10b797 1381is the same as
87275199 1382
c543c01b 1383 'foo{bar}baz'
87275199
GS
1384
1385Note, however, that this does not always work for quoting Perl code:
1386
db691027 1387 $s = q{ if($x eq "}") ... }; # WRONG
87275199 1388
ba7f043c 1389is a syntax error. The C<L<Text::Balanced>> module (standard as of v5.8,
c543c01b 1390and from CPAN before then) is able to do this properly.
87275199 1391
19799a22 1392There can be whitespace between the operator and the quoting
fb73857a 1393characters, except when C<#> is being used as the quoting character.
ba7f043c 1394C<q#foo#> is parsed as the string C<foo>, while S<C<q #foo#>> is the
19799a22
GS
1395operator C<q> followed by a comment. Its argument will be taken
1396from the next line. This allows you to write:
fb73857a
PP
1397
1398 s {foo} # Replace foo
1399 {bar} # with bar.
1400
c543c01b
TC
1401The following escape sequences are available in constructs that interpolate,
1402and in transliterations:
5691ca5f 1403X<\t> X<\n> X<\r> X<\f> X<\b> X<\a> X<\e> X<\x> X<\0> X<\c> X<\N> X<\N{}>
04341565 1404X<\o{}>
5691ca5f 1405
2c4c1ff2
KW
1406 Sequence Note Description
1407 \t tab (HT, TAB)
1408 \n newline (NL)
1409 \r return (CR)
1410 \f form feed (FF)
1411 \b backspace (BS)
1412 \a alarm (bell) (BEL)
1413 \e escape (ESC)
c543c01b 1414 \x{263A} [1,8] hex char (example: SMILEY)
2c4c1ff2 1415 \x1b [2,8] restricted range hex char (example: ESC)
fb121860 1416 \N{name} [3] named Unicode character or character sequence
2c4c1ff2
KW
1417 \N{U+263D} [4,8] Unicode character (example: FIRST QUARTER MOON)
1418 \c[ [5] control char (example: chr(27))
1419 \o{23072} [6,8] octal char (example: SMILEY)
1420 \033 [7,8] restricted range octal char (example: ESC)
5691ca5f
KW
1421
1422=over 4
1423
1424=item [1]
1425
2c4c1ff2
KW
1426The result is the character specified by the hexadecimal number between
1427the braces. See L</[8]> below for details on which character.
96448467 1428
46f8a5ea 1429Only hexadecimal digits are valid between the braces. If an invalid
96448467
DG
1430character is encountered, a warning will be issued and the invalid
1431character and all subsequent characters (valid or invalid) within the
1432braces will be discarded.
1433
1434If there are no valid digits between the braces, the generated character is
1435the NULL character (C<\x{00}>). However, an explicit empty brace (C<\x{}>)
c543c01b 1436will not cause a warning (currently).
40687185
KW
1437
1438=item [2]
1439
2c4c1ff2
KW
1440The result is the character specified by the hexadecimal number in the range
14410x00 to 0xFF. See L</[8]> below for details on which character.
96448467
DG
1442
1443Only hexadecimal digits are valid following C<\x>. When C<\x> is followed
2c4c1ff2 1444by fewer than two valid digits, any valid digits will be zero-padded. This
ba7f043c 1445means that C<\x7> will be interpreted as C<\x07>, and a lone C<"\x"> will be
2c4c1ff2 1446interpreted as C<\x00>. Except at the end of a string, having fewer than
c543c01b 1447two valid digits will result in a warning. Note that although the warning
96448467
DG
1448says the illegal character is ignored, it is only ignored as part of the
1449escape and will still be used as the subsequent character in the string.
1450For example:
1451
1452 Original Result Warns?
1453 "\x7" "\x07" no
1454 "\x" "\x00" no
1455 "\x7q" "\x07q" yes
1456 "\xq" "\x00q" yes
1457
40687185
KW
1458=item [3]
1459
fb121860 1460The result is the Unicode character or character sequence given by I<name>.
2c4c1ff2 1461See L<charnames>.
40687185
KW
1462
1463=item [4]
1464
ba7f043c 1465S<C<\N{U+I<hexadecimal number>}>> means the Unicode character whose Unicode code
2c4c1ff2 1466point is I<hexadecimal number>.
40687185
KW
1467
1468=item [5]
1469
5691ca5f
KW
1470The character following C<\c> is mapped to some other character as shown in the
1471table:
1472
1473 Sequence Value
1474 \c@ chr(0)
1475 \cA chr(1)
1476 \ca chr(1)
1477 \cB chr(2)
1478 \cb chr(2)
1479 ...
1480 \cZ chr(26)
1481 \cz chr(26)
1482 \c[ chr(27)
ba7f043c 1483 # See below for chr(28)
5691ca5f
KW
1484 \c] chr(29)
1485 \c^ chr(30)
c3e9d7a9 1486 \c_ chr(31)
ba7f043c
KW
1487 \c? chr(127) # (on ASCII platforms; see below for link to
1488 # EBCDIC discussion)
5691ca5f 1489
d813941f 1490In other words, it's the character whose code point has had 64 xor'd with
c3e9d7a9
KW
1491its uppercase. C<\c?> is DELETE on ASCII platforms because
1492S<C<ord("?") ^ 64>> is 127, and
ba7f043c 1493C<\c@> is NULL because the ord of C<"@"> is 64, so xor'ing 64 itself produces 0.
d813941f 1494
ba7f043c 1495Also, C<\c\I<X>> yields S<C< chr(28) . "I<X>">> for any I<X>, but cannot come at the
5691ca5f
KW
1496end of a string, because the backslash would be parsed as escaping the end
1497quote.
1498
1499On ASCII platforms, the resulting characters from the list above are the
1500complete set of ASCII controls. This isn't the case on EBCDIC platforms; see
c3e9d7a9
KW
1501L<perlebcdic/OPERATOR DIFFERENCES> for a full discussion of the
1502differences between these for ASCII versus EBCDIC platforms.
5691ca5f 1503
c3e9d7a9 1504Use of any other character following the C<"c"> besides those listed above is
63a63d81
KW
1505discouraged, and as of Perl v5.20, the only characters actually allowed
1506are the printable ASCII ones, minus the left brace C<"{">. What happens
1507for any of the allowed other characters is that the value is derived by
1508xor'ing with the seventh bit, which is 64, and a warning raised if
1509enabled. Using the non-allowed characters generates a fatal error.
5691ca5f
KW
1510
1511To get platform independent controls, you can use C<\N{...}>.
1512
40687185
KW
1513=item [6]
1514
2c4c1ff2
KW
1515The result is the character specified by the octal number between the braces.
1516See L</[8]> below for details on which character.
04341565
DG
1517
1518If a character that isn't an octal digit is encountered, a warning is raised,
1519and the value is based on the octal digits before it, discarding it and all
1520following characters up to the closing brace. It is a fatal error if there are
1521no octal digits at all.
1522
1523=item [7]
1524
c543c01b 1525The result is the character specified by the three-digit octal number in the
2c4c1ff2
KW
1526range 000 to 777 (but best to not use above 077, see next paragraph). See
1527L</[8]> below for details on which character.
1528
1529Some contexts allow 2 or even 1 digit, but any usage without exactly
40687185 1530three digits, the first being a zero, may give unintended results. (For
5db3e519
FC
1531example, in a regular expression it may be confused with a backreference;
1532see L<perlrebackslash/Octal escapes>.) Starting in Perl 5.14, you may
c543c01b 1533use C<\o{}> instead, which avoids all these problems. Otherwise, it is best to
04341565
DG
1534use this construct only for ordinals C<\077> and below, remembering to pad to
1535the left with zeros to make three digits. For larger ordinals, either use
ba7f043c
KW
1536C<\o{}>, or convert to something else, such as to hex and use C<\N{U+}>
1537(which is portable between platforms with different character sets) or
1538C<\x{}> instead.
40687185 1539
2c4c1ff2
KW
1540=item [8]
1541
c543c01b 1542Several constructs above specify a character by a number. That number
2c4c1ff2 1543gives the character's position in the character set encoding (indexed from 0).
c543c01b 1544This is called synonymously its ordinal, code position, or code point. Perl
2c4c1ff2
KW
1545works on platforms that have a native encoding currently of either ASCII/Latin1
1546or EBCDIC, each of which allow specification of 256 characters. In general, if
1547the number is 255 (0xFF, 0377) or below, Perl interprets this in the platform's
1548native encoding. If the number is 256 (0x100, 0400) or above, Perl interprets
c543c01b 1549it as a Unicode code point and the result is the corresponding Unicode
2c4c1ff2
KW
1550character. For example C<\x{50}> and C<\o{120}> both are the number 80 in
1551decimal, which is less than 256, so the number is interpreted in the native
1552character set encoding. In ASCII the character in the 80th position (indexed
ba7f043c 1553from 0) is the letter C<"P">, and in EBCDIC it is the ampersand symbol C<"&">.
2c4c1ff2
KW
1554C<\x{100}> and C<\o{400}> are both 256 in decimal, so the number is interpreted
1555as a Unicode code point no matter what the native encoding is. The name of the
9fef6a0d 1556character in the 256th position (indexed by 0) in Unicode is
2c4c1ff2
KW
1557C<LATIN CAPITAL LETTER A WITH MACRON>.
1558
9fef6a0d 1559There are a couple of exceptions to the above rule. S<C<\N{U+I<hex number>}>> is
ba7f043c
KW
1560always interpreted as a Unicode code point, so that C<\N{U+0050}> is C<"P"> even
1561on EBCDIC platforms. And if C<S<L<use encoding|encoding>>> is in effect, the
2c4c1ff2
KW
1562number is considered to be in that encoding, and is translated from that into
1563the platform's native encoding if there is a corresponding native character;
1564otherwise to Unicode.
1565
5691ca5f 1566=back
4c77eaa2 1567
e526e8bb 1568B<NOTE>: Unlike C and other languages, Perl has no C<\v> escape sequence for
8b312c40 1569the vertical tab (VT, which is 11 in both ASCII and EBCDIC), but you may
ba7f043c 1570use C<\N{VT}>, C<\ck>, C<\N{U+0b}>, or C<\x0b>. (C<\v>
e526e8bb
KW
1571does have meaning in regular expression patterns in Perl, see L<perlre>.)
1572
1573The following escape sequences are available in constructs that interpolate,
904501ec 1574but not in transliterations.
628253b8 1575X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q> X<\F>
904501ec 1576
c543c01b
TC
1577 \l lowercase next character only
1578 \u titlecase (not uppercase!) next character only
e4d34742
EB
1579 \L lowercase all characters till \E or end of string
1580 \U uppercase all characters till \E or end of string
628253b8 1581 \F foldcase all characters till \E or end of string
736fe711
KW
1582 \Q quote (disable) pattern metacharacters till \E or
1583 end of string
7e31b643 1584 \E end either case modification or quoted section
c543c01b
TC
1585 (whichever was last seen)
1586
736fe711
KW
1587See L<perlfunc/quotemeta> for the exact definition of characters that
1588are quoted by C<\Q>.
1589
628253b8 1590C<\L>, C<\U>, C<\F>, and C<\Q> can stack, in which case you need one
c543c01b
TC
1591C<\E> for each. For example:
1592
9fef6a0d
KW
1593 say"This \Qquoting \ubusiness \Uhere isn't quite\E done yet,\E is it?";
1594 This quoting\ Business\ HERE\ ISN\'T\ QUITE\ done\ yet\, is it?
a0d0e21e 1595
ba7f043c
KW
1596If a S<C<use locale>> form that includes C<LC_CTYPE> is in effect (see
1597L<perllocale>), the case map used by C<\l>, C<\L>, C<\u>, and C<\U> is
1598taken from the current locale. If Unicode (for example, C<\N{}> or code
1599points of 0x100 or beyond) is being used, the case map used by C<\l>,
1600C<\L>, C<\u>, and C<\U> is as defined by Unicode. That means that
1601case-mapping a single character can sometimes produce a sequence of
1602several characters.
1603Under S<C<use locale>>, C<\F> produces the same results as C<\L>
31f05a37
KW
1604for all locales but a UTF-8 one, where it instead uses the Unicode
1605definition.
a034a98d 1606
5a964f20
TC
1607All systems use the virtual C<"\n"> to represent a line terminator,
1608called a "newline". There is no such thing as an unvarying, physical
19799a22 1609newline character. It is only an illusion that the operating system,
5a964f20
TC
1610device drivers, C libraries, and Perl all conspire to preserve. Not all
1611systems read C<"\r"> as ASCII CR and C<"\n"> as ASCII LF. For example,
c543c01b 1612on the ancient Macs (pre-MacOS X) of yesteryear, these used to be reversed,
ba7f043c 1613and on systems without a line terminator,
c543c01b 1614printing C<"\n"> might emit no actual data. In general, use C<"\n"> when
5a964f20
TC
1615you mean a "newline" for your system, but use the literal ASCII when you
1616need an exact character. For example, most networking protocols expect
2a380090 1617and prefer a CR+LF (C<"\015\012"> or C<"\cM\cJ">) for line terminators,
5a964f20
TC
1618and although they often accept just C<"\012">, they seldom tolerate just
1619C<"\015">. If you get in the habit of using C<"\n"> for networking,
1620you may be burned some day.
d74e8afc
ITB
1621X<newline> X<line terminator> X<eol> X<end of line>
1622X<\n> X<\r> X<\r\n>
5a964f20 1623
904501ec
MG
1624For constructs that do interpolate, variables beginning with "C<$>"
1625or "C<@>" are interpolated. Subscripted variables such as C<$a[3]> or
ad0f383a
A
1626C<< $href->{key}[0] >> are also interpolated, as are array and hash slices.
1627But method calls such as C<< $obj->meth >> are not.
af9219ee
MG
1628
1629Interpolating an array or slice interpolates the elements in order,
1630separated by the value of C<$">, so is equivalent to interpolating
ba7f043c 1631S<C<join $", @array>>. "Punctuation" arrays such as C<@*> are usually
c543c01b
TC
1632interpolated only if the name is enclosed in braces C<@{*}>, but the
1633arrays C<@_>, C<@+>, and C<@-> are interpolated even without braces.
af9219ee 1634
bc7b91c6
EB
1635For double-quoted strings, the quoting from C<\Q> is applied after
1636interpolation and escapes are processed.
1637
1638 "abc\Qfoo\tbar$s\Exyz"
1639
1640is equivalent to
1641
1642 "abc" . quotemeta("foo\tbar$s") . "xyz"
1643
1644For the pattern of regex operators (C<qr//>, C<m//> and C<s///>),
1645the quoting from C<\Q> is applied after interpolation is processed,
46f8a5ea
FC
1646but before escapes are processed. This allows the pattern to match
1647literally (except for C<$> and C<@>). For example, the following matches:
bc7b91c6
EB
1648
1649 '\s\t' =~ /\Q\s\t/
1650
1651Because C<$> or C<@> trigger interpolation, you'll need to use something
1652like C</\Quser\E\@\Qhost/> to match them literally.
1d2dff63 1653
a0d0e21e
LW
1654Patterns are subject to an additional level of interpretation as a
1655regular expression. This is done as a second pass, after variables are
1656interpolated, so that regular expressions may be incorporated into the
1657pattern from the variables. If this is not what you want, use C<\Q> to
1658interpolate a variable literally.
1659
19799a22
GS
1660Apart from the behavior described above, Perl does not expand
1661multiple levels of interpolation. In particular, contrary to the
1662expectations of shell programmers, back-quotes do I<NOT> interpolate
1663within double quotes, nor do single quotes impede evaluation of
1664variables when used within double quotes.
a0d0e21e 1665
5f05dabc 1666=head2 Regexp Quote-Like Operators
d74e8afc 1667X<operator, regexp>
cb1a09d0 1668
5f05dabc 1669Here are the quote-like operators that apply to pattern
cb1a09d0
AD
1670matching and related activities.
1671
a0d0e21e
LW
1672=over 8
1673
ba7f043c 1674=item C<qr/I<STRING>/msixpodualn>
01c6f5f4 1675X<qr> X</i> X</m> X</o> X</s> X</x> X</p>
a0d0e21e 1676
87e95b7f
YO
1677This operator quotes (and possibly compiles) its I<STRING> as a regular
1678expression. I<STRING> is interpolated the same way as I<PATTERN>
6d314683
YO
1679in C<m/I<PATTERN>/>. If C<"'"> is used as the delimiter, no variable
1680interpolation is done. Returns a Perl value which may be used instead of the
ba7f043c 1681corresponding C</I<STRING>/msixpodualn> expression. The returned value is a
46f8a5ea 1682normalized version of the original pattern. It magically differs from
1c8ee595
CO
1683a string containing the same characters: C<ref(qr/x/)> returns "Regexp";
1684however, dereferencing it is not well defined (you currently get the
1685normalized version of the original pattern, but this may change).
1686
a0d0e21e 1687
87e95b7f
YO
1688For example,
1689
1690 $rex = qr/my.STRING/is;
85dd5c8b 1691 print $rex; # prints (?si-xm:my.STRING)
87e95b7f
YO
1692 s/$rex/foo/;
1693
1694is equivalent to
1695
1696 s/my.STRING/foo/is;
1697
1698The result may be used as a subpattern in a match:
1699
1700 $re = qr/$pattern/;
7188ca43
KW
1701 $string =~ /foo${re}bar/; # can be interpolated in other
1702 # patterns
87e95b7f
YO
1703 $string =~ $re; # or used standalone
1704 $string =~ /$re/; # or this way
1705
ba7f043c
KW
1706Since Perl may compile the pattern at the moment of execution of the C<qr()>
1707operator, using C<qr()> may have speed advantages in some situations,
1708notably if the result of C<qr()> is used standalone:
87e95b7f
YO
1709
1710 sub match {
1711 my $patterns = shift;
1712 my @compiled = map qr/$_/i, @$patterns;
1713 grep {
1714 my $success = 0;
1715 foreach my $pat (@compiled) {
1716 $success = 1, last if /$pat/;
1717 }
1718 $success;
1719 } @_;
5a964f20
TC
1720 }
1721
87e95b7f 1722Precompilation of the pattern into an internal representation at
ba7f043c 1723the moment of C<qr()> avoids the need to recompile the pattern every
87e95b7f
YO
1724time a match C</$pat/> is attempted. (Perl has many other internal
1725optimizations, but none would be triggered in the above example if
ba7f043c 1726we did not use C<qr()> operator.)
87e95b7f 1727
765fa144 1728Options (specified by the following modifiers) are:
87e95b7f
YO
1729
1730 m Treat string as multiple lines.
1731 s Treat string as single line. (Make . match a newline)
1732 i Do case-insensitive pattern matching.
1733 x Use extended regular expressions.
1734 p When matching preserve a copy of the matched string so
7188ca43 1735 that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be
ba7f043c
KW
1736 defined (ignored starting in v5.20) as these are always
1737 defined starting in that relese
87e95b7f 1738 o Compile pattern only once.
7188ca43 1739 a ASCII-restrict: Use ASCII for \d, \s, \w; specifying two
ba7f043c
KW
1740 a's further restricts things to that that no ASCII
1741 character will match a non-ASCII one under /i.
1742 l Use the current run-time locale's rules.
48cbae4f
SK
1743 u Use Unicode rules.
1744 d Use Unicode or native charset, as in 5.12 and earlier.
33be4c61 1745 n Non-capture mode. Don't let () fill in $1, $2, etc...
87e95b7f
YO
1746
1747If a precompiled pattern is embedded in a larger pattern then the effect
ba7f043c
KW
1748of C<"msixpluadn"> will be propagated appropriately. The effect that the
1749C</o> modifier has is not propagated, being restricted to those patterns
87e95b7f
YO
1750explicitly using it.
1751
b6fa137b 1752The last four modifiers listed above, added in Perl 5.14,
850b7ec9 1753control the character set rules, but C</a> is the only one you are likely
18509dec
KW
1754to want to specify explicitly; the other three are selected
1755automatically by various pragmas.
da392a17 1756
ba7f043c 1757See L<perlre> for additional information on valid syntax for I<STRING>, and
5e2aa8f5 1758for a detailed look at the semantics of regular expressions. In
1ca345ed
TC
1759particular, all modifiers except the largely obsolete C</o> are further
1760explained in L<perlre/Modifiers>. C</o> is described in the next section.
a0d0e21e 1761
ba7f043c 1762=item C<m/I<PATTERN>/msixpodualngc>
89d205f2
YO
1763X<m> X<operator, match>
1764X<regexp, options> X<regexp> X<regex, options> X<regex>
01c6f5f4 1765X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c>
a0d0e21e 1766
ba7f043c 1767=item C</I<PATTERN>/msixpodualngc>
a0d0e21e 1768
5a964f20 1769Searches a string for a pattern match, and in scalar context returns
19799a22 1770true if it succeeds, false if it fails. If no string is specified
ba7f043c 1771via the C<=~> or C<!~> operator, the C<$_> string is searched. (The
19799a22
GS
1772string specified with C<=~> need not be an lvalue--it may be the
1773result of an expression evaluation, but remember the C<=~> binds
006671a6 1774rather tightly.) See also L<perlre>.
a0d0e21e 1775
f6050459 1776Options are as described in C<qr//> above; in addition, the following match
01c6f5f4 1777process modifiers are available:
a0d0e21e 1778
950b09ed 1779 g Match globally, i.e., find all occurrences.
7188ca43
KW
1780 c Do not reset search position on a failed match when /g is
1781 in effect.
a0d0e21e 1782
ba7f043c 1783If C<"/"> is the delimiter then the initial C<m> is optional. With the C<m>
c543c01b 1784you can use any pair of non-whitespace (ASCII) characters
725a61d7 1785as delimiters. This is particularly useful for matching path names
ba7f043c 1786that contain C<"/">, to avoid LTS (leaning toothpick syndrome). If C<"?"> is
725a61d7 1787the delimiter, then a match-only-once rule applies,
ba7f043c 1788described in C<m?I<PATTERN>?> below. If C<"'"> (single quote) is the delimiter,
6d314683 1789no variable interpolation is performed on the I<PATTERN>.
ba7f043c 1790When using a delimiter character valid in an identifier, whitespace is required
ed02a3bf 1791after the C<m>.
a0d0e21e 1792
ba7f043c 1793I<PATTERN> may contain variables, which will be interpolated
532c9e80 1794every time the pattern search is evaluated, except
1f247705
GS
1795for when the delimiter is a single quote. (Note that C<$(>, C<$)>, and
1796C<$|> are not interpolated because they look like end-of-string tests.)
532c9e80
KW
1797Perl will not recompile the pattern unless an interpolated
1798variable that it contains changes. You can force Perl to skip the
1799test and never recompile by adding a C</o> (which stands for "once")
1800after the trailing delimiter.
1801Once upon a time, Perl would recompile regular expressions
1802unnecessarily, and this modifier was useful to tell it not to do so, in the
5cc41653 1803interests of speed. But now, the only reasons to use C</o> are one of:
532c9e80
KW
1804
1805=over
1806
1807=item 1
1808
1809The variables are thousands of characters long and you know that they
1810don't change, and you need to wring out the last little bit of speed by
1811having Perl skip testing for that. (There is a maintenance penalty for
1812doing this, as mentioning C</o> constitutes a promise that you won't
18509dec 1813change the variables in the pattern. If you do change them, Perl won't
532c9e80
KW
1814even notice.)
1815
1816=item 2
1817
1818you want the pattern to use the initial values of the variables
1819regardless of whether they change or not. (But there are saner ways
1820of accomplishing this than using C</o>.)
1821
fa9b8686
DM
1822=item 3
1823
1824If the pattern contains embedded code, such as
1825
1826 use re 'eval';
1827 $code = 'foo(?{ $x })';
1828 /$code/
1829
1830then perl will recompile each time, even though the pattern string hasn't
1831changed, to ensure that the current value of C<$x> is seen each time.
1832Use C</o> if you want to avoid this.
1833
532c9e80 1834=back
a0d0e21e 1835
18509dec
KW
1836The bottom line is that using C</o> is almost never a good idea.
1837
ba7f043c 1838=item The empty pattern C<//>
e9d89077 1839
ba7f043c 1840If the I<PATTERN> evaluates to the empty string, the last
46f8a5ea 1841I<successfully> matched regular expression is used instead. In this
c543c01b 1842case, only the C<g> and C<c> flags on the empty pattern are honored;
46f8a5ea 1843the other flags are taken from the original pattern. If no match has
d65afb4b
HS
1844previously succeeded, this will (silently) act instead as a genuine
1845empty pattern (which will always match).
a0d0e21e 1846
89d205f2
YO
1847Note that it's possible to confuse Perl into thinking C<//> (the empty
1848regex) is really C<//> (the defined-or operator). Perl is usually pretty
1849good about this, but some pathological cases might trigger this, such as
ba7f043c
KW
1850C<$x///> (is that S<C<($x) / (//)>> or S<C<$x // />>?) and S<C<print $fh //>>
1851(S<C<print $fh(//>> or S<C<print($fh //>>?). In all of these examples, Perl
89d205f2
YO
1852will assume you meant defined-or. If you meant the empty regex, just
1853use parentheses or spaces to disambiguate, or even prefix the empty
c963b151
BD
1854regex with an C<m> (so C<//> becomes C<m//>).
1855
e9d89077
DN
1856=item Matching in list context
1857
19799a22 1858If the C</g> option is not used, C<m//> in list context returns a
a0d0e21e 1859list consisting of the subexpressions matched by the parentheses in the
3ff8ecf9
BF
1860pattern, that is, (C<$1>, C<$2>, C<$3>...) (Note that here C<$1> etc. are
1861also set). When there are no parentheses in the pattern, the return
1862value is the list C<(1)> for success.
1863With or without parentheses, an empty list is returned upon failure.
a0d0e21e
LW
1864
1865Examples:
1866
7188ca43
KW
1867 open(TTY, "+</dev/tty")
1868 || die "can't access /dev/tty: $!";
c543c01b 1869
7188ca43 1870 <TTY> =~ /^y/i && foo(); # do foo if desired
a0d0e21e 1871
7188ca43 1872 if (/Version: *([0-9.]*)/) { $version = $1; }
a0d0e21e 1873
7188ca43 1874 next if m#^/usr/spool/uucp#;
a0d0e21e 1875
7188ca43
KW
1876 # poor man's grep
1877 $arg = shift;
1878 while (<>) {
1879 print if /$arg/o; # compile only once (no longer needed!)
1880 }
a0d0e21e 1881
7188ca43 1882 if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
a0d0e21e 1883
ba7f043c
KW
1884This last example splits C<$foo> into the first two words and the
1885remainder of the line, and assigns those three fields to C<$F1>, C<$F2>, and
1886C<$Etc>. The conditional is true if any variables were assigned; that is,
c543c01b 1887if the pattern matched.
a0d0e21e 1888
19799a22 1889The C</g> modifier specifies global pattern matching--that is,
46f8a5ea
FC
1890matching as many times as possible within the string. How it behaves
1891depends on the context. In list context, it returns a list of the
19799a22 1892substrings matched by any capturing parentheses in the regular
46f8a5ea 1893expression. If there are no parentheses, it returns a list of all
19799a22
GS
1894the matched strings, as if there were parentheses around the whole
1895pattern.
a0d0e21e 1896
7e86de3e 1897In scalar context, each execution of C<m//g> finds the next match,
19799a22 1898returning true if it matches, and false if there is no further match.
3dd93342 1899The position after the last match can be read or set using the C<pos()>
46f8a5ea 1900function; see L<perlfunc/pos>. A failed match normally resets the
7e86de3e 1901search position to the beginning of the string, but you can avoid that
46f8a5ea 1902by adding the C</c> modifier (for example, C<m//gc>). Modifying the target
7e86de3e 1903string also resets the search position.
c90c0ff4 1904
ba7f043c 1905=item C<\G I<assertion>>
e9d89077 1906
c90c0ff4 1907You can intermix C<m//g> matches with C<m/\G.../g>, where C<\G> is a
3dd93342 1908zero-width assertion that matches the exact position where the
46f8a5ea 1909previous C<m//g>, if any, left off. Without the C</g> modifier, the
3dd93342 1910C<\G> assertion still anchors at C<pos()> as it was at the start of
1911the operation (see L<perlfunc/pos>), but the match is of course only
46f8a5ea 1912attempted once. Using C<\G> without C</g> on a target string that has
3dd93342 1913not previously had a C</g> match applied to it is the same as using
1914the C<\A> assertion to match the beginning of the string. Note also
1915that, currently, C<\G> is only properly supported when anchored at the
1916very beginning of the pattern.
c90c0ff4
PP
1917
1918Examples:
a0d0e21e
LW
1919
1920 # list context
1921 ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
1922
1923 # scalar context
c543c01b
TC
1924 local $/ = "";
1925 while ($paragraph = <>) {
1926 while ($paragraph =~ /\p{Ll}['")]*[.!?]+['")]*\s/g) {
19799a22 1927 $sentences++;
a0d0e21e
LW
1928 }
1929 }
c543c01b
TC
1930 say $sentences;
1931
1932Here's another way to check for sentences in a paragraph:
1933
7188ca43
KW
1934 my $sentence_rx = qr{
1935 (?: (?<= ^ ) | (?<= \s ) ) # after start-of-string or
1936 # whitespace
1937 \p{Lu} # capital letter
1938 .*? # a bunch of anything
1939 (?<= \S ) # that ends in non-
1940 # whitespace
1941 (?<! \b [DMS]r ) # but isn't a common abbr.
1942 (?<! \b Mrs )
1943 (?<! \b Sra )
1944 (?<! \b St )
1945 [.?!] # followed by a sentence
1946 # ender
1947 (?= $ | \s ) # in front of end-of-string
1948 # or whitespace
1949 }sx;
1950 local $/ = "";
1951 while (my $paragraph = <>) {
1952 say "NEW PARAGRAPH";
1953 my $count = 0;
1954 while ($paragraph =~ /($sentence_rx)/g) {
1955 printf "\tgot sentence %d: <%s>\n", ++$count, $1;
c543c01b 1956 }
7188ca43 1957 }
c543c01b
TC
1958
1959Here's how to use C<m//gc> with C<\G>:
a0d0e21e 1960
137443ea 1961 $_ = "ppooqppqq";
44a8e56a
PP
1962 while ($i++ < 2) {
1963 print "1: '";
c90c0ff4 1964 print $1 while /(o)/gc; print "', pos=", pos, "\n";
44a8e56a 1965 print "2: '";
c90c0ff4 1966 print $1 if /\G(q)/gc; print "', pos=", pos, "\n";
44a8e56a 1967 print "3: '";
c90c0ff4 1968 print $1 while /(p)/gc; print "', pos=", pos, "\n";
44a8e56a 1969 }
5d43e42d 1970 print "Final: '$1', pos=",pos,"\n" if /\G(.)/;
44a8e56a
PP
1971
1972The last example should print:
1973
1974 1: 'oo', pos=4
137443ea 1975 2: 'q', pos=5
44a8e56a
PP
1976 3: 'pp', pos=7
1977 1: '', pos=7
137443ea
PP
1978 2: 'q', pos=8
1979 3: '', pos=8
5d43e42d
DC
1980 Final: 'q', pos=8
1981
1982Notice that the final match matched C<q> instead of C<p>, which a match
46f8a5ea
FC
1983without the C<\G> anchor would have done. Also note that the final match
1984did not update C<pos>. C<pos> is only updated on a C</g> match. If the
c543c01b
TC
1985final match did indeed match C<p>, it's a good bet that you're running a
1986very old (pre-5.6.0) version of Perl.
44a8e56a 1987
c90c0ff4 1988A useful idiom for C<lex>-like scanners is C</\G.../gc>. You can
e7ea3e70 1989combine several regexps like this to process a string part-by-part,
c90c0ff4
PP
1990doing different actions depending on which regexp matched. Each
1991regexp tries to match where the previous one leaves off.
e7ea3e70 1992
3fe9a6f1 1993 $_ = <<'EOL';
7188ca43
KW
1994 $url = URI::URL->new( "http://example.com/" );
1995 die if $url eq "xXx";
3fe9a6f1 1996 EOL
c543c01b
TC
1997
1998 LOOP: {
950b09ed 1999 print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc;
7188ca43
KW
2000 print(" lowercase"), redo LOOP
2001 if /\G\p{Ll}+\b[,.;]?\s*/gc;
2002 print(" UPPERCASE"), redo LOOP
2003 if /\G\p{Lu}+\b[,.;]?\s*/gc;
2004 print(" Capitalized"), redo LOOP
2005 if /\G\p{Lu}\p{Ll}+\b[,.;]?\s*/gc;
c543c01b 2006 print(" MiXeD"), redo LOOP if /\G\pL+\b[,.;]?\s*/gc;
7188ca43
KW
2007 print(" alphanumeric"), redo LOOP
2008 if /\G[\p{Alpha}\pN]+\b[,.;]?\s*/gc;
c543c01b 2009 print(" line-noise"), redo LOOP if /\G\W+/gc;
950b09ed 2010 print ". That's all!\n";
c543c01b 2011 }
e7ea3e70
IZ
2012
2013Here is the output (split into several lines):
2014
7188ca43
KW
2015 line-noise lowercase line-noise UPPERCASE line-noise UPPERCASE
2016 line-noise lowercase line-noise lowercase line-noise lowercase
2017 lowercase line-noise lowercase lowercase line-noise lowercase
2018 lowercase line-noise MiXeD line-noise. That's all!
44a8e56a 2019
ba7f043c 2020=item C<m?I<PATTERN>?msixpodualngc>
725a61d7 2021X<?> X<operator, match-once>
87e95b7f 2022
ba7f043c 2023=item C<?I<PATTERN>?msixpodualngc>
55d389e7 2024
ba7f043c
KW
2025This is just like the C<m/I<PATTERN>/> search, except that it matches
2026only once between calls to the C<reset()> operator. This is a useful
87e95b7f 2027optimization when you want to see only the first occurrence of
ceb131e8 2028something in each file of a set of files, for instance. Only C<m??>
87e95b7f
YO
2029patterns local to the current package are reset.
2030
2031 while (<>) {
ceb131e8 2032 if (m?^$?) {
87e95b7f
YO
2033 # blank line between header and body
2034 }
2035 } continue {
725a61d7 2036 reset if eof; # clear m?? status for next file
87e95b7f
YO
2037 }
2038
c543c01b
TC
2039Another example switched the first "latin1" encoding it finds
2040to "utf8" in a pod file:
2041
2042 s//utf8/ if m? ^ =encoding \h+ \K latin1 ?x;
2043
2044The match-once behavior is controlled by the match delimiter being
4932eeca 2045C<?>; with any other delimiter this is the normal C<m//> operator.
725a61d7 2046
ba7f043c 2047In the past, the leading C<m> in C<m?I<PATTERN>?> was optional, but omitting it
0381ecf1
MH
2048would produce a deprecation warning. As of v5.22.0, omitting it produces a
2049syntax error. If you encounter this construct in older code, you can just add
2050C<m>.
87e95b7f 2051
ba7f043c 2052=item C<s/I<PATTERN>/I<REPLACEMENT>/msixpodualngcer>
87e95b7f 2053X<substitute> X<substitution> X<replace> X<regexp, replace>
4f4d7508 2054X<regexp, substitute> X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c> X</e> X</r>
87e95b7f
YO
2055
2056Searches a string for a pattern, and if found, replaces that pattern
2057with the replacement text and returns the number of substitutions
2058made. Otherwise it returns false (specifically, the empty string).
2059
c543c01b 2060If the C</r> (non-destructive) option is used then it runs the
679563bb
KW
2061substitution on a copy of the string and instead of returning the
2062number of substitutions, it returns the copy whether or not a
c543c01b
TC
2063substitution occurred. The original string is never changed when
2064C</r> is used. The copy will always be a plain string, even if the
2065input is an object or a tied variable.
4f4d7508 2066
87e95b7f 2067If no string is specified via the C<=~> or C<!~> operator, the C<$_>
c543c01b
TC
2068variable is searched and modified. Unless the C</r> option is used,
2069the string specified must be a scalar variable, an array element, a
2070hash element, or an assignment to one of those; that is, some sort of
2071scalar lvalue.
87e95b7f 2072
6d314683 2073If the delimiter chosen is a single quote, no variable interpolation is
ba7f043c
KW
2074done on either the I<PATTERN> or the I<REPLACEMENT>. Otherwise, if the
2075I<PATTERN> contains a C<$> that looks like a variable rather than an
87e95b7f
YO
2076end-of-string test, the variable will be interpolated into the pattern
2077at run-time. If you want the pattern compiled only once the first time
2078the variable is interpolated, use the C</o> option. If the pattern
2079evaluates to the empty string, the last successfully executed regular
2080expression is used instead. See L<perlre> for further explanation on these.
87e95b7f 2081
ba7f043c 2082Options are as with C<m//> with the addition of the following replacement
87e95b7f
YO
2083specific options:
2084
2085 e Evaluate the right side as an expression.
7188ca43
KW
2086 ee Evaluate the right side as a string then eval the
2087 result.
2088 r Return substitution and leave the original string
2089 untouched.
87e95b7f 2090
ed02a3bf
DN
2091Any non-whitespace delimiter may replace the slashes. Add space after
2092the C<s> when using a character allowed in identifiers. If single quotes
2093are used, no interpretation is done on the replacement string (the C</e>
3ff8ecf9 2094modifier overrides this, however). Note that Perl treats backticks
ed02a3bf 2095as normal delimiters; the replacement text is not evaluated as a command.
ba7f043c 2096If the I<PATTERN> is delimited by bracketing quotes, the I<REPLACEMENT> has
1ca345ed 2097its own pair of quotes, which may or may not be bracketing quotes, for example,
87e95b7f
YO
2098C<s(foo)(bar)> or C<< s<foo>/bar/ >>. A C</e> will cause the
2099replacement portion to be treated as a full-fledged Perl expression
2100and evaluated right then and there. It is, however, syntax checked at
46f8a5ea 2101compile-time. A second C<e> modifier will cause the replacement portion
87e95b7f
YO
2102to be C<eval>ed before being run as a Perl expression.
2103
2104Examples:
2105
7188ca43 2106 s/\bgreen\b/mauve/g; # don't change wintergreen
87e95b7f
YO
2107
2108 $path =~ s|/usr/bin|/usr/local/bin|;
2109
2110 s/Login: $foo/Login: $bar/; # run-time pattern
2111
7188ca43
KW
2112 ($foo = $bar) =~ s/this/that/; # copy first, then
2113 # change
2114 ($foo = "$bar") =~ s/this/that/; # convert to string,
2115 # copy, then change
4f4d7508
DC
2116 $foo = $bar =~ s/this/that/r; # Same as above using /r
2117 $foo = $bar =~ s/this/that/r
7188ca43
KW
2118 =~ s/that/the other/r; # Chained substitutes
2119 # using /r
2120 @foo = map { s/this/that/r } @bar # /r is very useful in
2121 # maps
87e95b7f 2122
7188ca43 2123 $count = ($paragraph =~ s/Mister\b/Mr./g); # get change-cnt
87e95b7f
YO
2124
2125 $_ = 'abc123xyz';
2126 s/\d+/$&*2/e; # yields 'abc246xyz'
2127 s/\d+/sprintf("%5d",$&)/e; # yields 'abc 246xyz'
2128 s/\w/$& x 2/eg; # yields 'aabbcc 224466xxyyzz'
2129
2130 s/%(.)/$percent{$1}/g; # change percent escapes; no /e
2131 s/%(.)/$percent{$1} || $&/ge; # expr now, so /e
2132 s/^=(\w+)/pod($1)/ge; # use function call
2133
4f4d7508 2134 $_ = 'abc123xyz';
db691027 2135 $x = s/abc/def/r; # $x is 'def123xyz' and
4f4d7508
DC
2136 # $_ remains 'abc123xyz'.
2137
87e95b7f
YO
2138 # expand variables in $_, but dynamics only, using
2139 # symbolic dereferencing
2140 s/\$(\w+)/${$1}/g;
2141
2142 # Add one to the value of any numbers in the string
2143 s/(\d+)/1 + $1/eg;
2144
c543c01b
TC
2145 # Titlecase words in the last 30 characters only
2146 substr($str, -30) =~ s/\b(\p{Alpha}+)\b/\u\L$1/g;
2147
87e95b7f
YO
2148 # This will expand any embedded scalar variable
2149 # (including lexicals) in $_ : First $1 is interpolated
2150 # to the variable name, and then evaluated
2151 s/(\$\w+)/$1/eeg;
2152
2153 # Delete (most) C comments.
2154 $program =~ s {
2155 /\* # Match the opening delimiter.
2156 .*? # Match a minimal number of characters.
2157 \*/ # Match the closing delimiter.
2158 } []gsx;
2159
7188ca43
KW
2160 s/^\s*(.*?)\s*$/$1/; # trim whitespace in $_,
2161 # expensively
87e95b7f 2162
7188ca43
KW
2163 for ($variable) { # trim whitespace in $variable,
2164 # cheap
87e95b7f
YO
2165 s/^\s+//;
2166 s/\s+$//;
2167 }
2168
2169 s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
2170
ba7f043c
KW
2171Note the use of C<$> instead of C<\> in the last example. Unlike
2172B<sed>, we use the \<I<digit>> form only in the left hand side.
87e95b7f
YO
2173Anywhere else it's $<I<digit>>.
2174
2175Occasionally, you can't use just a C</g> to get all the changes
2176to occur that you might want. Here are two common cases:
2177
2178 # put commas in the right places in an integer
2179 1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g;
2180
2181 # expand tabs to 8-column spacing
2182 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
2183
2184=back
2185
2186=head2 Quote-Like Operators
2187X<operator, quote-like>
2188
01c6f5f4
RGS
2189=over 4
2190
ba7f043c 2191=item C<q/I<STRING>/>
5d44bfff 2192X<q> X<quote, single> X<'> X<''>
a0d0e21e 2193
ba7f043c 2194=item C<'I<STRING>'>
a0d0e21e 2195
19799a22 2196A single-quoted, literal string. A backslash represents a backslash
68dc0745
PP
2197unless followed by the delimiter or another backslash, in which case
2198the delimiter or backslash is interpolated.
a0d0e21e
LW
2199
2200 $foo = q!I said, "You said, 'She said it.'"!;
2201 $bar = q('This is it.');
68dc0745 2202 $baz = '\n'; # a two-character string
a0d0e21e 2203
ba7f043c 2204=item C<qq/I<STRING>/>
d74e8afc 2205X<qq> X<quote, double> X<"> X<"">
a0d0e21e 2206
ba7f043c 2207=item "I<STRING>"
a0d0e21e
LW
2208
2209A double-quoted, interpolated string.
2210
2211 $_ .= qq
2212 (*** The previous line contains the naughty word "$1".\n)
19799a22 2213 if /\b(tcl|java|python)\b/i; # :-)
68dc0745 2214 $baz = "\n"; # a one-character string
a0d0e21e 2215
ba7f043c 2216=item C<qx/I<STRING>/>
d74e8afc 2217X<qx> X<`> X<``> X<backtick>
a0d0e21e 2218
ba7f043c 2219=item C<`I<STRING>`>
a0d0e21e 2220
43dd4d21 2221A string which is (possibly) interpolated and then executed as a
f703fc96 2222system command with F</bin/sh> or its equivalent. Shell wildcards,
43dd4d21
JH
2223pipes, and redirections will be honored. The collected standard
2224output of the command is returned; standard error is unaffected. In
2225scalar context, it comes back as a single (potentially multi-line)
ba7f043c
KW
2226string, or C<undef> if the command failed. In list context, returns a
2227list of lines (however you've defined lines with C<$/> or
2228C<$INPUT_RECORD_SEPARATOR>), or an empty list if the command failed.
5a964f20
TC
2229
2230Because backticks do not affect standard error, use shell file descriptor
2231syntax (assuming the shell supports this) if you care to address this.
2232To capture a command's STDERR and STDOUT together:
a0d0e21e 2233
5a964f20
TC
2234 $output = `cmd 2>&1`;
2235
2236To capture a command's STDOUT but discard its STDERR:
2237
2238 $output = `cmd 2>/dev/null`;
2239
2240To capture a command's STDERR but discard its STDOUT (ordering is
2241important here):
2242
2243 $output = `cmd 2>&1 1>/dev/null`;
2244
2245To exchange a command's STDOUT and STDERR in order to capture the STDERR
2246but leave its STDOUT to come out the old STDERR:
2247
2248 $output = `cmd 3>&1 1>&2 2>&3 3>&-`;
2249
2250To read both a command's STDOUT and its STDERR separately, it's easiest
2359510d
SD
2251to redirect them separately to files, and then read from those files
2252when the program is done:
5a964f20 2253
2359510d 2254 system("program args 1>program.stdout 2>program.stderr");
5a964f20 2255
30398227
SP
2256The STDIN filehandle used by the command is inherited from Perl's STDIN.
2257For example:
2258
c543c01b
TC
2259 open(SPLAT, "stuff") || die "can't open stuff: $!";
2260 open(STDIN, "<&SPLAT") || die "can't dupe SPLAT: $!";
40bbb707 2261 print STDOUT `sort`;
30398227 2262
40bbb707 2263will print the sorted contents of the file named F<"stuff">.
30398227 2264
5a964f20
TC
2265Using single-quote as a delimiter protects the command from Perl's
2266double-quote interpolation, passing it on to the shell instead:
2267
2268 $perl_info = qx(ps $$); # that's Perl's $$
2269 $shell_info = qx'ps $$'; # that's the new shell's $$
2270
19799a22 2271How that string gets evaluated is entirely subject to the command
5a964f20
TC
2272interpreter on your system. On most platforms, you will have to protect
2273shell metacharacters if you want them treated literally. This is in
2274practice difficult to do, as it's unclear how to escape which characters.
ba7f043c 2275See L<perlsec> for a clean and safe example of a manual C<fork()> and C<exec()>
5a964f20 2276to emulate backticks safely.
a0d0e21e 2277
bb32b41a
GS
2278On some platforms (notably DOS-like ones), the shell may not be
2279capable of dealing with multiline commands, so putting newlines in
2280the string may not get you what you want. You may be able to evaluate
2281multiple commands in a single line by separating them with the command
1ca345ed
TC
2282separator character, if your shell supports that (for example, C<;> on
2283many Unix shells and C<&> on the Windows NT C<cmd> shell).
bb32b41a 2284
3ff8ecf9 2285Perl will attempt to flush all files opened for
0f897271
GS
2286output before starting the child process, but this may not be supported
2287on some platforms (see L<perlport>). To be safe, you may need to set
ba7f043c
KW
2288C<$|> (C<$AUTOFLUSH> in C<L<English>>) or call the C<autoflush()> method of
2289C<L<IO::Handle>> on any open handles.
0f897271 2290
bb32b41a
GS
2291Beware that some command shells may place restrictions on the length
2292of the command line. You must ensure your strings don't exceed this
2293limit after any necessary interpolations. See the platform-specific
2294release notes for more details about your particular environment.
2295
5a964f20
TC
2296Using this operator can lead to programs that are difficult to port,
2297because the shell commands called vary between systems, and may in
2298fact not be present at all. As one example, the C<type> command under
2299the POSIX shell is very different from the C<type> command under DOS.
2300That doesn't mean you should go out of your way to avoid backticks
2301when they're the right way to get something done. Perl was made to be
2302a glue language, and one of the things it glues together is commands.
2303Just understand what you're getting yourself into.
bb32b41a 2304
7cf4dd3e
DB
2305Like C<system>, backticks put the child process exit code in C<$?>.
2306If you'd like to manually inspect failure, you can check all possible
2307failure modes by inspecting C<$?> like this:
2308
2309 if ($? == -1) {
2310 print "failed to execute: $!\n";
2311 }
2312 elsif ($? & 127) {
2313 printf "child died with signal %d, %s coredump\n",
2314 ($? & 127), ($? & 128) ? 'with' : 'without';
2315 }
2316 else {
2317 printf "child exited with value %d\n", $? >> 8;
2318 }
2319
fe43a9cc
TC
2320Use the L<open> pragma to control the I/O layers used when reading the
2321output of the command, for example:
2322
2323 use open IN => ":encoding(UTF-8)";
2324 my $x = `cmd-producing-utf-8`;
2325
da87341d 2326See L</"I/O Operators"> for more discussion.
a0d0e21e 2327
ba7f043c 2328=item C<qw/I<STRING>/>
d74e8afc 2329X<qw> X<quote, list> X<quote, words>
945c54fd 2330
ba7f043c 2331Evaluates to a list of the words extracted out of I<STRING>, using embedded
945c54fd
JH
2332whitespace as the word delimiters. It can be understood as being roughly
2333equivalent to:
2334
c543c01b 2335 split(" ", q/STRING/);
945c54fd 2336
efb1e162
CW
2337the differences being that it generates a real list at compile time, and
2338in scalar context it returns the last element in the list. So
945c54fd
JH
2339this expression:
2340
2341 qw(foo bar baz)
2342
2343is semantically equivalent to the list:
2344
c543c01b 2345 "foo", "bar", "baz"
945c54fd
JH
2346
2347Some frequently seen examples:
2348
2349 use POSIX qw( setlocale localeconv )
2350 @EXPORT = qw( foo bar baz );
2351
ba7f043c 2352A common mistake is to try to separate the words with commas or to
945c54fd 2353put comments into a multi-line C<qw>-string. For this reason, the
ba7f043c
KW
2354S<C<use warnings>> pragma and the B<-w> switch (that is, the C<$^W> variable)
2355produces warnings if the I<STRING> contains the C<","> or the C<"#"> character.
945c54fd 2356
ba7f043c 2357=item C<tr/I<SEARCHLIST>/I<REPLACEMENTLIST>/cdsr>
d74e8afc 2358X<tr> X<y> X<transliterate> X</c> X</d> X</s>
a0d0e21e 2359
ba7f043c 2360=item C<y/I<SEARCHLIST>/I<REPLACEMENTLIST>/cdsr>
a0d0e21e 2361
2c268ad5 2362Transliterates all occurrences of the characters found in the search list
a0d0e21e
LW
2363with the corresponding character in the replacement list. It returns
2364the number of characters replaced or deleted. If no string is
ba7f043c 2365specified via the C<=~> or C<!~> operator, the C<$_> string is transliterated.
c543c01b
TC
2366
2367If the C</r> (non-destructive) option is present, a new copy of the string
2368is made and its characters transliterated, and this copy is returned no
2369matter whether it was modified or not: the original string is always
2370left unchanged. The new copy is always a plain string, even if the input
2371string is an object or a tied variable.
8ada0baa 2372
c543c01b
TC
2373Unless the C</r> option is used, the string specified with C<=~> must be a
2374scalar variable, an array element, a hash element, or an assignment to one
2375of those; in other words, an lvalue.
8ff32507 2376
89d205f2 2377A character range may be specified with a hyphen, so C<tr/A-J/0-9/>
2c268ad5 2378does the same replacement as C<tr/ACEGIBDFHJ/0246813579/>.
54310121 2379For B<sed> devotees, C<y> is provided as a synonym for C<tr>. If the
af2cbe4d
KW
2380I<SEARCHLIST> is delimited by bracketing quotes, the I<REPLACEMENTLIST>
2381must have its own pair of quotes, which may or may not be bracketing
2382quotes; for example, C<tr[aeiouy][yuoiea]> or C<tr(+\-*/)/ABCD/>.
c543c01b 2383
ba7f043c 2384Characters may be literals or any of the escape sequences accepted in
6d314683
YO
2385double-quoted strings. But there is no variable interpolation, so C<"$">
2386and C<"@"> are treated as literals. A hyphen at the beginning or end, or
ba7f043c
KW
2387preceded by a backslash is considered a literal. Escape sequence
2388details are in L<the table near the beginning of this section|/Quote and
f4240379 2389Quote-like Operators>.
ba7f043c 2390
c543c01b 2391Note that C<tr> does B<not> do regular expression character classes such as
ba7f043c 2392C<\d> or C<\pL>. The C<tr> operator is not equivalent to the C<L<tr(1)>>
af2cbe4d
KW
2393utility. C<tr[a-z][A-Z]> will uppercase the 26 letters "a" through "z",
2394but for case changing not confined to ASCII, use
2395L<C<lc>|perlfunc/lc>, L<C<uc>|perlfunc/uc>,
2396L<C<lcfirst>|perlfunc/lcfirst>, L<C<ucfirst>|perlfunc/ucfirst>
2397(all documented in L<perlfunc>), or the
2398L<substitution operator C<sE<sol>I<PATTERN>E<sol>I<REPLACEMENT>E<sol>>|/sE<sol>PATTERNE<sol>REPLACEMENTE<sol>msixpodualngcer>
2399(with C<\U>, C<\u>, C<\L>, and C<\l> string-interpolation escapes in the
2400I<REPLACEMENT> portion).
cc255d5f 2401
f4240379
KW
2402Most ranges are unportable between character sets, but certain ones
2403signal Perl to do special handling to make them portable. There are two
2404classes of portable ranges. The first are any subsets of the ranges
2405C<A-Z>, C<a-z>, and C<0-9>, when expressed as literal characters.
2406
2407 tr/h-k/H-K/
2408
2409capitalizes the letters C<"h">, C<"i">, C<"j">, and C<"k"> and nothing
2410else, no matter what the platform's character set is. In contrast, all
2411of
2412
2413 tr/\x68-\x6B/\x48-\x4B/
2414 tr/h-\x6B/H-\x4B/
2415 tr/\x68-k/\x48-K/
2416
2417do the same capitalizations as the previous example when run on ASCII
2418platforms, but something completely different on EBCDIC ones.
2419
2420The second class of portable ranges is invoked when one or both of the
2421range's end points are expressed as C<\N{...}>
2422
2423 $string =~ tr/\N{U+20}-\N{U+7E}//d;
2424
2425removes from C<$string> all the platform's characters which are
2426equivalent to any of Unicode U+0020, U+0021, ... U+007D, U+007E. This
2427is a portable range, and has the same effect on every platform it is
2428run on. It turns out that in this example, these are the ASCII
2429printable characters. So after this is run, C<$string> has only
2430controls and characters which have no ASCII equivalents.
2431
2432But, even for portable ranges, it is not generally obvious what is
2433included without having to look things up. A sound principle is to use
2434only ranges that begin from and end at either ASCII alphabetics of equal
8df98a27 2435case (C<b-e>, C<B-E>), or digits (C<1-4>). Anything else is unclear
f4240379 2436(and unportable unless C<\N{...}> is used). If in doubt, spell out the
8ada0baa
JH
2437character sets in full.
2438
a0d0e21e
LW
2439Options:
2440
2441 c Complement the SEARCHLIST.
2442 d Delete found but unreplaced characters.
2443 s Squash duplicate replaced characters.
8ff32507
FC
2444 r Return the modified string and leave the original string
2445 untouched.
a0d0e21e 2446
ba7f043c 2447If the C</c> modifier is specified, the I<SEARCHLIST> character set
19799a22 2448is complemented. If the C</d> modifier is specified, any characters
ba7f043c 2449specified by I<SEARCHLIST> not found in I<REPLACEMENTLIST> are deleted.
19799a22 2450(Note that this is slightly more flexible than the behavior of some
ba7f043c 2451B<tr> programs, which delete anything they find in the I<SEARCHLIST>,
46f8a5ea 2452period.) If the C</s> modifier is specified, sequences of characters
19799a22
GS
2453that were transliterated to the same character are squashed down
2454to a single instance of the character.
a0d0e21e 2455
ba7f043c
KW
2456If the C</d> modifier is used, the I<REPLACEMENTLIST> is always interpreted
2457exactly as specified. Otherwise, if the I<REPLACEMENTLIST> is shorter
2458than the I<SEARCHLIST>, the final character is replicated till it is long
2459enough. If the I<REPLACEMENTLIST> is empty, the I<SEARCHLIST> is replicated.
a0d0e21e
LW
2460This latter is useful for counting characters in a class or for
2461squashing character sequences in a class.
2462
2463Examples:
2464
c543c01b 2465 $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case ASCII
a0d0e21e
LW
2466
2467 $cnt = tr/*/*/; # count the stars in $_
2468
2469 $cnt = $sky =~ tr/*/*/; # count the stars in $sky
2470
2471 $cnt = tr/0-9//; # count the digits in $_
2472
2473 tr/a-zA-Z//s; # bookkeeper -> bokeper
2474
2475 ($HOST = $host) =~ tr/a-z/A-Z/;
c543c01b 2476 $HOST = $host =~ tr/a-z/A-Z/r; # same thing
8ff32507 2477
c543c01b 2478 $HOST = $host =~ tr/a-z/A-Z/r # chained with s///r
8ff32507 2479 =~ s/:/ -p/r;
a0d0e21e
LW
2480
2481 tr/a-zA-Z/ /cs; # change non-alphas to single space
2482
8ff32507
FC
2483 @stripped = map tr/a-zA-Z/ /csr, @original;
2484 # /r with map
2485
a0d0e21e 2486 tr [\200-\377]
c543c01b 2487 [\000-\177]; # wickedly delete 8th bit
a0d0e21e 2488
19799a22
GS
2489If multiple transliterations are given for a character, only the
2490first one is used:
748a9306
LW
2491
2492 tr/AAA/XYZ/
2493
2c268ad5 2494will transliterate any A to X.
748a9306 2495
19799a22 2496Because the transliteration table is built at compile time, neither
ba7f043c 2497the I<SEARCHLIST> nor the I<REPLACEMENTLIST> are subjected to double quote
19799a22 2498interpolation. That means that if you want to use variables, you
ba7f043c 2499must use an C<eval()>:
a0d0e21e
LW
2500
2501 eval "tr/$oldlist/$newlist/";
2502 die $@ if $@;
2503
2504 eval "tr/$oldlist/$newlist/, 1" or die $@;
2505
ba7f043c 2506=item C<< <<I<EOF> >>
d74e8afc 2507X<here-doc> X<heredoc> X<here-document> X<<< << >>>
7e3b091d
DA
2508
2509A line-oriented form of quoting is based on the shell "here-document"
2510syntax. Following a C<< << >> you specify a string to terminate
2511the quoted material, and all lines following the current line down to
89d205f2
YO
2512the terminating string are the value of the item.
2513
2514The terminating string may be either an identifier (a word), or some
2515quoted text. An unquoted identifier works like double quotes.
2516There may not be a space between the C<< << >> and the identifier,
2517unless the identifier is explicitly quoted. (If you put a space it
2518will be treated as a null identifier, which is valid, and matches the
2519first empty line.) The terminating string must appear by itself
2520(unquoted and with no surrounding whitespace) on the terminating line.
2521
2522If the terminating string is quoted, the type of quotes used determine
2523the treatment of the text.
2524
2525=over 4
2526
2527=item Double Quotes
2528
2529Double quotes indicate that the text will be interpolated using exactly
2530the same rules as normal double quoted strings.
7e3b091d
DA
2531
2532 print <<EOF;
2533 The price is $Price.
2534 EOF
2535
2536 print << "EOF"; # same as above
2537 The price is $Price.
2538 EOF
2539
89d205f2
YO
2540
2541=item Single Quotes
2542
2543Single quotes indicate the text is to be treated literally with no
46f8a5ea 2544interpolation of its content. This is similar to single quoted
89d205f2
YO
2545strings except that backslashes have no special meaning, with C<\\>
2546being treated as two backslashes and not one as they would in every
2547other quoting construct.
2548
c543c01b
TC
2549Just as in the shell, a backslashed bareword following the C<<< << >>>
2550means the same thing as a single-quoted string does:
2551
2552 $cost = <<'VISTA'; # hasta la ...
2553 That'll be $10 please, ma'am.
2554 VISTA
2555
2556 $cost = <<\VISTA; # Same thing!
2557 That'll be $10 please, ma'am.
2558 VISTA
2559
89d205f2
YO
2560This is the only form of quoting in perl where there is no need
2561to worry about escaping content, something that code generators
2562can and do make good use of.
2563
2564=item Backticks
2565
2566The content of the here doc is treated just as it would be if the
46f8a5ea 2567string were embedded in backticks. Thus the content is interpolated
89d205f2
YO
2568as though it were double quoted and then executed via the shell, with
2569the results of the execution returned.
2570
2571 print << `EOC`; # execute command and get results
7e3b091d 2572 echo hi there
7e3b091d
DA
2573 EOC
2574
89d205f2
YO
2575=back
2576
2577It is possible to stack multiple here-docs in a row:
2578
7e3b091d
DA
2579 print <<"foo", <<"bar"; # you can stack them
2580 I said foo.
2581 foo
2582 I said bar.
2583 bar
2584
2585 myfunc(<< "THIS", 23, <<'THAT');
2586 Here's a line
2587 or two.
2588 THIS
2589 and here's another.
2590 THAT
2591
2592Just don't forget that you have to put a semicolon on the end
2593to finish the statement, as Perl doesn't know you're not going to
2594try to do this:
2595
2596 print <<ABC
2597 179231
2598 ABC
2599 + 20;
2600
872d7e53
ST
2601If you want to remove the line terminator from your here-docs,
2602use C<chomp()>.
2603
2604 chomp($string = <<'END');
2605 This is a string.
2606 END
2607
2608If you want your here-docs to be indented with the rest of the code,
2609you'll need to remove leading whitespace from each line manually:
7e3b091d
DA
2610
2611 ($quote = <<'FINIS') =~ s/^\s+//gm;
89d205f2 2612 The Road goes ever on and on,
7e3b091d
DA
2613 down from the door where it began.
2614 FINIS
2615
2616If you use a here-doc within a delimited construct, such as in C<s///eg>,
1bf48760
FC
2617the quoted material must still come on the line following the
2618C<<< <<FOO >>> marker, which means it may be inside the delimited
2619construct:
7e3b091d
DA
2620
2621 s/this/<<E . 'that'
2622 the other
2623 E
2624 . 'more '/eg;
2625
1bf48760
FC
2626It works this way as of Perl 5.18. Historically, it was inconsistent, and
2627you would have to write
7e3b091d 2628
89d205f2
YO
2629 s/this/<<E . 'that'
2630 . 'more '/eg;
2631 the other
2632 E
7e3b091d 2633
1bf48760
FC
2634outside of string evals.
2635
c543c01b 2636Additionally, quoting rules for the end-of-string identifier are
46f8a5ea 2637unrelated to Perl's quoting rules. C<q()>, C<qq()>, and the like are not
89d205f2
YO
2638supported in place of C<''> and C<"">, and the only interpolation is for
2639backslashing the quoting character:
7e3b091d
DA
2640
2641 print << "abc\"def";
2642 testing...
2643 abc"def
2644
2645Finally, quoted strings cannot span multiple lines. The general rule is
2646that the identifier must be a string literal. Stick with that, and you
2647should be safe.
2648
a0d0e21e
LW
2649=back
2650
75e14d17 2651=head2 Gory details of parsing quoted constructs
d74e8afc 2652X<quote, gory details>
75e14d17 2653
19799a22
GS
2654When presented with something that might have several different
2655interpretations, Perl uses the B<DWIM> (that's "Do What I Mean")
2656principle to pick the most probable interpretation. This strategy
2657is so successful that Perl programmers often do not suspect the
2658ambivalence of what they write. But from time to time, Perl's
2659notions differ substantially from what the author honestly meant.
2660
2661This section hopes to clarify how Perl handles quoted constructs.
2662Although the most common reason to learn this is to unravel labyrinthine
2663regular expressions, because the initial steps of parsing are the
2664same for all quoting operators, they are all discussed together.
2665
2666The most important Perl parsing rule is the first one discussed
2667below: when processing a quoted construct, Perl first finds the end
2668of that construct, then interprets its contents. If you understand
2669this rule, you may skip the rest of this section on the first
2670reading. The other rules are likely to contradict the user's
2671expectations much less frequently than this first one.
2672
2673Some passes discussed below are performed concurrently, but because
2674their results are the same, we consider them individually. For different
2675quoting constructs, Perl performs different numbers of passes, from
6deea57f 2676one to four, but these passes are always performed in the same order.
75e14d17 2677
13a2d996 2678=over 4
75e14d17
IZ
2679
2680=item Finding the end
2681
ba7f043c
KW
2682The first pass is finding the end of the quoted construct. This results
2683in saving to a safe location a copy of the text (between the starting
2684and ending delimiters), normalized as necessary to avoid needing to know
2685what the original delimiters were.
6deea57f
ST
2686
2687If the construct is a here-doc, the ending delimiter is a line
46f8a5ea 2688that has a terminating string as the content. Therefore C<<<EOF> is
6deea57f
ST
2689terminated by C<EOF> immediately followed by C<"\n"> and starting
2690from the first column of the terminating line.
2691When searching for the terminating line of a here-doc, nothing
46f8a5ea 2692is skipped. In other words, lines after the here-doc syntax
6deea57f
ST
2693are compared with the terminating string line by line.
2694
2695For the constructs except here-docs, single characters are used as starting
46f8a5ea 2696and ending delimiters. If the starting delimiter is an opening punctuation
6deea57f
ST
2697(that is C<(>, C<[>, C<{>, or C<< < >>), the ending delimiter is the
2698corresponding closing punctuation (that is C<)>, C<]>, C<}>, or C<< > >>).
2699If the starting delimiter is an unpaired character like C</> or a closing
ba7f043c 2700punctuation, the ending delimiter is the same as the starting delimiter.
6deea57f 2701Therefore a C</> terminates a C<qq//> construct, while a C<]> terminates
fc693347 2702both C<qq[]> and C<qq]]> constructs.
6deea57f
ST
2703
2704When searching for single-character delimiters, escaped delimiters
1ca345ed 2705and C<\\> are skipped. For example, while searching for terminating C</>,
6deea57f
ST
2706combinations of C<\\> and C<\/> are skipped. If the delimiters are
2707bracketing, nested pairs are also skipped. For example, while searching
ba7f043c 2708for a closing C<]> paired with the opening C<[>, combinations of C<\\>, C<\]>,
6deea57f
ST
2709and C<\[> are all skipped, and nested C<[> and C<]> are skipped as well.
2710However, when backslashes are used as the delimiters (like C<qq\\> and
2711C<tr\\\>), nothing is skipped.
32581033 2712During the search for the end, backslashes that escape delimiters or
7188ca43 2713other backslashes are removed (exactly speaking, they are not copied to the
32581033 2714safe location).
75e14d17 2715
19799a22
GS
2716For constructs with three-part delimiters (C<s///>, C<y///>, and
2717C<tr///>), the search is repeated once more.
fc693347 2718If the first delimiter is not an opening punctuation, the three delimiters must
d74605e5
FC
2719be the same, such as C<s!!!> and C<tr)))>,
2720in which case the second delimiter
6deea57f 2721terminates the left part and starts the right part at once.
b6538e4f 2722If the left part is delimited by bracketing punctuation (that is C<()>,
6deea57f 2723C<[]>, C<{}>, or C<< <> >>), the right part needs another pair of
b6538e4f 2724delimiters such as C<s(){}> and C<tr[]//>. In these cases, whitespace
ba7f043c 2725and comments are allowed between the two parts, although the comment must follow
b6538e4f
TC
2726at least one whitespace character; otherwise a character expected as the
2727start of the comment may be regarded as the starting delimiter of the right part.
75e14d17 2728
19799a22
GS
2729During this search no attention is paid to the semantics of the construct.
2730Thus:
75e14d17
IZ
2731
2732 "$hash{"$foo/$bar"}"
2733
2a94b7ce 2734or:
75e14d17 2735
89d205f2 2736 m/
2a94b7ce 2737 bar # NOT a comment, this slash / terminated m//!
75e14d17
IZ
2738 /x
2739
19799a22
GS
2740do not form legal quoted expressions. The quoted part ends on the
2741first C<"> and C</>, and the rest happens to be a syntax error.
2742Because the slash that terminated C<m//> was followed by a C<SPACE>,
2743the example above is not C<m//x>, but rather C<m//> with no C</x>
2744modifier. So the embedded C<#> is interpreted as a literal C<#>.
75e14d17 2745
89d205f2 2746Also no attention is paid to C<\c\> (multichar control char syntax) during
46f8a5ea 2747this search. Thus the second C<\> in C<qq/\c\/> is interpreted as a part
89d205f2 2748of C<\/>, and the following C</> is not recognized as a delimiter.
0d594e51
ST
2749Instead, use C<\034> or C<\x1c> at the end of quoted constructs.
2750
75e14d17 2751=item Interpolation
d74e8afc 2752X<interpolation>
75e14d17 2753
19799a22 2754The next step is interpolation in the text obtained, which is now
89d205f2 2755delimiter-independent. There are multiple cases.
75e14d17 2756
13a2d996 2757=over 4
75e14d17 2758
89d205f2 2759=item C<<<'EOF'>
75e14d17
IZ
2760
2761No interpolation is performed.
6deea57f
ST
2762Note that the combination C<\\> is left intact, since escaped delimiters
2763are not available for here-docs.
75e14d17 2764
6deea57f 2765=item C<m''>, the pattern of C<s'''>
89d205f2 2766
6deea57f
ST
2767No interpolation is performed at this stage.
2768Any backslashed sequences including C<\\> are treated at the stage
2769to L</"parsing regular expressions">.
89d205f2 2770
6deea57f 2771=item C<''>, C<q//>, C<tr'''>, C<y'''>, the replacement of C<s'''>
75e14d17 2772
89d205f2 2773The only interpolation is removal of C<\> from pairs of C<\\>.
ba7f043c 2774Therefore C<"-"> in C<tr'''> and C<y'''> is treated literally
6deea57f
ST
2775as a hyphen and no character range is available.
2776C<\1> in the replacement of C<s'''> does not work as C<$1>.
89d205f2
YO
2777
2778=item C<tr///>, C<y///>
2779
6deea57f
ST
2780No variable interpolation occurs. String modifying combinations for
2781case and quoting such as C<\Q>, C<\U>, and C<\E> are not recognized.
2782The other escape sequences such as C<\200> and C<\t> and backslashed
2783characters such as C<\\> and C<\-> are converted to appropriate literals.
ba7f043c
KW
2784The character C<"-"> is treated specially and therefore C<\-> is treated
2785as a literal C<"-">.
75e14d17 2786
89d205f2 2787=item C<"">, C<``>, C<qq//>, C<qx//>, C<< <file*glob> >>, C<<<"EOF">
75e14d17 2788
628253b8 2789C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F> (possibly paired with C<\E>) are
19799a22 2790converted to corresponding Perl constructs. Thus, C<"$foo\Qbaz$bar">
ba7f043c 2791is converted to S<C<$foo . (quotemeta("baz" . $bar))>> internally.
6deea57f
ST
2792The other escape sequences such as C<\200> and C<\t> and backslashed
2793characters such as C<\\> and C<\-> are replaced with appropriate
2794expansions.
2a94b7ce 2795
19799a22
GS
2796Let it be stressed that I<whatever falls between C<\Q> and C<\E>>
2797is interpolated in the usual way. Something like C<"\Q\\E"> has
48cbae4f 2798no C<\E> inside. Instead, it has C<\Q>, C<\\>, and C<E>, so the
19799a22
GS
2799result is the same as for C<"\\\\E">. As a general rule, backslashes
2800between C<\Q> and C<\E> may lead to counterintuitive results. So,
2801C<"\Q\t\E"> is converted to C<quotemeta("\t")>, which is the same
2802as C<"\\\t"> (since TAB is not alphanumeric). Note also that:
2a94b7ce
IZ
2803
2804 $str = '\t';
2805 return "\Q$str";
2806
2807may be closer to the conjectural I<intention> of the writer of C<"\Q\t\E">.
2808
19799a22 2809Interpolated scalars and arrays are converted internally to the C<join> and
ba7f043c 2810C<"."> catenation operations. Thus, S<C<"$foo XXX '@arr'">> becomes:
75e14d17 2811
19799a22 2812 $foo . " XXX '" . (join $", @arr) . "'";
75e14d17 2813
19799a22 2814All operations above are performed simultaneously, left to right.
75e14d17 2815
ba7f043c 2816Because the result of S<C<"\Q I<STRING> \E">> has all metacharacters
19799a22 2817quoted, there is no way to insert a literal C<$> or C<@> inside a
ba7f043c 2818C<\Q\E> pair. If protected by C<\>, C<$> will be quoted to become
19799a22
GS
2819C<"\\\$">; if not, it is interpreted as the start of an interpolated
2820scalar.
75e14d17 2821
19799a22 2822Note also that the interpolation code needs to make a decision on
89d205f2 2823where the interpolated scalar ends. For instance, whether
ba7f043c 2824S<C<< "a $x -> {c}" >>> really means:
75e14d17 2825
db691027 2826 "a " . $x . " -> {c}";
75e14d17 2827
2a94b7ce 2828or:
75e14d17 2829
db691027 2830 "a " . $x -> {c};
75e14d17 2831
19799a22
GS
2832Most of the time, the longest possible text that does not include
2833spaces between components and which contains matching braces or
2834brackets. because the outcome may be determined by voting based
2835on heuristic estimators, the result is not strictly predictable.
2836Fortunately, it's usually correct for ambiguous cases.
75e14d17 2837
6deea57f 2838=item the replacement of C<s///>
75e14d17 2839
628253b8 2840Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F> and interpolation
6deea57f
ST
2841happens as with C<qq//> constructs.
2842
2843It is at this step that C<\1> is begrudgingly converted to C<$1> in
2844the replacement text of C<s///>, in order to correct the incorrigible
2845I<sed> hackers who haven't picked up the saner idiom yet. A warning
ba7f043c 2846is emitted if the S<C<use warnings>> pragma or the B<-w> command-line flag
6deea57f
ST
2847(that is, the C<$^W> variable) was set.
2848
2849=item C<RE> in C<?RE?>, C</RE/>, C<m/RE/>, C<s/RE/foo/>,
2850
628253b8 2851Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F>, C<\E>,
cc74c5bd
ST
2852and interpolation happens (almost) as with C<qq//> constructs.
2853
5d03b57c
KW
2854Processing of C<\N{...}> is also done here, and compiled into an intermediate
2855form for the regex compiler. (This is because, as mentioned below, the regex
2856compilation may be done at execution time, and C<\N{...}> is a compile-time
2857construct.)
2858
cc74c5bd
ST
2859However any other combinations of C<\> followed by a character
2860are not substituted but only skipped, in order to parse them
2861as regular expressions at the following step.
6deea57f 2862As C<\c> is skipped at this step, C<@> of C<\c@> in RE is possibly
1749ea0d 2863treated as an array symbol (for example C<@foo>),
6deea57f 2864even though the same text in C<qq//> gives interpolation of C<\c@>.
6deea57f 2865
e128ab2c
DM
2866Code blocks such as C<(?{BLOCK})> are handled by temporarily passing control
2867back to the perl parser, in a similar way that an interpolated array
2868subscript expression such as C<"foo$array[1+f("[xyz")]bar"> would be.
2869
ba7f043c
KW
2870Moreover, inside C<(?{BLOCK})>, S<C<(?# comment )>>, and
2871a C<#>-comment in a C</x>-regular expression, no processing is
19799a22 2872performed whatsoever. This is the first step at which the presence
ba7f043c 2873of the C</x> modifier is relevant.
19799a22 2874
1749ea0d
ST
2875Interpolation in patterns has several quirks: C<$|>, C<$(>, C<$)>, C<@+>
2876and C<@-> are not interpolated, and constructs C<$var[SOMETHING]> are
2877voted (by several different estimators) to be either an array element
2878or C<$var> followed by an RE alternative. This is where the notation
19799a22
GS
2879C<${arr[$bar]}> comes handy: C</${arr[0-9]}/> is interpreted as
2880array element C<-9>, not as a regular expression from the variable
2881C<$arr> followed by a digit, which would be the interpretation of
2882C</$arr[0-9]/>. Since voting among different estimators may occur,
2883the result is not predictable.
2884
19799a22
GS
2885The lack of processing of C<\\> creates specific restrictions on
2886the post-processed text. If the delimiter is C</>, one cannot get
2887the combination C<\/> into the result of this step. C</> will
2888finish the regular expression, C<\/> will be stripped to C</> on
2889the previous step, and C<\\/> will be left as is. Because C</> is
2890equivalent to C<\/> inside a regular expression, this does not
2891matter unless the delimiter happens to be character special to the
2892RE engine, such as in C<s*foo*bar*>, C<m[foo]>, or C<?foo?>; or an
2893alphanumeric char, as in:
2a94b7ce
IZ
2894
2895 m m ^ a \s* b mmx;
2896
19799a22 2897In the RE above, which is intentionally obfuscated for illustration, the
6deea57f 2898delimiter is C<m>, the modifier is C<mx>, and after delimiter-removal the
ba7f043c 2899RE is the same as for S<C<m/ ^ a \s* b /mx>>. There's more than one
19799a22
GS
2900reason you're encouraged to restrict your delimiters to non-alphanumeric,
2901non-whitespace choices.
75e14d17
IZ
2902
2903=back
2904
19799a22 2905This step is the last one for all constructs except regular expressions,
75e14d17
IZ
2906which are processed further.
2907
6deea57f
ST
2908=item parsing regular expressions
2909X<regexp, parse>
75e14d17 2910
19799a22 2911Previous steps were performed during the compilation of Perl code,
ac036724 2912but this one happens at run time, although it may be optimized to
19799a22 2913be calculated at compile time if appropriate. After preprocessing
6deea57f 2914described above, and possibly after evaluation if concatenation,
19799a22
GS
2915joining, casing translation, or metaquoting are involved, the
2916resulting I<string> is passed to the RE engine for compilation.
2917
2918Whatever happens in the RE engine might be better discussed in L<perlre>,
2919but for the sake of continuity, we shall do so here.
2920
ba7f043c 2921This is another step where the presence of the C</x> modifier is
19799a22 2922relevant. The RE engine scans the string from left to right and
ba7f043c 2923converts it into a finite automaton.
19799a22
GS
2924
2925Backslashed characters are either replaced with corresponding
2926literal strings (as with C<\{>), or else they generate special nodes
2927in the finite automaton (as with C<\b>). Characters special to the
2928RE engine (such as C<|>) generate corresponding nodes or groups of
2929nodes. C<(?#...)> comments are ignored. All the rest is either
2930converted to literal strings to match, or else is ignored (as is
ba7f043c 2931whitespace and C<#>-style comments if C</x> is present).
19799a22
GS
2932
2933Parsing of the bracketed character class construct, C<[...]>, is
2934rather different than the rule used for the rest of the pattern.
2935The terminator of this construct is found using the same rules as
2936for finding the terminator of a C<{}>-delimited construct, the only
2937exception being that C<]> immediately following C<[> is treated as
e128ab2c
DM
2938though preceded by a backslash.
2939
2940The terminator of runtime C<(?{...})> is found by temporarily switching
2941control to the perl parser, which should stop at the point where the
2942logically balancing terminating C<}> is found.
19799a22
GS
2943
2944It is possible to inspect both the string given to RE engine and the
2945resulting finite automaton. See the arguments C<debug>/C<debugcolor>
ba7f043c 2946in the S<C<use L<re>>> pragma, as well as Perl's B<-Dr> command-line
4a4eefd0 2947switch documented in L<perlrun/"Command Switches">.
75e14d17
IZ
2948
2949=item Optimization of regular expressions
d74e8afc 2950X<regexp, optimization>
75e14d17 2951
7522fed5 2952This step is listed for completeness only. Since it does not change
75e14d17 2953semantics, details of this step are not documented and are subject
19799a22
GS
2954to change without notice. This step is performed over the finite
2955automaton that was generated during the previous pass.
2a94b7ce 2956
19799a22
GS
2957It is at this stage that C<split()> silently optimizes C</^/> to
2958mean C</^/m>.
75e14d17
IZ
2959
2960=back
2961
a0d0e21e 2962=head2 I/O Operators
d74e8afc 2963X<operator, i/o> X<operator, io> X<io> X<while> X<filehandle>
80a96bfc 2964X<< <> >> X<< <<>> >> X<@ARGV>
a0d0e21e 2965
54310121 2966There are several I/O operators you should know about.
fbad3eb5 2967
7b8d334a 2968A string enclosed by backticks (grave accents) first undergoes
19799a22
GS
2969double-quote interpolation. It is then interpreted as an external
2970command, and the output of that command is the value of the
e9c56f9b
JH
2971backtick string, like in a shell. In scalar context, a single string
2972consisting of all output is returned. In list context, a list of
2973values is returned, one per line of output. (You can set C<$/> to use
2974a different line terminator.) The command is executed each time the
2975pseudo-literal is evaluated. The status value of the command is
2976returned in C<$?> (see L<perlvar> for the interpretation of C<$?>).
2977Unlike in B<csh>, no translation is done on the return data--newlines
2978remain newlines. Unlike in any of the shells, single quotes do not
2979hide variable names in the command from interpretation. To pass a
2980literal dollar-sign through to the shell you need to hide it with a
2981backslash. The generalized form of backticks is C<qx//>. (Because
2982backticks always undergo shell expansion as well, see L<perlsec> for
2983security concerns.)
d74e8afc 2984X<qx> X<`> X<``> X<backtick> X<glob>
19799a22
GS
2985
2986In scalar context, evaluating a filehandle in angle brackets yields
2987the next line from that file (the newline, if any, included), or
2988C<undef> at end-of-file or on error. When C<$/> is set to C<undef>
2989(sometimes known as file-slurp mode) and the file is empty, it
2990returns C<''> the first time, followed by C<undef> subsequently.
2991
2992Ordinarily you must assign the returned value to a variable, but
2993there is one situation where an automatic assignment happens. If
2994and only if the input symbol is the only thing inside the conditional
2995of a C<while> statement (even if disguised as a C<for(;;)> loop),
ba7f043c 2996the value is automatically assigned to the global variable C<$_>,
19799a22
GS
2997destroying whatever was there previously. (This may seem like an
2998odd thing to you, but you'll use the construct in almost every Perl
ba7f043c
KW
2999script you write.) The C<$_> variable is not implicitly localized.
3000You'll have to put a S<C<local $_;>> before the loop if you want that
19799a22
GS
3001to happen.
3002
3003The following lines are equivalent:
a0d0e21e 3004
748a9306 3005 while (defined($_ = <STDIN>)) { print; }
7b8d334a 3006 while ($_ = <STDIN>) { print; }
a0d0e21e
LW
3007 while (<STDIN>) { print; }
3008 for (;<STDIN>;) { print; }
748a9306 3009 print while defined($_ = <STDIN>);
7b8d334a 3010 print while ($_ = <STDIN>);
a0d0e21e
LW
3011 print while <STDIN>;
3012
1ca345ed
TC
3013This also behaves similarly, but assigns to a lexical variable
3014instead of to C<$_>:
7b8d334a 3015
89d205f2 3016 while (my $line = <STDIN>) { print $line }
7b8d334a 3017
19799a22
GS
3018In these loop constructs, the assigned value (whether assignment
3019is automatic or explicit) is then tested to see whether it is
1ca345ed
TC
3020defined. The defined test avoids problems where the line has a string
3021value that would be treated as false by Perl; for example a "" or
ba7f043c 3022a C<"0"> with no trailing newline. If you really mean for such values
19799a22 3023to terminate the loop, they should be tested for explicitly:
7b8d334a
GS
3024
3025 while (($_ = <STDIN>) ne '0') { ... }
3026 while (<STDIN>) { last unless $_; ... }
3027
ba7f043c 3028In other boolean contexts, C<< <I<FILEHANDLE>> >> without an
5ef4d93e 3029explicit C<defined> test or comparison elicits a warning if the
ba7f043c 3030S<C<use warnings>> pragma or the B<-w>
19799a22 3031command-line switch (the C<$^W> variable) is in effect.
7b8d334a 3032
5f05dabc 3033The filehandles STDIN, STDOUT, and STDERR are predefined. (The
19799a22
GS
3034filehandles C<stdin>, C<stdout>, and C<stderr> will also work except
3035in packages, where they would be interpreted as local identifiers
3036rather than global.) Additional filehandles may be created with
ba7f043c 3037the C<open()> function, amongst others. See L<perlopentut> and
19799a22 3038L<perlfunc/open> for details on this.
d74e8afc 3039X<stdin> X<stdout> X<sterr>
a0d0e21e 3040
ba7f043c 3041If a C<< <I<FILEHANDLE>> >> is used in a context that is looking for
19799a22
GS
3042a list, a list comprising all input lines is returned, one line per
3043list element. It's easy to grow to a rather large data space this
3044way, so use with care.
a0d0e21e 3045
ba7f043c 3046C<< <I<FILEHANDLE>> >> may also be spelled C<readline(*I<FILEHANDLE>)>.
19799a22 3047See L<perlfunc/readline>.
fbad3eb5 3048
ba7f043c 3049The null filehandle C<< <> >> is special: it can be used to emulate the
1ca345ed
TC
3050behavior of B<sed> and B<awk>, and any other Unix filter program
3051that takes a list of filenames, doing the same to each line
ba7f043c 3052of input from all of them. Input from C<< <> >> comes either from
a0d0e21e 3053standard input, or from each file listed on the command line. Here's
ba7f043c
KW
3054how it works: the first time C<< <> >> is evaluated, the C<@ARGV> array is
3055checked, and if it is empty, C<$ARGV[0]> is set to C<"-">, which when opened
3056gives you standard input. The C<@ARGV> array is then processed as a list
a0d0e21e
LW
3057of filenames. The loop
3058
3059 while (<>) {
3060 ... # code for each line
3061 }
3062
3063is equivalent to the following Perl-like pseudo code:
3064
3e3baf6d 3065 unshift(@ARGV, '-') unless @ARGV;
a0d0e21e
LW
3066 while ($ARGV = shift) {
3067 open(ARGV, $ARGV);
3068 while (<ARGV>) {
3069 ... # code for each line
3070 }
3071 }
3072
19799a22 3073except that it isn't so cumbersome to say, and will actually work.
ba7f043c
KW
3074It really does shift the C<@ARGV> array and put the current filename
3075into the C<$ARGV> variable. It also uses filehandle I<ARGV>
3076internally. C<< <> >> is just a synonym for C<< <ARGV> >>, which
19799a22 3077is magical. (The pseudo code above doesn't work because it treats
ba7f043c 3078C<< <ARGV> >> as non-magical.)
a0d0e21e 3079
48ab5743
ML
3080Since the null filehandle uses the two argument form of L<perlfunc/open>
3081it interprets special characters, so if you have a script like this:
3082
3083 while (<>) {
3084 print;
3085 }
3086
ba7f043c 3087and call it with S<C<perl dangerous.pl 'rm -rfv *|'>>, it actually opens a
48ab5743
ML
3088pipe, executes the C<rm> command and reads C<rm>'s output from that pipe.
3089If you want all items in C<@ARGV> to be interpreted as file names, you
1033ba6e
PM
3090can use the module C<ARGV::readonly> from CPAN, or use the double bracket:
3091
3092 while (<<>>) {
3093 print;
3094 }
3095
3096Using double angle brackets inside of a while causes the open to use the
3097three argument form (with the second argument being C<< < >>), so all
ba7f043c
KW
3098arguments in C<ARGV> are treated as literal filenames (including C<"-">).
3099(Note that for convenience, if you use C<< <<>> >> and if C<@ARGV> is
80a96bfc 3100empty, it will still read from the standard input.)
48ab5743 3101
ba7f043c 3102You can modify C<@ARGV> before the first C<< <> >> as long as the array ends up
a0d0e21e 3103containing the list of filenames you really want. Line numbers (C<$.>)
19799a22
GS
3104continue as though the input were one big happy file. See the example
3105in L<perlfunc/eof> for how to reset line numbers on each file.
5a964f20 3106
ba7f043c
KW
3107If you want to set C<@ARGV> to your own list of files, go right ahead.
3108This sets C<@ARGV> to all plain text files if no C<@ARGV> was given:
5a964f20
TC
3109
3110 @ARGV = grep { -f && -T } glob('*') unless @ARGV;
a0d0e21e 3111
5a964f20
TC
3112You can even set them to pipe commands. For example, this automatically
3113filters compressed arguments through B<gzip>:
3114
3115 @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc < $_ |" : $_ } @ARGV;
3116
3117If you want to pass switches into your script, you can use one of the
ba7f043c 3118C<Getopts> modules or put a loop on the front like this:
a0d0e21e
LW
3119
3120 while ($_ = $ARGV[0], /^-/) {
3121 shift;
3122 last if /^--$/;
3123 if (/^-D(.*)/) { $debug = $1 }
3124 if (/^-v/) { $verbose++ }
5a964f20 3125 # ... # other switches
a0d0e21e 3126 }
5a964f20 3127
a0d0e21e 3128 while (<>) {
5a964f20 3129 # ... # code for each line
a0d0e21e
LW
3130 }
3131
ba7f043c 3132The C<< <> >> symbol will return C<undef> for end-of-file only once.
89d205f2 3133If you call it again after this, it will assume you are processing another
ba7f043c 3134C<@ARGV> list, and if you haven't set C<@ARGV>, will read input from STDIN.
a0d0e21e 3135
1ca345ed 3136If what the angle brackets contain is a simple scalar variable (for example,
ba7f043c 3137C<$foo>), then that variable contains the name of the
19799a22
GS
3138filehandle to input from, or its typeglob, or a reference to the
3139same. For example:
cb1a09d0
AD
3140
3141 $fh = \*STDIN;
3142 $line = <$fh>;
a0d0e21e 3143
5a964f20
TC
3144If what's within the angle brackets is neither a filehandle nor a simple
3145scalar variable containing a filehandle name, typeglob, or typeglob
3146reference, it is interpreted as a filename pattern to be globbed, and
3147either a list of filenames or the next filename in the list is returned,
19799a22 3148depending on context. This distinction is determined on syntactic
ba7f043c
KW
3149grounds alone. That means C<< <$x> >> is always a C<readline()> from
3150an indirect handle, but C<< <$hash{key}> >> is always a C<glob()>.
3151That's because C<$x> is a simple scalar variable, but C<$hash{key}> is
ef191992
YST
3152not--it's a hash element. Even C<< <$x > >> (note the extra space)
3153is treated as C<glob("$x ")>, not C<readline($x)>.
5a964f20
TC
3154
3155One level of double-quote interpretation is done first, but you can't
35f2feb0 3156say C<< <$foo> >> because that's an indirect filehandle as explained
5a964f20
TC
3157in the previous paragraph. (In older versions of Perl, programmers
3158would insert curly brackets to force interpretation as a filename glob:
35f2feb0 3159C<< <${foo}> >>. These days, it's considered cleaner to call the
5a964f20 3160internal function directly as C<glob($foo)>, which is probably the right
19799a22 3161way to have done it in the first place.) For example:
a0d0e21e
LW
3162
3163 while (<*.c>) {
3164 chmod 0644, $_;
3165 }
3166
3a4b19e4 3167is roughly equivalent to:
a0d0e21e
LW
3168
3169 open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|");
3170 while (<FOO>) {
5b3eff12 3171 chomp;
a0d0e21e
LW
3172 chmod 0644, $_;
3173 }
3174
3a4b19e4 3175except that the globbing is actually done internally using the standard
ba7f043c 3176C<L<File::Glob>> extension. Of course, the shortest way to do the above is:
a0d0e21e
LW
3177
3178 chmod 0644, <*.c>;
3179
19799a22
GS
3180A (file)glob evaluates its (embedded) argument only when it is
3181starting a new list. All values must be read before it will start
3182over. In list context, this isn't important because you automatically
3183get them all anyway. However, in scalar context the operator returns
069e01df 3184the next value each time it's called, or C<undef> when the list has
19799a22
GS
3185run out. As with filehandle reads, an automatic C<defined> is
3186generated when the glob occurs in the test part of a C<while>,
1ca345ed
TC
3187because legal glob returns (for example,
3188a file called F<0>) would otherwise
19799a22
GS
3189terminate the loop. Again, C<undef> is returned only once. So if
3190you're expecting a single value from a glob, it is much better to
3191say
4633a7c4
LW
3192
3193 ($file) = <blurch*>;
3194
3195than
3196
3197 $file = <blurch*>;
3198
3199because the latter will alternate between returning a filename and
19799a22 3200returning false.
4633a7c4 3201
b159ebd3 3202If you're trying to do variable interpolation, it's definitely better
ba7f043c 3203to use the C<glob()> function, because the older notation can cause people
e37d713d 3204to become confused with the indirect filehandle notation.
4633a7c4
LW
3205
3206 @files = glob("$dir/*.[ch]");
3207 @files = glob($files[$i]);
3208
a0d0e21e 3209=head2 Constant Folding
d74e8afc 3210X<constant folding> X<folding>
a0d0e21e
LW
3211
3212Like C, Perl does a certain amount of expression evaluation at
19799a22 3213compile time whenever it determines that all arguments to an
a0d0e21e
LW
3214operator are static and have no side effects. In particular, string
3215concatenation happens at compile time between literals that don't do
19799a22 3216variable substitution. Backslash interpolation also happens at
a0d0e21e
LW
3217compile time. You can say
3218
1ca345ed
TC
3219 'Now is the time for all'
3220 . "\n"
3221 . 'good men to come to.'
a0d0e21e 3222
54310121 3223and this all reduces to one string internally. Likewise, if
a0d0e21e
LW
3224you say
3225
3226 foreach $file (@filenames) {
5a964f20 3227 if (-s $file > 5 + 100 * 2**16) { }
54310121 3228 }
a0d0e21e 3229
1ca345ed 3230the compiler precomputes the number which that expression
19799a22 3231represents so that the interpreter won't have to.
a0d0e21e 3232
fd1abbef 3233=head2 No-ops
d74e8afc 3234X<no-op> X<nop>
fd1abbef
DN
3235
3236Perl doesn't officially have a no-op operator, but the bare constants
1ca345ed 3237C<0> and C<1> are special-cased not to produce a warning in void
fd1abbef
DN
3238context, so you can for example safely do
3239
3240 1 while foo();
3241
2c268ad5 3242=head2 Bitwise String Operators
fb7054ba 3243X<operator, bitwise, string> X<&.> X<|.> X<^.> X<~.>
2c268ad5
TP
3244
3245Bitstrings of any size may be manipulated by the bitwise operators
3246(C<~ | & ^>).
3247
19799a22
GS
3248If the operands to a binary bitwise op are strings of different
3249sizes, B<|> and B<^> ops act as though the shorter operand had
3250additional zero bits on the right, while the B<&> op acts as though
3251the longer operand were truncated to the length of the shorter.
3252The granularity for such extension or truncation is one or more
3253bytes.