This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
pod updates (from David Adler, M J T Guy)
[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
19799a22 56Note that my() functions as a list operator, not as a unary operator; so
54310121
PP
57be careful to use C<or> instead of C<||> in this case. However, if
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
174desperate behavior triggers a warning if you use the B<-w> flag.
3ce0d271
GS
175Unlike a C<foreach> statement, a C<while> statement never implicitly
176localises any variables.
4633a7c4
LW
177
178If there is a C<continue> BLOCK, it is always executed just before the
179conditional is about to be evaluated again, just like the third part of a
180C<for> loop in C. Thus it can be used to increment a loop variable, even
181when the loop has been continued via the C<next> statement (which is
182similar to the C C<continue> statement).
183
184=head2 Loop Control
185
186The C<next> command is like the C<continue> statement in C; it starts
187the next iteration of the loop:
188
189 LINE: while (<STDIN>) {
190 next LINE if /^#/; # discard comments
191 ...
192 }
193
194The C<last> command is like the C<break> statement in C (as used in
195loops); it immediately exits the loop in question. The
196C<continue> block, if any, is not executed:
197
198 LINE: while (<STDIN>) {
199 last LINE if /^$/; # exit when done with header
200 ...
201 }
202
203The C<redo> command restarts the loop block without evaluating the
204conditional again. The C<continue> block, if any, is I<not> executed.
205This command is normally used by programs that want to lie to themselves
206about what was just input.
207
208For example, when processing a file like F</etc/termcap>.
209If your input lines might end in backslashes to indicate continuation, you
210want to skip ahead and get the next record.
211
212 while (<>) {
213 chomp;
54310121
PP
214 if (s/\\$//) {
215 $_ .= <>;
4633a7c4
LW
216 redo unless eof();
217 }
218 # now process $_
54310121 219 }
4633a7c4
LW
220
221which is Perl short-hand for the more explicitly written version:
222
54310121 223 LINE: while (defined($line = <ARGV>)) {
4633a7c4 224 chomp($line);
54310121
PP
225 if ($line =~ s/\\$//) {
226 $line .= <ARGV>;
4633a7c4
LW
227 redo LINE unless eof(); # not eof(ARGV)!
228 }
229 # now process $line
54310121 230 }
4633a7c4 231
5a964f20
TC
232Note that if there were a C<continue> block on the above code, it would get
233executed even on discarded lines. This is often used to reset line counters
234or C<?pat?> one-time matches.
4633a7c4 235
5a964f20
TC
236 # inspired by :1,$g/fred/s//WILMA/
237 while (<>) {
238 ?(fred)? && s//WILMA $1 WILMA/;
239 ?(barney)? && s//BETTY $1 BETTY/;
240 ?(homer)? && s//MARGE $1 MARGE/;
241 } continue {
242 print "$ARGV $.: $_";
243 close ARGV if eof(); # reset $.
244 reset if eof(); # reset ?pat?
4633a7c4
LW
245 }
246
a0d0e21e
LW
247If the word C<while> is replaced by the word C<until>, the sense of the
248test is reversed, but the conditional is still tested before the first
249iteration.
250
5a964f20
TC
251The loop control statements don't work in an C<if> or C<unless>, since
252they aren't loops. You can double the braces to make them such, though.
253
254 if (/pattern/) {{
255 next if /fred/;
256 next if /barney/;
257 # so something here
258 }}
259
5b23ba8b
G
260The form C<while/if BLOCK BLOCK>, available in Perl 4, is no longer
261available. Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>.
4633a7c4 262
cb1a09d0 263=head2 For Loops
a0d0e21e 264
cb1a09d0
AD
265Perl's C-style C<for> loop works exactly like the corresponding C<while> loop;
266that means that this:
a0d0e21e
LW
267
268 for ($i = 1; $i < 10; $i++) {
269 ...
270 }
271
cb1a09d0 272is the same as this:
a0d0e21e
LW
273
274 $i = 1;
275 while ($i < 10) {
276 ...
277 } continue {
278 $i++;
279 }
280
55497cff
PP
281(There is one minor difference: The first form implies a lexical scope
282for variables declared with C<my> in the initialization expression.)
283
cb1a09d0
AD
284Besides the normal array index looping, C<for> can lend itself
285to many other interesting applications. Here's one that avoids the
54310121
PP
286problem you get into if you explicitly test for end-of-file on
287an interactive file descriptor causing your program to appear to
cb1a09d0
AD
288hang.
289
290 $on_a_tty = -t STDIN && -t STDOUT;
291 sub prompt { print "yes? " if $on_a_tty }
292 for ( prompt(); <STDIN>; prompt() ) {
293 # do something
54310121 294 }
cb1a09d0
AD
295
296=head2 Foreach Loops
297
4633a7c4 298The C<foreach> loop iterates over a normal list value and sets the
55497cff
PP
299variable VAR to be each element of the list in turn. If the variable
300is preceded with the keyword C<my>, then it is lexically scoped, and
301is therefore visible only within the loop. Otherwise, the variable is
302implicitly local to the loop and regains its former value upon exiting
303the loop. If the variable was previously declared with C<my>, it uses
304that variable instead of the global one, but it's still localized to
19799a22 305the loop.
4633a7c4
LW
306
307The C<foreach> keyword is actually a synonym for the C<for> keyword, so
5a964f20
TC
308you can use C<foreach> for readability or C<for> for brevity. (Or because
309the Bourne shell is more familiar to you than I<csh>, so writing C<for>
f86cebdf 310comes more naturally.) If VAR is omitted, C<$_> is set to each value.
5a964f20
TC
311If any element of LIST is an lvalue, you can modify it by modifying VAR
312inside the loop. That's because the C<foreach> loop index variable is
313an implicit alias for each item in the list that you're looping over.
302617ea
G
314
315If any part of LIST is an array, C<foreach> will get very confused if
316you add or remove elements within the loop body, for example with
317C<splice>. So don't do that.
318
319C<foreach> probably won't do what you expect if VAR is a tied or other
320special variable. Don't do that either.
4633a7c4 321
748a9306 322Examples:
a0d0e21e 323
4633a7c4 324 for (@ary) { s/foo/bar/ }
a0d0e21e 325
55497cff 326 foreach my $elem (@elements) {
a0d0e21e
LW
327 $elem *= 2;
328 }
329
4633a7c4
LW
330 for $count (10,9,8,7,6,5,4,3,2,1,'BOOM') {
331 print $count, "\n"; sleep(1);
a0d0e21e
LW
332 }
333
334 for (1..15) { print "Merry Christmas\n"; }
335
4633a7c4 336 foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
a0d0e21e
LW
337 print "Item: $item\n";
338 }
339
4633a7c4
LW
340Here's how a C programmer might code up a particular algorithm in Perl:
341
55497cff
PP
342 for (my $i = 0; $i < @ary1; $i++) {
343 for (my $j = 0; $j < @ary2; $j++) {
4633a7c4
LW
344 if ($ary1[$i] > $ary2[$j]) {
345 last; # can't go to outer :-(
346 }
347 $ary1[$i] += $ary2[$j];
348 }
cb1a09d0 349 # this is where that last takes me
4633a7c4
LW
350 }
351
184e9718 352Whereas here's how a Perl programmer more comfortable with the idiom might
cb1a09d0 353do it:
4633a7c4 354
54310121 355 OUTER: foreach my $wid (@ary1) {
55497cff 356 INNER: foreach my $jet (@ary2) {
cb1a09d0
AD
357 next OUTER if $wid > $jet;
358 $wid += $jet;
54310121
PP
359 }
360 }
4633a7c4 361
cb1a09d0
AD
362See how much easier this is? It's cleaner, safer, and faster. It's
363cleaner because it's less noisy. It's safer because if code gets added
c07a80fd 364between the inner and outer loops later on, the new code won't be
5f05dabc 365accidentally executed. The C<next> explicitly iterates the other loop
c07a80fd
PP
366rather than merely terminating the inner one. And it's faster because
367Perl executes a C<foreach> statement more rapidly than it would the
368equivalent C<for> loop.
4633a7c4
LW
369
370=head2 Basic BLOCKs and Switch Statements
371
55497cff
PP
372A BLOCK by itself (labeled or not) is semantically equivalent to a
373loop that executes once. Thus you can use any of the loop control
374statements in it to leave or restart the block. (Note that this is
375I<NOT> true in C<eval{}>, C<sub{}>, or contrary to popular belief
376C<do{}> blocks, which do I<NOT> count as loops.) The C<continue>
377block is optional.
4633a7c4
LW
378
379The BLOCK construct is particularly nice for doing case
a0d0e21e
LW
380structures.
381
382 SWITCH: {
383 if (/^abc/) { $abc = 1; last SWITCH; }
384 if (/^def/) { $def = 1; last SWITCH; }
385 if (/^xyz/) { $xyz = 1; last SWITCH; }
386 $nothing = 1;
387 }
388
f86cebdf 389There is no official C<switch> statement in Perl, because there are
a0d0e21e
LW
390already several ways to write the equivalent. In addition to the
391above, you could write
392
393 SWITCH: {
394 $abc = 1, last SWITCH if /^abc/;
395 $def = 1, last SWITCH if /^def/;
396 $xyz = 1, last SWITCH if /^xyz/;
397 $nothing = 1;
398 }
399
cb1a09d0 400(That's actually not as strange as it looks once you realize that you can
a0d0e21e
LW
401use loop control "operators" within an expression, That's just the normal
402C comma operator.)
403
404or
405
406 SWITCH: {
407 /^abc/ && do { $abc = 1; last SWITCH; };
408 /^def/ && do { $def = 1; last SWITCH; };
409 /^xyz/ && do { $xyz = 1; last SWITCH; };
410 $nothing = 1;
411 }
412
f86cebdf 413or formatted so it stands out more as a "proper" C<switch> statement:
a0d0e21e
LW
414
415 SWITCH: {
54310121
PP
416 /^abc/ && do {
417 $abc = 1;
418 last SWITCH;
a0d0e21e
LW
419 };
420
54310121
PP
421 /^def/ && do {
422 $def = 1;
423 last SWITCH;
a0d0e21e
LW
424 };
425
54310121
PP
426 /^xyz/ && do {
427 $xyz = 1;
428 last SWITCH;
a0d0e21e
LW
429 };
430 $nothing = 1;
431 }
432
433or
434
435 SWITCH: {
436 /^abc/ and $abc = 1, last SWITCH;
437 /^def/ and $def = 1, last SWITCH;
438 /^xyz/ and $xyz = 1, last SWITCH;
439 $nothing = 1;
440 }
441
442or even, horrors,
443
444 if (/^abc/)
445 { $abc = 1 }
446 elsif (/^def/)
447 { $def = 1 }
448 elsif (/^xyz/)
449 { $xyz = 1 }
450 else
451 { $nothing = 1 }
452
f86cebdf
GS
453A common idiom for a C<switch> statement is to use C<foreach>'s aliasing to make
454a temporary assignment to C<$_> for convenient matching:
4633a7c4
LW
455
456 SWITCH: for ($where) {
457 /In Card Names/ && do { push @flags, '-e'; last; };
458 /Anywhere/ && do { push @flags, '-h'; last; };
459 /In Rulings/ && do { last; };
460 die "unknown value for form variable where: `$where'";
54310121 461 }
4633a7c4 462
cb1a09d0
AD
463Another interesting approach to a switch statement is arrange
464for a C<do> block to return the proper value:
465
466 $amode = do {
5a964f20 467 if ($flag & O_RDONLY) { "r" } # XXX: isn't this 0?
54310121 468 elsif ($flag & O_WRONLY) { ($flag & O_APPEND) ? "a" : "w" }
cb1a09d0
AD
469 elsif ($flag & O_RDWR) {
470 if ($flag & O_CREAT) { "w+" }
c07a80fd 471 else { ($flag & O_APPEND) ? "a+" : "r+" }
cb1a09d0
AD
472 }
473 };
474
5a964f20
TC
475Or
476
477 print do {
478 ($flags & O_WRONLY) ? "write-only" :
479 ($flags & O_RDWR) ? "read-write" :
480 "read-only";
481 };
482
483Or if you are certainly that all the C<&&> clauses are true, you can use
484something like this, which "switches" on the value of the
f86cebdf 485C<HTTP_USER_AGENT> envariable.
5a964f20
TC
486
487 #!/usr/bin/perl
488 # pick out jargon file page based on browser
489 $dir = 'http://www.wins.uva.nl/~mes/jargon';
490 for ($ENV{HTTP_USER_AGENT}) {
491 $page = /Mac/ && 'm/Macintrash.html'
492 || /Win(dows )?NT/ && 'e/evilandrude.html'
493 || /Win|MSIE|WebTV/ && 'm/MicroslothWindows.html'
494 || /Linux/ && 'l/Linux.html'
495 || /HP-UX/ && 'h/HP-SUX.html'
496 || /SunOS/ && 's/ScumOS.html'
497 || 'a/AppendixB.html';
498 }
499 print "Location: $dir/$page\015\012\015\012";
500
501That kind of switch statement only works when you know the C<&&> clauses
502will be true. If you don't, the previous C<?:> example should be used.
503
19799a22
GS
504You might also consider writing a hash of subroutine references
505instead of synthesizing a C<switch> statement.
5a964f20 506
4633a7c4
LW
507=head2 Goto
508
19799a22
GS
509Although not for the faint of heart, Perl does support a C<goto>
510statement. There are three forms: C<goto>-LABEL, C<goto>-EXPR, and
511C<goto>-&NAME. A loop's LABEL is not actually a valid target for
512a C<goto>; it's just the name of the loop.
4633a7c4 513
f86cebdf 514The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
4633a7c4 515execution there. It may not be used to go into any construct that
f86cebdf 516requires initialization, such as a subroutine or a C<foreach> loop. It
4633a7c4
LW
517also can't be used to go into a construct that is optimized away. It
518can be used to go almost anywhere else within the dynamic scope,
519including out of subroutines, but it's usually better to use some other
f86cebdf
GS
520construct such as C<last> or C<die>. The author of Perl has never felt the
521need to use this form of C<goto> (in Perl, that is--C is another matter).
4633a7c4 522
f86cebdf
GS
523The C<goto>-EXPR form expects a label name, whose scope will be resolved
524dynamically. This allows for computed C<goto>s per FORTRAN, but isn't
4633a7c4
LW
525necessarily recommended if you're optimizing for maintainability:
526
527 goto ("FOO", "BAR", "GLARCH")[$i];
528
f86cebdf 529The C<goto>-&NAME form is highly magical, and substitutes a call to the
4633a7c4 530named subroutine for the currently running subroutine. This is used by
f86cebdf 531C<AUTOLOAD()> subroutines that wish to load another subroutine and then
4633a7c4 532pretend that the other subroutine had been called in the first place
f86cebdf
GS
533(except that any modifications to C<@_> in the current subroutine are
534propagated to the other subroutine.) After the C<goto>, not even C<caller()>
4633a7c4
LW
535will be able to tell that this routine was called first.
536
c07a80fd
PP
537In almost all cases like this, it's usually a far, far better idea to use the
538structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of
4633a7c4
LW
539resorting to a C<goto>. For certain applications, the catch and throw pair of
540C<eval{}> and die() for exception processing can also be a prudent approach.
cb1a09d0
AD
541
542=head2 PODs: Embedded Documentation
543
544Perl has a mechanism for intermixing documentation with source code.
c07a80fd 545While it's expecting the beginning of a new statement, if the compiler
cb1a09d0
AD
546encounters a line that begins with an equal sign and a word, like this
547
548 =head1 Here There Be Pods!
549
550Then that text and all remaining text up through and including a line
551beginning with C<=cut> will be ignored. The format of the intervening
54310121 552text is described in L<perlpod>.
cb1a09d0
AD
553
554This allows you to intermix your source code
555and your documentation text freely, as in
556
557 =item snazzle($)
558
54310121 559 The snazzle() function will behave in the most spectacular
cb1a09d0
AD
560 form that you can possibly imagine, not even excepting
561 cybernetic pyrotechnics.
562
563 =cut back to the compiler, nuff of this pod stuff!
564
565 sub snazzle($) {
566 my $thingie = shift;
567 .........
54310121 568 }
cb1a09d0 569
54310121 570Note that pod translators should look at only paragraphs beginning
184e9718 571with a pod directive (it makes parsing easier), whereas the compiler
54310121 572actually knows to look for pod escapes even in the middle of a
cb1a09d0
AD
573paragraph. This means that the following secret stuff will be
574ignored by both the compiler and the translators.
575
576 $a=3;
577 =secret stuff
578 warn "Neither POD nor CODE!?"
579 =cut back
580 print "got $a\n";
581
f86cebdf 582You probably shouldn't rely upon the C<warn()> being podded out forever.
cb1a09d0
AD
583Not all pod translators are well-behaved in this regard, and perhaps
584the compiler will become pickier.
774d564b
PP
585
586One may also use pod directives to quickly comment out a section
587of code.
588
589=head2 Plain Old Comments (Not!)
590
5a964f20
TC
591Much like the C preprocessor, Perl can process line directives. Using
592this, one can control Perl's idea of filenames and line numbers in
774d564b 593error or warning messages (especially for strings that are processed
f86cebdf 594with C<eval()>). The syntax for this mechanism is the same as for most
774d564b 595C preprocessors: it matches the regular expression
4b094ceb 596C</^#\s*line\s+(\d+)\s*(?:\s"([^"]*)")?/> with C<$1> being the line
774d564b
PP
597number for the next line, and C<$2> being the optional filename
598(specified within quotes).
599
600Here are some examples that you should be able to type into your command
601shell:
602
603 % perl
604 # line 200 "bzzzt"
605 # the `#' on the previous line must be the first char on line
606 die 'foo';
607 __END__
608 foo at bzzzt line 201.
54310121 609
774d564b
PP
610 % perl
611 # line 200 "bzzzt"
612 eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
613 __END__
614 foo at - line 2001.
54310121 615
774d564b
PP
616 % perl
617 eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
618 __END__
619 foo at foo bar line 200.
54310121 620
774d564b
PP
621 % perl
622 # line 345 "goop"
623 eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
624 print $@;
625 __END__
626 foo at goop line 345.
627
628=cut