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