This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Clarify use of 'continue' keyword after 'given'.
[perl5.git] / pod / perlsyn.pod
1 =head1 NAME
2 X<syntax>
3
4 perlsyn - Perl syntax
5
6 =head1 DESCRIPTION
7
8 A Perl program consists of a sequence of declarations and statements
9 which run from the top to the bottom.  Loops, subroutines, and other
10 control structures allow you to jump around within the code.
11
12 Perl is a B<free-form> language: you can format and indent it however
13 you like.  Whitespace serves mostly to separate tokens, unlike
14 languages like Python where it is an important part of the syntax,
15 or Fortran where it is immaterial.
16
17 Many of Perl's syntactic elements are B<optional>.  Rather than
18 requiring you to put parentheses around every function call and
19 declare every variable, you can often leave such explicit elements off
20 and Perl will figure out what you meant.  This is known as B<Do What I
21 Mean>, abbreviated B<DWIM>.  It allows programmers to be B<lazy> and to
22 code in a style with which they are comfortable.
23
24 Perl B<borrows syntax> and concepts from many languages: awk, sed, C,
25 Bourne Shell, Smalltalk, Lisp and even English.  Other
26 languages have borrowed syntax from Perl, particularly its regular
27 expression extensions.  So if you have programmed in another language
28 you will see familiar pieces in Perl.  They often work the same, but
29 see L<perltrap> for information about how they differ.
30
31 =head2 Declarations
32 X<declaration> X<undef> X<undefined> X<uninitialized>
33
34 The only things you need to declare in Perl are report formats and
35 subroutines (and sometimes not even subroutines).  A scalar variable holds
36 the undefined value (C<undef>) until it has been assigned a defined
37 value, which is anything other than C<undef>.  When used as a number,
38 C<undef> is treated as C<0>; when used as a string, it is treated as
39 the empty string, C<"">; and when used as a reference that isn't being
40 assigned to, it is treated as an error.  If you enable warnings,
41 you'll be notified of an uninitialized value whenever you treat
42 C<undef> as a string or a number.  Well, usually.  Boolean contexts,
43 such as:
44
45     if ($a) {}
46
47 are exempt from warnings (because they care about truth rather than
48 definedness).  Operators such as C<++>, C<-->, C<+=>,
49 C<-=>, and C<.=>, that operate on undefined variables such as:
50
51     undef $a;
52     $a++;
53
54 are also always exempt from such warnings.
55
56 A declaration can be put anywhere a statement can, but has no effect on
57 the execution of the primary sequence of statements: declarations all
58 take effect at compile time.  All declarations are typically put at
59 the beginning or the end of the script.  However, if you're using
60 lexically-scoped private variables created with C<my()>,
61 C<state()>, or C<our()>, you'll have to make sure
62 your format or subroutine definition is within the same block scope
63 as the my if you expect to be able to access those private variables.
64
65 Declaring a subroutine allows a subroutine name to be used as if it were a
66 list operator from that point forward in the program.  You can declare a
67 subroutine without defining it by saying C<sub name>, thus:
68 X<subroutine, declaration>
69
70     sub myname;
71     $me = myname $0             or die "can't get myname";
72
73 A bare declaration like that declares the function to be a list operator,
74 not a unary operator, so you have to be careful to use parentheses (or
75 C<or> instead of C<||>.)  The C<||> operator binds too tightly to use after
76 list operators; it becomes part of the last element.  You can always use
77 parentheses around the list operators arguments to turn the list operator
78 back into something that behaves more like a function call.  Alternatively,
79 you can use the prototype C<($)> to turn the subroutine into a unary
80 operator:
81
82   sub myname ($);
83   $me = myname $0             || die "can't get myname";
84
85 That now parses as you'd expect, but you still ought to get in the habit of
86 using parentheses in that situation.  For more on prototypes, see
87 L<perlsub>.
88
89 Subroutines declarations can also be loaded up with the C<require> statement
90 or both loaded and imported into your namespace with a C<use> statement.
91 See L<perlmod> for details on this.
92
93 A statement sequence may contain declarations of lexically-scoped
94 variables, but apart from declaring a variable name, the declaration acts
95 like an ordinary statement, and is elaborated within the sequence of
96 statements as if it were an ordinary statement.  That means it actually
97 has both compile-time and run-time effects.
98
99 =head2 Comments
100 X<comment> X<#>
101
102 Text from a C<"#"> character until the end of the line is a comment,
103 and is ignored.  Exceptions include C<"#"> inside a string or regular
104 expression.
105
106 =head2 Simple Statements
107 X<statement> X<semicolon> X<expression> X<;>
108
109 The only kind of simple statement is an expression evaluated for its
110 side-effects.  Every simple statement must be terminated with a
111 semicolon, unless it is the final statement in a block, in which case
112 the semicolon is optional.  But put the semicolon in anyway if the
113 block takes up more than one line, because you may eventually add
114 another line.  Note that there are operators like C<eval {}>, C<sub {}>, and
115 C<do {}> that I<look> like compound statements, but aren't--they're just
116 TERMs in an expression--and thus need an explicit termination when used
117 as the last item in a statement.
118
119 =head2 Truth and Falsehood
120 X<truth> X<falsehood> X<true> X<false> X<!> X<not> X<negation> X<0>
121
122 The number 0, the strings C<'0'> and C<"">, the empty list C<()>, and
123 C<undef> are all false in a boolean context.  All other values are true.
124 Negation of a true value by C<!> or C<not> returns a special false value.
125 When evaluated as a string it is treated as C<"">, but as a number, it
126 is treated as 0.  Most Perl operators
127 that return true or false behave this way.
128
129 =head2 Statement Modifiers
130 X<statement modifier> X<modifier> X<if> X<unless> X<while>
131 X<until> X<when> X<foreach> X<for>
132
133 Any simple statement may optionally be followed by a I<SINGLE> modifier,
134 just before the terminating semicolon (or block ending).  The possible
135 modifiers are:
136
137     if EXPR
138     unless EXPR
139     while EXPR
140     until EXPR
141     for LIST
142     foreach LIST
143     when EXPR
144
145 The C<EXPR> following the modifier is referred to as the "condition".
146 Its truth or falsehood determines how the modifier will behave.
147
148 C<if> executes the statement once I<if> and only if the condition is
149 true.  C<unless> is the opposite, it executes the statement I<unless>
150 the condition is true (that is, if the condition is false).
151
152     print "Basset hounds got long ears" if length $ear >= 10;
153     go_outside() and play() unless $is_raining;
154
155 The C<for(each)> modifier is an iterator: it executes the statement once
156 for each item in the LIST (with C<$_> aliased to each item in turn).
157
158     print "Hello $_!\n" for qw(world Dolly nurse);
159
160 C<while> repeats the statement I<while> the condition is true.
161 C<until> does the opposite, it repeats the statement I<until> the
162 condition is true (or while the condition is false):
163
164     # Both of these count from 0 to 10.
165     print $i++ while $i <= 10;
166     print $j++ until $j >  10;
167
168 The C<while> and C<until> modifiers have the usual "C<while> loop"
169 semantics (conditional evaluated first), except when applied to a
170 C<do>-BLOCK (or to the Perl4 C<do>-SUBROUTINE statement), in
171 which case the block executes once before the conditional is
172 evaluated.
173
174 This is so that you can write loops like:
175
176     do {
177         $line = <STDIN>;
178         ...
179     } until !defined($line) || $line eq ".\n"
180
181 See L<perlfunc/do>.  Note also that the loop control statements described
182 later will I<NOT> work in this construct, because modifiers don't take
183 loop labels.  Sorry.  You can always put another block inside of it
184 (for C<next>/C<redo>) or around it (for C<last>) to do that sort of thing.
185 X<next> X<last> X<redo>
186
187 For C<next> or C<redo>, just double the braces:
188
189     do {{
190         next if $x == $y;
191         # do something here
192     }} until $x++ > $z;
193
194 For C<last>, you have to be more elaborate and put braces around it:
195 X<last>
196
197     {
198         do {
199             last if $x == $y**2;
200             # do something here
201         } while $x++ <= $z;
202     }
203
204 If you need both C<next> and C<last>, you have to do both and also use a
205 loop label:
206
207     LOOP: {
208         do {{
209             next if $x == $y;
210             last LOOP if $x == $y**2;
211             # do something here
212         }} until $x++ > $z;
213     }
214
215 B<NOTE:> The behaviour of a C<my>, C<state>, or
216 C<our> modified with a statement modifier conditional
217 or loop construct (for example, C<my $x if ...>) is
218 B<undefined>.  The value of the C<my> variable may be C<undef>, any
219 previously assigned value, or possibly anything else.  Don't rely on
220 it.  Future versions of perl might do something different from the
221 version of perl you try it out on.  Here be dragons.
222 X<my>
223
224 The C<when> modifier is an experimental feature that first appeared in Perl
225 5.14.  To use it, you should include a C<use v5.14> declaration.
226 (Technically, it requires only the C<switch> feature, but that aspect of it
227 was not available before 5.14.)  Operative only from within a C<foreach>
228 loop or a C<given> block, it executes the statement only if the smartmatch
229 C<< $_ ~~ I<EXPR> >> is true.  If the statement executes, it is followed by
230 a C<next> from inside a C<foreach> and C<break> from inside a C<given>.
231
232 Under the current implementation, the C<foreach> loop can be
233 anywhere within the C<when> modifier's dynamic scope, but must be
234 within the C<given> block's lexical scope.  This restriction may
235 be relaxed in a future release.  See L</"Switch Statements"> below.
236
237 =head2 Compound Statements
238 X<statement, compound> X<block> X<bracket, curly> X<curly bracket> X<brace>
239 X<{> X<}> X<if> X<unless> X<given> X<while> X<until> X<foreach> X<for> X<continue>
240
241 In Perl, a sequence of statements that defines a scope is called a block.
242 Sometimes a block is delimited by the file containing it (in the case
243 of a required file, or the program as a whole), and sometimes a block
244 is delimited by the extent of a string (in the case of an eval).
245
246 But generally, a block is delimited by curly brackets, also known as braces.
247 We will call this syntactic construct a BLOCK.
248
249 The following compound statements may be used to control flow:
250
251     if (EXPR) BLOCK
252     if (EXPR) BLOCK else BLOCK
253     if (EXPR) BLOCK elsif (EXPR) BLOCK ...
254     if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
255
256     unless (EXPR) BLOCK
257     unless (EXPR) BLOCK else BLOCK
258     unless (EXPR) BLOCK elsif (EXPR) BLOCK ...
259     unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
260
261     given (EXPR) BLOCK
262
263     LABEL while (EXPR) BLOCK
264     LABEL while (EXPR) BLOCK continue BLOCK
265
266     LABEL until (EXPR) BLOCK
267     LABEL until (EXPR) BLOCK continue BLOCK
268
269     LABEL for (EXPR; EXPR; EXPR) BLOCK
270     LABEL for VAR (LIST) BLOCK
271     LABEL for VAR (LIST) BLOCK continue BLOCK
272
273     LABEL foreach (EXPR; EXPR; EXPR) BLOCK
274     LABEL foreach VAR (LIST) BLOCK
275     LABEL foreach VAR (LIST) BLOCK continue BLOCK
276
277     LABEL BLOCK
278     LABEL BLOCK continue BLOCK
279
280     PHASE BLOCK
281
282 The experimental C<given> statement is I<not automatically enabled>; see
283 L</"Switch Statements"> below for how to do so, and the attendant caveats.
284
285 Unlike in C and Pascal, in Perl these are all defined in terms of BLOCKs,
286 not statements.  This means that the curly brackets are I<required>--no
287 dangling statements allowed.  If you want to write conditionals without
288 curly brackets, there are several other ways to do it.  The following
289 all do the same thing:
290
291     if (!open(FOO)) { die "Can't open $FOO: $!" }
292     die "Can't open $FOO: $!" unless open(FOO);
293     open(FOO)  || die "Can't open $FOO: $!";
294     open(FOO) ? () : die "Can't open $FOO: $!";
295         # a bit exotic, that last one
296
297 The C<if> statement is straightforward.  Because BLOCKs are always
298 bounded by curly brackets, there is never any ambiguity about which
299 C<if> an C<else> goes with.  If you use C<unless> in place of C<if>,
300 the sense of the test is reversed.  Like C<if>, C<unless> can be followed
301 by C<else>.  C<unless> can even be followed by one or more C<elsif>
302 statements, though you may want to think twice before using that particular
303 language construct, as everyone reading your code will have to think at least
304 twice before they can understand what's going on.
305
306 The C<while> statement executes the block as long as the expression is
307 L<true|/"Truth and Falsehood">.
308 The C<until> statement executes the block as long as the expression is
309 false.
310 The LABEL is optional, and if present, consists of an identifier followed
311 by a colon.  The LABEL identifies the loop for the loop control
312 statements C<next>, C<last>, and C<redo>.
313 If the LABEL is omitted, the loop control statement
314 refers to the innermost enclosing loop.  This may include dynamically
315 looking back your call-stack at run time to find the LABEL.  Such
316 desperate behavior triggers a warning if you use the C<use warnings>
317 pragma or the B<-w> flag.
318
319 If there is a C<continue> BLOCK, it is always executed just before the
320 conditional is about to be evaluated again.  Thus it can be used to
321 increment a loop variable, even when the loop has been continued via
322 the C<next> statement.
323
324 When a block is preceding by a compilation phase keyword such as C<BEGIN>,
325 C<END>, C<INIT>, C<CHECK>, or C<UNITCHECK>, then the block will run only
326 during the corresponding phase of execution.  See L<perlmod> for more details.
327
328 Extension modules can also hook into the Perl parser to define new
329 kinds of compound statements.  These are introduced by a keyword which
330 the extension recognizes, and the syntax following the keyword is
331 defined entirely by the extension.  If you are an implementor, see
332 L<perlapi/PL_keyword_plugin> for the mechanism.  If you are using such
333 a module, see the module's documentation for details of the syntax that
334 it defines.
335
336 =head2 Loop Control
337 X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue>
338
339 The C<next> command starts the next iteration of the loop:
340
341     LINE: while (<STDIN>) {
342         next LINE if /^#/;      # discard comments
343         ...
344     }
345
346 The C<last> command immediately exits the loop in question.  The
347 C<continue> block, if any, is not executed:
348
349     LINE: while (<STDIN>) {
350         last LINE if /^$/;      # exit when done with header
351         ...
352     }
353
354 The C<redo> command restarts the loop block without evaluating the
355 conditional again.  The C<continue> block, if any, is I<not> executed.
356 This command is normally used by programs that want to lie to themselves
357 about what was just input.
358
359 For example, when processing a file like F</etc/termcap>.
360 If your input lines might end in backslashes to indicate continuation, you
361 want to skip ahead and get the next record.
362
363     while (<>) {
364         chomp;
365         if (s/\\$//) {
366             $_ .= <>;
367             redo unless eof();
368         }
369         # now process $_
370     }
371
372 which is Perl shorthand for the more explicitly written version:
373
374     LINE: while (defined($line = <ARGV>)) {
375         chomp($line);
376         if ($line =~ s/\\$//) {
377             $line .= <ARGV>;
378             redo LINE unless eof(); # not eof(ARGV)!
379         }
380         # now process $line
381     }
382
383 Note that if there were a C<continue> block on the above code, it would
384 get executed only on lines discarded by the regex (since redo skips the
385 continue block).  A continue block is often used to reset line counters
386 or C<m?pat?> one-time matches:
387
388     # inspired by :1,$g/fred/s//WILMA/
389     while (<>) {
390         m?(fred)?    && s//WILMA $1 WILMA/;
391         m?(barney)?  && s//BETTY $1 BETTY/;
392         m?(homer)?   && s//MARGE $1 MARGE/;
393     } continue {
394         print "$ARGV $.: $_";
395         close ARGV  if eof;             # reset $.
396         reset       if eof;             # reset ?pat?
397     }
398
399 If the word C<while> is replaced by the word C<until>, the sense of the
400 test is reversed, but the conditional is still tested before the first
401 iteration.
402
403 Loop control statements don't work in an C<if> or C<unless>, since
404 they aren't loops.  You can double the braces to make them such, though.
405
406     if (/pattern/) {{
407         last if /fred/;
408         next if /barney/; # same effect as "last",
409                           # but doesn't document as well
410         # do something here
411     }}
412
413 This is caused by the fact that a block by itself acts as a loop that
414 executes once, see L</"Basic BLOCKs">.
415
416 The form C<while/if BLOCK BLOCK>, available in Perl 4, is no longer
417 available.   Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>.
418
419 =head2 For Loops
420 X<for> X<foreach>
421
422 Perl's C-style C<for> loop works like the corresponding C<while> loop;
423 that means that this:
424
425     for ($i = 1; $i < 10; $i++) {
426         ...
427     }
428
429 is the same as this:
430
431     $i = 1;
432     while ($i < 10) {
433         ...
434     } continue {
435         $i++;
436     }
437
438 There is one minor difference: if variables are declared with C<my>
439 in the initialization section of the C<for>, the lexical scope of
440 those variables is exactly the C<for> loop (the body of the loop
441 and the control sections).
442 X<my>
443
444 As a special case, if the test in the C<for> loop (or the corresponding
445 C<while> loop) is empty, it is treated as true.  That is, both
446
447     for (;;) {
448         ...
449     }
450
451 and
452
453     while () {
454         ...
455     }
456
457 are treated as infinite loops.
458
459 Besides the normal array index looping, C<for> can lend itself
460 to many other interesting applications.  Here's one that avoids the
461 problem you get into if you explicitly test for end-of-file on
462 an interactive file descriptor causing your program to appear to
463 hang.
464 X<eof> X<end-of-file> X<end of file>
465
466     $on_a_tty = -t STDIN && -t STDOUT;
467     sub prompt { print "yes? " if $on_a_tty }
468     for ( prompt(); <STDIN>; prompt() ) {
469         # do something
470     }
471
472 Using C<readline> (or the operator form, C<< <EXPR> >>) as the
473 conditional of a C<for> loop is shorthand for the following.  This
474 behaviour is the same as a C<while> loop conditional.
475 X<readline> X<< <> >>
476
477     for ( prompt(); defined( $_ = <STDIN> ); prompt() ) {
478         # do something
479     }
480
481 =head2 Foreach Loops
482 X<for> X<foreach>
483
484 The C<foreach> loop iterates over a normal list value and sets the scalar
485 variable VAR to be each element of the list in turn.  If the variable
486 is preceded with the keyword C<my>, then it is lexically scoped, and
487 is therefore visible only within the loop.  Otherwise, the variable is
488 implicitly local to the loop and regains its former value upon exiting
489 the loop.  If the variable was previously declared with C<my>, it uses
490 that variable instead of the global one, but it's still localized to
491 the loop.  This implicit localization occurs I<only> in a C<foreach>
492 loop.
493 X<my> X<local>
494
495 The C<foreach> keyword is actually a synonym for the C<for> keyword, so
496 you can use either.  If VAR is omitted, C<$_> is set to each value.
497 X<$_>
498
499 If any element of LIST is an lvalue, you can modify it by modifying
500 VAR inside the loop.  Conversely, if any element of LIST is NOT an
501 lvalue, any attempt to modify that element will fail.  In other words,
502 the C<foreach> loop index variable is an implicit alias for each item
503 in the list that you're looping over.
504 X<alias>
505
506 If any part of LIST is an array, C<foreach> will get very confused if
507 you add or remove elements within the loop body, for example with
508 C<splice>.   So don't do that.
509 X<splice>
510
511 C<foreach> probably won't do what you expect if VAR is a tied or other
512 special variable.   Don't do that either.
513
514 As of Perl 5.22, there is an experimental variant of this loop that accepts
515 a variable preceded by a backslash for VAR, in which case the items in the
516 LIST must be references.  The backslashed variable will become an alias
517 to each referenced item in the LIST, which must be of the correct type.
518 The variable needn't be a scalar in this case, and the backslash may be
519 followed by C<my>.  To use this form, you must enable the C<refaliasing>
520 feature via C<use feature>.  (See L<feature>.  See also L<perlref/Assigning
521 to References>.)
522
523 Examples:
524
525     for (@ary) { s/foo/bar/ }
526
527     for my $elem (@elements) {
528         $elem *= 2;
529     }
530
531     for $count (reverse(1..10), "BOOM") {
532         print $count, "\n";
533         sleep(1);
534     }
535
536     for (1..15) { print "Merry Christmas\n"; }
537
538     foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
539         print "Item: $item\n";
540     }
541
542     use feature "refaliasing";
543     no warnings "experimental::refaliasing";
544     foreach \my %hash (@array_of_hash_references) {
545         # do something which each %hash
546     }
547
548 Here's how a C programmer might code up a particular algorithm in Perl:
549
550     for (my $i = 0; $i < @ary1; $i++) {
551         for (my $j = 0; $j < @ary2; $j++) {
552             if ($ary1[$i] > $ary2[$j]) {
553                 last; # can't go to outer :-(
554             }
555             $ary1[$i] += $ary2[$j];
556         }
557         # this is where that last takes me
558     }
559
560 Whereas here's how a Perl programmer more comfortable with the idiom might
561 do it:
562
563     OUTER: for my $wid (@ary1) {
564     INNER:   for my $jet (@ary2) {
565                 next OUTER if $wid > $jet;
566                 $wid += $jet;
567              }
568           }
569
570 See how much easier this is?  It's cleaner, safer, and faster.  It's
571 cleaner because it's less noisy.  It's safer because if code gets added
572 between the inner and outer loops later on, the new code won't be
573 accidentally executed.  The C<next> explicitly iterates the other loop
574 rather than merely terminating the inner one.  And it's faster because
575 Perl executes a C<foreach> statement more rapidly than it would the
576 equivalent C<for> loop.
577
578 Perceptive Perl hackers may have noticed that a C<for> loop has a return
579 value, and that this value can be captured by wrapping the loop in a C<do>
580 block.  The reward for this discovery is this cautionary advice:  The
581 return value of a C<for> loop is unspecified and may change without notice.
582 Do not rely on it.
583
584 =head2 Basic BLOCKs
585 X<block>
586
587 A BLOCK by itself (labeled or not) is semantically equivalent to a
588 loop that executes once.  Thus you can use any of the loop control
589 statements in it to leave or restart the block.  (Note that this is
590 I<NOT> true in C<eval{}>, C<sub{}>, or contrary to popular belief
591 C<do{}> blocks, which do I<NOT> count as loops.)  The C<continue>
592 block is optional.
593
594 The BLOCK construct can be used to emulate case structures.
595
596     SWITCH: {
597         if (/^abc/) { $abc = 1; last SWITCH; }
598         if (/^def/) { $def = 1; last SWITCH; }
599         if (/^xyz/) { $xyz = 1; last SWITCH; }
600         $nothing = 1;
601     }
602
603 You'll also find that C<foreach> loop used to create a topicalizer
604 and a switch:
605
606     SWITCH:
607     for ($var) {
608         if (/^abc/) { $abc = 1; last SWITCH; }
609         if (/^def/) { $def = 1; last SWITCH; }
610         if (/^xyz/) { $xyz = 1; last SWITCH; }
611         $nothing = 1;
612     }
613
614 Such constructs are quite frequently used, both because older versions of
615 Perl had no official C<switch> statement, and also because the new version
616 described immediately below remains experimental and can sometimes be confusing.
617
618 =head2 Switch Statements
619
620 X<switch> X<case> X<given> X<when> X<default>
621
622 Starting from Perl 5.10.1 (well, 5.10.0, but it didn't work
623 right), you can say
624
625     use feature "switch";
626
627 to enable an experimental switch feature.  This is loosely based on an
628 old version of a Perl 6 proposal, but it no longer resembles the Perl 6
629 construct.   You also get the switch feature whenever you declare that your
630 code prefers to run under a version of Perl that is 5.10 or later.  For
631 example:
632
633     use v5.14;
634
635 Under the "switch" feature, Perl gains the experimental keywords
636 C<given>, C<when>, C<default>, C<continue>, and C<break>.
637 Starting from Perl 5.16, one can prefix the switch
638 keywords with C<CORE::> to access the feature without a C<use feature>
639 statement.  The keywords C<given> and
640 C<when> are analogous to C<switch> and
641 C<case> in other languages -- though C<continue> is not -- so the code
642 in the previous section could be rewritten as
643
644     use v5.10.1;
645     for ($var) {
646         when (/^abc/) { $abc = 1 }
647         when (/^def/) { $def = 1 }
648         when (/^xyz/) { $xyz = 1 }
649         default       { $nothing = 1 }
650     }
651
652 The C<foreach> is the non-experimental way to set a topicalizer.
653 If you wish to use the highly experimental C<given>, that could be
654 written like this:
655
656     use v5.10.1;
657     given ($var) {
658         when (/^abc/) { $abc = 1 }
659         when (/^def/) { $def = 1 }
660         when (/^xyz/) { $xyz = 1 }
661         default       { $nothing = 1 }
662     }
663
664 As of 5.14, that can also be written this way:
665
666     use v5.14;
667     for ($var) {
668         $abc = 1 when /^abc/;
669         $def = 1 when /^def/;
670         $xyz = 1 when /^xyz/;
671         default { $nothing = 1 }
672     }
673
674 Or if you don't care to play it safe, like this:
675
676     use v5.14;
677     given ($var) {
678         $abc = 1 when /^abc/;
679         $def = 1 when /^def/;
680         $xyz = 1 when /^xyz/;
681         default { $nothing = 1 }
682     }
683
684 The arguments to C<given> and C<when> are in scalar context,
685 and C<given> assigns the C<$_> variable its topic value.
686
687 Exactly what the I<EXPR> argument to C<when> does is hard to describe
688 precisely, but in general, it tries to guess what you want done.  Sometimes
689 it is interpreted as C<< $_ ~~ I<EXPR> >>, and sometimes it is not.  It
690 also behaves differently when lexically enclosed by a C<given> block than
691 it does when dynamically enclosed by a C<foreach> loop.  The rules are far
692 too difficult to understand to be described here.  See L</"Experimental Details
693 on given and when"> later on.
694
695 Due to an unfortunate bug in how C<given> was implemented between Perl 5.10
696 and 5.16, under those implementations the version of C<$_> governed by
697 C<given> is merely a lexically scoped copy of the original, not a
698 dynamically scoped alias to the original, as it would be if it were a
699 C<foreach> or under both the original and the current Perl 6 language
700 specification.  This bug was fixed in Perl 5.18 (and lexicalized C<$_> itself
701 was removed in Perl 5.24).
702
703 If your code still needs to run on older versions,
704 stick to C<foreach> for your topicalizer and
705 you will be less unhappy.
706
707 =head2 Goto
708 X<goto>
709
710 Although not for the faint of heart, Perl does support a C<goto>
711 statement.  There are three forms: C<goto>-LABEL, C<goto>-EXPR, and
712 C<goto>-&NAME.  A loop's LABEL is not actually a valid target for
713 a C<goto>; it's just the name of the loop.
714
715 The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
716 execution there.  It may not be used to go into any construct that
717 requires initialization, such as a subroutine or a C<foreach> loop.  It
718 also can't be used to go into a construct that is optimized away.  It
719 can be used to go almost anywhere else within the dynamic scope,
720 including out of subroutines, but it's usually better to use some other
721 construct such as C<last> or C<die>.  The author of Perl has never felt the
722 need to use this form of C<goto> (in Perl, that is--C is another matter).
723
724 The C<goto>-EXPR form expects a label name, whose scope will be resolved
725 dynamically.  This allows for computed C<goto>s per FORTRAN, but isn't
726 necessarily recommended if you're optimizing for maintainability:
727
728     goto(("FOO", "BAR", "GLARCH")[$i]);
729
730 The C<goto>-&NAME form is highly magical, and substitutes a call to the
731 named subroutine for the currently running subroutine.  This is used by
732 C<AUTOLOAD()> subroutines that wish to load another subroutine and then
733 pretend that the other subroutine had been called in the first place
734 (except that any modifications to C<@_> in the current subroutine are
735 propagated to the other subroutine.)  After the C<goto>, not even C<caller()>
736 will be able to tell that this routine was called first.
737
738 In almost all cases like this, it's usually a far, far better idea to use the
739 structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of
740 resorting to a C<goto>.  For certain applications, the catch and throw pair of
741 C<eval{}> and die() for exception processing can also be a prudent approach.
742
743 =head2 The Ellipsis Statement
744 X<...>
745 X<... statement>
746 X<ellipsis operator>
747 X<elliptical statement>
748 X<unimplemented statement>
749 X<unimplemented operator>
750 X<yada-yada>
751 X<yada-yada operator>
752 X<... operator>
753 X<whatever operator>
754 X<triple-dot operator>
755
756 Beginning in Perl 5.12, Perl accepts an ellipsis, "C<...>", as a
757 placeholder for code that you haven't implemented yet.  This form of
758 ellipsis, the unimplemented statement, should not be confused with the
759 binary flip-flop C<...> operator.  One is a statement and the other an
760 operator.  (Perl doesn't usually confuse them because usually Perl can tell
761 whether it wants an operator or a statement, but see below for exceptions.)
762
763 When Perl 5.12 or later encounters an ellipsis statement, it parses this
764 without error, but if and when you should actually try to execute it, Perl
765 throws an exception with the text C<Unimplemented>:
766
767     use v5.12;
768     sub unimplemented { ... }
769     eval { unimplemented() };
770     if ($@ =~ /^Unimplemented at /) {
771         say "I found an ellipsis!";
772     }
773
774 You can only use the elliptical statement to stand in for a
775 complete statement.  These examples of how the ellipsis works:
776
777     use v5.12;
778     { ... }
779     sub foo { ... }
780     ...;
781     eval { ... };
782     sub somemeth {
783         my $self = shift;
784         ...;
785     }
786     $x = do {
787         my $n;
788         ...;
789         say "Hurrah!";
790         $n;
791     };
792
793 The elliptical statement cannot stand in for an expression that
794 is part of a larger statement, since the C<...> is also the three-dot
795 version of the flip-flop operator (see L<perlop/"Range Operators">).
796
797 These examples of attempts to use an ellipsis are syntax errors:
798
799     use v5.12;
800
801     print ...;
802     open(my $fh, ">", "/dev/passwd") or ...;
803     if ($condition && ... ) { say "Howdy" };
804
805 There are some cases where Perl can't immediately tell the difference
806 between an expression and a statement.  For instance, the syntax for a
807 block and an anonymous hash reference constructor look the same unless
808 there's something in the braces to give Perl a hint.  The ellipsis is a
809 syntax error if Perl doesn't guess that the C<{ ... }> is a block.  In that
810 case, it doesn't think the C<...> is an ellipsis because it's expecting an
811 expression instead of a statement:
812
813     @transformed = map { ... } @input;    # syntax error
814
815 Inside your block, you can use a C<;> before the ellipsis to denote that the
816 C<{ ... }> is a block and not a hash reference constructor.  Now the ellipsis
817 works:
818
819     @transformed = map {; ... } @input;   # ';' disambiguates
820
821 Note: Some folks colloquially refer to this bit of punctuation as a
822 "yada-yada" or "triple-dot", but its true name
823 is actually an ellipsis.
824
825 =head2 PODs: Embedded Documentation
826 X<POD> X<documentation>
827
828 Perl has a mechanism for intermixing documentation with source code.
829 While it's expecting the beginning of a new statement, if the compiler
830 encounters a line that begins with an equal sign and a word, like this
831
832     =head1 Here There Be Pods!
833
834 Then that text and all remaining text up through and including a line
835 beginning with C<=cut> will be ignored.  The format of the intervening
836 text is described in L<perlpod>.
837
838 This allows you to intermix your source code
839 and your documentation text freely, as in
840
841     =item snazzle($)
842
843     The snazzle() function will behave in the most spectacular
844     form that you can possibly imagine, not even excepting
845     cybernetic pyrotechnics.
846
847     =cut back to the compiler, nuff of this pod stuff!
848
849     sub snazzle($) {
850         my $thingie = shift;
851         .........
852     }
853
854 Note that pod translators should look at only paragraphs beginning
855 with a pod directive (it makes parsing easier), whereas the compiler
856 actually knows to look for pod escapes even in the middle of a
857 paragraph.  This means that the following secret stuff will be
858 ignored by both the compiler and the translators.
859
860     $a=3;
861     =secret stuff
862      warn "Neither POD nor CODE!?"
863     =cut back
864     print "got $a\n";
865
866 You probably shouldn't rely upon the C<warn()> being podded out forever.
867 Not all pod translators are well-behaved in this regard, and perhaps
868 the compiler will become pickier.
869
870 One may also use pod directives to quickly comment out a section
871 of code.
872
873 =head2 Plain Old Comments (Not!)
874 X<comment> X<line> X<#> X<preprocessor> X<eval>
875
876 Perl can process line directives, much like the C preprocessor.  Using
877 this, one can control Perl's idea of filenames and line numbers in
878 error or warning messages (especially for strings that are processed
879 with C<eval()>).  The syntax for this mechanism is almost the same as for
880 most C preprocessors: it matches the regular expression
881
882     # example: '# line 42 "new_filename.plx"'
883     /^\#   \s*
884       line \s+ (\d+)   \s*
885       (?:\s("?)([^"]+)\g2)? \s*
886      $/x
887
888 with C<$1> being the line number for the next line, and C<$3> being
889 the optional filename (specified with or without quotes).  Note that
890 no whitespace may precede the C<< # >>, unlike modern C preprocessors.
891
892 There is a fairly obvious gotcha included with the line directive:
893 Debuggers and profilers will only show the last source line to appear
894 at a particular line number in a given file.  Care should be taken not
895 to cause line number collisions in code you'd like to debug later.
896
897 Here are some examples that you should be able to type into your command
898 shell:
899
900     % perl
901     # line 200 "bzzzt"
902     # the '#' on the previous line must be the first char on line
903     die 'foo';
904     __END__
905     foo at bzzzt line 201.
906
907     % perl
908     # line 200 "bzzzt"
909     eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
910     __END__
911     foo at - line 2001.
912
913     % perl
914     eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
915     __END__
916     foo at foo bar line 200.
917
918     % perl
919     # line 345 "goop"
920     eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
921     print $@;
922     __END__
923     foo at goop line 345.
924
925 =head2 Experimental Details on given and when
926
927 As previously mentioned, the "switch" feature is considered highly
928 experimental; it is subject to change with little notice.  In particular,
929 C<when> has tricky behaviours that are expected to change to become less
930 tricky in the future.  Do not rely upon its current (mis)implementation.
931 Before Perl 5.18, C<given> also had tricky behaviours that you should still
932 beware of if your code must run on older versions of Perl.
933
934 Here is a longer example of C<given>:
935
936     use feature ":5.10";
937     given ($foo) {
938         when (undef) {
939             say '$foo is undefined';
940         }
941         when ("foo") {
942             say '$foo is the string "foo"';
943         }
944         when ([1,3,5,7,9]) {
945             say '$foo is an odd digit';
946             continue; # Fall through
947         }
948         when ($_ < 100) {
949             say '$foo is numerically less than 100';
950         }
951         when (\&complicated_check) {
952             say 'a complicated check for $foo is true';
953         }
954         default {
955             die q(I don't know what to do with $foo);
956         }
957     }
958
959 Before Perl 5.18, C<given(EXPR)> assigned the value of I<EXPR> to
960 merely a lexically scoped I<B<copy>> (!) of C<$_>, not a dynamically
961 scoped alias the way C<foreach> does.  That made it similar to
962
963         do { my $_ = EXPR; ... }
964
965 except that the block was automatically broken out of by a successful
966 C<when> or an explicit C<break>.  Because it was only a copy, and because
967 it was only lexically scoped, not dynamically scoped, you could not do the
968 things with it that you are used to in a C<foreach> loop.  In particular,
969 it did not work for arbitrary function calls if those functions might try
970 to access $_.  Best stick to C<foreach> for that.
971
972 Most of the power comes from the implicit smartmatching that can
973 sometimes apply.  Most of the time, C<when(EXPR)> is treated as an
974 implicit smartmatch of C<$_>, that is, C<$_ ~~ EXPR>.  (See
975 L<perlop/"Smartmatch Operator"> for more information on smartmatching.)
976 But when I<EXPR> is one of the 10 exceptional cases (or things like them)
977 listed below, it is used directly as a boolean.
978
979 =over 4
980
981 =item Z<>1.
982
983 A user-defined subroutine call or a method invocation.
984
985 =item Z<>2.
986
987 A regular expression match in the form of C</REGEX/>, C<$foo =~ /REGEX/>,
988 or C<$foo =~ EXPR>.  Also, a negated regular expression match in
989 the form C<!/REGEX/>, C<$foo !~ /REGEX/>, or C<$foo !~ EXPR>.
990
991 =item Z<>3.
992
993 A smart match that uses an explicit C<~~> operator, such as C<EXPR ~~ EXPR>.
994
995 B<NOTE:> You will often have to use C<$c ~~ $_> because the default case
996 uses C<$_ ~~ $c> , which is frequentlythe opposite of what you want.
997
998 =item Z<>4.
999
1000 A boolean comparison operator such as C<$_ E<lt> 10> or C<$x eq "abc">.  The
1001 relational operators that this applies to are the six numeric comparisons
1002 (C<< < >>, C<< > >>, C<< <= >>, C<< >= >>, C<< == >>, and C<< != >>), and
1003 the six string comparisons (C<lt>, C<gt>, C<le>, C<ge>, C<eq>, and C<ne>).
1004
1005 =item Z<>5.
1006
1007 At least the three builtin functions C<defined(...)>, C<exists(...)>, and
1008 C<eof(...)>.  We might someday add more of these later if we think of them.
1009
1010 =item Z<>6.
1011
1012 A negated expression, whether C<!(EXPR)> or C<not(EXPR)>, or a logical
1013 exclusive-or, C<(EXPR1) xor (EXPR2)>.  The bitwise versions (C<~> and C<^>)
1014 are not included.
1015
1016 =item Z<>7.
1017
1018 A filetest operator, with exactly 4 exceptions: C<-s>, C<-M>, C<-A>, and
1019 C<-C>, as these return numerical values, not boolean ones.  The C<-z>
1020 filetest operator is not included in the exception list.
1021
1022 =item Z<>8.
1023
1024 The C<..> and C<...> flip-flop operators.  Note that the C<...> flip-flop
1025 operator is completely different from the C<...> elliptical statement
1026 just described.
1027
1028 =back
1029
1030 In those 8 cases above, the value of EXPR is used directly as a boolean, so
1031 no smartmatching is done.  You may think of C<when> as a smartsmartmatch.
1032
1033 Furthermore, Perl inspects the operands of logical operators to
1034 decide whether to use smartmatching for each one by applying the
1035 above test to the operands:
1036
1037 =over 4
1038
1039 =item Z<>9.
1040
1041 If EXPR is C<EXPR1 && EXPR2> or C<EXPR1 and EXPR2>, the test is applied
1042 I<recursively> to both EXPR1 and EXPR2.
1043 Only if I<both> operands also pass the
1044 test, I<recursively>, will the expression be treated as boolean.  Otherwise,
1045 smartmatching is used.
1046
1047 =item Z<>10.
1048
1049 If EXPR is C<EXPR1 || EXPR2>, C<EXPR1 // EXPR2>, or C<EXPR1 or EXPR2>, the
1050 test is applied I<recursively> to EXPR1 only (which might itself be a
1051 higher-precedence AND operator, for example, and thus subject to the
1052 previous rule), not to EXPR2.  If EXPR1 is to use smartmatching, then EXPR2
1053 also does so, no matter what EXPR2 contains.  But if EXPR2 does not get to
1054 use smartmatching, then the second argument will not be either.  This is
1055 quite different from the C<&&> case just described, so be careful.
1056
1057 =back
1058
1059 These rules are complicated, but the goal is for them to do what you want
1060 (even if you don't quite understand why they are doing it).  For example:
1061
1062     when (/^\d+$/ && $_ < 75) { ... }
1063
1064 will be treated as a boolean match because the rules say both
1065 a regex match and an explicit test on C<$_> will be treated
1066 as boolean.
1067
1068 Also:
1069
1070     when ([qw(foo bar)] && /baz/) { ... }
1071
1072 will use smartmatching because only I<one> of the operands is a boolean:
1073 the other uses smartmatching, and that wins.
1074
1075 Further:
1076
1077     when ([qw(foo bar)] || /^baz/) { ... }
1078
1079 will use smart matching (only the first operand is considered), whereas
1080
1081     when (/^baz/ || [qw(foo bar)]) { ... }
1082
1083 will test only the regex, which causes both operands to be
1084 treated as boolean.  Watch out for this one, then, because an
1085 arrayref is always a true value, which makes it effectively
1086 redundant.  Not a good idea.
1087
1088 Tautologous boolean operators are still going to be optimized
1089 away.  Don't be tempted to write
1090
1091     when ("foo" or "bar") { ... }
1092
1093 This will optimize down to C<"foo">, so C<"bar"> will never be considered (even
1094 though the rules say to use a smartmatch
1095 on C<"foo">).  For an alternation like
1096 this, an array ref will work, because this will instigate smartmatching:
1097
1098     when ([qw(foo bar)] { ... }
1099
1100 This is somewhat equivalent to the C-style switch statement's fallthrough
1101 functionality (not to be confused with I<Perl's> fallthrough
1102 functionality--see below), wherein the same block is used for several
1103 C<case> statements.
1104
1105 Another useful shortcut is that, if you use a literal array or hash as the
1106 argument to C<given>, it is turned into a reference.  So C<given(@foo)> is
1107 the same as C<given(\@foo)>, for example.
1108
1109 C<default> behaves exactly like C<when(1 == 1)>, which is
1110 to say that it always matches.
1111
1112 =head3 Breaking out
1113
1114 You can use the C<break> keyword to break out of the enclosing
1115 C<given> block.  Every C<when> block is implicitly ended with
1116 a C<break>.
1117
1118 =head3 Fall-through
1119
1120 You can use the C<continue> keyword to fall through from one
1121 case to the next immediate C<when> or C<default>:
1122
1123     given($foo) {
1124         when (/x/) { say '$foo contains an x'; continue }
1125         when (/y/) { say '$foo contains a y'            }
1126         default    { say '$foo does not contain a y'    }
1127     }
1128
1129 =head3 Return value
1130
1131 When a C<given> statement is also a valid expression (for example,
1132 when it's the last statement of a block), it evaluates to:
1133
1134 =over 4
1135
1136 =item *
1137
1138 An empty list as soon as an explicit C<break> is encountered.
1139
1140 =item *
1141
1142 The value of the last evaluated expression of the successful
1143 C<when>/C<default> clause, if there happens to be one.
1144
1145 =item *
1146
1147 The value of the last evaluated expression of the C<given> block if no
1148 condition is true.
1149
1150 =back
1151
1152 In both last cases, the last expression is evaluated in the context that
1153 was applied to the C<given> block.
1154
1155 Note that, unlike C<if> and C<unless>, failed C<when> statements always
1156 evaluate to an empty list.
1157
1158     my $price = do {
1159         given ($item) {
1160             when (["pear", "apple"]) { 1 }
1161             break when "vote";      # My vote cannot be bought
1162             1e10  when /Mona Lisa/;
1163             "unknown";
1164         }
1165     };
1166
1167 Currently, C<given> blocks can't always
1168 be used as proper expressions.  This
1169 may be addressed in a future version of Perl.
1170
1171 =head3 Switching in a loop
1172
1173 Instead of using C<given()>, you can use a C<foreach()> loop.
1174 For example, here's one way to count how many times a particular
1175 string occurs in an array:
1176
1177     use v5.10.1;
1178     my $count = 0;
1179     for (@array) {
1180         when ("foo") { ++$count }
1181     }
1182     print "\@array contains $count copies of 'foo'\n";
1183
1184 Or in a more recent version:
1185
1186     use v5.14;
1187     my $count = 0;
1188     for (@array) {
1189         ++$count when "foo";
1190     }
1191     print "\@array contains $count copies of 'foo'\n";
1192
1193 At the end of all C<when> blocks, there is an implicit C<next>.
1194 You can override that with an explicit C<last> if you're
1195 interested in only the first match alone.
1196
1197 This doesn't work if you explicitly specify a loop variable, as
1198 in C<for $item (@array)>.  You have to use the default variable C<$_>.
1199
1200 =head3 Differences from Perl 6
1201
1202 The Perl 5 smartmatch and C<given>/C<when> constructs are not compatible
1203 with their Perl 6 analogues.  The most visible difference and least
1204 important difference is that, in Perl 5, parentheses are required around
1205 the argument to C<given()> and C<when()> (except when this last one is used
1206 as a statement modifier).  Parentheses in Perl 6 are always optional in a
1207 control construct such as C<if()>, C<while()>, or C<when()>; they can't be
1208 made optional in Perl 5 without a great deal of potential confusion,
1209 because Perl 5 would parse the expression
1210
1211     given $foo {
1212         ...
1213     }
1214
1215 as though the argument to C<given> were an element of the hash
1216 C<%foo>, interpreting the braces as hash-element syntax.
1217
1218 However, their are many, many other differences.  For example,
1219 this works in Perl 5:
1220
1221     use v5.12;
1222     my @primary = ("red", "blue", "green");
1223
1224     if (@primary ~~ "red") {
1225         say "primary smartmatches red";
1226     }
1227
1228     if ("red" ~~ @primary) {
1229         say "red smartmatches primary";
1230     }
1231
1232     say "that's all, folks!";
1233
1234 But it doesn't work at all in Perl 6.  Instead, you should
1235 use the (parallelizable) C<any> operator:
1236
1237    if any(@primary) eq "red" {
1238        say "primary smartmatches red";
1239    }
1240
1241    if "red" eq any(@primary) {
1242        say "red smartmatches primary";
1243    }
1244
1245 The table of smartmatches in L<perlop/"Smartmatch Operator"> is not
1246 identical to that proposed by the Perl 6 specification, mainly due to
1247 differences between Perl 6's and Perl 5's data models, but also because
1248 the Perl 6 spec has changed since Perl 5 rushed into early adoption.
1249
1250 In Perl 6, C<when()> will always do an implicit smartmatch with its
1251 argument, while in Perl 5 it is convenient (albeit potentially confusing) to
1252 suppress this implicit smartmatch in various rather loosely-defined
1253 situations, as roughly outlined above.  (The difference is largely because
1254 Perl 5 does not have, even internally, a boolean type.)
1255
1256 =cut