This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate perlio:
[perl5.git] / pod / perlop.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlop - Perl operators and precedence
4
5=head1 SYNOPSIS
6
7Perl operators have the following associativity and precedence,
19799a22
GS
8listed from highest precedence to lowest. Operators borrowed from
9C keep the same precedence relationship with each other, even where
10C's precedence is slightly screwy. (This makes learning Perl easier
11for C folks.) With very few exceptions, these all operate on scalar
12values only, not array values.
a0d0e21e
LW
13
14 left terms and list operators (leftward)
15 left ->
16 nonassoc ++ --
17 right **
18 right ! ~ \ and unary + and -
54310121 19 left =~ !~
a0d0e21e
LW
20 left * / % x
21 left + - .
22 left << >>
23 nonassoc named unary operators
24 nonassoc < > <= >= lt gt le ge
25 nonassoc == != <=> eq ne cmp
26 left &
27 left | ^
28 left &&
29 left ||
137443ea 30 nonassoc .. ...
a0d0e21e
LW
31 right ?:
32 right = += -= *= etc.
33 left , =>
34 nonassoc list operators (rightward)
a5f75d66 35 right not
a0d0e21e
LW
36 left and
37 left or xor
38
39In the following sections, these operators are covered in precedence order.
40
5a964f20
TC
41Many operators can be overloaded for objects. See L<overload>.
42
cb1a09d0 43=head1 DESCRIPTION
a0d0e21e
LW
44
45=head2 Terms and List Operators (Leftward)
46
62c18ce2 47A TERM has the highest precedence in Perl. They include variables,
5f05dabc 48quote and quote-like operators, any expression in parentheses,
a0d0e21e
LW
49and any function whose arguments are parenthesized. Actually, there
50aren't really functions in this sense, just list operators and unary
51operators behaving as functions because you put parentheses around
52the arguments. These are all documented in L<perlfunc>.
53
54If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
55is followed by a left parenthesis as the next token, the operator and
56arguments within parentheses are taken to be of highest precedence,
57just like a normal function call.
58
59In the absence of parentheses, the precedence of list operators such as
60C<print>, C<sort>, or C<chmod> is either very high or very low depending on
54310121 61whether you are looking at the left side or the right side of the operator.
a0d0e21e
LW
62For example, in
63
64 @ary = (1, 3, sort 4, 2);
65 print @ary; # prints 1324
66
19799a22
GS
67the commas on the right of the sort are evaluated before the sort,
68but the commas on the left are evaluated after. In other words,
69list operators tend to gobble up all arguments that follow, and
a0d0e21e 70then act like a simple TERM with regard to the preceding expression.
19799a22 71Be careful with parentheses:
a0d0e21e
LW
72
73 # These evaluate exit before doing the print:
74 print($foo, exit); # Obviously not what you want.
75 print $foo, exit; # Nor is this.
76
77 # These do the print before evaluating exit:
78 (print $foo), exit; # This is what you want.
79 print($foo), exit; # Or this.
80 print ($foo), exit; # Or even this.
81
82Also note that
83
84 print ($foo & 255) + 1, "\n";
85
54310121 86probably doesn't do what you expect at first glance. See
a0d0e21e
LW
87L<Named Unary Operators> for more discussion of this.
88
89Also parsed as terms are the C<do {}> and C<eval {}> constructs, as
54310121 90well as subroutine and method calls, and the anonymous
a0d0e21e
LW
91constructors C<[]> and C<{}>.
92
2ae324a7 93See also L<Quote and Quote-like Operators> toward the end of this section,
c07a80fd 94as well as L<"I/O Operators">.
a0d0e21e
LW
95
96=head2 The Arrow Operator
97
35f2feb0 98"C<< -> >>" is an infix dereference operator, just as it is in C
19799a22
GS
99and C++. If the right side is either a C<[...]>, C<{...}>, or a
100C<(...)> subscript, then the left side must be either a hard or
101symbolic reference to an array, a hash, or a subroutine respectively.
102(Or technically speaking, a location capable of holding a hard
103reference, if it's an array or hash reference being used for
104assignment.) See L<perlreftut> and L<perlref>.
a0d0e21e 105
19799a22
GS
106Otherwise, the right side is a method name or a simple scalar
107variable containing either the method name or a subroutine reference,
108and the left side must be either an object (a blessed reference)
109or a class name (that is, a package name). See L<perlobj>.
a0d0e21e 110
5f05dabc 111=head2 Auto-increment and Auto-decrement
a0d0e21e
LW
112
113"++" and "--" work as in C. That is, if placed before a variable, they
114increment or decrement the variable before returning the value, and if
115placed after, increment or decrement the variable after returning the value.
116
54310121 117The auto-increment operator has a little extra builtin magic to it. If
a0d0e21e
LW
118you increment a variable that is numeric, or that has ever been used in
119a numeric context, you get a normal increment. If, however, the
5f05dabc 120variable has been used in only string contexts since it was set, and
5a964f20 121has a value that is not the empty string and matches the pattern
9c0670e1 122C</^[a-zA-Z]*[0-9]*\z/>, the increment is done as a string, preserving each
a0d0e21e
LW
123character within its range, with carry:
124
125 print ++($foo = '99'); # prints '100'
126 print ++($foo = 'a0'); # prints 'a1'
127 print ++($foo = 'Az'); # prints 'Ba'
128 print ++($foo = 'zz'); # prints 'aaa'
129
5f05dabc 130The auto-decrement operator is not magical.
a0d0e21e
LW
131
132=head2 Exponentiation
133
19799a22 134Binary "**" is the exponentiation operator. It binds even more
cb1a09d0
AD
135tightly than unary minus, so -2**4 is -(2**4), not (-2)**4. (This is
136implemented using C's pow(3) function, which actually works on doubles
137internally.)
a0d0e21e
LW
138
139=head2 Symbolic Unary Operators
140
5f05dabc 141Unary "!" performs logical negation, i.e., "not". See also C<not> for a lower
a0d0e21e
LW
142precedence version of this.
143
144Unary "-" performs arithmetic negation if the operand is numeric. If
145the operand is an identifier, a string consisting of a minus sign
146concatenated with the identifier is returned. Otherwise, if the string
147starts with a plus or minus, a string starting with the opposite sign
148is returned. One effect of these rules is that C<-bareword> is equivalent
149to C<"-bareword">.
150
972b05a9
JH
151Unary "~" performs bitwise negation, i.e., 1's complement. For
152example, C<0666 & ~027> is 0640. (See also L<Integer Arithmetic> and
153L<Bitwise String Operators>.) Note that the width of the result is
154platform-dependent: ~0 is 32 bits wide on a 32-bit platform, but 64
155bits wide on a 64-bit platform, so if you are expecting a certain bit
156width, remember use the & operator to mask off the excess bits.
a0d0e21e
LW
157
158Unary "+" has no effect whatsoever, even on strings. It is useful
159syntactically for separating a function name from a parenthesized expression
160that would otherwise be interpreted as the complete list of function
5ba421f6 161arguments. (See examples above under L<Terms and List Operators (Leftward)>.)
a0d0e21e 162
19799a22
GS
163Unary "\" creates a reference to whatever follows it. See L<perlreftut>
164and L<perlref>. Do not confuse this behavior with the behavior of
165backslash within a string, although both forms do convey the notion
166of protecting the next thing from interpolation.
a0d0e21e
LW
167
168=head2 Binding Operators
169
c07a80fd 170Binary "=~" binds a scalar expression to a pattern match. Certain operations
cb1a09d0
AD
171search or modify the string $_ by default. This operator makes that kind
172of operation work on some other string. The right argument is a search
2c268ad5
TP
173pattern, substitution, or transliteration. The left argument is what is
174supposed to be searched, substituted, or transliterated instead of the default
f8bab1e9
GS
175$_. When used in scalar context, the return value generally indicates the
176success of the operation. Behavior in list context depends on the particular
177operator. See L</"Regexp Quote-Like Operators"> for details.
178
179If the right argument is an expression rather than a search pattern,
2c268ad5 180substitution, or transliteration, it is interpreted as a search pattern at run
2decb4fb
GS
181time. This can be less efficient than an explicit search, because the
182pattern must be compiled every time the expression is evaluated.
a0d0e21e
LW
183
184Binary "!~" is just like "=~" except the return value is negated in
185the logical sense.
186
187=head2 Multiplicative Operators
188
189Binary "*" multiplies two numbers.
190
191Binary "/" divides two numbers.
192
54310121
PP
193Binary "%" computes the modulus of two numbers. Given integer
194operands C<$a> and C<$b>: If C<$b> is positive, then C<$a % $b> is
195C<$a> minus the largest multiple of C<$b> that is not greater than
196C<$a>. If C<$b> is negative, then C<$a % $b> is C<$a> minus the
197smallest multiple of C<$b> that is not less than C<$a> (i.e. the
6bb4e6d4 198result will be less than or equal to zero).
f3798619 199Note than when C<use integer> is in scope, "%" gives you direct access
55d729e4
GS
200to the modulus operator as implemented by your C compiler. This
201operator is not as well defined for negative operands, but it will
202execute faster.
203
62d10b70
GS
204Binary "x" is the repetition operator. In scalar context or if the left
205operand is not enclosed in parentheses, it returns a string consisting
206of the left operand repeated the number of times specified by the right
207operand. In list context, if the left operand is enclosed in
208parentheses, it repeats the list.
a0d0e21e
LW
209
210 print '-' x 80; # print row of dashes
211
212 print "\t" x ($tab/8), ' ' x ($tab%8); # tab over
213
214 @ones = (1) x 80; # a list of 80 1's
215 @ones = (5) x @ones; # set all elements to 5
216
217
218=head2 Additive Operators
219
220Binary "+" returns the sum of two numbers.
221
222Binary "-" returns the difference of two numbers.
223
224Binary "." concatenates two strings.
225
226=head2 Shift Operators
227
55497cff
PP
228Binary "<<" returns the value of its left argument shifted left by the
229number of bits specified by the right argument. Arguments should be
982ce180 230integers. (See also L<Integer Arithmetic>.)
a0d0e21e 231
55497cff
PP
232Binary ">>" returns the value of its left argument shifted right by
233the number of bits specified by the right argument. Arguments should
982ce180 234be integers. (See also L<Integer Arithmetic>.)
a0d0e21e 235
b16cf6df
JH
236Note that both "<<" and ">>" in Perl are implemented directly using
237"<<" and ">>" in C. If C<use integer> (see L<Integer Arithmetic>) is
238in force then signed C integers are used, else unsigned C integers are
239used. Either way, the implementation isn't going to generate results
240larger than the size of the integer type Perl was built with (32 bits
241or 64 bits).
242
243The result of overflowing the range of the integers is undefined
244because it is undefined also in C. In other words, using 32-bit
245integers, C<< 1 << 32 >> is undefined. Shifting by a negative number
246of bits is also undefined.
247
a0d0e21e
LW
248=head2 Named Unary Operators
249
250The various named unary operators are treated as functions with one
251argument, with optional parentheses. These include the filetest
252operators, like C<-f>, C<-M>, etc. See L<perlfunc>.
253
254If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
255is followed by a left parenthesis as the next token, the operator and
256arguments within parentheses are taken to be of highest precedence,
3981b0eb 257just like a normal function call. For example,
258because named unary operators are higher precedence than ||:
a0d0e21e
LW
259
260 chdir $foo || die; # (chdir $foo) || die
261 chdir($foo) || die; # (chdir $foo) || die
262 chdir ($foo) || die; # (chdir $foo) || die
263 chdir +($foo) || die; # (chdir $foo) || die
264
3981b0eb 265but, because * is higher precedence than named operators:
a0d0e21e
LW
266
267 chdir $foo * 20; # chdir ($foo * 20)
268 chdir($foo) * 20; # (chdir $foo) * 20
269 chdir ($foo) * 20; # (chdir $foo) * 20
270 chdir +($foo) * 20; # chdir ($foo * 20)
271
272 rand 10 * 20; # rand (10 * 20)
273 rand(10) * 20; # (rand 10) * 20
274 rand (10) * 20; # (rand 10) * 20
275 rand +(10) * 20; # rand (10 * 20)
276
5ba421f6 277See also L<"Terms and List Operators (Leftward)">.
a0d0e21e
LW
278
279=head2 Relational Operators
280
35f2feb0 281Binary "<" returns true if the left argument is numerically less than
a0d0e21e
LW
282the right argument.
283
35f2feb0 284Binary ">" returns true if the left argument is numerically greater
a0d0e21e
LW
285than the right argument.
286
35f2feb0 287Binary "<=" returns true if the left argument is numerically less than
a0d0e21e
LW
288or equal to the right argument.
289
35f2feb0 290Binary ">=" returns true if the left argument is numerically greater
a0d0e21e
LW
291than or equal to the right argument.
292
293Binary "lt" returns true if the left argument is stringwise less than
294the right argument.
295
296Binary "gt" returns true if the left argument is stringwise greater
297than the right argument.
298
299Binary "le" returns true if the left argument is stringwise less than
300or equal to the right argument.
301
302Binary "ge" returns true if the left argument is stringwise greater
303than or equal to the right argument.
304
305=head2 Equality Operators
306
307Binary "==" returns true if the left argument is numerically equal to
308the right argument.
309
310Binary "!=" returns true if the left argument is numerically not equal
311to the right argument.
312
35f2feb0 313Binary "<=>" returns -1, 0, or 1 depending on whether the left
6ee5d4e7 314argument is numerically less than, equal to, or greater than the right
d4ad863d 315argument. If your platform supports NaNs (not-a-numbers) as numeric
7d3a9d88
NC
316values, using them with "<=>" returns undef. NaN is not "<", "==", ">",
317"<=" or ">=" anything (even NaN), so those 5 return false. NaN != NaN
318returns true, as does NaN != anything else. If your platform doesn't
319support NaNs then NaN is just a string with numeric value 0.
320
321 perl -le '$a = NaN; print "No NaN support here" if $a == $a'
322 perl -le '$a = NaN; print "NaN support here" if $a != $a'
a0d0e21e
LW
323
324Binary "eq" returns true if the left argument is stringwise equal to
325the right argument.
326
327Binary "ne" returns true if the left argument is stringwise not equal
328to the right argument.
329
d4ad863d
JH
330Binary "cmp" returns -1, 0, or 1 depending on whether the left
331argument is stringwise less than, equal to, or greater than the right
332argument.
a0d0e21e 333
a034a98d
DD
334"lt", "le", "ge", "gt" and "cmp" use the collation (sort) order specified
335by the current locale if C<use locale> is in effect. See L<perllocale>.
336
a0d0e21e
LW
337=head2 Bitwise And
338
339Binary "&" returns its operators ANDed together bit by bit.
2c268ad5 340(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
a0d0e21e
LW
341
342=head2 Bitwise Or and Exclusive Or
343
344Binary "|" returns its operators ORed together bit by bit.
2c268ad5 345(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
a0d0e21e
LW
346
347Binary "^" returns its operators XORed together bit by bit.
2c268ad5 348(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
a0d0e21e
LW
349
350=head2 C-style Logical And
351
352Binary "&&" performs a short-circuit logical AND operation. That is,
353if the left operand is false, the right operand is not even evaluated.
354Scalar or list context propagates down to the right operand if it
355is evaluated.
356
357=head2 C-style Logical Or
358
359Binary "||" performs a short-circuit logical OR operation. That is,
360if the left operand is true, the right operand is not even evaluated.
361Scalar or list context propagates down to the right operand if it
362is evaluated.
363
364The C<||> and C<&&> operators differ from C's in that, rather than returning
3650 or 1, they return the last value evaluated. Thus, a reasonably portable
366way to find out the home directory (assuming it's not "0") might be:
367
368 $home = $ENV{'HOME'} || $ENV{'LOGDIR'} ||
369 (getpwuid($<))[7] || die "You're homeless!\n";
370
5a964f20
TC
371In particular, this means that you shouldn't use this
372for selecting between two aggregates for assignment:
373
374 @a = @b || @c; # this is wrong
375 @a = scalar(@b) || @c; # really meant this
376 @a = @b ? @b : @c; # this works fine, though
377
378As more readable alternatives to C<&&> and C<||> when used for
379control flow, Perl provides C<and> and C<or> operators (see below).
380The short-circuit behavior is identical. The precedence of "and" and
381"or" is much lower, however, so that you can safely use them after a
382list operator without the need for parentheses:
a0d0e21e
LW
383
384 unlink "alpha", "beta", "gamma"
385 or gripe(), next LINE;
386
387With the C-style operators that would have been written like this:
388
389 unlink("alpha", "beta", "gamma")
390 || (gripe(), next LINE);
391
eeb6a2c9 392Using "or" for assignment is unlikely to do what you want; see below.
5a964f20
TC
393
394=head2 Range Operators
a0d0e21e
LW
395
396Binary ".." is the range operator, which is really two different
5a964f20 397operators depending on the context. In list context, it returns an
2cdbc966
JD
398array of values counting (up by ones) from the left value to the right
399value. If the left value is greater than the right value then it
400returns the empty array. The range operator is useful for writing
401C<foreach (1..10)> loops and for doing slice operations on arrays. In
402the current implementation, no temporary array is created when the
403range operator is used as the expression in C<foreach> loops, but older
404versions of Perl might burn a lot of memory when you write something
405like this:
a0d0e21e
LW
406
407 for (1 .. 1_000_000) {
408 # code
54310121 409 }
a0d0e21e 410
5a964f20 411In scalar context, ".." returns a boolean value. The operator is
a0d0e21e
LW
412bistable, like a flip-flop, and emulates the line-range (comma) operator
413of B<sed>, B<awk>, and various editors. Each ".." operator maintains its
414own boolean state. It is false as long as its left operand is false.
415Once the left operand is true, the range operator stays true until the
416right operand is true, I<AFTER> which the range operator becomes false
19799a22 417again. It doesn't become false till the next time the range operator is
a0d0e21e
LW
418evaluated. It can test the right operand and become false on the same
419evaluation it became true (as in B<awk>), but it still returns true once.
19799a22
GS
420If you don't want it to test the right operand till the next
421evaluation, as in B<sed>, just use three dots ("...") instead of
422two. In all other regards, "..." behaves just like ".." does.
423
424The right operand is not evaluated while the operator is in the
425"false" state, and the left operand is not evaluated while the
426operator is in the "true" state. The precedence is a little lower
427than || and &&. The value returned is either the empty string for
428false, or a sequence number (beginning with 1) for true. The
429sequence number is reset for each range encountered. The final
430sequence number in a range has the string "E0" appended to it, which
431doesn't affect its numeric value, but gives you something to search
432for if you want to exclude the endpoint. You can exclude the
433beginning point by waiting for the sequence number to be greater
434than 1. If either operand of scalar ".." is a constant expression,
435that operand is implicitly compared to the C<$.> variable, the
436current line number. Examples:
a0d0e21e
LW
437
438As a scalar operator:
439
440 if (101 .. 200) { print; } # print 2nd hundred lines
441 next line if (1 .. /^$/); # skip header lines
442 s/^/> / if (/^$/ .. eof()); # quote body
443
5a964f20
TC
444 # parse mail messages
445 while (<>) {
446 $in_header = 1 .. /^$/;
447 $in_body = /^$/ .. eof();
448 # do something based on those
449 } continue {
450 close ARGV if eof; # reset $. each file
451 }
452
a0d0e21e
LW
453As a list operator:
454
455 for (101 .. 200) { print; } # print $_ 100 times
3e3baf6d 456 @foo = @foo[0 .. $#foo]; # an expensive no-op
a0d0e21e
LW
457 @foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items
458
5a964f20 459The range operator (in list context) makes use of the magical
5f05dabc 460auto-increment algorithm if the operands are strings. You
a0d0e21e
LW
461can say
462
463 @alphabet = ('A' .. 'Z');
464
19799a22 465to get all normal letters of the alphabet, or
a0d0e21e
LW
466
467 $hexdigit = (0 .. 9, 'a' .. 'f')[$num & 15];
468
469to get a hexadecimal digit, or
470
471 @z2 = ('01' .. '31'); print $z2[$mday];
472
473to get dates with leading zeros. If the final value specified is not
474in the sequence that the magical increment would produce, the sequence
475goes until the next value would be longer than the final value
476specified.
477
478=head2 Conditional Operator
479
480Ternary "?:" is the conditional operator, just as in C. It works much
481like an if-then-else. If the argument before the ? is true, the
482argument before the : is returned, otherwise the argument after the :
cb1a09d0
AD
483is returned. For example:
484
54310121 485 printf "I have %d dog%s.\n", $n,
cb1a09d0
AD
486 ($n == 1) ? '' : "s";
487
488Scalar or list context propagates downward into the 2nd
54310121 489or 3rd argument, whichever is selected.
cb1a09d0
AD
490
491 $a = $ok ? $b : $c; # get a scalar
492 @a = $ok ? @b : @c; # get an array
493 $a = $ok ? @b : @c; # oops, that's just a count!
494
495The operator may be assigned to if both the 2nd and 3rd arguments are
496legal lvalues (meaning that you can assign to them):
a0d0e21e
LW
497
498 ($a_or_b ? $a : $b) = $c;
499
5a964f20
TC
500Because this operator produces an assignable result, using assignments
501without parentheses will get you in trouble. For example, this:
502
503 $a % 2 ? $a += 10 : $a += 2
504
505Really means this:
506
507 (($a % 2) ? ($a += 10) : $a) += 2
508
509Rather than this:
510
511 ($a % 2) ? ($a += 10) : ($a += 2)
512
19799a22
GS
513That should probably be written more simply as:
514
515 $a += ($a % 2) ? 10 : 2;
516
4633a7c4 517=head2 Assignment Operators
a0d0e21e
LW
518
519"=" is the ordinary assignment operator.
520
521Assignment operators work as in C. That is,
522
523 $a += 2;
524
525is equivalent to
526
527 $a = $a + 2;
528
529although without duplicating any side effects that dereferencing the lvalue
54310121
PP
530might trigger, such as from tie(). Other assignment operators work similarly.
531The following are recognized:
a0d0e21e
LW
532
533 **= += *= &= <<= &&=
534 -= /= |= >>= ||=
535 .= %= ^=
536 x=
537
19799a22 538Although these are grouped by family, they all have the precedence
a0d0e21e
LW
539of assignment.
540
b350dd2f
GS
541Unlike in C, the scalar assignment operator produces a valid lvalue.
542Modifying an assignment is equivalent to doing the assignment and
543then modifying the variable that was assigned to. This is useful
544for modifying a copy of something, like this:
a0d0e21e
LW
545
546 ($tmp = $global) =~ tr [A-Z] [a-z];
547
548Likewise,
549
550 ($a += 2) *= 3;
551
552is equivalent to
553
554 $a += 2;
555 $a *= 3;
556
b350dd2f
GS
557Similarly, a list assignment in list context produces the list of
558lvalues assigned to, and a list assignment in scalar context returns
559the number of elements produced by the expression on the right hand
560side of the assignment.
561
748a9306 562=head2 Comma Operator
a0d0e21e 563
5a964f20 564Binary "," is the comma operator. In scalar context it evaluates
a0d0e21e
LW
565its left argument, throws that value away, then evaluates its right
566argument and returns that value. This is just like C's comma operator.
567
5a964f20 568In list context, it's just the list argument separator, and inserts
a0d0e21e
LW
569both its arguments into the list.
570
35f2feb0 571The => digraph is mostly just a synonym for the comma operator. It's useful for
cb1a09d0 572documenting arguments that come in pairs. As of release 5.001, it also forces
4633a7c4 573any word to the left of it to be interpreted as a string.
748a9306 574
a0d0e21e
LW
575=head2 List Operators (Rightward)
576
577On the right side of a list operator, it has very low precedence,
578such that it controls all comma-separated expressions found there.
579The only operators with lower precedence are the logical operators
580"and", "or", and "not", which may be used to evaluate calls to list
581operators without the need for extra parentheses:
582
583 open HANDLE, "filename"
584 or die "Can't open: $!\n";
585
5ba421f6 586See also discussion of list operators in L<Terms and List Operators (Leftward)>.
a0d0e21e
LW
587
588=head2 Logical Not
589
590Unary "not" returns the logical negation of the expression to its right.
591It's the equivalent of "!" except for the very low precedence.
592
593=head2 Logical And
594
595Binary "and" returns the logical conjunction of the two surrounding
596expressions. It's equivalent to && except for the very low
5f05dabc 597precedence. This means that it short-circuits: i.e., the right
a0d0e21e
LW
598expression is evaluated only if the left expression is true.
599
600=head2 Logical or and Exclusive Or
601
602Binary "or" returns the logical disjunction of the two surrounding
5a964f20
TC
603expressions. It's equivalent to || except for the very low precedence.
604This makes it useful for control flow
605
606 print FH $data or die "Can't write to FH: $!";
607
608This means that it short-circuits: i.e., the right expression is evaluated
609only if the left expression is false. Due to its precedence, you should
610probably avoid using this for assignment, only for control flow.
611
612 $a = $b or $c; # bug: this is wrong
613 ($a = $b) or $c; # really means this
614 $a = $b || $c; # better written this way
615
19799a22 616However, when it's a list-context assignment and you're trying to use
5a964f20
TC
617"||" for control flow, you probably need "or" so that the assignment
618takes higher precedence.
619
620 @info = stat($file) || die; # oops, scalar sense of stat!
621 @info = stat($file) or die; # better, now @info gets its due
622
19799a22 623Then again, you could always use parentheses.
a0d0e21e
LW
624
625Binary "xor" returns the exclusive-OR of the two surrounding expressions.
626It cannot short circuit, of course.
627
628=head2 C Operators Missing From Perl
629
630Here is what C has that Perl doesn't:
631
632=over 8
633
634=item unary &
635
636Address-of operator. (But see the "\" operator for taking a reference.)
637
638=item unary *
639
54310121 640Dereference-address operator. (Perl's prefix dereferencing
a0d0e21e
LW
641operators are typed: $, @, %, and &.)
642
643=item (TYPE)
644
19799a22 645Type-casting operator.
a0d0e21e
LW
646
647=back
648
5f05dabc 649=head2 Quote and Quote-like Operators
a0d0e21e
LW
650
651While we usually think of quotes as literal values, in Perl they
652function as operators, providing various kinds of interpolating and
653pattern matching capabilities. Perl provides customary quote characters
654for these behaviors, but also provides a way for you to choose your
655quote character for any of them. In the following table, a C<{}> represents
87275199 656any pair of delimiters you choose.
a0d0e21e 657
2c268ad5
TP
658 Customary Generic Meaning Interpolates
659 '' q{} Literal no
660 "" qq{} Literal yes
af9219ee 661 `` qx{} Command yes*
2c268ad5 662 qw{} Word list no
af9219ee
MG
663 // m{} Pattern match yes*
664 qr{} Pattern yes*
665 s{}{} Substitution yes*
2c268ad5 666 tr{}{} Transliteration no (but see below)
a0d0e21e 667
af9219ee
MG
668 * unless the delimiter is ''.
669
87275199
GS
670Non-bracketing delimiters use the same character fore and aft, but the four
671sorts of brackets (round, angle, square, curly) will all nest, which means
672that
673
674 q{foo{bar}baz}
35f2feb0 675
87275199
GS
676is the same as
677
678 'foo{bar}baz'
679
680Note, however, that this does not always work for quoting Perl code:
681
682 $s = q{ if($a eq "}") ... }; # WRONG
683
83df6a1d
JH
684is a syntax error. The C<Text::Balanced> module (from CPAN, and
685starting from Perl 5.8 part of the standard distribution) is able
686to do this properly.
87275199 687
19799a22 688There can be whitespace between the operator and the quoting
fb73857a 689characters, except when C<#> is being used as the quoting character.
19799a22
GS
690C<q#foo#> is parsed as the string C<foo>, while C<q #foo#> is the
691operator C<q> followed by a comment. Its argument will be taken
692from the next line. This allows you to write:
fb73857a
PP
693
694 s {foo} # Replace foo
695 {bar} # with bar.
696
904501ec
MG
697The following escape sequences are available in constructs that interpolate
698and in transliterations.
a0d0e21e 699
6ee5d4e7 700 \t tab (HT, TAB)
5a964f20 701 \n newline (NL)
6ee5d4e7
PP
702 \r return (CR)
703 \f form feed (FF)
704 \b backspace (BS)
705 \a alarm (bell) (BEL)
706 \e escape (ESC)
a0ed51b3
LW
707 \033 octal char (ESC)
708 \x1b hex char (ESC)
709 \x{263a} wide hex char (SMILEY)
19799a22 710 \c[ control char (ESC)
4a2d328f 711 \N{name} named char
2c268ad5 712
904501ec
MG
713The following escape sequences are available in constructs that interpolate
714but not in transliterations.
715
a0d0e21e
LW
716 \l lowercase next char
717 \u uppercase next char
718 \L lowercase till \E
719 \U uppercase till \E
720 \E end case modification
1d2dff63 721 \Q quote non-word characters till \E
a0d0e21e 722
a034a98d 723If C<use locale> is in effect, the case map used by C<\l>, C<\L>, C<\u>
423cee85 724and C<\U> is taken from the current locale. See L<perllocale>. For
4a2d328f 725documentation of C<\N{name}>, see L<charnames>.
a034a98d 726
5a964f20
TC
727All systems use the virtual C<"\n"> to represent a line terminator,
728called a "newline". There is no such thing as an unvarying, physical
19799a22 729newline character. It is only an illusion that the operating system,
5a964f20
TC
730device drivers, C libraries, and Perl all conspire to preserve. Not all
731systems read C<"\r"> as ASCII CR and C<"\n"> as ASCII LF. For example,
732on a Mac, these are reversed, and on systems without line terminator,
733printing C<"\n"> may emit no actual data. In general, use C<"\n"> when
734you mean a "newline" for your system, but use the literal ASCII when you
735need an exact character. For example, most networking protocols expect
2a380090 736and prefer a CR+LF (C<"\015\012"> or C<"\cM\cJ">) for line terminators,
5a964f20
TC
737and although they often accept just C<"\012">, they seldom tolerate just
738C<"\015">. If you get in the habit of using C<"\n"> for networking,
739you may be burned some day.
740
904501ec
MG
741For constructs that do interpolate, variables beginning with "C<$>"
742or "C<@>" are interpolated. Subscripted variables such as C<$a[3]> or
743C<$href->{key}[0]> are also interpolated, as are array and hash slices.
744But method calls such as C<$obj->meth> are not.
af9219ee
MG
745
746Interpolating an array or slice interpolates the elements in order,
747separated by the value of C<$">, so is equivalent to interpolating
904501ec
MG
748C<join $", @array>. "Punctuation" arrays such as C<@+> are only
749interpolated if the name is enclosed in braces C<@{+}>.
af9219ee 750
1d2dff63
GS
751You cannot include a literal C<$> or C<@> within a C<\Q> sequence.
752An unescaped C<$> or C<@> interpolates the corresponding variable,
753while escaping will cause the literal string C<\$> to be inserted.
754You'll need to write something like C<m/\Quser\E\@\Qhost/>.
755
a0d0e21e
LW
756Patterns are subject to an additional level of interpretation as a
757regular expression. This is done as a second pass, after variables are
758interpolated, so that regular expressions may be incorporated into the
759pattern from the variables. If this is not what you want, use C<\Q> to
760interpolate a variable literally.
761
19799a22
GS
762Apart from the behavior described above, Perl does not expand
763multiple levels of interpolation. In particular, contrary to the
764expectations of shell programmers, back-quotes do I<NOT> interpolate
765within double quotes, nor do single quotes impede evaluation of
766variables when used within double quotes.
a0d0e21e 767
5f05dabc 768=head2 Regexp Quote-Like Operators
cb1a09d0 769
5f05dabc 770Here are the quote-like operators that apply to pattern
cb1a09d0
AD
771matching and related activities.
772
a0d0e21e
LW
773=over 8
774
775=item ?PATTERN?
776
777This is just like the C</pattern/> search, except that it matches only
778once between calls to the reset() operator. This is a useful
5f05dabc 779optimization when you want to see only the first occurrence of
a0d0e21e
LW
780something in each file of a set of files, for instance. Only C<??>
781patterns local to the current package are reset.
782
5a964f20
TC
783 while (<>) {
784 if (?^$?) {
785 # blank line between header and body
786 }
787 } continue {
788 reset if eof; # clear ?? status for next file
789 }
790
483b4840 791This usage is vaguely deprecated, which means it just might possibly
19799a22
GS
792be removed in some distant future version of Perl, perhaps somewhere
793around the year 2168.
a0d0e21e 794
fb73857a 795=item m/PATTERN/cgimosx
a0d0e21e 796
fb73857a 797=item /PATTERN/cgimosx
a0d0e21e 798
5a964f20 799Searches a string for a pattern match, and in scalar context returns
19799a22
GS
800true if it succeeds, false if it fails. If no string is specified
801via the C<=~> or C<!~> operator, the $_ string is searched. (The
802string specified with C<=~> need not be an lvalue--it may be the
803result of an expression evaluation, but remember the C<=~> binds
804rather tightly.) See also L<perlre>. See L<perllocale> for
805discussion of additional considerations that apply when C<use locale>
806is in effect.
a0d0e21e
LW
807
808Options are:
809
fb73857a 810 c Do not reset search position on a failed match when /g is in effect.
5f05dabc 811 g Match globally, i.e., find all occurrences.
a0d0e21e
LW
812 i Do case-insensitive pattern matching.
813 m Treat string as multiple lines.
5f05dabc 814 o Compile pattern only once.
a0d0e21e
LW
815 s Treat string as single line.
816 x Use extended regular expressions.
817
818If "/" is the delimiter then the initial C<m> is optional. With the C<m>
01ae956f 819you can use any pair of non-alphanumeric, non-whitespace characters
19799a22
GS
820as delimiters. This is particularly useful for matching path names
821that contain "/", to avoid LTS (leaning toothpick syndrome). If "?" is
7bac28a0 822the delimiter, then the match-only-once rule of C<?PATTERN?> applies.
19799a22 823If "'" is the delimiter, no interpolation is performed on the PATTERN.
a0d0e21e
LW
824
825PATTERN may contain variables, which will be interpolated (and the
f70b4f9c 826pattern recompiled) every time the pattern search is evaluated, except
1f247705
GS
827for when the delimiter is a single quote. (Note that C<$(>, C<$)>, and
828C<$|> are not interpolated because they look like end-of-string tests.)
f70b4f9c
AB
829If you want such a pattern to be compiled only once, add a C</o> after
830the trailing delimiter. This avoids expensive run-time recompilations,
831and is useful when the value you are interpolating won't change over
832the life of the script. However, mentioning C</o> constitutes a promise
833that you won't change the variables in the pattern. If you change them,
13a2d996 834Perl won't even notice. See also L<"qr/STRING/imosx">.
a0d0e21e 835
5a964f20
TC
836If the PATTERN evaluates to the empty string, the last
837I<successfully> matched regular expression is used instead.
a0d0e21e 838
19799a22 839If the C</g> option is not used, C<m//> in list context returns a
a0d0e21e 840list consisting of the subexpressions matched by the parentheses in the
f7e33566
GS
841pattern, i.e., (C<$1>, C<$2>, C<$3>...). (Note that here C<$1> etc. are
842also set, and that this differs from Perl 4's behavior.) When there are
843no parentheses in the pattern, the return value is the list C<(1)> for
844success. With or without parentheses, an empty list is returned upon
845failure.
a0d0e21e
LW
846
847Examples:
848
849 open(TTY, '/dev/tty');
850 <TTY> =~ /^y/i && foo(); # do foo if desired
851
852 if (/Version: *([0-9.]*)/) { $version = $1; }
853
854 next if m#^/usr/spool/uucp#;
855
856 # poor man's grep
857 $arg = shift;
858 while (<>) {
859 print if /$arg/o; # compile only once
860 }
861
862 if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
863
864This last example splits $foo into the first two words and the
5f05dabc
PP
865remainder of the line, and assigns those three fields to $F1, $F2, and
866$Etc. The conditional is true if any variables were assigned, i.e., if
a0d0e21e
LW
867the pattern matched.
868
19799a22
GS
869The C</g> modifier specifies global pattern matching--that is,
870matching as many times as possible within the string. How it behaves
871depends on the context. In list context, it returns a list of the
872substrings matched by any capturing parentheses in the regular
873expression. If there are no parentheses, it returns a list of all
874the matched strings, as if there were parentheses around the whole
875pattern.
a0d0e21e 876
7e86de3e 877In scalar context, each execution of C<m//g> finds the next match,
19799a22 878returning true if it matches, and false if there is no further match.
7e86de3e
G
879The position after the last match can be read or set using the pos()
880function; see L<perlfunc/pos>. A failed match normally resets the
881search position to the beginning of the string, but you can avoid that
882by adding the C</c> modifier (e.g. C<m//gc>). Modifying the target
883string also resets the search position.
c90c0ff4
PP
884
885You can intermix C<m//g> matches with C<m/\G.../g>, where C<\G> is a
886zero-width assertion that matches the exact position where the previous
5d43e42d
DC
887C<m//g>, if any, left off. Without the C</g> modifier, the C<\G> assertion
888still anchors at pos(), but the match is of course only attempted once.
889Using C<\G> without C</g> on a target string that has not previously had a
890C</g> match applied to it is the same as using the C<\A> assertion to match
891the beginning of the string.
c90c0ff4
PP
892
893Examples:
a0d0e21e
LW
894
895 # list context
896 ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
897
898 # scalar context
5d43e42d 899 $/ = "";
19799a22
GS
900 while (defined($paragraph = <>)) {
901 while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) {
902 $sentences++;
a0d0e21e
LW
903 }
904 }
905 print "$sentences\n";
906
c90c0ff4 907 # using m//gc with \G
137443ea 908 $_ = "ppooqppqq";
44a8e56a
PP
909 while ($i++ < 2) {
910 print "1: '";
c90c0ff4 911 print $1 while /(o)/gc; print "', pos=", pos, "\n";
44a8e56a 912 print "2: '";
c90c0ff4 913 print $1 if /\G(q)/gc; print "', pos=", pos, "\n";
44a8e56a 914 print "3: '";
c90c0ff4 915 print $1 while /(p)/gc; print "', pos=", pos, "\n";
44a8e56a 916 }
5d43e42d 917 print "Final: '$1', pos=",pos,"\n" if /\G(.)/;
44a8e56a
PP
918
919The last example should print:
920
921 1: 'oo', pos=4
137443ea 922 2: 'q', pos=5
44a8e56a
PP
923 3: 'pp', pos=7
924 1: '', pos=7
137443ea
PP
925 2: 'q', pos=8
926 3: '', pos=8
5d43e42d
DC
927 Final: 'q', pos=8
928
929Notice that the final match matched C<q> instead of C<p>, which a match
930without the C<\G> anchor would have done. Also note that the final match
931did not update C<pos> -- C<pos> is only updated on a C</g> match. If the
932final match did indeed match C<p>, it's a good bet that you're running an
933older (pre-5.6.0) Perl.
44a8e56a 934
c90c0ff4 935A useful idiom for C<lex>-like scanners is C</\G.../gc>. You can
e7ea3e70 936combine several regexps like this to process a string part-by-part,
c90c0ff4
PP
937doing different actions depending on which regexp matched. Each
938regexp tries to match where the previous one leaves off.
e7ea3e70 939
3fe9a6f1 940 $_ = <<'EOL';
e7ea3e70 941 $url = new URI::URL "http://www/"; die if $url eq "xXx";
3fe9a6f1
PP
942 EOL
943 LOOP:
e7ea3e70 944 {
c90c0ff4
PP
945 print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc;
946 print(" lowercase"), redo LOOP if /\G[a-z]+\b[,.;]?\s*/gc;
947 print(" UPPERCASE"), redo LOOP if /\G[A-Z]+\b[,.;]?\s*/gc;
948 print(" Capitalized"), redo LOOP if /\G[A-Z][a-z]+\b[,.;]?\s*/gc;
949 print(" MiXeD"), redo LOOP if /\G[A-Za-z]+\b[,.;]?\s*/gc;
950 print(" alphanumeric"), redo LOOP if /\G[A-Za-z0-9]+\b[,.;]?\s*/gc;
951 print(" line-noise"), redo LOOP if /\G[^A-Za-z0-9]+/gc;
e7ea3e70
IZ
952 print ". That's all!\n";
953 }
954
955Here is the output (split into several lines):
956
957 line-noise lowercase line-noise lowercase UPPERCASE line-noise
958 UPPERCASE line-noise lowercase line-noise lowercase line-noise
959 lowercase lowercase line-noise lowercase lowercase line-noise
960 MiXeD line-noise. That's all!
44a8e56a 961
a0d0e21e
LW
962=item q/STRING/
963
964=item C<'STRING'>
965
19799a22 966A single-quoted, literal string. A backslash represents a backslash
68dc0745
PP
967unless followed by the delimiter or another backslash, in which case
968the delimiter or backslash is interpolated.
a0d0e21e
LW
969
970 $foo = q!I said, "You said, 'She said it.'"!;
971 $bar = q('This is it.');
68dc0745 972 $baz = '\n'; # a two-character string
a0d0e21e
LW
973
974=item qq/STRING/
975
976=item "STRING"
977
978A double-quoted, interpolated string.
979
980 $_ .= qq
981 (*** The previous line contains the naughty word "$1".\n)
19799a22 982 if /\b(tcl|java|python)\b/i; # :-)
68dc0745 983 $baz = "\n"; # a one-character string
a0d0e21e 984
eec2d3df
GS
985=item qr/STRING/imosx
986
322edccd 987This operator quotes (and possibly compiles) its I<STRING> as a regular
19799a22
GS
988expression. I<STRING> is interpolated the same way as I<PATTERN>
989in C<m/PATTERN/>. If "'" is used as the delimiter, no interpolation
990is done. Returns a Perl value which may be used instead of the
991corresponding C</STRING/imosx> expression.
4b6a7270
IZ
992
993For example,
994
995 $rex = qr/my.STRING/is;
996 s/$rex/foo/;
997
998is equivalent to
999
1000 s/my.STRING/foo/is;
1001
1002The result may be used as a subpattern in a match:
eec2d3df
GS
1003
1004 $re = qr/$pattern/;
0a92e3a8
GS
1005 $string =~ /foo${re}bar/; # can be interpolated in other patterns
1006 $string =~ $re; # or used standalone
4b6a7270
IZ
1007 $string =~ /$re/; # or this way
1008
1009Since Perl may compile the pattern at the moment of execution of qr()
19799a22 1010operator, using qr() may have speed advantages in some situations,
4b6a7270
IZ
1011notably if the result of qr() is used standalone:
1012
1013 sub match {
1014 my $patterns = shift;
1015 my @compiled = map qr/$_/i, @$patterns;
1016 grep {
1017 my $success = 0;
a7665c5e 1018 foreach my $pat (@compiled) {
4b6a7270
IZ
1019 $success = 1, last if /$pat/;
1020 }
1021 $success;
1022 } @_;
1023 }
1024
19799a22
GS
1025Precompilation of the pattern into an internal representation at
1026the moment of qr() avoids a need to recompile the pattern every
1027time a match C</$pat/> is attempted. (Perl has many other internal
1028optimizations, but none would be triggered in the above example if
1029we did not use qr() operator.)
eec2d3df
GS
1030
1031Options are:
1032
1033 i Do case-insensitive pattern matching.
1034 m Treat string as multiple lines.
1035 o Compile pattern only once.
1036 s Treat string as single line.
1037 x Use extended regular expressions.
1038
0a92e3a8
GS
1039See L<perlre> for additional information on valid syntax for STRING, and
1040for a detailed look at the semantics of regular expressions.
1041
a0d0e21e
LW
1042=item qx/STRING/
1043
1044=item `STRING`
1045
43dd4d21
JH
1046A string which is (possibly) interpolated and then executed as a
1047system command with C</bin/sh> or its equivalent. Shell wildcards,
1048pipes, and redirections will be honored. The collected standard
1049output of the command is returned; standard error is unaffected. In
1050scalar context, it comes back as a single (potentially multi-line)
1051string, or undef if the command failed. In list context, returns a
1052list of lines (however you've defined lines with $/ or
1053$INPUT_RECORD_SEPARATOR), or an empty list if the command failed.
5a964f20
TC
1054
1055Because backticks do not affect standard error, use shell file descriptor
1056syntax (assuming the shell supports this) if you care to address this.
1057To capture a command's STDERR and STDOUT together:
a0d0e21e 1058
5a964f20
TC
1059 $output = `cmd 2>&1`;
1060
1061To capture a command's STDOUT but discard its STDERR:
1062
1063 $output = `cmd 2>/dev/null`;
1064
1065To capture a command's STDERR but discard its STDOUT (ordering is
1066important here):
1067
1068 $output = `cmd 2>&1 1>/dev/null`;
1069
1070To exchange a command's STDOUT and STDERR in order to capture the STDERR
1071but leave its STDOUT to come out the old STDERR:
1072
1073 $output = `cmd 3>&1 1>&2 2>&3 3>&-`;
1074
1075To read both a command's STDOUT and its STDERR separately, it's easiest
1076and safest to redirect them separately to files, and then read from those
1077files when the program is done:
1078
1079 system("program args 1>/tmp/program.stdout 2>/tmp/program.stderr");
1080
1081Using single-quote as a delimiter protects the command from Perl's
1082double-quote interpolation, passing it on to the shell instead:
1083
1084 $perl_info = qx(ps $$); # that's Perl's $$
1085 $shell_info = qx'ps $$'; # that's the new shell's $$
1086
19799a22 1087How that string gets evaluated is entirely subject to the command
5a964f20
TC
1088interpreter on your system. On most platforms, you will have to protect
1089shell metacharacters if you want them treated literally. This is in
1090practice difficult to do, as it's unclear how to escape which characters.
1091See L<perlsec> for a clean and safe example of a manual fork() and exec()
1092to emulate backticks safely.
a0d0e21e 1093
bb32b41a
GS
1094On some platforms (notably DOS-like ones), the shell may not be
1095capable of dealing with multiline commands, so putting newlines in
1096the string may not get you what you want. You may be able to evaluate
1097multiple commands in a single line by separating them with the command
1098separator character, if your shell supports that (e.g. C<;> on many Unix
1099shells; C<&> on the Windows NT C<cmd> shell).
1100
0f897271
GS
1101Beginning with v5.6.0, Perl will attempt to flush all files opened for
1102output before starting the child process, but this may not be supported
1103on some platforms (see L<perlport>). To be safe, you may need to set
1104C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
1105C<IO::Handle> on any open handles.
1106
bb32b41a
GS
1107Beware that some command shells may place restrictions on the length
1108of the command line. You must ensure your strings don't exceed this
1109limit after any necessary interpolations. See the platform-specific
1110release notes for more details about your particular environment.
1111
5a964f20
TC
1112Using this operator can lead to programs that are difficult to port,
1113because the shell commands called vary between systems, and may in
1114fact not be present at all. As one example, the C<type> command under
1115the POSIX shell is very different from the C<type> command under DOS.
1116That doesn't mean you should go out of your way to avoid backticks
1117when they're the right way to get something done. Perl was made to be
1118a glue language, and one of the things it glues together is commands.
1119Just understand what you're getting yourself into.
bb32b41a 1120
dc848c6f 1121See L<"I/O Operators"> for more discussion.
a0d0e21e 1122
945c54fd
JH
1123=item qw/STRING/
1124
1125Evaluates to a list of the words extracted out of STRING, using embedded
1126whitespace as the word delimiters. It can be understood as being roughly
1127equivalent to:
1128
1129 split(' ', q/STRING/);
1130
1131the difference being that it generates a real list at compile time. So
1132this expression:
1133
1134 qw(foo bar baz)
1135
1136is semantically equivalent to the list:
1137
1138 'foo', 'bar', 'baz'
1139
1140Some frequently seen examples:
1141
1142 use POSIX qw( setlocale localeconv )
1143 @EXPORT = qw( foo bar baz );
1144
1145A common mistake is to try to separate the words with comma or to
1146put comments into a multi-line C<qw>-string. For this reason, the
1147C<use warnings> pragma and the B<-w> switch (that is, the C<$^W> variable)
1148produces warnings if the STRING contains the "," or the "#" character.
1149
a0d0e21e
LW
1150=item s/PATTERN/REPLACEMENT/egimosx
1151
1152Searches a string for a pattern, and if found, replaces that pattern
1153with the replacement text and returns the number of substitutions
e37d713d 1154made. Otherwise it returns false (specifically, the empty string).
a0d0e21e
LW
1155
1156If no string is specified via the C<=~> or C<!~> operator, the C<$_>
1157variable is searched and modified. (The string specified with C<=~> must
5a964f20 1158be scalar variable, an array element, a hash element, or an assignment
5f05dabc 1159to one of those, i.e., an lvalue.)
a0d0e21e 1160
19799a22 1161If the delimiter chosen is a single quote, no interpolation is
a0d0e21e
LW
1162done on either the PATTERN or the REPLACEMENT. Otherwise, if the
1163PATTERN contains a $ that looks like a variable rather than an
1164end-of-string test, the variable will be interpolated into the pattern
5f05dabc 1165at run-time. If you want the pattern compiled only once the first time
a0d0e21e 1166the variable is interpolated, use the C</o> option. If the pattern
5a964f20 1167evaluates to the empty string, the last successfully executed regular
a0d0e21e 1168expression is used instead. See L<perlre> for further explanation on these.
5a964f20 1169See L<perllocale> for discussion of additional considerations that apply
a034a98d 1170when C<use locale> is in effect.
a0d0e21e
LW
1171
1172Options are:
1173
1174 e Evaluate the right side as an expression.
5f05dabc 1175 g Replace globally, i.e., all occurrences.
a0d0e21e
LW
1176 i Do case-insensitive pattern matching.
1177 m Treat string as multiple lines.
5f05dabc 1178 o Compile pattern only once.
a0d0e21e
LW
1179 s Treat string as single line.
1180 x Use extended regular expressions.
1181
1182Any non-alphanumeric, non-whitespace delimiter may replace the
1183slashes. If single quotes are used, no interpretation is done on the
e37d713d 1184replacement string (the C</e> modifier overrides this, however). Unlike
54310121 1185Perl 4, Perl 5 treats backticks as normal delimiters; the replacement
e37d713d 1186text is not evaluated as a command. If the
a0d0e21e 1187PATTERN is delimited by bracketing quotes, the REPLACEMENT has its own
5f05dabc 1188pair of quotes, which may or may not be bracketing quotes, e.g.,
35f2feb0 1189C<s(foo)(bar)> or C<< s<foo>/bar/ >>. A C</e> will cause the
cec88af6
GS
1190replacement portion to be treated as a full-fledged Perl expression
1191and evaluated right then and there. It is, however, syntax checked at
1192compile-time. A second C<e> modifier will cause the replacement portion
1193to be C<eval>ed before being run as a Perl expression.
a0d0e21e
LW
1194
1195Examples:
1196
1197 s/\bgreen\b/mauve/g; # don't change wintergreen
1198
1199 $path =~ s|/usr/bin|/usr/local/bin|;
1200
1201 s/Login: $foo/Login: $bar/; # run-time pattern
1202
5a964f20 1203 ($foo = $bar) =~ s/this/that/; # copy first, then change
a0d0e21e 1204
5a964f20 1205 $count = ($paragraph =~ s/Mister\b/Mr./g); # get change-count
a0d0e21e
LW
1206
1207 $_ = 'abc123xyz';
1208 s/\d+/$&*2/e; # yields 'abc246xyz'
1209 s/\d+/sprintf("%5d",$&)/e; # yields 'abc 246xyz'
1210 s/\w/$& x 2/eg; # yields 'aabbcc 224466xxyyzz'
1211
1212 s/%(.)/$percent{$1}/g; # change percent escapes; no /e
1213 s/%(.)/$percent{$1} || $&/ge; # expr now, so /e
1214 s/^=(\w+)/&pod($1)/ge; # use function call
1215
5a964f20
TC
1216 # expand variables in $_, but dynamics only, using
1217 # symbolic dereferencing
1218 s/\$(\w+)/${$1}/g;
1219
cec88af6
GS
1220 # Add one to the value of any numbers in the string
1221 s/(\d+)/1 + $1/eg;
1222
1223 # This will expand any embedded scalar variable
1224 # (including lexicals) in $_ : First $1 is interpolated
1225 # to the variable name, and then evaluated
a0d0e21e
LW
1226 s/(\$\w+)/$1/eeg;
1227
5a964f20 1228 # Delete (most) C comments.
a0d0e21e 1229 $program =~ s {
4633a7c4
LW
1230 /\* # Match the opening delimiter.
1231 .*? # Match a minimal number of characters.
1232 \*/ # Match the closing delimiter.
a0d0e21e
LW
1233 } []gsx;
1234
5a964f20
TC
1235 s/^\s*(.*?)\s*$/$1/; # trim white space in $_, expensively
1236
1237 for ($variable) { # trim white space in $variable, cheap
1238 s/^\s+//;
1239 s/\s+$//;
1240 }
a0d0e21e
LW
1241
1242 s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
1243
54310121 1244Note the use of $ instead of \ in the last example. Unlike
35f2feb0
GS
1245B<sed>, we use the \<I<digit>> form in only the left hand side.
1246Anywhere else it's $<I<digit>>.
a0d0e21e 1247
5f05dabc 1248Occasionally, you can't use just a C</g> to get all the changes
19799a22 1249to occur that you might want. Here are two common cases:
a0d0e21e
LW
1250
1251 # put commas in the right places in an integer
19799a22 1252 1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g;
a0d0e21e
LW
1253
1254 # expand tabs to 8-column spacing
1255 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
1256
6940069f 1257=item tr/SEARCHLIST/REPLACEMENTLIST/cds
a0d0e21e 1258
6940069f 1259=item y/SEARCHLIST/REPLACEMENTLIST/cds
a0d0e21e 1260
2c268ad5 1261Transliterates all occurrences of the characters found in the search list
a0d0e21e
LW
1262with the corresponding character in the replacement list. It returns
1263the number of characters replaced or deleted. If no string is
2c268ad5 1264specified via the =~ or !~ operator, the $_ string is transliterated. (The
54310121
PP
1265string specified with =~ must be a scalar variable, an array element, a
1266hash element, or an assignment to one of those, i.e., an lvalue.)
8ada0baa 1267
2c268ad5
TP
1268A character range may be specified with a hyphen, so C<tr/A-J/0-9/>
1269does the same replacement as C<tr/ACEGIBDFHJ/0246813579/>.
54310121
PP
1270For B<sed> devotees, C<y> is provided as a synonym for C<tr>. If the
1271SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has
1272its own pair of quotes, which may or may not be bracketing quotes,
2c268ad5 1273e.g., C<tr[A-Z][a-z]> or C<tr(+\-*/)/ABCD/>.
a0d0e21e 1274
cc255d5f
JH
1275Note that C<tr> does B<not> do regular expression character classes
1276such as C<\d> or C<[:lower:]>. The <tr> operator is not equivalent to
1277the tr(1) utility. If you want to map strings between lower/upper
1278cases, see L<perlfunc/lc> and L<perlfunc/uc>, and in general consider
1279using the C<s> operator if you need regular expressions.
1280
8ada0baa
JH
1281Note also that the whole range idea is rather unportable between
1282character sets--and even within character sets they may cause results
1283you probably didn't expect. A sound principle is to use only ranges
1284that begin from and end at either alphabets of equal case (a-e, A-E),
1285or digits (0-4). Anything else is unsafe. If in doubt, spell out the
1286character sets in full.
1287
a0d0e21e
LW
1288Options:
1289
1290 c Complement the SEARCHLIST.
1291 d Delete found but unreplaced characters.
1292 s Squash duplicate replaced characters.
1293
19799a22
GS
1294If the C</c> modifier is specified, the SEARCHLIST character set
1295is complemented. If the C</d> modifier is specified, any characters
1296specified by SEARCHLIST not found in REPLACEMENTLIST are deleted.
1297(Note that this is slightly more flexible than the behavior of some
1298B<tr> programs, which delete anything they find in the SEARCHLIST,
1299period.) If the C</s> modifier is specified, sequences of characters
1300that were transliterated to the same character are squashed down
1301to a single instance of the character.
a0d0e21e
LW
1302
1303If the C</d> modifier is used, the REPLACEMENTLIST is always interpreted
1304exactly as specified. Otherwise, if the REPLACEMENTLIST is shorter
1305than the SEARCHLIST, the final character is replicated till it is long
5a964f20 1306enough. If the REPLACEMENTLIST is empty, the SEARCHLIST is replicated.
a0d0e21e
LW
1307This latter is useful for counting characters in a class or for
1308squashing character sequences in a class.
1309
1310Examples:
1311
1312 $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case
1313
1314 $cnt = tr/*/*/; # count the stars in $_
1315
1316 $cnt = $sky =~ tr/*/*/; # count the stars in $sky
1317
1318 $cnt = tr/0-9//; # count the digits in $_
1319
1320 tr/a-zA-Z//s; # bookkeeper -> bokeper
1321
1322 ($HOST = $host) =~ tr/a-z/A-Z/;
1323
1324 tr/a-zA-Z/ /cs; # change non-alphas to single space
1325
1326 tr [\200-\377]
1327 [\000-\177]; # delete 8th bit
1328
19799a22
GS
1329If multiple transliterations are given for a character, only the
1330first one is used:
748a9306
LW
1331
1332 tr/AAA/XYZ/
1333
2c268ad5 1334will transliterate any A to X.
748a9306 1335
19799a22 1336Because the transliteration table is built at compile time, neither
a0d0e21e 1337the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote
19799a22
GS
1338interpolation. That means that if you want to use variables, you
1339must use an eval():
a0d0e21e
LW
1340
1341 eval "tr/$oldlist/$newlist/";
1342 die $@ if $@;
1343
1344 eval "tr/$oldlist/$newlist/, 1" or die $@;
1345
1346=back
1347
75e14d17
IZ
1348=head2 Gory details of parsing quoted constructs
1349
19799a22
GS
1350When presented with something that might have several different
1351interpretations, Perl uses the B<DWIM> (that's "Do What I Mean")
1352principle to pick the most probable interpretation. This strategy
1353is so successful that Perl programmers often do not suspect the
1354ambivalence of what they write. But from time to time, Perl's
1355notions differ substantially from what the author honestly meant.
1356
1357This section hopes to clarify how Perl handles quoted constructs.
1358Although the most common reason to learn this is to unravel labyrinthine
1359regular expressions, because the initial steps of parsing are the
1360same for all quoting operators, they are all discussed together.
1361
1362The most important Perl parsing rule is the first one discussed
1363below: when processing a quoted construct, Perl first finds the end
1364of that construct, then interprets its contents. If you understand
1365this rule, you may skip the rest of this section on the first
1366reading. The other rules are likely to contradict the user's
1367expectations much less frequently than this first one.
1368
1369Some passes discussed below are performed concurrently, but because
1370their results are the same, we consider them individually. For different
1371quoting constructs, Perl performs different numbers of passes, from
1372one to five, but these passes are always performed in the same order.
75e14d17 1373
13a2d996 1374=over 4
75e14d17
IZ
1375
1376=item Finding the end
1377
19799a22
GS
1378The first pass is finding the end of the quoted construct, whether
1379it be a multicharacter delimiter C<"\nEOF\n"> in the C<<<EOF>
1380construct, a C</> that terminates a C<qq//> construct, a C<]> which
35f2feb0
GS
1381terminates C<qq[]> construct, or a C<< > >> which terminates a
1382fileglob started with C<< < >>.
75e14d17 1383
19799a22
GS
1384When searching for single-character non-pairing delimiters, such
1385as C</>, combinations of C<\\> and C<\/> are skipped. However,
1386when searching for single-character pairing delimiter like C<[>,
1387combinations of C<\\>, C<\]>, and C<\[> are all skipped, and nested
1388C<[>, C<]> are skipped as well. When searching for multicharacter
1389delimiters, nothing is skipped.
75e14d17 1390
19799a22
GS
1391For constructs with three-part delimiters (C<s///>, C<y///>, and
1392C<tr///>), the search is repeated once more.
75e14d17 1393
19799a22
GS
1394During this search no attention is paid to the semantics of the construct.
1395Thus:
75e14d17
IZ
1396
1397 "$hash{"$foo/$bar"}"
1398
2a94b7ce 1399or:
75e14d17
IZ
1400
1401 m/
2a94b7ce 1402 bar # NOT a comment, this slash / terminated m//!
75e14d17
IZ
1403 /x
1404
19799a22
GS
1405do not form legal quoted expressions. The quoted part ends on the
1406first C<"> and C</>, and the rest happens to be a syntax error.
1407Because the slash that terminated C<m//> was followed by a C<SPACE>,
1408the example above is not C<m//x>, but rather C<m//> with no C</x>
1409modifier. So the embedded C<#> is interpreted as a literal C<#>.
75e14d17
IZ
1410
1411=item Removal of backslashes before delimiters
1412
19799a22
GS
1413During the second pass, text between the starting and ending
1414delimiters is copied to a safe location, and the C<\> is removed
1415from combinations consisting of C<\> and delimiter--or delimiters,
1416meaning both starting and ending delimiters will should these differ.
1417This removal does not happen for multi-character delimiters.
1418Note that the combination C<\\> is left intact, just as it was.
75e14d17 1419
19799a22
GS
1420Starting from this step no information about the delimiters is
1421used in parsing.
75e14d17
IZ
1422
1423=item Interpolation
1424
19799a22
GS
1425The next step is interpolation in the text obtained, which is now
1426delimiter-independent. There are four different cases.
75e14d17 1427
13a2d996 1428=over 4
75e14d17
IZ
1429
1430=item C<<<'EOF'>, C<m''>, C<s'''>, C<tr///>, C<y///>
1431
1432No interpolation is performed.
1433
1434=item C<''>, C<q//>
1435
1436The only interpolation is removal of C<\> from pairs C<\\>.
1437
35f2feb0 1438=item C<"">, C<``>, C<qq//>, C<qx//>, C<< <file*glob> >>
75e14d17 1439
19799a22
GS
1440C<\Q>, C<\U>, C<\u>, C<\L>, C<\l> (possibly paired with C<\E>) are
1441converted to corresponding Perl constructs. Thus, C<"$foo\Qbaz$bar">
1442is converted to C<$foo . (quotemeta("baz" . $bar))> internally.
1443The other combinations are replaced with appropriate expansions.
2a94b7ce 1444
19799a22
GS
1445Let it be stressed that I<whatever falls between C<\Q> and C<\E>>
1446is interpolated in the usual way. Something like C<"\Q\\E"> has
1447no C<\E> inside. instead, it has C<\Q>, C<\\>, and C<E>, so the
1448result is the same as for C<"\\\\E">. As a general rule, backslashes
1449between C<\Q> and C<\E> may lead to counterintuitive results. So,
1450C<"\Q\t\E"> is converted to C<quotemeta("\t")>, which is the same
1451as C<"\\\t"> (since TAB is not alphanumeric). Note also that:
2a94b7ce
IZ
1452
1453 $str = '\t';
1454 return "\Q$str";
1455
1456may be closer to the conjectural I<intention> of the writer of C<"\Q\t\E">.
1457
19799a22 1458Interpolated scalars and arrays are converted internally to the C<join> and
92d29cee 1459C<.> catenation operations. Thus, C<"$foo XXX '@arr'"> becomes:
75e14d17 1460
19799a22 1461 $foo . " XXX '" . (join $", @arr) . "'";
75e14d17 1462
19799a22 1463All operations above are performed simultaneously, left to right.
75e14d17 1464
19799a22
GS
1465Because the result of C<"\Q STRING \E"> has all metacharacters
1466quoted, there is no way to insert a literal C<$> or C<@> inside a
1467C<\Q\E> pair. If protected by C<\>, C<$> will be quoted to became
1468C<"\\\$">; if not, it is interpreted as the start of an interpolated
1469scalar.
75e14d17 1470
19799a22
GS
1471Note also that the interpolation code needs to make a decision on
1472where the interpolated scalar ends. For instance, whether
35f2feb0 1473C<< "a $b -> {c}" >> really means:
75e14d17
IZ
1474
1475 "a " . $b . " -> {c}";
1476
2a94b7ce 1477or:
75e14d17
IZ
1478
1479 "a " . $b -> {c};
1480
19799a22
GS
1481Most of the time, the longest possible text that does not include
1482spaces between components and which contains matching braces or
1483brackets. because the outcome may be determined by voting based
1484on heuristic estimators, the result is not strictly predictable.
1485Fortunately, it's usually correct for ambiguous cases.
75e14d17
IZ
1486
1487=item C<?RE?>, C</RE/>, C<m/RE/>, C<s/RE/foo/>,
1488
19799a22
GS
1489Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, and interpolation
1490happens (almost) as with C<qq//> constructs, but the substitution
1491of C<\> followed by RE-special chars (including C<\>) is not
1492performed. Moreover, inside C<(?{BLOCK})>, C<(?# comment )>, and
1493a C<#>-comment in a C<//x>-regular expression, no processing is
1494performed whatsoever. This is the first step at which the presence
1495of the C<//x> modifier is relevant.
1496
1497Interpolation has several quirks: C<$|>, C<$(>, and C<$)> are not
1498interpolated, and constructs C<$var[SOMETHING]> are voted (by several
1499different estimators) to be either an array element or C<$var>
1500followed by an RE alternative. This is where the notation
1501C<${arr[$bar]}> comes handy: C</${arr[0-9]}/> is interpreted as
1502array element C<-9>, not as a regular expression from the variable
1503C<$arr> followed by a digit, which would be the interpretation of
1504C</$arr[0-9]/>. Since voting among different estimators may occur,
1505the result is not predictable.
1506
1507It is at this step that C<\1> is begrudgingly converted to C<$1> in
1508the replacement text of C<s///> to correct the incorrigible
1509I<sed> hackers who haven't picked up the saner idiom yet. A warning
9f1b1f2d
GS
1510is emitted if the C<use warnings> pragma or the B<-w> command-line flag
1511(that is, the C<$^W> variable) was set.
19799a22
GS
1512
1513The lack of processing of C<\\> creates specific restrictions on
1514the post-processed text. If the delimiter is C</>, one cannot get
1515the combination C<\/> into the result of this step. C</> will
1516finish the regular expression, C<\/> will be stripped to C</> on
1517the previous step, and C<\\/> will be left as is. Because C</> is
1518equivalent to C<\/> inside a regular expression, this does not
1519matter unless the delimiter happens to be character special to the
1520RE engine, such as in C<s*foo*bar*>, C<m[foo]>, or C<?foo?>; or an
1521alphanumeric char, as in:
2a94b7ce
IZ
1522
1523 m m ^ a \s* b mmx;
1524
19799a22 1525In the RE above, which is intentionally obfuscated for illustration, the
2a94b7ce 1526delimiter is C<m>, the modifier is C<mx>, and after backslash-removal the
19799a22
GS
1527RE is the same as for C<m/ ^ a s* b /mx>). There's more than one
1528reason you're encouraged to restrict your delimiters to non-alphanumeric,
1529non-whitespace choices.
75e14d17
IZ
1530
1531=back
1532
19799a22 1533This step is the last one for all constructs except regular expressions,
75e14d17
IZ
1534which are processed further.
1535
1536=item Interpolation of regular expressions
1537
19799a22
GS
1538Previous steps were performed during the compilation of Perl code,
1539but this one happens at run time--although it may be optimized to
1540be calculated at compile time if appropriate. After preprocessing
1541described above, and possibly after evaluation if catenation,
1542joining, casing translation, or metaquoting are involved, the
1543resulting I<string> is passed to the RE engine for compilation.
1544
1545Whatever happens in the RE engine might be better discussed in L<perlre>,
1546but for the sake of continuity, we shall do so here.
1547
1548This is another step where the presence of the C<//x> modifier is
1549relevant. The RE engine scans the string from left to right and
1550converts it to a finite automaton.
1551
1552Backslashed characters are either replaced with corresponding
1553literal strings (as with C<\{>), or else they generate special nodes
1554in the finite automaton (as with C<\b>). Characters special to the
1555RE engine (such as C<|>) generate corresponding nodes or groups of
1556nodes. C<(?#...)> comments are ignored. All the rest is either
1557converted to literal strings to match, or else is ignored (as is
1558whitespace and C<#>-style comments if C<//x> is present).
1559
1560Parsing of the bracketed character class construct, C<[...]>, is
1561rather different than the rule used for the rest of the pattern.
1562The terminator of this construct is found using the same rules as
1563for finding the terminator of a C<{}>-delimited construct, the only
1564exception being that C<]> immediately following C<[> is treated as
1565though preceded by a backslash. Similarly, the terminator of
1566C<(?{...})> is found using the same rules as for finding the
1567terminator of a C<{}>-delimited construct.
1568
1569It is possible to inspect both the string given to RE engine and the
1570resulting finite automaton. See the arguments C<debug>/C<debugcolor>
1571in the C<use L<re>> pragma, as well as Perl's B<-Dr> command-line
4a4eefd0 1572switch documented in L<perlrun/"Command Switches">.
75e14d17
IZ
1573
1574=item Optimization of regular expressions
1575
7522fed5 1576This step is listed for completeness only. Since it does not change
75e14d17 1577semantics, details of this step are not documented and are subject
19799a22
GS
1578to change without notice. This step is performed over the finite
1579automaton that was generated during the previous pass.
2a94b7ce 1580
19799a22
GS
1581It is at this stage that C<split()> silently optimizes C</^/> to
1582mean C</^/m>.
75e14d17
IZ
1583
1584=back
1585
a0d0e21e
LW
1586=head2 I/O Operators
1587
54310121 1588There are several I/O operators you should know about.
fbad3eb5 1589
7b8d334a 1590A string enclosed by backticks (grave accents) first undergoes
19799a22
GS
1591double-quote interpolation. It is then interpreted as an external
1592command, and the output of that command is the value of the
e9c56f9b
JH
1593backtick string, like in a shell. In scalar context, a single string
1594consisting of all output is returned. In list context, a list of
1595values is returned, one per line of output. (You can set C<$/> to use
1596a different line terminator.) The command is executed each time the
1597pseudo-literal is evaluated. The status value of the command is
1598returned in C<$?> (see L<perlvar> for the interpretation of C<$?>).
1599Unlike in B<csh>, no translation is done on the return data--newlines
1600remain newlines. Unlike in any of the shells, single quotes do not
1601hide variable names in the command from interpretation. To pass a
1602literal dollar-sign through to the shell you need to hide it with a
1603backslash. The generalized form of backticks is C<qx//>. (Because
1604backticks always undergo shell expansion as well, see L<perlsec> for
1605security concerns.)
19799a22
GS
1606
1607In scalar context, evaluating a filehandle in angle brackets yields
1608the next line from that file (the newline, if any, included), or
1609C<undef> at end-of-file or on error. When C<$/> is set to C<undef>
1610(sometimes known as file-slurp mode) and the file is empty, it
1611returns C<''> the first time, followed by C<undef> subsequently.
1612
1613Ordinarily you must assign the returned value to a variable, but
1614there is one situation where an automatic assignment happens. If
1615and only if the input symbol is the only thing inside the conditional
1616of a C<while> statement (even if disguised as a C<for(;;)> loop),
1617the value is automatically assigned to the global variable $_,
1618destroying whatever was there previously. (This may seem like an
1619odd thing to you, but you'll use the construct in almost every Perl
17b829fa 1620script you write.) The $_ variable is not implicitly localized.
19799a22
GS
1621You'll have to put a C<local $_;> before the loop if you want that
1622to happen.
1623
1624The following lines are equivalent:
a0d0e21e 1625
748a9306 1626 while (defined($_ = <STDIN>)) { print; }
7b8d334a 1627 while ($_ = <STDIN>) { print; }
a0d0e21e
LW
1628 while (<STDIN>) { print; }
1629 for (;<STDIN>;) { print; }
748a9306 1630 print while defined($_ = <STDIN>);
7b8d334a 1631 print while ($_ = <STDIN>);
a0d0e21e
LW
1632 print while <STDIN>;
1633
19799a22 1634This also behaves similarly, but avoids $_ :
7b8d334a
GS
1635
1636 while (my $line = <STDIN>) { print $line }
1637
19799a22
GS
1638In these loop constructs, the assigned value (whether assignment
1639is automatic or explicit) is then tested to see whether it is
1640defined. The defined test avoids problems where line has a string
1641value that would be treated as false by Perl, for example a "" or
1642a "0" with no trailing newline. If you really mean for such values
1643to terminate the loop, they should be tested for explicitly:
7b8d334a
GS
1644
1645 while (($_ = <STDIN>) ne '0') { ... }
1646 while (<STDIN>) { last unless $_; ... }
1647
35f2feb0 1648In other boolean contexts, C<< <I<filehandle>> >> without an
9f1b1f2d
GS
1649explicit C<defined> test or comparison elicit a warning if the
1650C<use warnings> pragma or the B<-w>
19799a22 1651command-line switch (the C<$^W> variable) is in effect.
7b8d334a 1652
5f05dabc 1653The filehandles STDIN, STDOUT, and STDERR are predefined. (The
19799a22
GS
1654filehandles C<stdin>, C<stdout>, and C<stderr> will also work except
1655in packages, where they would be interpreted as local identifiers
1656rather than global.) Additional filehandles may be created with
1657the open() function, amongst others. See L<perlopentut> and
1658L<perlfunc/open> for details on this.
a0d0e21e 1659
35f2feb0 1660If a <FILEHANDLE> is used in a context that is looking for
19799a22
GS
1661a list, a list comprising all input lines is returned, one line per
1662list element. It's easy to grow to a rather large data space this
1663way, so use with care.
a0d0e21e 1664
35f2feb0 1665<FILEHANDLE> may also be spelled C<readline(*FILEHANDLE)>.
19799a22 1666See L<perlfunc/readline>.
fbad3eb5 1667
35f2feb0
GS
1668The null filehandle <> is special: it can be used to emulate the
1669behavior of B<sed> and B<awk>. Input from <> comes either from
a0d0e21e 1670standard input, or from each file listed on the command line. Here's
35f2feb0 1671how it works: the first time <> is evaluated, the @ARGV array is
5a964f20 1672checked, and if it is empty, C<$ARGV[0]> is set to "-", which when opened
a0d0e21e
LW
1673gives you standard input. The @ARGV array is then processed as a list
1674of filenames. The loop
1675
1676 while (<>) {
1677 ... # code for each line
1678 }
1679
1680is equivalent to the following Perl-like pseudo code:
1681
3e3baf6d 1682 unshift(@ARGV, '-') unless @ARGV;
a0d0e21e
LW
1683 while ($ARGV = shift) {
1684 open(ARGV, $ARGV);
1685 while (<ARGV>) {
1686 ... # code for each line
1687 }
1688 }
1689
19799a22
GS
1690except that it isn't so cumbersome to say, and will actually work.
1691It really does shift the @ARGV array and put the current filename
1692into the $ARGV variable. It also uses filehandle I<ARGV>
35f2feb0 1693internally--<> is just a synonym for <ARGV>, which
19799a22 1694is magical. (The pseudo code above doesn't work because it treats
35f2feb0 1695<ARGV> as non-magical.)
a0d0e21e 1696
35f2feb0 1697You can modify @ARGV before the first <> as long as the array ends up
a0d0e21e 1698containing the list of filenames you really want. Line numbers (C<$.>)
19799a22
GS
1699continue as though the input were one big happy file. See the example
1700in L<perlfunc/eof> for how to reset line numbers on each file.
5a964f20
TC
1701
1702If you want to set @ARGV to your own list of files, go right ahead.
1703This sets @ARGV to all plain text files if no @ARGV was given:
1704
1705 @ARGV = grep { -f && -T } glob('*') unless @ARGV;
a0d0e21e 1706
5a964f20
TC
1707You can even set them to pipe commands. For example, this automatically
1708filters compressed arguments through B<gzip>:
1709
1710 @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc < $_ |" : $_ } @ARGV;
1711
1712If you want to pass switches into your script, you can use one of the
a0d0e21e
LW
1713Getopts modules or put a loop on the front like this:
1714
1715 while ($_ = $ARGV[0], /^-/) {
1716 shift;
1717 last if /^--$/;
1718 if (/^-D(.*)/) { $debug = $1 }
1719 if (/^-v/) { $verbose++ }
5a964f20 1720 # ... # other switches
a0d0e21e 1721 }
5a964f20 1722
a0d0e21e 1723 while (<>) {
5a964f20 1724 # ... # code for each line
a0d0e21e
LW
1725 }
1726
35f2feb0 1727The <> symbol will return C<undef> for end-of-file only once.
19799a22
GS
1728If you call it again after this, it will assume you are processing another
1729@ARGV list, and if you haven't set @ARGV, will read input from STDIN.
a0d0e21e 1730
b159ebd3 1731If what the angle brackets contain is a simple scalar variable (e.g.,
35f2feb0 1732<$foo>), then that variable contains the name of the
19799a22
GS
1733filehandle to input from, or its typeglob, or a reference to the
1734same. For example:
cb1a09d0
AD
1735
1736 $fh = \*STDIN;
1737 $line = <$fh>;
a0d0e21e 1738
5a964f20
TC
1739If what's within the angle brackets is neither a filehandle nor a simple
1740scalar variable containing a filehandle name, typeglob, or typeglob
1741reference, it is interpreted as a filename pattern to be globbed, and
1742either a list of filenames or the next filename in the list is returned,
19799a22 1743depending on context. This distinction is determined on syntactic
35f2feb0
GS
1744grounds alone. That means C<< <$x> >> is always a readline() from
1745an indirect handle, but C<< <$hash{key}> >> is always a glob().
5a964f20
TC
1746That's because $x is a simple scalar variable, but C<$hash{key}> is
1747not--it's a hash element.
1748
1749One level of double-quote interpretation is done first, but you can't
35f2feb0 1750say C<< <$foo> >> because that's an indirect filehandle as explained
5a964f20
TC
1751in the previous paragraph. (In older versions of Perl, programmers
1752would insert curly brackets to force interpretation as a filename glob:
35f2feb0 1753C<< <${foo}> >>. These days, it's considered cleaner to call the
5a964f20 1754internal function directly as C<glob($foo)>, which is probably the right
19799a22 1755way to have done it in the first place.) For example:
a0d0e21e
LW
1756
1757 while (<*.c>) {
1758 chmod 0644, $_;
1759 }
1760
3a4b19e4 1761is roughly equivalent to:
a0d0e21e
LW
1762
1763 open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|");
1764 while (<FOO>) {
5b3eff12 1765 chomp;
a0d0e21e
LW
1766 chmod 0644, $_;
1767 }
1768
3a4b19e4
GS
1769except that the globbing is actually done internally using the standard
1770C<File::Glob> extension. Of course, the shortest way to do the above is:
a0d0e21e
LW
1771
1772 chmod 0644, <*.c>;
1773
19799a22
GS
1774A (file)glob evaluates its (embedded) argument only when it is
1775starting a new list. All values must be read before it will start
1776over. In list context, this isn't important because you automatically
1777get them all anyway. However, in scalar context the operator returns
069e01df 1778the next value each time it's called, or C<undef> when the list has
19799a22
GS
1779run out. As with filehandle reads, an automatic C<defined> is
1780generated when the glob occurs in the test part of a C<while>,
1781because legal glob returns (e.g. a file called F<0>) would otherwise
1782terminate the loop. Again, C<undef> is returned only once. So if
1783you're expecting a single value from a glob, it is much better to
1784say
4633a7c4
LW
1785
1786 ($file) = <blurch*>;
1787
1788than
1789
1790 $file = <blurch*>;
1791
1792because the latter will alternate between returning a filename and
19799a22 1793returning false.
4633a7c4 1794
b159ebd3 1795If you're trying to do variable interpolation, it's definitely better
4633a7c4 1796to use the glob() function, because the older notation can cause people
e37d713d 1797to become confused with the indirect filehandle notation.
4633a7c4
LW
1798
1799 @files = glob("$dir/*.[ch]");
1800 @files = glob($files[$i]);
1801
a0d0e21e
LW
1802=head2 Constant Folding
1803
1804Like C, Perl does a certain amount of expression evaluation at
19799a22 1805compile time whenever it determines that all arguments to an
a0d0e21e
LW
1806operator are static and have no side effects. In particular, string
1807concatenation happens at compile time between literals that don't do
19799a22 1808variable substitution. Backslash interpolation also happens at
a0d0e21e
LW
1809compile time. You can say
1810
1811 'Now is the time for all' . "\n" .
1812 'good men to come to.'
1813
54310121 1814and this all reduces to one string internally. Likewise, if
a0d0e21e
LW
1815you say
1816
1817 foreach $file (@filenames) {
5a964f20 1818 if (-s $file > 5 + 100 * 2**16) { }
54310121 1819 }
a0d0e21e 1820
19799a22
GS
1821the compiler will precompute the number which that expression
1822represents so that the interpreter won't have to.
a0d0e21e 1823
2c268ad5
TP
1824=head2 Bitwise String Operators
1825
1826Bitstrings of any size may be manipulated by the bitwise operators
1827(C<~ | & ^>).
1828
19799a22
GS
1829If the operands to a binary bitwise op are strings of different
1830sizes, B<|> and B<^> ops act as though the shorter operand had
1831additional zero bits on the right, while the B<&> op acts as though
1832the longer operand were truncated to the length of the shorter.
1833The granularity for such extension or truncation is one or more
1834bytes.
2c268ad5
TP
1835
1836 # ASCII-based examples
1837 print "j p \n" ^ " a h"; # prints "JAPH\n"
1838 print "JA" | " ph\n"; # prints "japh\n"
1839 print "japh\nJunk" & '_____'; # prints "JAPH\n";
1840 print 'p N$' ^ " E<H\n"; # prints "Perl\n";
1841
19799a22 1842If you are intending to manipulate bitstrings, be certain that
2c268ad5 1843you're supplying bitstrings: If an operand is a number, that will imply
19799a22 1844a B<numeric> bitwise operation. You may explicitly show which type of
2c268ad5
TP
1845operation you intend by using C<""> or C<0+>, as in the examples below.
1846
1847 $foo = 150 | 105 ; # yields 255 (0x96 | 0x69 is 0xFF)
1848 $foo = '150' | 105 ; # yields 255
1849 $foo = 150 | '105'; # yields 255
1850 $foo = '150' | '105'; # yields string '155' (under ASCII)
1851
1852 $baz = 0+$foo & 0+$bar; # both ops explicitly numeric
1853 $biz = "$foo" ^ "$bar"; # both ops explicitly stringy
a0d0e21e 1854
1ae175c8
GS
1855See L<perlfunc/vec> for information on how to manipulate individual bits
1856in a bit vector.
1857
55497cff 1858=head2 Integer Arithmetic
a0d0e21e 1859
19799a22 1860By default, Perl assumes that it must do most of its arithmetic in
a0d0e21e
LW
1861floating point. But by saying
1862
1863 use integer;
1864
1865you may tell the compiler that it's okay to use integer operations
19799a22
GS
1866(if it feels like it) from here to the end of the enclosing BLOCK.
1867An inner BLOCK may countermand this by saying
a0d0e21e
LW
1868
1869 no integer;
1870
19799a22
GS
1871which lasts until the end of that BLOCK. Note that this doesn't
1872mean everything is only an integer, merely that Perl may use integer
1873operations if it is so inclined. For example, even under C<use
1874integer>, if you take the C<sqrt(2)>, you'll still get C<1.4142135623731>
1875or so.
1876
1877Used on numbers, the bitwise operators ("&", "|", "^", "~", "<<",
13a2d996
SP
1878and ">>") always produce integral results. (But see also
1879L<Bitwise String Operators>.) However, C<use integer> still has meaning for
19799a22
GS
1880them. By default, their results are interpreted as unsigned integers, but
1881if C<use integer> is in effect, their results are interpreted
1882as signed integers. For example, C<~0> usually evaluates to a large
1883integral value. However, C<use integer; ~0> is C<-1> on twos-complement
1884machines.
68dc0745
PP
1885
1886=head2 Floating-point Arithmetic
1887
1888While C<use integer> provides integer-only arithmetic, there is no
19799a22
GS
1889analogous mechanism to provide automatic rounding or truncation to a
1890certain number of decimal places. For rounding to a certain number
1891of digits, sprintf() or printf() is usually the easiest route.
1892See L<perlfaq4>.
68dc0745 1893
5a964f20
TC
1894Floating-point numbers are only approximations to what a mathematician
1895would call real numbers. There are infinitely more reals than floats,
1896so some corners must be cut. For example:
1897
1898 printf "%.20g\n", 123456789123456789;
1899 # produces 123456789123456784
1900
1901Testing for exact equality of floating-point equality or inequality is
1902not a good idea. Here's a (relatively expensive) work-around to compare
1903whether two floating-point numbers are equal to a particular number of
1904decimal places. See Knuth, volume II, for a more robust treatment of
1905this topic.
1906
1907 sub fp_equal {
1908 my ($X, $Y, $POINTS) = @_;
1909 my ($tX, $tY);
1910 $tX = sprintf("%.${POINTS}g", $X);
1911 $tY = sprintf("%.${POINTS}g", $Y);
1912 return $tX eq $tY;
1913 }
1914
68dc0745 1915The POSIX module (part of the standard perl distribution) implements
19799a22
GS
1916ceil(), floor(), and other mathematical and trigonometric functions.
1917The Math::Complex module (part of the standard perl distribution)
1918defines mathematical functions that work on both the reals and the
1919imaginary numbers. Math::Complex not as efficient as POSIX, but
68dc0745
PP
1920POSIX can't work with complex numbers.
1921
1922Rounding in financial applications can have serious implications, and
1923the rounding method used should be specified precisely. In these
1924cases, it probably pays not to trust whichever system rounding is
1925being used by Perl, but to instead implement the rounding function you
1926need yourself.
5a964f20
TC
1927
1928=head2 Bigger Numbers
1929
1930The standard Math::BigInt and Math::BigFloat modules provide
19799a22 1931variable-precision arithmetic and overloaded operators, although
cd5c4fce 1932they're currently pretty slow. At the cost of some space and
19799a22
GS
1933considerable speed, they avoid the normal pitfalls associated with
1934limited-precision representations.
5a964f20
TC
1935
1936 use Math::BigInt;
1937 $x = Math::BigInt->new('123456789123456789');
1938 print $x * $x;
1939
1940 # prints +15241578780673678515622620750190521
19799a22 1941
cd5c4fce
T
1942There are several modules that let you calculate with (bound only by
1943memory and cpu-time) unlimited or fixed precision. There are also
1944some non-standard modules that provide faster implementations via
1945external C libraries.
1946
1947Here is a short, but incomplete summary:
1948
1949 Math::Fraction big, unlimited fractions like 9973 / 12967
1950 Math::String treat string sequences like numbers
1951 Math::FixedPrecision calculate with a fixed precision
1952 Math::Currency for currency calculations
1953 Bit::Vector manipulate bit vectors fast (uses C)
1954 Math::BigIntFast Bit::Vector wrapper for big numbers
1955 Math::Pari provides access to the Pari C library
1956 Math::BigInteger uses an external C library
1957 Math::Cephes uses external Cephes C library (no big numbers)
1958 Math::Cephes::Fraction fractions via the Cephes library
1959 Math::GMP another one using an external C library
1960
1961Choose wisely.
16070b82
GS
1962
1963=cut