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