Removal of a bunch of changes that don't merit perldelta integration
[perl.git] / pod / perlsyn.pod
1 =head1 NAME
2 X<syntax>
3
4 perlsyn - Perl syntax
5
6 =head1 DESCRIPTION
7
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.
11
12 Perl is a B<free-form> language, you can format and indent it however
13 you like.  Whitespace mostly serves to separate tokens, unlike
14 languages like Python where it is an important part of the syntax.
15
16 Many of Perl's syntactic elements are B<optional>.  Rather than
17 requiring you to put parentheses around every function call and
18 declare every variable, you can often leave such explicit elements off
19 and Perl will figure out what you meant.  This is known as B<Do What I
20 Mean>, abbreviated B<DWIM>.  It allows programmers to be B<lazy> and to
21 code in a style with which they are comfortable.
22
23 Perl B<borrows syntax> and concepts from many languages: awk, sed, C,
24 Bourne Shell, Smalltalk, Lisp and even English.  Other
25 languages have borrowed syntax from Perl, particularly its regular
26 expression extensions.  So if you have programmed in another language
27 you will see familiar pieces in Perl.  They often work the same, but
28 see L<perltrap> for information about how they differ.
29
30 =head2 Declarations
31 X<declaration> X<undef> X<undefined> X<uninitialized>
32
33 The only things you need to declare in Perl are report formats and
34 subroutines (and sometimes not even subroutines).  A variable holds
35 the undefined value (C<undef>) until it has been assigned a defined
36 value, which is anything other than C<undef>.  When used as a number,
37 C<undef> is treated as C<0>; when used as a string, it is treated as
38 the empty string, C<"">; and when used as a reference that isn't being
39 assigned to, it is treated as an error.  If you enable warnings,
40 you'll be notified of an uninitialized value whenever you treat
41 C<undef> as a string or a number.  Well, usually.  Boolean contexts,
42 such as:
43
44     my $a;
45     if ($a) {}
46
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 left values such as:
50
51     my $a;
52     $a++;
53
54 are also always exempt from such warnings.
55
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.  Typically all the declarations are 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()>, you'll
61 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.
64
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>
69
70     sub myname;
71     $me = myname $0             or die "can't get myname";
72
73 Note that myname() functions as a list operator, not as a unary operator;
74 so be careful to use C<or> instead of C<||> in this case.  However, if
75 you were to declare the subroutine as C<sub myname ($)>, then
76 C<myname> would function as a unary operator, so either C<or> or
77 C<||> would work.
78
79 Subroutines declarations can also be loaded up with the C<require> statement
80 or both loaded and imported into your namespace with a C<use> statement.
81 See L<perlmod> for details on this.
82
83 A statement sequence may contain declarations of lexically-scoped
84 variables, but apart from declaring a variable name, the declaration acts
85 like an ordinary statement, and is elaborated within the sequence of
86 statements as if it were an ordinary statement.  That means it actually
87 has both compile-time and run-time effects.
88
89 =head2 Comments
90 X<comment> X<#>
91
92 Text from a C<"#"> character until the end of the line is a comment,
93 and is ignored.  Exceptions include C<"#"> inside a string or regular
94 expression.
95
96 =head2 Simple Statements
97 X<statement> X<semicolon> X<expression> X<;>
98
99 The only kind of simple statement is an expression evaluated for its
100 side effects.  Every simple statement must be terminated with a
101 semicolon, unless it is the final statement in a block, in which case
102 the semicolon is optional.  (A semicolon is still encouraged if the
103 block takes up more than one line, because you may eventually add
104 another line.)  Note that there are some operators like C<eval {}> and
105 C<do {}> that look like compound statements, but aren't (they're just
106 TERMs in an expression), and thus need an explicit termination if used
107 as the last item in a statement.
108
109 =head2 Truth and Falsehood
110 X<truth> X<falsehood> X<true> X<false> X<!> X<not> X<negation> X<0>
111
112 The number 0, the strings C<'0'> and C<''>, the empty list C<()>, and
113 C<undef> are all false in a boolean context. All other values are true.
114 Negation of a true value by C<!> or C<not> returns a special false value.
115 When evaluated as a string it is treated as C<''>, but as a number, it
116 is treated as 0.
117
118 =head2 Statement Modifiers
119 X<statement modifier> X<modifier> X<if> X<unless> X<while>
120 X<until> X<when> X<foreach> X<for>
121
122 Any simple statement may optionally be followed by a I<SINGLE> modifier,
123 just before the terminating semicolon (or block ending).  The possible
124 modifiers are:
125
126     if EXPR
127     unless EXPR
128     while EXPR
129     until EXPR
130     when EXPR
131     for LIST
132     foreach LIST
133
134 The C<EXPR> following the modifier is referred to as the "condition".
135 Its truth or falsehood determines how the modifier will behave.
136
137 C<if> executes the statement once I<if> and only if the condition is
138 true.  C<unless> is the opposite, it executes the statement I<unless>
139 the condition is true (i.e., if the condition is false).
140
141     print "Basset hounds got long ears" if length $ear >= 10;
142     go_outside() and play() unless $is_raining;
143
144 C<when> executes the statement I<when> C<$_> smart matches C<EXPR>, and
145 then either C<break>s out if it's enclosed in a C<given> scope or skips
146 to the C<next> element when it lies directly inside a C<for> loop.
147 See also L</"Switch statements">.
148
149     given ($something) {
150         $abc    = 1 when /^abc/;
151         $just_a = 1 when /^a/;
152         $other  = 1;
153     }
154
155     for (@names) {
156         admin($_)   when [ qw/Alice Bob/ ];
157         regular($_) when [ qw/Chris David Ellen/ ];
158     }
159
160 The C<foreach> modifier is an iterator: it executes the statement once
161 for each item in the LIST (with C<$_> aliased to each item in turn).
162
163     print "Hello $_!\n" foreach qw(world Dolly nurse);
164
165 C<while> repeats the statement I<while> the condition is true.
166 C<until> does the opposite, it repeats the statement I<until> the
167 condition is true (or while the condition is false):
168
169     # Both of these count from 0 to 10.
170     print $i++ while $i <= 10;
171     print $j++ until $j >  10;
172
173 The C<while> and C<until> modifiers have the usual "C<while> loop"
174 semantics (conditional evaluated first), except when applied to a
175 C<do>-BLOCK (or to the deprecated C<do>-SUBROUTINE statement), in
176 which case the block executes once before the conditional is
177 evaluated.  This is so that you can write loops like:
178
179     do {
180         $line = <STDIN>;
181         ...
182     } until $line  eq ".\n";
183
184 See L<perlfunc/do>.  Note also that the loop control statements described
185 later will I<NOT> work in this construct, because modifiers don't take
186 loop labels.  Sorry.  You can always put another block inside of it
187 (for C<next>) or around it (for C<last>) to do that sort of thing.
188 For C<next>, just double the braces:
189 X<next> X<last> X<redo>
190
191     do {{
192         next if $x == $y;
193         # do something here
194     }} until $x++ > $z;
195
196 For C<last>, you have to be more elaborate:
197 X<last>
198
199     LOOP: { 
200             do {
201                 last if $x = $y**2;
202                 # do something here
203             } while $x++ <= $z;
204     }
205
206 B<NOTE:> The behaviour of a C<my> statement modified with a statement
207 modifier conditional or loop construct (e.g. C<my $x if ...>) is
208 B<undefined>.  The value of the C<my> variable may be C<undef>, any
209 previously assigned value, or possibly anything else.  Don't rely on
210 it.  Future versions of perl might do something different from the
211 version of perl you try it out on.  Here be dragons.
212 X<my>
213
214 =head2 Compound Statements
215 X<statement, compound> X<block> X<bracket, curly> X<curly bracket> X<brace>
216 X<{> X<}> X<if> X<unless> X<while> X<until> X<foreach> X<for> X<continue>
217
218 In Perl, a sequence of statements that defines a scope is called a block.
219 Sometimes a block is delimited by the file containing it (in the case
220 of a required file, or the program as a whole), and sometimes a block
221 is delimited by the extent of a string (in the case of an eval).
222
223 But generally, a block is delimited by curly brackets, also known as braces.
224 We will call this syntactic construct a BLOCK.
225
226 The following compound statements may be used to control flow:
227
228     if (EXPR) BLOCK
229     if (EXPR) BLOCK else BLOCK
230     if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
231     LABEL while (EXPR) BLOCK
232     LABEL while (EXPR) BLOCK continue BLOCK
233     LABEL until (EXPR) BLOCK
234     LABEL until (EXPR) BLOCK continue BLOCK
235     LABEL for (EXPR; EXPR; EXPR) BLOCK
236     LABEL foreach VAR (LIST) BLOCK
237     LABEL foreach VAR (LIST) BLOCK continue BLOCK
238     LABEL BLOCK continue BLOCK
239
240 Note that, unlike C and Pascal, these are defined in terms of BLOCKs,
241 not statements.  This means that the curly brackets are I<required>--no
242 dangling statements allowed.  If you want to write conditionals without
243 curly brackets there are several other ways to do it.  The following
244 all do the same thing:
245
246     if (!open(FOO)) { die "Can't open $FOO: $!"; }
247     die "Can't open $FOO: $!" unless open(FOO);
248     open(FOO) or die "Can't open $FOO: $!";     # FOO or bust!
249     open(FOO) ? 'hi mom' : die "Can't open $FOO: $!";
250                         # a bit exotic, that last one
251
252 The C<if> statement is straightforward.  Because BLOCKs are always
253 bounded by curly brackets, there is never any ambiguity about which
254 C<if> an C<else> goes with.  If you use C<unless> in place of C<if>,
255 the sense of the test is reversed.
256
257 The C<while> statement executes the block as long as the expression is
258 L<true|/"Truth and Falsehood">.
259 The C<until> statement executes the block as long as the expression is
260 false.
261 The LABEL is optional, and if present, consists of an identifier followed
262 by a colon.  The LABEL identifies the loop for the loop control
263 statements C<next>, C<last>, and C<redo>.
264 If the LABEL is omitted, the loop control statement
265 refers to the innermost enclosing loop.  This may include dynamically
266 looking back your call-stack at run time to find the LABEL.  Such
267 desperate behavior triggers a warning if you use the C<use warnings>
268 pragma or the B<-w> flag.
269
270 If there is a C<continue> BLOCK, it is always executed just before the
271 conditional is about to be evaluated again.  Thus it can be used to
272 increment a loop variable, even when the loop has been continued via
273 the C<next> statement.
274
275 =head2 Loop Control
276 X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue>
277
278 The C<next> command starts the next iteration of the loop:
279
280     LINE: while (<STDIN>) {
281         next LINE if /^#/;      # discard comments
282         ...
283     }
284
285 The C<last> command immediately exits the loop in question.  The
286 C<continue> block, if any, is not executed:
287
288     LINE: while (<STDIN>) {
289         last LINE if /^$/;      # exit when done with header
290         ...
291     }
292
293 The C<redo> command restarts the loop block without evaluating the
294 conditional again.  The C<continue> block, if any, is I<not> executed.
295 This command is normally used by programs that want to lie to themselves
296 about what was just input.
297
298 For example, when processing a file like F</etc/termcap>.
299 If your input lines might end in backslashes to indicate continuation, you
300 want to skip ahead and get the next record.
301
302     while (<>) {
303         chomp;
304         if (s/\\$//) {
305             $_ .= <>;
306             redo unless eof();
307         }
308         # now process $_
309     }
310
311 which is Perl short-hand for the more explicitly written version:
312
313     LINE: while (defined($line = <ARGV>)) {
314         chomp($line);
315         if ($line =~ s/\\$//) {
316             $line .= <ARGV>;
317             redo LINE unless eof(); # not eof(ARGV)!
318         }
319         # now process $line
320     }
321
322 Note that if there were a C<continue> block on the above code, it would
323 get executed only on lines discarded by the regex (since redo skips the
324 continue block). A continue block is often used to reset line counters
325 or C<?pat?> one-time matches:
326
327     # inspired by :1,$g/fred/s//WILMA/
328     while (<>) {
329         ?(fred)?    && s//WILMA $1 WILMA/;
330         ?(barney)?  && s//BETTY $1 BETTY/;
331         ?(homer)?   && s//MARGE $1 MARGE/;
332     } continue {
333         print "$ARGV $.: $_";
334         close ARGV  if eof();           # reset $.
335         reset       if eof();           # reset ?pat?
336     }
337
338 If the word C<while> is replaced by the word C<until>, the sense of the
339 test is reversed, but the conditional is still tested before the first
340 iteration.
341
342 The loop control statements don't work in an C<if> or C<unless>, since
343 they aren't loops.  You can double the braces to make them such, though.
344
345     if (/pattern/) {{
346         last if /fred/;
347         next if /barney/; # same effect as "last", but doesn't document as well
348         # do something here
349     }}
350
351 This is caused by the fact that a block by itself acts as a loop that
352 executes once, see L<"Basic BLOCKs">.
353
354 The form C<while/if BLOCK BLOCK>, available in Perl 4, is no longer
355 available.   Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>.
356
357 =head2 For Loops
358 X<for> X<foreach>
359
360 Perl's C-style C<for> loop works like the corresponding C<while> loop;
361 that means that this:
362
363     for ($i = 1; $i < 10; $i++) {
364         ...
365     }
366
367 is the same as this:
368
369     $i = 1;
370     while ($i < 10) {
371         ...
372     } continue {
373         $i++;
374     }
375
376 There is one minor difference: if variables are declared with C<my>
377 in the initialization section of the C<for>, the lexical scope of
378 those variables is exactly the C<for> loop (the body of the loop
379 and the control sections).
380 X<my>
381
382 Besides the normal array index looping, C<for> can lend itself
383 to many other interesting applications.  Here's one that avoids the
384 problem you get into if you explicitly test for end-of-file on
385 an interactive file descriptor causing your program to appear to
386 hang.
387 X<eof> X<end-of-file> X<end of file>
388
389     $on_a_tty = -t STDIN && -t STDOUT;
390     sub prompt { print "yes? " if $on_a_tty }
391     for ( prompt(); <STDIN>; prompt() ) {
392         # do something
393     }
394
395 Using C<readline> (or the operator form, C<< <EXPR> >>) as the
396 conditional of a C<for> loop is shorthand for the following.  This
397 behaviour is the same as a C<while> loop conditional.
398 X<readline> X<< <> >>
399
400     for ( prompt(); defined( $_ = <STDIN> ); prompt() ) {
401         # do something
402     }
403
404 =head2 Foreach Loops
405 X<for> X<foreach>
406
407 The C<foreach> loop iterates over a normal list value and sets the
408 variable VAR to be each element of the list in turn.  If the variable
409 is preceded with the keyword C<my>, then it is lexically scoped, and
410 is therefore visible only within the loop.  Otherwise, the variable is
411 implicitly local to the loop and regains its former value upon exiting
412 the loop.  If the variable was previously declared with C<my>, it uses
413 that variable instead of the global one, but it's still localized to
414 the loop.  This implicit localisation occurs I<only> in a C<foreach>
415 loop.
416 X<my> X<local>
417
418 The C<foreach> keyword is actually a synonym for the C<for> keyword, so
419 you can use C<foreach> for readability or C<for> for brevity.  (Or because
420 the Bourne shell is more familiar to you than I<csh>, so writing C<for>
421 comes more naturally.)  If VAR is omitted, C<$_> is set to each value.
422 X<$_>
423
424 If any element of LIST is an lvalue, you can modify it by modifying
425 VAR inside the loop.  Conversely, if any element of LIST is NOT an
426 lvalue, any attempt to modify that element will fail.  In other words,
427 the C<foreach> loop index variable is an implicit alias for each item
428 in the list that you're looping over.
429 X<alias>
430
431 If any part of LIST is an array, C<foreach> will get very confused if
432 you add or remove elements within the loop body, for example with
433 C<splice>.   So don't do that.
434 X<splice>
435
436 C<foreach> probably won't do what you expect if VAR is a tied or other
437 special variable.   Don't do that either.
438
439 Examples:
440
441     for (@ary) { s/foo/bar/ }
442
443     for my $elem (@elements) {
444         $elem *= 2;
445     }
446
447     for $count (10,9,8,7,6,5,4,3,2,1,'BOOM') {
448         print $count, "\n"; sleep(1);
449     }
450
451     for (1..15) { print "Merry Christmas\n"; }
452
453     foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
454         print "Item: $item\n";
455     }
456
457 Here's how a C programmer might code up a particular algorithm in Perl:
458
459     for (my $i = 0; $i < @ary1; $i++) {
460         for (my $j = 0; $j < @ary2; $j++) {
461             if ($ary1[$i] > $ary2[$j]) {
462                 last; # can't go to outer :-(
463             }
464             $ary1[$i] += $ary2[$j];
465         }
466         # this is where that last takes me
467     }
468
469 Whereas here's how a Perl programmer more comfortable with the idiom might
470 do it:
471
472     OUTER: for my $wid (@ary1) {
473     INNER:   for my $jet (@ary2) {
474                 next OUTER if $wid > $jet;
475                 $wid += $jet;
476              }
477           }
478
479 See how much easier this is?  It's cleaner, safer, and faster.  It's
480 cleaner because it's less noisy.  It's safer because if code gets added
481 between the inner and outer loops later on, the new code won't be
482 accidentally executed.  The C<next> explicitly iterates the other loop
483 rather than merely terminating the inner one.  And it's faster because
484 Perl executes a C<foreach> statement more rapidly than it would the
485 equivalent C<for> loop.
486
487 =head2 Basic BLOCKs
488 X<block>
489
490 A BLOCK by itself (labeled or not) is semantically equivalent to a
491 loop that executes once.  Thus you can use any of the loop control
492 statements in it to leave or restart the block.  (Note that this is
493 I<NOT> true in C<eval{}>, C<sub{}>, or contrary to popular belief
494 C<do{}> blocks, which do I<NOT> count as loops.)  The C<continue>
495 block is optional.
496
497 The BLOCK construct can be used to emulate case structures.
498
499     SWITCH: {
500         if (/^abc/) { $abc = 1; last SWITCH; }
501         if (/^def/) { $def = 1; last SWITCH; }
502         if (/^xyz/) { $xyz = 1; last SWITCH; }
503         $nothing = 1;
504     }
505
506 Such constructs are quite frequently used, because older versions
507 of Perl had no official C<switch> statement.
508
509 =head2 Switch statements
510 X<switch> X<case> X<given> X<when> X<default>
511
512 Starting from Perl 5.10, you can say
513
514     use feature "switch";
515
516 which enables a switch feature that is closely based on the
517 Perl 6 proposal.
518
519 The keywords C<given> and C<when> are analogous
520 to C<switch> and C<case> in other languages, so the code
521 above could be written as
522
523     given($_) {
524         when (/^abc/) { $abc = 1; }
525         when (/^def/) { $def = 1; }
526         when (/^xyz/) { $xyz = 1; }
527         default { $nothing = 1; }
528     }
529
530 This construct is very flexible and powerful. For example:
531
532     use feature ":5.10";
533     given($foo) {
534         when (undef) {
535             say '$foo is undefined';
536         }
537         when ("foo") {
538             say '$foo is the string "foo"';
539         }
540         when ([1,3,5,7,9]) {
541             say '$foo is an odd digit';
542             continue; # Fall through
543         }
544         when ($_ < 100) {
545             say '$foo is numerically less than 100';
546         }
547         when (\&complicated_check) {
548             say 'a complicated check for $foo is true';
549         }
550         default {
551             die q(I don't know what to do with $foo);
552         }
553     }
554
555 C<given(EXPR)> will assign the value of EXPR to C<$_>
556 within the lexical scope of the block, so it's similar to
557
558         do { my $_ = EXPR; ... }
559
560 except that the block is automatically broken out of by a
561 successful C<when> or an explicit C<break>.
562
563 Most of the power comes from implicit smart matching:
564
565         when($foo)
566
567 is exactly equivalent to
568
569         when($_ ~~ $foo)
570
571 Most of the time, C<when(EXPR)> is treated as an implicit smart match of
572 C<$_>, i.e. C<$_ ~~ EXPR>. (See L</"Smart matching in detail"> for more
573 information on smart matching.) But when EXPR is one of the below
574 exceptional cases, it is used directly as a boolean:
575
576 =over 4
577
578 =item *
579
580 a subroutine or method call
581
582 =item *
583
584 a regular expression match, i.e. C</REGEX/> or C<$foo =~ /REGEX/>,
585 or a negated regular expression match (C<!/REGEX/> or C<$foo !~ /REGEX/>).
586
587 =item *
588
589 a comparison such as C<$_ E<lt> 10> or C<$x eq "abc">
590 (or of course C<$_ ~~ $c>)
591
592 =item *
593
594 C<defined(...)>, C<exists(...)>, or C<eof(...)>
595
596 =item *
597
598 a negated expression C<!(...)> or C<not (...)>, or a logical
599 exclusive-or C<(...) xor (...)>.
600
601 =item *
602
603 a filetest operator, with the exception of C<-s>, C<-M>, C<-A>, and C<-C>,
604 that return numerical values, not boolean ones.
605
606 =item *
607
608 the C<..> and C<...> flip-flop operators.
609
610 =back
611
612 In those cases the value of EXPR is used directly as a boolean.
613
614 Furthermore:
615
616 =over 4
617
618 =item *
619
620 If EXPR is C<... && ...> or C<... and ...>, the test
621 is applied recursively to both arguments. If I<both>
622 arguments pass the test, then the argument is treated
623 as boolean.
624
625 =item *
626
627 If EXPR is C<... || ...>, C<... // ...> or C<... or ...>, the test
628 is applied recursively to the first argument.
629
630 =back
631
632 These rules look complicated, but usually they will do what
633 you want. For example you could write:
634
635     when (/^\d+$/ && $_ < 75) { ... }
636
637 Another useful shortcut is that, if you use a literal array
638 or hash as the argument to C<given>, it is turned into a
639 reference. So C<given(@foo)> is the same as C<given(\@foo)>,
640 for example.
641
642 C<default> behaves exactly like C<when(1 == 1)>, which is
643 to say that it always matches.
644
645 =head3 Breaking out
646
647 You can use the C<break> keyword to break out of the enclosing
648 C<given> block.  Every C<when> block is implicitly ended with
649 a C<break>.
650
651 =head3 Fall-through
652
653 You can use the C<continue> keyword to fall through from one
654 case to the next:
655
656     given($foo) {
657         when (/x/) { say '$foo contains an x'; continue }
658         when (/y/) { say '$foo contains a y' }
659         default    { say '$foo does not contain a y' }
660     }
661
662 =head3 Switching in a loop
663
664 Instead of using C<given()>, you can use a C<foreach()> loop.
665 For example, here's one way to count how many times a particular
666 string occurs in an array:
667
668     my $count = 0;
669     for (@array) {
670         when ("foo") { ++$count }
671     }
672     print "\@array contains $count copies of 'foo'\n";
673
674 On exit from the C<when> block, there is an implicit C<next>.
675 You can override that with an explicit C<last> if you're only
676 interested in the first match.
677
678 This doesn't work if you explicitly specify a loop variable,
679 as in C<for $item (@array)>. You have to use the default
680 variable C<$_>. (You can use C<for my $_ (@array)>.)
681
682 =head3 Smart matching in detail
683
684 The behaviour of a smart match depends on what type of thing its arguments
685 are. The behaviour is determined by the following table: the first row
686 that applies determines the match behaviour (which is thus mostly
687 determined by the type of the right operand). Note that the smart match
688 implicitly dereferences any non-blessed hash or array ref, so the "Hash"
689 and "Array" entries apply in those cases. (For blessed references, the
690 "Object" entries apply.)
691
692 Note that the "Matching Code" column is not always an exact rendition.  For
693 example, the smart match operator short-circuits whenever possible, but
694 C<grep> does not.
695
696     $a      $b        Type of Match Implied    Matching Code
697     ======  =====     =====================    =============
698     Any     undef     undefined                !defined $a
699
700     Any     Object    invokes ~~ overloading on $object, or dies
701
702     Hash    CodeRef   sub truth for each key[1] !grep { !$b->($_) } keys %$a
703     Array   CodeRef   sub truth for each elt[1] !grep { !$b->($_) } @$a
704     Any     CodeRef   scalar sub truth          $b->($a)
705
706     Hash    Hash      hash keys identical (every key is found in both hashes)
707     Array   Hash      hash slice existence     grep { exists $b->{$_} } @$a
708     Regex   Hash      hash key grep            grep /$a/, keys %$b
709     undef   Hash      always false (undef can't be a key)
710     Any     Hash      hash entry existence     exists $b->{$a}
711
712     Hash    Array     hash slice existence     grep { exists $a->{$_} } @$b
713     Array   Array     arrays are comparable[2]
714     Regex   Array     array grep               grep /$a/, @$b
715     undef   Array     array contains undef     grep !defined, @$b
716     Any     Array     match against an array element[3]
717                                                grep $a ~~ $_, @$b
718
719     Hash    Regex     hash key grep            grep /$b/, keys %$a
720     Array   Regex     array grep               grep /$b/, @$a
721     Any     Regex     pattern match            $a =~ /$b/
722
723     Object  Any       invokes ~~ overloading on $object, or falls back:
724     Any     Num       numeric equality         $a == $b
725     Num     numish[4] numeric equality         $a == $b
726     undef   Any       undefined                !defined($b)
727     Any     Any       string equality          $a eq $b
728
729  1 - empty hashes or arrays will match.
730  2 - that is, each element smart-matches the element of same index in the
731      other array. [3]
732  3 - If a circular reference is found, we fall back to referential equality.
733  4 - either a real number, or a string that looks like a number
734
735 =head3 Custom matching via overloading
736
737 You can change the way that an object is matched by overloading
738 the C<~~> operator. This may alter the usual smart match semantics.
739
740 It should be noted that C<~~> will refuse to work on objects that
741 don't overload it (in order to avoid relying on the object's
742 underlying structure).
743
744 Note also that smart match's matching rules take precedence over
745 overloading, so if C<$obj> has smart match overloading, then
746
747     $obj ~~ X
748
749 will not automatically invoke the overload method with X as an argument;
750 instead the table above is consulted as normal, and based in the type of X,
751 overloading may or may not be invoked.
752
753 See L<overload>.
754
755 =head3 Differences from Perl 6
756
757 The Perl 5 smart match and C<given>/C<when> constructs are not
758 absolutely identical to their Perl 6 analogues. The most visible
759 difference is that, in Perl 5, parentheses are required around
760 the argument to C<given()> and C<when()> (except when this last
761 one is used as a statement modifier). Parentheses in Perl 6
762 are always optional in a control construct such as C<if()>,
763 C<while()>, or C<when()>; they can't be made optional in Perl
764 5 without a great deal of potential confusion, because Perl 5
765 would parse the expression
766
767   given $foo {
768     ...
769   }
770
771 as though the argument to C<given> were an element of the hash
772 C<%foo>, interpreting the braces as hash-element syntax.
773
774 The table of smart matches is not identical to that proposed by the
775 Perl 6 specification, mainly due to the differences between Perl 6's
776 and Perl 5's data models.
777
778 In Perl 6, C<when()> will always do an implicit smart match
779 with its argument, whilst it is convenient in Perl 5 to
780 suppress this implicit smart match in certain situations,
781 as documented above. (The difference is largely because Perl 5
782 does not, even internally, have a boolean type.)
783
784 =head2 Goto
785 X<goto>
786
787 Although not for the faint of heart, Perl does support a C<goto>
788 statement.  There are three forms: C<goto>-LABEL, C<goto>-EXPR, and
789 C<goto>-&NAME.  A loop's LABEL is not actually a valid target for
790 a C<goto>; it's just the name of the loop.
791
792 The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
793 execution there.  It may not be used to go into any construct that
794 requires initialization, such as a subroutine or a C<foreach> loop.  It
795 also can't be used to go into a construct that is optimized away.  It
796 can be used to go almost anywhere else within the dynamic scope,
797 including out of subroutines, but it's usually better to use some other
798 construct such as C<last> or C<die>.  The author of Perl has never felt the
799 need to use this form of C<goto> (in Perl, that is--C is another matter).
800
801 The C<goto>-EXPR form expects a label name, whose scope will be resolved
802 dynamically.  This allows for computed C<goto>s per FORTRAN, but isn't
803 necessarily recommended if you're optimizing for maintainability:
804
805     goto(("FOO", "BAR", "GLARCH")[$i]);
806
807 The C<goto>-&NAME form is highly magical, and substitutes a call to the
808 named subroutine for the currently running subroutine.  This is used by
809 C<AUTOLOAD()> subroutines that wish to load another subroutine and then
810 pretend that the other subroutine had been called in the first place
811 (except that any modifications to C<@_> in the current subroutine are
812 propagated to the other subroutine.)  After the C<goto>, not even C<caller()>
813 will be able to tell that this routine was called first.
814
815 In almost all cases like this, it's usually a far, far better idea to use the
816 structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of
817 resorting to a C<goto>.  For certain applications, the catch and throw pair of
818 C<eval{}> and die() for exception processing can also be a prudent approach.
819
820 =head2 PODs: Embedded Documentation
821 X<POD> X<documentation>
822
823 Perl has a mechanism for intermixing documentation with source code.
824 While it's expecting the beginning of a new statement, if the compiler
825 encounters a line that begins with an equal sign and a word, like this
826
827     =head1 Here There Be Pods!
828
829 Then that text and all remaining text up through and including a line
830 beginning with C<=cut> will be ignored.  The format of the intervening
831 text is described in L<perlpod>.
832
833 This allows you to intermix your source code
834 and your documentation text freely, as in
835
836     =item snazzle($)
837
838     The snazzle() function will behave in the most spectacular
839     form that you can possibly imagine, not even excepting
840     cybernetic pyrotechnics.
841
842     =cut back to the compiler, nuff of this pod stuff!
843
844     sub snazzle($) {
845         my $thingie = shift;
846         .........
847     }
848
849 Note that pod translators should look at only paragraphs beginning
850 with a pod directive (it makes parsing easier), whereas the compiler
851 actually knows to look for pod escapes even in the middle of a
852 paragraph.  This means that the following secret stuff will be
853 ignored by both the compiler and the translators.
854
855     $a=3;
856     =secret stuff
857      warn "Neither POD nor CODE!?"
858     =cut back
859     print "got $a\n";
860
861 You probably shouldn't rely upon the C<warn()> being podded out forever.
862 Not all pod translators are well-behaved in this regard, and perhaps
863 the compiler will become pickier.
864
865 One may also use pod directives to quickly comment out a section
866 of code.
867
868 =head2 Plain Old Comments (Not!)
869 X<comment> X<line> X<#> X<preprocessor> X<eval>
870
871 Perl can process line directives, much like the C preprocessor.  Using
872 this, one can control Perl's idea of filenames and line numbers in
873 error or warning messages (especially for strings that are processed
874 with C<eval()>).  The syntax for this mechanism is the same as for most
875 C preprocessors: it matches the regular expression
876
877     # example: '# line 42 "new_filename.plx"'
878     /^\#   \s*
879       line \s+ (\d+)   \s*
880       (?:\s("?)([^"]+)\2)? \s*
881      $/x
882
883 with C<$1> being the line number for the next line, and C<$3> being
884 the optional filename (specified with or without quotes).
885
886 There is a fairly obvious gotcha included with the line directive:
887 Debuggers and profilers will only show the last source line to appear
888 at a particular line number in a given file.  Care should be taken not
889 to cause line number collisions in code you'd like to debug later.
890
891 Here are some examples that you should be able to type into your command
892 shell:
893
894     % perl
895     # line 200 "bzzzt"
896     # the `#' on the previous line must be the first char on line
897     die 'foo';
898     __END__
899     foo at bzzzt line 201.
900
901     % perl
902     # line 200 "bzzzt"
903     eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
904     __END__
905     foo at - line 2001.
906
907     % perl
908     eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
909     __END__
910     foo at foo bar line 200.
911
912     % perl
913     # line 345 "goop"
914     eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
915     print $@;
916     __END__
917     foo at goop line 345.
918
919 =cut