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