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