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