2 ''' $Header: perl.man.1,v 2.0 88/06/05 00:09:23 root Exp $
4 ''' $Log: perl.man.1,v $
5 ''' Revision 2.0 88/06/05 00:09:23 root
6 ''' Baseline version 2.0.
27 ''' Set up \*(-- to give an unbreakable dash;
28 ''' string Tr holds user defined translation string.
29 ''' Bell System Logo is used as a dummy character.
34 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
35 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 perl - Practical Extraction and Report Language
53 .B perl [options] filename args
56 is a interpreted language optimized for scanning arbitrary text files,
57 extracting information from those text files, and printing reports based
59 It's also a good language for many system management tasks.
60 The language is intended to be practical (easy to use, efficient, complete)
61 rather than beautiful (tiny, elegant, minimal).
62 It combines (in the author's opinion, anyway) some of the best features of C,
63 \fIsed\fR, \fIawk\fR, and \fIsh\fR,
64 so people familiar with those languages should have little difficulty with it.
65 (Language historians will also note some vestiges of \fIcsh\fR, Pascal, and
67 Expression syntax corresponds quite closely to C expression syntax.
68 If you have a problem that would ordinarily use \fIsed\fR
69 or \fIawk\fR or \fIsh\fR, but it
70 exceeds their capabilities or must run a little faster,
71 and you don't want to write the silly thing in C, then
74 There are also translators to turn your sed and awk scripts into perl scripts.
79 looks for your script in one of the following places:
81 Specified line by line via
83 switches on the command line.
85 Contained in the file specified by the first filename on the command line.
86 (Note that systems supporting the #! notation invoke interpreters this way.)
88 Passed in implicity via standard input.
89 This only works if there are no filename arguments\*(--to pass
90 arguments to a stdin script you must explicitly specify a - for the script name.
92 After locating your script,
94 compiles it to an internal form.
95 If the script is syntactically correct, it is executed.
97 Note: on first reading this section may not make much sense to you. It's here
98 at the front for easy reference.
100 A single-character option may be combined with the following option, if any.
101 This is particularly useful when invoking a script using the #! construct which
102 only allows one argument. Example:
106 #!/usr/bin/perl -spi.bak # same as -s -p -i.bak
113 turns on autosplit mode when used with a \-n or \-p.
114 An implicit split command to the @F array
115 is done as the first thing inside the implicit while loop produced by
119 perl -ane 'print pop(@F),"\en";'
131 sets debugging flags.
132 To watch how it executes your script, use
134 (This only works if debugging is compiled into your
138 may be used to enter one line of script.
141 commands may be given to build up a multi-line script.
146 will not look for a script filename in the argument list.
149 specifies that files processed by the <> construct are to be edited
151 It does this by renaming the input file, opening the output file by the
152 same name, and selecting that output file as the default for print statements.
153 The extension, if supplied, is added to the name of the
154 old file to make a backup copy.
155 If no extension is supplied, no backup is made.
156 Saying \*(L"perl -p -i.bak -e "s/foo/bar/;" .\|.\|. \*(R" is the same as using
161 #!/usr/bin/perl -pi.bak
164 which is equivalent to
169 if ($ARGV ne $oldargv) {
170 rename($ARGV,$ARGV . '.bak');
171 open(ARGVOUT,">$ARGV");
178 print; # this prints to original filename
183 except that the \-i form doesn't need to compare $ARGV to $oldargv to know when
184 the filename has changed.
185 It does, however, use ARGVOUT for the selected filehandle.
186 Note that stdout is restored as the default output filehandle after the loop.
188 You can use eof to locate the end of each input file, in case you want
189 to append to each file, or reset line numbering (see example under eof).
192 may be used in conjunction with
194 to tell the C preprocessor where to look for include files.
195 By default /usr/include and /usr/lib/perl are searched.
200 to assume the following loop around your script, which makes it iterate
201 over filename arguments somewhat like \*(L"sed -n\*(R" or \fIawk\fR:
206 .\|.\|. # your script goes here
210 Note that the lines are not printed by default.
213 to have lines printed.
214 Here is an efficient way to delete all files older than a week:
217 find . -mtime +7 -print | perl -ne 'chop;unlink;'
220 This is faster than using the -exec switch find because you don't have to
221 start a process on every filename found.
226 to assume the following loop around your script, which makes it iterate
227 over filename arguments somewhat like \fIsed\fR:
232 .\|.\|. # your script goes here
238 Note that the lines are printed automatically.
239 To suppress printing use the
249 causes your script to be run through the C preprocessor before
252 (Since both comments and cpp directives begin with the # character,
253 you should avoid starting comments with any words recognized
254 by the C preprocessor such as \*(L"if\*(R", \*(L"else\*(R" or \*(L"define\*(R".)
257 enables some rudimentary switch parsing for switches on the command line
258 after the script name but before any filename arguments (or before a --).
259 Any switch found there is removed from @ARGV and sets the corresponding variable in the
262 The following script prints \*(L"true\*(R" if and only if the script is
263 invoked with a -xyz switch.
268 if ($xyz) { print "true\en"; }
273 makes perl use the PATH environment variable to search for the script
274 (unless the name of the script starts with a slash).
275 Typically this is used to emulate #! startup on machines that don't
276 support #!, in the following manner:
280 eval "exec /usr/bin/perl -S $0 $*"
281 if $running_under_some_shell;
284 The system ignores the first line and feeds the script to /bin/sh,
285 which proceeds to try to execute the perl script as a shell script.
286 The shell executes the second line as a normal shell command, and thus
287 starts up the perl interpreter.
288 On some systems $0 doesn't always contain the full pathname,
289 so the -S tells perl to search for the script if necessary.
290 After perl locates the script, it parses the lines and ignores them because
291 the variable $running_under_some_shell is never true.
294 allows perl to do unsafe operations.
295 Currently the only "unsafe" operation is the unlinking of directories while
296 running as superuser.
299 prints the version and patchlevel of your perl executable.
302 prints warnings about identifiers that are mentioned only once, and scalar
303 variables that are used before being set.
304 Also warns about redefined subroutines, and references to undefined
305 subroutines and filehandles.
306 .Sh "Data Types and Objects"
308 Perl has about two and a half data types: scalars, arrays of scalars, and
310 Scalars and arrays of scalars are first class objects, for the most part,
311 in the sense that they can be used as a whole as values in an expression.
312 Associative arrays can only be accessed on an association by association basis;
313 they don't have a value as a whole (at least not yet).
315 Scalars are interpreted as strings or numbers as appropriate.
316 A scalar is interpreted as TRUE in the boolean sense if it is not the null
318 Booleans returned by operators are 1 for true and '0' or '' (the null
321 References to scalar variables always begin with \*(L'$\*(R', even when referring
322 to a scalar that is part of an array.
327 $days \h'|2i'# a simple scalar variable
328 $days[28] \h'|2i'# 29th element of array @days
329 $days{'Feb'}\h'|2i'# one value from an associative array
330 $#days \h'|2i'# last index of array @days
332 but entire arrays are denoted by \*(L'@\*(R':
334 @days \h'|2i'# ($days[0], $days[1],\|.\|.\|. $days[n])
338 Any of these five constructs may server as an lvalue,
339 that is, may be assigned to.
340 (You may also use an assignment to one of these lvalues as an lvalue in
341 certain contexts\*(--see s, tr and chop.)
342 You may find the length of array @days by evaluating
343 \*(L"$#days\*(R", as in
345 (Actually, it's not the length of the array, it's the subscript of the last element, since there is (ordinarily) a 0th element.)
346 Assigning to $#days changes the length of the array.
347 Shortening an array by this method does not actually destroy any values.
348 Lengthening an array that was previously shortened recovers the values that
349 were in those elements.
350 You can also gain some measure of efficiency by preextending an array that
352 (You can also extend an array by assigning to an element that is off the
354 This differs from assigning to $#whatever in that intervening values
355 are set to null rather than recovered.)
356 You can truncate an array down to nothing by assigning the null list () to
358 The following are exactly equivalent
362 $#whatever = $[ \- 1;
366 Every data type has its own namespace.
367 You can, without fear of conflict, use the same name for a scalar variable,
368 an array, an associative array, a filehandle, a subroutine name, and/or
370 Since variable and array references always start with \*(L'$\*(R'
371 or \*(L'@\*(R', the \*(L"reserved\*(R" words aren't in fact reserved
372 with respect to variable names.
373 (They ARE reserved with respect to labels and filehandles, however, which
374 don't have an initial special character.
375 Hint: you could say open(LOG,'logfile') rather than open(log,'logfile').)
376 Case IS significant\*(--\*(L"FOO\*(R", \*(L"Foo\*(R" and \*(L"foo\*(R" are all
378 Names which start with a letter may also contain digits and underscores.
379 Names which do not start with a letter are limited to one character,
380 e.g. \*(L"$%\*(R" or \*(L"$$\*(R".
381 (Many one character names have a predefined significance to
385 String literals are delimited by either single or double quotes.
386 They work much like shell quotes:
387 double-quoted string literals are subject to backslash and variable
388 substitution; single-quoted strings are not.
389 The usual backslash rules apply for making characters such as newline, tab, etc.
390 You can also embed newlines directly in your strings, i.e. they can end on
391 a different line than they begin.
392 This is nice, but if you forget your trailing quote, the error will not be
393 reported until perl finds another line containing the quote character, which
394 may be much further on in the script.
395 Variable substitution inside strings is limited (currently) to simple scalar variables.
396 The following code segment prints out \*(L"The price is $100.\*(R"
400 $Price = '$100';\h'|3.5i'# not interpreted
401 print "The price is $Price.\e\|n";\h'|3.5i'# interpreted
404 Note that you can put curly brackets around the identifier to delimit it
405 from following alphanumerics.
407 Array literals are denoted by separating individual values by commas, and
408 enclosing the list in parentheses.
409 In a context not requiring an array value, the value of the array literal
410 is the value of the final element, as in the C comma operator.
415 @foo = ('cc', '\-E', $bar);
417 assigns the entire array value to array foo, but
419 $foo = ('cc', '\-E', $bar);
422 assigns the value of variable bar to variable foo.
423 Array lists may be assigned to if and only if each element of the list
427 ($a, $b, $c) = (1, 2, 3);
429 ($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00);
432 Array assignment returns the number of elements assigned.
434 Numeric literals are specified in any of the usual floating point or
437 There are several other pseudo-literals that you should know about.
438 If a string is enclosed by backticks (grave accents), it first undergoes
439 variable substitution just like a double quoted string.
440 It is then interpreted as a command, and the output of that command
441 is the value of the pseudo-literal, like in a shell.
442 The command is executed each time the pseudo-literal is evaluated.
443 The status value of the command is returned in $? (see Predefined Names
444 for the interpretation of $?).
445 Unlike in \f2csh\f1, no translation is done on the return
446 data\*(--newlines remain newlines.
447 Unlike in any of the shells, single quotes do not hide variable names
448 in the command from interpretation.
449 To pass a $ through to the shell you need to hide it with a backslash.
451 Evaluating a filehandle in angle brackets yields the next line
452 from that file (newline included, so it's never false until EOF).
453 Ordinarily you must assign that value to a variable,
454 but there is one situation where in which an automatic assignment happens.
455 If (and only if) the input symbol is the only thing inside the conditional of a
458 automatically assigned to the variable \*(L"$_\*(R".
459 (This may seem like an odd thing to you, but you'll use the construct
463 Anyway, the following lines are equivalent to each other:
467 while ($_ = <stdin>) {
469 for (\|;\|<stdin>;\|) {
478 Additional filehandles may be created with the
482 If a <FILEHANDLE> is used in a context that is looking for an array, an array
483 consisting of all the input lines is returned, one line per array element.
484 It's easy to make a LARGE data space this way, so use with care.
486 The null filehandle <> is special and can be used to emulate the behavior of
487 \fIsed\fR and \fIawk\fR.
488 Input from <> comes either from standard input, or from each file listed on
490 Here's how it works: the first time <> is evaluated, the ARGV array is checked,
491 and if it is null, $ARGV[0] is set to '-', which when opened gives you standard
493 The ARGV array is then processed as a list of filenames.
499 .\|.\|. # code for each line
505 unshift(@ARGV, '\-') \|if \|$#ARGV < $[;
506 while ($ARGV = shift) {
509 .\|.\|. # code for each line
514 except that it isn't as cumbersome to say.
515 It really does shift array ARGV and put the current filename into
517 It also uses filehandle ARGV internally.
518 You can modify @ARGV before the first <> as long as you leave the first
519 filename at the beginning of the array.
520 Line numbers ($.) continue as if the input was one big happy file.
521 (But see example under eof for how to reset line numbers on each file.)
524 If you want to set @ARGV to your own list of files, go right ahead.
525 If you want to pass switches into your script, you can
526 put a loop on the front like this:
530 while ($_ = $ARGV[0], /\|^\-/\|) {
532 last if /\|^\-\|\-$\|/\|;
533 /\|^\-D\|(.*\|)/ \|&& \|($debug = $1);
534 /\|^\-v\|/ \|&& \|$verbose++;
535 .\|.\|. # other switches
538 .\|.\|. # code for each line
542 The <> symbol will return FALSE only once.
543 If you call it again after this it will assume you are processing another
544 @ARGV list, and if you haven't set @ARGV, will input from stdin.
546 If the string inside the angle brackets is a reference to a scalar variable
548 then that variable contains the name of the filehandle to input from.
550 If the string inside angle brackets is not a filehandle, it is interpreted
551 as a filename pattern to be globbed, and either an array of filenames or the
552 next filename in the list is returned, depending on context.
553 One level of $ interpretation is done first, but you can't say <$foo>
554 because that's an indirect filehandle as explained in the previous
556 You could insert curly brackets to force interpretation as a
557 filename glob: <${foo}>.
569 open(foo,"echo *.c | tr -s ' \et\er\ef' '\e\e012\e\e012\e\e012\e\e012'|");
576 In fact, it's currently implemented that way.
577 (Which means it will not work on filenames with spaces in them.)
578 Of course, the shortest way to do the above is:
588 script consists of a sequence of declarations and commands.
589 The only things that need to be declared in
591 are report formats and subroutines.
592 See the sections below for more information on those declarations.
593 All objects are assumed to start with a null or 0 value.
594 The sequence of commands is executed just once, unlike in
598 scripts, where the sequence of commands is executed for each input line.
599 While this means that you must explicitly loop over the lines of your input file
600 (or files), it also means you have much more control over which files and which
602 (Actually, I'm lying\*(--it is possible to do an implicit loop with either the
608 A declaration can be put anywhere a command can, but has no effect on the
609 execution of the primary sequence of commands.
610 Typically all the declarations are put at the beginning or the end of the script.
613 is, for the most part, a free-form language.
614 (The only exception to this is format declarations, for fairly obvious reasons.)
615 Comments are indicated by the # character, and extend to the end of the line.
616 If you attempt to use /* */ C comments, it will be interpreted either as
617 division or pattern matching, depending on the context.
619 .Sh "Compound statements"
622 a sequence of commands may be treated as one command by enclosing it
624 We will call this a BLOCK.
626 The following compound commands may be used to control flow:
631 if (EXPR) BLOCK else BLOCK
632 if (EXPR) BLOCK elsif (EXPR) BLOCK .\|.\|. else BLOCK
633 LABEL while (EXPR) BLOCK
634 LABEL while (EXPR) BLOCK continue BLOCK
635 LABEL for (EXPR; EXPR; EXPR) BLOCK
636 LABEL foreach VAR (ARRAY) BLOCK
637 LABEL BLOCK continue BLOCK
640 Note that, unlike C and Pascal, these are defined in terms of BLOCKs, not
642 This means that the curly brackets are \fIrequired\fR\*(--no dangling statements allowed.
643 If you want to write conditionals without curly brackets there are several
645 The following all do the same thing:
649 if (!open(foo)) { die "Can't open $foo"; }
650 die "Can't open $foo" unless open(foo);
651 open(foo) || die "Can't open $foo"; # foo or bust!
652 open(foo) ? die "Can't open $foo" : 'hi mom';
653 # a bit exotic, that last one
659 statement is straightforward.
660 Since BLOCKs are always bounded by curly brackets, there is never any
661 ambiguity about which
670 the sense of the test is reversed.
674 statement executes the block as long as the expression is true
675 (does not evaluate to the null string or 0).
676 The LABEL is optional, and if present, consists of an identifier followed by
678 The LABEL identifies the loop for the loop control statements
686 BLOCK, it is always executed just before
687 the conditional is about to be evaluated again, similarly to the third part
691 Thus it can be used to increment a loop variable, even when the loop has
692 been continued via the
694 statement (similar to the C \*(L"continue\*(R" statement).
698 is replaced by the word
700 the sense of the test is reversed, but the conditional is still tested before
707 statement, you may replace \*(L"(EXPR)\*(R" with a BLOCK, and the conditional
708 is true if the value of the last command in that block is true.
712 loop works exactly like the corresponding
718 for ($i = 1; $i < 10; $i++) {
732 The foreach loop iterates over a normal array value and sets the variable
733 VAR to be each element of the array in turn.
734 The "foreach" keyword is actually identical to the "for" keyword,
735 so you can use "foreach" for readability or "for" for brevity.
736 If VAR is omitted, $_ is set to each value.
737 If ARRAY is an actual array (as opposed to an expression returning an array
738 value), you can modify each element of the array
739 by modifying VAR inside the loop.
744 for (@ary) { s/foo/bar/; }
746 foreach $elem (@elements) {
750 for ((10,9,8,7,6,5,4,3,2,1,'BOOM')) {
751 print $_,"\en"; sleep(1);
755 foreach $item (split(/:[\e\e\en:]*/,$ENV{'TERMCAP'}) {
756 print "Item: $item\en";
760 The BLOCK by itself (labeled or not) is equivalent to a loop that executes
762 Thus you can use any of the loop control statements in it to leave or
767 This construct is particularly nice for doing case structures.
772 if (/abc/) { $abc = 1; last foo; }
773 if (/def/) { $def = 1; last foo; }
774 if (/xyz/) { $xyz = 1; last foo; }
779 It's also nice for exiting subroutines early.
780 Note the double curly brackets:
794 .Sh "Simple statements"
795 The only kind of simple statement is an expression evaluated for its side
797 Every expression (simple statement) must be terminated with a semicolon.
798 Note that this is like C, but unlike Pascal (and
801 Any simple statement may optionally be followed by a
802 single modifier, just before the terminating semicolon.
803 The possible modifiers are:
817 modifiers have the expected semantics.
822 modifiers also have the expected semantics (conditional evaluated first),
823 except when applied to a do-BLOCK command,
824 in which case the block executes once before the conditional is evaluated.
825 This is so that you can write loops like:
832 } until $_ \|eq \|".\|\e\|n";
837 operator below. Note also that the loop control commands described later will
838 NOT work in this construct, since modifiers don't take loop labels.
843 expressions work almost exactly like C expressions, only the differences
844 will be mentioned here.
850 The null list, used to initialize an array to null.
852 Concatenation of two strings.
854 The corresponding assignment operator.
856 String equality (== is numeric equality).
857 For a mnemonic just think of \*(L"eq\*(R" as a string.
858 (If you are used to the
860 behavior of using == for either string or numeric equality
861 based on the current form of the comparands, beware!
862 You must be explicit here.)
864 String inequality (!= is numeric inequality).
870 String less than or equal.
872 String greater than or equal.
874 Certain operations search or modify the string \*(L"$_\*(R" by default.
875 This operator makes that kind of operation work on some other string.
876 The right argument is a search pattern, substitution, or translation.
877 The left argument is what is supposed to be searched, substituted, or
878 translated instead of the default \*(L"$_\*(R".
879 The return value indicates the success of the operation.
880 (If the right argument is an expression other than a search pattern,
881 substitution, or translation, it is interpreted as a search pattern
883 This is less efficient than an explicit search, since the pattern must
884 be compiled every time the expression is evaluated.)
885 The precedence of this operator is lower than unary minus and autoincrement/decrement, but higher than everything else.
887 Just like =~ except the return value is negated.
889 The repetition operator.
890 Returns a string consisting of the left operand repeated the
891 number of times specified by the right operand.
894 print '-' x 80; # print row of dashes
895 print '-' x80; # illegal, x80 is identifier
897 print "\et" x ($tab/8), ' ' x ($tab%8); # tab over
901 The corresponding assignment operator.
903 The range operator, which is bistable.
904 Each .. operator maintains its own boolean state.
905 It is false as long as its left operand is false.
906 Once the left operand is true, the range operator stays true
907 until the right operand is true,
908 AFTER which the range operator becomes false again.
909 (It doesn't become false till the next time the range operator evaluated.
910 It can become false on the same evaluation it became true, but it still returns
912 The right operand is not evaluated while the operator is in the "false" state,
913 and the left operand is not evaluated while the operator is in the "true" state.
914 The .. operator is primarily intended for doing line number ranges after
915 the fashion of \fIsed\fR or \fIawk\fR.
916 The precedence is a little lower than || and &&.
917 The value returned is either the null string for false, or a sequence number
918 (beginning with 1) for true.
919 The sequence number is reset for each range encountered.
920 The final sequence number in a range has the string 'E0' appended to it, which
921 doesn't affect its numeric value, but gives you something to search for if you
922 want to exclude the endpoint.
923 You can exclude the beginning point by waiting for the sequence number to be
925 If either operand of .. is static, that operand is implicitly compared to
926 the $. variable, the current line number.
931 if (101 .. 200) { print; } # print 2nd hundred lines
933 next line if (1 .. /^$/); # skip header lines
935 s/^/> / if (/^$/ .. eof()); # quote body
940 This unary operator takes one argument, either a filename or a filehandle,
941 and tests the associated file to see if something is true about it.
942 If the argument is omitted, tests $_, except for \-t, which tests stdin.
943 It returns 1 for true and '' for false.
944 Precedence is higher than logical and relational operators, but lower than
945 arithmetic operators.
946 The operator may be any of:
948 \-r File is readable by effective uid.
949 \-w File is writeable by effective uid.
950 \-x File is executable by effective uid.
951 \-o File is owned by effective uid.
952 \-R File is readable by real uid.
953 \-W File is writeable by real uid.
954 \-X File is executable by real uid.
955 \-O File is owned by real uid.
957 \-z File has zero size.
958 \-s File has non-zero size.
959 \-f File is a plain file.
960 \-d File is a directory.
961 \-l File is a symbolic link.
962 \-p File is a named pipe (FIFO).
963 \-S File is a socket.
964 \-b File is a block special file.
965 \-c File is a character special file.
966 \-u File has setuid bit set.
967 \-g File has setgid bit set.
968 \-k File has sticky bit set.
969 \-t Filehandle is opened to a tty.
970 \-T File is a text file.
971 \-B File is a binary file (opposite of \-T).
974 The interpretation of the file permission operators \-r, \-R, \-w, \-W, \-x and \-X
975 is based solely on the mode of the file and the uids and gids of the user.
976 There may be other reasons you can't actually read, write or execute the file.
977 Also note that, for the superuser, \-r, \-R, \-w and \-W always return 1, and
978 \-x and \-X return 1 if any execute bit is set in the mode.
979 Scripts run by the superuser may thus need to do a stat() in order to determine
980 the actual mode of the file, or temporarily set the uid to something else.
988 next unless \-f $_; # ignore specials
993 Note that -s/a/b/ does not do a negated substitution.
994 Saying -exp($foo) still works as expected, however\*(--only single letters
995 following a minus are interpreted as file tests.
997 The \-T and \-B switches work as follows.
998 The first block or so of the file is examined for odd characters such as
999 strange control codes or metacharacters.
1000 If too many odd characters (>10%) are found, it's a \-B file, otherwise it's a \-T file.
1001 Also, any file containing null in the first block is considered a binary file.
1002 If \-T or \-B is used on a filehandle, the current stdio buffer is examined
1003 rather than the first block.
1004 Since input doesn't work well on binary files you should probably test a
1005 filehandle before doing any input if you're unsure of the nature of the
1006 filehandle you've been handed (usually via stdin).
1007 Both \-T and \-B return TRUE on a null file, or a file at EOF when testing
1010 Here is what C has that
1014 Address-of operator.
1016 Dereference-address operator.
1018 Type casting operator.
1022 does a certain amount of expression evaluation at compile time, whenever
1023 it determines that all of the arguments to an operator are static and have
1025 In particular, string concatenation happens at compile time between literals that don't do variable substitution.
1026 Backslash interpretation also happens at compile time.
1031 'Now is the time for all' . "\|\e\|n" .
1032 'good men to come to.'
1035 and this all reduces to one string internally.
1037 The autoincrement operator has a little extra built-in magic to it.
1038 If you increment a variable that is numeric, or that has ever been used in
1039 a numeric context, you get a normal increment.
1040 If, however, the variable has only been used in string contexts since it
1041 was set, and has a value that is not null and matches the
1042 pattern /^[a-zA-Z]*[0-9]*$/, the increment is done
1043 as a string, preserving each character within its range, with carry:
1046 print ++($foo = '99'); # prints '100'
1047 print ++($foo = 'a0'); # prints 'a1'
1048 print ++($foo = 'Az'); # prints 'Ba'
1049 print ++($foo = 'zz'); # prints 'aaa'
1052 The autodecrement is not magical.
1054 Along with the literals and variables mentioned earlier,
1055 the following operations can serve as terms in an expression.
1056 Some of these operations take a LIST as an argument.
1057 Such a list can consist of any combination of scalar arguments or arrays;
1058 the arrays will be included in the list as if each individual element were
1059 interpolated at that point in the list.
1060 .Ip "/PATTERN/i" 8 4
1061 Searches a string for a pattern, and returns true (1) or false ('').
1062 If no string is specified via the =~ or !~ operator,
1063 the $_ string is searched.
1064 (The string specified with =~ need not be an lvalue\*(--it may be the result of an expression evaluation, but remember the =~ binds rather tightly.)
1065 See also the section on regular expressions.
1067 If you prepend an `m' you can use any pair of characters as delimiters.
1068 This is particularly useful for matching Unix path names that contain `/'.
1069 If the final delimiter is followed by the optional letter `i', the matching is
1070 done in a case-insensitive manner.
1072 If used in a context that requires an array value, a pattern match returns an
1073 array consisting of the subexpressions matched by the parens in pattern,
1074 i.e. ($1, $2, $3.\|.\|.).
1080 open(tty, '/dev/tty');
1081 <tty> \|=~ \|/\|^y\|/i \|&& \|do foo(\|); # do foo if desired
1083 if (/Version: \|*\|([0-9.]*\|)\|/\|) { $version = $1; }
1085 next if m#^/usr/spool/uucp#;
1087 if (($F1,$F2,$Etc) = ($foo =~ /^(\eS+)\es+(\eS+)\es*(.*)/))
1090 This last example splits $foo into the first two words and the remainder
1091 of the line, and assigns those three fields to $F1, $F2 and $Etc.
1092 The conditional is true if any variables were assigned, i.e. if the pattern
1095 This is just like the /pattern/ search, except that it matches only once between
1099 This is a useful optimization when you only want to see the first occurence of
1100 something in each file of a set of files, for instance.
1101 .Ip "chdir EXPR" 8 2
1102 Changes the working directory to EXPR, if possible.
1103 Returns 1 upon success, 0 otherwise.
1104 See example under die().
1105 .Ip "chmod LIST" 8 2
1106 Changes the permissions of a list of files.
1107 The first element of the list must be the numerical mode.
1108 Returns the number of files successfully changed.
1112 $cnt = chmod 0755,'foo','bar';
1113 chmod 0755,@executables;
1116 .Ip "chop(VARIABLE)" 8 5
1118 Chops off the last character of a string and returns it.
1119 It's used primarily to remove the newline from the end of an input record,
1120 but is much more efficient than s/\en// because it neither scans nor copies
1122 If VARIABLE is omitted, chops $_.
1128 chop; # avoid \en on last field
1129 @array = split(/:/);
1134 You can actually chop anything that's an lvalue, including an assignment:
1140 .Ip "chown LIST" 8 2
1141 Changes the owner (and group) of a list of files.
1142 The first two elements of the list must be the NUMERICAL uid and gid,
1144 Returns the number of files successfully changed.
1148 $cnt = chown $uid,$gid,'foo','bar';
1149 chown $uid,$gid,@filenames;
1153 Here's an example of looking up non-numeric uids:
1162 open(pass,'/etc/passwd') || die "Can't open passwd";
1164 ($login,$pass,$uid,$gid) = split(/:/);
1165 $uid{$login} = $uid;
1166 $gid{$login} = $gid;
1168 @ary = <$pattern>; # get filenames
1169 if ($uid{$user} eq '') {
1170 die "$user not in passwd file";
1173 unshift(@ary,$uid{$user},$gid{$user});
1178 .Ip "close(FILEHANDLE)" 8 5
1179 .Ip "close FILEHANDLE" 8
1180 Closes the file or pipe associated with the file handle.
1181 You don't have to close FILEHANDLE if you are immediately going to
1182 do another open on it, since open will close it for you.
1185 However, an explicit close on an input file resets the line counter ($.), while
1186 the implicit close done by
1189 Also, closing a pipe will wait for the process executing on the pipe to complete,
1190 in case you want to look at the output of the pipe afterwards.
1195 open(output,'|sort >foo'); # pipe to sort
1196 .\|.\|. # print stuff to output
1197 close(output); # wait for sort to finish
1198 open(input,'foo'); # get sort's results
1201 FILEHANDLE may be an expression whose value gives the real filehandle name.
1202 .Ip "crypt(PLAINTEXT,SALT)" 8 6
1203 Encrypts a string exactly like the crypt() function in the C library.
1204 Useful for checking the password file for lousy passwords.
1205 Only the guys wearing white hats should do this.
1206 .Ip "delete $ASSOC{KEY}" 8 6
1207 Deletes the specified value from the specified associative array.
1208 Returns the deleted value;
1209 The following deletes all the values of an associative array:
1213 foreach $key (keys(ARRAY)) {
1214 delete $ARRAY{$key};
1218 (But it would be faster to use the reset command.)
1220 Prints the value of EXPR to stderr and exits with the current value of $!
1222 If $! is 0, exits with the value of ($? >> 8) (`command` status).
1223 If ($? >> 8) is 0, exits with 255.
1224 Equivalent examples:
1228 die "Can't cd to spool.\en" unless chdir '/usr/spool/news';
1230 chdir '/usr/spool/news' || die "Can't cd to spool.\en"
1234 If the value of EXPR does not end in a newline, the current script line
1235 number and input line number (if any) are also printed, and a newline is
1237 Hint: sometimes appending ", stopped" to your message will cause it to make
1238 better sense when the string "at foo line 123" is appended.
1239 Suppose you are running script "canasta".
1243 die "/etc/games is no good";
1244 die "/etc/games is no good, stopped";
1246 produce, respectively
1248 /etc/games is no good at canasta line 123.
1249 /etc/games is no good, stopped at canasta line 123.
1255 Returns the value of the last command in the sequence of commands indicated
1257 When modified by a loop modifier, executes the BLOCK once before testing the
1259 (On other statements the loop modifiers test the conditional first.)
1260 .Ip "do SUBROUTINE (LIST)" 8 3
1261 Executes a SUBROUTINE declared by a
1263 declaration, and returns the value
1264 of the last expression evaluated in SUBROUTINE.
1265 If you pass arrays as part of LIST you may wish to pass the length
1266 of the array in front of each array.
1267 (See the section on subroutines later on.)
1268 SUBROUTINE may be a scalar variable, in which case the variable contains
1269 the name of the subroutine to execute.
1270 The parentheses are required to avoid confusion with the next form of "do".
1272 Uses the value of EXPR as a filename and executes the contents of the file
1274 It's primary use is to include subroutines from a perl subroutine library.
1283 except that it's more efficient, more concise, keeps track of the current
1284 filename for error messages, and searches all the -I libraries if the file
1285 isn't in the current directory (see also the @INC array in Predefined Names).
1286 It's the same, however, in that it does reparse the file every time you
1287 call it, so if you are going to use the file inside a loop you might prefer
1288 to use #include, at the expense of a little more startup time.
1289 (The main problem with #include is that cpp doesn't grok # comments--a
1290 workaround is to use ";#" for standalone comments.)
1291 Note that the following are NOT equivalent:
1295 do $foo; # eval a file
1296 do $foo(); # call a subroutine
1299 .Ip "each(ASSOC_ARRAY)" 8 6
1300 Returns a 2 element array consisting of the key and value for the next
1301 value of an associative array, so that you can iterate over it.
1302 Entries are returned in an apparently random order.
1303 When the array is entirely read, a null array is returned (which when
1304 assigned produces a FALSE (0) value).
1305 The next call to each() after that will start iterating again.
1306 The iterator can be reset only by reading all the elements from the array.
1307 You must not modify the array while iterating over it.
1308 There is a single iterator for each associative array, shared by all
1309 each(), keys() and values() function calls in the program.
1310 The following prints out your environment like the printenv program, only
1311 in a different order:
1315 while (($key,$value) = each(ENV)) {
1316 print "$key=$value\en";
1320 See also keys() and values().
1321 .Ip "eof(FILEHANDLE)" 8 8
1323 Returns 1 if the next read on FILEHANDLE will return end of file, or if
1324 FILEHANDLE is not open.
1325 FILEHANDLE may be an expression whose value gives the real filehandle name.
1326 An eof without an argument returns the eof status for the last file read.
1327 Empty parentheses () may be used to indicate the pseudo file formed of the
1328 files listed on the command line, i.e. eof() is reasonable to use inside
1329 a while (<>) loop to detect the end of only the last file.
1330 Use eof(ARGV) or eof without the parens to test EACH file in a while (<>) loop.
1335 # insert dashes just before last line of last file
1338 print "--------------\en";
1344 # reset line numbering on each input file
1347 if (eof) { # Not eof().
1354 EXPR is parsed and executed as if it were a little perl program.
1355 It is executed in the context of the current perl program, so that
1356 any variable settings, subroutine or format definitions remain afterwards.
1357 The value returned is the value of the last expression evaluated, just
1358 as with subroutines.
1359 If there is a syntax error or runtime error, a null string is returned by
1360 eval, and $@ is set to the error message.
1361 If there was no error, $@ is null.
1362 If EXPR is omitted, evaluates $_.
1364 If there is more than one argument in LIST,
1365 calls execvp() with the arguments in LIST.
1366 If there is only one argument, the argument is checked for shell metacharacters.
1367 If there are any, the entire argument is passed to /bin/sh -c for parsing.
1368 If there are none, the argument is split into words and passed directly to
1369 execvp(), which is more efficient.
1370 Note: exec (and system) do not flush your output buffer, so you may need to
1371 set $| to avoid lost output.
1375 exec '/bin/echo', 'Your arguments are: ', @ARGV;
1376 exec "sort $outfile | uniq";
1380 Evaluates EXPR and exits immediately with that value.
1386 exit 0 \|if \|$ans \|=~ \|/\|^[Xx]\|/\|;
1392 Returns e to the power of EXPR.
1395 Returns the child pid to the parent process and 0 to the child process.
1396 Note: unflushed buffers remain unflushed in both processes, which means
1397 you may need to set $| to avoid duplicate output.
1398 .Ip "gmtime(EXPR)" 8 4
1399 Converts a time as returned by the time function to a 9-element array with
1400 the time analyzed for the Greenwich timezone.
1401 Typically used as follows:
1405 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
1409 All array elements are numeric, and come straight out of a struct tm.
1410 In particular this means that $mon has the range 0..11 and $wday has the