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