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 Truth and Falsehood
113 The number 0, the strings '0' and "", the empty list "()", and "undef"
114 are all false in a boolean context. All other values are true.
115 Negation of a true value by "!" or "not" returns a special false value.
116 When evaluated as a string it is treated as "", but as a number, it is
117 treated as 0. Most Perl operators that return true or false behave
118 this way.
119 Statement Modifiers
121 Any simple statement may optionally be followed by a SINGLE modifier,
122 just before the terminating semicolon (or block ending). The possible
123 modifiers are:
124 if EXPR
126 unless EXPR
127 while EXPR
128 until EXPR
129 for LIST
130 foreach LIST
131 when EXPR
132 The "EXPR" following the modifier is referred to as the "condition".
134 Its truth or falsehood determines how the modifier will behave.
135 "if" executes the statement once if and only if the condition is true.
137 "unless" is the opposite, it executes the statement unless the
138 condition is true (that is, if the condition is false).
139 print "Basset hounds got long ears" if length $ear >= 10;
141 go_outside() and play() unless $is_raining;
142 The "for(each)" modifier is an iterator: it executes the statement once
144 for each item in the LIST (with $_ aliased to each item in turn).
145 print "Hello $_!\n" for qw(world Dolly nurse);
147 "while" repeats the statement while the condition is true. "until"
149 does the opposite, it repeats the statement until the condition is true
150 (or while the condition is false):
151 # Both of these count from 0 to 10.
153 print $i++ while $i <= 10;
154 print $j++ until $j > 10;
155 The "while" and "until" modifiers have the usual ""while" loop"
157 semantics (conditional evaluated first), except when applied to a
158 "do"-BLOCK (or to the Perl4 "do"-SUBROUTINE statement), in which case
159 the block executes once before the conditional is evaluated.
160 This is so that you can write loops like:
162 do {
164 $line = <STDIN>;
165 ...
166 } until !defined($line) || $line eq ".\n"
167 See "do" in perlfunc. Note also that the loop control statements
169 described later will NOT work in this construct, because modifiers
170 don't take loop labels. Sorry. You can always put another block
171 inside of it (for "next"/"redo") or around it (for "last") to do that
172 sort of thing.
173 For "next" or "redo", just double the braces:
175 do {{
177 next if $x == $y;
178 # do something here
179 }} until $x++ > $z;
180 For "last", you have to be more elaborate and put braces around it:
182 {
184 do {
185 last if $x == $y**2;
186 # do something here
187 } while $x++ <= $z;
188 }
189 If you need both "next" and "last", you have to do both and also use a
191 loop label:
192 LOOP: {
194 do {{
195 next if $x == $y;
196 last LOOP if $x == $y**2;
197 # do something here
198 }} until $x++ > $z;
199 }
200 NOTE: The behaviour of a "my", "state", or "our" modified with a
202 statement modifier conditional or loop construct (for example, "my $x
203 if ...") is undefined. The value of the "my" variable may be "undef",
204 any previously assigned value, or possibly anything else. Don't rely
205 on it. Future versions of perl might do something different from the
206 version of perl you try it out on. Here be dragons.
207 The "when" modifier is an experimental feature that first appeared in
209 Perl 5.14. To use it, you should include a "use v5.14" declaration.
210 (Technically, it requires only the "switch" feature, but that aspect of
211 it was not available before 5.14.) Operative only from within a
212 "foreach" loop or a "given" block, it executes the statement only if
213 the smartmatch "$_ ~~ EXPR" is true. If the statement executes, it is
214 followed by a "next" from inside a "foreach" and "break" from inside a
215 "given".
216 Under the current implementation, the "foreach" loop can be anywhere
218 within the "when" modifier's dynamic scope, but must be within the
219 "given" block's lexical scope. This restriction may be relaxed in a
220 future release. See "Switch Statements" below.
221 Compound Statements
223 In Perl, a sequence of statements that defines a scope is called a
224 block. Sometimes a block is delimited by the file containing it (in
225 the case of a required file, or the program as a whole), and sometimes
226 a block is delimited by the extent of a string (in the case of an
227 eval).
228 But generally, a block is delimited by curly brackets, also known as
230 braces. We will call this syntactic construct a BLOCK.
231 The following compound statements may be used to control flow:
233 if (EXPR) BLOCK
235 if (EXPR) BLOCK else BLOCK
236 if (EXPR) BLOCK elsif (EXPR) BLOCK ...
237 if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
238 unless (EXPR) BLOCK
240 unless (EXPR) BLOCK else BLOCK
241 unless (EXPR) BLOCK elsif (EXPR) BLOCK ...
242 unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
243 given (EXPR) BLOCK
245 LABEL while (EXPR) BLOCK
247 LABEL while (EXPR) BLOCK continue BLOCK
248 LABEL until (EXPR) BLOCK
250 LABEL until (EXPR) BLOCK continue BLOCK
251 LABEL for (EXPR; EXPR; EXPR) BLOCK
253 LABEL for VAR (LIST) BLOCK
254 LABEL for VAR (LIST) BLOCK continue BLOCK
255 LABEL foreach (EXPR; EXPR; EXPR) BLOCK
257 LABEL foreach VAR (LIST) BLOCK
258 LABEL foreach VAR (LIST) BLOCK continue BLOCK
259 LABEL BLOCK
261 LABEL BLOCK continue BLOCK
262 PHASE BLOCK
264 The experimental "given" statement is not automatically enabled; see
266 "Switch Statements" below for how to do so, and the attendant caveats.
267 Unlike in C and Pascal, in Perl these are all defined in terms of
269 BLOCKs, not statements. This means that the curly brackets are
270 required--no dangling statements allowed. If you want to write
271 conditionals without curly brackets, there are several other ways to do
272 it. The following all do the same thing:
273 if (!open(FOO)) { die "Can't open $FOO: $!" }
275 die "Can't open $FOO: $!" unless open(FOO);
276 open(FOO) || die "Can't open $FOO: $!";
277 open(FOO) ? () : die "Can't open $FOO: $!";
278 # a bit exotic, that last one
279 The "if" statement is straightforward. Because BLOCKs are always
281 bounded by curly brackets, there is never any ambiguity about which
282 "if" an "else" goes with. If you use "unless" in place of "if", the
283 sense of the test is reversed. Like "if", "unless" can be followed by
284 "else". "unless" can even be followed by one or more "elsif"
285 statements, though you may want to think twice before using that
286 particular language construct, as everyone reading your code will have
287 to think at least twice before they can understand what's going on.
288 The "while" statement executes the block as long as the expression is
290 true. The "until" statement executes the block as long as the
291 expression is false. The LABEL is optional, and if present, consists
292 of an identifier followed by a colon. The LABEL identifies the loop
293 for the loop control statements "next", "last", and "redo". If the
294 LABEL is omitted, the loop control statement refers to the innermost
295 enclosing loop. This may include dynamically looking back your call-
296 stack at run time to find the LABEL. Such desperate behavior triggers
297 a warning if you use the "use warnings" pragma or the -w flag.
298 If there is a "continue" BLOCK, it is always executed just before the
300 conditional is about to be evaluated again. Thus it can be used to
301 increment a loop variable, even when the loop has been continued via
302 the "next" statement.
303 When a block is preceding by a compilation phase keyword such as
305 "BEGIN", "END", "INIT", "CHECK", or "UNITCHECK", then the block will
306 run only during the corresponding phase of execution. See perlmod for
307 more details.
308 Extension modules can also hook into the Perl parser to define new
310 kinds of compound statements. These are introduced by a keyword which
311 the extension recognizes, and the syntax following the keyword is
312 defined entirely by the extension. If you are an implementor, see
313 "PL_keyword_plugin" in perlapi for the mechanism. If you are using
314 such a module, see the module's documentation for details of the syntax
315 that it defines.
316 Loop Control
318 The "next" command starts the next iteration of the loop:
319 LINE: while (<STDIN>) {
321 next LINE if /^#/; # discard comments
322 ...
323 }
324 The "last" command immediately exits the loop in question. The
326 "continue" block, if any, is not executed:
327 LINE: while (<STDIN>) {
329 last LINE if /^$/; # exit when done with header
330 ...
331 }
332 The "redo" command restarts the loop block without evaluating the
334 conditional again. The "continue" block, if any, is not executed.
335 This command is normally used by programs that want to lie to
336 themselves about what was just input.
337 For example, when processing a file like /etc/termcap. If your input
339 lines might end in backslashes to indicate continuation, you want to
340 skip ahead and get the next record.
341 while (<>) {
343 chomp;
344 if (s/\\$//) {
345 $_ .= <>;
346 redo unless eof();
347 }
348 # now process $_
349 }
350 which is Perl shorthand for the more explicitly written version:
352 LINE: while (defined($line = <ARGV>)) {
354 chomp($line);
355 if ($line =~ s/\\$//) {
356 $line .= <ARGV>;
357 redo LINE unless eof(); # not eof(ARGV)!
358 }
359 # now process $line
360 }
361 Note that if there were a "continue" block on the above code, it would
363 get executed only on lines discarded by the regex (since redo skips the
364 continue block). A continue block is often used to reset line counters
365 or "m?pat?" one-time matches:
366 # inspired by :1,$g/fred/s//WILMA/
368 while (<>) {
369 m?(fred)? && s//WILMA $1 WILMA/;
370 m?(barney)? && s//BETTY $1 BETTY/;
371 m?(homer)? && s//MARGE $1 MARGE/;
372 } continue {
373 print "$ARGV $.: $_";
374 close ARGV if eof; # reset $.
375 reset if eof; # reset ?pat?
376 }
377 If the word "while" is replaced by the word "until", the sense of the
379 test is reversed, but the conditional is still tested before the first
380 iteration.
381 Loop control statements don't work in an "if" or "unless", since they
383 aren't loops. You can double the braces to make them such, though.
384 if (/pattern/) {{
386 last if /fred/;
387 next if /barney/; # same effect as "last",
388 # but doesn't document as well
389 # do something here
390 }}
391 This is caused by the fact that a block by itself acts as a loop that
393 executes once, see "Basic BLOCKs".
394 The form "while/if BLOCK BLOCK", available in Perl 4, is no longer
396 available. Replace any occurrence of "if BLOCK" by "if (do BLOCK)".
397 For Loops
399 Perl's C-style "for" loop works like the corresponding "while" loop;
400 that means that this:
401 for ($i = 1; $i < 10; $i++) {
403 ...
404 }
405 is the same as this:
407 $i = 1;
409 while ($i < 10) {
410 ...
411 } continue {
412 $i++;
413 }
414 There is one minor difference: if variables are declared with "my" in
416 the initialization section of the "for", the lexical scope of those
417 variables is exactly the "for" loop (the body of the loop and the
418 control sections).
419 As a special case, if the test in the "for" loop (or the corresponding
421 "while" loop) is empty, it is treated as true. That is, both
422 for (;;) {
424 ...
425 }
426 and
428 while () {
430 ...
431 }
432 are treated as infinite loops.
434 Besides the normal array index looping, "for" can lend itself to many
436 other interesting applications. Here's one that avoids the problem you
437 get into if you explicitly test for end-of-file on an interactive file
438 descriptor causing your program to appear to hang.
439 $on_a_tty = -t STDIN && -t STDOUT;
441 sub prompt { print "yes? " if $on_a_tty }
442 for ( prompt(); <STDIN>; prompt() ) {
443 # do something
444 }
445 Using "readline" (or the operator form, "<EXPR>") as the conditional of
447 a "for" loop is shorthand for the following. This behaviour is the
448 same as a "while" loop conditional.
449 for ( prompt(); defined( $_ = <STDIN> ); prompt() ) {
451 # do something
452 }
453 Foreach Loops
455 The "foreach" loop iterates over a normal list value and sets the
456 scalar variable VAR to be each element of the list in turn. If the
457 variable is preceded with the keyword "my", then it is lexically
458 scoped, and is therefore visible only within the loop. Otherwise, the
459 variable is implicitly local to the loop and regains its former value
460 upon exiting the loop. If the variable was previously declared with
461 "my", it uses that variable instead of the global one, but it's still
462 localized to the loop. This implicit localization occurs only in a
463 "foreach" loop.
464 The "foreach" keyword is actually a synonym for the "for" keyword, so
466 you can use either. If VAR is omitted, $_ is set to each value.
467 If any element of LIST is an lvalue, you can modify it by modifying VAR
469 inside the loop. Conversely, if any element of LIST is NOT an lvalue,
470 any attempt to modify that element will fail. In other words, the
471 "foreach" loop index variable is an implicit alias for each item in the
472 list that you're looping over.
473 If any part of LIST is an array, "foreach" will get very confused if
475 you add or remove elements within the loop body, for example with
476 "splice". So don't do that.
477 "foreach" probably won't do what you expect if VAR is a tied or other
479 special variable. Don't do that either.
480 As of Perl 5.22, there is an experimental variant of this loop that
482 accepts a variable preceded by a backslash for VAR, in which case the
483 items in the LIST must be references. The backslashed variable will
484 become an alias to each referenced item in the LIST, which must be of
485 the correct type. The variable needn't be a scalar in this case, and
486 the backslash may be followed by "my". To use this form, you must
487 enable the "refaliasing" feature via "use feature". (See feature. See
488 also "Assigning to References" in perlref.)
489 Examples:
491 for (@ary) { s/foo/bar/ }
493 for my $elem (@elements) {
495 $elem *= 2;
496 }
497 for $count (reverse(1..10), "BOOM") {
499 print $count, "\n";
500 sleep(1);
501 }
502 for (1..15) { print "Merry Christmas\n"; }
504 foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
506 print "Item: $item\n";
507 }
508 use feature "refaliasing";
510 no warnings "experimental::refaliasing";
511 foreach \my %hash (@array_of_hash_references) {
512 # do something which each %hash
513 }
514 Here's how a C programmer might code up a particular algorithm in Perl:
516 for (my $i = 0; $i < @ary1; $i++) {
518 for (my $j = 0; $j < @ary2; $j++) {
519 if ($ary1[$i] > $ary2[$j]) {
520 last; # can't go to outer :-(
521 }
522 $ary1[$i] += $ary2[$j];
523 }
524 # this is where that last takes me
525 }
526 Whereas here's how a Perl programmer more comfortable with the idiom
528 might do it:
529 OUTER: for my $wid (@ary1) {
531 INNER: for my $jet (@ary2) {
532 next OUTER if $wid > $jet;
533 $wid += $jet;
534 }
535 }
536 See how much easier this is? It's cleaner, safer, and faster. It's
538 cleaner because it's less noisy. It's safer because if code gets added
539 between the inner and outer loops later on, the new code won't be
540 accidentally executed. The "next" explicitly iterates the other loop
541 rather than merely terminating the inner one. And it's faster because
542 Perl executes a "foreach" statement more rapidly than it would the
543 equivalent "for" loop.
544 Perceptive Perl hackers may have noticed that a "for" loop has a return
546 value, and that this value can be captured by wrapping the loop in a
547 "do" block. The reward for this discovery is this cautionary advice:
548 The return value of a "for" loop is unspecified and may change without
549 notice. Do not rely on it.
550 Basic BLOCKs
552 A BLOCK by itself (labeled or not) is semantically equivalent to a loop
553 that executes once. Thus you can use any of the loop control
554 statements in it to leave or restart the block. (Note that this is NOT
555 true in "eval{}", "sub{}", or contrary to popular belief "do{}" blocks,
556 which do NOT count as loops.) The "continue" block is optional.
557 The BLOCK construct can be used to emulate case structures.
559 SWITCH: {
561 if (/^abc/) { $abc = 1; last SWITCH; }
562 if (/^def/) { $def = 1; last SWITCH; }
563 if (/^xyz/) { $xyz = 1; last SWITCH; }
564 $nothing = 1;
565 }
566 You'll also find that "foreach" loop used to create a topicalizer and a
568 switch:
569 SWITCH:
571 for ($var) {
572 if (/^abc/) { $abc = 1; last SWITCH; }
573 if (/^def/) { $def = 1; last SWITCH; }
574 if (/^xyz/) { $xyz = 1; last SWITCH; }
575 $nothing = 1;
576 }
577 Such constructs are quite frequently used, both because older versions
579 of Perl had no official "switch" statement, and also because the new
580 version described immediately below remains experimental and can
581 sometimes be confusing.
582 Switch Statements
584 Starting from Perl 5.10.1 (well, 5.10.0, but it didn't work right), you
585 can say
586 use feature "switch";
588 to enable an experimental switch feature. This is loosely based on an
590 old version of a Perl 6 proposal, but it no longer resembles the Perl 6
591 construct. You also get the switch feature whenever you declare that
592 your code prefers to run under a version of Perl that is 5.10 or later.
593 For example:
594 use v5.14;
596 Under the "switch" feature, Perl gains the experimental keywords
598 "given", "when", "default", "continue", and "break". Starting from
599 Perl 5.16, one can prefix the switch keywords with "CORE::" to access
600 the feature without a "use feature" statement. The keywords "given"
601 and "when" are analogous to "switch" and "case" in other languages --
602 though "continue" is not -- so the code in the previous section could
603 be rewritten as
604 use v5.10.1;
606 for ($var) {
607 when (/^abc/) { $abc = 1 }
608 when (/^def/) { $def = 1 }
609 when (/^xyz/) { $xyz = 1 }
610 default { $nothing = 1 }
611 }
612 The "foreach" is the non-experimental way to set a topicalizer. If you
614 wish to use the highly experimental "given", that could be written like
615 this:
616 use v5.10.1;
618 given ($var) {
619 when (/^abc/) { $abc = 1 }
620 when (/^def/) { $def = 1 }
621 when (/^xyz/) { $xyz = 1 }
622 default { $nothing = 1 }
623 }
624 As of 5.14, that can also be written this way:
626 use v5.14;
628 for ($var) {
629 $abc = 1 when /^abc/;
630 $def = 1 when /^def/;
631 $xyz = 1 when /^xyz/;
632 default { $nothing = 1 }
633 }
634 Or if you don't care to play it safe, like this:
636 use v5.14;
638 given ($var) {
639 $abc = 1 when /^abc/;
640 $def = 1 when /^def/;
641 $xyz = 1 when /^xyz/;
642 default { $nothing = 1 }
643 }
644 The arguments to "given" and "when" are in scalar context, and "given"
646 assigns the $_ variable its topic value.
647 Exactly what the EXPR argument to "when" does is hard to describe
649 precisely, but in general, it tries to guess what you want done.
650 Sometimes it is interpreted as "$_ ~~ EXPR", and sometimes it is not.
651 It also behaves differently when lexically enclosed by a "given" block
652 than it does when dynamically enclosed by a "foreach" loop. The rules
653 are far too difficult to understand to be described here. See
654 "Experimental Details on given and when" later on.
655 Due to an unfortunate bug in how "given" was implemented between Perl
657 5.10 and 5.16, under those implementations the version of $_ governed
658 by "given" is merely a lexically scoped copy of the original, not a
659 dynamically scoped alias to the original, as it would be if it were a
660 "foreach" or under both the original and the current Perl 6 language
661 specification. This bug was fixed in Perl 5.18 (and lexicalized $_
662 itself was removed in Perl 5.24).
663 If your code still needs to run on older versions, stick to "foreach"
665 for your topicalizer and you will be less unhappy.
666 Goto
668 Although not for the faint of heart, Perl does support a "goto"
669 statement. There are three forms: "goto"-LABEL, "goto"-EXPR, and
670 "goto"-&NAME. A loop's LABEL is not actually a valid target for a
671 "goto"; it's just the name of the loop.
672 The "goto"-LABEL form finds the statement labeled with LABEL and
674 resumes execution there. It may not be used to go into any construct
675 that requires initialization, such as a subroutine or a "foreach" loop.
676 It also can't be used to go into a construct that is optimized away.
677 It can be used to go almost anywhere else within the dynamic scope,
678 including out of subroutines, but it's usually better to use some other
679 construct such as "last" or "die". The author of Perl has never felt
680 the need to use this form of "goto" (in Perl, that is--C is another
681 matter).
682 The "goto"-EXPR form expects a label name, whose scope will be resolved
684 dynamically. This allows for computed "goto"s per FORTRAN, but isn't
685 necessarily recommended if you're optimizing for maintainability:
686 goto(("FOO", "BAR", "GLARCH")[$i]);
688 The "goto"-&NAME form is highly magical, and substitutes a call to the
690 named subroutine for the currently running subroutine. This is used by
691 "AUTOLOAD()" subroutines that wish to load another subroutine and then
692 pretend that the other subroutine had been called in the first place
693 (except that any modifications to @_ in the current subroutine are
694 propagated to the other subroutine.) After the "goto", not even
695 "caller()" will be able to tell that this routine was called first.
696 In almost all cases like this, it's usually a far, far better idea to
698 use the structured control flow mechanisms of "next", "last", or "redo"
699 instead of resorting to a "goto". For certain applications, the catch
700 and throw pair of "eval{}" and die() for exception processing can also
701 be a prudent approach.
702 The Ellipsis Statement
704 Beginning in Perl 5.12, Perl accepts an ellipsis, ""..."", as a
705 placeholder for code that you haven't implemented yet. This form of
706 ellipsis, the unimplemented statement, should not be confused with the
707 binary flip-flop "..." operator. One is a statement and the other an
708 operator. (Perl doesn't usually confuse them because usually Perl can
709 tell whether it wants an operator or a statement, but see below for
710 exceptions.)
711 When Perl 5.12 or later encounters an ellipsis statement, it parses
713 this without error, but if and when you should actually try to execute
714 it, Perl throws an exception with the text "Unimplemented":
715 use v5.12;
717 sub unimplemented { ... }
718 eval { unimplemented() };
719 if ($@ =~ /^Unimplemented at /) {
720 say "I found an ellipsis!";
721 }
722 You can only use the elliptical statement to stand in for a complete
724 statement. These examples of how the ellipsis works:
725 use v5.12;
727 { ... }
728 sub foo { ... }
729 ...;
730 eval { ... };
731 sub somemeth {
732 my $self = shift;
733 ...;
734 }
735 $x = do {
736 my $n;
737 ...;
738 say "Hurrah!";
739 $n;
740 };
741 The elliptical statement cannot stand in for an expression that is part
743 of a larger statement, since the "..." is also the three-dot version of
744 the flip-flop operator (see "Range Operators" in perlop).
745 These examples of attempts to use an ellipsis are syntax errors:
747 use v5.12;
749 print ...;
751 open(my $fh, ">", "/dev/passwd") or ...;
752 if ($condition && ... ) { say "Howdy" };
753 There are some cases where Perl can't immediately tell the difference
755 between an expression and a statement. For instance, the syntax for a
756 block and an anonymous hash reference constructor look the same unless
757 there's something in the braces to give Perl a hint. The ellipsis is a
758 syntax error if Perl doesn't guess that the "{ ... }" is a block. In
759 that case, it doesn't think the "..." is an ellipsis because it's
760 expecting an expression instead of a statement:
761 @transformed = map { ... } @input; # syntax error
763 Inside your block, you can use a ";" before the ellipsis to denote that
765 the "{ ... }" is a block and not a hash reference constructor. Now the
766 ellipsis works:
767 @transformed = map {; ... } @input; # ';' disambiguates
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 frequentlythe 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.26.3 2018-03-23 PERLSYN(1)