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