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