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