This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[win32] merge changes#872,873 from maintbranch
[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
cb1a09d0 41=head1 DESCRIPTION
a0d0e21e
LW
42
43=head2 Terms and List Operators (Leftward)
44
54310121 45A TERM has the highest precedence in Perl. They includes variables,
5f05dabc 46quote and quote-like operators, any expression in parentheses,
a0d0e21e
LW
47and any function whose arguments are parenthesized. Actually, there
48aren't really functions in this sense, just list operators and unary
49operators behaving as functions because you put parentheses around
50the arguments. These are all documented in L<perlfunc>.
51
52If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
53is followed by a left parenthesis as the next token, the operator and
54arguments within parentheses are taken to be of highest precedence,
55just like a normal function call.
56
57In the absence of parentheses, the precedence of list operators such as
58C<print>, C<sort>, or C<chmod> is either very high or very low depending on
54310121 59whether you are looking at the left side or the right side of the operator.
a0d0e21e
LW
60For example, in
61
62 @ary = (1, 3, sort 4, 2);
63 print @ary; # prints 1324
64
65the commas on the right of the sort are evaluated before the sort, but
66the commas on the left are evaluated after. In other words, list
67operators tend to gobble up all the arguments that follow them, and
68then act like a simple TERM with regard to the preceding expression.
5f05dabc 69Note that you have to be careful with parentheses:
a0d0e21e
LW
70
71 # These evaluate exit before doing the print:
72 print($foo, exit); # Obviously not what you want.
73 print $foo, exit; # Nor is this.
74
75 # These do the print before evaluating exit:
76 (print $foo), exit; # This is what you want.
77 print($foo), exit; # Or this.
78 print ($foo), exit; # Or even this.
79
80Also note that
81
82 print ($foo & 255) + 1, "\n";
83
54310121 84probably doesn't do what you expect at first glance. See
a0d0e21e
LW
85L<Named Unary Operators> for more discussion of this.
86
87Also parsed as terms are the C<do {}> and C<eval {}> constructs, as
54310121 88well as subroutine and method calls, and the anonymous
a0d0e21e
LW
89constructors C<[]> and C<{}>.
90
2ae324a7 91See also L<Quote and Quote-like Operators> toward the end of this section,
c07a80fd 92as well as L<"I/O Operators">.
a0d0e21e
LW
93
94=head2 The Arrow Operator
95
96Just as in C and C++, "C<-E<gt>>" is an infix dereference operator. If the
97right side is either a C<[...]> or C<{...}> subscript, then the left side
98must be either a hard or symbolic reference to an array or hash (or
99a location capable of holding a hard reference, if it's an lvalue (assignable)).
100See L<perlref>.
101
102Otherwise, the right side is a method name or a simple scalar variable
103containing the method name, and the left side must either be an object
104(a blessed reference) or a class name (that is, a package name).
105See L<perlobj>.
106
5f05dabc 107=head2 Auto-increment and Auto-decrement
a0d0e21e
LW
108
109"++" and "--" work as in C. That is, if placed before a variable, they
110increment or decrement the variable before returning the value, and if
111placed after, increment or decrement the variable after returning the value.
112
54310121 113The auto-increment operator has a little extra builtin magic to it. If
a0d0e21e
LW
114you increment a variable that is numeric, or that has ever been used in
115a numeric context, you get a normal increment. If, however, the
5f05dabc 116variable has been used in only string contexts since it was set, and
a0d0e21e
LW
117has a value that is not null and matches the pattern
118C</^[a-zA-Z]*[0-9]*$/>, the increment is done as a string, preserving each
119character within its range, with carry:
120
121 print ++($foo = '99'); # prints '100'
122 print ++($foo = 'a0'); # prints 'a1'
123 print ++($foo = 'Az'); # prints 'Ba'
124 print ++($foo = 'zz'); # prints 'aaa'
125
5f05dabc 126The auto-decrement operator is not magical.
a0d0e21e
LW
127
128=head2 Exponentiation
129
130Binary "**" is the exponentiation operator. Note that it binds even more
cb1a09d0
AD
131tightly than unary minus, so -2**4 is -(2**4), not (-2)**4. (This is
132implemented using C's pow(3) function, which actually works on doubles
133internally.)
a0d0e21e
LW
134
135=head2 Symbolic Unary Operators
136
5f05dabc 137Unary "!" performs logical negation, i.e., "not". See also C<not> for a lower
a0d0e21e
LW
138precedence version of this.
139
140Unary "-" performs arithmetic negation if the operand is numeric. If
141the operand is an identifier, a string consisting of a minus sign
142concatenated with the identifier is returned. Otherwise, if the string
143starts with a plus or minus, a string starting with the opposite sign
144is returned. One effect of these rules is that C<-bareword> is equivalent
145to C<"-bareword">.
146
5f05dabc 147Unary "~" performs bitwise negation, i.e., 1's complement.
2c268ad5 148(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
a0d0e21e
LW
149
150Unary "+" has no effect whatsoever, even on strings. It is useful
151syntactically for separating a function name from a parenthesized expression
152that would otherwise be interpreted as the complete list of function
5ba421f6 153arguments. (See examples above under L<Terms and List Operators (Leftward)>.)
a0d0e21e
LW
154
155Unary "\" creates a reference to whatever follows it. See L<perlref>.
156Do not confuse this behavior with the behavior of backslash within a
157string, although both forms do convey the notion of protecting the next
158thing from interpretation.
159
160=head2 Binding Operators
161
c07a80fd 162Binary "=~" binds a scalar expression to a pattern match. Certain operations
cb1a09d0
AD
163search or modify the string $_ by default. This operator makes that kind
164of operation work on some other string. The right argument is a search
2c268ad5
TP
165pattern, substitution, or transliteration. The left argument is what is
166supposed to be searched, substituted, or transliterated instead of the default
cb1a09d0
AD
167$_. The return value indicates the success of the operation. (If the
168right argument is an expression rather than a search pattern,
2c268ad5 169substitution, or transliteration, it is interpreted as a search pattern at run
aa689395
PP
170time. This can be is less efficient than an explicit search, because the
171pattern must be compiled every time the expression is evaluated.
a0d0e21e
LW
172
173Binary "!~" is just like "=~" except the return value is negated in
174the logical sense.
175
176=head2 Multiplicative Operators
177
178Binary "*" multiplies two numbers.
179
180Binary "/" divides two numbers.
181
54310121
PP
182Binary "%" computes the modulus of two numbers. Given integer
183operands C<$a> and C<$b>: If C<$b> is positive, then C<$a % $b> is
184C<$a> minus the largest multiple of C<$b> that is not greater than
185C<$a>. If C<$b> is negative, then C<$a % $b> is C<$a> minus the
186smallest multiple of C<$b> that is not less than C<$a> (i.e. the
187result will be less than or equal to zero).
a0d0e21e
LW
188
189Binary "x" is the repetition operator. In a scalar context, it
190returns a string consisting of the left operand repeated the number of
191times specified by the right operand. In a list context, if the left
5f05dabc 192operand is a list in parentheses, it repeats the list.
a0d0e21e
LW
193
194 print '-' x 80; # print row of dashes
195
196 print "\t" x ($tab/8), ' ' x ($tab%8); # tab over
197
198 @ones = (1) x 80; # a list of 80 1's
199 @ones = (5) x @ones; # set all elements to 5
200
201
202=head2 Additive Operators
203
204Binary "+" returns the sum of two numbers.
205
206Binary "-" returns the difference of two numbers.
207
208Binary "." concatenates two strings.
209
210=head2 Shift Operators
211
55497cff
PP
212Binary "<<" returns the value of its left argument shifted left by the
213number of bits specified by the right argument. Arguments should be
214integers. (See also L<Integer Arithmetic>.)
a0d0e21e 215
55497cff
PP
216Binary ">>" returns the value of its left argument shifted right by
217the number of bits specified by the right argument. Arguments should
218be integers. (See also L<Integer Arithmetic>.)
a0d0e21e
LW
219
220=head2 Named Unary Operators
221
222The various named unary operators are treated as functions with one
223argument, with optional parentheses. These include the filetest
224operators, like C<-f>, C<-M>, etc. See L<perlfunc>.
225
226If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
227is followed by a left parenthesis as the next token, the operator and
228arguments within parentheses are taken to be of highest precedence,
229just like a normal function call. Examples:
230
231 chdir $foo || die; # (chdir $foo) || die
232 chdir($foo) || die; # (chdir $foo) || die
233 chdir ($foo) || die; # (chdir $foo) || die
234 chdir +($foo) || die; # (chdir $foo) || die
235
236but, because * is higher precedence than ||:
237
238 chdir $foo * 20; # chdir ($foo * 20)
239 chdir($foo) * 20; # (chdir $foo) * 20
240 chdir ($foo) * 20; # (chdir $foo) * 20
241 chdir +($foo) * 20; # chdir ($foo * 20)
242
243 rand 10 * 20; # rand (10 * 20)
244 rand(10) * 20; # (rand 10) * 20
245 rand (10) * 20; # (rand 10) * 20
246 rand +(10) * 20; # rand (10 * 20)
247
5ba421f6 248See also L<"Terms and List Operators (Leftward)">.
a0d0e21e
LW
249
250=head2 Relational Operators
251
6ee5d4e7 252Binary "E<lt>" returns true if the left argument is numerically less than
a0d0e21e
LW
253the right argument.
254
6ee5d4e7 255Binary "E<gt>" returns true if the left argument is numerically greater
a0d0e21e
LW
256than the right argument.
257
6ee5d4e7 258Binary "E<lt>=" returns true if the left argument is numerically less than
a0d0e21e
LW
259or equal to the right argument.
260
6ee5d4e7 261Binary "E<gt>=" returns true if the left argument is numerically greater
a0d0e21e
LW
262than or equal to the right argument.
263
264Binary "lt" returns true if the left argument is stringwise less than
265the right argument.
266
267Binary "gt" returns true if the left argument is stringwise greater
268than the right argument.
269
270Binary "le" returns true if the left argument is stringwise less than
271or equal to the right argument.
272
273Binary "ge" returns true if the left argument is stringwise greater
274than or equal to the right argument.
275
276=head2 Equality Operators
277
278Binary "==" returns true if the left argument is numerically equal to
279the right argument.
280
281Binary "!=" returns true if the left argument is numerically not equal
282to the right argument.
283
6ee5d4e7
PP
284Binary "E<lt>=E<gt>" returns -1, 0, or 1 depending on whether the left
285argument is numerically less than, equal to, or greater than the right
286argument.
a0d0e21e
LW
287
288Binary "eq" returns true if the left argument is stringwise equal to
289the right argument.
290
291Binary "ne" returns true if the left argument is stringwise not equal
292to the right argument.
293
294Binary "cmp" returns -1, 0, or 1 depending on whether the left argument is stringwise
295less than, equal to, or greater than the right argument.
296
a034a98d
DD
297"lt", "le", "ge", "gt" and "cmp" use the collation (sort) order specified
298by the current locale if C<use locale> is in effect. See L<perllocale>.
299
a0d0e21e
LW
300=head2 Bitwise And
301
302Binary "&" returns its operators ANDed together bit by bit.
2c268ad5 303(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
a0d0e21e
LW
304
305=head2 Bitwise Or and Exclusive Or
306
307Binary "|" returns its operators ORed together bit by bit.
2c268ad5 308(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
a0d0e21e
LW
309
310Binary "^" returns its operators XORed together bit by bit.
2c268ad5 311(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
a0d0e21e
LW
312
313=head2 C-style Logical And
314
315Binary "&&" performs a short-circuit logical AND operation. That is,
316if the left operand is false, the right operand is not even evaluated.
317Scalar or list context propagates down to the right operand if it
318is evaluated.
319
320=head2 C-style Logical Or
321
322Binary "||" performs a short-circuit logical OR operation. That is,
323if the left operand is true, the right operand is not even evaluated.
324Scalar or list context propagates down to the right operand if it
325is evaluated.
326
327The C<||> and C<&&> operators differ from C's in that, rather than returning
3280 or 1, they return the last value evaluated. Thus, a reasonably portable
329way to find out the home directory (assuming it's not "0") might be:
330
331 $home = $ENV{'HOME'} || $ENV{'LOGDIR'} ||
332 (getpwuid($<))[7] || die "You're homeless!\n";
333
334As more readable alternatives to C<&&> and C<||>, Perl provides "and" and
335"or" operators (see below). The short-circuit behavior is identical. The
336precedence of "and" and "or" is much lower, however, so that you can
337safely use them after a list operator without the need for
338parentheses:
339
340 unlink "alpha", "beta", "gamma"
341 or gripe(), next LINE;
342
343With the C-style operators that would have been written like this:
344
345 unlink("alpha", "beta", "gamma")
346 || (gripe(), next LINE);
347
348=head2 Range Operator
349
350Binary ".." is the range operator, which is really two different
351operators depending on the context. In a list context, it returns an
352array of values counting (by ones) from the left value to the right
353value. This is useful for writing C<for (1..10)> loops and for doing
354slice operations on arrays. Be aware that under the current implementation,
54310121 355a temporary array is created, so you'll burn a lot of memory if you
a0d0e21e
LW
356write something like this:
357
358 for (1 .. 1_000_000) {
359 # code
54310121 360 }
a0d0e21e
LW
361
362In a scalar context, ".." returns a boolean value. The operator is
363bistable, like a flip-flop, and emulates the line-range (comma) operator
364of B<sed>, B<awk>, and various editors. Each ".." operator maintains its
365own boolean state. It is false as long as its left operand is false.
366Once the left operand is true, the range operator stays true until the
367right operand is true, I<AFTER> which the range operator becomes false
368again. (It doesn't become false till the next time the range operator is
369evaluated. It can test the right operand and become false on the same
370evaluation it became true (as in B<awk>), but it still returns true once.
371If you don't want it to test the right operand till the next evaluation
372(as in B<sed>), use three dots ("...") instead of two.) The right
373operand is not evaluated while the operator is in the "false" state, and
374the left operand is not evaluated while the operator is in the "true"
375state. The precedence is a little lower than || and &&. The value
376returned is either the null string for false, or a sequence number
377(beginning with 1) for true. The sequence number is reset for each range
378encountered. The final sequence number in a range has the string "E0"
379appended to it, which doesn't affect its numeric value, but gives you
380something to search for if you want to exclude the endpoint. You can
381exclude the beginning point by waiting for the sequence number to be
382greater than 1. If either operand of scalar ".." is a numeric literal,
383that operand is implicitly compared to the C<$.> variable, the current
384line number. Examples:
385
386As a scalar operator:
387
388 if (101 .. 200) { print; } # print 2nd hundred lines
389 next line if (1 .. /^$/); # skip header lines
390 s/^/> / if (/^$/ .. eof()); # quote body
391
392As a list operator:
393
394 for (101 .. 200) { print; } # print $_ 100 times
3e3baf6d 395 @foo = @foo[0 .. $#foo]; # an expensive no-op
a0d0e21e
LW
396 @foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items
397
398The range operator (in a list context) makes use of the magical
5f05dabc 399auto-increment algorithm if the operands are strings. You
a0d0e21e
LW
400can say
401
402 @alphabet = ('A' .. 'Z');
403
404to get all the letters of the alphabet, or
405
406 $hexdigit = (0 .. 9, 'a' .. 'f')[$num & 15];
407
408to get a hexadecimal digit, or
409
410 @z2 = ('01' .. '31'); print $z2[$mday];
411
412to get dates with leading zeros. If the final value specified is not
413in the sequence that the magical increment would produce, the sequence
414goes until the next value would be longer than the final value
415specified.
416
417=head2 Conditional Operator
418
419Ternary "?:" is the conditional operator, just as in C. It works much
420like an if-then-else. If the argument before the ? is true, the
421argument before the : is returned, otherwise the argument after the :
cb1a09d0
AD
422is returned. For example:
423
54310121 424 printf "I have %d dog%s.\n", $n,
cb1a09d0
AD
425 ($n == 1) ? '' : "s";
426
427Scalar or list context propagates downward into the 2nd
54310121 428or 3rd argument, whichever is selected.
cb1a09d0
AD
429
430 $a = $ok ? $b : $c; # get a scalar
431 @a = $ok ? @b : @c; # get an array
432 $a = $ok ? @b : @c; # oops, that's just a count!
433
434The operator may be assigned to if both the 2nd and 3rd arguments are
435legal lvalues (meaning that you can assign to them):
a0d0e21e
LW
436
437 ($a_or_b ? $a : $b) = $c;
438
cb1a09d0 439This is not necessarily guaranteed to contribute to the readability of your program.
a0d0e21e 440
4633a7c4 441=head2 Assignment Operators
a0d0e21e
LW
442
443"=" is the ordinary assignment operator.
444
445Assignment operators work as in C. That is,
446
447 $a += 2;
448
449is equivalent to
450
451 $a = $a + 2;
452
453although without duplicating any side effects that dereferencing the lvalue
54310121
PP
454might trigger, such as from tie(). Other assignment operators work similarly.
455The following are recognized:
a0d0e21e
LW
456
457 **= += *= &= <<= &&=
458 -= /= |= >>= ||=
459 .= %= ^=
460 x=
461
462Note that while these are grouped by family, they all have the precedence
463of assignment.
464
465Unlike in C, the assignment operator produces a valid lvalue. Modifying
466an assignment is equivalent to doing the assignment and then modifying
467the variable that was assigned to. This is useful for modifying
468a copy of something, like this:
469
470 ($tmp = $global) =~ tr [A-Z] [a-z];
471
472Likewise,
473
474 ($a += 2) *= 3;
475
476is equivalent to
477
478 $a += 2;
479 $a *= 3;
480
748a9306 481=head2 Comma Operator
a0d0e21e
LW
482
483Binary "," is the comma operator. In a scalar context it evaluates
484its left argument, throws that value away, then evaluates its right
485argument and returns that value. This is just like C's comma operator.
486
487In a list context, it's just the list argument separator, and inserts
488both its arguments into the list.
489
6ee5d4e7 490The =E<gt> digraph is mostly just a synonym for the comma operator. It's useful for
cb1a09d0 491documenting arguments that come in pairs. As of release 5.001, it also forces
4633a7c4 492any word to the left of it to be interpreted as a string.
748a9306 493
a0d0e21e
LW
494=head2 List Operators (Rightward)
495
496On the right side of a list operator, it has very low precedence,
497such that it controls all comma-separated expressions found there.
498The only operators with lower precedence are the logical operators
499"and", "or", and "not", which may be used to evaluate calls to list
500operators without the need for extra parentheses:
501
502 open HANDLE, "filename"
503 or die "Can't open: $!\n";
504
5ba421f6 505See also discussion of list operators in L<Terms and List Operators (Leftward)>.
a0d0e21e
LW
506
507=head2 Logical Not
508
509Unary "not" returns the logical negation of the expression to its right.
510It's the equivalent of "!" except for the very low precedence.
511
512=head2 Logical And
513
514Binary "and" returns the logical conjunction of the two surrounding
515expressions. It's equivalent to && except for the very low
5f05dabc 516precedence. This means that it short-circuits: i.e., the right
a0d0e21e
LW
517expression is evaluated only if the left expression is true.
518
519=head2 Logical or and Exclusive Or
520
521Binary "or" returns the logical disjunction of the two surrounding
522expressions. It's equivalent to || except for the very low
5f05dabc 523precedence. This means that it short-circuits: i.e., the right
a0d0e21e
LW
524expression is evaluated only if the left expression is false.
525
526Binary "xor" returns the exclusive-OR of the two surrounding expressions.
527It cannot short circuit, of course.
528
529=head2 C Operators Missing From Perl
530
531Here is what C has that Perl doesn't:
532
533=over 8
534
535=item unary &
536
537Address-of operator. (But see the "\" operator for taking a reference.)
538
539=item unary *
540
54310121 541Dereference-address operator. (Perl's prefix dereferencing
a0d0e21e
LW
542operators are typed: $, @, %, and &.)
543
544=item (TYPE)
545
54310121 546Type casting operator.
a0d0e21e
LW
547
548=back
549
5f05dabc 550=head2 Quote and Quote-like Operators
a0d0e21e
LW
551
552While we usually think of quotes as literal values, in Perl they
553function as operators, providing various kinds of interpolating and
554pattern matching capabilities. Perl provides customary quote characters
555for these behaviors, but also provides a way for you to choose your
556quote character for any of them. In the following table, a C<{}> represents
557any pair of delimiters you choose. Non-bracketing delimiters use
54310121 558the same character fore and aft, but the 4 sorts of brackets
a0d0e21e
LW
559(round, angle, square, curly) will all nest.
560
2c268ad5
TP
561 Customary Generic Meaning Interpolates
562 '' q{} Literal no
563 "" qq{} Literal yes
564 `` qx{} Command yes
565 qw{} Word list no
566 // m{} Pattern match yes
567 s{}{} Substitution yes
568 tr{}{} Transliteration no (but see below)
a0d0e21e 569
fb73857a
PP
570Note that there can be whitespace between the operator and the quoting
571characters, except when C<#> is being used as the quoting character.
a3cb178b 572C<q#foo#> is parsed as being the string C<foo>, while C<q #foo#> is the
fb73857a
PP
573operator C<q> followed by a comment. Its argument will be taken from the
574next line. This allows you to write:
575
576 s {foo} # Replace foo
577 {bar} # with bar.
578
2c268ad5
TP
579For constructs that do interpolation, variables beginning with "C<$>"
580or "C<@>" are interpolated, as are the following sequences. Within
581a transliteration, the first ten of these sequences may be used.
a0d0e21e 582
6ee5d4e7
PP
583 \t tab (HT, TAB)
584 \n newline (LF, NL)
585 \r return (CR)
586 \f form feed (FF)
587 \b backspace (BS)
588 \a alarm (bell) (BEL)
589 \e escape (ESC)
a0d0e21e
LW
590 \033 octal char
591 \x1b hex char
592 \c[ control char
2c268ad5 593
a0d0e21e
LW
594 \l lowercase next char
595 \u uppercase next char
596 \L lowercase till \E
597 \U uppercase till \E
598 \E end case modification
599 \Q quote regexp metacharacters till \E
600
a034a98d
DD
601If C<use locale> is in effect, the case map used by C<\l>, C<\L>, C<\u>
602and <\U> is taken from the current locale. See L<perllocale>.
603
a0d0e21e
LW
604Patterns are subject to an additional level of interpretation as a
605regular expression. This is done as a second pass, after variables are
606interpolated, so that regular expressions may be incorporated into the
607pattern from the variables. If this is not what you want, use C<\Q> to
608interpolate a variable literally.
609
610Apart from the above, there are no multiple levels of interpolation. In
5f05dabc 611particular, contrary to the expectations of shell programmers, back-quotes
a0d0e21e
LW
612do I<NOT> interpolate within double quotes, nor do single quotes impede
613evaluation of variables when used within double quotes.
614
5f05dabc 615=head2 Regexp Quote-Like Operators
cb1a09d0 616
5f05dabc 617Here are the quote-like operators that apply to pattern
cb1a09d0
AD
618matching and related activities.
619
a0d0e21e
LW
620=over 8
621
622=item ?PATTERN?
623
624This is just like the C</pattern/> search, except that it matches only
625once between calls to the reset() operator. This is a useful
5f05dabc 626optimization when you want to see only the first occurrence of
a0d0e21e
LW
627something in each file of a set of files, for instance. Only C<??>
628patterns local to the current package are reset.
629
630This usage is vaguely deprecated, and may be removed in some future
631version of Perl.
632
fb73857a 633=item m/PATTERN/cgimosx
a0d0e21e 634
fb73857a 635=item /PATTERN/cgimosx
a0d0e21e
LW
636
637Searches a string for a pattern match, and in a scalar context returns
638true (1) or false (''). If no string is specified via the C<=~> or
639C<!~> operator, the $_ string is searched. (The string specified with
640C<=~> need not be an lvalue--it may be the result of an expression
641evaluation, but remember the C<=~> binds rather tightly.) See also
642L<perlre>.
a034a98d
DD
643See L<perllocale> for discussion of additional considerations which apply
644when C<use locale> is in effect.
a0d0e21e
LW
645
646Options are:
647
fb73857a 648 c Do not reset search position on a failed match when /g is in effect.
5f05dabc 649 g Match globally, i.e., find all occurrences.
a0d0e21e
LW
650 i Do case-insensitive pattern matching.
651 m Treat string as multiple lines.
5f05dabc 652 o Compile pattern only once.
a0d0e21e
LW
653 s Treat string as single line.
654 x Use extended regular expressions.
655
656If "/" is the delimiter then the initial C<m> is optional. With the C<m>
657you can use any pair of non-alphanumeric, non-whitespace characters as
658delimiters. This is particularly useful for matching Unix path names
7bac28a0
PP
659that contain "/", to avoid LTS (leaning toothpick syndrome). If "?" is
660the delimiter, then the match-only-once rule of C<?PATTERN?> applies.
a0d0e21e
LW
661
662PATTERN may contain variables, which will be interpolated (and the
663pattern recompiled) every time the pattern search is evaluated. (Note
664that C<$)> and C<$|> might not be interpolated because they look like
665end-of-string tests.) If you want such a pattern to be compiled only
666once, add a C</o> after the trailing delimiter. This avoids expensive
667run-time recompilations, and is useful when the value you are
668interpolating won't change over the life of the script. However, mentioning
669C</o> constitutes a promise that you won't change the variables in the pattern.
670If you change them, Perl won't even notice.
671
4633a7c4 672If the PATTERN evaluates to a null string, the last
a3cb178b 673successfully matched regular expression is used instead.
a0d0e21e
LW
674
675If used in a context that requires a list value, a pattern match returns a
676list consisting of the subexpressions matched by the parentheses in the
5f05dabc 677pattern, i.e., (C<$1>, $2, $3...). (Note that here $1 etc. are also set, and
a0d0e21e
LW
678that this differs from Perl 4's behavior.) If the match fails, a null
679array is returned. If the match succeeds, but there were no parentheses,
680a list value of (1) is returned.
681
682Examples:
683
684 open(TTY, '/dev/tty');
685 <TTY> =~ /^y/i && foo(); # do foo if desired
686
687 if (/Version: *([0-9.]*)/) { $version = $1; }
688
689 next if m#^/usr/spool/uucp#;
690
691 # poor man's grep
692 $arg = shift;
693 while (<>) {
694 print if /$arg/o; # compile only once
695 }
696
697 if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
698
699This last example splits $foo into the first two words and the
5f05dabc
PP
700remainder of the line, and assigns those three fields to $F1, $F2, and
701$Etc. The conditional is true if any variables were assigned, i.e., if
a0d0e21e
LW
702the pattern matched.
703
704The C</g> modifier specifies global pattern matching--that is, matching
705as many times as possible within the string. How it behaves depends on
706the context. In a list context, it returns a list of all the
707substrings matched by all the parentheses in the regular expression.
708If there are no parentheses, it returns a list of all the matched
709strings, as if there were parentheses around the whole pattern.
710
711In a scalar context, C<m//g> iterates through the string, returning TRUE
c90c0ff4
PP
712each time it matches, and FALSE when it eventually runs out of matches.
713(In other words, it remembers where it left off last time and restarts
714the search at that point. You can actually find the current match
715position of a string or set it using the pos() function; see
716L<perlfunc/pos>.) A failed match normally resets the search position to
90248788 717the beginning of the string, but you can avoid that by adding the C</c>
c90c0ff4
PP
718modifier (e.g. C<m//gc>). Modifying the target string also resets the
719search position.
720
721You can intermix C<m//g> matches with C<m/\G.../g>, where C<\G> is a
722zero-width assertion that matches the exact position where the previous
723C<m//g>, if any, left off. The C<\G> assertion is not supported without
724the C</g> modifier; currently, without C</g>, C<\G> behaves just like
725C<\A>, but that's accidental and may change in the future.
726
727Examples:
a0d0e21e
LW
728
729 # list context
730 ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
731
732 # scalar context
5f05dabc 733 $/ = ""; $* = 1; # $* deprecated in modern perls
54310121 734 while (defined($paragraph = <>)) {
a0d0e21e
LW
735 while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) {
736 $sentences++;
737 }
738 }
739 print "$sentences\n";
740
c90c0ff4 741 # using m//gc with \G
137443ea 742 $_ = "ppooqppqq";
44a8e56a
PP
743 while ($i++ < 2) {
744 print "1: '";
c90c0ff4 745 print $1 while /(o)/gc; print "', pos=", pos, "\n";
44a8e56a 746 print "2: '";
c90c0ff4 747 print $1 if /\G(q)/gc; print "', pos=", pos, "\n";
44a8e56a 748 print "3: '";
c90c0ff4 749 print $1 while /(p)/gc; print "', pos=", pos, "\n";
44a8e56a
PP
750 }
751
752The last example should print:
753
754 1: 'oo', pos=4
137443ea 755 2: 'q', pos=5
44a8e56a
PP
756 3: 'pp', pos=7
757 1: '', pos=7
137443ea
PP
758 2: 'q', pos=8
759 3: '', pos=8
44a8e56a 760
c90c0ff4 761A useful idiom for C<lex>-like scanners is C</\G.../gc>. You can
e7ea3e70 762combine several regexps like this to process a string part-by-part,
c90c0ff4
PP
763doing different actions depending on which regexp matched. Each
764regexp tries to match where the previous one leaves off.
e7ea3e70 765
3fe9a6f1 766 $_ = <<'EOL';
e7ea3e70 767 $url = new URI::URL "http://www/"; die if $url eq "xXx";
3fe9a6f1
PP
768 EOL
769 LOOP:
e7ea3e70 770 {
c90c0ff4
PP
771 print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc;
772 print(" lowercase"), redo LOOP if /\G[a-z]+\b[,.;]?\s*/gc;
773 print(" UPPERCASE"), redo LOOP if /\G[A-Z]+\b[,.;]?\s*/gc;
774 print(" Capitalized"), redo LOOP if /\G[A-Z][a-z]+\b[,.;]?\s*/gc;
775 print(" MiXeD"), redo LOOP if /\G[A-Za-z]+\b[,.;]?\s*/gc;
776 print(" alphanumeric"), redo LOOP if /\G[A-Za-z0-9]+\b[,.;]?\s*/gc;
777 print(" line-noise"), redo LOOP if /\G[^A-Za-z0-9]+/gc;
e7ea3e70
IZ
778 print ". That's all!\n";
779 }
780
781Here is the output (split into several lines):
782
783 line-noise lowercase line-noise lowercase UPPERCASE line-noise
784 UPPERCASE line-noise lowercase line-noise lowercase line-noise
785 lowercase lowercase line-noise lowercase lowercase line-noise
786 MiXeD line-noise. That's all!
44a8e56a 787
a0d0e21e
LW
788=item q/STRING/
789
790=item C<'STRING'>
791
68dc0745
PP
792A single-quoted, literal string. A backslash represents a backslash
793unless followed by the delimiter or another backslash, in which case
794the delimiter or backslash is interpolated.
a0d0e21e
LW
795
796 $foo = q!I said, "You said, 'She said it.'"!;
797 $bar = q('This is it.');
68dc0745 798 $baz = '\n'; # a two-character string
a0d0e21e
LW
799
800=item qq/STRING/
801
802=item "STRING"
803
804A double-quoted, interpolated string.
805
806 $_ .= qq
807 (*** The previous line contains the naughty word "$1".\n)
808 if /(tcl|rexx|python)/; # :-)
68dc0745 809 $baz = "\n"; # a one-character string
a0d0e21e
LW
810
811=item qx/STRING/
812
813=item `STRING`
814
815A string which is interpolated and then executed as a system command.
816The collected standard output of the command is returned. In scalar
4a6725af 817context, it comes back as a single (potentially multi-line) string.
a0d0e21e
LW
818In list context, returns a list of lines (however you've defined lines
819with $/ or $INPUT_RECORD_SEPARATOR).
820
821 $today = qx{ date };
822
bb32b41a
GS
823Note that how the string gets evaluated is entirely subject to the
824command interpreter on your system. On most platforms, you will have
825to protect shell metacharacters if you want them treated literally.
826On some platforms (notably DOS-like ones), the shell may not be
827capable of dealing with multiline commands, so putting newlines in
828the string may not get you what you want. You may be able to evaluate
829multiple commands in a single line by separating them with the command
830separator character, if your shell supports that (e.g. C<;> on many Unix
831shells; C<&> on the Windows NT C<cmd> shell).
832
833Beware that some command shells may place restrictions on the length
834of the command line. You must ensure your strings don't exceed this
835limit after any necessary interpolations. See the platform-specific
836release notes for more details about your particular environment.
837
838Also realize that using this operator frequently leads to unportable
839programs.
840
dc848c6f 841See L<"I/O Operators"> for more discussion.
a0d0e21e
LW
842
843=item qw/STRING/
844
845Returns a list of the words extracted out of STRING, using embedded
846whitespace as the word delimiters. It is exactly equivalent to
847
848 split(' ', q/STRING/);
849
850Some frequently seen examples:
851
852 use POSIX qw( setlocale localeconv )
853 @EXPORT = qw( foo bar baz );
854
7bac28a0
PP
855A common mistake is to try to separate the words with comma or to put
856comments into a multi-line qw-string. For this reason the C<-w>
857switch produce warnings if the STRING contains the "," or the "#"
858character.
859
a0d0e21e
LW
860=item s/PATTERN/REPLACEMENT/egimosx
861
862Searches a string for a pattern, and if found, replaces that pattern
863with the replacement text and returns the number of substitutions
e37d713d 864made. Otherwise it returns false (specifically, the empty string).
a0d0e21e
LW
865
866If no string is specified via the C<=~> or C<!~> operator, the C<$_>
867variable is searched and modified. (The string specified with C<=~> must
868be a scalar variable, an array element, a hash element, or an assignment
5f05dabc 869to one of those, i.e., an lvalue.)
a0d0e21e
LW
870
871If the delimiter chosen is single quote, no variable interpolation is
872done on either the PATTERN or the REPLACEMENT. Otherwise, if the
873PATTERN contains a $ that looks like a variable rather than an
874end-of-string test, the variable will be interpolated into the pattern
5f05dabc 875at run-time. If you want the pattern compiled only once the first time
a0d0e21e 876the variable is interpolated, use the C</o> option. If the pattern
4633a7c4 877evaluates to a null string, the last successfully executed regular
a0d0e21e 878expression is used instead. See L<perlre> for further explanation on these.
a034a98d
DD
879See L<perllocale> for discussion of additional considerations which apply
880when C<use locale> is in effect.
a0d0e21e
LW
881
882Options are:
883
884 e Evaluate the right side as an expression.
5f05dabc 885 g Replace globally, i.e., all occurrences.
a0d0e21e
LW
886 i Do case-insensitive pattern matching.
887 m Treat string as multiple lines.
5f05dabc 888 o Compile pattern only once.
a0d0e21e
LW
889 s Treat string as single line.
890 x Use extended regular expressions.
891
892Any non-alphanumeric, non-whitespace delimiter may replace the
893slashes. If single quotes are used, no interpretation is done on the
e37d713d 894replacement string (the C</e> modifier overrides this, however). Unlike
54310121 895Perl 4, Perl 5 treats backticks as normal delimiters; the replacement
e37d713d 896text is not evaluated as a command. If the
a0d0e21e 897PATTERN is delimited by bracketing quotes, the REPLACEMENT has its own
5f05dabc 898pair of quotes, which may or may not be bracketing quotes, e.g.,
a0d0e21e
LW
899C<s(foo)(bar)> or C<sE<lt>fooE<gt>/bar/>. A C</e> will cause the
900replacement portion to be interpreter as a full-fledged Perl expression
901and eval()ed right then and there. It is, however, syntax checked at
902compile-time.
903
904Examples:
905
906 s/\bgreen\b/mauve/g; # don't change wintergreen
907
908 $path =~ s|/usr/bin|/usr/local/bin|;
909
910 s/Login: $foo/Login: $bar/; # run-time pattern
911
912 ($foo = $bar) =~ s/this/that/;
913
914 $count = ($paragraph =~ s/Mister\b/Mr./g);
915
916 $_ = 'abc123xyz';
917 s/\d+/$&*2/e; # yields 'abc246xyz'
918 s/\d+/sprintf("%5d",$&)/e; # yields 'abc 246xyz'
919 s/\w/$& x 2/eg; # yields 'aabbcc 224466xxyyzz'
920
921 s/%(.)/$percent{$1}/g; # change percent escapes; no /e
922 s/%(.)/$percent{$1} || $&/ge; # expr now, so /e
923 s/^=(\w+)/&pod($1)/ge; # use function call
924
925 # /e's can even nest; this will expand
926 # simple embedded variables in $_
927 s/(\$\w+)/$1/eeg;
928
929 # Delete C comments.
930 $program =~ s {
4633a7c4
LW
931 /\* # Match the opening delimiter.
932 .*? # Match a minimal number of characters.
933 \*/ # Match the closing delimiter.
a0d0e21e
LW
934 } []gsx;
935
936 s/^\s*(.*?)\s*$/$1/; # trim white space
937
938 s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
939
54310121 940Note the use of $ instead of \ in the last example. Unlike
5f05dabc 941B<sed>, we use the \E<lt>I<digit>E<gt> form in only the left hand side.
6ee5d4e7 942Anywhere else it's $E<lt>I<digit>E<gt>.
a0d0e21e 943
5f05dabc 944Occasionally, you can't use just a C</g> to get all the changes
a0d0e21e
LW
945to occur. Here are two common cases:
946
947 # put commas in the right places in an integer
948 1 while s/(.*\d)(\d\d\d)/$1,$2/g; # perl4
949 1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g; # perl5
950
951 # expand tabs to 8-column spacing
952 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
953
954
955=item tr/SEARCHLIST/REPLACEMENTLIST/cds
956
957=item y/SEARCHLIST/REPLACEMENTLIST/cds
958
2c268ad5 959Transliterates all occurrences of the characters found in the search list
a0d0e21e
LW
960with the corresponding character in the replacement list. It returns
961the number of characters replaced or deleted. If no string is
2c268ad5 962specified via the =~ or !~ operator, the $_ string is transliterated. (The
54310121
PP
963string specified with =~ must be a scalar variable, an array element, a
964hash element, or an assignment to one of those, i.e., an lvalue.)
2c268ad5
TP
965A character range may be specified with a hyphen, so C<tr/A-J/0-9/>
966does the same replacement as C<tr/ACEGIBDFHJ/0246813579/>.
54310121
PP
967For B<sed> devotees, C<y> is provided as a synonym for C<tr>. If the
968SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has
969its own pair of quotes, which may or may not be bracketing quotes,
2c268ad5 970e.g., C<tr[A-Z][a-z]> or C<tr(+\-*/)/ABCD/>.
a0d0e21e
LW
971
972Options:
973
974 c Complement the SEARCHLIST.
975 d Delete found but unreplaced characters.
976 s Squash duplicate replaced characters.
977
978If the C</c> modifier is specified, the SEARCHLIST character set is
979complemented. If the C</d> modifier is specified, any characters specified
980by SEARCHLIST not found in REPLACEMENTLIST are deleted. (Note
981that this is slightly more flexible than the behavior of some B<tr>
982programs, which delete anything they find in the SEARCHLIST, period.)
983If the C</s> modifier is specified, sequences of characters that were
2c268ad5 984transliterated to the same character are squashed down to a single instance of the
a0d0e21e
LW
985character.
986
987If the C</d> modifier is used, the REPLACEMENTLIST is always interpreted
988exactly as specified. Otherwise, if the REPLACEMENTLIST is shorter
989than the SEARCHLIST, the final character is replicated till it is long
990enough. If the REPLACEMENTLIST is null, the SEARCHLIST is replicated.
991This latter is useful for counting characters in a class or for
992squashing character sequences in a class.
993
994Examples:
995
996 $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case
997
998 $cnt = tr/*/*/; # count the stars in $_
999
1000 $cnt = $sky =~ tr/*/*/; # count the stars in $sky
1001
1002 $cnt = tr/0-9//; # count the digits in $_
1003
1004 tr/a-zA-Z//s; # bookkeeper -> bokeper
1005
1006 ($HOST = $host) =~ tr/a-z/A-Z/;
1007
1008 tr/a-zA-Z/ /cs; # change non-alphas to single space
1009
1010 tr [\200-\377]
1011 [\000-\177]; # delete 8th bit
1012
2c268ad5 1013If multiple transliterations are given for a character, only the first one is used:
748a9306
LW
1014
1015 tr/AAA/XYZ/
1016
2c268ad5 1017will transliterate any A to X.
748a9306 1018
2c268ad5 1019Note that because the transliteration table is built at compile time, neither
a0d0e21e
LW
1020the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote
1021interpolation. That means that if you want to use variables, you must use
1022an eval():
1023
1024 eval "tr/$oldlist/$newlist/";
1025 die $@ if $@;
1026
1027 eval "tr/$oldlist/$newlist/, 1" or die $@;
1028
1029=back
1030
1031=head2 I/O Operators
1032
54310121
PP
1033There are several I/O operators you should know about.
1034A string is enclosed by backticks (grave accents) first undergoes
a0d0e21e
LW
1035variable substitution just like a double quoted string. It is then
1036interpreted as a command, and the output of that command is the value
1037of the pseudo-literal, like in a shell. In a scalar context, a single
1038string consisting of all the output is returned. In a list context,
1039a list of values is returned, one for each line of output. (You can
1040set C<$/> to use a different line terminator.) The command is executed
1041each time the pseudo-literal is evaluated. The status value of the
1042command is returned in C<$?> (see L<perlvar> for the interpretation
1043of C<$?>). Unlike in B<csh>, no translation is done on the return
1044data--newlines remain newlines. Unlike in any of the shells, single
1045quotes do not hide variable names in the command from interpretation.
1046To pass a $ through to the shell you need to hide it with a backslash.
54310121
PP
1047The generalized form of backticks is C<qx//>. (Because backticks
1048always undergo shell expansion as well, see L<perlsec> for
cb1a09d0 1049security concerns.)
a0d0e21e
LW
1050
1051Evaluating a filehandle in angle brackets yields the next line from
aa689395
PP
1052that file (newline, if any, included), or C<undef> at end of file.
1053Ordinarily you must assign that value to a variable, but there is one
1054situation where an automatic assignment happens. I<If and ONLY if> the
1055input symbol is the only thing inside the conditional of a C<while> or
1056C<for(;;)> loop, the value is automatically assigned to the variable
1057C<$_>. The assigned value is then tested to see if it is defined.
1058(This may seem like an odd thing to you, but you'll use the construct
1059in almost every Perl script you write.) Anyway, the following lines
1060are equivalent to each other:
a0d0e21e 1061
748a9306 1062 while (defined($_ = <STDIN>)) { print; }
a0d0e21e
LW
1063 while (<STDIN>) { print; }
1064 for (;<STDIN>;) { print; }
748a9306 1065 print while defined($_ = <STDIN>);
a0d0e21e
LW
1066 print while <STDIN>;
1067
5f05dabc
PP
1068The filehandles STDIN, STDOUT, and STDERR are predefined. (The
1069filehandles C<stdin>, C<stdout>, and C<stderr> will also work except in
a0d0e21e
LW
1070packages, where they would be interpreted as local identifiers rather
1071than global.) Additional filehandles may be created with the open()
cb1a09d0 1072function. See L<perlfunc/open()> for details on this.
a0d0e21e 1073
6ee5d4e7 1074If a E<lt>FILEHANDLEE<gt> is used in a context that is looking for a list, a
a0d0e21e
LW
1075list consisting of all the input lines is returned, one line per list
1076element. It's easy to make a I<LARGE> data space this way, so use with
1077care.
1078
d28ebecd
PP
1079The null filehandle E<lt>E<gt> is special and can be used to emulate the
1080behavior of B<sed> and B<awk>. Input from E<lt>E<gt> comes either from
a0d0e21e 1081standard input, or from each file listed on the command line. Here's
d28ebecd 1082how it works: the first time E<lt>E<gt> is evaluated, the @ARGV array is
a0d0e21e
LW
1083checked, and if it is null, C<$ARGV[0]> is set to "-", which when opened
1084gives you standard input. The @ARGV array is then processed as a list
1085of filenames. The loop
1086
1087 while (<>) {
1088 ... # code for each line
1089 }
1090
1091is equivalent to the following Perl-like pseudo code:
1092
3e3baf6d 1093 unshift(@ARGV, '-') unless @ARGV;
a0d0e21e
LW
1094 while ($ARGV = shift) {
1095 open(ARGV, $ARGV);
1096 while (<ARGV>) {
1097 ... # code for each line
1098 }
1099 }
1100
1101except that it isn't so cumbersome to say, and will actually work. It
1102really does shift array @ARGV and put the current filename into variable
5f05dabc
PP
1103$ARGV. It also uses filehandle I<ARGV> internally--E<lt>E<gt> is just a
1104synonym for E<lt>ARGVE<gt>, which is magical. (The pseudo code above
1105doesn't work because it treats E<lt>ARGVE<gt> as non-magical.)
a0d0e21e 1106
d28ebecd 1107You can modify @ARGV before the first E<lt>E<gt> as long as the array ends up
a0d0e21e
LW
1108containing the list of filenames you really want. Line numbers (C<$.>)
1109continue as if the input were one big happy file. (But see example
1110under eof() for how to reset line numbers on each file.)
1111
1112If you want to set @ARGV to your own list of files, go right ahead. If
54310121 1113you want to pass switches into your script, you can use one of the
a0d0e21e
LW
1114Getopts modules or put a loop on the front like this:
1115
1116 while ($_ = $ARGV[0], /^-/) {
1117 shift;
1118 last if /^--$/;
1119 if (/^-D(.*)/) { $debug = $1 }
1120 if (/^-v/) { $verbose++ }
1121 ... # other switches
1122 }
1123 while (<>) {
1124 ... # code for each line
1125 }
1126
d28ebecd 1127The E<lt>E<gt> symbol will return FALSE only once. If you call it again after
a0d0e21e
LW
1128this it will assume you are processing another @ARGV list, and if you
1129haven't set @ARGV, will input from STDIN.
1130
1131If the string inside the angle brackets is a reference to a scalar
5f05dabc 1132variable (e.g., E<lt>$fooE<gt>), then that variable contains the name of the
cb1a09d0
AD
1133filehandle to input from, or a reference to the same. For example:
1134
1135 $fh = \*STDIN;
1136 $line = <$fh>;
a0d0e21e 1137
cb1a09d0
AD
1138If the string inside angle brackets is not a filehandle or a scalar
1139variable containing a filehandle name or reference, then it is interpreted
4633a7c4
LW
1140as a filename pattern to be globbed, and either a list of filenames or the
1141next filename in the list is returned, depending on context. One level of
1142$ interpretation is done first, but you can't say C<E<lt>$fooE<gt>>
1143because that's an indirect filehandle as explained in the previous
6ee5d4e7 1144paragraph. (In older versions of Perl, programmers would insert curly
4633a7c4 1145brackets to force interpretation as a filename glob: C<E<lt>${foo}E<gt>>.
d28ebecd 1146These days, it's considered cleaner to call the internal function directly
4633a7c4
LW
1147as C<glob($foo)>, which is probably the right way to have done it in the
1148first place.) Example:
a0d0e21e
LW
1149
1150 while (<*.c>) {
1151 chmod 0644, $_;
1152 }
1153
1154is equivalent to
1155
1156 open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|");
1157 while (<FOO>) {
1158 chop;
1159 chmod 0644, $_;
1160 }
1161
1162In fact, it's currently implemented that way. (Which means it will not
1163work on filenames with spaces in them unless you have csh(1) on your
1164machine.) Of course, the shortest way to do the above is:
1165
1166 chmod 0644, <*.c>;
1167
1168Because globbing invokes a shell, it's often faster to call readdir() yourself
5f05dabc 1169and do your own grep() on the filenames. Furthermore, due to its current
54310121 1170implementation of using a shell, the glob() routine may get "Arg list too
a0d0e21e
LW
1171long" errors (unless you've installed tcsh(1L) as F</bin/csh>).
1172
5f05dabc 1173A glob evaluates its (embedded) argument only when it is starting a new
4633a7c4
LW
1174list. All values must be read before it will start over. In a list
1175context this isn't important, because you automatically get them all
1176anyway. In a scalar context, however, the operator returns the next value
1177each time it is called, or a FALSE value if you've just run out. Again,
1178FALSE is returned only once. So if you're expecting a single value from
1179a glob, it is much better to say
1180
1181 ($file) = <blurch*>;
1182
1183than
1184
1185 $file = <blurch*>;
1186
1187because the latter will alternate between returning a filename and
54310121 1188returning FALSE.
4633a7c4
LW
1189
1190It you're trying to do variable interpolation, it's definitely better
1191to use the glob() function, because the older notation can cause people
e37d713d 1192to become confused with the indirect filehandle notation.
4633a7c4
LW
1193
1194 @files = glob("$dir/*.[ch]");
1195 @files = glob($files[$i]);
1196
a0d0e21e
LW
1197=head2 Constant Folding
1198
1199Like C, Perl does a certain amount of expression evaluation at
1200compile time, whenever it determines that all of the arguments to an
1201operator are static and have no side effects. In particular, string
1202concatenation happens at compile time between literals that don't do
1203variable substitution. Backslash interpretation also happens at
1204compile time. You can say
1205
1206 'Now is the time for all' . "\n" .
1207 'good men to come to.'
1208
54310121 1209and this all reduces to one string internally. Likewise, if
a0d0e21e
LW
1210you say
1211
1212 foreach $file (@filenames) {
1213 if (-s $file > 5 + 100 * 2**16) { ... }
54310121 1214 }
a0d0e21e 1215
54310121 1216the compiler will precompute the number that
a0d0e21e
LW
1217expression represents so that the interpreter
1218won't have to.
1219
2c268ad5
TP
1220=head2 Bitwise String Operators
1221
1222Bitstrings of any size may be manipulated by the bitwise operators
1223(C<~ | & ^>).
1224
1225If the operands to a binary bitwise op are strings of different sizes,
1226B<or> and B<xor> ops will act as if the shorter operand had additional
1227zero bits on the right, while the B<and> op will act as if the longer
1228operand were truncated to the length of the shorter.
1229
1230 # ASCII-based examples
1231 print "j p \n" ^ " a h"; # prints "JAPH\n"
1232 print "JA" | " ph\n"; # prints "japh\n"
1233 print "japh\nJunk" & '_____'; # prints "JAPH\n";
1234 print 'p N$' ^ " E<H\n"; # prints "Perl\n";
1235
1236If you are intending to manipulate bitstrings, you should be certain that
1237you're supplying bitstrings: If an operand is a number, that will imply
1238a B<numeric> bitwise operation. You may explicitly show which type of
1239operation you intend by using C<""> or C<0+>, as in the examples below.
1240
1241 $foo = 150 | 105 ; # yields 255 (0x96 | 0x69 is 0xFF)
1242 $foo = '150' | 105 ; # yields 255
1243 $foo = 150 | '105'; # yields 255
1244 $foo = '150' | '105'; # yields string '155' (under ASCII)
1245
1246 $baz = 0+$foo & 0+$bar; # both ops explicitly numeric
1247 $biz = "$foo" ^ "$bar"; # both ops explicitly stringy
a0d0e21e 1248
55497cff 1249=head2 Integer Arithmetic
a0d0e21e
LW
1250
1251By default Perl assumes that it must do most of its arithmetic in
1252floating point. But by saying
1253
1254 use integer;
1255
1256you may tell the compiler that it's okay to use integer operations
1257from here to the end of the enclosing BLOCK. An inner BLOCK may
54310121 1258countermand this by saying
a0d0e21e
LW
1259
1260 no integer;
1261
1262which lasts until the end of that BLOCK.
1263
55497cff 1264The bitwise operators ("&", "|", "^", "~", "<<", and ">>") always
2c268ad5
TP
1265produce integral results. (But see also L<Bitwise String Operators>.)
1266However, C<use integer> still has meaning
55497cff
PP
1267for them. By default, their results are interpreted as unsigned
1268integers. However, if C<use integer> is in effect, their results are
5f05dabc 1269interpreted as signed integers. For example, C<~0> usually evaluates
55497cff 1270to a large integral value. However, C<use integer; ~0> is -1.
68dc0745
PP
1271
1272=head2 Floating-point Arithmetic
1273
1274While C<use integer> provides integer-only arithmetic, there is no
1275similar ways to provide rounding or truncation at a certain number of
1276decimal places. For rounding to a certain number of digits, sprintf()
1277or printf() is usually the easiest route.
1278
1279The POSIX module (part of the standard perl distribution) implements
1280ceil(), floor(), and a number of other mathematical and trigonometric
1281functions. The Math::Complex module (part of the standard perl
1282distribution) defines a number of mathematical functions that can also
1283work on real numbers. Math::Complex not as efficient as POSIX, but
1284POSIX can't work with complex numbers.
1285
1286Rounding in financial applications can have serious implications, and
1287the rounding method used should be specified precisely. In these
1288cases, it probably pays not to trust whichever system rounding is
1289being used by Perl, but to instead implement the rounding function you
1290need yourself.