1PERLSYN(1) Perl Programmers Reference Guide PERLSYN(1)
2
6 perlsyn - Perl syntax
7
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 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 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 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 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 if ($a) {}
44 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 undef $a;
50 $a++;
51 are also always exempt from such warnings.
53 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 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 sub myname;
68 $me = myname $0 or die "can't get myname";
69 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 sub myname ($);
80 $me = myname $0 || die "can't get myname";
81 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 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 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 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 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 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 if EXPR
118 unless EXPR
119 while EXPR
120 until EXPR
121 for LIST
122 foreach LIST
123 when EXPR
124 The "EXPR" following the modifier is referred to as the "condition".
126 Its truth or falsehood determines how the modifier will behave.
127 "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 print "Basset hounds got long ears" if length $ear >= 10;
133 go_outside() and play() unless $is_raining;
134 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 print "Hello $_!\n" for qw(world Dolly nurse);
139 "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 # Both of these count from 0 to 10.
147 print $i++ while $i <= 10;
148 print $j++ until $j > 10;
149 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 This is so that you can write loops like:
156 do {
158 $line = <STDIN>;
159 ...
160 } until !defined($line) || $line eq ".\n"
161 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 For "next" or "redo", just double the braces:
169 do {{
171 next if $x == $y;
172 # do something here
173 }} until $x++ > $z;
174 For "last", you have to be more elaborate and put braces around it:
176 {
178 do {
179 last if $x == $y**2;
180 # do something here
181 } while $x++ <= $z;
182 }
183 If you need both "next" and "last", you have to do both and also use a
185 loop label:
186 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 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 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 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 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 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 The following compound statements may be used to control flow:
236 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 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 given (EXPR) BLOCK
248 LABEL while (EXPR) BLOCK
250 LABEL while (EXPR) BLOCK continue BLOCK
251 LABEL until (EXPR) BLOCK
253 LABEL until (EXPR) BLOCK continue BLOCK
254 LABEL for (EXPR; EXPR; EXPR) BLOCK
256 LABEL for VAR (LIST) BLOCK
257 LABEL for VAR (LIST) BLOCK continue BLOCK
258 LABEL foreach (EXPR; EXPR; EXPR) BLOCK
260 LABEL foreach VAR (LIST) BLOCK
261 LABEL foreach VAR (LIST) BLOCK continue BLOCK
262 LABEL BLOCK
264 LABEL BLOCK continue BLOCK
265 PHASE BLOCK
267 The experimental "given" statement is not automatically enabled; see
269 "Switch Statements" below for how to do so, and the attendant caveats.
270 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 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 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 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 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 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 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 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 Loop Control
332 The "next" command starts the next iteration of the loop:
333 LINE: while (<STDIN>) {
335 next LINE if /^#/; # discard comments
336 ...
337 }
338 The "last" command immediately exits the loop in question. The
340 "continue" block, if any, is not executed:
341 LINE: while (<STDIN>) {
343 last LINE if /^$/; # exit when done with header
344 ...
345 }
346 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 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 while (<>) {
357 chomp;
358 if (s/\\$//) {
359 $_ .= <>;
360 redo unless eof();
361 }
362 # now process $_
363 }
364 which is Perl shorthand for the more explicitly written version:
366 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 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 # 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 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 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 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 This is caused by the fact that a block by itself acts as a loop that
407 executes once, see "Basic BLOCKs".
408 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 For Loops
413 Perl's C-style "for" loop works like the corresponding "while" loop;
414 that means that this:
415 for ($i = 1; $i < 10; $i++) {
417 ...
418 }
419 is the same as this:
421 $i = 1;
423 while ($i < 10) {
424 ...
425 } continue {
426 $i++;
427 }
428 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 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 for (;;) {
438 ...
439 }
440 and
442 while () {
444 ...
445 }
446 are treated as infinite loops.
448 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 $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 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 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 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 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 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 "foreach" probably won't do what you expect if VAR is a tied or other
489 special variable. Don't do that either.
490 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 Examples:
501 for (@ary) { s/foo/bar/ }
503 for my $elem (@elements) {
505 $elem *= 2;
506 }
507 for $count (reverse(1..10), "BOOM") {
509 print $count, "\n";
510 sleep(1);
511 }
512 for (1..15) { print "Merry Christmas\n"; }
514 foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
516 print "Item: $item\n";
517 }
518 use feature "refaliasing";
520 no warnings "experimental::refaliasing";
521 foreach \my %hash (@array_of_hash_references) {
522 # do something which each %hash
523 }
524 Here's how a C programmer might code up a particular algorithm in Perl:
526 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 Whereas here's how a Perl programmer more comfortable with the idiom
538 might do it:
539 OUTER: for my $wid (@ary1) {
541 INNER: for my $jet (@ary2) {
542 next OUTER if $wid > $jet;
543 $wid += $jet;
544 }
545 }
546 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 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 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 The BLOCK construct can be used to emulate case structures.
569 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 You'll also find that "foreach" loop used to create a topicalizer and a
578 switch:
579 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 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 Switch Statements
594 Starting from Perl 5.10.1 (well, 5.10.0, but it didn't work right), you
595 can say
596 use feature "switch";
598 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 use v5.14;
606 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 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 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 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 As of 5.14, that can also be written this way:
636 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 Or if you don't care to play it safe, like this:
646 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 The arguments to "given" and "when" are in scalar context, and "given"
656 assigns the $_ variable its topic value.
657 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 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 If your code still needs to run on older versions, stick to "foreach"
675 for your topicalizer and you will be less unhappy.
676 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 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 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 goto(("FOO", "BAR", "GLARCH")[$i]);
698 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 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 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 use v5.12;
721 sub unimplemented { ... }
722 eval { unimplemented() };
723 if ($@ =~ /^Unimplemented at /) {
724 say "I found an ellipsis!";
725 }
726 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 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 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 use v5.12;
754 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 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 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 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 =head1 Here There Be Pods!
779 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 This allows you to intermix your source code and your documentation
785 text freely, as in
786 =item snazzle($)
788 The snazzle() function will behave in the most spectacular
790 form that you can possibly imagine, not even excepting
791 cybernetic pyrotechnics.
792 =cut back to the compiler, nuff of this pod stuff!
794 sub snazzle($) {
796 my $thingie = shift;
797 .........
798 }
799 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 $a=3;
807 =secret stuff
808 warn "Neither POD nor CODE!?"
809 =cut back
810 print "got $a\n";
811 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 One may also use pod directives to quickly comment out a section of
817 code.
818 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 # example: '# line 42 "new_filename.plx"'
827 /^\# \s*
828 line \s+ (\d+) \s*
829 (?:\s("?)([^"]+)\g2)? \s*
830 $/x
831 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 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 Here are some examples that you should be able to type into your
842 command shell:
843 % 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 % perl
852 # line 200 "bzzzt"
853 eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
854 __END__
855 foo at - line 2001.
856 % perl
858 eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
859 __END__
860 foo at foo bar line 200.
861 % perl
863 # line 345 "goop"
864 eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
865 print $@;
866 __END__
867 foo at goop line 345.
868 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 Here is a longer example of "given":
879 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 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 do { my $_ = EXPR; ... }
908 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 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 1. A user-defined subroutine call or a method invocation.
924 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 3. A smart match that uses an explicit "~~" operator, such as "EXPR ~~
930 EXPR".
931 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 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 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 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 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 8. The ".." and "..." flip-flop operators. Note that the "..." flip-
954 flop operator is completely different from the "..." elliptical
955 statement just described.
956 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 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 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 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 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 when (/^\d+$/ && $_ < 75) { ... }
984 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 Also:
989 when ([qw(foo bar)] && /baz/) { ... }
991 will use smartmatching because only one of the operands is a boolean:
993 the other uses smartmatching, and that wins.
994 Further:
996 when ([qw(foo bar)] || /^baz/) { ... }
998 will use smart matching (only the first operand is considered), whereas
1000 when (/^baz/ || [qw(foo bar)]) { ... }
1002 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 Tautologous boolean operators are still going to be optimized away.
1008 Don't be tempted to write
1009 when ("foo" or "bar") { ... }
1011 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 when ([qw(foo bar)] { ... }
1018 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 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 "default" behaves exactly like "when(1 == 1)", which is to say that it
1029 always matches.
1030 Breaking out
1032 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 Fall-through
1037 You can use the "continue" keyword to fall through from one case to the
1039 next immediate "when" or "default":
1040 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 Return value
1048 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 · An empty list as soon as an explicit "break" is encountered.
1053 · The value of the last evaluated expression of the successful
1055 "when"/"default" clause, if there happens to be one.
1056 · The value of the last evaluated expression of the "given" block if
1058 no condition is true.
1059 In both last cases, the last expression is evaluated in the context
1061 that was applied to the "given" block.
1062 Note that, unlike "if" and "unless", failed "when" statements always
1064 evaluate to an empty list.
1065 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 Currently, "given" blocks can't always be used as proper expressions.
1076 This may be addressed in a future version of Perl.
1077 Switching in a loop
1079 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 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 Or in a more recent version:
1092 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 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 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 Differences from Perl 6
1108 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 given $foo {
1119 ...
1120 }
1121 as though the argument to "given" were an element of the hash %foo,
1123 interpreting the braces as hash-element syntax.
1124 However, their are many, many other differences. For example, this
1126 works in Perl 5:
1127 use v5.12;
1129 my @primary = ("red", "blue", "green");
1130 if (@primary ~~ "red") {
1132 say "primary smartmatches red";
1133 }
1134 if ("red" ~~ @primary) {
1136 say "red smartmatches primary";
1137 }
1138 say "that's all, folks!";
1140 But it doesn't work at all in Perl 6. Instead, you should use the
1142 (parallelizable) "any" operator:
1143 if any(@primary) eq "red" {
1145 say "primary smartmatches red";
1146 }
1147 if "red" eq any(@primary) {
1149 say "red smartmatches primary";
1150 }
1151 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 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.)
1163perl v5.30.2 2020-03-27 PERLSYN(1)