This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
pod/perlsyn: for is equivalent to "foreach'
[perl5.git] / pod / perlsyn.pod
CommitLineData
a0d0e21e 1=head1 NAME
d74e8afc 2X<syntax>
a0d0e21e
LW
3
4perlsyn - Perl syntax
5
6=head1 DESCRIPTION
7
6014d0cb
MS
8A Perl program consists of a sequence of declarations and statements
9which run from the top to the bottom. Loops, subroutines and other
10control structures allow you to jump around within the code.
11
12Perl is a B<free-form> language, you can format and indent it however
13you like. Whitespace mostly serves to separate tokens, unlike
14languages like Python where it is an important part of the syntax.
15
16Many of Perl's syntactic elements are B<optional>. Rather than
110b9c83 17requiring you to put parentheses around every function call and
6014d0cb
MS
18declare every variable, you can often leave such explicit elements off
19and Perl will figure out what you meant. This is known as B<Do What I
20Mean>, abbreviated B<DWIM>. It allows programmers to be B<lazy> and to
110b9c83 21code in a style with which they are comfortable.
6014d0cb
MS
22
23Perl B<borrows syntax> and concepts from many languages: awk, sed, C,
24Bourne Shell, Smalltalk, Lisp and even English. Other
25languages have borrowed syntax from Perl, particularly its regular
26expression extensions. So if you have programmed in another language
27you will see familiar pieces in Perl. They often work the same, but
28see L<perltrap> for information about how they differ.
a0d0e21e 29
0b8d69e9 30=head2 Declarations
d74e8afc 31X<declaration> X<undef> X<undefined> X<uninitialized>
0b8d69e9 32
cf48932e
SF
33The only things you need to declare in Perl are report formats and
34subroutines (and sometimes not even subroutines). A variable holds
35the undefined value (C<undef>) until it has been assigned a defined
36value, which is anything other than C<undef>. When used as a number,
37C<undef> is treated as C<0>; when used as a string, it is treated as
38the empty string, C<"">; and when used as a reference that isn't being
39assigned to, it is treated as an error. If you enable warnings,
40you'll be notified of an uninitialized value whenever you treat
41C<undef> as a string or a number. Well, usually. Boolean contexts,
42such as:
7bd1983c
EM
43
44 my $a;
45 if ($a) {}
46
a6b1f6d8
RGS
47are exempt from warnings (because they care about truth rather than
48definedness). Operators such as C<++>, C<-->, C<+=>,
7bd1983c
EM
49C<-=>, and C<.=>, that operate on undefined left values such as:
50
51 my $a;
52 $a++;
53
54are also always exempt from such warnings.
0b8d69e9 55
a0d0e21e
LW
56A declaration can be put anywhere a statement can, but has no effect on
57the execution of the primary sequence of statements--declarations all
58take effect at compile time. Typically all the declarations are put at
54310121 59the beginning or the end of the script. However, if you're using
0b8d69e9
GS
60lexically-scoped private variables created with C<my()>, you'll
61have to make sure
4633a7c4 62your format or subroutine definition is within the same block scope
5f05dabc 63as the my if you expect to be able to access those private variables.
a0d0e21e 64
4633a7c4
LW
65Declaring a subroutine allows a subroutine name to be used as if it were a
66list operator from that point forward in the program. You can declare a
54310121 67subroutine without defining it by saying C<sub name>, thus:
d74e8afc 68X<subroutine, declaration>
a0d0e21e 69
54310121 70 sub myname;
a0d0e21e
LW
71 $me = myname $0 or die "can't get myname";
72
1f950eb4
JB
73Note that myname() functions as a list operator, not as a unary operator;
74so be careful to use C<or> instead of C<||> in this case. However, if
54310121 75you were to declare the subroutine as C<sub myname ($)>, then
02c45c47 76C<myname> would function as a unary operator, so either C<or> or
54310121 77C<||> would work.
a0d0e21e 78
4633a7c4
LW
79Subroutines declarations can also be loaded up with the C<require> statement
80or both loaded and imported into your namespace with a C<use> statement.
81See L<perlmod> for details on this.
a0d0e21e 82
4633a7c4
LW
83A statement sequence may contain declarations of lexically-scoped
84variables, but apart from declaring a variable name, the declaration acts
85like an ordinary statement, and is elaborated within the sequence of
86statements as if it were an ordinary statement. That means it actually
87has both compile-time and run-time effects.
a0d0e21e 88
6014d0cb 89=head2 Comments
d74e8afc 90X<comment> X<#>
6014d0cb
MS
91
92Text from a C<"#"> character until the end of the line is a comment,
93and is ignored. Exceptions include C<"#"> inside a string or regular
94expression.
95
6ec4bd10 96=head2 Simple Statements
d74e8afc 97X<statement> X<semicolon> X<expression> X<;>
a0d0e21e
LW
98
99The only kind of simple statement is an expression evaluated for its
100side effects. Every simple statement must be terminated with a
101semicolon, unless it is the final statement in a block, in which case
f386e492
AMS
102the semicolon is optional. (A semicolon is still encouraged if the
103block takes up more than one line, because you may eventually add
cf48932e
SF
104another line.) Note that there are some operators like C<eval {}> and
105C<do {}> that look like compound statements, but aren't (they're just
106TERMs in an expression), and thus need an explicit termination if used
107as the last item in a statement.
108
109=head2 Truth and Falsehood
d74e8afc 110X<truth> X<falsehood> X<true> X<false> X<!> X<not> X<negation> X<0>
cf48932e 111
f92061c1
AMS
112The number 0, the strings C<'0'> and C<''>, the empty list C<()>, and
113C<undef> are all false in a boolean context. All other values are true.
52ea55c9
SP
114Negation of a true value by C<!> or C<not> returns a special false value.
115When evaluated as a string it is treated as C<''>, but as a number, it
116is treated as 0.
cf48932e 117
cf48932e 118=head2 Statement Modifiers
d74e8afc 119X<statement modifier> X<modifier> X<if> X<unless> X<while>
4f8ea571 120X<until> X<when> X<foreach> X<for>
a0d0e21e
LW
121
122Any simple statement may optionally be followed by a I<SINGLE> modifier,
123just before the terminating semicolon (or block ending). The possible
124modifiers are:
125
126 if EXPR
127 unless EXPR
128 while EXPR
129 until EXPR
4f8ea571
VP
130 when EXPR
131 for LIST
cf48932e
SF
132 foreach LIST
133
134The C<EXPR> following the modifier is referred to as the "condition".
135Its truth or falsehood determines how the modifier will behave.
136
137C<if> executes the statement once I<if> and only if the condition is
138true. C<unless> is the opposite, it executes the statement I<unless>
139the condition is true (i.e., if the condition is false).
140
141 print "Basset hounds got long ears" if length $ear >= 10;
142 go_outside() and play() unless $is_raining;
143
4f8ea571
VP
144C<when> executes the statement I<when> C<$_> smart matches C<EXPR>, and
145then either C<break>s out if it's enclosed in a C<given> scope or skips
146to the C<next> element when it lies directly inside a C<for> loop.
147See also L</"Switch statements">.
148
149 given ($something) {
150 $abc = 1 when /^abc/;
151 $just_a = 1 when /^a/;
152 $other = 1;
153 }
154
155 for (@names) {
156 admin($_) when [ qw/Alice Bob/ ];
157 regular($_) when [ qw/Chris David Ellen/ ];
158 }
159
cf48932e
SF
160The C<foreach> modifier is an iterator: it executes the statement once
161for each item in the LIST (with C<$_> aliased to each item in turn).
162
163 print "Hello $_!\n" foreach qw(world Dolly nurse);
164
165C<while> repeats the statement I<while> the condition is true.
166C<until> does the opposite, it repeats the statement I<until> the
167condition is true (or while the condition is false):
168
169 # Both of these count from 0 to 10.
170 print $i++ while $i <= 10;
171 print $j++ until $j > 10;
172
173The C<while> and C<until> modifiers have the usual "C<while> loop"
174semantics (conditional evaluated first), except when applied to a
175C<do>-BLOCK (or to the deprecated C<do>-SUBROUTINE statement), in
176which case the block executes once before the conditional is
177evaluated. This is so that you can write loops like:
a0d0e21e
LW
178
179 do {
4633a7c4 180 $line = <STDIN>;
a0d0e21e 181 ...
4633a7c4 182 } until $line eq ".\n";
a0d0e21e 183
5a964f20
TC
184See L<perlfunc/do>. Note also that the loop control statements described
185later will I<NOT> work in this construct, because modifiers don't take
186loop labels. Sorry. You can always put another block inside of it
187(for C<next>) or around it (for C<last>) to do that sort of thing.
f86cebdf 188For C<next>, just double the braces:
d74e8afc 189X<next> X<last> X<redo>
5a964f20
TC
190
191 do {{
192 next if $x == $y;
193 # do something here
194 }} until $x++ > $z;
195
f86cebdf 196For C<last>, you have to be more elaborate:
d74e8afc 197X<last>
5a964f20
TC
198
199 LOOP: {
200 do {
201 last if $x = $y**2;
202 # do something here
203 } while $x++ <= $z;
204 }
a0d0e21e 205
457b36cb
MV
206B<NOTE:> The behaviour of a C<my> statement modified with a statement
207modifier conditional or loop construct (e.g. C<my $x if ...>) is
208B<undefined>. The value of the C<my> variable may be C<undef>, any
209previously assigned value, or possibly anything else. Don't rely on
210it. Future versions of perl might do something different from the
211version of perl you try it out on. Here be dragons.
d74e8afc 212X<my>
457b36cb 213
6ec4bd10 214=head2 Compound Statements
d74e8afc
ITB
215X<statement, compound> X<block> X<bracket, curly> X<curly bracket> X<brace>
216X<{> X<}> X<if> X<unless> X<while> X<until> X<foreach> X<for> X<continue>
a0d0e21e
LW
217
218In Perl, a sequence of statements that defines a scope is called a block.
219Sometimes a block is delimited by the file containing it (in the case
220of a required file, or the program as a whole), and sometimes a block
221is delimited by the extent of a string (in the case of an eval).
222
223But generally, a block is delimited by curly brackets, also known as braces.
224We will call this syntactic construct a BLOCK.
225
226The following compound statements may be used to control flow:
227
228 if (EXPR) BLOCK
229 if (EXPR) BLOCK else BLOCK
230 if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
62d98eed
RU
231 unless (EXPR) BLOCK
232 unless (EXPR) BLOCK else BLOCK
d27f8d4b 233 unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
a0d0e21e
LW
234 LABEL while (EXPR) BLOCK
235 LABEL while (EXPR) BLOCK continue BLOCK
5ec6d87f
EA
236 LABEL until (EXPR) BLOCK
237 LABEL until (EXPR) BLOCK continue BLOCK
a0d0e21e 238 LABEL for (EXPR; EXPR; EXPR) BLOCK
7808b687
AB
239 LABEL for VAR (LIST) BLOCK
240 LABEL for VAR (LIST) BLOCK continue BLOCK
241 LABEL foreach (EXPR; EXPR; EXPR) BLOCK
748a9306 242 LABEL foreach VAR (LIST) BLOCK
b303ae78 243 LABEL foreach VAR (LIST) BLOCK continue BLOCK
a0d0e21e 244 LABEL BLOCK continue BLOCK
43f66a76 245 PHASE BLOCK
a0d0e21e
LW
246
247Note that, unlike C and Pascal, these are defined in terms of BLOCKs,
248not statements. This means that the curly brackets are I<required>--no
249dangling statements allowed. If you want to write conditionals without
250curly brackets there are several other ways to do it. The following
251all do the same thing:
252
253 if (!open(FOO)) { die "Can't open $FOO: $!"; }
254 die "Can't open $FOO: $!" unless open(FOO);
255 open(FOO) or die "Can't open $FOO: $!"; # FOO or bust!
256 open(FOO) ? 'hi mom' : die "Can't open $FOO: $!";
257 # a bit exotic, that last one
258
5f05dabc 259The C<if> statement is straightforward. Because BLOCKs are always
a0d0e21e
LW
260bounded by curly brackets, there is never any ambiguity about which
261C<if> an C<else> goes with. If you use C<unless> in place of C<if>,
d27f8d4b
JV
262the sense of the test is reversed. Like C<if>, C<unless> can be followed
263by C<else>. C<unless> can even be followed by one or more C<elsif>
264statements, though you may want to think twice before using that particular
265language construct, as everyone reading your code will have to think at least
266twice before they can understand what's going on.
a0d0e21e
LW
267
268The C<while> statement executes the block as long as the expression is
e17b7802 269L<true|/"Truth and Falsehood">.
1d5653dd
RGS
270The C<until> statement executes the block as long as the expression is
271false.
b78218b7
GS
272The LABEL is optional, and if present, consists of an identifier followed
273by a colon. The LABEL identifies the loop for the loop control
274statements C<next>, C<last>, and C<redo>.
275If the LABEL is omitted, the loop control statement
4633a7c4
LW
276refers to the innermost enclosing loop. This may include dynamically
277looking back your call-stack at run time to find the LABEL. Such
9f1b1f2d 278desperate behavior triggers a warning if you use the C<use warnings>
a2293a43 279pragma or the B<-w> flag.
4633a7c4
LW
280
281If there is a C<continue> BLOCK, it is always executed just before the
6ec4bd10
MS
282conditional is about to be evaluated again. Thus it can be used to
283increment a loop variable, even when the loop has been continued via
284the C<next> statement.
4633a7c4 285
43f66a76
DG
286When a block is preceding by a compilation phase keyword such as C<BEGIN>,
287C<END>, C<INIT>, C<CHECK>, or C<UNITCHECK>, then the block will run only
288during the corresponding phase of execution. See L<perlmod> for more details.
289
88e1f1a2
JV
290Extension modules can also hook into the Perl parser to define new
291kinds of compound statement. These are introduced by a keyword which
6a0969e5 292the extension recognizes, and the syntax following the keyword is
88e1f1a2
JV
293defined entirely by the extension. If you are an implementor, see
294L<perlapi/PL_keyword_plugin> for the mechanism. If you are using such
295a module, see the module's documentation for details of the syntax that
296it defines.
297
4633a7c4 298=head2 Loop Control
d74e8afc 299X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue>
4633a7c4 300
6ec4bd10 301The C<next> command starts the next iteration of the loop:
4633a7c4
LW
302
303 LINE: while (<STDIN>) {
304 next LINE if /^#/; # discard comments
305 ...
306 }
307
6ec4bd10 308The C<last> command immediately exits the loop in question. The
4633a7c4
LW
309C<continue> block, if any, is not executed:
310
311 LINE: while (<STDIN>) {
312 last LINE if /^$/; # exit when done with header
313 ...
314 }
315
316The C<redo> command restarts the loop block without evaluating the
317conditional again. The C<continue> block, if any, is I<not> executed.
318This command is normally used by programs that want to lie to themselves
319about what was just input.
320
321For example, when processing a file like F</etc/termcap>.
322If your input lines might end in backslashes to indicate continuation, you
323want to skip ahead and get the next record.
324
325 while (<>) {
326 chomp;
54310121 327 if (s/\\$//) {
328 $_ .= <>;
4633a7c4
LW
329 redo unless eof();
330 }
331 # now process $_
54310121 332 }
4633a7c4
LW
333
334which is Perl short-hand for the more explicitly written version:
335
54310121 336 LINE: while (defined($line = <ARGV>)) {
4633a7c4 337 chomp($line);
54310121 338 if ($line =~ s/\\$//) {
339 $line .= <ARGV>;
4633a7c4
LW
340 redo LINE unless eof(); # not eof(ARGV)!
341 }
342 # now process $line
54310121 343 }
4633a7c4 344
36e7a065
AMS
345Note that if there were a C<continue> block on the above code, it would
346get executed only on lines discarded by the regex (since redo skips the
347continue block). A continue block is often used to reset line counters
499a640d 348or C<m?pat?> one-time matches:
4633a7c4 349
5a964f20
TC
350 # inspired by :1,$g/fred/s//WILMA/
351 while (<>) {
499a640d
TC
352 m?(fred)? && s//WILMA $1 WILMA/;
353 m?(barney)? && s//BETTY $1 BETTY/;
354 m?(homer)? && s//MARGE $1 MARGE/;
5a964f20
TC
355 } continue {
356 print "$ARGV $.: $_";
499a640d
TC
357 close ARGV if eof; # reset $.
358 reset if eof; # reset ?pat?
4633a7c4
LW
359 }
360
a0d0e21e
LW
361If the word C<while> is replaced by the word C<until>, the sense of the
362test is reversed, but the conditional is still tested before the first
363iteration.
364
5a964f20
TC
365The loop control statements don't work in an C<if> or C<unless>, since
366they aren't loops. You can double the braces to make them such, though.
367
368 if (/pattern/) {{
7bd1983c
EM
369 last if /fred/;
370 next if /barney/; # same effect as "last", but doesn't document as well
371 # do something here
5a964f20
TC
372 }}
373
7bd1983c 374This is caused by the fact that a block by itself acts as a loop that
27cec4bd 375executes once, see L<"Basic BLOCKs">.
7bd1983c 376
5b23ba8b
MG
377The form C<while/if BLOCK BLOCK>, available in Perl 4, is no longer
378available. Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>.
4633a7c4 379
cb1a09d0 380=head2 For Loops
d74e8afc 381X<for> X<foreach>
a0d0e21e 382
b78df5de 383Perl's C-style C<for> loop works like the corresponding C<while> loop;
cb1a09d0 384that means that this:
a0d0e21e
LW
385
386 for ($i = 1; $i < 10; $i++) {
387 ...
388 }
389
cb1a09d0 390is the same as this:
a0d0e21e
LW
391
392 $i = 1;
393 while ($i < 10) {
394 ...
395 } continue {
396 $i++;
397 }
398
b78df5de
JA
399There is one minor difference: if variables are declared with C<my>
400in the initialization section of the C<for>, the lexical scope of
401those variables is exactly the C<for> loop (the body of the loop
402and the control sections).
d74e8afc 403X<my>
55497cff 404
cb1a09d0
AD
405Besides the normal array index looping, C<for> can lend itself
406to many other interesting applications. Here's one that avoids the
54310121 407problem you get into if you explicitly test for end-of-file on
408an interactive file descriptor causing your program to appear to
cb1a09d0 409hang.
d74e8afc 410X<eof> X<end-of-file> X<end of file>
cb1a09d0
AD
411
412 $on_a_tty = -t STDIN && -t STDOUT;
413 sub prompt { print "yes? " if $on_a_tty }
414 for ( prompt(); <STDIN>; prompt() ) {
415 # do something
54310121 416 }
cb1a09d0 417
00cb5da1
CW
418Using C<readline> (or the operator form, C<< <EXPR> >>) as the
419conditional of a C<for> loop is shorthand for the following. This
420behaviour is the same as a C<while> loop conditional.
d74e8afc 421X<readline> X<< <> >>
00cb5da1
CW
422
423 for ( prompt(); defined( $_ = <STDIN> ); prompt() ) {
424 # do something
425 }
426
cb1a09d0 427=head2 Foreach Loops
d74e8afc 428X<for> X<foreach>
cb1a09d0 429
4633a7c4 430The C<foreach> loop iterates over a normal list value and sets the
55497cff 431variable VAR to be each element of the list in turn. If the variable
432is preceded with the keyword C<my>, then it is lexically scoped, and
433is therefore visible only within the loop. Otherwise, the variable is
434implicitly local to the loop and regains its former value upon exiting
435the loop. If the variable was previously declared with C<my>, it uses
436that variable instead of the global one, but it's still localized to
6a0969e5 437the loop. This implicit localization occurs I<only> in a C<foreach>
5c502d37 438loop.
d74e8afc 439X<my> X<local>
4633a7c4
LW
440
441The C<foreach> keyword is actually a synonym for the C<for> keyword, so
5a964f20
TC
442you can use C<foreach> for readability or C<for> for brevity. (Or because
443the Bourne shell is more familiar to you than I<csh>, so writing C<for>
f86cebdf 444comes more naturally.) If VAR is omitted, C<$_> is set to each value.
d74e8afc 445X<$_>
c5674021
PDF
446
447If any element of LIST is an lvalue, you can modify it by modifying
448VAR inside the loop. Conversely, if any element of LIST is NOT an
449lvalue, any attempt to modify that element will fail. In other words,
450the C<foreach> loop index variable is an implicit alias for each item
451in the list that you're looping over.
d74e8afc 452X<alias>
302617ea
MG
453
454If any part of LIST is an array, C<foreach> will get very confused if
455you add or remove elements within the loop body, for example with
456C<splice>. So don't do that.
d74e8afc 457X<splice>
302617ea
MG
458
459C<foreach> probably won't do what you expect if VAR is a tied or other
460special variable. Don't do that either.
4633a7c4 461
748a9306 462Examples:
a0d0e21e 463
4633a7c4 464 for (@ary) { s/foo/bar/ }
a0d0e21e 465
96f2dc66 466 for my $elem (@elements) {
a0d0e21e
LW
467 $elem *= 2;
468 }
469
4633a7c4
LW
470 for $count (10,9,8,7,6,5,4,3,2,1,'BOOM') {
471 print $count, "\n"; sleep(1);
a0d0e21e
LW
472 }
473
474 for (1..15) { print "Merry Christmas\n"; }
475
4633a7c4 476 foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
a0d0e21e
LW
477 print "Item: $item\n";
478 }
479
4633a7c4
LW
480Here's how a C programmer might code up a particular algorithm in Perl:
481
55497cff 482 for (my $i = 0; $i < @ary1; $i++) {
483 for (my $j = 0; $j < @ary2; $j++) {
4633a7c4
LW
484 if ($ary1[$i] > $ary2[$j]) {
485 last; # can't go to outer :-(
486 }
487 $ary1[$i] += $ary2[$j];
488 }
cb1a09d0 489 # this is where that last takes me
4633a7c4
LW
490 }
491
184e9718 492Whereas here's how a Perl programmer more comfortable with the idiom might
cb1a09d0 493do it:
4633a7c4 494
96f2dc66
GS
495 OUTER: for my $wid (@ary1) {
496 INNER: for my $jet (@ary2) {
cb1a09d0
AD
497 next OUTER if $wid > $jet;
498 $wid += $jet;
54310121 499 }
500 }
4633a7c4 501
cb1a09d0
AD
502See how much easier this is? It's cleaner, safer, and faster. It's
503cleaner because it's less noisy. It's safer because if code gets added
c07a80fd 504between the inner and outer loops later on, the new code won't be
5f05dabc 505accidentally executed. The C<next> explicitly iterates the other loop
c07a80fd 506rather than merely terminating the inner one. And it's faster because
507Perl executes a C<foreach> statement more rapidly than it would the
508equivalent C<for> loop.
4633a7c4 509
0d863452
RH
510=head2 Basic BLOCKs
511X<block>
4633a7c4 512
55497cff 513A BLOCK by itself (labeled or not) is semantically equivalent to a
514loop that executes once. Thus you can use any of the loop control
515statements in it to leave or restart the block. (Note that this is
516I<NOT> true in C<eval{}>, C<sub{}>, or contrary to popular belief
517C<do{}> blocks, which do I<NOT> count as loops.) The C<continue>
518block is optional.
4633a7c4 519
27cec4bd 520The BLOCK construct can be used to emulate case structures.
a0d0e21e
LW
521
522 SWITCH: {
523 if (/^abc/) { $abc = 1; last SWITCH; }
524 if (/^def/) { $def = 1; last SWITCH; }
525 if (/^xyz/) { $xyz = 1; last SWITCH; }
526 $nothing = 1;
527 }
528
0d863452
RH
529Such constructs are quite frequently used, because older versions
530of Perl had no official C<switch> statement.
83df6a1d 531
0d863452 532=head2 Switch statements
fd4f5766 533
0d863452 534X<switch> X<case> X<given> X<when> X<default>
83df6a1d 535
27cec4bd 536Starting from Perl 5.10, you can say
83df6a1d 537
27cec4bd 538 use feature "switch";
a0d0e21e 539
0d863452 540which enables a switch feature that is closely based on the
4a904372
FC
541Perl 6 proposal. Starting from Perl 5.16, one can prefix the switch
542keywords with C<CORE::> to access the feature without a C<use feature>
543statement.
0d863452
RH
544
545The keywords C<given> and C<when> are analogous
546to C<switch> and C<case> in other languages, so the code
547above could be written as
548
27cec4bd
RGS
549 given($_) {
550 when (/^abc/) { $abc = 1; }
551 when (/^def/) { $def = 1; }
552 when (/^xyz/) { $xyz = 1; }
553 default { $nothing = 1; }
a0d0e21e
LW
554 }
555
0d863452 556This construct is very flexible and powerful. For example:
a0d0e21e 557
4b7b0ae4
RH
558 use feature ":5.10";
559 given($foo) {
560 when (undef) {
561 say '$foo is undefined';
562 }
4b7b0ae4
RH
563 when ("foo") {
564 say '$foo is the string "foo"';
565 }
4b7b0ae4
RH
566 when ([1,3,5,7,9]) {
567 say '$foo is an odd digit';
568 continue; # Fall through
9f435386 569 }
4b7b0ae4
RH
570 when ($_ < 100) {
571 say '$foo is numerically less than 100';
572 }
4b7b0ae4 573 when (\&complicated_check) {
f92e1a16 574 say 'a complicated check for $foo is true';
4b7b0ae4 575 }
4b7b0ae4
RH
576 default {
577 die q(I don't know what to do with $foo);
578 }
579 }
580
581C<given(EXPR)> will assign the value of EXPR to C<$_>
582within the lexical scope of the block, so it's similar to
583
584 do { my $_ = EXPR; ... }
585
586except that the block is automatically broken out of by a
587successful C<when> or an explicit C<break>.
588
589Most of the power comes from implicit smart matching:
a0d0e21e 590
4b7b0ae4 591 when($foo)
a0d0e21e 592
0d863452 593is exactly equivalent to
a0d0e21e 594
4b7b0ae4 595 when($_ ~~ $foo)
a0d0e21e 596
b3ed409d
CS
597Most of the time, C<when(EXPR)> is treated as an implicit smart match of
598C<$_>, i.e. C<$_ ~~ EXPR>. (See L</"Smart matching in detail"> for more
599information on smart matching.) But when EXPR is one of the below
600exceptional cases, it is used directly as a boolean:
0d863452
RH
601
602=over 4
603
d991eed6 604=item *
0d863452
RH
605
606a subroutine or method call
607
d991eed6 608=item *
0d863452
RH
609
610a regular expression match, i.e. C</REGEX/> or C<$foo =~ /REGEX/>,
f92e1a16 611or a negated regular expression match (C<!/REGEX/> or C<$foo !~ /REGEX/>).
0d863452 612
d991eed6 613=item *
0d863452 614
4b7b0ae4
RH
615a comparison such as C<$_ E<lt> 10> or C<$x eq "abc">
616(or of course C<$_ ~~ $c>)
0d863452 617
d991eed6 618=item *
0d863452
RH
619
620C<defined(...)>, C<exists(...)>, or C<eof(...)>
621
d991eed6 622=item *
4633a7c4 623
f92e1a16 624a negated expression C<!(...)> or C<not (...)>, or a logical
0d863452 625exclusive-or C<(...) xor (...)>.
cb1a09d0 626
516817b4
RGS
627=item *
628
629a filetest operator, with the exception of C<-s>, C<-M>, C<-A>, and C<-C>,
630that return numerical values, not boolean ones.
631
202d7cbd
RGS
632=item *
633
f118ea0d 634the C<..> and C<...> flip-flop operators.
202d7cbd 635
0d863452
RH
636=back
637
f92e1a16
RGS
638In those cases the value of EXPR is used directly as a boolean.
639
a4fce065
AD
640Furthermore, Perl inspects the operands of the binary boolean operators to
641decide whether to use smart matching for each one by applying the above test to
642the operands:
0d863452
RH
643
644=over 4
645
f92e1a16 646=item *
0d863452
RH
647
648If EXPR is C<... && ...> or C<... and ...>, the test
a4fce065
AD
649is applied recursively to both operands. If I<both>
650operands pass the test, then the expression is treated
651as boolean; otherwise, smart matching is used.
0d863452 652
f92e1a16 653=item *
0d863452 654
f92e1a16 655If EXPR is C<... || ...>, C<... // ...> or C<... or ...>, the test
a4fce065
AD
656is applied recursively to the first operand (which may be a
657higher-precedence AND operator, for example). If the first operand
658is to use smart matching, then both operands will do so; if it is
659not, then the second argument will not be either.
0d863452
RH
660
661=back
662
663These rules look complicated, but usually they will do what
a4fce065 664you want. For example:
0d863452 665
f849b90f 666 when (/^\d+$/ && $_ < 75) { ... }
0d863452 667
a4fce065
AD
668will be treated as a boolean match because the rules say both a regex match and
669an explicit test on $_ will be treated as boolean.
670
671Also:
672
673 when ([qw(foo bar)] && /baz/) { ... }
674
675will use smart matching because only I<one> of the operands is a boolean; the
676other uses smart matching, and that wins.
677
678Further:
679
680 when ([qw(foo bar)] || /^baz/) { ... }
681
682will use smart matching (only the first operand is considered), whereas
683
684 when (/^baz/ || [qw(foo bar)]) { ... }
685
686will test only the regex, which causes both operands to be treated as boolean.
687Watch out for this one, then, because an arrayref is always a true value, which
688makes it effectively redundant.
689
6a0969e5 690Tautologous boolean operators are still going to be optimized away. Don't be
a4fce065
AD
691tempted to write
692
693 when ('foo' or 'bar') { ... }
694
6a0969e5 695This will optimize down to C<'foo'>, so C<'bar'> will never be considered (even
a4fce065
AD
696though the rules say to use a smart match on C<'foo'>). For an alternation like
697this, an array ref will work, because this will instigate smart matching:
698
699 when ([qw(foo bar)] { ... }
700
701This is somewhat equivalent to the C-style switch statement's fallthrough
702functionality (not to be confused with I<Perl's> fallthrough functionality - see
703below), wherein the same block is used for several C<case> statements.
704
4b7b0ae4 705Another useful shortcut is that, if you use a literal array
107bd117 706or hash as the argument to C<given>, it is turned into a
4b7b0ae4
RH
707reference. So C<given(@foo)> is the same as C<given(\@foo)>,
708for example.
709
0d863452
RH
710C<default> behaves exactly like C<when(1 == 1)>, which is
711to say that it always matches.
712
4b7b0ae4
RH
713=head3 Breaking out
714
715You can use the C<break> keyword to break out of the enclosing
716C<given> block. Every C<when> block is implicitly ended with
717a C<break>.
718
0d863452
RH
719=head3 Fall-through
720
721You can use the C<continue> keyword to fall through from one
722case to the next:
723
27cec4bd 724 given($foo) {
4b7b0ae4
RH
725 when (/x/) { say '$foo contains an x'; continue }
726 when (/y/) { say '$foo contains a y' }
02e7afe2 727 default { say '$foo does not contain a y' }
27cec4bd 728 }
0d863452 729
25b991bf
VP
730=head3 Return value
731
732When a C<given> statement is also a valid expression (e.g.
06b608b9 733when it's the last statement of a block), it evaluates to :
25b991bf
VP
734
735=over 4
736
737=item *
738
06b608b9 739an empty list as soon as an explicit C<break> is encountered.
25b991bf
VP
740
741=item *
742
06b608b9 743the value of the last evaluated expression of the successful
25b991bf
VP
744C<when>/C<default> clause, if there's one.
745
746=item *
747
06b608b9
VP
748the value of the last evaluated expression of the C<given> block if no
749condition is true.
25b991bf
VP
750
751=back
752
06b608b9
VP
753In both last cases, the last expression is evaluated in the context that
754was applied to the C<given> block.
755
756Note that, unlike C<if> and C<unless>, failed C<when> statements always
757evaluate to an empty list.
25b991bf
VP
758
759 my $price = do { given ($item) {
760 when ([ 'pear', 'apple' ]) { 1 }
761 break when 'vote'; # My vote cannot be bought
762 1e10 when /Mona Lisa/;
763 'unknown';
764 } };
765
06b608b9 766Currently, C<given> blocks can't always be used as proper expressions. This
25b991bf
VP
767may be addressed in a future version of perl.
768
0d863452
RH
769=head3 Switching in a loop
770
771Instead of using C<given()>, you can use a C<foreach()> loop.
772For example, here's one way to count how many times a particular
773string occurs in an array:
774
27cec4bd
RGS
775 my $count = 0;
776 for (@array) {
777 when ("foo") { ++$count }
5a964f20 778 }
27cec4bd 779 print "\@array contains $count copies of 'foo'\n";
0d863452 780
54091fc3 781At the end of all C<when> blocks, there is an implicit C<next>.
0d863452
RH
782You can override that with an explicit C<last> if you're only
783interested in the first match.
784
785This doesn't work if you explicitly specify a loop variable,
786as in C<for $item (@array)>. You have to use the default
787variable C<$_>. (You can use C<for my $_ (@array)>.)
788
789=head3 Smart matching in detail
790
202d7cbd
RGS
791The behaviour of a smart match depends on what type of thing its arguments
792are. The behaviour is determined by the following table: the first row
793that applies determines the match behaviour (which is thus mostly
794determined by the type of the right operand). Note that the smart match
d0b243e3
RGS
795implicitly dereferences any non-blessed hash or array ref, so the "Hash"
796and "Array" entries apply in those cases. (For blessed references, the
c6ebb512 797"Object" entries apply.)
4b7b0ae4 798
b3ed409d
CS
799Note that the "Matching Code" column is not always an exact rendition. For
800example, the smart match operator short-circuits whenever possible, but
801C<grep> does not.
802
4b7b0ae4
RH
803 $a $b Type of Match Implied Matching Code
804 ====== ===== ===================== =============
202d7cbd
RGS
805 Any undef undefined !defined $a
806
c6ebb512 807 Any Object invokes ~~ overloading on $object, or dies
4b7b0ae4 808
168ff818
RGS
809 Hash CodeRef sub truth for each key[1] !grep { !$b->($_) } keys %$a
810 Array CodeRef sub truth for each elt[1] !grep { !$b->($_) } @$a
811 Any CodeRef scalar sub truth $b->($a)
4b7b0ae4 812
6f76d139 813 Hash Hash hash keys identical (every key is found in both hashes)
a8b2c106 814 Array Hash hash keys intersection grep { exists $b->{$_} } @$a
07edf497 815 Regex Hash hash key grep grep /$a/, keys %$b
202d7cbd
RGS
816 undef Hash always false (undef can't be a key)
817 Any Hash hash entry existence exists $b->{$a}
818
a8b2c106 819 Hash Array hash keys intersection grep { exists $a->{$_} } @$b
168ff818 820 Array Array arrays are comparable[2]
c3886e8b
RGS
821 Regex Array array grep grep /$a/, @$b
822 undef Array array contains undef grep !defined, @$b
168ff818 823 Any Array match against an array element[3]
c3886e8b 824 grep $a ~~ $_, @$b
4b7b0ae4 825
202d7cbd 826 Hash Regex hash key grep grep /$b/, keys %$a
4b7b0ae4 827 Array Regex array grep grep /$b/, @$a
4b7b0ae4 828 Any Regex pattern match $a =~ /$b/
202d7cbd 829
2c9d2554 830 Object Any invokes ~~ overloading on $object, or falls back:
0d7c3953 831 undef Any undefined !defined($b)
4b7b0ae4 832 Any Num numeric equality $a == $b
f118ea0d 833 Num numish[4] numeric equality $a == $b
4b7b0ae4
RH
834 Any Any string equality $a eq $b
835
07edf497 836 1 - empty hashes or arrays will match.
329802ba
RGS
837 2 - that is, each element smart-matches the element of same index in the
838 other array. [3]
168ff818 839 3 - If a circular reference is found, we fall back to referential equality.
f118ea0d 840 4 - either a real number, or a string that looks like a number
0d863452 841
0d863452 842=head3 Custom matching via overloading
5a964f20 843
0d863452 844You can change the way that an object is matched by overloading
0de1c906 845the C<~~> operator. This may alter the usual smart match semantics.
5a964f20 846
202d7cbd
RGS
847It should be noted that C<~~> will refuse to work on objects that
848don't overload it (in order to avoid relying on the object's
2da5311b 849underlying structure).
202d7cbd 850
0de1c906
DM
851Note also that smart match's matching rules take precedence over
852overloading, so if C<$obj> has smart match overloading, then
853
854 $obj ~~ X
855
856will not automatically invoke the overload method with X as an argument;
857instead the table above is consulted as normal, and based in the type of X,
858overloading may or may not be invoked.
859
860See L<overload>.
861
54a85b95
RH
862=head3 Differences from Perl 6
863
864The Perl 5 smart match and C<given>/C<when> constructs are not
865absolutely identical to their Perl 6 analogues. The most visible
866difference is that, in Perl 5, parentheses are required around
4f8ea571
VP
867the argument to C<given()> and C<when()> (except when this last
868one is used as a statement modifier). Parentheses in Perl 6
54a85b95
RH
869are always optional in a control construct such as C<if()>,
870C<while()>, or C<when()>; they can't be made optional in Perl
8715 without a great deal of potential confusion, because Perl 5
872would parse the expression
873
874 given $foo {
875 ...
876 }
877
878as though the argument to C<given> were an element of the hash
879C<%foo>, interpreting the braces as hash-element syntax.
880
ccc668fa
RGS
881The table of smart matches is not identical to that proposed by the
882Perl 6 specification, mainly due to the differences between Perl 6's
883and Perl 5's data models.
54a85b95
RH
884
885In Perl 6, C<when()> will always do an implicit smart match
886with its argument, whilst it is convenient in Perl 5 to
887suppress this implicit smart match in certain situations,
888as documented above. (The difference is largely because Perl 5
889does not, even internally, have a boolean type.)
890
4633a7c4 891=head2 Goto
d74e8afc 892X<goto>
4633a7c4 893
19799a22
GS
894Although not for the faint of heart, Perl does support a C<goto>
895statement. There are three forms: C<goto>-LABEL, C<goto>-EXPR, and
896C<goto>-&NAME. A loop's LABEL is not actually a valid target for
897a C<goto>; it's just the name of the loop.
4633a7c4 898
f86cebdf 899The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
4633a7c4 900execution there. It may not be used to go into any construct that
f86cebdf 901requires initialization, such as a subroutine or a C<foreach> loop. It
4633a7c4
LW
902also can't be used to go into a construct that is optimized away. It
903can be used to go almost anywhere else within the dynamic scope,
904including out of subroutines, but it's usually better to use some other
f86cebdf
GS
905construct such as C<last> or C<die>. The author of Perl has never felt the
906need to use this form of C<goto> (in Perl, that is--C is another matter).
4633a7c4 907
f86cebdf
GS
908The C<goto>-EXPR form expects a label name, whose scope will be resolved
909dynamically. This allows for computed C<goto>s per FORTRAN, but isn't
4633a7c4
LW
910necessarily recommended if you're optimizing for maintainability:
911
96f2dc66 912 goto(("FOO", "BAR", "GLARCH")[$i]);
4633a7c4 913
f86cebdf 914The C<goto>-&NAME form is highly magical, and substitutes a call to the
4633a7c4 915named subroutine for the currently running subroutine. This is used by
f86cebdf 916C<AUTOLOAD()> subroutines that wish to load another subroutine and then
4633a7c4 917pretend that the other subroutine had been called in the first place
f86cebdf
GS
918(except that any modifications to C<@_> in the current subroutine are
919propagated to the other subroutine.) After the C<goto>, not even C<caller()>
4633a7c4
LW
920will be able to tell that this routine was called first.
921
c07a80fd 922In almost all cases like this, it's usually a far, far better idea to use the
923structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of
4633a7c4
LW
924resorting to a C<goto>. For certain applications, the catch and throw pair of
925C<eval{}> and die() for exception processing can also be a prudent approach.
cb1a09d0
AD
926
927=head2 PODs: Embedded Documentation
d74e8afc 928X<POD> X<documentation>
cb1a09d0
AD
929
930Perl has a mechanism for intermixing documentation with source code.
c07a80fd 931While it's expecting the beginning of a new statement, if the compiler
cb1a09d0
AD
932encounters a line that begins with an equal sign and a word, like this
933
934 =head1 Here There Be Pods!
935
936Then that text and all remaining text up through and including a line
937beginning with C<=cut> will be ignored. The format of the intervening
54310121 938text is described in L<perlpod>.
cb1a09d0
AD
939
940This allows you to intermix your source code
941and your documentation text freely, as in
942
943 =item snazzle($)
944
54310121 945 The snazzle() function will behave in the most spectacular
cb1a09d0
AD
946 form that you can possibly imagine, not even excepting
947 cybernetic pyrotechnics.
948
949 =cut back to the compiler, nuff of this pod stuff!
950
951 sub snazzle($) {
952 my $thingie = shift;
953 .........
54310121 954 }
cb1a09d0 955
54310121 956Note that pod translators should look at only paragraphs beginning
184e9718 957with a pod directive (it makes parsing easier), whereas the compiler
54310121 958actually knows to look for pod escapes even in the middle of a
cb1a09d0
AD
959paragraph. This means that the following secret stuff will be
960ignored by both the compiler and the translators.
961
962 $a=3;
963 =secret stuff
964 warn "Neither POD nor CODE!?"
965 =cut back
966 print "got $a\n";
967
f86cebdf 968You probably shouldn't rely upon the C<warn()> being podded out forever.
cb1a09d0
AD
969Not all pod translators are well-behaved in this regard, and perhaps
970the compiler will become pickier.
774d564b 971
972One may also use pod directives to quickly comment out a section
973of code.
974
975=head2 Plain Old Comments (Not!)
d74e8afc 976X<comment> X<line> X<#> X<preprocessor> X<eval>
774d564b 977
6ec4bd10 978Perl can process line directives, much like the C preprocessor. Using
5a964f20 979this, one can control Perl's idea of filenames and line numbers in
774d564b 980error or warning messages (especially for strings that are processed
24802a74
A
981with C<eval()>). The syntax for this mechanism is almost the same as for
982most C preprocessors: it matches the regular expression
6ec4bd10
MS
983
984 # example: '# line 42 "new_filename.plx"'
82d4537c 985 /^\# \s*
6ec4bd10 986 line \s+ (\d+) \s*
d8b950dc 987 (?:\s("?)([^"]+)\g2)? \s*
6ec4bd10
MS
988 $/x
989
7b6e93a8 990with C<$1> being the line number for the next line, and C<$3> being
24802a74 991the optional filename (specified with or without quotes). Note that
c69ca1d4 992no whitespace may precede the C<< # >>, unlike modern C preprocessors.
774d564b 993
003183f2
GS
994There is a fairly obvious gotcha included with the line directive:
995Debuggers and profilers will only show the last source line to appear
996at a particular line number in a given file. Care should be taken not
997to cause line number collisions in code you'd like to debug later.
998
774d564b 999Here are some examples that you should be able to type into your command
1000shell:
1001
1002 % perl
1003 # line 200 "bzzzt"
0c78c5bc 1004 # the '#' on the previous line must be the first char on line
774d564b 1005 die 'foo';
1006 __END__
1007 foo at bzzzt line 201.
54310121 1008
774d564b 1009 % perl
1010 # line 200 "bzzzt"
1011 eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
1012 __END__
1013 foo at - line 2001.
54310121 1014
774d564b 1015 % perl
1016 eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
1017 __END__
1018 foo at foo bar line 200.
54310121 1019
774d564b 1020 % perl
1021 # line 345 "goop"
1022 eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
1023 print $@;
1024 __END__
1025 foo at goop line 345.
1026
1027=cut