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