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