This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl 3.0 patch #33 patch #29, continued
[perl5.git] / perl.man.1
1 .rn '' }`
2 ''' $Header: perl_man.1,v 3.0.1.8 90/10/15 18:16:19 lwall Locked $
3 ''' 
4 ''' $Log:       perl.man.1,v $
5 ''' Revision 3.0.1.8  90/10/15  18:16:19  lwall
6 ''' patch29: added DATA filehandle to read stuff after __END__
7 ''' patch29: added cmp and <=>
8 ''' patch29: added -M, -A and -C
9 ''' 
10 ''' Revision 3.0.1.7  90/08/09  04:24:03  lwall
11 ''' patch19: added -x switch to extract script from input trash
12 ''' patch19: Added -c switch to do compilation only
13 ''' patch19: bare identifiers are now strings if no other interpretation possible
14 ''' patch19: -s now returns size of file
15 ''' patch19: Added __LINE__ and __FILE__ tokens
16 ''' patch19: Added __END__ token
17 ''' 
18 ''' Revision 3.0.1.6  90/08/03  11:14:44  lwall
19 ''' patch19: Intermediate diffs for Randal
20 ''' 
21 ''' Revision 3.0.1.5  90/03/27  16:14:37  lwall
22 ''' patch16: .. now works using magical string increment
23 ''' 
24 ''' Revision 3.0.1.4  90/03/12  16:44:33  lwall
25 ''' patch13: (LIST,) now legal
26 ''' patch13: improved LIST documentation
27 ''' patch13: example of if-elsif switch was wrong  
28 ''' 
29 ''' Revision 3.0.1.3  90/02/28  17:54:32  lwall
30 ''' patch9: @array in scalar context now returns length of array
31 ''' patch9: in manual, example of open and ?: was backwards
32 ''' 
33 ''' Revision 3.0.1.2  89/11/17  15:30:03  lwall
34 ''' patch5: fixed some manual typos and indent problems
35 ''' 
36 ''' Revision 3.0.1.1  89/11/11  04:41:22  lwall
37 ''' patch2: explained about sh and ${1+"$@"}
38 ''' patch2: documented that space must separate word and '' string
39 ''' 
40 ''' Revision 3.0  89/10/18  15:21:29  lwall
41 ''' 3.0 baseline
42 ''' 
43 ''' 
44 .de Sh
45 .br
46 .ne 5
47 .PP
48 \fB\\$1\fR
49 .PP
50 ..
51 .de Sp
52 .if t .sp .5v
53 .if n .sp
54 ..
55 .de Ip
56 .br
57 .ie \\n.$>=3 .ne \\$3
58 .el .ne 3
59 .IP "\\$1" \\$2
60 ..
61 '''
62 '''     Set up \*(-- to give an unbreakable dash;
63 '''     string Tr holds user defined translation string.
64 '''     Bell System Logo is used as a dummy character.
65 '''
66 .tr \(*W-|\(bv\*(Tr
67 .ie n \{\
68 .ds -- \(*W-
69 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
70 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
71 .ds L" ""
72 .ds R" ""
73 .ds L' '
74 .ds R' '
75 'br\}
76 .el\{\
77 .ds -- \(em\|
78 .tr \*(Tr
79 .ds L" ``
80 .ds R" ''
81 .ds L' `
82 .ds R' '
83 'br\}
84 .TH PERL 1 "\*(RP"
85 .UC
86 .SH NAME
87 perl \- Practical Extraction and Report Language
88 .SH SYNOPSIS
89 .B perl
90 [options] filename args
91 .SH DESCRIPTION
92 .I Perl
93 is an interpreted language optimized for scanning arbitrary text files,
94 extracting information from those text files, and printing reports based
95 on that information.
96 It's also a good language for many system management tasks.
97 The language is intended to be practical (easy to use, efficient, complete)
98 rather than beautiful (tiny, elegant, minimal).
99 It combines (in the author's opinion, anyway) some of the best features of C,
100 \fIsed\fR, \fIawk\fR, and \fIsh\fR,
101 so people familiar with those languages should have little difficulty with it.
102 (Language historians will also note some vestiges of \fIcsh\fR, Pascal, and
103 even BASIC-PLUS.)
104 Expression syntax corresponds quite closely to C expression syntax.
105 Unlike most Unix utilities,
106 .I perl
107 does not arbitrarily limit the size of your data\*(--if you've got
108 the memory,
109 .I perl
110 can slurp in your whole file as a single string.
111 Recursion is of unlimited depth.
112 And the hash tables used by associative arrays grow as necessary to prevent
113 degraded performance.
114 .I Perl
115 uses sophisticated pattern matching techniques to scan large amounts of
116 data very quickly.
117 Although optimized for scanning text,
118 .I perl
119 can also deal with binary data, and can make dbm files look like associative
120 arrays (where dbm is available).
121 Setuid
122 .I perl
123 scripts are safer than C programs
124 through a dataflow tracing mechanism which prevents many stupid security holes.
125 If you have a problem that would ordinarily use \fIsed\fR
126 or \fIawk\fR or \fIsh\fR, but it
127 exceeds their capabilities or must run a little faster,
128 and you don't want to write the silly thing in C, then
129 .I perl
130 may be for you.
131 There are also translators to turn your
132 .I sed
133 and
134 .I awk
135 scripts into
136 .I perl
137 scripts.
138 OK, enough hype.
139 .PP
140 Upon startup,
141 .I perl
142 looks for your script in one of the following places:
143 .Ip 1. 4 2
144 Specified line by line via
145 .B \-e
146 switches on the command line.
147 .Ip 2. 4 2
148 Contained in the file specified by the first filename on the command line.
149 (Note that systems supporting the #! notation invoke interpreters this way.)
150 .Ip 3. 4 2
151 Passed in implicitly via standard input.
152 This only works if there are no filename arguments\*(--to pass
153 arguments to a
154 .I stdin
155 script you must explicitly specify a \- for the script name.
156 .PP
157 After locating your script,
158 .I perl
159 compiles it to an internal form.
160 If the script is syntactically correct, it is executed.
161 .Sh "Options"
162 Note: on first reading this section may not make much sense to you.  It's here
163 at the front for easy reference.
164 .PP
165 A single-character option may be combined with the following option, if any.
166 This is particularly useful when invoking a script using the #! construct which
167 only allows one argument.  Example:
168 .nf
169
170 .ne 2
171         #!/usr/bin/perl \-spi.bak       # same as \-s \-p \-i.bak
172         .\|.\|.
173
174 .fi
175 Options include:
176 .TP 5
177 .B \-a
178 turns on autosplit mode when used with a
179 .B \-n
180 or
181 .BR \-p .
182 An implicit split command to the @F array
183 is done as the first thing inside the implicit while loop produced by
184 the
185 .B \-n
186 or
187 .BR \-p .
188 .nf
189
190         perl \-ane \'print pop(@F), "\en";\'
191
192 is equivalent to
193
194         while (<>) {
195                 @F = split(\' \');
196                 print pop(@F), "\en";
197         }
198
199 .fi
200 .TP 5
201 .B \-c
202 causes
203 .I perl
204 to check the syntax of the script and then exit without executing it.
205 .TP 5
206 .BI \-d
207 runs the script under the perl debugger.
208 See the section on Debugging.
209 .TP 5
210 .BI \-D number
211 sets debugging flags.
212 To watch how it executes your script, use
213 .BR \-D14 .
214 (This only works if debugging is compiled into your
215 .IR perl .)
216 Another nice value is \-D1024, which lists your compiled syntax tree.
217 And \-D512 displays compiled regular expressions.
218 .TP 5
219 .BI \-e " commandline"
220 may be used to enter one line of script.
221 Multiple
222 .B \-e
223 commands may be given to build up a multi-line script.
224 If
225 .B \-e
226 is given,
227 .I perl
228 will not look for a script filename in the argument list.
229 .TP 5
230 .BI \-i extension
231 specifies that files processed by the <> construct are to be edited
232 in-place.
233 It does this by renaming the input file, opening the output file by the
234 same name, and selecting that output file as the default for print statements.
235 The extension, if supplied, is added to the name of the
236 old file to make a backup copy.
237 If no extension is supplied, no backup is made.
238 Saying \*(L"perl \-p \-i.bak \-e "s/foo/bar/;" .\|.\|. \*(R" is the same as using
239 the script:
240 .nf
241
242 .ne 2
243         #!/usr/bin/perl \-pi.bak
244         s/foo/bar/;
245
246 which is equivalent to
247
248 .ne 14
249         #!/usr/bin/perl
250         while (<>) {
251                 if ($ARGV ne $oldargv) {
252                         rename($ARGV, $ARGV . \'.bak\');
253                         open(ARGVOUT, ">$ARGV");
254                         select(ARGVOUT);
255                         $oldargv = $ARGV;
256                 }
257                 s/foo/bar/;
258         }
259         continue {
260             print;      # this prints to original filename
261         }
262         select(STDOUT);
263
264 .fi
265 except that the
266 .B \-i
267 form doesn't need to compare $ARGV to $oldargv to know when
268 the filename has changed.
269 It does, however, use ARGVOUT for the selected filehandle.
270 Note that
271 .I STDOUT
272 is restored as the default output filehandle after the loop.
273 .Sp
274 You can use eof to locate the end of each input file, in case you want
275 to append to each file, or reset line numbering (see example under eof).
276 .TP 5
277 .BI \-I directory
278 may be used in conjunction with
279 .B \-P
280 to tell the C preprocessor where to look for include files.
281 By default /usr/include and /usr/lib/perl are searched.
282 .TP 5
283 .B \-n
284 causes
285 .I perl
286 to assume the following loop around your script, which makes it iterate
287 over filename arguments somewhat like \*(L"sed \-n\*(R" or \fIawk\fR:
288 .nf
289
290 .ne 3
291         while (<>) {
292                 .\|.\|.         # your script goes here
293         }
294
295 .fi
296 Note that the lines are not printed by default.
297 See
298 .B \-p
299 to have lines printed.
300 Here is an efficient way to delete all files older than a week:
301 .nf
302
303         find . \-mtime +7 \-print | perl \-ne \'chop;unlink;\'
304
305 .fi
306 This is faster than using the \-exec switch of find because you don't have to
307 start a process on every filename found.
308 .TP 5
309 .B \-p
310 causes
311 .I perl
312 to assume the following loop around your script, which makes it iterate
313 over filename arguments somewhat like \fIsed\fR:
314 .nf
315
316 .ne 5
317         while (<>) {
318                 .\|.\|.         # your script goes here
319         } continue {
320                 print;
321         }
322
323 .fi
324 Note that the lines are printed automatically.
325 To suppress printing use the
326 .B \-n
327 switch.
328 A
329 .B \-p
330 overrides a
331 .B \-n
332 switch.
333 .TP 5
334 .B \-P
335 causes your script to be run through the C preprocessor before
336 compilation by
337 .IR perl .
338 (Since both comments and cpp directives begin with the # character,
339 you should avoid starting comments with any words recognized
340 by the C preprocessor such as \*(L"if\*(R", \*(L"else\*(R" or \*(L"define\*(R".)
341 .TP 5
342 .B \-s
343 enables some rudimentary switch parsing for switches on the command line
344 after the script name but before any filename arguments (or before a \-\|\-).
345 Any switch found there is removed from @ARGV and sets the corresponding variable in the
346 .I perl
347 script.
348 The following script prints \*(L"true\*(R" if and only if the script is
349 invoked with a \-xyz switch.
350 .nf
351
352 .ne 2
353         #!/usr/bin/perl \-s
354         if ($xyz) { print "true\en"; }
355
356 .fi
357 .TP 5
358 .B \-S
359 makes
360 .I perl
361 use the PATH environment variable to search for the script
362 (unless the name of the script starts with a slash).
363 Typically this is used to emulate #! startup on machines that don't
364 support #!, in the following manner:
365 .nf
366
367         #!/usr/bin/perl
368         eval "exec /usr/bin/perl \-S $0 $*"
369                 if $running_under_some_shell;
370
371 .fi
372 The system ignores the first line and feeds the script to /bin/sh,
373 which proceeds to try to execute the
374 .I perl
375 script as a shell script.
376 The shell executes the second line as a normal shell command, and thus
377 starts up the
378 .I perl
379 interpreter.
380 On some systems $0 doesn't always contain the full pathname,
381 so the
382 .B \-S
383 tells
384 .I perl
385 to search for the script if necessary.
386 After
387 .I perl
388 locates the script, it parses the lines and ignores them because
389 the variable $running_under_some_shell is never true.
390 A better construct than $* would be ${1+"$@"}, which handles embedded spaces
391 and such in the filenames, but doesn't work if the script is being interpreted
392 by csh.
393 In order to start up sh rather than csh, some systems may have to replace the
394 #! line with a line containing just
395 a colon, which will be politely ignored by perl.
396 Other systems can't control that, and need a totally devious construct that
397 will work under any of csh, sh or perl, such as the following:
398 .nf
399
400 .ne 3
401         eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
402         & eval 'exec /usr/bin/perl -S $0 $argv:q'
403                 if 0;
404
405 .fi
406 .TP 5
407 .B \-u
408 causes
409 .I perl
410 to dump core after compiling your script.
411 You can then take this core dump and turn it into an executable file
412 by using the undump program (not supplied).
413 This speeds startup at the expense of some disk space (which you can
414 minimize by stripping the executable).
415 (Still, a "hello world" executable comes out to about 200K on my machine.)
416 If you are going to run your executable as a set-id program then you
417 should probably compile it using taintperl rather than normal perl.
418 If you want to execute a portion of your script before dumping, use the
419 dump operator instead.
420 Note: availability of undump is platform specific and may not be available
421 for a specific port of perl.
422 .TP 5
423 .B \-U
424 allows
425 .I perl
426 to do unsafe operations.
427 Currently the only \*(L"unsafe\*(R" operation is the unlinking of directories while
428 running as superuser.
429 .TP 5
430 .B \-v
431 prints the version and patchlevel of your
432 .I perl
433 executable.
434 .TP 5
435 .B \-w
436 prints warnings about identifiers that are mentioned only once, and scalar
437 variables that are used before being set.
438 Also warns about redefined subroutines, and references to undefined
439 filehandles or filehandles opened readonly that you are attempting to
440 write on.
441 Also warns you if you use == on values that don't look like numbers, and if
442 your subroutines recurse more than 100 deep.
443 .TP 5
444 .BI \-x directory
445 tells
446 .I perl
447 that the script is embedded in a message.
448 Leading garbage will be discarded until the first line that starts
449 with #! and contains the string "perl".
450 Any meaningful switches on that line will be applied (but only one
451 group of switches, as with normal #! processing).
452 If a directory name is specified, Perl will switch to that directory
453 before running the script.
454 The
455 .B \-x
456 switch only controls the the disposal of leading garbage.
457 The script must be terminated with __END__ if there is trailing garbage
458 to be ignored (the script can process any or all of the trailing garbage
459 via the DATA filehandle if desired).
460 .Sh "Data Types and Objects"
461 .PP
462 .I Perl
463 has three data types: scalars, arrays of scalars, and
464 associative arrays of scalars.
465 Normal arrays are indexed by number, and associative arrays by string.
466 .PP
467 The interpretation of operations and values in perl sometimes
468 depends on the requirements
469 of the context around the operation or value.
470 There are three major contexts: string, numeric and array.
471 Certain operations return array values
472 in contexts wanting an array, and scalar values otherwise.
473 (If this is true of an operation it will be mentioned in the documentation
474 for that operation.)
475 Operations which return scalars don't care whether the context is looking
476 for a string or a number, but
477 scalar variables and values are interpreted as strings or numbers
478 as appropriate to the context.
479 A scalar is interpreted as TRUE in the boolean sense if it is not the null
480 string or 0.
481 Booleans returned by operators are 1 for true and 0 or \'\' (the null
482 string) for false.
483 .PP
484 There are actually two varieties of null string: defined and undefined.
485 Undefined null strings are returned when there is no real value for something,
486 such as when there was an error, or at end of file, or when you refer
487 to an uninitialized variable or element of an array.
488 An undefined null string may become defined the first time you access it, but
489 prior to that you can use the defined() operator to determine whether the
490 value is defined or not.
491 .PP
492 References to scalar variables always begin with \*(L'$\*(R', even when referring
493 to a scalar that is part of an array.
494 Thus:
495 .nf
496
497 .ne 3
498     $days       \h'|2i'# a simple scalar variable
499     $days[28]   \h'|2i'# 29th element of array @days
500     $days{\'Feb\'}\h'|2i'# one value from an associative array
501     $#days      \h'|2i'# last index of array @days
502
503 but entire arrays or array slices are denoted by \*(L'@\*(R':
504
505     @days       \h'|2i'# ($days[0], $days[1],\|.\|.\|. $days[n])
506     @days[3,4,5]\h'|2i'# same as @days[3.\|.5]
507     @days{'a','c'}\h'|2i'# same as ($days{'a'},$days{'c'})
508
509 and entire associative arrays are denoted by \*(L'%\*(R':
510
511     %days       \h'|2i'# (key1, val1, key2, val2 .\|.\|.)
512 .fi
513 .PP
514 Any of these eight constructs may serve as an lvalue,
515 that is, may be assigned to.
516 (It also turns out that an assignment is itself an lvalue in
517 certain contexts\*(--see examples under s, tr and chop.)
518 Assignment to a scalar evaluates the righthand side in a scalar context,
519 while assignment to an array or array slice evaluates the righthand side
520 in an array context.
521 .PP
522 You may find the length of array @days by evaluating
523 \*(L"$#days\*(R", as in
524 .IR csh .
525 (Actually, it's not the length of the array, it's the subscript of the last element, since there is (ordinarily) a 0th element.)
526 Assigning to $#days changes the length of the array.
527 Shortening an array by this method does not actually destroy any values.
528 Lengthening an array that was previously shortened recovers the values that
529 were in those elements.
530 You can also gain some measure of efficiency by preextending an array that
531 is going to get big.
532 (You can also extend an array by assigning to an element that is off the
533 end of the array.
534 This differs from assigning to $#whatever in that intervening values
535 are set to null rather than recovered.)
536 You can truncate an array down to nothing by assigning the null list () to
537 it.
538 The following are exactly equivalent
539 .nf
540
541         @whatever = ();
542         $#whatever = $[ \- 1;
543
544 .fi
545 .PP
546 If you evaluate an array in a scalar context, it returns the length of
547 the array.
548 The following is always true:
549 .nf
550
551         @whatever == $#whatever \- $[ + 1;
552
553 .fi
554 .PP
555 Multi-dimensional arrays are not directly supported, but see the discussion
556 of the $; variable later for a means of emulating multiple subscripts with
557 an associative array.
558 You could also write a subroutine to turn multiple subscripts into a single
559 subscript.
560 .PP
561 Every data type has its own namespace.
562 You can, without fear of conflict, use the same name for a scalar variable,
563 an array, an associative array, a filehandle, a subroutine name, and/or
564 a label.
565 Since variable and array references always start with \*(L'$\*(R', \*(L'@\*(R',
566 or \*(L'%\*(R', the \*(L"reserved\*(R" words aren't in fact reserved
567 with respect to variable names.
568 (They ARE reserved with respect to labels and filehandles, however, which
569 don't have an initial special character.
570 Hint: you could say open(LOG,\'logfile\') rather than open(log,\'logfile\').
571 Using uppercase filehandles also improves readability and protects you
572 from conflict with future reserved words.)
573 Case IS significant\*(--\*(L"FOO\*(R", \*(L"Foo\*(R" and \*(L"foo\*(R" are all
574 different names.
575 Names which start with a letter may also contain digits and underscores.
576 Names which do not start with a letter are limited to one character,
577 e.g. \*(L"$%\*(R" or \*(L"$$\*(R".
578 (Most of the one character names have a predefined significance to
579 .IR perl .
580 More later.)
581 .PP
582 Numeric literals are specified in any of the usual floating point or
583 integer formats:
584 .nf
585
586 .ne 5
587     12345
588     12345.67
589     .23E-10
590     0xffff      # hex
591     0377        # octal
592
593 .fi
594 String literals are delimited by either single or double quotes.
595 They work much like shell quotes:
596 double-quoted string literals are subject to backslash and variable
597 substitution; single-quoted strings are not (except for \e\' and \e\e).
598 The usual backslash rules apply for making characters such as newline, tab, etc.
599 You can also embed newlines directly in your strings, i.e. they can end on
600 a different line than they begin.
601 This is nice, but if you forget your trailing quote, the error will not be
602 reported until
603 .I perl
604 finds another line containing the quote character, which
605 may be much further on in the script.
606 Variable substitution inside strings is limited to scalar variables, normal
607 array values, and array slices.
608 (In other words, identifiers beginning with $ or @, followed by an optional
609 bracketed expression as a subscript.)
610 The following code segment prints out \*(L"The price is $100.\*(R"
611 .nf
612
613 .ne 2
614     $Price = \'$100\';\h'|3.5i'# not interpreted
615     print "The price is $Price.\e\|n";\h'|3.5i'# interpreted
616
617 .fi
618 Note that you can put curly brackets around the identifier to delimit it
619 from following alphanumerics.
620 Also note that a single quoted string must be separated from a preceding
621 word by a space, since single quote is a valid character in an identifier
622 (see Packages).
623 .PP
624 Two special literals are __LINE__ and __FILE__, which represent the current
625 line number and filename at that point in your program.
626 They may only be used as separate tokens; they will not be interpolated
627 into strings.
628 In addition, the token __END__ may be used to indicate the logical end of the
629 script before the actual end of file.
630 Any following text is ignored (but may be read via the DATA filehandle).
631 The two control characters ^D and ^Z are synomyms for __END__.
632 .PP
633 A word that doesn't have any other interpretation in the grammar will be
634 treated as if it had single quotes around it.
635 For this purpose, a word consists only of alphanumeric characters and underline,
636 and must start with an alphabetic character.
637 As with filehandles and labels, a bare word that consists entirely of
638 lowercase letters risks conflict with future reserved words, and if you
639 use the
640 .B \-w
641 switch, Perl will warn you about any such words.
642 .PP
643 Array values are interpolated into double-quoted strings by joining all the
644 elements of the array with the delimiter specified in the $" variable,
645 space by default.
646 (Since in versions of perl prior to 3.0 the @ character was not a metacharacter
647 in double-quoted strings, the interpolation of @array, $array[EXPR],
648 @array[LIST], $array{EXPR}, or @array{LIST} only happens if array is
649 referenced elsewhere in the program or is predefined.)
650 The following are equivalent:
651 .nf
652
653 .ne 4
654         $temp = join($",@ARGV);
655         system "echo $temp";
656
657         system "echo @ARGV";
658
659 .fi
660 Within search patterns (which also undergo double-quotish substitution)
661 there is a bad ambiguity:  Is /$foo[bar]/ to be
662 interpreted as /${foo}[bar]/ (where [bar] is a character class for the
663 regular expression) or as /${foo[bar]}/ (where [bar] is the subscript to
664 array @foo)?
665 If @foo doesn't otherwise exist, then it's obviously a character class.
666 If @foo exists, perl takes a good guess about [bar], and is almost always right.
667 If it does guess wrong, or if you're just plain paranoid,
668 you can force the correct interpretation with curly brackets as above.
669 .PP
670 A line-oriented form of quoting is based on the shell here-is syntax.
671 Following a << you specify a string to terminate the quoted material, and all lines
672 following the current line down to the terminating string are the value
673 of the item.
674 The terminating string may be either an identifier (a word), or some
675 quoted text.
676 If quoted, the type of quotes you use determines the treatment of the text,
677 just as in regular quoting.
678 An unquoted identifier works like double quotes.
679 There must be no space between the << and the identifier.
680 (If you put a space it will be treated as a null identifier, which is
681 valid, and matches the first blank line\*(--see Merry Christmas example below.)
682 The terminating string must appear by itself (unquoted and with no surrounding
683 whitespace) on the terminating line.
684 .nf
685
686         print <<EOF;            # same as above
687 The price is $Price.
688 EOF
689
690         print <<"EOF";          # same as above
691 The price is $Price.
692 EOF
693
694         print << x 10;          # null identifier is delimiter
695 Merry Christmas!
696
697         print <<`EOC`;          # execute commands
698 echo hi there
699 echo lo there
700 EOC
701
702         print <<foo, <<bar;     # you can stack them
703 I said foo.
704 foo
705 I said bar.
706 bar
707
708 .fi
709 Array literals are denoted by separating individual values by commas, and
710 enclosing the list in parentheses:
711 .nf
712
713         (LIST)
714
715 .fi
716 In a context not requiring an array value, the value of the array literal
717 is the value of the final element, as in the C comma operator.
718 For example,
719 .nf
720
721 .ne 4
722     @foo = (\'cc\', \'\-E\', $bar);
723
724 assigns the entire array value to array foo, but
725
726     $foo = (\'cc\', \'\-E\', $bar);
727
728 .fi
729 assigns the value of variable bar to variable foo.
730 Note that the value of an actual array in a scalar context is the length
731 of the array; the following assigns to $foo the value 3:
732 .nf
733
734 .ne 2
735     @foo = (\'cc\', \'\-E\', $bar);
736     $foo = @foo;                # $foo gets 3
737
738 .fi
739 You may have an optional comma before the closing parenthesis of an
740 array literal, so that you can say:
741 .nf
742
743     @foo = (
744         1,
745         2,
746         3,
747     );
748
749 .fi
750 When a LIST is evaluated, each element of the list is evaluated in
751 an array context, and the resulting array value is interpolated into LIST
752 just as if each individual element were a member of LIST.  Thus arrays
753 lose their identity in a LIST\*(--the list
754
755         (@foo,@bar,&SomeSub)
756
757 contains all the elements of @foo followed by all the elements of @bar,
758 followed by all the elements returned by the subroutine named SomeSub.
759 .PP
760 A list value may also be subscripted like a normal array.
761 Examples:
762 .nf
763
764         $time = (stat($file))[8];       # stat returns array value
765         $digit = ('a','b','c','d','e','f')[$digit-10];
766         return (pop(@foo),pop(@foo))[0];
767
768 .fi
769 .PP
770 Array lists may be assigned to if and only if each element of the list
771 is an lvalue:
772 .nf
773
774     ($a, $b, $c) = (1, 2, 3);
775
776     ($map{\'red\'}, $map{\'blue\'}, $map{\'green\'}) = (0x00f, 0x0f0, 0xf00);
777
778 The final element may be an array or an associative array:
779
780     ($a, $b, @rest) = split;
781     local($a, $b, %rest) = @_;
782
783 .fi
784 You can actually put an array anywhere in the list, but the first array
785 in the list will soak up all the values, and anything after it will get
786 a null value.
787 This may be useful in a local().
788 .PP
789 An associative array literal contains pairs of values to be interpreted
790 as a key and a value:
791 .nf
792
793 .ne 2
794     # same as map assignment above
795     %map = ('red',0x00f,'blue',0x0f0,'green',0xf00);
796
797 .fi
798 Array assignment in a scalar context returns the number of elements
799 produced by the expression on the right side of the assignment:
800 .nf
801
802         $x = (($foo,$bar) = (3,2,1));   # set $x to 3, not 2
803
804 .fi
805 .PP
806 There are several other pseudo-literals that you should know about.
807 If a string is enclosed by backticks (grave accents), it first undergoes
808 variable substitution just like a double quoted string.
809 It is then interpreted as a command, and the output of that command
810 is the value of the pseudo-literal, like in a shell.
811 In a scalar context, a single string consisting of all the output is
812 returned.
813 In an array context, an array of values is returned, one for each line
814 of output.
815 (You can set $/ to use a different line terminator.)
816 The command is executed each time the pseudo-literal is evaluated.
817 The status value of the command is returned in $? (see Predefined Names
818 for the interpretation of $?).
819 Unlike in \f2csh\f1, no translation is done on the return
820 data\*(--newlines remain newlines.
821 Unlike in any of the shells, single quotes do not hide variable names
822 in the command from interpretation.
823 To pass a $ through to the shell you need to hide it with a backslash.
824 .PP
825 Evaluating a filehandle in angle brackets yields the next line
826 from that file (newline included, so it's never false until EOF, at
827 which time an undefined value is returned).
828 Ordinarily you must assign that value to a variable,
829 but there is one situation where an automatic assignment happens.
830 If (and only if) the input symbol is the only thing inside the conditional of a
831 .I while
832 loop, the value is
833 automatically assigned to the variable \*(L"$_\*(R".
834 (This may seem like an odd thing to you, but you'll use the construct
835 in almost every
836 .I perl
837 script you write.)
838 Anyway, the following lines are equivalent to each other:
839 .nf
840
841 .ne 5
842     while ($_ = <STDIN>) { print; }
843     while (<STDIN>) { print; }
844     for (\|;\|<STDIN>;\|) { print; }
845     print while $_ = <STDIN>;
846     print while <STDIN>;
847
848 .fi
849 The filehandles
850 .IR STDIN ,
851 .I STDOUT
852 and
853 .I STDERR
854 are predefined.
855 (The filehandles
856 .IR stdin ,
857 .I stdout
858 and
859 .I stderr
860 will also work except in packages, where they would be interpreted as
861 local identifiers rather than global.)
862 Additional filehandles may be created with the
863 .I open
864 function.
865 .PP
866 If a <FILEHANDLE> is used in a context that is looking for an array, an array
867 consisting of all the input lines is returned, one line per array element.
868 It's easy to make a LARGE data space this way, so use with care.
869 .PP
870 The null filehandle <> is special and can be used to emulate the behavior of
871 \fIsed\fR and \fIawk\fR.
872 Input from <> comes either from standard input, or from each file listed on
873 the command line.
874 Here's how it works: the first time <> is evaluated, the ARGV array is checked,
875 and if it is null, $ARGV[0] is set to \'-\', which when opened gives you standard
876 input.
877 The ARGV array is then processed as a list of filenames.
878 The loop
879 .nf
880
881 .ne 3
882         while (<>) {
883                 .\|.\|.                 # code for each line
884         }
885
886 .ne 10
887 is equivalent to
888
889         unshift(@ARGV, \'\-\') \|if \|$#ARGV < $[;
890         while ($ARGV = shift) {
891                 open(ARGV, $ARGV);
892                 while (<ARGV>) {
893                         .\|.\|.         # code for each line
894                 }
895         }
896
897 .fi
898 except that it isn't as cumbersome to say.
899 It really does shift array ARGV and put the current filename into
900 variable ARGV.
901 It also uses filehandle ARGV internally.
902 You can modify @ARGV before the first <> as long as you leave the first
903 filename at the beginning of the array.
904 Line numbers ($.) continue as if the input was one big happy file.
905 (But see example under eof for how to reset line numbers on each file.)
906 .PP
907 .ne 5
908 If you want to set @ARGV to your own list of files, go right ahead.
909 If you want to pass switches into your script, you can
910 put a loop on the front like this:
911 .nf
912
913 .ne 10
914         while ($_ = $ARGV[0], /\|^\-/\|) {
915                 shift;
916             last if /\|^\-\|\-$\|/\|;
917                 /\|^\-D\|(.*\|)/ \|&& \|($debug = $1);
918                 /\|^\-v\|/ \|&& \|$verbose++;
919                 .\|.\|.         # other switches
920         }
921         while (<>) {
922                 .\|.\|.         # code for each line
923         }
924
925 .fi
926 The <> symbol will return FALSE only once.
927 If you call it again after this it will assume you are processing another
928 @ARGV list, and if you haven't set @ARGV, will input from
929 .IR STDIN .
930 .PP
931 If the string inside the angle brackets is a reference to a scalar variable
932 (e.g. <$foo>),
933 then that variable contains the name of the filehandle to input from.
934 .PP
935 If the string inside angle brackets is not a filehandle, it is interpreted
936 as a filename pattern to be globbed, and either an array of filenames or the
937 next filename in the list is returned, depending on context.
938 One level of $ interpretation is done first, but you can't say <$foo>
939 because that's an indirect filehandle as explained in the previous
940 paragraph.
941 You could insert curly brackets to force interpretation as a
942 filename glob: <${foo}>.
943 Example:
944 .nf
945
946 .ne 3
947         while (<*.c>) {
948                 chmod 0644, $_;
949         }
950
951 is equivalent to
952
953 .ne 5
954         open(foo, "echo *.c | tr \-s \' \et\er\ef\' \'\e\e012\e\e012\e\e012\e\e012\'|");
955         while (<foo>) {
956                 chop;
957                 chmod 0644, $_;
958         }
959
960 .fi
961 In fact, it's currently implemented that way.
962 (Which means it will not work on filenames with spaces in them unless
963 you have /bin/csh on your machine.)
964 Of course, the shortest way to do the above is:
965 .nf
966
967         chmod 0644, <*.c>;
968
969 .fi
970 .Sh "Syntax"
971 .PP
972 A
973 .I perl
974 script consists of a sequence of declarations and commands.
975 The only things that need to be declared in
976 .I perl
977 are report formats and subroutines.
978 See the sections below for more information on those declarations.
979 All uninitialized user-created objects are assumed to
980 start with a null or 0 value until they
981 are defined by some explicit operation such as assignment.
982 The sequence of commands is executed just once, unlike in
983 .I sed
984 and
985 .I awk
986 scripts, where the sequence of commands is executed for each input line.
987 While this means that you must explicitly loop over the lines of your input file
988 (or files), it also means you have much more control over which files and which
989 lines you look at.
990 (Actually, I'm lying\*(--it is possible to do an implicit loop with either the
991 .B \-n
992 or
993 .B \-p
994 switch.)
995 .PP
996 A declaration can be put anywhere a command can, but has no effect on the
997 execution of the primary sequence of commands--declarations all take effect
998 at compile time.
999 Typically all the declarations are put at the beginning or the end of the script.
1000 .PP
1001 .I Perl
1002 is, for the most part, a free-form language.
1003 (The only exception to this is format declarations, for fairly obvious reasons.)
1004 Comments are indicated by the # character, and extend to the end of the line.
1005 If you attempt to use /* */ C comments, it will be interpreted either as
1006 division or pattern matching, depending on the context.
1007 So don't do that.
1008 .Sh "Compound statements"
1009 In
1010 .IR perl ,
1011 a sequence of commands may be treated as one command by enclosing it
1012 in curly brackets.
1013 We will call this a BLOCK.
1014 .PP
1015 The following compound commands may be used to control flow:
1016 .nf
1017
1018 .ne 4
1019         if (EXPR) BLOCK
1020         if (EXPR) BLOCK else BLOCK
1021         if (EXPR) BLOCK elsif (EXPR) BLOCK .\|.\|. else BLOCK
1022         LABEL while (EXPR) BLOCK
1023         LABEL while (EXPR) BLOCK continue BLOCK
1024         LABEL for (EXPR; EXPR; EXPR) BLOCK
1025         LABEL foreach VAR (ARRAY) BLOCK
1026         LABEL BLOCK continue BLOCK
1027
1028 .fi
1029 Note that, unlike C and Pascal, these are defined in terms of BLOCKs, not
1030 statements.
1031 This means that the curly brackets are \fIrequired\fR\*(--no dangling statements allowed.
1032 If you want to write conditionals without curly brackets there are several
1033 other ways to do it.
1034 The following all do the same thing:
1035 .nf
1036
1037 .ne 5
1038         if (!open(foo)) { die "Can't open $foo: $!"; }
1039         die "Can't open $foo: $!" unless open(foo);
1040         open(foo) || die "Can't open $foo: $!"; # foo or bust!
1041         open(foo) ? \'hi mom\' : die "Can't open $foo: $!";
1042                                 # a bit exotic, that last one
1043
1044 .fi
1045 .PP
1046 The
1047 .I if
1048 statement is straightforward.
1049 Since BLOCKs are always bounded by curly brackets, there is never any
1050 ambiguity about which
1051 .I if
1052 an
1053 .I else
1054 goes with.
1055 If you use
1056 .I unless
1057 in place of
1058 .IR if ,
1059 the sense of the test is reversed.
1060 .PP
1061 The
1062 .I while
1063 statement executes the block as long as the expression is true
1064 (does not evaluate to the null string or 0).
1065 The LABEL is optional, and if present, consists of an identifier followed by
1066 a colon.
1067 The LABEL identifies the loop for the loop control statements
1068 .IR next ,
1069 .IR last ,
1070 and
1071 .I redo
1072 (see below).
1073 If there is a
1074 .I continue
1075 BLOCK, it is always executed just before
1076 the conditional is about to be evaluated again, similarly to the third part
1077 of a
1078 .I for
1079 loop in C.
1080 Thus it can be used to increment a loop variable, even when the loop has
1081 been continued via the
1082 .I next
1083 statement (similar to the C \*(L"continue\*(R" statement).
1084 .PP
1085 If the word
1086 .I while
1087 is replaced by the word
1088 .IR until ,
1089 the sense of the test is reversed, but the conditional is still tested before
1090 the first iteration.
1091 .PP
1092 In either the
1093 .I if
1094 or the
1095 .I while
1096 statement, you may replace \*(L"(EXPR)\*(R" with a BLOCK, and the conditional
1097 is true if the value of the last command in that block is true.
1098 .PP
1099 The
1100 .I for
1101 loop works exactly like the corresponding
1102 .I while
1103 loop:
1104 .nf
1105
1106 .ne 12
1107         for ($i = 1; $i < 10; $i++) {
1108                 .\|.\|.
1109         }
1110
1111 is the same as
1112
1113         $i = 1;
1114         while ($i < 10) {
1115                 .\|.\|.
1116         } continue {
1117                 $i++;
1118         }
1119 .fi
1120 .PP
1121 The foreach loop iterates over a normal array value and sets the variable
1122 VAR to be each element of the array in turn.
1123 The variable is implicitly local to the loop, and regains its former value
1124 upon exiting the loop.
1125 The \*(L"foreach\*(R" keyword is actually identical to the \*(L"for\*(R" keyword,
1126 so you can use \*(L"foreach\*(R" for readability or \*(L"for\*(R" for brevity.
1127 If VAR is omitted, $_ is set to each value.
1128 If ARRAY is an actual array (as opposed to an expression returning an array
1129 value), you can modify each element of the array
1130 by modifying VAR inside the loop.
1131 Examples:
1132 .nf
1133
1134 .ne 5
1135         for (@ary) { s/foo/bar/; }
1136
1137         foreach $elem (@elements) {
1138                 $elem *= 2;
1139         }
1140
1141 .ne 3
1142         for ((10,9,8,7,6,5,4,3,2,1,\'BOOM\')) {
1143                 print $_, "\en"; sleep(1);
1144         }
1145
1146         for (1..15) { print "Merry Christmas\en"; }
1147
1148 .ne 3
1149         foreach $item (split(/:[\e\e\en:]*/, $ENV{\'TERMCAP\'})) {
1150                 print "Item: $item\en";
1151         }
1152
1153 .fi
1154 .PP
1155 The BLOCK by itself (labeled or not) is equivalent to a loop that executes
1156 once.
1157 Thus you can use any of the loop control statements in it to leave or
1158 restart the block.
1159 The
1160 .I continue
1161 block is optional.
1162 This construct is particularly nice for doing case structures.
1163 .nf
1164
1165 .ne 6
1166         foo: {
1167                 if (/^abc/) { $abc = 1; last foo; }
1168                 if (/^def/) { $def = 1; last foo; }
1169                 if (/^xyz/) { $xyz = 1; last foo; }
1170                 $nothing = 1;
1171         }
1172
1173 .fi
1174 There is no official switch statement in perl, because there
1175 are already several ways to write the equivalent.
1176 In addition to the above, you could write
1177 .nf
1178
1179 .ne 6
1180         foo: {
1181                 $abc = 1, last foo  if /^abc/;
1182                 $def = 1, last foo  if /^def/;
1183                 $xyz = 1, last foo  if /^xyz/;
1184                 $nothing = 1;
1185         }
1186
1187 or
1188
1189 .ne 6
1190         foo: {
1191                 /^abc/ && do { $abc = 1; last foo; };
1192                 /^def/ && do { $def = 1; last foo; };
1193                 /^xyz/ && do { $xyz = 1; last foo; };
1194                 $nothing = 1;
1195         }
1196
1197 or
1198
1199 .ne 6
1200         foo: {
1201                 /^abc/ && ($abc = 1, last foo);
1202                 /^def/ && ($def = 1, last foo);
1203                 /^xyz/ && ($xyz = 1, last foo);
1204                 $nothing = 1;
1205         }
1206
1207 or even
1208
1209 .ne 8
1210         if (/^abc/)
1211                 { $abc = 1; }
1212         elsif (/^def/)
1213                 { $def = 1; }
1214         elsif (/^xyz/)
1215                 { $xyz = 1; }
1216         else
1217                 {$nothing = 1;}
1218
1219 .fi
1220 As it happens, these are all optimized internally to a switch structure,
1221 so perl jumps directly to the desired statement, and you needn't worry
1222 about perl executing a lot of unnecessary statements when you have a string
1223 of 50 elsifs, as long as you are testing the same simple scalar variable
1224 using ==, eq, or pattern matching as above.
1225 (If you're curious as to whether the optimizer has done this for a particular
1226 case statement, you can use the \-D1024 switch to list the syntax tree
1227 before execution.)
1228 .Sh "Simple statements"
1229 The only kind of simple statement is an expression evaluated for its side
1230 effects.
1231 Every expression (simple statement) must be terminated with a semicolon.
1232 Note that this is like C, but unlike Pascal (and
1233 .IR awk ).
1234 .PP
1235 Any simple statement may optionally be followed by a
1236 single modifier, just before the terminating semicolon.
1237 The possible modifiers are:
1238 .nf
1239
1240 .ne 4
1241         if EXPR
1242         unless EXPR
1243         while EXPR
1244         until EXPR
1245
1246 .fi
1247 The
1248 .I if
1249 and
1250 .I unless
1251 modifiers have the expected semantics.
1252 The
1253 .I while
1254 and
1255 .I until
1256 modifiers also have the expected semantics (conditional evaluated first),
1257 except when applied to a do-BLOCK command,
1258 in which case the block executes once before the conditional is evaluated.
1259 This is so that you can write loops like:
1260 .nf
1261
1262 .ne 4
1263         do {
1264                 $_ = <STDIN>;
1265                 .\|.\|.
1266         } until $_ \|eq \|".\|\e\|n";
1267
1268 .fi
1269 (See the
1270 .I do
1271 operator below.  Note also that the loop control commands described later will
1272 NOT work in this construct, since modifiers don't take loop labels.
1273 Sorry.)
1274 .Sh "Expressions"
1275 Since
1276 .I perl
1277 expressions work almost exactly like C expressions, only the differences
1278 will be mentioned here.
1279 .PP
1280 Here's what
1281 .I perl
1282 has that C doesn't:
1283 .Ip ** 8 2
1284 The exponentiation operator.
1285 .Ip **= 8
1286 The exponentiation assignment operator.
1287 .Ip (\|) 8 3
1288 The null list, used to initialize an array to null.
1289 .Ip . 8
1290 Concatenation of two strings.
1291 .Ip .= 8
1292 The concatenation assignment operator.
1293 .Ip eq 8
1294 String equality (== is numeric equality).
1295 For a mnemonic just think of \*(L"eq\*(R" as a string.
1296 (If you are used to the
1297 .I awk
1298 behavior of using == for either string or numeric equality
1299 based on the current form of the comparands, beware!
1300 You must be explicit here.)
1301 .Ip ne 8
1302 String inequality (!= is numeric inequality).
1303 .Ip lt 8
1304 String less than.
1305 .Ip gt 8
1306 String greater than.
1307 .Ip le 8
1308 String less than or equal.
1309 .Ip ge 8
1310 String greater than or equal.
1311 .Ip cmp 8
1312 String comparison, returning -1, 0, or 1.
1313 .Ip <=> 8
1314 Numeric comparison, returning -1, 0, or 1.
1315 .Ip =~ 8 2
1316 Certain operations search or modify the string \*(L"$_\*(R" by default.
1317 This operator makes that kind of operation work on some other string.
1318 The right argument is a search pattern, substitution, or translation.
1319 The left argument is what is supposed to be searched, substituted, or
1320 translated instead of the default \*(L"$_\*(R".
1321 The return value indicates the success of the operation.
1322 (If the right argument is an expression other than a search pattern,
1323 substitution, or translation, it is interpreted as a search pattern
1324 at run time.
1325 This is less efficient than an explicit search, since the pattern must
1326 be compiled every time the expression is evaluated.)
1327 The precedence of this operator is lower than unary minus and autoincrement/decrement, but higher than everything else.
1328 .Ip !~ 8
1329 Just like =~ except the return value is negated.
1330 .Ip x 8
1331 The repetition operator.
1332 Returns a string consisting of the left operand repeated the
1333 number of times specified by the right operand.
1334 .nf
1335
1336         print \'\-\' x 80;              # print row of dashes
1337         print \'\-\' x80;               # illegal, x80 is identifier
1338
1339         print "\et" x ($tab/8), \' \' x ($tab%8);       # tab over
1340
1341 .fi
1342 .Ip x= 8
1343 The repetition assignment operator.
1344 .Ip .\|. 8
1345 The range operator, which is really two different operators depending
1346 on the context.
1347 In an array context, returns an array of values counting (by ones)
1348 from the left value to the right value.
1349 This is useful for writing \*(L"for (1..10)\*(R" loops and for doing
1350 slice operations on arrays.
1351 .Sp
1352 In a scalar context, .\|. returns a boolean value.
1353 The operator is bistable, like a flip-flop..
1354 Each .\|. operator maintains its own boolean state.
1355 It is false as long as its left operand is false.
1356 Once the left operand is true, the range operator stays true
1357 until the right operand is true,
1358 AFTER which the range operator becomes false again.
1359 (It doesn't become false till the next time the range operator is evaluated.
1360 It can become false on the same evaluation it became true, but it still returns
1361 true once.)
1362 The right operand is not evaluated while the operator is in the \*(L"false\*(R" state,
1363 and the left operand is not evaluated while the operator is in the \*(L"true\*(R" state.
1364 The scalar .\|. operator is primarily intended for doing line number ranges
1365 after
1366 the fashion of \fIsed\fR or \fIawk\fR.
1367 The precedence is a little lower than || and &&.
1368 The value returned is either the null string for false, or a sequence number
1369 (beginning with 1) for true.
1370 The sequence number is reset for each range encountered.
1371 The final sequence number in a range has the string \'E0\' appended to it, which
1372 doesn't affect its numeric value, but gives you something to search for if you
1373 want to exclude the endpoint.
1374 You can exclude the beginning point by waiting for the sequence number to be
1375 greater than 1.
1376 If either operand of scalar .\|. is static, that operand is implicitly compared
1377 to the $. variable, the current line number.
1378 Examples:
1379 .nf
1380
1381 .ne 6
1382 As a scalar operator:
1383     if (101 .\|. 200) { print; }        # print 2nd hundred lines
1384
1385     next line if (1 .\|. /^$/); # skip header lines
1386
1387     s/^/> / if (/^$/ .\|. eof());       # quote body
1388
1389 .ne 4
1390 As an array operator:
1391     for (101 .\|. 200) { print; }       # print $_ 100 times
1392
1393     @foo = @foo[$[ .\|. $#foo]; # an expensive no-op
1394     @foo = @foo[$#foo-4 .\|. $#foo];    # slice last 5 items
1395
1396 .fi
1397 .Ip \-x 8
1398 A file test.
1399 This unary operator takes one argument, either a filename or a filehandle,
1400 and tests the associated file to see if something is true about it.
1401 If the argument is omitted, tests $_, except for \-t, which tests
1402 .IR STDIN .
1403 It returns 1 for true and \'\' for false, or the undefined value if the
1404 file doesn't exist.
1405 Precedence is higher than logical and relational operators, but lower than
1406 arithmetic operators.
1407 The operator may be any of:
1408 .nf
1409         \-r     File is readable by effective uid.
1410         \-w     File is writable by effective uid.
1411         \-x     File is executable by effective uid.
1412         \-o     File is owned by effective uid.
1413         \-R     File is readable by real uid.
1414         \-W     File is writable by real uid.
1415         \-X     File is executable by real uid.
1416         \-O     File is owned by real uid.
1417         \-e     File exists.
1418         \-z     File has zero size.
1419         \-s     File has non-zero size (returns size).
1420         \-f     File is a plain file.
1421         \-d     File is a directory.
1422         \-l     File is a symbolic link.
1423         \-p     File is a named pipe (FIFO).
1424         \-S     File is a socket.
1425         \-b     File is a block special file.
1426         \-c     File is a character special file.
1427         \-u     File has setuid bit set.
1428         \-g     File has setgid bit set.
1429         \-k     File has sticky bit set.
1430         \-t     Filehandle is opened to a tty.
1431         \-T     File is a text file.
1432         \-B     File is a binary file (opposite of \-T).
1433         \-M     Age of file in days when script started.
1434         \-A     Same for access time.
1435         \-C     Same for inode change time.
1436
1437 .fi
1438 The interpretation of the file permission operators \-r, \-R, \-w, \-W, \-x and \-X
1439 is based solely on the mode of the file and the uids and gids of the user.
1440 There may be other reasons you can't actually read, write or execute the file.
1441 Also note that, for the superuser, \-r, \-R, \-w and \-W always return 1, and 
1442 \-x and \-X return 1 if any execute bit is set in the mode.
1443 Scripts run by the superuser may thus need to do a stat() in order to determine
1444 the actual mode of the file, or temporarily set the uid to something else.
1445 .Sp
1446 Example:
1447 .nf
1448 .ne 7
1449         
1450         while (<>) {
1451                 chop;
1452                 next unless \-f $_;     # ignore specials
1453                 .\|.\|.
1454         }
1455
1456 .fi
1457 Note that \-s/a/b/ does not do a negated substitution.
1458 Saying \-exp($foo) still works as expected, however\*(--only single letters
1459 following a minus are interpreted as file tests.
1460 .Sp
1461 The \-T and \-B switches work as follows.
1462 The first block or so of the file is examined for odd characters such as
1463 strange control codes or metacharacters.
1464 If too many odd characters (>10%) are found, it's a \-B file, otherwise it's a \-T file.
1465 Also, any file containing null in the first block is considered a binary file.
1466 If \-T or \-B is used on a filehandle, the current stdio buffer is examined
1467 rather than the first block.
1468 Both \-T and \-B return TRUE on a null file, or a file at EOF when testing
1469 a filehandle.
1470 .PP
1471 If any of the file tests (or either stat operator) are given the special
1472 filehandle consisting of a solitary underline, then the stat structure
1473 of the previous file test (or stat operator) is used, saving a system
1474 call.
1475 (This doesn't work with \-t, and you need to remember that lstat and -l
1476 will leave values in the stat structure for the symbolic link, not the
1477 real file.)
1478 Example:
1479 .nf
1480
1481         print "Can do.\en" if -r $a || -w _ || -x _;
1482
1483 .ne 9
1484         stat($filename);
1485         print "Readable\en" if -r _;
1486         print "Writable\en" if -w _;
1487         print "Executable\en" if -x _;
1488         print "Setuid\en" if -u _;
1489         print "Setgid\en" if -g _;
1490         print "Sticky\en" if -k _;
1491         print "Text\en" if -T _;
1492         print "Binary\en" if -B _;
1493
1494 .fi
1495 .PP
1496 Here is what C has that
1497 .I perl
1498 doesn't:
1499 .Ip "unary &" 12
1500 Address-of operator.
1501 .Ip "unary *" 12
1502 Dereference-address operator.
1503 .Ip "(TYPE)" 12
1504 Type casting operator.
1505 .PP
1506 Like C,
1507 .I perl
1508 does a certain amount of expression evaluation at compile time, whenever
1509 it determines that all of the arguments to an operator are static and have
1510 no side effects.
1511 In particular, string concatenation happens at compile time between literals that don't do variable substitution.
1512 Backslash interpretation also happens at compile time.
1513 You can say
1514 .nf
1515
1516 .ne 2
1517         \'Now is the time for all\' . "\|\e\|n" .
1518         \'good men to come to.\'
1519
1520 .fi
1521 and this all reduces to one string internally.
1522 .PP
1523 The autoincrement operator has a little extra built-in magic to it.
1524 If you increment a variable that is numeric, or that has ever been used in
1525 a numeric context, you get a normal increment.
1526 If, however, the variable has only been used in string contexts since it
1527 was set, and has a value that is not null and matches the
1528 pattern /^[a\-zA\-Z]*[0\-9]*$/, the increment is done
1529 as a string, preserving each character within its range, with carry:
1530 .nf
1531
1532         print ++($foo = \'99\');        # prints \*(L'100\*(R'
1533         print ++($foo = \'a0\');        # prints \*(L'a1\*(R'
1534         print ++($foo = \'Az\');        # prints \*(L'Ba\*(R'
1535         print ++($foo = \'zz\');        # prints \*(L'aaa\*(R'
1536
1537 .fi
1538 The autodecrement is not magical.
1539 .PP
1540 The range operator (in an array context) makes use of the magical
1541 autoincrement algorithm if the minimum and maximum are strings.
1542 You can say
1543
1544         @alphabet = (\'A\' .. \'Z\');
1545
1546 to get all the letters of the alphabet, or
1547
1548         $hexdigit = (0 .. 9, \'a\' .. \'f\')[$num & 15];
1549
1550 to get a hexadecimal digit, or
1551
1552         @z2 = (\'01\' .. \'31\');  print @z2[$mday];
1553
1554 to get dates with leading zeros.
1555 (If the final value specified is not in the sequence that the magical increment
1556 would produce, the sequence goes until the next value would be longer than
1557 the final value specified.)
1558 .PP
1559 The || and && operators differ from C's in that, rather than returning 0 or 1,
1560 they return the last value evaluated. 
1561 Thus, a portable way to find out the home directory might be:
1562 .nf
1563
1564         $home = $ENV{'HOME'} || $ENV{'LOGDIR'} ||
1565             (getpwuid($<))[7] || die "You're homeless!\en";
1566
1567 .fi