pod/perlsyn.pod

   1 =head1 NAME
   2
   3 perlsyn - Perl syntax
   4
   5 =head1 DESCRIPTION
   6
   7 A Perl program consists of a sequence of declarations and statements
   8 which run from the top to the bottom.  Loops, subroutines and other
   9 control structures allow you to jump around within the code.
  10
  11 Perl is a B<free-form> language, you can format and indent it however
  12 you like.  Whitespace mostly serves to separate tokens, unlike
  13 languages like Python where it is an important part of the syntax.
  14
  15 Many of Perl's syntactic elements are B<optional>.  Rather than
  16 requiring you to put parentheses around every function call and
  17 declare every variable, you can often leave such explicit elements off
  18 and Perl will figure out what you meant.  This is known as B<Do What I
  19 Mean>, abbreviated B<DWIM>.  It allows programmers to be B<lazy> and to
  20 code in a style with which they are comfortable.
  21
  22 Perl B<borrows syntax> and concepts from many languages: awk, sed, C,
  23 Bourne Shell, Smalltalk, Lisp and even English.  Other
  24 languages have borrowed syntax from Perl, particularly its regular
  25 expression extensions.  So if you have programmed in another language
  26 you will see familiar pieces in Perl.  They often work the same, but
  27 see L<perltrap> for information about how they differ.
  28
  29 =head2 Declarations
  30
  31 The only things you need to declare in Perl are report formats and
  32 subroutines (and sometimes not even subroutines).  A variable holds
  33 the undefined value (C<undef>) until it has been assigned a defined
  34 value, which is anything other than C<undef>.  When used as a number,
  35 C<undef> is treated as C<0>; when used as a string, it is treated as
  36 the empty string, C<"">; and when used as a reference that isn't being
  37 assigned to, it is treated as an error.  If you enable warnings,
  38 you'll be notified of an uninitialized value whenever you treat
  39 C<undef> as a string or a number.  Well, usually.  Boolean contexts,
  40 such as:
  41
  42     my $a;
  43     if ($a) {}
  44
  45 are exempt from warnings (because they care about truth rather than
  46 definedness).  Operators such as C<++>, C<-->, C<+=>,
  47 C<-=>, and C<.=>, that operate on undefined left values such as:
  48
  49     my $a;
  50     $a++;
  51
  52 are also always exempt from such warnings.
  53
  54 A declaration can be put anywhere a statement can, but has no effect on
  55 the execution of the primary sequence of statements--declarations all
  56 take effect at compile time.  Typically all the declarations are put at
  57 the beginning or the end of the script.  However, if you're using
  58 lexically-scoped private variables created with C<my()>, you'll
  59 have to make sure
  60 your format or subroutine definition is within the same block scope
  61 as the my if you expect to be able to access those private variables.
  62
  63 Declaring a subroutine allows a subroutine name to be used as if it were a
  64 list operator from that point forward in the program.  You can declare a
  65 subroutine without defining it by saying C<sub name>, thus:
  66
  67     sub myname;
  68     $me = myname $0             or die "can't get myname";
  69
  70 Note that myname() functions as a list operator, not as a unary operator;
  71 so be careful to use C<or> instead of C<||> in this case.  However, if
  72 you were to declare the subroutine as C<sub myname ($)>, then
  73 C<myname> would function as a unary operator, so either C<or> or
  74 C<||> would work.
  75
  76 Subroutines declarations can also be loaded up with the C<require> statement
  77 or both loaded and imported into your namespace with a C<use> statement.
  78 See L<perlmod> for details on this.
  79
  80 A statement sequence may contain declarations of lexically-scoped
  81 variables, but apart from declaring a variable name, the declaration acts
  82 like an ordinary statement, and is elaborated within the sequence of
  83 statements as if it were an ordinary statement.  That means it actually
  84 has both compile-time and run-time effects.
  85
  86 =head2 Comments
  87
  88 Text from a C<"#"> character until the end of the line is a comment,
  89 and is ignored.  Exceptions include C<"#"> inside a string or regular
  90 expression.
  91
  92 =head2 Simple Statements
  93
  94 The only kind of simple statement is an expression evaluated for its
  95 side effects.  Every simple statement must be terminated with a
  96 semicolon, unless it is the final statement in a block, in which case
  97 the semicolon is optional.  (A semicolon is still encouraged if the
  98 block takes up more than one line, because you may eventually add
  99 another line.)  Note that there are some operators like C<eval {}> and
 100 C<do {}> that look like compound statements, but aren't (they're just
 101 TERMs in an expression), and thus need an explicit termination if used
 102 as the last item in a statement.
 103
 104 =head2 Truth and Falsehood
 105
 106 The number 0, the strings C<'0'> and C<''>, the empty list C<()>, and
 107 C<undef> are all false in a boolean context. All other values are true.
 108
 109 =head2 Statement Modifiers
 110
 111 Any simple statement may optionally be followed by a I<SINGLE> modifier,
 112 just before the terminating semicolon (or block ending).  The possible
 113 modifiers are:
 114
 115     if EXPR
 116     unless EXPR
 117     while EXPR
 118     until EXPR
 119     foreach LIST
 120
 121 The C<EXPR> following the modifier is referred to as the "condition".
 122 Its truth or falsehood determines how the modifier will behave.
 123
 124 C<if> executes the statement once I<if> and only if the condition is
 125 true.  C<unless> is the opposite, it executes the statement I<unless>
 126 the condition is true (i.e., if the condition is false).
 127
 128     print "Basset hounds got long ears" if length $ear >= 10;
 129     go_outside() and play() unless $is_raining;
 130
 131 The C<foreach> modifier is an iterator: it executes the statement once
 132 for each item in the LIST (with C<$_> aliased to each item in turn).
 133
 134     print "Hello $_!\n" foreach qw(world Dolly nurse);
 135
 136 C<while> repeats the statement I<while> the condition is true.
 137 C<until> does the opposite, it repeats the statement I<until> the
 138 condition is true (or while the condition is false):
 139
 140     # Both of these count from 0 to 10.
 141     print $i++ while $i <= 10;
 142     print $j++ until $j >  10;
 143
 144 The C<while> and C<until> modifiers have the usual "C<while> loop"
 145 semantics (conditional evaluated first), except when applied to a
 146 C<do>-BLOCK (or to the deprecated C<do>-SUBROUTINE statement), in
 147 which case the block executes once before the conditional is
 148 evaluated.  This is so that you can write loops like:
 149
 150     do {
 151         $line = <STDIN>;
 152         ...
 153     } until $line  eq ".\n";
 154
 155 See L<perlfunc/do>.  Note also that the loop control statements described
 156 later will I<NOT> work in this construct, because modifiers don't take
 157 loop labels.  Sorry.  You can always put another block inside of it
 158 (for C<next>) or around it (for C<last>) to do that sort of thing.
 159 For C<next>, just double the braces:
 160
 161     do {{
 162         next if $x == $y;
 163         # do something here
 164     }} until $x++ > $z;
 165
 166 For C<last>, you have to be more elaborate:
 167
 168     LOOP: {
 169             do {
 170                 last if $x = $y**2;
 171                 # do something here
 172             } while $x++ <= $z;
 173     }
 174
 175 B<NOTE:> The behaviour of a C<my> statement modified with a statement
 176 modifier conditional or loop construct (e.g. C<my $x if ...>) is
 177 B<undefined>.  The value of the C<my> variable may be C<undef>, any
 178 previously assigned value, or possibly anything else.  Don't rely on
 179 it.  Future versions of perl might do something different from the
 180 version of perl you try it out on.  Here be dragons.
 181
 182 =head2 Compound Statements
 183
 184 In Perl, a sequence of statements that defines a scope is called a block.
 185 Sometimes a block is delimited by the file containing it (in the case
 186 of a required file, or the program as a whole), and sometimes a block
 187 is delimited by the extent of a string (in the case of an eval).
 188
 189 But generally, a block is delimited by curly brackets, also known as braces.
 190 We will call this syntactic construct a BLOCK.
 191
 192 The following compound statements may be used to control flow:
 193
 194     if (EXPR) BLOCK
 195     if (EXPR) BLOCK else BLOCK
 196     if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
 197     LABEL while (EXPR) BLOCK
 198     LABEL while (EXPR) BLOCK continue BLOCK
 199     LABEL for (EXPR; EXPR; EXPR) BLOCK
 200     LABEL foreach VAR (LIST) BLOCK
 201     LABEL foreach VAR (LIST) BLOCK continue BLOCK
 202     LABEL BLOCK continue BLOCK
 203
 204 Note that, unlike C and Pascal, these are defined in terms of BLOCKs,
 205 not statements.  This means that the curly brackets are I<required>--no
 206 dangling statements allowed.  If you want to write conditionals without
 207 curly brackets there are several other ways to do it.  The following
 208 all do the same thing:
 209
 210     if (!open(FOO)) { die "Can't open $FOO: $!"; }
 211     die "Can't open $FOO: $!" unless open(FOO);
 212     open(FOO) or die "Can't open $FOO: $!";     # FOO or bust!
 213     open(FOO) ? 'hi mom' : die "Can't open $FOO: $!";
 214                         # a bit exotic, that last one
 215
 216 The C<if> statement is straightforward.  Because BLOCKs are always
 217 bounded by curly brackets, there is never any ambiguity about which
 218 C<if> an C<else> goes with.  If you use C<unless> in place of C<if>,
 219 the sense of the test is reversed.
 220
 221 The C<while> statement executes the block as long as the expression is
 222 true (does not evaluate to the null string C<""> or C<0> or C<"0">).
 223 The LABEL is optional, and if present, consists of an identifier followed
 224 by a colon.  The LABEL identifies the loop for the loop control
 225 statements C<next>, C<last>, and C<redo>.
 226 If the LABEL is omitted, the loop control statement
 227 refers to the innermost enclosing loop.  This may include dynamically
 228 looking back your call-stack at run time to find the LABEL.  Such
 229 desperate behavior triggers a warning if you use the C<use warnings>
 230 pragma or the B<-w> flag.
 231
 232 If there is a C<continue> BLOCK, it is always executed just before the
 233 conditional is about to be evaluated again.  Thus it can be used to
 234 increment a loop variable, even when the loop has been continued via
 235 the C<next> statement.
 236
 237 =head2 Loop Control
 238
 239 The C<next> command starts the next iteration of the loop:
 240
 241     LINE: while (<STDIN>) {
 242         next LINE if /^#/;      # discard comments
 243         ...
 244     }
 245
 246 The C<last> command immediately exits the loop in question.  The
 247 C<continue> block, if any, is not executed:
 248
 249     LINE: while (<STDIN>) {
 250         last LINE if /^$/;      # exit when done with header
 251         ...
 252     }
 253
 254 The C<redo> command restarts the loop block without evaluating the
 255 conditional again.  The C<continue> block, if any, is I<not> executed.
 256 This command is normally used by programs that want to lie to themselves
 257 about what was just input.
 258
 259 For example, when processing a file like F</etc/termcap>.
 260 If your input lines might end in backslashes to indicate continuation, you
 261 want to skip ahead and get the next record.
 262
 263     while (<>) {
 264         chomp;
 265         if (s/\\$//) {
 266             $_ .= <>;
 267             redo unless eof();
 268         }
 269         # now process $_
 270     }
 271
 272 which is Perl short-hand for the more explicitly written version:
 273
 274     LINE: while (defined($line = <ARGV>)) {
 275         chomp($line);
 276         if ($line =~ s/\\$//) {
 277             $line .= <ARGV>;
 278             redo LINE unless eof(); # not eof(ARGV)!
 279         }
 280         # now process $line
 281     }
 282
 283 Note that if there were a C<continue> block on the above code, it would
 284 get executed only on lines discarded by the regex (since redo skips the
 285 continue block). A continue block is often used to reset line counters
 286 or C<?pat?> one-time matches:
 287
 288     # inspired by :1,$g/fred/s//WILMA/
 289     while (<>) {
 290         ?(fred)?    && s//WILMA $1 WILMA/;
 291         ?(barney)?  && s//BETTY $1 BETTY/;
 292         ?(homer)?   && s//MARGE $1 MARGE/;
 293     } continue {
 294         print "$ARGV $.: $_";
 295         close ARGV  if eof();           # reset $.
 296         reset       if eof();           # reset ?pat?
 297     }
 298
 299 If the word C<while> is replaced by the word C<until>, the sense of the
 300 test is reversed, but the conditional is still tested before the first
 301 iteration.
 302
 303 The loop control statements don't work in an C<if> or C<unless>, since
 304 they aren't loops.  You can double the braces to make them such, though.
 305
 306     if (/pattern/) {{
 307         last if /fred/;
 308         next if /barney/; # same effect as "last", but doesn't document as well
 309         # do something here
 310     }}
 311
 312 This is caused by the fact that a block by itself acts as a loop that
 313 executes once, see L<"Basic BLOCKs and Switch Statements">.
 314
 315 The form C<while/if BLOCK BLOCK>, available in Perl 4, is no longer
 316 available.   Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>.
 317
 318 =head2 For Loops
 319
 320 Perl's C-style C<for> loop works like the corresponding C<while> loop;
 321 that means that this:
 322
 323     for ($i = 1; $i < 10; $i++) {
 324         ...
 325     }
 326
 327 is the same as this:
 328
 329     $i = 1;
 330     while ($i < 10) {
 331         ...
 332     } continue {
 333         $i++;
 334     }
 335
 336 There is one minor difference: if variables are declared with C<my>
 337 in the initialization section of the C<for>, the lexical scope of
 338 those variables is exactly the C<for> loop (the body of the loop
 339 and the control sections).
 340
 341 Besides the normal array index looping, C<for> can lend itself
 342 to many other interesting applications.  Here's one that avoids the
 343 problem you get into if you explicitly test for end-of-file on
 344 an interactive file descriptor causing your program to appear to
 345 hang.
 346
 347     $on_a_tty = -t STDIN && -t STDOUT;
 348     sub prompt { print "yes? " if $on_a_tty }
 349     for ( prompt(); <STDIN>; prompt() ) {
 350         # do something
 351     }
 352
 353 Using C<readline> (or the operator form, C<< <EXPR> >>) as the
 354 conditional of a C<for> loop is shorthand for the following.  This
 355 behaviour is the same as a C<while> loop conditional.
 356
 357     for ( prompt(); defined( $_ = <STDIN> ); prompt() ) {
 358         # do something
 359     }
 360
 361 =head2 Foreach Loops
 362
 363 The C<foreach> loop iterates over a normal list value and sets the
 364 variable VAR to be each element of the list in turn.  If the variable
 365 is preceded with the keyword C<my>, then it is lexically scoped, and
 366 is therefore visible only within the loop.  Otherwise, the variable is
 367 implicitly local to the loop and regains its former value upon exiting
 368 the loop.  If the variable was previously declared with C<my>, it uses
 369 that variable instead of the global one, but it's still localized to
 370 the loop.  This implicit localisation occurs I<only> in a C<foreach>
 371 loop.
 372
 373 The C<foreach> keyword is actually a synonym for the C<for> keyword, so
 374 you can use C<foreach> for readability or C<for> for brevity.  (Or because
 375 the Bourne shell is more familiar to you than I<csh>, so writing C<for>
 376 comes more naturally.)  If VAR is omitted, C<$_> is set to each value.
 377
 378 If any element of LIST is an lvalue, you can modify it by modifying
 379 VAR inside the loop.  Conversely, if any element of LIST is NOT an
 380 lvalue, any attempt to modify that element will fail.  In other words,
 381 the C<foreach> loop index variable is an implicit alias for each item
 382 in the list that you're looping over.
 383
 384 If any part of LIST is an array, C<foreach> will get very confused if
 385 you add or remove elements within the loop body, for example with
 386 C<splice>.   So don't do that.
 387
 388 C<foreach> probably won't do what you expect if VAR is a tied or other
 389 special variable.   Don't do that either.
 390
 391 Examples:
 392
 393     for (@ary) { s/foo/bar/ }
 394
 395     for my $elem (@elements) {
 396         $elem *= 2;
 397     }
 398
 399     for $count (10,9,8,7,6,5,4,3,2,1,'BOOM') {
 400         print $count, "\n"; sleep(1);
 401     }
 402
 403     for (1..15) { print "Merry Christmas\n"; }
 404
 405     foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
 406         print "Item: $item\n";
 407     }
 408
 409 Here's how a C programmer might code up a particular algorithm in Perl:
 410
 411     for (my $i = 0; $i < @ary1; $i++) {
 412         for (my $j = 0; $j < @ary2; $j++) {
 413             if ($ary1[$i] > $ary2[$j]) {
 414                 last; # can't go to outer :-(
 415             }
 416             $ary1[$i] += $ary2[$j];
 417         }
 418         # this is where that last takes me
 419     }
 420
 421 Whereas here's how a Perl programmer more comfortable with the idiom might
 422 do it:
 423
 424     OUTER: for my $wid (@ary1) {
 425     INNER:   for my $jet (@ary2) {
 426                 next OUTER if $wid > $jet;
 427                 $wid += $jet;
 428              }
 429           }
 430
 431 See how much easier this is?  It's cleaner, safer, and faster.  It's
 432 cleaner because it's less noisy.  It's safer because if code gets added
 433 between the inner and outer loops later on, the new code won't be
 434 accidentally executed.  The C<next> explicitly iterates the other loop
 435 rather than merely terminating the inner one.  And it's faster because
 436 Perl executes a C<foreach> statement more rapidly than it would the
 437 equivalent C<for> loop.
 438
 439 =head2 Basic BLOCKs and Switch Statements
 440
 441 A BLOCK by itself (labeled or not) is semantically equivalent to a
 442 loop that executes once.  Thus you can use any of the loop control
 443 statements in it to leave or restart the block.  (Note that this is
 444 I<NOT> true in C<eval{}>, C<sub{}>, or contrary to popular belief
 445 C<do{}> blocks, which do I<NOT> count as loops.)  The C<continue>
 446 block is optional.
 447
 448 The BLOCK construct is particularly nice for doing case
 449 structures.
 450
 451     SWITCH: {
 452         if (/^abc/) { $abc = 1; last SWITCH; }
 453         if (/^def/) { $def = 1; last SWITCH; }
 454         if (/^xyz/) { $xyz = 1; last SWITCH; }
 455         $nothing = 1;
 456     }
 457
 458 There is no official C<switch> statement in Perl, because there are
 459 already several ways to write the equivalent.
 460
 461 However, starting from Perl 5.8 to get switch and case one can use
 462 the Switch extension and say:
 463
 464         use Switch;
 465
 466 after which one has switch and case.  It is not as fast as it could be
 467 because it's not really part of the language (it's done using source
 468 filters) but it is available, and it's very flexible.
 469
 470 In addition to the above BLOCK construct, you could write
 471
 472     SWITCH: {
 473         $abc = 1, last SWITCH  if /^abc/;
 474         $def = 1, last SWITCH  if /^def/;
 475         $xyz = 1, last SWITCH  if /^xyz/;
 476         $nothing = 1;
 477     }
 478
 479 (That's actually not as strange as it looks once you realize that you can
 480 use loop control "operators" within an expression.  That's just the binary
 481 comma operator in scalar context.  See L<perlop/"Comma Operator">.)
 482
 483 or
 484
 485     SWITCH: {
 486         /^abc/ && do { $abc = 1; last SWITCH; };
 487         /^def/ && do { $def = 1; last SWITCH; };
 488         /^xyz/ && do { $xyz = 1; last SWITCH; };
 489         $nothing = 1;
 490     }
 491
 492 or formatted so it stands out more as a "proper" C<switch> statement:
 493
 494     SWITCH: {
 495         /^abc/      && do {
 496                             $abc = 1;
 497                             last SWITCH;
 498                        };
 499
 500         /^def/      && do {
 501                             $def = 1;
 502                             last SWITCH;
 503                        };
 504
 505         /^xyz/      && do {
 506                             $xyz = 1;
 507                             last SWITCH;
 508                         };
 509         $nothing = 1;
 510     }
 511
 512 or
 513
 514     SWITCH: {
 515         /^abc/ and $abc = 1, last SWITCH;
 516         /^def/ and $def = 1, last SWITCH;
 517         /^xyz/ and $xyz = 1, last SWITCH;
 518         $nothing = 1;
 519     }
 520
 521 or even, horrors,
 522
 523     if (/^abc/)
 524         { $abc = 1 }
 525     elsif (/^def/)
 526         { $def = 1 }
 527     elsif (/^xyz/)
 528         { $xyz = 1 }
 529     else
 530         { $nothing = 1 }
 531
 532 A common idiom for a C<switch> statement is to use C<foreach>'s aliasing to make
 533 a temporary assignment to C<$_> for convenient matching:
 534
 535     SWITCH: for ($where) {
 536                 /In Card Names/     && do { push @flags, '-e'; last; };
 537                 /Anywhere/          && do { push @flags, '-h'; last; };
 538                 /In Rulings/        && do {                    last; };
 539                 die "unknown value for form variable where: `$where'";
 540             }
 541
 542 Another interesting approach to a switch statement is arrange
 543 for a C<do> block to return the proper value:
 544
 545     $amode = do {
 546         if     ($flag & O_RDONLY) { "r" }       # XXX: isn't this 0?
 547         elsif  ($flag & O_WRONLY) { ($flag & O_APPEND) ? "a" : "w" }
 548         elsif  ($flag & O_RDWR)   {
 549             if ($flag & O_CREAT)  { "w+" }
 550             else                  { ($flag & O_APPEND) ? "a+" : "r+" }
 551         }
 552     };
 553
 554 Or
 555
 556         print do {
 557             ($flags & O_WRONLY) ? "write-only"          :
 558             ($flags & O_RDWR)   ? "read-write"          :
 559                                   "read-only";
 560         };
 561
 562 Or if you are certain that all the C<&&> clauses are true, you can use
 563 something like this, which "switches" on the value of the
 564 C<HTTP_USER_AGENT> environment variable.
 565
 566     #!/usr/bin/perl
 567     # pick out jargon file page based on browser
 568     $dir = 'http://www.wins.uva.nl/~mes/jargon';
 569     for ($ENV{HTTP_USER_AGENT}) {
 570         $page  =    /Mac/            && 'm/Macintrash.html'
 571                  || /Win(dows )?NT/  && 'e/evilandrude.html'
 572                  || /Win|MSIE|WebTV/ && 'm/MicroslothWindows.html'
 573                  || /Linux/          && 'l/Linux.html'
 574                  || /HP-UX/          && 'h/HP-SUX.html'
 575                  || /SunOS/          && 's/ScumOS.html'
 576                  ||                     'a/AppendixB.html';
 577     }
 578     print "Location: $dir/$page\015\012\015\012";
 579
 580 That kind of switch statement only works when you know the C<&&> clauses
 581 will be true.  If you don't, the previous C<?:> example should be used.
 582
 583 You might also consider writing a hash of subroutine references
 584 instead of synthesizing a C<switch> statement.
 585
 586 =head2 Goto
 587
 588 Although not for the faint of heart, Perl does support a C<goto>
 589 statement.  There are three forms: C<goto>-LABEL, C<goto>-EXPR, and
 590 C<goto>-&NAME.  A loop's LABEL is not actually a valid target for
 591 a C<goto>; it's just the name of the loop.
 592
 593 The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
 594 execution there.  It may not be used to go into any construct that
 595 requires initialization, such as a subroutine or a C<foreach> loop.  It
 596 also can't be used to go into a construct that is optimized away.  It
 597 can be used to go almost anywhere else within the dynamic scope,
 598 including out of subroutines, but it's usually better to use some other
 599 construct such as C<last> or C<die>.  The author of Perl has never felt the
 600 need to use this form of C<goto> (in Perl, that is--C is another matter).
 601
 602 The C<goto>-EXPR form expects a label name, whose scope will be resolved
 603 dynamically.  This allows for computed C<goto>s per FORTRAN, but isn't
 604 necessarily recommended if you're optimizing for maintainability:
 605
 606     goto(("FOO", "BAR", "GLARCH")[$i]);
 607
 608 The C<goto>-&NAME form is highly magical, and substitutes a call to the
 609 named subroutine for the currently running subroutine.  This is used by
 610 C<AUTOLOAD()> subroutines that wish to load another subroutine and then
 611 pretend that the other subroutine had been called in the first place
 612 (except that any modifications to C<@_> in the current subroutine are
 613 propagated to the other subroutine.)  After the C<goto>, not even C<caller()>
 614 will be able to tell that this routine was called first.
 615
 616 In almost all cases like this, it's usually a far, far better idea to use the
 617 structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of
 618 resorting to a C<goto>.  For certain applications, the catch and throw pair of
 619 C<eval{}> and die() for exception processing can also be a prudent approach.
 620
 621 =head2 PODs: Embedded Documentation
 622
 623 Perl has a mechanism for intermixing documentation with source code.
 624 While it's expecting the beginning of a new statement, if the compiler
 625 encounters a line that begins with an equal sign and a word, like this
 626
 627     =head1 Here There Be Pods!
 628
 629 Then that text and all remaining text up through and including a line
 630 beginning with C<=cut> will be ignored.  The format of the intervening
 631 text is described in L<perlpod>.
 632
 633 This allows you to intermix your source code
 634 and your documentation text freely, as in
 635
 636     =item snazzle($)
 637
 638     The snazzle() function will behave in the most spectacular
 639     form that you can possibly imagine, not even excepting
 640     cybernetic pyrotechnics.
 641
 642     =cut back to the compiler, nuff of this pod stuff!
 643
 644     sub snazzle($) {
 645         my $thingie = shift;
 646         .........
 647     }
 648
 649 Note that pod translators should look at only paragraphs beginning
 650 with a pod directive (it makes parsing easier), whereas the compiler
 651 actually knows to look for pod escapes even in the middle of a
 652 paragraph.  This means that the following secret stuff will be
 653 ignored by both the compiler and the translators.
 654
 655     $a=3;
 656     =secret stuff
 657      warn "Neither POD nor CODE!?"
 658     =cut back
 659     print "got $a\n";
 660
 661 You probably shouldn't rely upon the C<warn()> being podded out forever.
 662 Not all pod translators are well-behaved in this regard, and perhaps
 663 the compiler will become pickier.
 664
 665 One may also use pod directives to quickly comment out a section
 666 of code.
 667
 668 =head2 Plain Old Comments (Not!)
 669
 670 Perl can process line directives, much like the C preprocessor.  Using
 671 this, one can control Perl's idea of filenames and line numbers in
 672 error or warning messages (especially for strings that are processed
 673 with C<eval()>).  The syntax for this mechanism is the same as for most
 674 C preprocessors: it matches the regular expression
 675
 676     # example: '# line 42 "new_filename.plx"'
 677     /^\#   \s*
 678       line \s+ (\d+)   \s*
 679       (?:\s("?)([^"]+)\2)? \s*
 680      $/x
 681
 682 with C<$1> being the line number for the next line, and C<$3> being
 683 the optional filename (specified with or without quotes).
 684
 685 There is a fairly obvious gotcha included with the line directive:
 686 Debuggers and profilers will only show the last source line to appear
 687 at a particular line number in a given file.  Care should be taken not
 688 to cause line number collisions in code you'd like to debug later.
 689
 690 Here are some examples that you should be able to type into your command
 691 shell:
 692
 693     % perl
 694     # line 200 "bzzzt"
 695     # the `#' on the previous line must be the first char on line
 696     die 'foo';
 697     __END__
 698     foo at bzzzt line 201.
 699
 700     % perl
 701     # line 200 "bzzzt"
 702     eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
 703     __END__
 704     foo at - line 2001.
 705
 706     % perl
 707     eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
 708     __END__
 709     foo at foo bar line 200.
 710
 711     % perl
 712     # line 345 "goop"
 713     eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
 714     print $@;
 715     __END__
 716     foo at goop line 345.
 717
 718 =cut