pod/perlsyn.pod

   1 =head1 NAME
   2
   3 perlsyn - Perl syntax
   4
   5 =head1 DESCRIPTION
   6
   7 A Perl script consists of a sequence of declarations and statements.
   8 The only things that need to be declared in Perl are report formats
   9 and subroutines.  See the sections below for more information on those
  10 declarations.  All uninitialized user-created objects are assumed to
  11 start with a null or 0 value until they are defined by some explicit
  12 operation such as assignment.  (Though you can get warnings about the
  13 use of undefined values if you like.)  The sequence of statements is
  14 executed just once, unlike in B<sed> and B<awk> scripts, where the
  15 sequence of statements is executed for each input line.  While this means
  16 that you must explicitly loop over the lines of your input file (or
  17 files), it also means you have much more control over which files and
  18 which lines you look at.  (Actually, I'm lying--it is possible to do an
  19 implicit loop with either the B<-n> or B<-p> switch.  It's just not the
  20 mandatory default like it is in B<sed> and B<awk>.)
  21
  22 =head2 Declarations
  23
  24 Perl is, for the most part, a free-form language.  (The only
  25 exception to this is format declarations, for obvious reasons.) Comments
  26 are indicated by the "#" character, and extend to the end of the line.  If
  27 you attempt to use C</* */> C-style comments, it will be interpreted
  28 either as division or pattern matching, depending on the context, and C++
  29 C<//> comments just look like a null regular expression, so don't do
  30 that.
  31
  32 A declaration can be put anywhere a statement can, but has no effect on
  33 the execution of the primary sequence of statements--declarations all
  34 take effect at compile time.  Typically all the declarations are put at
  35 the beginning or the end of the script.  However, if you're using
  36 lexically-scoped private variables created with my(), you'll have to make sure
  37 your format or subroutine definition is within the same block scope
  38 as the my if you expect to be able to access those private variables.
  39
  40 Declaring a subroutine allows a subroutine name to be used as if it were a
  41 list operator from that point forward in the program.  You can declare a
  42 subroutine without defining it by saying C<sub name>, thus:
  43
  44     sub myname;
  45     $me = myname $0             or die "can't get myname";
  46
  47 Note that it functions as a list operator, not as a unary operator; so
  48 be careful to use C<or> instead of C<||> in this case.  However, if
  49 you were to declare the subroutine as C<sub myname ($)>, then
  50 C<myname> would function as a unary operator, so either C<or> or
  51 C<||> would work.
  52
  53 Subroutines declarations can also be loaded up with the C<require> statement
  54 or both loaded and imported into your namespace with a C<use> statement.
  55 See L<perlmod> for details on this.
  56
  57 A statement sequence may contain declarations of lexically-scoped
  58 variables, but apart from declaring a variable name, the declaration acts
  59 like an ordinary statement, and is elaborated within the sequence of
  60 statements as if it were an ordinary statement.  That means it actually
  61 has both compile-time and run-time effects.
  62
  63 =head2 Simple statements
  64
  65 The only kind of simple statement is an expression evaluated for its
  66 side effects.  Every simple statement must be terminated with a
  67 semicolon, unless it is the final statement in a block, in which case
  68 the semicolon is optional.  (A semicolon is still encouraged there if the
  69 block takes up more than one line, because you may eventually add another line.)
  70 Note that there are some operators like C<eval {}> and C<do {}> that look
  71 like compound statements, but aren't (they're just TERMs in an expression),
  72 and thus need an explicit termination if used as the last item in a statement.
  73
  74 Any simple statement may optionally be followed by a I<SINGLE> modifier,
  75 just before the terminating semicolon (or block ending).  The possible
  76 modifiers are:
  77
  78     if EXPR
  79     unless EXPR
  80     while EXPR
  81     until EXPR
  82     foreach EXPR
  83
  84 The C<if> and C<unless> modifiers have the expected semantics,
  85 presuming you're a speaker of English.  The C<foreach> modifier is an
  86 iterator:  For each value in EXPR, it aliases $_ to the value and
  87 executes the statement.  The C<while> and C<until> modifiers have the
  88 usual "while loop" semantics (conditional evaluated first), except
  89 when applied to a do-BLOCK (or to the now-deprecated do-SUBROUTINE
  90 statement), in which case the block executes once before the
  91 conditional is evaluated.  This is so that you can write loops like:
  92
  93     do {
  94         $line = <STDIN>;
  95         ...
  96     } until $line  eq ".\n";
  97
  98 See L<perlfunc/do>.  Note also that the loop control
  99 statements described later will I<NOT> work in this construct, because
 100 modifiers don't take loop labels.  Sorry.  You can always wrap
 101 another block around it to do that sort of thing.
 102
 103 =head2 Compound statements
 104
 105 In Perl, a sequence of statements that defines a scope is called a block.
 106 Sometimes a block is delimited by the file containing it (in the case
 107 of a required file, or the program as a whole), and sometimes a block
 108 is delimited by the extent of a string (in the case of an eval).
 109
 110 But generally, a block is delimited by curly brackets, also known as braces.
 111 We will call this syntactic construct a BLOCK.
 112
 113 The following compound statements may be used to control flow:
 114
 115     if (EXPR) BLOCK
 116     if (EXPR) BLOCK else BLOCK
 117     if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
 118     LABEL while (EXPR) BLOCK
 119     LABEL while (EXPR) BLOCK continue BLOCK
 120     LABEL for (EXPR; EXPR; EXPR) BLOCK
 121     LABEL foreach VAR (LIST) BLOCK
 122     LABEL BLOCK continue BLOCK
 123
 124 Note that, unlike C and Pascal, these are defined in terms of BLOCKs,
 125 not statements.  This means that the curly brackets are I<required>--no
 126 dangling statements allowed.  If you want to write conditionals without
 127 curly brackets there are several other ways to do it.  The following
 128 all do the same thing:
 129
 130     if (!open(FOO)) { die "Can't open $FOO: $!"; }
 131     die "Can't open $FOO: $!" unless open(FOO);
 132     open(FOO) or die "Can't open $FOO: $!";     # FOO or bust!
 133     open(FOO) ? 'hi mom' : die "Can't open $FOO: $!";
 134                         # a bit exotic, that last one
 135
 136 The C<if> statement is straightforward.  Because BLOCKs are always
 137 bounded by curly brackets, there is never any ambiguity about which
 138 C<if> an C<else> goes with.  If you use C<unless> in place of C<if>,
 139 the sense of the test is reversed.
 140
 141 The C<while> statement executes the block as long as the expression is
 142 true (does not evaluate to the null string or 0 or "0").  The LABEL is
 143 optional, and if present, consists of an identifier followed by a colon.
 144 The LABEL identifies the loop for the loop control statements C<next>,
 145 C<last>, and C<redo>.  If the LABEL is omitted, the loop control statement
 146 refers to the innermost enclosing loop.  This may include dynamically
 147 looking back your call-stack at run time to find the LABEL.  Such
 148 desperate behavior triggers a warning if you use the B<-w> flag.
 149
 150 If there is a C<continue> BLOCK, it is always executed just before the
 151 conditional is about to be evaluated again, just like the third part of a
 152 C<for> loop in C.  Thus it can be used to increment a loop variable, even
 153 when the loop has been continued via the C<next> statement (which is
 154 similar to the C C<continue> statement).
 155
 156 =head2 Loop Control
 157
 158 The C<next> command is like the C<continue> statement in C; it starts
 159 the next iteration of the loop:
 160
 161     LINE: while (<STDIN>) {
 162         next LINE if /^#/;      # discard comments
 163         ...
 164     }
 165
 166 The C<last> command is like the C<break> statement in C (as used in
 167 loops); it immediately exits the loop in question.  The
 168 C<continue> block, if any, is not executed:
 169
 170     LINE: while (<STDIN>) {
 171         last LINE if /^$/;      # exit when done with header
 172         ...
 173     }
 174
 175 The C<redo> command restarts the loop block without evaluating the
 176 conditional again.  The C<continue> block, if any, is I<not> executed.
 177 This command is normally used by programs that want to lie to themselves
 178 about what was just input.
 179
 180 For example, when processing a file like F</etc/termcap>.
 181 If your input lines might end in backslashes to indicate continuation, you
 182 want to skip ahead and get the next record.
 183
 184     while (<>) {
 185         chomp;
 186         if (s/\\$//) {
 187             $_ .= <>;
 188             redo unless eof();
 189         }
 190         # now process $_
 191     }
 192
 193 which is Perl short-hand for the more explicitly written version:
 194
 195     LINE: while (defined($line = <ARGV>)) {
 196         chomp($line);
 197         if ($line =~ s/\\$//) {
 198             $line .= <ARGV>;
 199             redo LINE unless eof(); # not eof(ARGV)!
 200         }
 201         # now process $line
 202     }
 203
 204 Or here's a simpleminded Pascal comment stripper (warning: assumes no
 205 { or } in strings).
 206
 207     LINE: while (<STDIN>) {
 208         while (s|({.*}.*){.*}|$1 |) {}
 209         s|{.*}| |;
 210         if (s|{.*| |) {
 211             $front = $_;
 212             while (<STDIN>) {
 213                 if (/}/) {      # end of comment?
 214                     s|^|$front{|;
 215                     redo LINE;
 216                 }
 217             }
 218         }
 219         print;
 220     }
 221
 222 Note that if there were a C<continue> block on the above code, it would get
 223 executed even on discarded lines.
 224
 225 If the word C<while> is replaced by the word C<until>, the sense of the
 226 test is reversed, but the conditional is still tested before the first
 227 iteration.
 228
 229 The form C<while/if BLOCK BLOCK>, available in Perl 4, is no longer
 230 available.   Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>.
 231
 232 =head2 For Loops
 233
 234 Perl's C-style C<for> loop works exactly like the corresponding C<while> loop;
 235 that means that this:
 236
 237     for ($i = 1; $i < 10; $i++) {
 238         ...
 239     }
 240
 241 is the same as this:
 242
 243     $i = 1;
 244     while ($i < 10) {
 245         ...
 246     } continue {
 247         $i++;
 248     }
 249
 250 (There is one minor difference: The first form implies a lexical scope
 251 for variables declared with C<my> in the initialization expression.)
 252
 253 Besides the normal array index looping, C<for> can lend itself
 254 to many other interesting applications.  Here's one that avoids the
 255 problem you get into if you explicitly test for end-of-file on
 256 an interactive file descriptor causing your program to appear to
 257 hang.
 258
 259     $on_a_tty = -t STDIN && -t STDOUT;
 260     sub prompt { print "yes? " if $on_a_tty }
 261     for ( prompt(); <STDIN>; prompt() ) {
 262         # do something
 263     }
 264
 265 =head2 Foreach Loops
 266
 267 The C<foreach> loop iterates over a normal list value and sets the
 268 variable VAR to be each element of the list in turn.  If the variable
 269 is preceded with the keyword C<my>, then it is lexically scoped, and
 270 is therefore visible only within the loop.  Otherwise, the variable is
 271 implicitly local to the loop and regains its former value upon exiting
 272 the loop.  If the variable was previously declared with C<my>, it uses
 273 that variable instead of the global one, but it's still localized to
 274 the loop.  (Note that a lexically scoped variable can cause problems
 275 if you have subroutine or format declarations within the loop which
 276 refer to it.)
 277
 278 The C<foreach> keyword is actually a synonym for the C<for> keyword, so
 279 you can use C<foreach> for readability or C<for> for brevity.  If VAR is
 280 omitted, $_ is set to each value.  If any element of LIST is an lvalue,
 281 you can modify it by modifying VAR inside the loop.  That's because
 282 the C<foreach> loop index variable is an implicit alias for each item
 283 in the list that you're looping over.
 284
 285 If any part of LIST is an array, C<foreach> will get very confused if
 286 you add or remove elements within the loop body, for example with
 287 C<splice>.   So don't do that.
 288
 289 C<foreach> probably won't do what you expect if VAR is a tied or other
 290 special variable.   Don't do that either.
 291
 292 Examples:
 293
 294     for (@ary) { s/foo/bar/ }
 295
 296     foreach my $elem (@elements) {
 297         $elem *= 2;
 298     }
 299
 300     for $count (10,9,8,7,6,5,4,3,2,1,'BOOM') {
 301         print $count, "\n"; sleep(1);
 302     }
 303
 304     for (1..15) { print "Merry Christmas\n"; }
 305
 306     foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
 307         print "Item: $item\n";
 308     }
 309
 310 Here's how a C programmer might code up a particular algorithm in Perl:
 311
 312     for (my $i = 0; $i < @ary1; $i++) {
 313         for (my $j = 0; $j < @ary2; $j++) {
 314             if ($ary1[$i] > $ary2[$j]) {
 315                 last; # can't go to outer :-(
 316             }
 317             $ary1[$i] += $ary2[$j];
 318         }
 319         # this is where that last takes me
 320     }
 321
 322 Whereas here's how a Perl programmer more comfortable with the idiom might
 323 do it:
 324
 325     OUTER: foreach my $wid (@ary1) {
 326     INNER:   foreach my $jet (@ary2) {
 327                 next OUTER if $wid > $jet;
 328                 $wid += $jet;
 329              }
 330           }
 331
 332 See how much easier this is?  It's cleaner, safer, and faster.  It's
 333 cleaner because it's less noisy.  It's safer because if code gets added
 334 between the inner and outer loops later on, the new code won't be
 335 accidentally executed.  The C<next> explicitly iterates the other loop
 336 rather than merely terminating the inner one.  And it's faster because
 337 Perl executes a C<foreach> statement more rapidly than it would the
 338 equivalent C<for> loop.
 339
 340 =head2 Basic BLOCKs and Switch Statements
 341
 342 A BLOCK by itself (labeled or not) is semantically equivalent to a
 343 loop that executes once.  Thus you can use any of the loop control
 344 statements in it to leave or restart the block.  (Note that this is
 345 I<NOT> true in C<eval{}>, C<sub{}>, or contrary to popular belief
 346 C<do{}> blocks, which do I<NOT> count as loops.)  The C<continue>
 347 block is optional.
 348
 349 The BLOCK construct is particularly nice for doing case
 350 structures.
 351
 352     SWITCH: {
 353         if (/^abc/) { $abc = 1; last SWITCH; }
 354         if (/^def/) { $def = 1; last SWITCH; }
 355         if (/^xyz/) { $xyz = 1; last SWITCH; }
 356         $nothing = 1;
 357     }
 358
 359 There is no official switch statement in Perl, because there are
 360 already several ways to write the equivalent.  In addition to the
 361 above, you could write
 362
 363     SWITCH: {
 364         $abc = 1, last SWITCH  if /^abc/;
 365         $def = 1, last SWITCH  if /^def/;
 366         $xyz = 1, last SWITCH  if /^xyz/;
 367         $nothing = 1;
 368     }
 369
 370 (That's actually not as strange as it looks once you realize that you can
 371 use loop control "operators" within an expression,  That's just the normal
 372 C comma operator.)
 373
 374 or
 375
 376     SWITCH: {
 377         /^abc/ && do { $abc = 1; last SWITCH; };
 378         /^def/ && do { $def = 1; last SWITCH; };
 379         /^xyz/ && do { $xyz = 1; last SWITCH; };
 380         $nothing = 1;
 381     }
 382
 383 or formatted so it stands out more as a "proper" switch statement:
 384
 385     SWITCH: {
 386         /^abc/      && do {
 387                             $abc = 1;
 388                             last SWITCH;
 389                        };
 390
 391         /^def/      && do {
 392                             $def = 1;
 393                             last SWITCH;
 394                        };
 395
 396         /^xyz/      && do {
 397                             $xyz = 1;
 398                             last SWITCH;
 399                         };
 400         $nothing = 1;
 401     }
 402
 403 or
 404
 405     SWITCH: {
 406         /^abc/ and $abc = 1, last SWITCH;
 407         /^def/ and $def = 1, last SWITCH;
 408         /^xyz/ and $xyz = 1, last SWITCH;
 409         $nothing = 1;
 410     }
 411
 412 or, using experimental C<EVAL blocks> of regular expressions
 413 (see L<perlre/"(?{ code })">),
 414
 415         / ^abc (?{ $abc = 1 })
 416          |
 417           ^def (?{  $def = 1 })
 418          |
 419           ^xyz (?{ $xyz = 1 })
 420          |
 421           (?{ $nothing = 1 })
 422         /x;
 423
 424 or even, horrors,
 425
 426     if (/^abc/)
 427         { $abc = 1 }
 428     elsif (/^def/)
 429         { $def = 1 }
 430     elsif (/^xyz/)
 431         { $xyz = 1 }
 432     else
 433         { $nothing = 1 }
 434
 435
 436 A common idiom for a switch statement is to use C<foreach>'s aliasing to make
 437 a temporary assignment to $_ for convenient matching:
 438
 439     SWITCH: for ($where) {
 440                 /In Card Names/     && do { push @flags, '-e'; last; };
 441                 /Anywhere/          && do { push @flags, '-h'; last; };
 442                 /In Rulings/        && do {                    last; };
 443                 die "unknown value for form variable where: `$where'";
 444             }
 445
 446 Another interesting approach to a switch statement is arrange
 447 for a C<do> block to return the proper value:
 448
 449     $amode = do {
 450         if     ($flag & O_RDONLY) { "r" }
 451         elsif  ($flag & O_WRONLY) { ($flag & O_APPEND) ? "a" : "w" }
 452         elsif  ($flag & O_RDWR)   {
 453             if ($flag & O_CREAT)  { "w+" }
 454             else                  { ($flag & O_APPEND) ? "a+" : "r+" }
 455         }
 456     };
 457
 458 =head2 Goto
 459
 460 Although not for the faint of heart, Perl does support a C<goto> statement.
 461 A loop's LABEL is not actually a valid target for a C<goto>;
 462 it's just the name of the loop.  There are three forms: goto-LABEL,
 463 goto-EXPR, and goto-&NAME.
 464
 465 The goto-LABEL form finds the statement labeled with LABEL and resumes
 466 execution there.  It may not be used to go into any construct that
 467 requires initialization, such as a subroutine or a foreach loop.  It
 468 also can't be used to go into a construct that is optimized away.  It
 469 can be used to go almost anywhere else within the dynamic scope,
 470 including out of subroutines, but it's usually better to use some other
 471 construct such as last or die.  The author of Perl has never felt the
 472 need to use this form of goto (in Perl, that is--C is another matter).
 473
 474 The goto-EXPR form expects a label name, whose scope will be resolved
 475 dynamically.  This allows for computed gotos per FORTRAN, but isn't
 476 necessarily recommended if you're optimizing for maintainability:
 477
 478     goto ("FOO", "BAR", "GLARCH")[$i];
 479
 480 The goto-&NAME form is highly magical, and substitutes a call to the
 481 named subroutine for the currently running subroutine.  This is used by
 482 AUTOLOAD() subroutines that wish to load another subroutine and then
 483 pretend that the other subroutine had been called in the first place
 484 (except that any modifications to @_ in the current subroutine are
 485 propagated to the other subroutine.)  After the C<goto>, not even caller()
 486 will be able to tell that this routine was called first.
 487
 488 In almost all cases like this, it's usually a far, far better idea to use the
 489 structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of
 490 resorting to a C<goto>.  For certain applications, the catch and throw pair of
 491 C<eval{}> and die() for exception processing can also be a prudent approach.
 492
 493 =head2 PODs: Embedded Documentation
 494
 495 Perl has a mechanism for intermixing documentation with source code.
 496 While it's expecting the beginning of a new statement, if the compiler
 497 encounters a line that begins with an equal sign and a word, like this
 498
 499     =head1 Here There Be Pods!
 500
 501 Then that text and all remaining text up through and including a line
 502 beginning with C<=cut> will be ignored.  The format of the intervening
 503 text is described in L<perlpod>.
 504
 505 This allows you to intermix your source code
 506 and your documentation text freely, as in
 507
 508     =item snazzle($)
 509
 510     The snazzle() function will behave in the most spectacular
 511     form that you can possibly imagine, not even excepting
 512     cybernetic pyrotechnics.
 513
 514     =cut back to the compiler, nuff of this pod stuff!
 515
 516     sub snazzle($) {
 517         my $thingie = shift;
 518         .........
 519     }
 520
 521 Note that pod translators should look at only paragraphs beginning
 522 with a pod directive (it makes parsing easier), whereas the compiler
 523 actually knows to look for pod escapes even in the middle of a
 524 paragraph.  This means that the following secret stuff will be
 525 ignored by both the compiler and the translators.
 526
 527     $a=3;
 528     =secret stuff
 529      warn "Neither POD nor CODE!?"
 530     =cut back
 531     print "got $a\n";
 532
 533 You probably shouldn't rely upon the warn() being podded out forever.
 534 Not all pod translators are well-behaved in this regard, and perhaps
 535 the compiler will become pickier.
 536
 537 One may also use pod directives to quickly comment out a section
 538 of code.
 539
 540 =head2 Plain Old Comments (Not!)
 541
 542 Much like the C preprocessor, perl can process line directives.  Using
 543 this, one can control perl's idea of filenames and line numbers in
 544 error or warning messages (especially for strings that are processed
 545 with eval()).  The syntax for this mechanism is the same as for most
 546 C preprocessors: it matches the regular expression
 547 C</^#\s*line\s+(\d+)\s*(?:\s"([^"]*)")?/> with C<$1> being the line
 548 number for the next line, and C<$2> being the optional filename
 549 (specified within quotes).
 550
 551 Here are some examples that you should be able to type into your command
 552 shell:
 553
 554     % perl
 555     # line 200 "bzzzt"
 556     # the `#' on the previous line must be the first char on line
 557     die 'foo';
 558     __END__
 559     foo at bzzzt line 201.
 560
 561     % perl
 562     # line 200 "bzzzt"
 563     eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
 564     __END__
 565     foo at - line 2001.
 566
 567     % perl
 568     eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
 569     __END__
 570     foo at foo bar line 200.
 571
 572     % perl
 573     # line 345 "goop"
 574     eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
 575     print $@;
 576     __END__
 577     foo at goop line 345.
 578
 579 =cut