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