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