[Summary view] [Print] [Text view]

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