2 ''' $Header: perl_man.1,v 3.0.1.11 91/01/11 18:15:46 lwall Locked $
4 ''' $Log: perl.man.1,v $
5 ''' Revision 3.0.1.11 91/01/11 18:15:46 lwall
6 ''' patch42: added -0 option
8 ''' Revision 3.0.1.10 90/11/10 01:45:16 lwall
9 ''' patch38: random cleanup
11 ''' Revision 3.0.1.9 90/10/20 02:14:24 lwall
12 ''' patch37: fixed various typos in man page
14 ''' Revision 3.0.1.8 90/10/15 18:16:19 lwall
15 ''' patch29: added DATA filehandle to read stuff after __END__
16 ''' patch29: added cmp and <=>
17 ''' patch29: added -M, -A and -C
19 ''' Revision 3.0.1.7 90/08/09 04:24:03 lwall
20 ''' patch19: added -x switch to extract script from input trash
21 ''' patch19: Added -c switch to do compilation only
22 ''' patch19: bare identifiers are now strings if no other interpretation possible
23 ''' patch19: -s now returns size of file
24 ''' patch19: Added __LINE__ and __FILE__ tokens
25 ''' patch19: Added __END__ token
27 ''' Revision 3.0.1.6 90/08/03 11:14:44 lwall
28 ''' patch19: Intermediate diffs for Randal
30 ''' Revision 3.0.1.5 90/03/27 16:14:37 lwall
31 ''' patch16: .. now works using magical string increment
33 ''' Revision 3.0.1.4 90/03/12 16:44:33 lwall
34 ''' patch13: (LIST,) now legal
35 ''' patch13: improved LIST documentation
36 ''' patch13: example of if-elsif switch was wrong
38 ''' Revision 3.0.1.3 90/02/28 17:54:32 lwall
39 ''' patch9: @array in scalar context now returns length of array
40 ''' patch9: in manual, example of open and ?: was backwards
42 ''' Revision 3.0.1.2 89/11/17 15:30:03 lwall
43 ''' patch5: fixed some manual typos and indent problems
45 ''' Revision 3.0.1.1 89/11/11 04:41:22 lwall
46 ''' patch2: explained about sh and ${1+"$@"}
47 ''' patch2: documented that space must separate word and '' string
49 ''' Revision 3.0 89/10/18 15:21:29 lwall
66 .ie \\n(.$>=3 .ne \\$3
71 ''' Set up \*(-- to give an unbreakable dash;
72 ''' string Tr holds user defined translation string.
73 ''' Bell System Logo is used as a dummy character.
78 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
79 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
96 perl \- Practical Extraction and Report Language
99 [options] filename args
102 is an interpreted language optimized for scanning arbitrary text files,
103 extracting information from those text files, and printing reports based
105 It's also a good language for many system management tasks.
106 The language is intended to be practical (easy to use, efficient, complete)
107 rather than beautiful (tiny, elegant, minimal).
108 It combines (in the author's opinion, anyway) some of the best features of C,
109 \fIsed\fR, \fIawk\fR, and \fIsh\fR,
110 so people familiar with those languages should have little difficulty with it.
111 (Language historians will also note some vestiges of \fIcsh\fR, Pascal, and
113 Expression syntax corresponds quite closely to C expression syntax.
114 Unlike most Unix utilities,
116 does not arbitrarily limit the size of your data\*(--if you've got
119 can slurp in your whole file as a single string.
120 Recursion is of unlimited depth.
121 And the hash tables used by associative arrays grow as necessary to prevent
122 degraded performance.
124 uses sophisticated pattern matching techniques to scan large amounts of
126 Although optimized for scanning text,
128 can also deal with binary data, and can make dbm files look like associative
129 arrays (where dbm is available).
132 scripts are safer than C programs
133 through a dataflow tracing mechanism which prevents many stupid security holes.
134 If you have a problem that would ordinarily use \fIsed\fR
135 or \fIawk\fR or \fIsh\fR, but it
136 exceeds their capabilities or must run a little faster,
137 and you don't want to write the silly thing in C, then
140 There are also translators to turn your
151 looks for your script in one of the following places:
153 Specified line by line via
155 switches on the command line.
157 Contained in the file specified by the first filename on the command line.
158 (Note that systems supporting the #! notation invoke interpreters this way.)
160 Passed in implicitly via standard input.
161 This only works if there are no filename arguments\*(--to pass
164 script you must explicitly specify a \- for the script name.
166 After locating your script,
168 compiles it to an internal form.
169 If the script is syntactically correct, it is executed.
171 Note: on first reading this section may not make much sense to you. It's here
172 at the front for easy reference.
174 A single-character option may be combined with the following option, if any.
175 This is particularly useful when invoking a script using the #! construct which
176 only allows one argument. Example:
180 #!/usr/bin/perl \-spi.bak # same as \-s \-p \-i.bak
187 specifies the record separator ($/) as an octal number.
188 If there are no digits, the null character is the separator.
189 Other switches may precede or follow the digits.
190 For example, if you have a version of
192 which can print filenames terminated by the null character, you can say this:
195 find . \-name '*.bak' \-print0 | perl \-n0e unlink
198 The special value 00 will cause Perl to slurp files in paragraph mode.
199 The value 0777 will cause Perl to slurp files whole since there is no
200 legal character with that value.
203 turns on autosplit mode when used with a
207 An implicit split command to the @F array
208 is done as the first thing inside the implicit while loop produced by
215 perl \-ane \'print pop(@F), "\en";\'
221 print pop(@F), "\en";
229 to check the syntax of the script and then exit without executing it.
232 runs the script under the perl debugger.
233 See the section on Debugging.
236 sets debugging flags.
237 To watch how it executes your script, use
239 (This only works if debugging is compiled into your
241 Another nice value is \-D1024, which lists your compiled syntax tree.
242 And \-D512 displays compiled regular expressions.
244 .BI \-e " commandline"
245 may be used to enter one line of script.
248 commands may be given to build up a multi-line script.
253 will not look for a script filename in the argument list.
256 specifies that files processed by the <> construct are to be edited
258 It does this by renaming the input file, opening the output file by the
259 same name, and selecting that output file as the default for print statements.
260 The extension, if supplied, is added to the name of the
261 old file to make a backup copy.
262 If no extension is supplied, no backup is made.
263 Saying \*(L"perl \-p \-i.bak \-e "s/foo/bar/;" .\|.\|. \*(R" is the same as using
268 #!/usr/bin/perl \-pi.bak
271 which is equivalent to
276 if ($ARGV ne $oldargv) {
277 rename($ARGV, $ARGV . \'.bak\');
278 open(ARGVOUT, ">$ARGV");
285 print; # this prints to original filename
292 form doesn't need to compare $ARGV to $oldargv to know when
293 the filename has changed.
294 It does, however, use ARGVOUT for the selected filehandle.
297 is restored as the default output filehandle after the loop.
299 You can use eof to locate the end of each input file, in case you want
300 to append to each file, or reset line numbering (see example under eof).
303 may be used in conjunction with
305 to tell the C preprocessor where to look for include files.
306 By default /usr/include and /usr/lib/perl are searched.
311 to assume the following loop around your script, which makes it iterate
312 over filename arguments somewhat like \*(L"sed \-n\*(R" or \fIawk\fR:
317 .\|.\|. # your script goes here
321 Note that the lines are not printed by default.
324 to have lines printed.
325 Here is an efficient way to delete all files older than a week:
328 find . \-mtime +7 \-print | perl \-ne \'chop;unlink;\'
331 This is faster than using the \-exec switch of find because you don't have to
332 start a process on every filename found.
337 to assume the following loop around your script, which makes it iterate
338 over filename arguments somewhat like \fIsed\fR:
343 .\|.\|. # your script goes here
349 Note that the lines are printed automatically.
350 To suppress printing use the
360 causes your script to be run through the C preprocessor before
363 (Since both comments and cpp directives begin with the # character,
364 you should avoid starting comments with any words recognized
365 by the C preprocessor such as \*(L"if\*(R", \*(L"else\*(R" or \*(L"define\*(R".)
368 enables some rudimentary switch parsing for switches on the command line
369 after the script name but before any filename arguments (or before a \-\|\-).
370 Any switch found there is removed from @ARGV and sets the corresponding variable in the
373 The following script prints \*(L"true\*(R" if and only if the script is
374 invoked with a \-xyz switch.
379 if ($xyz) { print "true\en"; }
386 use the PATH environment variable to search for the script
387 (unless the name of the script starts with a slash).
388 Typically this is used to emulate #! startup on machines that don't
389 support #!, in the following manner:
393 eval "exec /usr/bin/perl \-S $0 $*"
394 if $running_under_some_shell;
397 The system ignores the first line and feeds the script to /bin/sh,
398 which proceeds to try to execute the
400 script as a shell script.
401 The shell executes the second line as a normal shell command, and thus
405 On some systems $0 doesn't always contain the full pathname,
410 to search for the script if necessary.
413 locates the script, it parses the lines and ignores them because
414 the variable $running_under_some_shell is never true.
415 A better construct than $* would be ${1+"$@"}, which handles embedded spaces
416 and such in the filenames, but doesn't work if the script is being interpreted
418 In order to start up sh rather than csh, some systems may have to replace the
419 #! line with a line containing just
420 a colon, which will be politely ignored by perl.
421 Other systems can't control that, and need a totally devious construct that
422 will work under any of csh, sh or perl, such as the following:
426 eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
427 & eval 'exec /usr/bin/perl -S $0 $argv:q'
435 to dump core after compiling your script.
436 You can then take this core dump and turn it into an executable file
437 by using the undump program (not supplied).
438 This speeds startup at the expense of some disk space (which you can
439 minimize by stripping the executable).
440 (Still, a "hello world" executable comes out to about 200K on my machine.)
441 If you are going to run your executable as a set-id program then you
442 should probably compile it using taintperl rather than normal perl.
443 If you want to execute a portion of your script before dumping, use the
444 dump operator instead.
445 Note: availability of undump is platform specific and may not be available
446 for a specific port of perl.
451 to do unsafe operations.
452 Currently the only \*(L"unsafe\*(R" operation is the unlinking of directories while
453 running as superuser.
456 prints the version and patchlevel of your
461 prints warnings about identifiers that are mentioned only once, and scalar
462 variables that are used before being set.
463 Also warns about redefined subroutines, and references to undefined
464 filehandles or filehandles opened readonly that you are attempting to
466 Also warns you if you use == on values that don't look like numbers, and if
467 your subroutines recurse more than 100 deep.
472 that the script is embedded in a message.
473 Leading garbage will be discarded until the first line that starts
474 with #! and contains the string "perl".
475 Any meaningful switches on that line will be applied (but only one
476 group of switches, as with normal #! processing).
477 If a directory name is specified, Perl will switch to that directory
478 before running the script.
481 switch only controls the the disposal of leading garbage.
482 The script must be terminated with __END__ if there is trailing garbage
483 to be ignored (the script can process any or all of the trailing garbage
484 via the DATA filehandle if desired).
485 .Sh "Data Types and Objects"
488 has three data types: scalars, arrays of scalars, and
489 associative arrays of scalars.
490 Normal arrays are indexed by number, and associative arrays by string.
492 The interpretation of operations and values in perl sometimes
493 depends on the requirements
494 of the context around the operation or value.
495 There are three major contexts: string, numeric and array.
496 Certain operations return array values
497 in contexts wanting an array, and scalar values otherwise.
498 (If this is true of an operation it will be mentioned in the documentation
500 Operations which return scalars don't care whether the context is looking
501 for a string or a number, but
502 scalar variables and values are interpreted as strings or numbers
503 as appropriate to the context.
504 A scalar is interpreted as TRUE in the boolean sense if it is not the null
506 Booleans returned by operators are 1 for true and 0 or \'\' (the null
509 There are actually two varieties of null string: defined and undefined.
510 Undefined null strings are returned when there is no real value for something,
511 such as when there was an error, or at end of file, or when you refer
512 to an uninitialized variable or element of an array.
513 An undefined null string may become defined the first time you access it, but
514 prior to that you can use the defined() operator to determine whether the
515 value is defined or not.
517 References to scalar variables always begin with \*(L'$\*(R', even when referring
518 to a scalar that is part of an array.
523 $days \h'|2i'# a simple scalar variable
524 $days[28] \h'|2i'# 29th element of array @days
525 $days{\'Feb\'}\h'|2i'# one value from an associative array
526 $#days \h'|2i'# last index of array @days
528 but entire arrays or array slices are denoted by \*(L'@\*(R':
530 @days \h'|2i'# ($days[0], $days[1],\|.\|.\|. $days[n])
531 @days[3,4,5]\h'|2i'# same as @days[3.\|.5]
532 @days{'a','c'}\h'|2i'# same as ($days{'a'},$days{'c'})
534 and entire associative arrays are denoted by \*(L'%\*(R':
536 %days \h'|2i'# (key1, val1, key2, val2 .\|.\|.)
539 Any of these eight constructs may serve as an lvalue,
540 that is, may be assigned to.
541 (It also turns out that an assignment is itself an lvalue in
542 certain contexts\*(--see examples under s, tr and chop.)
543 Assignment to a scalar evaluates the righthand side in a scalar context,
544 while assignment to an array or array slice evaluates the righthand side
547 You may find the length of array @days by evaluating
548 \*(L"$#days\*(R", as in
550 (Actually, it's not the length of the array, it's the subscript of the last element, since there is (ordinarily) a 0th element.)
551 Assigning to $#days changes the length of the array.
552 Shortening an array by this method does not actually destroy any values.
553 Lengthening an array that was previously shortened recovers the values that
554 were in those elements.
555 You can also gain some measure of efficiency by preextending an array that
557 (You can also extend an array by assigning to an element that is off the
559 This differs from assigning to $#whatever in that intervening values
560 are set to null rather than recovered.)
561 You can truncate an array down to nothing by assigning the null list () to
563 The following are exactly equivalent
567 $#whatever = $[ \- 1;
571 If you evaluate an array in a scalar context, it returns the length of
573 The following is always true:
576 @whatever == $#whatever \- $[ + 1;
580 Multi-dimensional arrays are not directly supported, but see the discussion
581 of the $; variable later for a means of emulating multiple subscripts with
582 an associative array.
583 You could also write a subroutine to turn multiple subscripts into a single
586 Every data type has its own namespace.
587 You can, without fear of conflict, use the same name for a scalar variable,
588 an array, an associative array, a filehandle, a subroutine name, and/or
590 Since variable and array references always start with \*(L'$\*(R', \*(L'@\*(R',
591 or \*(L'%\*(R', the \*(L"reserved\*(R" words aren't in fact reserved
592 with respect to variable names.
593 (They ARE reserved with respect to labels and filehandles, however, which
594 don't have an initial special character.
595 Hint: you could say open(LOG,\'logfile\') rather than open(log,\'logfile\').
596 Using uppercase filehandles also improves readability and protects you
597 from conflict with future reserved words.)
598 Case IS significant\*(--\*(L"FOO\*(R", \*(L"Foo\*(R" and \*(L"foo\*(R" are all
600 Names which start with a letter may also contain digits and underscores.
601 Names which do not start with a letter are limited to one character,
602 e.g. \*(L"$%\*(R" or \*(L"$$\*(R".
603 (Most of the one character names have a predefined significance to
607 Numeric literals are specified in any of the usual floating point or
619 String literals are delimited by either single or double quotes.
620 They work much like shell quotes:
621 double-quoted string literals are subject to backslash and variable
622 substitution; single-quoted strings are not (except for \e\' and \e\e).
623 The usual backslash rules apply for making characters such as newline, tab, etc.
624 You can also embed newlines directly in your strings, i.e. they can end on
625 a different line than they begin.
626 This is nice, but if you forget your trailing quote, the error will not be
629 finds another line containing the quote character, which
630 may be much further on in the script.
631 Variable substitution inside strings is limited to scalar variables, normal
632 array values, and array slices.
633 (In other words, identifiers beginning with $ or @, followed by an optional
634 bracketed expression as a subscript.)
635 The following code segment prints out \*(L"The price is $100.\*(R"
639 $Price = \'$100\';\h'|3.5i'# not interpreted
640 print "The price is $Price.\e\|n";\h'|3.5i'# interpreted
643 Note that you can put curly brackets around the identifier to delimit it
644 from following alphanumerics.
645 Also note that a single quoted string must be separated from a preceding
646 word by a space, since single quote is a valid character in an identifier
649 Two special literals are __LINE__ and __FILE__, which represent the current
650 line number and filename at that point in your program.
651 They may only be used as separate tokens; they will not be interpolated
653 In addition, the token __END__ may be used to indicate the logical end of the
654 script before the actual end of file.
655 Any following text is ignored (but may be read via the DATA filehandle).
656 The two control characters ^D and ^Z are synonyms for __END__.
658 A word that doesn't have any other interpretation in the grammar will be
659 treated as if it had single quotes around it.
660 For this purpose, a word consists only of alphanumeric characters and underline,
661 and must start with an alphabetic character.
662 As with filehandles and labels, a bare word that consists entirely of
663 lowercase letters risks conflict with future reserved words, and if you
666 switch, Perl will warn you about any such words.
668 Array values are interpolated into double-quoted strings by joining all the
669 elements of the array with the delimiter specified in the $" variable,
671 (Since in versions of perl prior to 3.0 the @ character was not a metacharacter
672 in double-quoted strings, the interpolation of @array, $array[EXPR],
673 @array[LIST], $array{EXPR}, or @array{LIST} only happens if array is
674 referenced elsewhere in the program or is predefined.)
675 The following are equivalent:
679 $temp = join($",@ARGV);
685 Within search patterns (which also undergo double-quotish substitution)
686 there is a bad ambiguity: Is /$foo[bar]/ to be
687 interpreted as /${foo}[bar]/ (where [bar] is a character class for the
688 regular expression) or as /${foo[bar]}/ (where [bar] is the subscript to
690 If @foo doesn't otherwise exist, then it's obviously a character class.
691 If @foo exists, perl takes a good guess about [bar], and is almost always right.
692 If it does guess wrong, or if you're just plain paranoid,
693 you can force the correct interpretation with curly brackets as above.
695 A line-oriented form of quoting is based on the shell here-is syntax.
696 Following a << you specify a string to terminate the quoted material, and all lines
697 following the current line down to the terminating string are the value
699 The terminating string may be either an identifier (a word), or some
701 If quoted, the type of quotes you use determines the treatment of the text,
702 just as in regular quoting.
703 An unquoted identifier works like double quotes.
704 There must be no space between the << and the identifier.
705 (If you put a space it will be treated as a null identifier, which is
706 valid, and matches the first blank line\*(--see Merry Christmas example below.)
707 The terminating string must appear by itself (unquoted and with no surrounding
708 whitespace) on the terminating line.
711 print <<EOF; # same as above
715 print <<"EOF"; # same as above
719 print << x 10; # null identifier is delimiter
722 print <<`EOC`; # execute commands
727 print <<foo, <<bar; # you can stack them
734 Array literals are denoted by separating individual values by commas, and
735 enclosing the list in parentheses:
741 In a context not requiring an array value, the value of the array literal
742 is the value of the final element, as in the C comma operator.
747 @foo = (\'cc\', \'\-E\', $bar);
749 assigns the entire array value to array foo, but
751 $foo = (\'cc\', \'\-E\', $bar);
754 assigns the value of variable bar to variable foo.
755 Note that the value of an actual array in a scalar context is the length
756 of the array; the following assigns to $foo the value 3:
760 @foo = (\'cc\', \'\-E\', $bar);
761 $foo = @foo; # $foo gets 3
764 You may have an optional comma before the closing parenthesis of an
765 array literal, so that you can say:
775 When a LIST is evaluated, each element of the list is evaluated in
776 an array context, and the resulting array value is interpolated into LIST
777 just as if each individual element were a member of LIST. Thus arrays
778 lose their identity in a LIST\*(--the list
782 contains all the elements of @foo followed by all the elements of @bar,
783 followed by all the elements returned by the subroutine named SomeSub.
785 A list value may also be subscripted like a normal array.
789 $time = (stat($file))[8]; # stat returns array value
790 $digit = ('a','b','c','d','e','f')[$digit-10];
791 return (pop(@foo),pop(@foo))[0];
795 Array lists may be assigned to if and only if each element of the list
799 ($a, $b, $c) = (1, 2, 3);
801 ($map{\'red\'}, $map{\'blue\'}, $map{\'green\'}) = (0x00f, 0x0f0, 0xf00);
803 The final element may be an array or an associative array:
805 ($a, $b, @rest) = split;
806 local($a, $b, %rest) = @_;
809 You can actually put an array anywhere in the list, but the first array
810 in the list will soak up all the values, and anything after it will get
812 This may be useful in a local().
814 An associative array literal contains pairs of values to be interpreted
815 as a key and a value:
819 # same as map assignment above
820 %map = ('red',0x00f,'blue',0x0f0,'green',0xf00);
823 Array assignment in a scalar context returns the number of elements
824 produced by the expression on the right side of the assignment:
827 $x = (($foo,$bar) = (3,2,1)); # set $x to 3, not 2
831 There are several other pseudo-literals that you should know about.
832 If a string is enclosed by backticks (grave accents), it first undergoes
833 variable substitution just like a double quoted string.
834 It is then interpreted as a command, and the output of that command
835 is the value of the pseudo-literal, like in a shell.
836 In a scalar context, a single string consisting of all the output is
838 In an array context, an array of values is returned, one for each line
840 (You can set $/ to use a different line terminator.)
841 The command is executed each time the pseudo-literal is evaluated.
842 The status value of the command is returned in $? (see Predefined Names
843 for the interpretation of $?).
844 Unlike in \f2csh\f1, no translation is done on the return
845 data\*(--newlines remain newlines.
846 Unlike in any of the shells, single quotes do not hide variable names
847 in the command from interpretation.
848 To pass a $ through to the shell you need to hide it with a backslash.
850 Evaluating a filehandle in angle brackets yields the next line
851 from that file (newline included, so it's never false until EOF, at
852 which time an undefined value is returned).
853 Ordinarily you must assign that value to a variable,
854 but there is one situation where an automatic assignment happens.
855 If (and only if) the input symbol is the only thing inside the conditional of a
858 automatically assigned to the variable \*(L"$_\*(R".
859 (This may seem like an odd thing to you, but you'll use the construct
863 Anyway, the following lines are equivalent to each other:
867 while ($_ = <STDIN>) { print; }
868 while (<STDIN>) { print; }
869 for (\|;\|<STDIN>;\|) { print; }
870 print while $_ = <STDIN>;
885 will also work except in packages, where they would be interpreted as
886 local identifiers rather than global.)
887 Additional filehandles may be created with the
891 If a <FILEHANDLE> is used in a context that is looking for an array, an array
892 consisting of all the input lines is returned, one line per array element.
893 It's easy to make a LARGE data space this way, so use with care.
895 The null filehandle <> is special and can be used to emulate the behavior of
896 \fIsed\fR and \fIawk\fR.
897 Input from <> comes either from standard input, or from each file listed on
899 Here's how it works: the first time <> is evaluated, the ARGV array is checked,
900 and if it is null, $ARGV[0] is set to \'-\', which when opened gives you standard
902 The ARGV array is then processed as a list of filenames.
908 .\|.\|. # code for each line
914 unshift(@ARGV, \'\-\') \|if \|$#ARGV < $[;
915 while ($ARGV = shift) {
918 .\|.\|. # code for each line
923 except that it isn't as cumbersome to say.
924 It really does shift array ARGV and put the current filename into
926 It also uses filehandle ARGV internally.
927 You can modify @ARGV before the first <> as long as you leave the first
928 filename at the beginning of the array.
929 Line numbers ($.) continue as if the input was one big happy file.
930 (But see example under eof for how to reset line numbers on each file.)
933 If you want to set @ARGV to your own list of files, go right ahead.
934 If you want to pass switches into your script, you can
935 put a loop on the front like this:
939 while ($_ = $ARGV[0], /\|^\-/\|) {
941 last if /\|^\-\|\-$\|/\|;
942 /\|^\-D\|(.*\|)/ \|&& \|($debug = $1);
943 /\|^\-v\|/ \|&& \|$verbose++;
944 .\|.\|. # other switches
947 .\|.\|. # code for each line
951 The <> symbol will return FALSE only once.
952 If you call it again after this it will assume you are processing another
953 @ARGV list, and if you haven't set @ARGV, will input from
956 If the string inside the angle brackets is a reference to a scalar variable
958 then that variable contains the name of the filehandle to input from.
960 If the string inside angle brackets is not a filehandle, it is interpreted
961 as a filename pattern to be globbed, and either an array of filenames or the
962 next filename in the list is returned, depending on context.
963 One level of $ interpretation is done first, but you can't say <$foo>
964 because that's an indirect filehandle as explained in the previous
966 You could insert curly brackets to force interpretation as a
967 filename glob: <${foo}>.
979 open(foo, "echo *.c | tr \-s \' \et\er\ef\' \'\e\e012\e\e012\e\e012\e\e012\'|");
986 In fact, it's currently implemented that way.
987 (Which means it will not work on filenames with spaces in them unless
988 you have /bin/csh on your machine.)
989 Of course, the shortest way to do the above is:
999 script consists of a sequence of declarations and commands.
1000 The only things that need to be declared in
1002 are report formats and subroutines.
1003 See the sections below for more information on those declarations.
1004 All uninitialized user-created objects are assumed to
1005 start with a null or 0 value until they
1006 are defined by some explicit operation such as assignment.
1007 The sequence of commands is executed just once, unlike in
1011 scripts, where the sequence of commands is executed for each input line.
1012 While this means that you must explicitly loop over the lines of your input file
1013 (or files), it also means you have much more control over which files and which
1015 (Actually, I'm lying\*(--it is possible to do an implicit loop with either the
1021 A declaration can be put anywhere a command can, but has no effect on the
1022 execution of the primary sequence of commands\(*--declarations all take effect
1024 Typically all the declarations are put at the beginning or the end of the script.
1027 is, for the most part, a free-form language.
1028 (The only exception to this is format declarations, for fairly obvious reasons.)
1029 Comments are indicated by the # character, and extend to the end of the line.
1030 If you attempt to use /* */ C comments, it will be interpreted either as
1031 division or pattern matching, depending on the context.
1033 .Sh "Compound statements"
1036 a sequence of commands may be treated as one command by enclosing it
1038 We will call this a BLOCK.
1040 The following compound commands may be used to control flow:
1045 if (EXPR) BLOCK else BLOCK
1046 if (EXPR) BLOCK elsif (EXPR) BLOCK .\|.\|. else BLOCK
1047 LABEL while (EXPR) BLOCK
1048 LABEL while (EXPR) BLOCK continue BLOCK
1049 LABEL for (EXPR; EXPR; EXPR) BLOCK
1050 LABEL foreach VAR (ARRAY) BLOCK
1051 LABEL BLOCK continue BLOCK
1054 Note that, unlike C and Pascal, these are defined in terms of BLOCKs, not
1056 This means that the curly brackets are \fIrequired\fR\*(--no dangling statements allowed.
1057 If you want to write conditionals without curly brackets there are several
1058 other ways to do it.
1059 The following all do the same thing:
1063 if (!open(foo)) { die "Can't open $foo: $!"; }
1064 die "Can't open $foo: $!" unless open(foo);
1065 open(foo) || die "Can't open $foo: $!"; # foo or bust!
1066 open(foo) ? \'hi mom\' : die "Can't open $foo: $!";
1067 # a bit exotic, that last one
1073 statement is straightforward.
1074 Since BLOCKs are always bounded by curly brackets, there is never any
1075 ambiguity about which
1084 the sense of the test is reversed.
1088 statement executes the block as long as the expression is true
1089 (does not evaluate to the null string or 0).
1090 The LABEL is optional, and if present, consists of an identifier followed by
1092 The LABEL identifies the loop for the loop control statements
1100 BLOCK, it is always executed just before
1101 the conditional is about to be evaluated again, similarly to the third part
1105 Thus it can be used to increment a loop variable, even when the loop has
1106 been continued via the
1108 statement (similar to the C \*(L"continue\*(R" statement).
1112 is replaced by the word
1114 the sense of the test is reversed, but the conditional is still tested before
1115 the first iteration.
1121 statement, you may replace \*(L"(EXPR)\*(R" with a BLOCK, and the conditional
1122 is true if the value of the last command in that block is true.
1126 loop works exactly like the corresponding
1132 for ($i = 1; $i < 10; $i++) {
1146 The foreach loop iterates over a normal array value and sets the variable
1147 VAR to be each element of the array in turn.
1148 The variable is implicitly local to the loop, and regains its former value
1149 upon exiting the loop.
1150 The \*(L"foreach\*(R" keyword is actually identical to the \*(L"for\*(R" keyword,
1151 so you can use \*(L"foreach\*(R" for readability or \*(L"for\*(R" for brevity.
1152 If VAR is omitted, $_ is set to each value.
1153 If ARRAY is an actual array (as opposed to an expression returning an array
1154 value), you can modify each element of the array
1155 by modifying VAR inside the loop.
1160 for (@ary) { s/foo/bar/; }
1162 foreach $elem (@elements) {
1167 for ((10,9,8,7,6,5,4,3,2,1,\'BOOM\')) {
1168 print $_, "\en"; sleep(1);
1171 for (1..15) { print "Merry Christmas\en"; }
1174 foreach $item (split(/:[\e\e\en:]*/, $ENV{\'TERMCAP\'})) {
1175 print "Item: $item\en";
1180 The BLOCK by itself (labeled or not) is equivalent to a loop that executes
1182 Thus you can use any of the loop control statements in it to leave or
1187 This construct is particularly nice for doing case structures.
1192 if (/^abc/) { $abc = 1; last foo; }
1193 if (/^def/) { $def = 1; last foo; }
1194 if (/^xyz/) { $xyz = 1; last foo; }
1199 There is no official switch statement in perl, because there
1200 are already several ways to write the equivalent.
1201 In addition to the above, you could write
1206 $abc = 1, last foo if /^abc/;
1207 $def = 1, last foo if /^def/;
1208 $xyz = 1, last foo if /^xyz/;
1216 /^abc/ && do { $abc = 1; last foo; };
1217 /^def/ && do { $def = 1; last foo; };
1218 /^xyz/ && do { $xyz = 1; last foo; };
1226 /^abc/ && ($abc = 1, last foo);
1227 /^def/ && ($def = 1, last foo);
1228 /^xyz/ && ($xyz = 1, last foo);
1245 As it happens, these are all optimized internally to a switch structure,
1246 so perl jumps directly to the desired statement, and you needn't worry
1247 about perl executing a lot of unnecessary statements when you have a string
1248 of 50 elsifs, as long as you are testing the same simple scalar variable
1249 using ==, eq, or pattern matching as above.
1250 (If you're curious as to whether the optimizer has done this for a particular
1251 case statement, you can use the \-D1024 switch to list the syntax tree
1253 .Sh "Simple statements"
1254 The only kind of simple statement is an expression evaluated for its side
1256 Every expression (simple statement) must be terminated with a semicolon.
1257 Note that this is like C, but unlike Pascal (and
1260 Any simple statement may optionally be followed by a
1261 single modifier, just before the terminating semicolon.
1262 The possible modifiers are:
1276 modifiers have the expected semantics.
1281 modifiers also have the expected semantics (conditional evaluated first),
1282 except when applied to a do-BLOCK command,
1283 in which case the block executes once before the conditional is evaluated.
1284 This is so that you can write loops like:
1291 } until $_ \|eq \|".\|\e\|n";
1296 operator below. Note also that the loop control commands described later will
1297 NOT work in this construct, since modifiers don't take loop labels.
1302 expressions work almost exactly like C expressions, only the differences
1303 will be mentioned here.
1309 The exponentiation operator.
1311 The exponentiation assignment operator.
1313 The null list, used to initialize an array to null.
1315 Concatenation of two strings.
1317 The concatenation assignment operator.
1319 String equality (== is numeric equality).
1320 For a mnemonic just think of \*(L"eq\*(R" as a string.
1321 (If you are used to the
1323 behavior of using == for either string or numeric equality
1324 based on the current form of the comparands, beware!
1325 You must be explicit here.)
1327 String inequality (!= is numeric inequality).
1331 String greater than.
1333 String less than or equal.
1335 String greater than or equal.
1337 String comparison, returning -1, 0, or 1.
1339 Numeric comparison, returning -1, 0, or 1.
1341 Certain operations search or modify the string \*(L"$_\*(R" by default.
1342 This operator makes that kind of operation work on some other string.
1343 The right argument is a search pattern, substitution, or translation.
1344 The left argument is what is supposed to be searched, substituted, or
1345 translated instead of the default \*(L"$_\*(R".
1346 The return value indicates the success of the operation.
1347 (If the right argument is an expression other than a search pattern,
1348 substitution, or translation, it is interpreted as a search pattern
1350 This is less efficient than an explicit search, since the pattern must
1351 be compiled every time the expression is evaluated.)
1352 The precedence of this operator is lower than unary minus and autoincrement/decrement, but higher than everything else.
1354 Just like =~ except the return value is negated.
1356 The repetition operator.
1357 Returns a string consisting of the left operand repeated the
1358 number of times specified by the right operand.
1361 print \'\-\' x 80; # print row of dashes
1362 print \'\-\' x80; # illegal, x80 is identifier
1364 print "\et" x ($tab/8), \' \' x ($tab%8); # tab over
1368 The repetition assignment operator.
1370 The range operator, which is really two different operators depending
1372 In an array context, returns an array of values counting (by ones)
1373 from the left value to the right value.
1374 This is useful for writing \*(L"for (1..10)\*(R" loops and for doing
1375 slice operations on arrays.
1377 In a scalar context, .\|. returns a boolean value.
1378 The operator is bistable, like a flip-flop..
1379 Each .\|. operator maintains its own boolean state.
1380 It is false as long as its left operand is false.
1381 Once the left operand is true, the range operator stays true
1382 until the right operand is true,
1383 AFTER which the range operator becomes false again.
1384 (It doesn't become false till the next time the range operator is evaluated.
1385 It can become false on the same evaluation it became true, but it still returns
1387 The right operand is not evaluated while the operator is in the \*(L"false\*(R" state,
1388 and the left operand is not evaluated while the operator is in the \*(L"true\*(R" state.
1389 The scalar .\|. operator is primarily intended for doing line number ranges
1391 the fashion of \fIsed\fR or \fIawk\fR.
1392 The precedence is a little lower than || and &&.
1393 The value returned is either the null string for false, or a sequence number
1394 (beginning with 1) for true.
1395 The sequence number is reset for each range encountered.
1396 The final sequence number in a range has the string \'E0\' appended to it, which
1397 doesn't affect its numeric value, but gives you something to search for if you
1398 want to exclude the endpoint.
1399 You can exclude the beginning point by waiting for the sequence number to be
1401 If either operand of scalar .\|. is static, that operand is implicitly compared
1402 to the $. variable, the current line number.
1407 As a scalar operator:
1408 if (101 .\|. 200) { print; } # print 2nd hundred lines
1410 next line if (1 .\|. /^$/); # skip header lines
1412 s/^/> / if (/^$/ .\|. eof()); # quote body
1415 As an array operator:
1416 for (101 .\|. 200) { print; } # print $_ 100 times
1418 @foo = @foo[$[ .\|. $#foo]; # an expensive no-op
1419 @foo = @foo[$#foo-4 .\|. $#foo]; # slice last 5 items
1424 This unary operator takes one argument, either a filename or a filehandle,
1425 and tests the associated file to see if something is true about it.
1426 If the argument is omitted, tests $_, except for \-t, which tests
1428 It returns 1 for true and \'\' for false, or the undefined value if the
1430 Precedence is higher than logical and relational operators, but lower than
1431 arithmetic operators.
1432 The operator may be any of:
1434 \-r File is readable by effective uid.
1435 \-w File is writable by effective uid.
1436 \-x File is executable by effective uid.
1437 \-o File is owned by effective uid.
1438 \-R File is readable by real uid.
1439 \-W File is writable by real uid.
1440 \-X File is executable by real uid.
1441 \-O File is owned by real uid.
1443 \-z File has zero size.
1444 \-s File has non-zero size (returns size).
1445 \-f File is a plain file.
1446 \-d File is a directory.
1447 \-l File is a symbolic link.
1448 \-p File is a named pipe (FIFO).
1449 \-S File is a socket.
1450 \-b File is a block special file.
1451 \-c File is a character special file.
1452 \-u File has setuid bit set.
1453 \-g File has setgid bit set.
1454 \-k File has sticky bit set.
1455 \-t Filehandle is opened to a tty.
1456 \-T File is a text file.
1457 \-B File is a binary file (opposite of \-T).
1458 \-M Age of file in days when script started.
1459 \-A Same for access time.
1460 \-C Same for inode change time.
1463 The interpretation of the file permission operators \-r, \-R, \-w, \-W, \-x and \-X
1464 is based solely on the mode of the file and the uids and gids of the user.
1465 There may be other reasons you can't actually read, write or execute the file.
1466 Also note that, for the superuser, \-r, \-R, \-w and \-W always return 1, and
1467 \-x and \-X return 1 if any execute bit is set in the mode.
1468 Scripts run by the superuser may thus need to do a stat() in order to determine
1469 the actual mode of the file, or temporarily set the uid to something else.
1477 next unless \-f $_; # ignore specials
1482 Note that \-s/a/b/ does not do a negated substitution.
1483 Saying \-exp($foo) still works as expected, however\*(--only single letters
1484 following a minus are interpreted as file tests.
1486 The \-T and \-B switches work as follows.
1487 The first block or so of the file is examined for odd characters such as
1488 strange control codes or metacharacters.
1489 If too many odd characters (>10%) are found, it's a \-B file, otherwise it's a \-T file.
1490 Also, any file containing null in the first block is considered a binary file.
1491 If \-T or \-B is used on a filehandle, the current stdio buffer is examined
1492 rather than the first block.
1493 Both \-T and \-B return TRUE on a null file, or a file at EOF when testing
1496 If any of the file tests (or either stat operator) are given the special
1497 filehandle consisting of a solitary underline, then the stat structure
1498 of the previous file test (or stat operator) is used, saving a system
1500 (This doesn't work with \-t, and you need to remember that lstat and -l
1501 will leave values in the stat structure for the symbolic link, not the
1506 print "Can do.\en" if -r $a || -w _ || -x _;
1510 print "Readable\en" if -r _;
1511 print "Writable\en" if -w _;
1512 print "Executable\en" if -x _;
1513 print "Setuid\en" if -u _;
1514 print "Setgid\en" if -g _;
1515 print "Sticky\en" if -k _;
1516 print "Text\en" if -T _;
1517 print "Binary\en" if -B _;
1521 Here is what C has that
1525 Address-of operator.
1527 Dereference-address operator.
1529 Type casting operator.
1533 does a certain amount of expression evaluation at compile time, whenever
1534 it determines that all of the arguments to an operator are static and have
1536 In particular, string concatenation happens at compile time between literals that don't do variable substitution.
1537 Backslash interpretation also happens at compile time.
1542 \'Now is the time for all\' . "\|\e\|n" .
1543 \'good men to come to.\'
1546 and this all reduces to one string internally.
1548 The autoincrement operator has a little extra built-in magic to it.
1549 If you increment a variable that is numeric, or that has ever been used in
1550 a numeric context, you get a normal increment.
1551 If, however, the variable has only been used in string contexts since it
1552 was set, and has a value that is not null and matches the
1553 pattern /^[a\-zA\-Z]*[0\-9]*$/, the increment is done
1554 as a string, preserving each character within its range, with carry:
1557 print ++($foo = \'99\'); # prints \*(L'100\*(R'
1558 print ++($foo = \'a0\'); # prints \*(L'a1\*(R'
1559 print ++($foo = \'Az\'); # prints \*(L'Ba\*(R'
1560 print ++($foo = \'zz\'); # prints \*(L'aaa\*(R'
1563 The autodecrement is not magical.
1565 The range operator (in an array context) makes use of the magical
1566 autoincrement algorithm if the minimum and maximum are strings.
1569 @alphabet = (\'A\' .. \'Z\');
1571 to get all the letters of the alphabet, or
1573 $hexdigit = (0 .. 9, \'a\' .. \'f\')[$num & 15];
1575 to get a hexadecimal digit, or
1577 @z2 = (\'01\' .. \'31\'); print @z2[$mday];
1579 to get dates with leading zeros.
1580 (If the final value specified is not in the sequence that the magical increment
1581 would produce, the sequence goes until the next value would be longer than
1582 the final value specified.)
1584 The || and && operators differ from C's in that, rather than returning 0 or 1,
1585 they return the last value evaluated.
1586 Thus, a portable way to find out the home directory might be:
1589 $home = $ENV{'HOME'} || $ENV{'LOGDIR'} ||
1590 (getpwuid($<))[7] || die "You're homeless!\en";