This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
adapted contents of message into comments in malloc.c and INSTALL
[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
54310121 47A TERM has the highest precedence in Perl. They includes 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
5a964f20
TC
190result will be less than or equal to zero). If C<use integer> is
191in effect, the native hardware will be used instead of this rule,
192which may be construed a bug that will be fixed at some point.
a0d0e21e 193
5a964f20 194Note than when C<use integer> is in scope, "%" give you direct access
55d729e4
GS
195to the modulus operator as implemented by your C compiler. This
196operator is not as well defined for negative operands, but it will
197execute faster.
198
5a964f20 199Binary "x" is the repetition operator. In scalar context, it
a0d0e21e 200returns a string consisting of the left operand repeated the number of
5a964f20 201times specified by the right operand. In list context, if the left
5f05dabc 202operand is a list in parentheses, it repeats the list.
a0d0e21e
LW
203
204 print '-' x 80; # print row of dashes
205
206 print "\t" x ($tab/8), ' ' x ($tab%8); # tab over
207
208 @ones = (1) x 80; # a list of 80 1's
209 @ones = (5) x @ones; # set all elements to 5
210
211
212=head2 Additive Operators
213
214Binary "+" returns the sum of two numbers.
215
216Binary "-" returns the difference of two numbers.
217
218Binary "." concatenates two strings.
219
220=head2 Shift Operators
221
55497cff
PP
222Binary "<<" returns the value of its left argument shifted left by the
223number of bits specified by the right argument. Arguments should be
224integers. (See also L<Integer Arithmetic>.)
a0d0e21e 225
55497cff
PP
226Binary ">>" returns the value of its left argument shifted right by
227the number of bits specified by the right argument. Arguments should
228be integers. (See also L<Integer Arithmetic>.)
a0d0e21e
LW
229
230=head2 Named Unary Operators
231
232The various named unary operators are treated as functions with one
233argument, with optional parentheses. These include the filetest
234operators, like C<-f>, C<-M>, etc. See L<perlfunc>.
235
236If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
237is followed by a left parenthesis as the next token, the operator and
238arguments within parentheses are taken to be of highest precedence,
239just like a normal function call. Examples:
240
241 chdir $foo || die; # (chdir $foo) || die
242 chdir($foo) || die; # (chdir $foo) || die
243 chdir ($foo) || die; # (chdir $foo) || die
244 chdir +($foo) || die; # (chdir $foo) || die
245
246but, because * is higher precedence than ||:
247
248 chdir $foo * 20; # chdir ($foo * 20)
249 chdir($foo) * 20; # (chdir $foo) * 20
250 chdir ($foo) * 20; # (chdir $foo) * 20
251 chdir +($foo) * 20; # chdir ($foo * 20)
252
253 rand 10 * 20; # rand (10 * 20)
254 rand(10) * 20; # (rand 10) * 20
255 rand (10) * 20; # (rand 10) * 20
256 rand +(10) * 20; # rand (10 * 20)
257
5ba421f6 258See also L<"Terms and List Operators (Leftward)">.
a0d0e21e
LW
259
260=head2 Relational Operators
261
6ee5d4e7 262Binary "E<lt>" returns true if the left argument is numerically less than
a0d0e21e
LW
263the right argument.
264
6ee5d4e7 265Binary "E<gt>" returns true if the left argument is numerically greater
a0d0e21e
LW
266than the right argument.
267
6ee5d4e7 268Binary "E<lt>=" returns true if the left argument is numerically less than
a0d0e21e
LW
269or equal to the right argument.
270
6ee5d4e7 271Binary "E<gt>=" returns true if the left argument is numerically greater
a0d0e21e
LW
272than or equal to the right argument.
273
274Binary "lt" returns true if the left argument is stringwise less than
275the right argument.
276
277Binary "gt" returns true if the left argument is stringwise greater
278than the right argument.
279
280Binary "le" returns true if the left argument is stringwise less than
281or equal to the right argument.
282
283Binary "ge" returns true if the left argument is stringwise greater
284than or equal to the right argument.
285
286=head2 Equality Operators
287
288Binary "==" returns true if the left argument is numerically equal to
289the right argument.
290
291Binary "!=" returns true if the left argument is numerically not equal
292to the right argument.
293
6ee5d4e7
PP
294Binary "E<lt>=E<gt>" returns -1, 0, or 1 depending on whether the left
295argument is numerically less than, equal to, or greater than the right
296argument.
a0d0e21e
LW
297
298Binary "eq" returns true if the left argument is stringwise equal to
299the right argument.
300
301Binary "ne" returns true if the left argument is stringwise not equal
302to the right argument.
303
304Binary "cmp" returns -1, 0, or 1 depending on whether the left argument is stringwise
305less than, equal to, or greater than the right argument.
306
a034a98d
DD
307"lt", "le", "ge", "gt" and "cmp" use the collation (sort) order specified
308by the current locale if C<use locale> is in effect. See L<perllocale>.
309
a0d0e21e
LW
310=head2 Bitwise And
311
312Binary "&" returns its operators ANDed together bit by bit.
2c268ad5 313(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
a0d0e21e
LW
314
315=head2 Bitwise Or and Exclusive Or
316
317Binary "|" returns its operators ORed together bit by bit.
2c268ad5 318(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
a0d0e21e
LW
319
320Binary "^" returns its operators XORed together bit by bit.
2c268ad5 321(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
a0d0e21e
LW
322
323=head2 C-style Logical And
324
325Binary "&&" performs a short-circuit logical AND operation. That is,
326if the left operand is false, the right operand is not even evaluated.
327Scalar or list context propagates down to the right operand if it
328is evaluated.
329
330=head2 C-style Logical Or
331
332Binary "||" performs a short-circuit logical OR operation. That is,
333if the left operand is true, the right operand is not even evaluated.
334Scalar or list context propagates down to the right operand if it
335is evaluated.
336
337The C<||> and C<&&> operators differ from C's in that, rather than returning
3380 or 1, they return the last value evaluated. Thus, a reasonably portable
339way to find out the home directory (assuming it's not "0") might be:
340
341 $home = $ENV{'HOME'} || $ENV{'LOGDIR'} ||
342 (getpwuid($<))[7] || die "You're homeless!\n";
343
5a964f20
TC
344In particular, this means that you shouldn't use this
345for selecting between two aggregates for assignment:
346
347 @a = @b || @c; # this is wrong
348 @a = scalar(@b) || @c; # really meant this
349 @a = @b ? @b : @c; # this works fine, though
350
351As more readable alternatives to C<&&> and C<||> when used for
352control flow, Perl provides C<and> and C<or> operators (see below).
353The short-circuit behavior is identical. The precedence of "and" and
354"or" is much lower, however, so that you can safely use them after a
355list operator without the need for parentheses:
a0d0e21e
LW
356
357 unlink "alpha", "beta", "gamma"
358 or gripe(), next LINE;
359
360With the C-style operators that would have been written like this:
361
362 unlink("alpha", "beta", "gamma")
363 || (gripe(), next LINE);
364
5a964f20
TC
365Use "or" for assignment is unlikely to do what you want; see below.
366
367=head2 Range Operators
a0d0e21e
LW
368
369Binary ".." is the range operator, which is really two different
5a964f20 370operators depending on the context. In list context, it returns an
a0d0e21e
LW
371array of values counting (by ones) from the left value to the right
372value. This is useful for writing C<for (1..10)> loops and for doing
373slice operations on arrays. Be aware that under the current implementation,
54310121 374a temporary array is created, so you'll burn a lot of memory if you
a0d0e21e
LW
375write something like this:
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
401greater than 1. If either operand of scalar ".." is a numeric literal,
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
TP
624 qw{} Word list no
625 // m{} Pattern match yes
626 s{}{} Substitution yes
627 tr{}{} Transliteration no (but see below)
a0d0e21e 628
fb73857a
PP
629Note that there can be whitespace between the operator and the quoting
630characters, except when C<#> is being used as the quoting character.
a3cb178b 631C<q#foo#> is parsed as being the string C<foo>, while C<q #foo#> is the
fb73857a
PP
632operator C<q> followed by a comment. Its argument will be taken from the
633next line. This allows you to write:
634
635 s {foo} # Replace foo
636 {bar} # with bar.
637
2c268ad5
TP
638For constructs that do interpolation, variables beginning with "C<$>"
639or "C<@>" are interpolated, as are the following sequences. Within
640a transliteration, the first ten of these sequences may be used.
a0d0e21e 641
6ee5d4e7 642 \t tab (HT, TAB)
5a964f20 643 \n newline (NL)
6ee5d4e7
PP
644 \r return (CR)
645 \f form feed (FF)
646 \b backspace (BS)
647 \a alarm (bell) (BEL)
648 \e escape (ESC)
a0d0e21e
LW
649 \033 octal char
650 \x1b hex char
651 \c[ control char
2c268ad5 652
a0d0e21e
LW
653 \l lowercase next char
654 \u uppercase next char
655 \L lowercase till \E
656 \U uppercase till \E
657 \E end case modification
1d2dff63 658 \Q quote non-word characters till \E
a0d0e21e 659
a034a98d 660If C<use locale> is in effect, the case map used by C<\l>, C<\L>, C<\u>
7b8d334a 661and C<\U> is taken from the current locale. See L<perllocale>.
a034a98d 662
5a964f20
TC
663All systems use the virtual C<"\n"> to represent a line terminator,
664called a "newline". There is no such thing as an unvarying, physical
665newline character. It is an illusion that the operating system,
666device drivers, C libraries, and Perl all conspire to preserve. Not all
667systems read C<"\r"> as ASCII CR and C<"\n"> as ASCII LF. For example,
668on a Mac, these are reversed, and on systems without line terminator,
669printing C<"\n"> may emit no actual data. In general, use C<"\n"> when
670you mean a "newline" for your system, but use the literal ASCII when you
671need an exact character. For example, most networking protocols expect
672and prefer a CR+LF (C<"\012\015"> or C<"\cJ\cM">) for line terminators,
673and although they often accept just C<"\012">, they seldom tolerate just
674C<"\015">. If you get in the habit of using C<"\n"> for networking,
675you may be burned some day.
676
1d2dff63
GS
677You cannot include a literal C<$> or C<@> within a C<\Q> sequence.
678An unescaped C<$> or C<@> interpolates the corresponding variable,
679while escaping will cause the literal string C<\$> to be inserted.
680You'll need to write something like C<m/\Quser\E\@\Qhost/>.
681
a0d0e21e
LW
682Patterns are subject to an additional level of interpretation as a
683regular expression. This is done as a second pass, after variables are
684interpolated, so that regular expressions may be incorporated into the
685pattern from the variables. If this is not what you want, use C<\Q> to
686interpolate a variable literally.
687
688Apart from the above, there are no multiple levels of interpolation. In
5f05dabc 689particular, contrary to the expectations of shell programmers, back-quotes
a0d0e21e
LW
690do I<NOT> interpolate within double quotes, nor do single quotes impede
691evaluation of variables when used within double quotes.
692
5f05dabc 693=head2 Regexp Quote-Like Operators
cb1a09d0 694
5f05dabc 695Here are the quote-like operators that apply to pattern
cb1a09d0
AD
696matching and related activities.
697
a0d0e21e
LW
698=over 8
699
700=item ?PATTERN?
701
702This is just like the C</pattern/> search, except that it matches only
703once between calls to the reset() operator. This is a useful
5f05dabc 704optimization when you want to see only the first occurrence of
a0d0e21e
LW
705something in each file of a set of files, for instance. Only C<??>
706patterns local to the current package are reset.
707
5a964f20
TC
708 while (<>) {
709 if (?^$?) {
710 # blank line between header and body
711 }
712 } continue {
713 reset if eof; # clear ?? status for next file
714 }
715
a0d0e21e
LW
716This usage is vaguely deprecated, and may be removed in some future
717version of Perl.
718
fb73857a 719=item m/PATTERN/cgimosx
a0d0e21e 720
fb73857a 721=item /PATTERN/cgimosx
a0d0e21e 722
5a964f20 723Searches a string for a pattern match, and in scalar context returns
a0d0e21e
LW
724true (1) or false (''). If no string is specified via the C<=~> or
725C<!~> operator, the $_ string is searched. (The string specified with
726C<=~> need not be an lvalue--it may be the result of an expression
727evaluation, but remember the C<=~> binds rather tightly.) See also
728L<perlre>.
5a964f20 729See L<perllocale> for discussion of additional considerations that apply
a034a98d 730when C<use locale> is in effect.
a0d0e21e
LW
731
732Options are:
733
fb73857a 734 c Do not reset search position on a failed match when /g is in effect.
5f05dabc 735 g Match globally, i.e., find all occurrences.
a0d0e21e
LW
736 i Do case-insensitive pattern matching.
737 m Treat string as multiple lines.
5f05dabc 738 o Compile pattern only once.
a0d0e21e 739 s Treat string as single line.
48c036b1 740 t Taint $1 etc. if target string is tainted.
a0d0e21e
LW
741 x Use extended regular expressions.
742
743If "/" is the delimiter then the initial C<m> is optional. With the C<m>
01ae956f
DG
744you can use any pair of non-alphanumeric, non-whitespace characters
745as delimiters (if single quotes are used, no interpretation is done
746on the replacement string. Unlike Perl 4, Perl 5 treats backticks as normal
747delimiters; the replacement text is not evaluated as a command).
748This is particularly useful for matching Unix path names
7bac28a0
PP
749that contain "/", to avoid LTS (leaning toothpick syndrome). If "?" is
750the delimiter, then the match-only-once rule of C<?PATTERN?> applies.
a0d0e21e
LW
751
752PATTERN may contain variables, which will be interpolated (and the
753pattern recompiled) every time the pattern search is evaluated. (Note
754that C<$)> and C<$|> might not be interpolated because they look like
755end-of-string tests.) If you want such a pattern to be compiled only
756once, add a C</o> after the trailing delimiter. This avoids expensive
757run-time recompilations, and is useful when the value you are
758interpolating won't change over the life of the script. However, mentioning
759C</o> constitutes a promise that you won't change the variables in the pattern.
760If you change them, Perl won't even notice.
761
5a964f20
TC
762If the PATTERN evaluates to the empty string, the last
763I<successfully> matched regular expression is used instead.
a0d0e21e
LW
764
765If used in a context that requires a list value, a pattern match returns a
766list consisting of the subexpressions matched by the parentheses in the
5f05dabc 767pattern, i.e., (C<$1>, $2, $3...). (Note that here $1 etc. are also set, and
1d2dff63
GS
768that this differs from Perl 4's behavior.) If there are no parentheses,
769the return value is the list C<(1)> for success or C<('')> upon failure.
770With parentheses, C<()> is returned upon failure.
a0d0e21e
LW
771
772Examples:
773
774 open(TTY, '/dev/tty');
775 <TTY> =~ /^y/i && foo(); # do foo if desired
776
777 if (/Version: *([0-9.]*)/) { $version = $1; }
778
779 next if m#^/usr/spool/uucp#;
780
781 # poor man's grep
782 $arg = shift;
783 while (<>) {
784 print if /$arg/o; # compile only once
785 }
786
787 if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
788
789This last example splits $foo into the first two words and the
5f05dabc
PP
790remainder of the line, and assigns those three fields to $F1, $F2, and
791$Etc. The conditional is true if any variables were assigned, i.e., if
a0d0e21e
LW
792the pattern matched.
793
794The C</g> modifier specifies global pattern matching--that is, matching
795as many times as possible within the string. How it behaves depends on
5a964f20 796the context. In list context, it returns a list of all the
a0d0e21e
LW
797substrings matched by all the parentheses in the regular expression.
798If there are no parentheses, it returns a list of all the matched
799strings, as if there were parentheses around the whole pattern.
800
5a964f20 801In scalar context, C<m//g> iterates through the string, returning TRUE
c90c0ff4
PP
802each time it matches, and FALSE when it eventually runs out of matches.
803(In other words, it remembers where it left off last time and restarts
804the search at that point. You can actually find the current match
805position of a string or set it using the pos() function; see
806L<perlfunc/pos>.) A failed match normally resets the search position to
90248788 807the beginning of the string, but you can avoid that by adding the C</c>
c90c0ff4
PP
808modifier (e.g. C<m//gc>). Modifying the target string also resets the
809search position.
810
811You can intermix C<m//g> matches with C<m/\G.../g>, where C<\G> is a
812zero-width assertion that matches the exact position where the previous
813C<m//g>, if any, left off. The C<\G> assertion is not supported without
814the C</g> modifier; currently, without C</g>, C<\G> behaves just like
815C<\A>, but that's accidental and may change in the future.
816
817Examples:
a0d0e21e
LW
818
819 # list context
820 ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
821
822 # scalar context
5f05dabc 823 $/ = ""; $* = 1; # $* deprecated in modern perls
54310121 824 while (defined($paragraph = <>)) {
a0d0e21e
LW
825 while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) {
826 $sentences++;
827 }
828 }
829 print "$sentences\n";
830
c90c0ff4 831 # using m//gc with \G
137443ea 832 $_ = "ppooqppqq";
44a8e56a
PP
833 while ($i++ < 2) {
834 print "1: '";
c90c0ff4 835 print $1 while /(o)/gc; print "', pos=", pos, "\n";
44a8e56a 836 print "2: '";
c90c0ff4 837 print $1 if /\G(q)/gc; print "', pos=", pos, "\n";
44a8e56a 838 print "3: '";
c90c0ff4 839 print $1 while /(p)/gc; print "', pos=", pos, "\n";
44a8e56a
PP
840 }
841
842The last example should print:
843
844 1: 'oo', pos=4
137443ea 845 2: 'q', pos=5
44a8e56a
PP
846 3: 'pp', pos=7
847 1: '', pos=7
137443ea
PP
848 2: 'q', pos=8
849 3: '', pos=8
44a8e56a 850
c90c0ff4 851A useful idiom for C<lex>-like scanners is C</\G.../gc>. You can
e7ea3e70 852combine several regexps like this to process a string part-by-part,
c90c0ff4
PP
853doing different actions depending on which regexp matched. Each
854regexp tries to match where the previous one leaves off.
e7ea3e70 855
3fe9a6f1 856 $_ = <<'EOL';
e7ea3e70 857 $url = new URI::URL "http://www/"; die if $url eq "xXx";
3fe9a6f1
PP
858 EOL
859 LOOP:
e7ea3e70 860 {
c90c0ff4
PP
861 print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc;
862 print(" lowercase"), redo LOOP if /\G[a-z]+\b[,.;]?\s*/gc;
863 print(" UPPERCASE"), redo LOOP if /\G[A-Z]+\b[,.;]?\s*/gc;
864 print(" Capitalized"), redo LOOP if /\G[A-Z][a-z]+\b[,.;]?\s*/gc;
865 print(" MiXeD"), redo LOOP if /\G[A-Za-z]+\b[,.;]?\s*/gc;
866 print(" alphanumeric"), redo LOOP if /\G[A-Za-z0-9]+\b[,.;]?\s*/gc;
867 print(" line-noise"), redo LOOP if /\G[^A-Za-z0-9]+/gc;
e7ea3e70
IZ
868 print ". That's all!\n";
869 }
870
871Here is the output (split into several lines):
872
873 line-noise lowercase line-noise lowercase UPPERCASE line-noise
874 UPPERCASE line-noise lowercase line-noise lowercase line-noise
875 lowercase lowercase line-noise lowercase lowercase line-noise
876 MiXeD line-noise. That's all!
44a8e56a 877
a0d0e21e
LW
878=item q/STRING/
879
880=item C<'STRING'>
881
68dc0745
PP
882A single-quoted, literal string. A backslash represents a backslash
883unless followed by the delimiter or another backslash, in which case
884the delimiter or backslash is interpolated.
a0d0e21e
LW
885
886 $foo = q!I said, "You said, 'She said it.'"!;
887 $bar = q('This is it.');
68dc0745 888 $baz = '\n'; # a two-character string
a0d0e21e
LW
889
890=item qq/STRING/
891
892=item "STRING"
893
894A double-quoted, interpolated string.
895
896 $_ .= qq
897 (*** The previous line contains the naughty word "$1".\n)
898 if /(tcl|rexx|python)/; # :-)
68dc0745 899 $baz = "\n"; # a one-character string
a0d0e21e
LW
900
901=item qx/STRING/
902
903=item `STRING`
904
5a964f20
TC
905A string which is (possibly) interpolated and then executed as a system
906command with C</bin/sh> or its equivalent. Shell wildcards, pipes,
907and redirections will be honored. The collected standard output of the
908command is returned; standard error is unaffected. In scalar context,
909it comes back as a single (potentially multi-line) string. In list
910context, returns a list of lines (however you've defined lines with $/
911or $INPUT_RECORD_SEPARATOR).
912
913Because backticks do not affect standard error, use shell file descriptor
914syntax (assuming the shell supports this) if you care to address this.
915To capture a command's STDERR and STDOUT together:
a0d0e21e 916
5a964f20
TC
917 $output = `cmd 2>&1`;
918
919To capture a command's STDOUT but discard its STDERR:
920
921 $output = `cmd 2>/dev/null`;
922
923To capture a command's STDERR but discard its STDOUT (ordering is
924important here):
925
926 $output = `cmd 2>&1 1>/dev/null`;
927
928To exchange a command's STDOUT and STDERR in order to capture the STDERR
929but leave its STDOUT to come out the old STDERR:
930
931 $output = `cmd 3>&1 1>&2 2>&3 3>&-`;
932
933To read both a command's STDOUT and its STDERR separately, it's easiest
934and safest to redirect them separately to files, and then read from those
935files when the program is done:
936
937 system("program args 1>/tmp/program.stdout 2>/tmp/program.stderr");
938
939Using single-quote as a delimiter protects the command from Perl's
940double-quote interpolation, passing it on to the shell instead:
941
942 $perl_info = qx(ps $$); # that's Perl's $$
943 $shell_info = qx'ps $$'; # that's the new shell's $$
944
945Note that how the string gets evaluated is entirely subject to the command
946interpreter on your system. On most platforms, you will have to protect
947shell metacharacters if you want them treated literally. This is in
948practice difficult to do, as it's unclear how to escape which characters.
949See L<perlsec> for a clean and safe example of a manual fork() and exec()
950to emulate backticks safely.
a0d0e21e 951
bb32b41a
GS
952On some platforms (notably DOS-like ones), the shell may not be
953capable of dealing with multiline commands, so putting newlines in
954the string may not get you what you want. You may be able to evaluate
955multiple commands in a single line by separating them with the command
956separator character, if your shell supports that (e.g. C<;> on many Unix
957shells; C<&> on the Windows NT C<cmd> shell).
958
959Beware that some command shells may place restrictions on the length
960of the command line. You must ensure your strings don't exceed this
961limit after any necessary interpolations. See the platform-specific
962release notes for more details about your particular environment.
963
5a964f20
TC
964Using this operator can lead to programs that are difficult to port,
965because the shell commands called vary between systems, and may in
966fact not be present at all. As one example, the C<type> command under
967the POSIX shell is very different from the C<type> command under DOS.
968That doesn't mean you should go out of your way to avoid backticks
969when they're the right way to get something done. Perl was made to be
970a glue language, and one of the things it glues together is commands.
971Just understand what you're getting yourself into.
bb32b41a 972
dc848c6f 973See L<"I/O Operators"> for more discussion.
a0d0e21e
LW
974
975=item qw/STRING/
976
977Returns a list of the words extracted out of STRING, using embedded
978whitespace as the word delimiters. It is exactly equivalent to
979
980 split(' ', q/STRING/);
981
5a964f20
TC
982This equivalency means that if used in scalar context, you'll get split's
983(unfortunate) scalar context behavior, complete with mysterious warnings.
984
a0d0e21e
LW
985Some frequently seen examples:
986
987 use POSIX qw( setlocale localeconv )
988 @EXPORT = qw( foo bar baz );
989
7bac28a0 990A common mistake is to try to separate the words with comma or to put
5a964f20 991comments into a multi-line C<qw>-string. For this reason the C<-w>
7bac28a0
PP
992switch produce warnings if the STRING contains the "," or the "#"
993character.
994
a0d0e21e
LW
995=item s/PATTERN/REPLACEMENT/egimosx
996
997Searches a string for a pattern, and if found, replaces that pattern
998with the replacement text and returns the number of substitutions
e37d713d 999made. Otherwise it returns false (specifically, the empty string).
a0d0e21e
LW
1000
1001If no string is specified via the C<=~> or C<!~> operator, the C<$_>
1002variable is searched and modified. (The string specified with C<=~> must
5a964f20 1003be scalar variable, an array element, a hash element, or an assignment
5f05dabc 1004to one of those, i.e., an lvalue.)
a0d0e21e
LW
1005
1006If the delimiter chosen is single quote, no variable interpolation is
1007done on either the PATTERN or the REPLACEMENT. Otherwise, if the
1008PATTERN contains a $ that looks like a variable rather than an
1009end-of-string test, the variable will be interpolated into the pattern
5f05dabc 1010at run-time. If you want the pattern compiled only once the first time
a0d0e21e 1011the variable is interpolated, use the C</o> option. If the pattern
5a964f20 1012evaluates to the empty string, the last successfully executed regular
a0d0e21e 1013expression is used instead. See L<perlre> for further explanation on these.
5a964f20 1014See L<perllocale> for discussion of additional considerations that apply
a034a98d 1015when C<use locale> is in effect.
a0d0e21e
LW
1016
1017Options are:
1018
1019 e Evaluate the right side as an expression.
5f05dabc 1020 g Replace globally, i.e., all occurrences.
a0d0e21e
LW
1021 i Do case-insensitive pattern matching.
1022 m Treat string as multiple lines.
5f05dabc 1023 o Compile pattern only once.
a0d0e21e
LW
1024 s Treat string as single line.
1025 x Use extended regular expressions.
1026
1027Any non-alphanumeric, non-whitespace delimiter may replace the
1028slashes. If single quotes are used, no interpretation is done on the
e37d713d 1029replacement string (the C</e> modifier overrides this, however). Unlike
54310121 1030Perl 4, Perl 5 treats backticks as normal delimiters; the replacement
e37d713d 1031text is not evaluated as a command. If the
a0d0e21e 1032PATTERN is delimited by bracketing quotes, the REPLACEMENT has its own
5f05dabc 1033pair of quotes, which may or may not be bracketing quotes, e.g.,
a0d0e21e 1034C<s(foo)(bar)> or C<sE<lt>fooE<gt>/bar/>. A C</e> will cause the
7b8d334a 1035replacement portion to be interpreted as a full-fledged Perl expression
a0d0e21e
LW
1036and eval()ed right then and there. It is, however, syntax checked at
1037compile-time.
1038
1039Examples:
1040
1041 s/\bgreen\b/mauve/g; # don't change wintergreen
1042
1043 $path =~ s|/usr/bin|/usr/local/bin|;
1044
1045 s/Login: $foo/Login: $bar/; # run-time pattern
1046
5a964f20 1047 ($foo = $bar) =~ s/this/that/; # copy first, then change
a0d0e21e 1048
5a964f20 1049 $count = ($paragraph =~ s/Mister\b/Mr./g); # get change-count
a0d0e21e
LW
1050
1051 $_ = 'abc123xyz';
1052 s/\d+/$&*2/e; # yields 'abc246xyz'
1053 s/\d+/sprintf("%5d",$&)/e; # yields 'abc 246xyz'
1054 s/\w/$& x 2/eg; # yields 'aabbcc 224466xxyyzz'
1055
1056 s/%(.)/$percent{$1}/g; # change percent escapes; no /e
1057 s/%(.)/$percent{$1} || $&/ge; # expr now, so /e
1058 s/^=(\w+)/&pod($1)/ge; # use function call
1059
5a964f20
TC
1060 # expand variables in $_, but dynamics only, using
1061 # symbolic dereferencing
1062 s/\$(\w+)/${$1}/g;
1063
a0d0e21e 1064 # /e's can even nest; this will expand
5a964f20 1065 # any embedded scalar variable (including lexicals) in $_
a0d0e21e
LW
1066 s/(\$\w+)/$1/eeg;
1067
5a964f20 1068 # Delete (most) C comments.
a0d0e21e 1069 $program =~ s {
4633a7c4
LW
1070 /\* # Match the opening delimiter.
1071 .*? # Match a minimal number of characters.
1072 \*/ # Match the closing delimiter.
a0d0e21e
LW
1073 } []gsx;
1074
5a964f20
TC
1075 s/^\s*(.*?)\s*$/$1/; # trim white space in $_, expensively
1076
1077 for ($variable) { # trim white space in $variable, cheap
1078 s/^\s+//;
1079 s/\s+$//;
1080 }
a0d0e21e
LW
1081
1082 s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
1083
54310121 1084Note the use of $ instead of \ in the last example. Unlike
5f05dabc 1085B<sed>, we use the \E<lt>I<digit>E<gt> form in only the left hand side.
6ee5d4e7 1086Anywhere else it's $E<lt>I<digit>E<gt>.
a0d0e21e 1087
5f05dabc 1088Occasionally, you can't use just a C</g> to get all the changes
a0d0e21e
LW
1089to occur. Here are two common cases:
1090
1091 # put commas in the right places in an integer
1092 1 while s/(.*\d)(\d\d\d)/$1,$2/g; # perl4
1093 1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g; # perl5
1094
1095 # expand tabs to 8-column spacing
1096 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
1097
1098
1099=item tr/SEARCHLIST/REPLACEMENTLIST/cds
1100
1101=item y/SEARCHLIST/REPLACEMENTLIST/cds
1102
2c268ad5 1103Transliterates all occurrences of the characters found in the search list
a0d0e21e
LW
1104with the corresponding character in the replacement list. It returns
1105the number of characters replaced or deleted. If no string is
2c268ad5 1106specified via the =~ or !~ operator, the $_ string is transliterated. (The
54310121
PP
1107string specified with =~ must be a scalar variable, an array element, a
1108hash element, or an assignment to one of those, i.e., an lvalue.)
2c268ad5
TP
1109A character range may be specified with a hyphen, so C<tr/A-J/0-9/>
1110does the same replacement as C<tr/ACEGIBDFHJ/0246813579/>.
54310121
PP
1111For B<sed> devotees, C<y> is provided as a synonym for C<tr>. If the
1112SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has
1113its own pair of quotes, which may or may not be bracketing quotes,
2c268ad5 1114e.g., C<tr[A-Z][a-z]> or C<tr(+\-*/)/ABCD/>.
a0d0e21e
LW
1115
1116Options:
1117
1118 c Complement the SEARCHLIST.
1119 d Delete found but unreplaced characters.
1120 s Squash duplicate replaced characters.
1121
1122If the C</c> modifier is specified, the SEARCHLIST character set is
1123complemented. If the C</d> modifier is specified, any characters specified
1124by SEARCHLIST not found in REPLACEMENTLIST are deleted. (Note
1125that this is slightly more flexible than the behavior of some B<tr>
1126programs, which delete anything they find in the SEARCHLIST, period.)
1127If the C</s> modifier is specified, sequences of characters that were
2c268ad5 1128transliterated to the same character are squashed down to a single instance of the
a0d0e21e
LW
1129character.
1130
1131If the C</d> modifier is used, the REPLACEMENTLIST is always interpreted
1132exactly as specified. Otherwise, if the REPLACEMENTLIST is shorter
1133than the SEARCHLIST, the final character is replicated till it is long
5a964f20 1134enough. If the REPLACEMENTLIST is empty, the SEARCHLIST is replicated.
a0d0e21e
LW
1135This latter is useful for counting characters in a class or for
1136squashing character sequences in a class.
1137
1138Examples:
1139
1140 $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case
1141
1142 $cnt = tr/*/*/; # count the stars in $_
1143
1144 $cnt = $sky =~ tr/*/*/; # count the stars in $sky
1145
1146 $cnt = tr/0-9//; # count the digits in $_
1147
1148 tr/a-zA-Z//s; # bookkeeper -> bokeper
1149
1150 ($HOST = $host) =~ tr/a-z/A-Z/;
1151
1152 tr/a-zA-Z/ /cs; # change non-alphas to single space
1153
1154 tr [\200-\377]
1155 [\000-\177]; # delete 8th bit
1156
2c268ad5 1157If multiple transliterations are given for a character, only the first one is used:
748a9306
LW
1158
1159 tr/AAA/XYZ/
1160
2c268ad5 1161will transliterate any A to X.
748a9306 1162
2c268ad5 1163Note that because the transliteration table is built at compile time, neither
a0d0e21e
LW
1164the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote
1165interpolation. That means that if you want to use variables, you must use
1166an eval():
1167
1168 eval "tr/$oldlist/$newlist/";
1169 die $@ if $@;
1170
1171 eval "tr/$oldlist/$newlist/, 1" or die $@;
1172
1173=back
1174
1175=head2 I/O Operators
1176
54310121 1177There are several I/O operators you should know about.
7b8d334a 1178A string enclosed by backticks (grave accents) first undergoes
a0d0e21e
LW
1179variable substitution just like a double quoted string. It is then
1180interpreted as a command, and the output of that command is the value
5a964f20
TC
1181of the pseudo-literal, like in a shell. In scalar context, a single
1182string consisting of all the output is returned. In list context,
a0d0e21e
LW
1183a list of values is returned, one for each line of output. (You can
1184set C<$/> to use a different line terminator.) The command is executed
1185each time the pseudo-literal is evaluated. The status value of the
1186command is returned in C<$?> (see L<perlvar> for the interpretation
1187of C<$?>). Unlike in B<csh>, no translation is done on the return
1188data--newlines remain newlines. Unlike in any of the shells, single
1189quotes do not hide variable names in the command from interpretation.
1190To pass a $ through to the shell you need to hide it with a backslash.
54310121
PP
1191The generalized form of backticks is C<qx//>. (Because backticks
1192always undergo shell expansion as well, see L<perlsec> for
cb1a09d0 1193security concerns.)
a0d0e21e
LW
1194
1195Evaluating a filehandle in angle brackets yields the next line from
aa689395
PP
1196that file (newline, if any, included), or C<undef> at end of file.
1197Ordinarily you must assign that value to a variable, but there is one
1198situation where an automatic assignment happens. I<If and ONLY if> the
1199input symbol is the only thing inside the conditional of a C<while> or
1200C<for(;;)> loop, the value is automatically assigned to the variable
7b8d334a 1201C<$_>. In these loop constructs, the assigned value (whether assignment
5a964f20 1202is automatic or explicit) is then tested to see if it is defined.
7b8d334a
GS
1203The defined test avoids problems where line has a string value
1204that would be treated as false by perl e.g. "" or "0" with no trailing
1205newline. (This may seem like an odd thing to you, but you'll use the
1206construct in almost every Perl script you write.) Anyway, the following
1207lines are equivalent to each other:
a0d0e21e 1208
748a9306 1209 while (defined($_ = <STDIN>)) { print; }
7b8d334a 1210 while ($_ = <STDIN>) { print; }
a0d0e21e
LW
1211 while (<STDIN>) { print; }
1212 for (;<STDIN>;) { print; }
748a9306 1213 print while defined($_ = <STDIN>);
7b8d334a 1214 print while ($_ = <STDIN>);
a0d0e21e
LW
1215 print while <STDIN>;
1216
7b8d334a
GS
1217and this also behaves similarly, but avoids the use of $_ :
1218
1219 while (my $line = <STDIN>) { print $line }
1220
1221If you really mean such values to terminate the loop they should be
5a964f20 1222tested for explicitly:
7b8d334a
GS
1223
1224 while (($_ = <STDIN>) ne '0') { ... }
1225 while (<STDIN>) { last unless $_; ... }
1226
5a964f20 1227In other boolean contexts, C<E<lt>I<filehandle>E<gt>> without explicit C<defined>
7b8d334a
GS
1228test or comparison will solicit a warning if C<-w> is in effect.
1229
5f05dabc
PP
1230The filehandles STDIN, STDOUT, and STDERR are predefined. (The
1231filehandles C<stdin>, C<stdout>, and C<stderr> will also work except in
a0d0e21e
LW
1232packages, where they would be interpreted as local identifiers rather
1233than global.) Additional filehandles may be created with the open()
cb1a09d0 1234function. See L<perlfunc/open()> for details on this.
a0d0e21e 1235
6ee5d4e7 1236If a E<lt>FILEHANDLEE<gt> is used in a context that is looking for a list, a
a0d0e21e
LW
1237list consisting of all the input lines is returned, one line per list
1238element. It's easy to make a I<LARGE> data space this way, so use with
1239care.
1240
d28ebecd
PP
1241The null filehandle E<lt>E<gt> is special and can be used to emulate the
1242behavior of B<sed> and B<awk>. Input from E<lt>E<gt> comes either from
a0d0e21e 1243standard input, or from each file listed on the command line. Here's
d28ebecd 1244how it works: the first time E<lt>E<gt> is evaluated, the @ARGV array is
5a964f20 1245checked, and if it is empty, C<$ARGV[0]> is set to "-", which when opened
a0d0e21e
LW
1246gives you standard input. The @ARGV array is then processed as a list
1247of filenames. The loop
1248
1249 while (<>) {
1250 ... # code for each line
1251 }
1252
1253is equivalent to the following Perl-like pseudo code:
1254
3e3baf6d 1255 unshift(@ARGV, '-') unless @ARGV;
a0d0e21e
LW
1256 while ($ARGV = shift) {
1257 open(ARGV, $ARGV);
1258 while (<ARGV>) {
1259 ... # code for each line
1260 }
1261 }
1262
1263except that it isn't so cumbersome to say, and will actually work. It
1264really does shift array @ARGV and put the current filename into variable
5f05dabc
PP
1265$ARGV. It also uses filehandle I<ARGV> internally--E<lt>E<gt> is just a
1266synonym for E<lt>ARGVE<gt>, which is magical. (The pseudo code above
1267doesn't work because it treats E<lt>ARGVE<gt> as non-magical.)
a0d0e21e 1268
d28ebecd 1269You can modify @ARGV before the first E<lt>E<gt> as long as the array ends up
a0d0e21e
LW
1270containing the list of filenames you really want. Line numbers (C<$.>)
1271continue as if the input were one big happy file. (But see example
5a964f20
TC
1272under C<eof> for how to reset line numbers on each file.)
1273
1274If you want to set @ARGV to your own list of files, go right ahead.
1275This sets @ARGV to all plain text files if no @ARGV was given:
1276
1277 @ARGV = grep { -f && -T } glob('*') unless @ARGV;
a0d0e21e 1278
5a964f20
TC
1279You can even set them to pipe commands. For example, this automatically
1280filters compressed arguments through B<gzip>:
1281
1282 @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc < $_ |" : $_ } @ARGV;
1283
1284If you want to pass switches into your script, you can use one of the
a0d0e21e
LW
1285Getopts modules or put a loop on the front like this:
1286
1287 while ($_ = $ARGV[0], /^-/) {
1288 shift;
1289 last if /^--$/;
1290 if (/^-D(.*)/) { $debug = $1 }
1291 if (/^-v/) { $verbose++ }
5a964f20 1292 # ... # other switches
a0d0e21e 1293 }
5a964f20 1294
a0d0e21e 1295 while (<>) {
5a964f20 1296 # ... # code for each line
a0d0e21e
LW
1297 }
1298
7b8d334a
GS
1299The E<lt>E<gt> symbol will return C<undef> for end-of-file only once.
1300If you call it again after this it will assume you are processing another
1301@ARGV list, and if you haven't set @ARGV, will input from STDIN.
a0d0e21e
LW
1302
1303If the string inside the angle brackets is a reference to a scalar
5f05dabc 1304variable (e.g., E<lt>$fooE<gt>), then that variable contains the name of the
5a964f20 1305filehandle to input from, or its typeglob, or a reference to the same. For example:
cb1a09d0
AD
1306
1307 $fh = \*STDIN;
1308 $line = <$fh>;
a0d0e21e 1309
5a964f20
TC
1310If what's within the angle brackets is neither a filehandle nor a simple
1311scalar variable containing a filehandle name, typeglob, or typeglob
1312reference, it is interpreted as a filename pattern to be globbed, and
1313either a list of filenames or the next filename in the list is returned,
1314depending on context. This distinction is determined on syntactic
1315grounds alone. That means C<E<lt>$xE<gt>> is always a readline from
1316an indirect handle, but C<E<lt>$hash{key}E<gt>> is always a glob.
1317That's because $x is a simple scalar variable, but C<$hash{key}> is
1318not--it's a hash element.
1319
1320One level of double-quote interpretation is done first, but you can't
1321say C<E<lt>$fooE<gt>> because that's an indirect filehandle as explained
1322in the previous paragraph. (In older versions of Perl, programmers
1323would insert curly brackets to force interpretation as a filename glob:
1324C<E<lt>${foo}E<gt>>. These days, it's considered cleaner to call the
1325internal function directly as C<glob($foo)>, which is probably the right
1326way to have done it in the first place.) Example:
a0d0e21e
LW
1327
1328 while (<*.c>) {
1329 chmod 0644, $_;
1330 }
1331
1332is equivalent to
1333
1334 open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|");
1335 while (<FOO>) {
1336 chop;
1337 chmod 0644, $_;
1338 }
1339
1340In fact, it's currently implemented that way. (Which means it will not
1341work on filenames with spaces in them unless you have csh(1) on your
1342machine.) Of course, the shortest way to do the above is:
1343
1344 chmod 0644, <*.c>;
1345
1346Because globbing invokes a shell, it's often faster to call readdir() yourself
5f05dabc 1347and do your own grep() on the filenames. Furthermore, due to its current
54310121 1348implementation of using a shell, the glob() routine may get "Arg list too
a0d0e21e
LW
1349long" errors (unless you've installed tcsh(1L) as F</bin/csh>).
1350
5f05dabc 1351A glob evaluates its (embedded) argument only when it is starting a new
4633a7c4
LW
1352list. All values must be read before it will start over. In a list
1353context this isn't important, because you automatically get them all
5a964f20 1354anyway. In scalar context, however, the operator returns the next value
7b8d334a
GS
1355each time it is called, or a C<undef> value if you've just run out. As
1356for filehandles an automatic C<defined> is generated when the glob
1357occurs in the test part of a C<while> or C<for> - because legal glob returns
1358(e.g. a file called F<0>) would otherwise terminate the loop.
1359Again, C<undef> is returned only once. So if you're expecting a single value
1360from a glob, it is much better to say
4633a7c4
LW
1361
1362 ($file) = <blurch*>;
1363
1364than
1365
1366 $file = <blurch*>;
1367
1368because the latter will alternate between returning a filename and
54310121 1369returning FALSE.
4633a7c4
LW
1370
1371It you're trying to do variable interpolation, it's definitely better
1372to use the glob() function, because the older notation can cause people
e37d713d 1373to become confused with the indirect filehandle notation.
4633a7c4
LW
1374
1375 @files = glob("$dir/*.[ch]");
1376 @files = glob($files[$i]);
1377
a0d0e21e
LW
1378=head2 Constant Folding
1379
1380Like C, Perl does a certain amount of expression evaluation at
5a964f20 1381compile time, whenever it determines that all arguments to an
a0d0e21e
LW
1382operator are static and have no side effects. In particular, string
1383concatenation happens at compile time between literals that don't do
1384variable substitution. Backslash interpretation also happens at
1385compile time. You can say
1386
1387 'Now is the time for all' . "\n" .
1388 'good men to come to.'
1389
54310121 1390and this all reduces to one string internally. Likewise, if
a0d0e21e
LW
1391you say
1392
1393 foreach $file (@filenames) {
5a964f20 1394 if (-s $file > 5 + 100 * 2**16) { }
54310121 1395 }
a0d0e21e 1396
54310121 1397the compiler will precompute the number that
a0d0e21e
LW
1398expression represents so that the interpreter
1399won't have to.
1400
2c268ad5
TP
1401=head2 Bitwise String Operators
1402
1403Bitstrings of any size may be manipulated by the bitwise operators
1404(C<~ | & ^>).
1405
1406If the operands to a binary bitwise op are strings of different sizes,
1407B<or> and B<xor> ops will act as if the shorter operand had additional
1408zero bits on the right, while the B<and> op will act as if the longer
1409operand were truncated to the length of the shorter.
1410
1411 # ASCII-based examples
1412 print "j p \n" ^ " a h"; # prints "JAPH\n"
1413 print "JA" | " ph\n"; # prints "japh\n"
1414 print "japh\nJunk" & '_____'; # prints "JAPH\n";
1415 print 'p N$' ^ " E<H\n"; # prints "Perl\n";
1416
1417If you are intending to manipulate bitstrings, you should be certain that
1418you're supplying bitstrings: If an operand is a number, that will imply
1419a B<numeric> bitwise operation. You may explicitly show which type of
1420operation you intend by using C<""> or C<0+>, as in the examples below.
1421
1422 $foo = 150 | 105 ; # yields 255 (0x96 | 0x69 is 0xFF)
1423 $foo = '150' | 105 ; # yields 255
1424 $foo = 150 | '105'; # yields 255
1425 $foo = '150' | '105'; # yields string '155' (under ASCII)
1426
1427 $baz = 0+$foo & 0+$bar; # both ops explicitly numeric
1428 $biz = "$foo" ^ "$bar"; # both ops explicitly stringy
a0d0e21e 1429
55497cff 1430=head2 Integer Arithmetic
a0d0e21e
LW
1431
1432By default Perl assumes that it must do most of its arithmetic in
1433floating point. But by saying
1434
1435 use integer;
1436
1437you may tell the compiler that it's okay to use integer operations
1438from here to the end of the enclosing BLOCK. An inner BLOCK may
54310121 1439countermand this by saying
a0d0e21e
LW
1440
1441 no integer;
1442
1443which lasts until the end of that BLOCK.
1444
55497cff 1445The bitwise operators ("&", "|", "^", "~", "<<", and ">>") always
2c268ad5
TP
1446produce integral results. (But see also L<Bitwise String Operators>.)
1447However, C<use integer> still has meaning
55497cff
PP
1448for them. By default, their results are interpreted as unsigned
1449integers. However, if C<use integer> is in effect, their results are
5f05dabc 1450interpreted as signed integers. For example, C<~0> usually evaluates
5a964f20 1451to a large integral value. However, C<use integer; ~0> is -1 on twos-complement machines.
68dc0745
PP
1452
1453=head2 Floating-point Arithmetic
1454
1455While C<use integer> provides integer-only arithmetic, there is no
1456similar ways to provide rounding or truncation at a certain number of
1457decimal places. For rounding to a certain number of digits, sprintf()
1458or printf() is usually the easiest route.
1459
5a964f20
TC
1460Floating-point numbers are only approximations to what a mathematician
1461would call real numbers. There are infinitely more reals than floats,
1462so some corners must be cut. For example:
1463
1464 printf "%.20g\n", 123456789123456789;
1465 # produces 123456789123456784
1466
1467Testing for exact equality of floating-point equality or inequality is
1468not a good idea. Here's a (relatively expensive) work-around to compare
1469whether two floating-point numbers are equal to a particular number of
1470decimal places. See Knuth, volume II, for a more robust treatment of
1471this topic.
1472
1473 sub fp_equal {
1474 my ($X, $Y, $POINTS) = @_;
1475 my ($tX, $tY);
1476 $tX = sprintf("%.${POINTS}g", $X);
1477 $tY = sprintf("%.${POINTS}g", $Y);
1478 return $tX eq $tY;
1479 }
1480
68dc0745
PP
1481The POSIX module (part of the standard perl distribution) implements
1482ceil(), floor(), and a number of other mathematical and trigonometric
1483functions. The Math::Complex module (part of the standard perl
1484distribution) defines a number of mathematical functions that can also
1485work on real numbers. Math::Complex not as efficient as POSIX, but
1486POSIX can't work with complex numbers.
1487
1488Rounding in financial applications can have serious implications, and
1489the rounding method used should be specified precisely. In these
1490cases, it probably pays not to trust whichever system rounding is
1491being used by Perl, but to instead implement the rounding function you
1492need yourself.
5a964f20
TC
1493
1494=head2 Bigger Numbers
1495
1496The standard Math::BigInt and Math::BigFloat modules provide
1497variable precision arithmetic and overloaded operators.
1498At the cost of some space and considerable speed, they
1499avoid the normal pitfalls associated with limited-precision
1500representations.
1501
1502 use Math::BigInt;
1503 $x = Math::BigInt->new('123456789123456789');
1504 print $x * $x;
1505
1506 # prints +15241578780673678515622620750190521