8 A Perl program consists of a sequence of declarations and statements
9 which run from the top to the bottom. Loops, subroutines, and other
10 control structures allow you to jump around within the code.
12 Perl is a B<free-form> language: you can format and indent it however
13 you like. Whitespace serves mostly to separate tokens, unlike
14 languages like Python where it is an important part of the syntax,
15 or Fortran where it is immaterial.
17 Many of Perl's syntactic elements are B<optional>. Rather than
18 requiring you to put parentheses around every function call and
19 declare every variable, you can often leave such explicit elements off
20 and Perl will figure out what you meant. This is known as B<Do What I
21 Mean>, abbreviated B<DWIM>. It allows programmers to be B<lazy> and to
22 code in a style with which they are comfortable.
24 Perl B<borrows syntax> and concepts from many languages: awk, sed, C,
25 Bourne Shell, Smalltalk, Lisp and even English. Other
26 languages have borrowed syntax from Perl, particularly its regular
27 expression extensions. So if you have programmed in another language
28 you will see familiar pieces in Perl. They often work the same, but
29 see L<perltrap> for information about how they differ.
32 X<declaration> X<undef> X<undefined> X<uninitialized>
34 The only things you need to declare in Perl are report formats and
35 subroutines (and sometimes not even subroutines). A scalar variable holds
36 the undefined value (C<undef>) until it has been assigned a defined
37 value, which is anything other than C<undef>. When used as a number,
38 C<undef> is treated as C<0>; when used as a string, it is treated as
39 the empty string, C<"">; and when used as a reference that isn't being
40 assigned to, it is treated as an error. If you enable warnings,
41 you'll be notified of an uninitialized value whenever you treat
42 C<undef> as a string or a number. Well, usually. Boolean contexts,
47 are exempt from warnings (because they care about truth rather than
48 definedness). Operators such as C<++>, C<-->, C<+=>,
49 C<-=>, and C<.=>, that operate on undefined variables such as:
54 are also always exempt from such warnings.
56 A declaration can be put anywhere a statement can, but has no effect on
57 the execution of the primary sequence of statements: declarations all
58 take effect at compile time. All declarations are typically put at
59 the beginning or the end of the script. However, if you're using
60 lexically-scoped private variables created with C<my()>,
61 C<state()>, or C<our()>, you'll have to make sure
62 your format or subroutine definition is within the same block scope
63 as the my if you expect to be able to access those private variables.
65 Declaring a subroutine allows a subroutine name to be used as if it were a
66 list operator from that point forward in the program. You can declare a
67 subroutine without defining it by saying C<sub name>, thus:
68 X<subroutine, declaration>
71 $me = myname $0 or die "can't get myname";
73 A bare declaration like that declares the function to be a list operator,
74 not a unary operator, so you have to be careful to use parentheses (or
75 C<or> instead of C<||>.) The C<||> operator binds too tightly to use after
76 list operators; it becomes part of the last element. You can always use
77 parentheses around the list operators arguments to turn the list operator
78 back into something that behaves more like a function call. Alternatively,
79 you can use the prototype C<($)> to turn the subroutine into a unary
83 $me = myname $0 || die "can't get myname";
85 That now parses as you'd expect, but you still ought to get in the habit of
86 using parentheses in that situation. For more on prototypes, see
89 Subroutines declarations can also be loaded up with the C<require> statement
90 or both loaded and imported into your namespace with a C<use> statement.
91 See L<perlmod> for details on this.
93 A statement sequence may contain declarations of lexically-scoped
94 variables, but apart from declaring a variable name, the declaration acts
95 like an ordinary statement, and is elaborated within the sequence of
96 statements as if it were an ordinary statement. That means it actually
97 has both compile-time and run-time effects.
102 Text from a C<"#"> character until the end of the line is a comment,
103 and is ignored. Exceptions include C<"#"> inside a string or regular
106 =head2 Simple Statements
107 X<statement> X<semicolon> X<expression> X<;>
109 The only kind of simple statement is an expression evaluated for its
110 side-effects. Every simple statement must be terminated with a
111 semicolon, unless it is the final statement in a block, in which case
112 the semicolon is optional. But put the semicolon in anyway if the
113 block takes up more than one line, because you may eventually add
114 another line. Note that there are operators like C<eval {}>, C<sub {}>, and
115 C<do {}> that I<look> like compound statements, but aren't--they're just
116 TERMs in an expression--and thus need an explicit termination when used
117 as the last item in a statement.
119 =head2 Statement Modifiers
120 X<statement modifier> X<modifier> X<if> X<unless> X<while>
121 X<until> X<when> X<foreach> X<for>
123 Any simple statement may optionally be followed by a I<SINGLE> modifier,
124 just before the terminating semicolon (or block ending). The possible
135 The C<EXPR> following the modifier is referred to as the "condition".
136 Its truth or falsehood determines how the modifier will behave.
138 C<if> executes the statement once I<if> and only if the condition is
139 true. C<unless> is the opposite, it executes the statement I<unless>
140 the condition is true (that is, if the condition is false). See
141 L<perldata/Scalar values> for definitions of true and false.
143 print "Basset hounds got long ears" if length $ear >= 10;
144 go_outside() and play() unless $is_raining;
146 The C<for(each)> modifier is an iterator: it executes the statement once
147 for each item in the LIST (with C<$_> aliased to each item in turn).
148 There is no syntax to specify a C-style for loop or a lexically scoped
149 iteration variable in this form.
151 print "Hello $_!\n" for qw(world Dolly nurse);
153 C<while> repeats the statement I<while> the condition is true.
154 Postfix C<while> has the same magic treatment of some kinds of condition
155 that prefix C<while> has.
156 C<until> does the opposite, it repeats the statement I<until> the
157 condition is true (or while the condition is false):
159 # Both of these count from 0 to 10.
160 print $i++ while $i <= 10;
161 print $j++ until $j > 10;
163 The C<while> and C<until> modifiers have the usual "C<while> loop"
164 semantics (conditional evaluated first), except when applied to a
165 C<do>-BLOCK (or to the Perl4 C<do>-SUBROUTINE statement), in
166 which case the block executes once before the conditional is
169 This is so that you can write loops like:
174 } until !defined($line) || $line eq ".\n"
176 See L<perlfunc/do>. Note also that the loop control statements described
177 later will I<NOT> work in this construct, because modifiers don't take
178 loop labels. Sorry. You can always put another block inside of it
179 (for C<next>/C<redo>) or around it (for C<last>) to do that sort of thing.
180 X<next> X<last> X<redo>
182 For C<next> or C<redo>, just double the braces:
189 For C<last>, you have to be more elaborate and put braces around it:
199 If you need both C<next> and C<last>, you have to do both and also use a
205 last LOOP if $x == $y**2;
210 B<NOTE:> The behaviour of a C<my>, C<state>, or
211 C<our> modified with a statement modifier conditional
212 or loop construct (for example, C<my $x if ...>) is
213 B<undefined>. The value of the C<my> variable may be C<undef>, any
214 previously assigned value, or possibly anything else. Don't rely on
215 it. Future versions of perl might do something different from the
216 version of perl you try it out on. Here be dragons.
219 The C<when> modifier is an experimental feature that first appeared in Perl
220 5.14. To use it, you should include a C<use v5.14> declaration.
221 (Technically, it requires only the C<switch> feature, but that aspect of it
222 was not available before 5.14.) Operative only from within a C<foreach>
223 loop or a C<given> block, it executes the statement only if the smartmatch
224 C<< $_ ~~ I<EXPR> >> is true. If the statement executes, it is followed by
225 a C<next> from inside a C<foreach> and C<break> from inside a C<given>.
227 Under the current implementation, the C<foreach> loop can be
228 anywhere within the C<when> modifier's dynamic scope, but must be
229 within the C<given> block's lexical scope. This restriction may
230 be relaxed in a future release. See L</"Switch Statements"> below.
232 =head2 Compound Statements
233 X<statement, compound> X<block> X<bracket, curly> X<curly bracket> X<brace>
234 X<{> X<}> X<if> X<unless> X<given> X<while> X<until> X<foreach> X<for> X<continue>
236 In Perl, a sequence of statements that defines a scope is called a block.
237 Sometimes a block is delimited by the file containing it (in the case
238 of a required file, or the program as a whole), and sometimes a block
239 is delimited by the extent of a string (in the case of an eval).
241 But generally, a block is delimited by curly brackets, also known as
242 braces. We will call this syntactic construct a BLOCK. Because enclosing
243 braces are also the syntax for hash reference constructor expressions
244 (see L<perlref>), you may occasionally need to disambiguate by placing a
245 C<;> immediately after an opening brace so that Perl realises the brace
246 is the start of a block. You will more frequently need to disambiguate
247 the other way, by placing a C<+> immediately before an opening brace to
248 force it to be interpreted as a hash reference constructor expression.
249 It is considered good style to use these disambiguating mechanisms
250 liberally, not only when Perl would otherwise guess incorrectly.
252 The following compound statements may be used to control flow:
255 if (EXPR) BLOCK else BLOCK
256 if (EXPR) BLOCK elsif (EXPR) BLOCK ...
257 if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
260 unless (EXPR) BLOCK else BLOCK
261 unless (EXPR) BLOCK elsif (EXPR) BLOCK ...
262 unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
266 LABEL while (EXPR) BLOCK
267 LABEL while (EXPR) BLOCK continue BLOCK
269 LABEL until (EXPR) BLOCK
270 LABEL until (EXPR) BLOCK continue BLOCK
272 LABEL for (EXPR; EXPR; EXPR) BLOCK
273 LABEL for VAR (LIST) BLOCK
274 LABEL for VAR (LIST) BLOCK continue BLOCK
276 LABEL foreach (EXPR; EXPR; EXPR) BLOCK
277 LABEL foreach VAR (LIST) BLOCK
278 LABEL foreach VAR (LIST) BLOCK continue BLOCK
281 LABEL BLOCK continue BLOCK
285 As of Perl 5.36, you can iterate over multiple values at a time by specifying
286 a list of lexicals within parentheses:
288 no warnings "experimental::for_list";
289 LABEL for my (VAR, VAR) (LIST) BLOCK
290 LABEL for my (VAR, VAR) (LIST) BLOCK continue BLOCK
291 LABEL foreach my (VAR, VAR) (LIST) BLOCK
292 LABEL foreach my (VAR, VAR) (LIST) BLOCK continue BLOCK
294 If enabled by the experimental C<try> feature, the following may also be used
296 try BLOCK catch (VAR) BLOCK
297 try BLOCK catch (VAR) BLOCK finally BLOCK
299 The experimental C<given> statement is I<not automatically enabled>; see
300 L</"Switch Statements"> below for how to do so, and the attendant caveats.
302 Unlike in C and Pascal, in Perl these are all defined in terms of BLOCKs,
303 not statements. This means that the curly brackets are I<required>--no
304 dangling statements allowed. If you want to write conditionals without
305 curly brackets, there are several other ways to do it. The following
306 all do the same thing:
308 if (!open(FOO)) { die "Can't open $FOO: $!" }
309 die "Can't open $FOO: $!" unless open(FOO);
310 open(FOO) || die "Can't open $FOO: $!";
311 open(FOO) ? () : die "Can't open $FOO: $!";
312 # a bit exotic, that last one
314 The C<if> statement is straightforward. Because BLOCKs are always
315 bounded by curly brackets, there is never any ambiguity about which
316 C<if> an C<else> goes with. If you use C<unless> in place of C<if>,
317 the sense of the test is reversed. Like C<if>, C<unless> can be followed
318 by C<else>. C<unless> can even be followed by one or more C<elsif>
319 statements, though you may want to think twice before using that particular
320 language construct, as everyone reading your code will have to think at least
321 twice before they can understand what's going on.
323 The C<while> statement executes the block as long as the expression is
325 The C<until> statement executes the block as long as the expression is
327 The LABEL is optional, and if present, consists of an identifier followed
328 by a colon. The LABEL identifies the loop for the loop control
329 statements C<next>, C<last>, and C<redo>.
330 If the LABEL is omitted, the loop control statement
331 refers to the innermost enclosing loop. This may include dynamically
332 searching through your call-stack at run time to find the LABEL. Such
333 desperate behavior triggers a warning if you use the C<use warnings>
334 pragma or the B<-w> flag.
336 If the condition expression of a C<while> statement is based
337 on any of a group of iterative expression types then it gets
338 some magic treatment. The affected iterative expression types
339 are L<C<readline>|perlfunc/readline EXPR>, the L<C<< <FILEHANDLE>
340 >>|perlop/"I/O Operators"> input operator, L<C<readdir>|perlfunc/readdir
341 DIRHANDLE>, L<C<glob>|perlfunc/glob EXPR>, the L<C<< <PATTERN>
342 >>|perlop/"I/O Operators"> globbing operator, and L<C<each>|perlfunc/each
343 HASH>. If the condition expression is one of these expression types, then
344 the value yielded by the iterative operator will be implicitly assigned
345 to C<$_>. If the condition expression is one of these expression types
346 or an explicit assignment of one of them to a scalar, then the condition
347 actually tests for definedness of the expression's value, not for its
350 If there is a C<continue> BLOCK, it is always executed just before the
351 conditional is about to be evaluated again. Thus it can be used to
352 increment a loop variable, even when the loop has been continued via
353 the C<next> statement.
355 When a block is preceded by a compilation phase keyword such as C<BEGIN>,
356 C<END>, C<INIT>, C<CHECK>, or C<UNITCHECK>, then the block will run only
357 during the corresponding phase of execution. See L<perlmod> for more details.
359 Extension modules can also hook into the Perl parser to define new
360 kinds of compound statements. These are introduced by a keyword which
361 the extension recognizes, and the syntax following the keyword is
362 defined entirely by the extension. If you are an implementor, see
363 L<perlapi/PL_keyword_plugin> for the mechanism. If you are using such
364 a module, see the module's documentation for details of the syntax that
368 X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue>
370 The C<next> command starts the next iteration of the loop:
372 LINE: while (<STDIN>) {
373 next LINE if /^#/; # discard comments
377 The C<last> command immediately exits the loop in question. The
378 C<continue> block, if any, is not executed:
380 LINE: while (<STDIN>) {
381 last LINE if /^$/; # exit when done with header
385 The C<redo> command restarts the loop block without evaluating the
386 conditional again. The C<continue> block, if any, is I<not> executed.
387 This command is normally used by programs that want to lie to themselves
388 about what was just input.
390 For example, when processing a file like F</etc/termcap>.
391 If your input lines might end in backslashes to indicate continuation, you
392 want to skip ahead and get the next record.
403 which is Perl shorthand for the more explicitly written version:
405 LINE: while (defined($line = <ARGV>)) {
407 if ($line =~ s/\\$//) {
409 redo LINE unless eof(); # not eof(ARGV)!
414 Note that if there were a C<continue> block on the above code, it would
415 get executed only on lines discarded by the regex (since redo skips the
416 continue block). A continue block is often used to reset line counters
417 or C<m?pat?> one-time matches:
419 # inspired by :1,$g/fred/s//WILMA/
421 m?(fred)? && s//WILMA $1 WILMA/;
422 m?(barney)? && s//BETTY $1 BETTY/;
423 m?(homer)? && s//MARGE $1 MARGE/;
425 print "$ARGV $.: $_";
426 close ARGV if eof; # reset $.
427 reset if eof; # reset ?pat?
430 If the word C<while> is replaced by the word C<until>, the sense of the
431 test is reversed, but the conditional is still tested before the first
434 Loop control statements don't work in an C<if> or C<unless>, since
435 they aren't loops. You can double the braces to make them such, though.
439 next if /barney/; # same effect as "last",
440 # but doesn't document as well
444 This is caused by the fact that a block by itself acts as a loop that
445 executes once, see L</"Basic BLOCKs">.
447 The form C<while/if BLOCK BLOCK>, available in Perl 4, is no longer
448 available. Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>.
453 Perl's C-style C<for> loop works like the corresponding C<while> loop;
454 that means that this:
456 for ($i = 1; $i < 10; $i++) {
469 There is one minor difference: if variables are declared with C<my>
470 in the initialization section of the C<for>, the lexical scope of
471 those variables is exactly the C<for> loop (the body of the loop
472 and the control sections). To illustrate:
476 for (my $i = 1; $i <= 4; $i++) {
481 when executed, gives:
489 As a special case, if the test in the C<for> loop (or the corresponding
490 C<while> loop) is empty, it is treated as true. That is, both
502 are treated as infinite loops.
504 Besides the normal array index looping, C<for> can lend itself
505 to many other interesting applications. Here's one that avoids the
506 problem you get into if you explicitly test for end-of-file on
507 an interactive file descriptor causing your program to appear to
509 X<eof> X<end-of-file> X<end of file>
511 $on_a_tty = -t STDIN && -t STDOUT;
512 sub prompt { print "yes? " if $on_a_tty }
513 for ( prompt(); <STDIN>; prompt() ) {
517 The condition expression of a C<for> loop gets the same magic treatment of
518 C<readline> et al that the condition expression of a C<while> loop gets.
523 The C<foreach> loop iterates over a normal list value and sets the scalar
524 variable VAR to be each element of the list in turn. If the variable
525 is preceded with the keyword C<my>, then it is lexically scoped, and
526 is therefore visible only within the loop. Otherwise, the variable is
527 implicitly local to the loop and regains its former value upon exiting
528 the loop. If the variable was previously declared with C<my>, it uses
529 that variable instead of the global one, but it's still localized to
530 the loop. This implicit localization occurs I<only> in a C<foreach>
534 The C<foreach> keyword is actually a synonym for the C<for> keyword, so
535 you can use either. If VAR is omitted, C<$_> is set to each value.
538 If any element of LIST is an lvalue, you can modify it by modifying
539 VAR inside the loop. Conversely, if any element of LIST is NOT an
540 lvalue, any attempt to modify that element will fail. In other words,
541 the C<foreach> loop index variable is an implicit alias for each item
542 in the list that you're looping over.
545 If any part of LIST is an array, C<foreach> will get very confused if
546 you add or remove elements within the loop body, for example with
547 C<splice>. So don't do that.
550 C<foreach> probably won't do what you expect if VAR is a tied or other
551 special variable. Don't do that either.
553 As of Perl 5.22, there is an experimental variant of this loop that accepts
554 a variable preceded by a backslash for VAR, in which case the items in the
555 LIST must be references. The backslashed variable will become an alias
556 to each referenced item in the LIST, which must be of the correct type.
557 The variable needn't be a scalar in this case, and the backslash may be
558 followed by C<my>. To use this form, you must enable the C<refaliasing>
559 feature via C<use feature>. (See L<feature>. See also L<perlref/Assigning
562 As of Perl 5.36, you can iterate over multiple values at a time.
563 You can only iterate with lexical scalars as the iterator variables - unlike
564 list assignment, it's not possible to use C<undef> to signify a value that
565 isn't wanted. This is a limitation of the current implementation, and might
566 be changed in the future.
568 If the size of the LIST is not an exact multiple of the number of iterator
569 variables, then on the last iteration the "excess" iterator variables are
570 aliases to C<undef>, as if the LIST had C<, undef> appended as many times as
571 needed for its length to become an exact multiple. This happens whether
572 LIST is a literal LIST or an array - ie arrays are not extended if their
573 size is not a multiple of the iteration size, consistent with iterating an
574 array one-at-a-time. As these padding elements are not lvalues, attempting
575 to modify them will fail, consistent with the behaviour when iterating a
576 list with literal C<undef>s. If this is not the behaviour you desire, then
577 before the loop starts either explicitly extend your array to be an exact
578 multiple, or explicitly throw an exception.
582 for (@ary) { s/foo/bar/ }
584 for my $elem (@elements) {
588 for $count (reverse(1..10), "BOOM") {
593 for (1..15) { print "Merry Christmas\n"; }
595 foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
596 print "Item: $item\n";
599 use feature "refaliasing";
600 no warnings "experimental::refaliasing";
601 foreach \my %hash (@array_of_hash_references) {
602 # do something with each %hash
605 foreach my ($foo, $bar, $baz) (@list) {
606 # do something three-at-a-time
609 foreach my ($key, $value) (%hash) {
610 # iterate over the hash
611 # The hash is immediately copied to a flat list before the loop
612 # starts. The list contains copies of keys but aliases of values.
613 # This is the same behaviour as for $var (%hash) {...}
616 Here's how a C programmer might code up a particular algorithm in Perl:
618 for (my $i = 0; $i < @ary1; $i++) {
619 for (my $j = 0; $j < @ary2; $j++) {
620 if ($ary1[$i] > $ary2[$j]) {
621 last; # can't go to outer :-(
623 $ary1[$i] += $ary2[$j];
625 # this is where that last takes me
628 Whereas here's how a Perl programmer more comfortable with the idiom might
631 OUTER: for my $wid (@ary1) {
632 INNER: for my $jet (@ary2) {
633 next OUTER if $wid > $jet;
638 See how much easier this is? It's cleaner, safer, and faster. It's
639 cleaner because it's less noisy. It's safer because if code gets added
640 between the inner and outer loops later on, the new code won't be
641 accidentally executed. The C<next> explicitly iterates the other loop
642 rather than merely terminating the inner one. And it's faster because
643 Perl executes a C<foreach> statement more rapidly than it would the
644 equivalent C-style C<for> loop.
646 Perceptive Perl hackers may have noticed that a C<for> loop has a return
647 value, and that this value can be captured by wrapping the loop in a C<do>
648 block. The reward for this discovery is this cautionary advice: The
649 return value of a C<for> loop is unspecified and may change without notice.
652 =head2 Try Catch Exception Handling
653 X<try> X<catch> X<finally>
655 The C<try>/C<catch> syntax provides control flow relating to exception
656 handling. The C<try> keyword introduces a block which will be executed when it
657 is encountered, and the C<catch> block provides code to handle any exception
658 that may be thrown by the first.
661 my $x = call_a_function();
662 $x < 100 or die "Too big";
666 warn "Unable to output a value; $e";
670 Here, the body of the C<catch> block (i.e. the C<warn> statement) will be
671 executed if the initial block invokes the conditional C<die>, or if either of
672 the functions it invokes throws an uncaught exception. The C<catch> block can
673 inspect the C<$e> lexical variable in this case to see what the exception was.
674 If no exception was thrown then the C<catch> block does not happen. In either
675 case, execution will then continue from the following statement - in this
676 example the C<print>.
678 The C<catch> keyword must be immediately followed by a variable declaration in
679 parentheses, which introduces a new variable visible to the body of the
680 subsequent block. Inside the block this variable will contain the exception
681 value that was thrown by the code in the C<try> block. It is not necessary
682 to use the C<my> keyword to declare this variable; this is implied (similar
683 as it is for subroutine signatures).
685 Both the C<try> and the C<catch> blocks are permitted to contain control-flow
686 expressions, such as C<return>, C<goto>, or C<next>/C<last>/C<redo>. In all
687 cases they behave as expected without warnings. In particular, a C<return>
688 expression inside the C<try> block will make its entire containing function
689 return - this is in contrast to its behaviour inside an C<eval> block, where
690 it would only make that block return.
692 Like other control-flow syntax, C<try> and C<catch> will yield the last
693 evaluated value when placed as the final statement in a function or a C<do>
694 block. This permits the syntax to be used to create a value. In this case
695 remember not to use the C<return> expression, or that will cause the
696 containing function to return.
703 warn "Unable to get thing - $e";
708 As with other control-flow syntax, C<try> blocks are not visible to
709 C<caller()> (just as for example, C<while> or C<foreach> loops are not).
710 Successive levels of the C<caller> result can see subroutine calls and
711 C<eval> blocks, because those affect the way that C<return> would work. Since
712 C<try> blocks do not intercept C<return>, they are not of interest to
715 The C<try> and C<catch> blocks may optionally be followed by a third block
716 introduced by the C<finally> keyword. This third block is executed after the
717 rest of the construct has finished.
723 warn "Unable to call; $e";
729 The C<finally> block is equivalent to using a C<defer> block and will be
730 invoked in the same situations; whether the C<try> block completes
731 successfully, throws an exception, or transfers control elsewhere by using
732 C<return>, a loop control, or C<goto>.
734 Unlike the C<try> and C<catch> blocks, a C<finally> block is not permitted to
735 C<return>, C<goto> or use any loop controls. The final expression value is
736 ignored, and does not affect the return value of the containing function even
737 if it is placed last in the function.
739 This syntax is currently experimental and must be enabled with
740 C<use feature 'try'>. It emits a warning in the C<experimental::try> category.
745 A BLOCK by itself (labeled or not) is semantically equivalent to a
746 loop that executes once. Thus you can use any of the loop control
747 statements in it to leave or restart the block. (Note that this is
748 I<NOT> true in C<eval{}>, C<sub{}>, or contrary to popular belief
749 C<do{}> blocks, which do I<NOT> count as loops.) The C<continue>
752 The BLOCK construct can be used to emulate case structures.
755 if (/^abc/) { $abc = 1; last SWITCH; }
756 if (/^def/) { $def = 1; last SWITCH; }
757 if (/^xyz/) { $xyz = 1; last SWITCH; }
761 You'll also find that C<foreach> loop used to create a topicalizer
766 if (/^abc/) { $abc = 1; last SWITCH; }
767 if (/^def/) { $def = 1; last SWITCH; }
768 if (/^xyz/) { $xyz = 1; last SWITCH; }
772 Such constructs are quite frequently used, both because older versions of
773 Perl had no official C<switch> statement, and also because the new version
774 described immediately below remains experimental and can sometimes be confusing.
779 A block prefixed by the C<defer> modifier provides a section of code which
780 runs at a later time during scope exit.
782 A C<defer> block can appear at any point where a regular block or other
783 statement is permitted. If the flow of execution reaches this statement, the
784 body of the block is stored for later, but not invoked immediately. When the
785 flow of control leaves the containing block for any reason, this stored block
786 is executed on the way past. It provides a means of deferring execution until
787 a later time. This acts similarly to syntax provided by some other languages,
788 often using keywords named C<try / finally>.
790 This syntax is available if enabled by the C<defer> named feature, and is
791 currently experimental. If experimental warnings are enabled it will emit a
797 say "This happens first";
798 defer { say "This happens last"; }
800 say "And this happens inbetween";
803 If multiple C<defer> blocks are contained in a single scope, they are
804 executed in LIFO order; the last one reached is the first one executed.
806 The code stored by the C<defer> block will be invoked when control leaves
807 its containing block due to regular fallthrough, explicit C<return>,
808 exceptions thrown by C<die> or propagated by functions called by it, C<goto>,
809 or any of the loop control statements C<next>, C<last> or C<redo>.
811 If the flow of control does not reach the C<defer> statement itself then its
812 body is not stored for later execution. (This is in direct contrast to the
813 code provided by an C<END> phaser block, which is always enqueued by the
814 compiler, regardless of whether execution ever reached the line it was given
820 defer { say "This will run"; }
822 defer { say "This will not"; }
825 Exceptions thrown by code inside a C<defer> block will propagate to the
826 caller in the same way as any other exception thrown by normal code.
828 If the C<defer> block is being executed due to a thrown exception and throws
829 another one it is not specified what happens, beyond that the caller will
830 definitely receive an exception.
832 Besides throwing an exception, a C<defer> block is not permitted to
833 otherwise alter the control flow of its surrounding code. In particular, it
834 may not cause its containing function to C<return>, nor may it C<goto> a
835 label, or control a containing loop using C<next>, C<last> or C<redo>. These
836 constructions are however, permitted entirely within the body of the
844 last if $_ == 3; # this is permitted
850 foreach ( 6 .. 10 ) {
852 last if $_ == 8; # this is not
857 =head2 Switch Statements
859 X<switch> X<case> X<given> X<when> X<default>
861 Starting from Perl 5.10.1 (well, 5.10.0, but it didn't work
864 use feature "switch";
866 to enable an experimental switch feature. This is loosely based on an
867 old version of a Raku proposal, but it no longer resembles the Raku
868 construct. You also get the switch feature whenever you declare that your
869 code prefers to run under a version of Perl between 5.10 and 5.34. For
874 Under the "switch" feature, Perl gains the experimental keywords
875 C<given>, C<when>, C<default>, C<continue>, and C<break>.
876 Starting from Perl 5.16, one can prefix the switch
877 keywords with C<CORE::> to access the feature without a C<use feature>
878 statement. The keywords C<given> and
879 C<when> are analogous to C<switch> and
880 C<case> in other languages -- though C<continue> is not -- so the code
881 in the previous section could be rewritten as
885 when (/^abc/) { $abc = 1 }
886 when (/^def/) { $def = 1 }
887 when (/^xyz/) { $xyz = 1 }
888 default { $nothing = 1 }
891 The C<foreach> is the non-experimental way to set a topicalizer.
892 If you wish to use the highly experimental C<given>, that could be
897 when (/^abc/) { $abc = 1 }
898 when (/^def/) { $def = 1 }
899 when (/^xyz/) { $xyz = 1 }
900 default { $nothing = 1 }
903 As of 5.14, that can also be written this way:
907 $abc = 1 when /^abc/;
908 $def = 1 when /^def/;
909 $xyz = 1 when /^xyz/;
910 default { $nothing = 1 }
913 Or if you don't care to play it safe, like this:
917 $abc = 1 when /^abc/;
918 $def = 1 when /^def/;
919 $xyz = 1 when /^xyz/;
920 default { $nothing = 1 }
923 The arguments to C<given> and C<when> are in scalar context,
924 and C<given> assigns the C<$_> variable its topic value.
926 Exactly what the I<EXPR> argument to C<when> does is hard to describe
927 precisely, but in general, it tries to guess what you want done. Sometimes
928 it is interpreted as C<< $_ ~~ I<EXPR> >>, and sometimes it is not. It
929 also behaves differently when lexically enclosed by a C<given> block than
930 it does when dynamically enclosed by a C<foreach> loop. The rules are far
931 too difficult to understand to be described here. See L</"Experimental Details
932 on given and when"> later on.
934 Due to an unfortunate bug in how C<given> was implemented between Perl 5.10
935 and 5.16, under those implementations the version of C<$_> governed by
936 C<given> is merely a lexically scoped copy of the original, not a
937 dynamically scoped alias to the original, as it would be if it were a
938 C<foreach> or under both the original and the current Raku language
939 specification. This bug was fixed in Perl 5.18 (and lexicalized C<$_> itself
940 was removed in Perl 5.24).
942 If your code still needs to run on older versions,
943 stick to C<foreach> for your topicalizer and
944 you will be less unhappy.
949 Although not for the faint of heart, Perl does support a C<goto>
950 statement. There are three forms: C<goto>-LABEL, C<goto>-EXPR, and
951 C<goto>-&NAME. A loop's LABEL is not actually a valid target for
952 a C<goto>; it's just the name of the loop.
954 The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
955 execution there. It may not be used to go into any construct that
956 requires initialization, such as a subroutine or a C<foreach> loop. It
957 also can't be used to go into a construct that is optimized away. It
958 can be used to go almost anywhere else within the dynamic scope,
959 including out of subroutines, but it's usually better to use some other
960 construct such as C<last> or C<die>. The author of Perl has never felt the
961 need to use this form of C<goto> (in Perl, that is--C is another matter).
963 The C<goto>-EXPR form expects a label name, whose scope will be resolved
964 dynamically. This allows for computed C<goto>s per FORTRAN, but isn't
965 necessarily recommended if you're optimizing for maintainability:
967 goto(("FOO", "BAR", "GLARCH")[$i]);
969 The C<goto>-&NAME form is highly magical, and substitutes a call to the
970 named subroutine for the currently running subroutine. This is used by
971 C<AUTOLOAD()> subroutines that wish to load another subroutine and then
972 pretend that the other subroutine had been called in the first place
973 (except that any modifications to C<@_> in the current subroutine are
974 propagated to the other subroutine.) After the C<goto>, not even C<caller()>
975 will be able to tell that this routine was called first.
977 In almost all cases like this, it's usually a far, far better idea to use the
978 structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of
979 resorting to a C<goto>. For certain applications, the catch and throw pair of
980 C<eval{}> and die() for exception processing can also be a prudent approach.
982 =head2 The Ellipsis Statement
986 X<elliptical statement>
987 X<unimplemented statement>
988 X<unimplemented operator>
990 X<yada-yada operator>
993 X<triple-dot operator>
995 Beginning in Perl 5.12, Perl accepts an ellipsis, "C<...>", as a
996 placeholder for code that you haven't implemented yet.
997 When Perl 5.12 or later encounters an ellipsis statement, it parses this
998 without error, but if and when you should actually try to execute it, Perl
999 throws an exception with the text C<Unimplemented>:
1002 sub unimplemented { ... }
1003 eval { unimplemented() };
1004 if ($@ =~ /^Unimplemented at /) {
1005 say "I found an ellipsis!";
1008 You can only use the elliptical statement to stand in for a complete
1009 statement. Syntactically, "C<...;>" is a complete statement, but,
1010 as with other kinds of semicolon-terminated statement, the semicolon
1011 may be omitted if "C<...>" appears immediately before a closing brace.
1012 These examples show how the ellipsis works:
1030 The elliptical statement cannot stand in for an expression that
1031 is part of a larger statement.
1032 These examples of attempts to use an ellipsis are syntax errors:
1037 open(my $fh, ">", "/dev/passwd") or ...;
1038 if ($condition && ... ) { say "Howdy" };
1040 say "Cromulent" if ...;
1043 There are some cases where Perl can't immediately tell the difference
1044 between an expression and a statement. For instance, the syntax for a
1045 block and an anonymous hash reference constructor look the same unless
1046 there's something in the braces to give Perl a hint. The ellipsis is a
1047 syntax error if Perl doesn't guess that the C<{ ... }> is a block.
1048 Inside your block, you can use a C<;> before the ellipsis to denote that the
1049 C<{ ... }> is a block and not a hash reference constructor.
1051 Note: Some folks colloquially refer to this bit of punctuation as a
1052 "yada-yada" or "triple-dot", but its true name
1053 is actually an ellipsis.
1055 =head2 PODs: Embedded Documentation
1056 X<POD> X<documentation>
1058 Perl has a mechanism for intermixing documentation with source code.
1059 While it's expecting the beginning of a new statement, if the compiler
1060 encounters a line that begins with an equal sign and a word, like this
1062 =head1 Here There Be Pods!
1064 Then that text and all remaining text up through and including a line
1065 beginning with C<=cut> will be ignored. The format of the intervening
1066 text is described in L<perlpod>.
1068 This allows you to intermix your source code
1069 and your documentation text freely, as in
1073 The snazzle() function will behave in the most spectacular
1074 form that you can possibly imagine, not even excepting
1075 cybernetic pyrotechnics.
1077 =cut back to the compiler, nuff of this pod stuff!
1080 my $thingie = shift;
1084 Note that pod translators should look at only paragraphs beginning
1085 with a pod directive (it makes parsing easier), whereas the compiler
1086 actually knows to look for pod escapes even in the middle of a
1087 paragraph. This means that the following secret stuff will be
1088 ignored by both the compiler and the translators.
1092 warn "Neither POD nor CODE!?"
1096 You probably shouldn't rely upon the C<warn()> being podded out forever.
1097 Not all pod translators are well-behaved in this regard, and perhaps
1098 the compiler will become pickier.
1100 One may also use pod directives to quickly comment out a section
1103 =head2 Plain Old Comments (Not!)
1104 X<comment> X<line> X<#> X<preprocessor> X<eval>
1106 Perl can process line directives, much like the C preprocessor. Using
1107 this, one can control Perl's idea of filenames and line numbers in
1108 error or warning messages (especially for strings that are processed
1109 with C<eval()>). The syntax for this mechanism is almost the same as for
1110 most C preprocessors: it matches the regular expression
1112 # example: '# line 42 "new_filename.plx"'
1115 (?:\s("?)([^"]+)\g2)? \s*
1118 with C<$1> being the line number for the next line, and C<$3> being
1119 the optional filename (specified with or without quotes). Note that
1120 no whitespace may precede the C<< # >>, unlike modern C preprocessors.
1122 There is a fairly obvious gotcha included with the line directive:
1123 Debuggers and profilers will only show the last source line to appear
1124 at a particular line number in a given file. Care should be taken not
1125 to cause line number collisions in code you'd like to debug later.
1127 Here are some examples that you should be able to type into your command
1132 # the '#' on the previous line must be the first char on line
1135 foo at bzzzt line 201.
1139 eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
1144 eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
1146 foo at foo bar line 200.
1150 eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
1153 foo at goop line 345.
1155 =head2 Experimental Details on given and when
1157 As previously mentioned, the "switch" feature is considered highly
1158 experimental; it is subject to change with little notice. In particular,
1159 C<when> has tricky behaviours that are expected to change to become less
1160 tricky in the future. Do not rely upon its current (mis)implementation.
1161 Before Perl 5.18, C<given> also had tricky behaviours that you should still
1162 beware of if your code must run on older versions of Perl.
1164 Here is a longer example of C<given>:
1166 use feature ":5.10";
1169 say '$foo is undefined';
1172 say '$foo is the string "foo"';
1174 when ([1,3,5,7,9]) {
1175 say '$foo is an odd digit';
1176 continue; # Fall through
1179 say '$foo is numerically less than 100';
1181 when (\&complicated_check) {
1182 say 'a complicated check for $foo is true';
1185 die q(I don't know what to do with $foo);
1189 Before Perl 5.18, C<given(EXPR)> assigned the value of I<EXPR> to
1190 merely a lexically scoped I<B<copy>> (!) of C<$_>, not a dynamically
1191 scoped alias the way C<foreach> does. That made it similar to
1193 do { my $_ = EXPR; ... }
1195 except that the block was automatically broken out of by a successful
1196 C<when> or an explicit C<break>. Because it was only a copy, and because
1197 it was only lexically scoped, not dynamically scoped, you could not do the
1198 things with it that you are used to in a C<foreach> loop. In particular,
1199 it did not work for arbitrary function calls if those functions might try
1200 to access $_. Best stick to C<foreach> for that.
1202 Most of the power comes from the implicit smartmatching that can
1203 sometimes apply. Most of the time, C<when(EXPR)> is treated as an
1204 implicit smartmatch of C<$_>, that is, C<$_ ~~ EXPR>. (See
1205 L<perlop/"Smartmatch Operator"> for more information on smartmatching.)
1206 But when I<EXPR> is one of the 10 exceptional cases (or things like them)
1207 listed below, it is used directly as a boolean.
1213 A user-defined subroutine call or a method invocation.
1217 A regular expression match in the form of C</REGEX/>, C<$foo =~ /REGEX/>,
1218 or C<$foo =~ EXPR>. Also, a negated regular expression match in
1219 the form C<!/REGEX/>, C<$foo !~ /REGEX/>, or C<$foo !~ EXPR>.
1223 A smart match that uses an explicit C<~~> operator, such as C<EXPR ~~ EXPR>.
1225 B<NOTE:> You will often have to use C<$c ~~ $_> because the default case
1226 uses C<$_ ~~ $c> , which is frequently the opposite of what you want.
1230 A boolean comparison operator such as C<$_ E<lt> 10> or C<$x eq "abc">. The
1231 relational operators that this applies to are the six numeric comparisons
1232 (C<< < >>, C<< > >>, C<< <= >>, C<< >= >>, C<< == >>, and C<< != >>), and
1233 the six string comparisons (C<lt>, C<gt>, C<le>, C<ge>, C<eq>, and C<ne>).
1237 At least the three builtin functions C<defined(...)>, C<exists(...)>, and
1238 C<eof(...)>. We might someday add more of these later if we think of them.
1242 A negated expression, whether C<!(EXPR)> or C<not(EXPR)>, or a logical
1243 exclusive-or, C<(EXPR1) xor (EXPR2)>. The bitwise versions (C<~> and C<^>)
1248 A filetest operator, with exactly 4 exceptions: C<-s>, C<-M>, C<-A>, and
1249 C<-C>, as these return numerical values, not boolean ones. The C<-z>
1250 filetest operator is not included in the exception list.
1254 The C<..> and C<...> flip-flop operators. Note that the C<...> flip-flop
1255 operator is completely different from the C<...> elliptical statement
1260 In those 8 cases above, the value of EXPR is used directly as a boolean, so
1261 no smartmatching is done. You may think of C<when> as a smartsmartmatch.
1263 Furthermore, Perl inspects the operands of logical operators to
1264 decide whether to use smartmatching for each one by applying the
1265 above test to the operands:
1271 If EXPR is C<EXPR1 && EXPR2> or C<EXPR1 and EXPR2>, the test is applied
1272 I<recursively> to both EXPR1 and EXPR2.
1273 Only if I<both> operands also pass the
1274 test, I<recursively>, will the expression be treated as boolean. Otherwise,
1275 smartmatching is used.
1279 If EXPR is C<EXPR1 || EXPR2>, C<EXPR1 // EXPR2>, or C<EXPR1 or EXPR2>, the
1280 test is applied I<recursively> to EXPR1 only (which might itself be a
1281 higher-precedence AND operator, for example, and thus subject to the
1282 previous rule), not to EXPR2. If EXPR1 is to use smartmatching, then EXPR2
1283 also does so, no matter what EXPR2 contains. But if EXPR2 does not get to
1284 use smartmatching, then the second argument will not be either. This is
1285 quite different from the C<&&> case just described, so be careful.
1289 These rules are complicated, but the goal is for them to do what you want
1290 (even if you don't quite understand why they are doing it). For example:
1292 when (/^\d+$/ && $_ < 75) { ... }
1294 will be treated as a boolean match because the rules say both
1295 a regex match and an explicit test on C<$_> will be treated
1300 when ([qw(foo bar)] && /baz/) { ... }
1302 will use smartmatching because only I<one> of the operands is a boolean:
1303 the other uses smartmatching, and that wins.
1307 when ([qw(foo bar)] || /^baz/) { ... }
1309 will use smart matching (only the first operand is considered), whereas
1311 when (/^baz/ || [qw(foo bar)]) { ... }
1313 will test only the regex, which causes both operands to be
1314 treated as boolean. Watch out for this one, then, because an
1315 arrayref is always a true value, which makes it effectively
1316 redundant. Not a good idea.
1318 Tautologous boolean operators are still going to be optimized
1319 away. Don't be tempted to write
1321 when ("foo" or "bar") { ... }
1323 This will optimize down to C<"foo">, so C<"bar"> will never be considered (even
1324 though the rules say to use a smartmatch
1325 on C<"foo">). For an alternation like
1326 this, an array ref will work, because this will instigate smartmatching:
1328 when ([qw(foo bar)] { ... }
1330 This is somewhat equivalent to the C-style switch statement's fallthrough
1331 functionality (not to be confused with I<Perl's> fallthrough
1332 functionality--see below), wherein the same block is used for several
1335 Another useful shortcut is that, if you use a literal array or hash as the
1336 argument to C<given>, it is turned into a reference. So C<given(@foo)> is
1337 the same as C<given(\@foo)>, for example.
1339 C<default> behaves exactly like C<when(1 == 1)>, which is
1340 to say that it always matches.
1344 You can use the C<break> keyword to break out of the enclosing
1345 C<given> block. Every C<when> block is implicitly ended with
1350 You can use the C<continue> keyword to fall through from one
1351 case to the next immediate C<when> or C<default>:
1354 when (/x/) { say '$foo contains an x'; continue }
1355 when (/y/) { say '$foo contains a y' }
1356 default { say '$foo does not contain a y' }
1361 When a C<given> statement is also a valid expression (for example,
1362 when it's the last statement of a block), it evaluates to:
1368 An empty list as soon as an explicit C<break> is encountered.
1372 The value of the last evaluated expression of the successful
1373 C<when>/C<default> clause, if there happens to be one.
1377 The value of the last evaluated expression of the C<given> block if no
1382 In both last cases, the last expression is evaluated in the context that
1383 was applied to the C<given> block.
1385 Note that, unlike C<if> and C<unless>, failed C<when> statements always
1386 evaluate to an empty list.
1390 when (["pear", "apple"]) { 1 }
1391 break when "vote"; # My vote cannot be bought
1392 1e10 when /Mona Lisa/;
1397 Currently, C<given> blocks can't always
1398 be used as proper expressions. This
1399 may be addressed in a future version of Perl.
1401 =head3 Switching in a loop
1403 Instead of using C<given()>, you can use a C<foreach()> loop.
1404 For example, here's one way to count how many times a particular
1405 string occurs in an array:
1410 when ("foo") { ++$count }
1412 print "\@array contains $count copies of 'foo'\n";
1414 Or in a more recent version:
1419 ++$count when "foo";
1421 print "\@array contains $count copies of 'foo'\n";
1423 At the end of all C<when> blocks, there is an implicit C<next>.
1424 You can override that with an explicit C<last> if you're
1425 interested in only the first match alone.
1427 This doesn't work if you explicitly specify a loop variable, as
1428 in C<for $item (@array)>. You have to use the default variable C<$_>.
1430 =head3 Differences from Raku
1432 The Perl 5 smartmatch and C<given>/C<when> constructs are not compatible
1433 with their Raku analogues. The most visible difference and least
1434 important difference is that, in Perl 5, parentheses are required around
1435 the argument to C<given()> and C<when()> (except when this last one is used
1436 as a statement modifier). Parentheses in Raku are always optional in a
1437 control construct such as C<if()>, C<while()>, or C<when()>; they can't be
1438 made optional in Perl 5 without a great deal of potential confusion,
1439 because Perl 5 would parse the expression
1445 as though the argument to C<given> were an element of the hash
1446 C<%foo>, interpreting the braces as hash-element syntax.
1448 However, their are many, many other differences. For example,
1449 this works in Perl 5:
1452 my @primary = ("red", "blue", "green");
1454 if (@primary ~~ "red") {
1455 say "primary smartmatches red";
1458 if ("red" ~~ @primary) {
1459 say "red smartmatches primary";
1462 say "that's all, folks!";
1464 But it doesn't work at all in Raku. Instead, you should
1465 use the (parallelizable) C<any> operator:
1467 if any(@primary) eq "red" {
1468 say "primary smartmatches red";
1471 if "red" eq any(@primary) {
1472 say "red smartmatches primary";
1475 The table of smartmatches in L<perlop/"Smartmatch Operator"> is not
1476 identical to that proposed by the Raku specification, mainly due to
1477 differences between Raku's and Perl 5's data models, but also because
1478 the Raku spec has changed since Perl 5 rushed into early adoption.
1480 In Raku, C<when()> will always do an implicit smartmatch with its
1481 argument, while in Perl 5 it is convenient (albeit potentially confusing) to
1482 suppress this implicit smartmatch in various rather loosely-defined
1483 situations, as roughly outlined above. (The difference is largely because
1484 Perl 5 does not have, even internally, a boolean type.)