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