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