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