1PERLSYN(1)             Perl Programmers Reference Guide             PERLSYN(1)
2
3
4

NAME

6       perlsyn - Perl syntax
7

DESCRIPTION

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