This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Clarify docs for implicit "next" on all "when" blocks
[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
231 LABEL while (EXPR) BLOCK
232 LABEL while (EXPR) BLOCK continue BLOCK
5ec6d87f
EA
233 LABEL until (EXPR) BLOCK
234 LABEL until (EXPR) BLOCK continue BLOCK
a0d0e21e 235 LABEL for (EXPR; EXPR; EXPR) BLOCK
748a9306 236 LABEL foreach VAR (LIST) BLOCK
b303ae78 237 LABEL foreach VAR (LIST) BLOCK continue BLOCK
a0d0e21e
LW
238 LABEL BLOCK continue BLOCK
239
240Note that, unlike C and Pascal, these are defined in terms of BLOCKs,
241not statements. This means that the curly brackets are I<required>--no
242dangling statements allowed. If you want to write conditionals without
243curly brackets there are several other ways to do it. The following
244all do the same thing:
245
246 if (!open(FOO)) { die "Can't open $FOO: $!"; }
247 die "Can't open $FOO: $!" unless open(FOO);
248 open(FOO) or die "Can't open $FOO: $!"; # FOO or bust!
249 open(FOO) ? 'hi mom' : die "Can't open $FOO: $!";
250 # a bit exotic, that last one
251
5f05dabc 252The C<if> statement is straightforward. Because BLOCKs are always
a0d0e21e
LW
253bounded by curly brackets, there is never any ambiguity about which
254C<if> an C<else> goes with. If you use C<unless> in place of C<if>,
255the sense of the test is reversed.
256
257The C<while> statement executes the block as long as the expression is
e17b7802 258L<true|/"Truth and Falsehood">.
1d5653dd
RGS
259The C<until> statement executes the block as long as the expression is
260false.
b78218b7
GS
261The LABEL is optional, and if present, consists of an identifier followed
262by a colon. The LABEL identifies the loop for the loop control
263statements C<next>, C<last>, and C<redo>.
264If the LABEL is omitted, the loop control statement
4633a7c4
LW
265refers to the innermost enclosing loop. This may include dynamically
266looking back your call-stack at run time to find the LABEL. Such
9f1b1f2d 267desperate behavior triggers a warning if you use the C<use warnings>
a2293a43 268pragma or the B<-w> flag.
4633a7c4
LW
269
270If there is a C<continue> BLOCK, it is always executed just before the
6ec4bd10
MS
271conditional is about to be evaluated again. Thus it can be used to
272increment a loop variable, even when the loop has been continued via
273the C<next> statement.
4633a7c4 274
88e1f1a2
JV
275Extension modules can also hook into the Perl parser to define new
276kinds of compound statement. These are introduced by a keyword which
277the extension recognises, and the syntax following the keyword is
278defined entirely by the extension. If you are an implementor, see
279L<perlapi/PL_keyword_plugin> for the mechanism. If you are using such
280a module, see the module's documentation for details of the syntax that
281it defines.
282
4633a7c4 283=head2 Loop Control
d74e8afc 284X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue>
4633a7c4 285
6ec4bd10 286The C<next> command starts the next iteration of the loop:
4633a7c4
LW
287
288 LINE: while (<STDIN>) {
289 next LINE if /^#/; # discard comments
290 ...
291 }
292
6ec4bd10 293The C<last> command immediately exits the loop in question. The
4633a7c4
LW
294C<continue> block, if any, is not executed:
295
296 LINE: while (<STDIN>) {
297 last LINE if /^$/; # exit when done with header
298 ...
299 }
300
301The C<redo> command restarts the loop block without evaluating the
302conditional again. The C<continue> block, if any, is I<not> executed.
303This command is normally used by programs that want to lie to themselves
304about what was just input.
305
306For example, when processing a file like F</etc/termcap>.
307If your input lines might end in backslashes to indicate continuation, you
308want to skip ahead and get the next record.
309
310 while (<>) {
311 chomp;
54310121 312 if (s/\\$//) {
313 $_ .= <>;
4633a7c4
LW
314 redo unless eof();
315 }
316 # now process $_
54310121 317 }
4633a7c4
LW
318
319which is Perl short-hand for the more explicitly written version:
320
54310121 321 LINE: while (defined($line = <ARGV>)) {
4633a7c4 322 chomp($line);
54310121 323 if ($line =~ s/\\$//) {
324 $line .= <ARGV>;
4633a7c4
LW
325 redo LINE unless eof(); # not eof(ARGV)!
326 }
327 # now process $line
54310121 328 }
4633a7c4 329
36e7a065
AMS
330Note that if there were a C<continue> block on the above code, it would
331get executed only on lines discarded by the regex (since redo skips the
332continue block). A continue block is often used to reset line counters
333or C<?pat?> one-time matches:
4633a7c4 334
5a964f20
TC
335 # inspired by :1,$g/fred/s//WILMA/
336 while (<>) {
337 ?(fred)? && s//WILMA $1 WILMA/;
338 ?(barney)? && s//BETTY $1 BETTY/;
339 ?(homer)? && s//MARGE $1 MARGE/;
340 } continue {
341 print "$ARGV $.: $_";
342 close ARGV if eof(); # reset $.
343 reset if eof(); # reset ?pat?
4633a7c4
LW
344 }
345
a0d0e21e
LW
346If the word C<while> is replaced by the word C<until>, the sense of the
347test is reversed, but the conditional is still tested before the first
348iteration.
349
5a964f20
TC
350The loop control statements don't work in an C<if> or C<unless>, since
351they aren't loops. You can double the braces to make them such, though.
352
353 if (/pattern/) {{
7bd1983c
EM
354 last if /fred/;
355 next if /barney/; # same effect as "last", but doesn't document as well
356 # do something here
5a964f20
TC
357 }}
358
7bd1983c 359This is caused by the fact that a block by itself acts as a loop that
27cec4bd 360executes once, see L<"Basic BLOCKs">.
7bd1983c 361
5b23ba8b
MG
362The form C<while/if BLOCK BLOCK>, available in Perl 4, is no longer
363available. Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>.
4633a7c4 364
cb1a09d0 365=head2 For Loops
d74e8afc 366X<for> X<foreach>
a0d0e21e 367
b78df5de 368Perl's C-style C<for> loop works like the corresponding C<while> loop;
cb1a09d0 369that means that this:
a0d0e21e
LW
370
371 for ($i = 1; $i < 10; $i++) {
372 ...
373 }
374
cb1a09d0 375is the same as this:
a0d0e21e
LW
376
377 $i = 1;
378 while ($i < 10) {
379 ...
380 } continue {
381 $i++;
382 }
383
b78df5de
JA
384There is one minor difference: if variables are declared with C<my>
385in the initialization section of the C<for>, the lexical scope of
386those variables is exactly the C<for> loop (the body of the loop
387and the control sections).
d74e8afc 388X<my>
55497cff 389
cb1a09d0
AD
390Besides the normal array index looping, C<for> can lend itself
391to many other interesting applications. Here's one that avoids the
54310121 392problem you get into if you explicitly test for end-of-file on
393an interactive file descriptor causing your program to appear to
cb1a09d0 394hang.
d74e8afc 395X<eof> X<end-of-file> X<end of file>
cb1a09d0
AD
396
397 $on_a_tty = -t STDIN && -t STDOUT;
398 sub prompt { print "yes? " if $on_a_tty }
399 for ( prompt(); <STDIN>; prompt() ) {
400 # do something
54310121 401 }
cb1a09d0 402
00cb5da1
CW
403Using C<readline> (or the operator form, C<< <EXPR> >>) as the
404conditional of a C<for> loop is shorthand for the following. This
405behaviour is the same as a C<while> loop conditional.
d74e8afc 406X<readline> X<< <> >>
00cb5da1
CW
407
408 for ( prompt(); defined( $_ = <STDIN> ); prompt() ) {
409 # do something
410 }
411
cb1a09d0 412=head2 Foreach Loops
d74e8afc 413X<for> X<foreach>
cb1a09d0 414
4633a7c4 415The C<foreach> loop iterates over a normal list value and sets the
55497cff 416variable VAR to be each element of the list in turn. If the variable
417is preceded with the keyword C<my>, then it is lexically scoped, and
418is therefore visible only within the loop. Otherwise, the variable is
419implicitly local to the loop and regains its former value upon exiting
420the loop. If the variable was previously declared with C<my>, it uses
421that variable instead of the global one, but it's still localized to
5c502d37
MV
422the loop. This implicit localisation occurs I<only> in a C<foreach>
423loop.
d74e8afc 424X<my> X<local>
4633a7c4
LW
425
426The C<foreach> keyword is actually a synonym for the C<for> keyword, so
5a964f20
TC
427you can use C<foreach> for readability or C<for> for brevity. (Or because
428the Bourne shell is more familiar to you than I<csh>, so writing C<for>
f86cebdf 429comes more naturally.) If VAR is omitted, C<$_> is set to each value.
d74e8afc 430X<$_>
c5674021
PDF
431
432If any element of LIST is an lvalue, you can modify it by modifying
433VAR inside the loop. Conversely, if any element of LIST is NOT an
434lvalue, any attempt to modify that element will fail. In other words,
435the C<foreach> loop index variable is an implicit alias for each item
436in the list that you're looping over.
d74e8afc 437X<alias>
302617ea
MG
438
439If any part of LIST is an array, C<foreach> will get very confused if
440you add or remove elements within the loop body, for example with
441C<splice>. So don't do that.
d74e8afc 442X<splice>
302617ea
MG
443
444C<foreach> probably won't do what you expect if VAR is a tied or other
445special variable. Don't do that either.
4633a7c4 446
748a9306 447Examples:
a0d0e21e 448
4633a7c4 449 for (@ary) { s/foo/bar/ }
a0d0e21e 450
96f2dc66 451 for my $elem (@elements) {
a0d0e21e
LW
452 $elem *= 2;
453 }
454
4633a7c4
LW
455 for $count (10,9,8,7,6,5,4,3,2,1,'BOOM') {
456 print $count, "\n"; sleep(1);
a0d0e21e
LW
457 }
458
459 for (1..15) { print "Merry Christmas\n"; }
460
4633a7c4 461 foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
a0d0e21e
LW
462 print "Item: $item\n";
463 }
464
4633a7c4
LW
465Here's how a C programmer might code up a particular algorithm in Perl:
466
55497cff 467 for (my $i = 0; $i < @ary1; $i++) {
468 for (my $j = 0; $j < @ary2; $j++) {
4633a7c4
LW
469 if ($ary1[$i] > $ary2[$j]) {
470 last; # can't go to outer :-(
471 }
472 $ary1[$i] += $ary2[$j];
473 }
cb1a09d0 474 # this is where that last takes me
4633a7c4
LW
475 }
476
184e9718 477Whereas here's how a Perl programmer more comfortable with the idiom might
cb1a09d0 478do it:
4633a7c4 479
96f2dc66
GS
480 OUTER: for my $wid (@ary1) {
481 INNER: for my $jet (@ary2) {
cb1a09d0
AD
482 next OUTER if $wid > $jet;
483 $wid += $jet;
54310121 484 }
485 }
4633a7c4 486
cb1a09d0
AD
487See how much easier this is? It's cleaner, safer, and faster. It's
488cleaner because it's less noisy. It's safer because if code gets added
c07a80fd 489between the inner and outer loops later on, the new code won't be
5f05dabc 490accidentally executed. The C<next> explicitly iterates the other loop
c07a80fd 491rather than merely terminating the inner one. And it's faster because
492Perl executes a C<foreach> statement more rapidly than it would the
493equivalent C<for> loop.
4633a7c4 494
0d863452
RH
495=head2 Basic BLOCKs
496X<block>
4633a7c4 497
55497cff 498A BLOCK by itself (labeled or not) is semantically equivalent to a
499loop that executes once. Thus you can use any of the loop control
500statements in it to leave or restart the block. (Note that this is
501I<NOT> true in C<eval{}>, C<sub{}>, or contrary to popular belief
502C<do{}> blocks, which do I<NOT> count as loops.) The C<continue>
503block is optional.
4633a7c4 504
27cec4bd 505The BLOCK construct can be used to emulate case structures.
a0d0e21e
LW
506
507 SWITCH: {
508 if (/^abc/) { $abc = 1; last SWITCH; }
509 if (/^def/) { $def = 1; last SWITCH; }
510 if (/^xyz/) { $xyz = 1; last SWITCH; }
511 $nothing = 1;
512 }
513
0d863452
RH
514Such constructs are quite frequently used, because older versions
515of Perl had no official C<switch> statement.
83df6a1d 516
0d863452
RH
517=head2 Switch statements
518X<switch> X<case> X<given> X<when> X<default>
83df6a1d 519
27cec4bd 520Starting from Perl 5.10, you can say
83df6a1d 521
27cec4bd 522 use feature "switch";
a0d0e21e 523
0d863452
RH
524which enables a switch feature that is closely based on the
525Perl 6 proposal.
526
527The keywords C<given> and C<when> are analogous
528to C<switch> and C<case> in other languages, so the code
529above could be written as
530
27cec4bd
RGS
531 given($_) {
532 when (/^abc/) { $abc = 1; }
533 when (/^def/) { $def = 1; }
534 when (/^xyz/) { $xyz = 1; }
535 default { $nothing = 1; }
a0d0e21e
LW
536 }
537
0d863452 538This construct is very flexible and powerful. For example:
a0d0e21e 539
4b7b0ae4
RH
540 use feature ":5.10";
541 given($foo) {
542 when (undef) {
543 say '$foo is undefined';
544 }
4b7b0ae4
RH
545 when ("foo") {
546 say '$foo is the string "foo"';
547 }
4b7b0ae4
RH
548 when ([1,3,5,7,9]) {
549 say '$foo is an odd digit';
550 continue; # Fall through
9f435386 551 }
4b7b0ae4
RH
552 when ($_ < 100) {
553 say '$foo is numerically less than 100';
554 }
4b7b0ae4 555 when (\&complicated_check) {
f92e1a16 556 say 'a complicated check for $foo is true';
4b7b0ae4 557 }
4b7b0ae4
RH
558 default {
559 die q(I don't know what to do with $foo);
560 }
561 }
562
563C<given(EXPR)> will assign the value of EXPR to C<$_>
564within the lexical scope of the block, so it's similar to
565
566 do { my $_ = EXPR; ... }
567
568except that the block is automatically broken out of by a
569successful C<when> or an explicit C<break>.
570
571Most of the power comes from implicit smart matching:
a0d0e21e 572
4b7b0ae4 573 when($foo)
a0d0e21e 574
0d863452 575is exactly equivalent to
a0d0e21e 576
4b7b0ae4 577 when($_ ~~ $foo)
a0d0e21e 578
b3ed409d
CS
579Most of the time, C<when(EXPR)> is treated as an implicit smart match of
580C<$_>, i.e. C<$_ ~~ EXPR>. (See L</"Smart matching in detail"> for more
581information on smart matching.) But when EXPR is one of the below
582exceptional cases, it is used directly as a boolean:
0d863452
RH
583
584=over 4
585
d991eed6 586=item *
0d863452
RH
587
588a subroutine or method call
589
d991eed6 590=item *
0d863452
RH
591
592a regular expression match, i.e. C</REGEX/> or C<$foo =~ /REGEX/>,
f92e1a16 593or a negated regular expression match (C<!/REGEX/> or C<$foo !~ /REGEX/>).
0d863452 594
d991eed6 595=item *
0d863452 596
4b7b0ae4
RH
597a comparison such as C<$_ E<lt> 10> or C<$x eq "abc">
598(or of course C<$_ ~~ $c>)
0d863452 599
d991eed6 600=item *
0d863452
RH
601
602C<defined(...)>, C<exists(...)>, or C<eof(...)>
603
d991eed6 604=item *
4633a7c4 605
f92e1a16 606a negated expression C<!(...)> or C<not (...)>, or a logical
0d863452 607exclusive-or C<(...) xor (...)>.
cb1a09d0 608
516817b4
RGS
609=item *
610
611a filetest operator, with the exception of C<-s>, C<-M>, C<-A>, and C<-C>,
612that return numerical values, not boolean ones.
613
202d7cbd
RGS
614=item *
615
f118ea0d 616the C<..> and C<...> flip-flop operators.
202d7cbd 617
0d863452
RH
618=back
619
f92e1a16
RGS
620In those cases the value of EXPR is used directly as a boolean.
621
0d863452
RH
622Furthermore:
623
624=over 4
625
f92e1a16 626=item *
0d863452
RH
627
628If EXPR is C<... && ...> or C<... and ...>, the test
629is applied recursively to both arguments. If I<both>
630arguments pass the test, then the argument is treated
631as boolean.
632
f92e1a16 633=item *
0d863452 634
f92e1a16 635If EXPR is C<... || ...>, C<... // ...> or C<... or ...>, the test
0d863452
RH
636is applied recursively to the first argument.
637
638=back
639
640These rules look complicated, but usually they will do what
641you want. For example you could write:
642
f849b90f 643 when (/^\d+$/ && $_ < 75) { ... }
0d863452 644
4b7b0ae4 645Another useful shortcut is that, if you use a literal array
107bd117 646or hash as the argument to C<given>, it is turned into a
4b7b0ae4
RH
647reference. So C<given(@foo)> is the same as C<given(\@foo)>,
648for example.
649
0d863452
RH
650C<default> behaves exactly like C<when(1 == 1)>, which is
651to say that it always matches.
652
4b7b0ae4
RH
653=head3 Breaking out
654
655You can use the C<break> keyword to break out of the enclosing
656C<given> block. Every C<when> block is implicitly ended with
657a C<break>.
658
0d863452
RH
659=head3 Fall-through
660
661You can use the C<continue> keyword to fall through from one
662case to the next:
663
27cec4bd 664 given($foo) {
4b7b0ae4
RH
665 when (/x/) { say '$foo contains an x'; continue }
666 when (/y/) { say '$foo contains a y' }
02e7afe2 667 default { say '$foo does not contain a y' }
27cec4bd 668 }
0d863452
RH
669
670=head3 Switching in a loop
671
672Instead of using C<given()>, you can use a C<foreach()> loop.
673For example, here's one way to count how many times a particular
674string occurs in an array:
675
27cec4bd
RGS
676 my $count = 0;
677 for (@array) {
678 when ("foo") { ++$count }
5a964f20 679 }
27cec4bd 680 print "\@array contains $count copies of 'foo'\n";
0d863452 681
54091fc3 682At the end of all C<when> blocks, there is an implicit C<next>.
0d863452
RH
683You can override that with an explicit C<last> if you're only
684interested in the first match.
685
686This doesn't work if you explicitly specify a loop variable,
687as in C<for $item (@array)>. You have to use the default
688variable C<$_>. (You can use C<for my $_ (@array)>.)
689
690=head3 Smart matching in detail
691
202d7cbd
RGS
692The behaviour of a smart match depends on what type of thing its arguments
693are. The behaviour is determined by the following table: the first row
694that applies determines the match behaviour (which is thus mostly
695determined by the type of the right operand). Note that the smart match
d0b243e3
RGS
696implicitly dereferences any non-blessed hash or array ref, so the "Hash"
697and "Array" entries apply in those cases. (For blessed references, the
c6ebb512 698"Object" entries apply.)
4b7b0ae4 699
b3ed409d
CS
700Note that the "Matching Code" column is not always an exact rendition. For
701example, the smart match operator short-circuits whenever possible, but
702C<grep> does not.
703
4b7b0ae4
RH
704 $a $b Type of Match Implied Matching Code
705 ====== ===== ===================== =============
202d7cbd
RGS
706 Any undef undefined !defined $a
707
c6ebb512 708 Any Object invokes ~~ overloading on $object, or dies
4b7b0ae4 709
168ff818
RGS
710 Hash CodeRef sub truth for each key[1] !grep { !$b->($_) } keys %$a
711 Array CodeRef sub truth for each elt[1] !grep { !$b->($_) } @$a
712 Any CodeRef scalar sub truth $b->($a)
4b7b0ae4 713
6f76d139 714 Hash Hash hash keys identical (every key is found in both hashes)
a8b2c106 715 Array Hash hash keys intersection grep { exists $b->{$_} } @$a
07edf497 716 Regex Hash hash key grep grep /$a/, keys %$b
202d7cbd
RGS
717 undef Hash always false (undef can't be a key)
718 Any Hash hash entry existence exists $b->{$a}
719
a8b2c106 720 Hash Array hash keys intersection grep { exists $a->{$_} } @$b
168ff818 721 Array Array arrays are comparable[2]
c3886e8b
RGS
722 Regex Array array grep grep /$a/, @$b
723 undef Array array contains undef grep !defined, @$b
168ff818 724 Any Array match against an array element[3]
c3886e8b 725 grep $a ~~ $_, @$b
4b7b0ae4 726
202d7cbd 727 Hash Regex hash key grep grep /$b/, keys %$a
4b7b0ae4 728 Array Regex array grep grep /$b/, @$a
4b7b0ae4 729 Any Regex pattern match $a =~ /$b/
202d7cbd 730
2c9d2554 731 Object Any invokes ~~ overloading on $object, or falls back:
4b7b0ae4 732 Any Num numeric equality $a == $b
f118ea0d 733 Num numish[4] numeric equality $a == $b
fb51372e 734 undef Any undefined !defined($b)
4b7b0ae4
RH
735 Any Any string equality $a eq $b
736
07edf497 737 1 - empty hashes or arrays will match.
329802ba
RGS
738 2 - that is, each element smart-matches the element of same index in the
739 other array. [3]
168ff818 740 3 - If a circular reference is found, we fall back to referential equality.
f118ea0d 741 4 - either a real number, or a string that looks like a number
0d863452 742
0d863452 743=head3 Custom matching via overloading
5a964f20 744
0d863452 745You can change the way that an object is matched by overloading
0de1c906 746the C<~~> operator. This may alter the usual smart match semantics.
5a964f20 747
202d7cbd
RGS
748It should be noted that C<~~> will refuse to work on objects that
749don't overload it (in order to avoid relying on the object's
2da5311b 750underlying structure).
202d7cbd 751
0de1c906
DM
752Note also that smart match's matching rules take precedence over
753overloading, so if C<$obj> has smart match overloading, then
754
755 $obj ~~ X
756
757will not automatically invoke the overload method with X as an argument;
758instead the table above is consulted as normal, and based in the type of X,
759overloading may or may not be invoked.
760
761See L<overload>.
762
54a85b95
RH
763=head3 Differences from Perl 6
764
765The Perl 5 smart match and C<given>/C<when> constructs are not
766absolutely identical to their Perl 6 analogues. The most visible
767difference is that, in Perl 5, parentheses are required around
4f8ea571
VP
768the argument to C<given()> and C<when()> (except when this last
769one is used as a statement modifier). Parentheses in Perl 6
54a85b95
RH
770are always optional in a control construct such as C<if()>,
771C<while()>, or C<when()>; they can't be made optional in Perl
7725 without a great deal of potential confusion, because Perl 5
773would parse the expression
774
775 given $foo {
776 ...
777 }
778
779as though the argument to C<given> were an element of the hash
780C<%foo>, interpreting the braces as hash-element syntax.
781
ccc668fa
RGS
782The table of smart matches is not identical to that proposed by the
783Perl 6 specification, mainly due to the differences between Perl 6's
784and Perl 5's data models.
54a85b95
RH
785
786In Perl 6, C<when()> will always do an implicit smart match
787with its argument, whilst it is convenient in Perl 5 to
788suppress this implicit smart match in certain situations,
789as documented above. (The difference is largely because Perl 5
790does not, even internally, have a boolean type.)
791
4633a7c4 792=head2 Goto
d74e8afc 793X<goto>
4633a7c4 794
19799a22
GS
795Although not for the faint of heart, Perl does support a C<goto>
796statement. There are three forms: C<goto>-LABEL, C<goto>-EXPR, and
797C<goto>-&NAME. A loop's LABEL is not actually a valid target for
798a C<goto>; it's just the name of the loop.
4633a7c4 799
f86cebdf 800The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
4633a7c4 801execution there. It may not be used to go into any construct that
f86cebdf 802requires initialization, such as a subroutine or a C<foreach> loop. It
4633a7c4
LW
803also can't be used to go into a construct that is optimized away. It
804can be used to go almost anywhere else within the dynamic scope,
805including out of subroutines, but it's usually better to use some other
f86cebdf
GS
806construct such as C<last> or C<die>. The author of Perl has never felt the
807need to use this form of C<goto> (in Perl, that is--C is another matter).
4633a7c4 808
f86cebdf
GS
809The C<goto>-EXPR form expects a label name, whose scope will be resolved
810dynamically. This allows for computed C<goto>s per FORTRAN, but isn't
4633a7c4
LW
811necessarily recommended if you're optimizing for maintainability:
812
96f2dc66 813 goto(("FOO", "BAR", "GLARCH")[$i]);
4633a7c4 814
f86cebdf 815The C<goto>-&NAME form is highly magical, and substitutes a call to the
4633a7c4 816named subroutine for the currently running subroutine. This is used by
f86cebdf 817C<AUTOLOAD()> subroutines that wish to load another subroutine and then
4633a7c4 818pretend that the other subroutine had been called in the first place
f86cebdf
GS
819(except that any modifications to C<@_> in the current subroutine are
820propagated to the other subroutine.) After the C<goto>, not even C<caller()>
4633a7c4
LW
821will be able to tell that this routine was called first.
822
c07a80fd 823In almost all cases like this, it's usually a far, far better idea to use the
824structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of
4633a7c4
LW
825resorting to a C<goto>. For certain applications, the catch and throw pair of
826C<eval{}> and die() for exception processing can also be a prudent approach.
cb1a09d0
AD
827
828=head2 PODs: Embedded Documentation
d74e8afc 829X<POD> X<documentation>
cb1a09d0
AD
830
831Perl has a mechanism for intermixing documentation with source code.
c07a80fd 832While it's expecting the beginning of a new statement, if the compiler
cb1a09d0
AD
833encounters a line that begins with an equal sign and a word, like this
834
835 =head1 Here There Be Pods!
836
837Then that text and all remaining text up through and including a line
838beginning with C<=cut> will be ignored. The format of the intervening
54310121 839text is described in L<perlpod>.
cb1a09d0
AD
840
841This allows you to intermix your source code
842and your documentation text freely, as in
843
844 =item snazzle($)
845
54310121 846 The snazzle() function will behave in the most spectacular
cb1a09d0
AD
847 form that you can possibly imagine, not even excepting
848 cybernetic pyrotechnics.
849
850 =cut back to the compiler, nuff of this pod stuff!
851
852 sub snazzle($) {
853 my $thingie = shift;
854 .........
54310121 855 }
cb1a09d0 856
54310121 857Note that pod translators should look at only paragraphs beginning
184e9718 858with a pod directive (it makes parsing easier), whereas the compiler
54310121 859actually knows to look for pod escapes even in the middle of a
cb1a09d0
AD
860paragraph. This means that the following secret stuff will be
861ignored by both the compiler and the translators.
862
863 $a=3;
864 =secret stuff
865 warn "Neither POD nor CODE!?"
866 =cut back
867 print "got $a\n";
868
f86cebdf 869You probably shouldn't rely upon the C<warn()> being podded out forever.
cb1a09d0
AD
870Not all pod translators are well-behaved in this regard, and perhaps
871the compiler will become pickier.
774d564b 872
873One may also use pod directives to quickly comment out a section
874of code.
875
876=head2 Plain Old Comments (Not!)
d74e8afc 877X<comment> X<line> X<#> X<preprocessor> X<eval>
774d564b 878
6ec4bd10 879Perl can process line directives, much like the C preprocessor. Using
5a964f20 880this, one can control Perl's idea of filenames and line numbers in
774d564b 881error or warning messages (especially for strings that are processed
f86cebdf 882with C<eval()>). The syntax for this mechanism is the same as for most
774d564b 883C preprocessors: it matches the regular expression
6ec4bd10
MS
884
885 # example: '# line 42 "new_filename.plx"'
82d4537c 886 /^\# \s*
6ec4bd10 887 line \s+ (\d+) \s*
7b6e93a8 888 (?:\s("?)([^"]+)\2)? \s*
6ec4bd10
MS
889 $/x
890
7b6e93a8
CW
891with C<$1> being the line number for the next line, and C<$3> being
892the optional filename (specified with or without quotes).
774d564b 893
003183f2
GS
894There is a fairly obvious gotcha included with the line directive:
895Debuggers and profilers will only show the last source line to appear
896at a particular line number in a given file. Care should be taken not
897to cause line number collisions in code you'd like to debug later.
898
774d564b 899Here are some examples that you should be able to type into your command
900shell:
901
902 % perl
903 # line 200 "bzzzt"
904 # the `#' on the previous line must be the first char on line
905 die 'foo';
906 __END__
907 foo at bzzzt line 201.
54310121 908
774d564b 909 % perl
910 # line 200 "bzzzt"
911 eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
912 __END__
913 foo at - line 2001.
54310121 914
774d564b 915 % perl
916 eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
917 __END__
918 foo at foo bar line 200.
54310121 919
774d564b 920 % perl
921 # line 345 "goop"
922 eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
923 print $@;
924 __END__
925 foo at goop line 345.
926
927=cut