Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/misc/volume18/perl/part08

Internet Message Format | 1991-04-15 | 50.2 KB

From: [e-mail] (Larry Wall)
Newsgroups: comp.sources.misc
Subject: v18i026:  perl - The perl programming language, Part08/36
Message-ID: <[e-mail]>
Date: 15 Apr 91 23:59:27 GMT
Approved: [e-mail]
X-Checksum-Snefru: 51df451e 07043afb f52ef98d d2b4c999

Submitted-by: Larry Wall <[e-mail]>
Posting-number: Volume 18, Issue 26
Archive-name: perl/part08

[There are 36 kits for perl version 4.0.]

#! /bin/sh

# Make a new directory for the perl sources, cd to it, and run kits 1
# thru 36 through sh.  When all 36 kits have been run, read README.

echo "This is perl 4.0 kit 8 (of 36).  If kit 8 is complete, the line"
echo '"'"End of kit 8 (of 36)"'" will echo at the end.'
echo ""
export PATH || (echo "You didn't use sh, you clunch." ; kill $$)
mkdir  2>/dev/null
echo Extracting perl.man:AC
sed >perl.man:AC <<'!STUFFY!FUNK!' -e 's/X//'
Xpadding with nulls or spaces as necessary.
X(When unpacking, "A" strips trailing spaces and nulls, but "a" does not.)
XLikewise, the "b" and "B" fields pack a string that many bits long.
XThe "h" and "H" fields pack a string that many nybbles long.
XReal numbers (floats and doubles) are in the native machine format
Xonly; due to the multiplicity of floating formats around, and the lack
Xof a standard \*(L"network\*(R" representation, no facility for
Xinterchange has been made.
XThis means that packed floating point data
Xwritten on one machine may not be readable on another - even if both
Xuse IEEE floating point arithmetic (as the endian-ness of the memory
Xrepresentation is not part of the IEEE spec).
XNote that perl uses
Xdoubles internally for all numeric calculation, and converting from
Xdouble -> float -> double will lose precision (i.e. unpack("f",
Xpack("f", $foo)) will not in general equal $foo).
X.br
XExamples:
X.nf
X
X    $foo = pack("cccc",65,66,67,68);
X    # foo eq "ABCD"
X    $foo = pack("c4",65,66,67,68);
X    # same thing
X
X    $foo = pack("ccxxcc",65,66,67,68);
X    # foo eq "AB\e0\e0CD"
X
X    $foo = pack("s2",1,2);
X    # "\e1\e0\e2\e0" on little-endian
X    # "\e0\e1\e0\e2" on big-endian
X
X    $foo = pack("a4","abcd","x","y","z");
X    # "abcd"
X
X    $foo = pack("aaaa","abcd","x","y","z");
X    # "axyz"
X
X    $foo = pack("a14","abcdefg");
X    # "abcdefg\e0\e0\e0\e0\e0\e0\e0"
X
X    $foo = pack("i9pl", gmtime);
X    # a real struct tm (on my system anyway)
X
X    sub bintodec {
X        unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
X    }
X.fi
XThe same template may generally also be used in the unpack function.
X.Ip "pipe(READHANDLE,WRITEHANDLE)" 8 3
XOpens a pair of connected pipes like the corresponding system call.
XNote that if you set up a loop of piped processes, deadlock can occur
Xunless you are very careful.
XIn addition, note that perl's pipes use stdio buffering, so you may need
Xto set $| to flush your WRITEHANDLE after each command, depending on
Xthe application.
X[Requires version 3.0 patchlevel 9.]
X.Ip "pop(ARRAY)" 8
X.Ip "pop ARRAY" 8 6
XPops and returns the last value of the array, shortening the array by 1.
XHas the same effect as
X.nf
X
X    $tmp = $ARRAY[$#ARRAY\-\|\-];
X
X.fi
XIf there are no elements in the array, returns the undefined value.
X.Ip "print(FILEHANDLE LIST)" 8 10
X.Ip "print(LIST)" 8
X.Ip "print FILEHANDLE LIST" 8
X.Ip "print LIST" 8
X.Ip "print" 8
XPrints a string or a comma-separated list of strings.
XReturns non-zero if successful.
XFILEHANDLE may be a scalar variable name, in which case the variable contains
Xthe name of the filehandle, thus introducing one level of indirection.
X(NOTE: If FILEHANDLE is a variable and the next token is a term, it may be
Xmisinterpreted as an operator unless you interpose a + or put parens around
Xthe arguments.)
XIf FILEHANDLE is omitted, prints by default to standard output (or to the
Xlast selected output channel\*(--see select()).
XIf LIST is also omitted, prints $_ to
X.IR STDOUT .
XTo set the default output channel to something other than
X.I STDOUT
Xuse the select operation.
XNote that, because print takes a LIST, anything in the LIST is evaluated
Xin an array context, and any subroutine that you call will have one or more
Xof its expressions evaluated in an array context.
XAlso be careful not to follow the print keyword with a left parenthesis
Xunless you want the corresponding right parenthesis to terminate the
Xarguments to the print\*(--interpose a + or put parens around all the arguments.
X.Ip "printf(FILEHANDLE LIST)" 8 10
X.Ip "printf(LIST)" 8
X.Ip "printf FILEHANDLE LIST" 8
X.Ip "printf LIST" 8
XEquivalent to a \*(L"print FILEHANDLE sprintf(LIST)\*(R".
X.Ip "push(ARRAY,LIST)" 8 7
XTreats ARRAY (@ is optional) as a stack, and pushes the values of LIST
Xonto the end of ARRAY.
XThe length of ARRAY increases by the length of LIST.
XHas the same effect as
X.nf
X
X    for $value (LIST) {
X        $ARRAY[++$#ARRAY] = $value;
X    }
X
X.fi
Xbut is more efficient.
X.Ip "q/STRING/" 8 5
X.Ip "qq/STRING/" 8
X.Ip "qx/STRING/" 8
XThese are not really functions, but simply syntactic sugar to let you
Xavoid putting too many backslashes into quoted strings.
XThe q operator is a generalized single quote, and the qq operator a
Xgeneralized double quote.
XThe qx operator is a generalized backquote.
XAny non-alphanumeric delimiter can be used in place of /, including newline.
XIf the delimiter is an opening bracket or parenthesis, the final delimiter
Xwill be the corresponding closing bracket or parenthesis.
X(Embedded occurrences of the closing bracket need to be backslashed as usual.)
XExamples:
X.nf
X
X.ne 5
X    $foo = q!I said, "You said, \'She said it.\'"!;
X    $bar = q(\'This is it.\');
X    $today = qx{ date };
X    $_ .= qq
X*** The previous line contains the naughty word "$&".\en
X        if /(ibm|apple|awk)/;      # :-)
X
X.fi
X.Ip "rand(EXPR)" 8 8
X.Ip "rand EXPR" 8
X.Ip "rand" 8
XReturns a random fractional number between 0 and the value of EXPR.
X(EXPR should be positive.)
XIf EXPR is omitted, returns a value between 0 and 1.
XSee also srand().
X.Ip "read(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5
X.Ip "read(FILEHANDLE,SCALAR,LENGTH)" 8 5
XAttempts to read LENGTH bytes of data into variable SCALAR from the specified
XFILEHANDLE.
XReturns the number of bytes actually read, or undef if there was an error.
XSCALAR will be grown or shrunk to the length actually read.
XAn OFFSET may be specified to place the read data at some other place
Xthan the beginning of the string.
XThis call is actually implemented in terms of stdio's fread call.  To get
Xa true read system call, see sysread.
X.Ip "readdir(DIRHANDLE)" 8 3
X.Ip "readdir DIRHANDLE" 8
XReturns the next directory entry for a directory opened by opendir().
XIf used in an array context, returns all the rest of the entries in the
Xdirectory.
XIf there are no more entries, returns an undefined value in a scalar context
Xor a null list in an array context.
X.Ip "readlink(EXPR)" 8 6
X.Ip "readlink EXPR" 8
XReturns the value of a symbolic link, if symbolic links are implemented.
XIf not, gives a fatal error.
XIf there is some system error, returns the undefined value and sets $! (errno).
XIf EXPR is omitted, uses $_.
X.Ip "recv(SOCKET,SCALAR,LEN,FLAGS)" 8 4
XReceives a message on a socket.
XAttempts to receive LENGTH bytes of data into variable SCALAR from the specified
XSOCKET filehandle.
XReturns the address of the sender, or the undefined value if there's an error.
XSCALAR will be grown or shrunk to the length actually read.
XTakes the same flags as the system call of the same name.
X.Ip "redo LABEL" 8 8
X.Ip "redo" 8
XThe
X.I redo
Xcommand restarts the loop block without evaluating the conditional again.
XThe
X.I continue
Xblock, if any, is not executed.
XIf the LABEL is omitted, the command refers to the innermost enclosing loop.
XThis command is normally used by programs that want to lie to themselves
Xabout what was just input:
X.nf
X
X.ne 16
X    # a simpleminded Pascal comment stripper
X    # (warning: assumes no { or } in strings)
X    line: while (<STDIN>) {
X        while (s|\|({.*}.*\|){.*}|$1 \||) {}
X        s|{.*}| \||;
X        if (s|{.*| \||) {
X            $front = $_;
X            while (<STDIN>) {
X                if (\|/\|}/\|) {    # end of comment?
X                    s|^|$front{|;
X                    redo line;
X                }
X            }
X        }
X        print;
X    }
X
X.fi
X.Ip "rename(OLDNAME,NEWNAME)" 8 2
XChanges the name of a file.
XReturns 1 for success, 0 otherwise.
XWill not work across filesystem boundaries.
X.Ip "require(EXPR)" 8 6
X.Ip "require EXPR" 8
X.Ip "require" 8
XIncludes the library file specified by EXPR, or by $_ if EXPR is not supplied.
XHas semantics similar to the following subroutine:
X.nf
X
X    sub require {
X        local($filename) = @_;
X        return 1 if $INC{$filename};
X        local($realfilename,$result);
X        ITER: {
X        foreach $prefix (@INC) {
X            $realfilename = "$prefix/$filename";
X            if (-f $realfilename) {
X            $result = do $realfilename;
X            last ITER;
X            }
X        }
X        die "Can't find $filename in \e@INC";
X        }
X        die $@ if $@;
X        die "$filename did not return true value" unless $result;
X        $INC{$filename} = $realfilename;
X        $result;
X    }
X
X.fi
XNote that the file will not be included twice under the same specified name.
X.Ip "reset(EXPR)" 8 6
X.Ip "reset EXPR" 8
X.Ip "reset" 8
XGenerally used in a
X.I continue
Xblock at the end of a loop to clear variables and reset ?? searches
Xso that they work again.
XThe expression is interpreted as a list of single characters (hyphens allowed
Xfor ranges).
XAll variables and arrays beginning with one of those letters are reset to
Xtheir pristine state.
XIf the expression is omitted, one-match searches (?pattern?) are reset to
Xmatch again.
XOnly resets variables or searches in the current package.
XAlways returns 1.
XExamples:
X.nf
X
X.ne 3
X    reset \'X\';    \h'|2i'# reset all X variables
X    reset \'a\-z\';\h'|2i'# reset lower case variables
X    reset;    \h'|2i'# just reset ?? searches
X
X.fi
XNote: resetting \*(L"A\-Z\*(R" is not recommended since you'll wipe out your ARGV and ENV
Xarrays.
X.Sp
XThe use of reset on dbm associative arrays does not change the dbm file.
X(It does, however, flush any entries cached by perl, which may be useful if
Xyou are sharing the dbm file.
XThen again, maybe not.)
X.Ip "return LIST" 8 3
XReturns from a subroutine with the value specified.
X(Note that a subroutine can automatically return
Xthe value of the last expression evaluated.
XThat's the preferred method\*(--use of an explicit
X.I return
Xis a bit slower.)
X.Ip "reverse(LIST)" 8 4
X.Ip "reverse LIST" 8
XIn an array context, returns an array value consisting of the elements
Xof LIST in the opposite order.
XIn a scalar context, returns a string value consisting of the bytes of
Xthe first element of LIST in the opposite order.
X.Ip "rewinddir(DIRHANDLE)" 8 5
X.Ip "rewinddir DIRHANDLE" 8
XSets the current position to the beginning of the directory for the readdir() routine on DIRHANDLE.
X.Ip "rindex(STR,SUBSTR,POSITION)" 8 6
X.Ip "rindex(STR,SUBSTR)" 8 4
XWorks just like index except that it
Xreturns the position of the LAST occurrence of SUBSTR in STR.
XIf POSITION is specified, returns the last occurrence at or before that
Xposition.
X.Ip "rmdir(FILENAME)" 8 4
X.Ip "rmdir FILENAME" 8
XDeletes the directory specified by FILENAME if it is empty.
XIf it succeeds it returns 1, otherwise it returns 0 and sets $! (errno).
XIf FILENAME is omitted, uses $_.
X.Ip "s/PATTERN/REPLACEMENT/gieo" 8 3
XSearches a string for a pattern, and if found, replaces that pattern with the
Xreplacement text and returns the number of substitutions made.
XOtherwise it returns false (0).
XThe \*(L"g\*(R" is optional, and if present, indicates that all occurrences
Xof the pattern are to be replaced.
XThe \*(L"i\*(R" is also optional, and if present, indicates that matching
Xis to be done in a case-insensitive manner.
XThe \*(L"e\*(R" is likewise optional, and if present, indicates that
Xthe replacement string is to be evaluated as an expression rather than just
Xas a double-quoted string.
XAny non-alphanumeric delimiter may replace the slashes;
Xif single quotes are used, no
Xinterpretation is done on the replacement string (the e modifier overrides
Xthis, however); if backquotes are used, the replacement string is a command
Xto execute whose output will be used as the actual replacement text.
XIf no string is specified via the =~ or !~ operator,
Xthe $_ string is searched and modified.
X(The string specified with =~ must be a scalar variable, an array element,
Xor an assignment to one of those, i.e. an lvalue.)
XIf the pattern contains a $ that looks like a variable rather than an
Xend-of-string test, the variable will be interpolated into the pattern at
Xrun-time.
XIf you only want the pattern compiled once the first time the variable is
Xinterpolated, add an \*(L"o\*(R" at the end.
XIf the PATTERN evaluates to a null string, the most recent successful
Xregular expression is used instead.
XSee also the section on regular expressions.
XExamples:
X.nf
X
X    s/\|\e\|bgreen\e\|b/mauve/g;        # don't change wintergreen
X
X    $path \|=~ \|s|\|/usr/bin|\|/usr/local/bin|;
X
X    s/Login: $foo/Login: $bar/; # run-time pattern
X
X    ($foo = $bar) =~ s/bar/foo/;
X
X    $_ = \'abc123xyz\';
X    s/\ed+/$&*2/e;        # yields \*(L'abc246xyz\*(R'
X    s/\ed+/sprintf("%5d",$&)/e;    # yields \*(L'abc  246xyz\*(R'
X    s/\ew/$& x 2/eg;        # yields \*(L'aabbcc  224466xxyyzz\*(R'
X
X    s/\|([^ \|]*\|) *\|([^ \|]*\|)\|/\|$2 $1/;    # reverse 1st two fields
X
X.fi
X(Note the use of $ instead of \|\e\| in the last example.  See section
Xon regular expressions.)
X.Ip "scalar(EXPR)" 8 3
XForces EXPR to be interpreted in a scalar context and returns the value
Xof EXPR.
X.Ip "seek(FILEHANDLE,POSITION,WHENCE)" 8 3
XRandomly positions the file pointer for FILEHANDLE, just like the fseek()
Xcall of stdio.
XFILEHANDLE may be an expression whose value gives the name of the filehandle.
XReturns 1 upon success, 0 otherwise.
X.Ip "seekdir(DIRHANDLE,POS)" 8 3
XSets the current position for the readdir() routine on DIRHANDLE.
XPOS must be a value returned by telldir().
XHas the same caveats about possible directory compaction as the corresponding
Xsystem library routine.
X.Ip "select(FILEHANDLE)" 8 3
X.Ip "select" 8 3
XReturns the currently selected filehandle.
XSets the current default filehandle for output, if FILEHANDLE is supplied.
XThis has two effects: first, a
X.I write
Xor a
X.I print
Xwithout a filehandle will default to this FILEHANDLE.
XSecond, references to variables related to output will refer to this output
Xchannel.
XFor example, if you have to set the top of form format for more than
Xone output channel, you might do the following:
X.nf
X
X.ne 4
X    select(REPORT1);
X    $^ = \'report1_top\';
X    select(REPORT2);
X    $^ = \'report2_top\';
X
X.fi
XFILEHANDLE may be an expression whose value gives the name of the actual filehandle.
XThus:
X.nf
X
X    $oldfh = select(STDERR); $| = 1; select($oldfh);
X
X.fi
X.Ip "select(RBITS,WBITS,EBITS,TIMEOUT)" 8 3
XThis calls the select system call with the bitmasks specified, which can
Xbe constructed using fileno() and vec(), along these lines:
X.nf
X
X    $rin = $win = $ein = '';
X    vec($rin,fileno(STDIN),1) = 1;
X    vec($win,fileno(STDOUT),1) = 1;
X    $ein = $rin | $win;
X
X.fi
XIf you want to select on many filehandles you might wish to write a subroutine:
X.nf
X
X    sub fhbits {
X        local(@fhlist) = split(' ',$_[0]);
X        local($bits);
X        for (@fhlist) {
X        vec($bits,fileno($_),1) = 1;
X        }
X        $bits;
X    }
X    $rin = &fhbits('STDIN TTY SOCK');
X
X.fi
XThe usual idiom is:
X.nf
X
X    ($nfound,$timeleft) =
X      select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
X
Xor to block until something becomes ready:
X
X.ie t \{\
X    $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
X'br\}
X.el \{\
X    $nfound = select($rout=$rin, $wout=$win,
X                $eout=$ein, undef);
X'br\}
X
X.fi
XAny of the bitmasks can also be undef.
XThe timeout, if specified, is in seconds, which may be fractional.
XNOTE: not all implementations are capable of returning the $timeleft.
XIf not, they always return $timeleft equal to the supplied $timeout.
X.Ip "semctl(ID,SEMNUM,CMD,ARG)" 8 4
XCalls the System V IPC function semctl.  If CMD is &IPC_STAT or
X&GETALL, then ARG must be a variable which will hold the returned
Xsemid_ds structure or semaphore value array.  Returns like ioctl: the
Xundefined value for error, "0 but true" for zero, or the actual return
Xvalue otherwise.
X.Ip "semget(KEY,NSEMS,SIZE,FLAGS)" 8 4
XCalls the System V IPC function semget.  Returns the semaphore id, or
Xthe undefined value if there is an error.
X.Ip "semop(KEY,OPSTRING)" 8 4
XCalls the System V IPC function semop to perform semaphore operations
Xsuch as signaling and waiting.  OPSTRING must be a packed array of
Xsemop structures.  Each semop structure can be generated with
X\&'pack("sss", $semnum, $semop, $semflag)'.  The number of semaphore
Xoperations is implied by the length of OPSTRING.  Returns true if
Xsuccessful, or false if there is an error.  As an example, the
Xfollowing code waits on semaphore $semnum of semaphore id $semid:
X.nf
X
X    $semop = pack("sss", $semnum, -1, 0);
X    die "Semaphore trouble: $!\en" unless semop($semid, $semop);
X
X.fi
XTo signal the semaphore, replace "-1" with "1".
X.Ip "send(SOCKET,MSG,FLAGS,TO)" 8 4
X.Ip "send(SOCKET,MSG,FLAGS)" 8
XSends a message on a socket.
XTakes the same flags as the system call of the same name.
XOn unconnected sockets you must specify a destination to send TO.
XReturns the number of characters sent, or the undefined value if
Xthere is an error.
X.Ip "setpgrp(PID,PGRP)" 8 4
XSets the current process group for the specified PID, 0 for the current
Xprocess.
XWill produce a fatal error if used on a machine that doesn't implement
Xsetpgrp(2).
X.Ip "setpriority(WHICH,WHO,PRIORITY)" 8 4
XSets the current priority for a process, a process group, or a user.
X(See setpriority(2).)
XWill produce a fatal error if used on a machine that doesn't implement
Xsetpriority(2).
X.Ip "setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL)" 8 3
XSets the socket option requested.
XReturns undefined if there is an error.
XOPTVAL may be specified as undef if you don't want to pass an argument.
X.Ip "shift(ARRAY)" 8 6
X.Ip "shift ARRAY" 8
X.Ip "shift" 8
XShifts the first value of the array off and returns it,
Xshortening the array by 1 and moving everything down.
XIf there are no elements in the array, returns the undefined value.
XIf ARRAY is omitted, shifts the @ARGV array in the main program, and the @_
Xarray in subroutines.
X(This is determined lexically.)
XSee also unshift(), push() and pop().
XShift() and unshift() do the same thing to the left end of an array that push()
Xand pop() do to the right end.
X.Ip "shmctl(ID,CMD,ARG)" 8 4
XCalls the System V IPC function shmctl.  If CMD is &IPC_STAT, then ARG
Xmust be a variable which will hold the returned shmid_ds structure.
XReturns like ioctl: the undefined value for error, "0 but true" for
Xzero, or the actual return value otherwise.
X.Ip "shmget(KEY,SIZE,FLAGS)" 8 4
XCalls the System V IPC function shmget.  Returns the shared memory
Xsegment id, or the undefined value if there is an error.
X.Ip "shmread(ID,VAR,POS,SIZE)" 8 4
X.Ip "shmwrite(ID,STRING,POS,SIZE)" 8
XReads or writes the System V shared memory segment ID starting at
Xposition POS for size SIZE by attaching to it, copying in/out, and
Xdetaching from it.  When reading, VAR must be a variable which
Xwill hold the data read.  When writing, if STRING is too long,
Xonly SIZE bytes are used; if STRING is too short, nulls are
Xwritten to fill out SIZE bytes.  Return true if successful, or
Xfalse if there is an error.
X.Ip "shutdown(SOCKET,HOW)" 8 3
XShuts down a socket connection in the manner indicated by HOW, which has
Xthe same interpretation as in the system call of the same name.
X.Ip "sin(EXPR)" 8 4
X.Ip "sin EXPR" 8
XReturns the sine of EXPR (expressed in radians).
XIf EXPR is omitted, returns sine of $_.
X.Ip "sleep(EXPR)" 8 6
X.Ip "sleep EXPR" 8
X.Ip "sleep" 8
XCauses the script to sleep for EXPR seconds, or forever if no EXPR.
XMay be interrupted by sending the process a SIGALARM.
XReturns the number of seconds actually slept.
X.Ip "socket(SOCKET,DOMAIN,TYPE,PROTOCOL)" 8 3
XOpens a socket of the specified kind and attaches it to filehandle SOCKET.
XDOMAIN, TYPE and PROTOCOL are specified the same as for the system call
Xof the same name.
XYou may need to run h2ph on sys/socket.h to get the proper values handy
Xin a perl library file.
XReturn true if successful.
XSee the example in the section on Interprocess Communication.
X.Ip "socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL)" 8 3
XCreates an unnamed pair of sockets in the specified domain, of the specified
Xtype.
XDOMAIN, TYPE and PROTOCOL are specified the same as for the system call
Xof the same name.
XIf unimplemented, yields a fatal error.
XReturn true if successful.
X.Ip "sort(SUBROUTINE LIST)" 8 9
X.Ip "sort(LIST)" 8
X.Ip "sort SUBROUTINE LIST" 8
X.Ip "sort LIST" 8
XSorts the LIST and returns the sorted array value.
XNonexistent values of arrays are stripped out.
XIf SUBROUTINE is omitted, sorts in standard string comparison order.
XIf SUBROUTINE is specified, gives the name of a subroutine that returns
Xan integer less than, equal to, or greater than 0,
Xdepending on how the elements of the array are to be ordered.
XIn the interests of efficiency the normal calling code for subroutines
Xis bypassed, with the following effects: the subroutine may not be a recursive
Xsubroutine, and the two elements to be compared are passed into the subroutine
Xnot via @_ but as $a and $b (see example below).
XThey are passed by reference so don't modify $a and $b.
XSUBROUTINE may be a scalar variable name, in which case the value provides
Xthe name of the subroutine to use.
XExamples:
X.nf
X
X.ne 4
X    sub byage {
X        $age{$a} - $age{$b};    # presuming integers
X    }
X    @sortedclass = sort byage @class;
X
X.ne 9
X    sub reverse { $a lt $b ? 1 : $a gt $b ? \-1 : 0; }
X    @harry = (\'dog\',\'cat\',\'x\',\'Cain\',\'Abel\');
X    @george = (\'gone\',\'chased\',\'yz\',\'Punished\',\'Axed\');
X    print sort @harry;
X        # prints AbelCaincatdogx
X    print sort reverse @harry;
X        # prints xdogcatCainAbel
X    print sort @george, \'to\', @harry;
X        # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
X
X.fi
X.Ip "splice(ARRAY,OFFSET,LENGTH,LIST)" 8 8
X.Ip "splice(ARRAY,OFFSET,LENGTH)" 8
X.Ip "splice(ARRAY,OFFSET)" 8
XRemoves the elements designated by OFFSET and LENGTH from an array, and
Xreplaces them with the elements of LIST, if any.
XReturns the elements removed from the array.
XThe array grows or shrinks as necessary.
XIf LENGTH is omitted, removes everything from OFFSET onward.
XThe following equivalencies hold (assuming $[ == 0):
X.nf
X
X    push(@a,$x,$y)\h'|3.5i'splice(@a,$#a+1,0,$x,$y)
X    pop(@a)\h'|3.5i'splice(@a,-1)
X    shift(@a)\h'|3.5i'splice(@a,0,1)
X    unshift(@a,$x,$y)\h'|3.5i'splice(@a,0,0,$x,$y)
X    $a[$x] = $y\h'|3.5i'splice(@a,$x,1,$y);
X
XExample, assuming array lengths are passed before arrays:
X
X    sub aeq {    # compare two array values
X        local(@a) = splice(@_,0,shift);
X        local(@b) = splice(@_,0,shift);
X        return 0 unless @a == @b;    # same len?
X        while (@a) {
X            return 0 if pop(@a) ne pop(@b);
X        }
X        return 1;
X    }
X    if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
X
X.fi
X.Ip "split(/PATTERN/,EXPR,LIMIT)" 8 8
X.Ip "split(/PATTERN/,EXPR)" 8 8
X.Ip "split(/PATTERN/)" 8
X.Ip "split" 8
XSplits a string into an array of strings, and returns it.
X(If not in an array context, returns the number of fields found and splits
Xinto the @_ array.
X(In an array context, you can force the split into @_
Xby using ?? as the pattern delimiters, but it still returns the array value.))
XIf EXPR is omitted, splits the $_ string.
XIf PATTERN is also omitted, splits on whitespace (/[\ \et\en]+/).
XAnything matching PATTERN is taken to be a delimiter separating the fields.
X(Note that the delimiter may be longer than one character.)
XIf LIMIT is specified, splits into no more than that many fields (though it
Xmay split into fewer).
XIf LIMIT is unspecified, trailing null fields are stripped (which
Xpotential users of pop() would do well to remember).
XA pattern matching the null string (not to be confused with a null pattern //,
Xwhich is just one member of the set of patterns matching a null string)
Xwill split the value of EXPR into separate characters at each point it
Xmatches that way.
XFor example:
X.nf
X
X    print join(\':\', split(/ */, \'hi there\'));
X
X.fi
Xproduces the output \*(L'h:i:t:h:e:r:e\*(R'.
X.Sp
XThe LIMIT parameter can be used to partially split a line
X.nf
X
X    ($login, $passwd, $remainder) = split(\|/\|:\|/\|, $_, 3);
X
X.fi
X(When assigning to a list, if LIMIT is omitted, perl supplies a LIMIT one
Xlarger than the number of variables in the list, to avoid unnecessary work.
XFor the list above LIMIT would have been 4 by default.
XIn time critical applications it behooves you not to split into
Xmore fields than you really need.)
X.Sp
XIf the PATTERN contains parentheses, additional array elements are created
Xfrom each matching substring in the delimiter.
X.Sp
X    split(/([,-])/,"1-10,20");
X.Sp
Xproduces the array value
X.Sp
X    (1,'-',10,',',20)
X.Sp
XThe pattern /PATTERN/ may be replaced with an expression to specify patterns
Xthat vary at runtime.
X(To do runtime compilation only once, use /$variable/o.)
XAs a special case, specifying a space (\'\ \') will split on white space
Xjust as split with no arguments does, but leading white space does NOT
Xproduce a null first field.
XThus, split(\'\ \') can be used to emulate
X.IR awk 's
Xdefault behavior, whereas
Xsplit(/\ /) will give you as many null initial fields as there are
Xleading spaces.
X.Sp
XExample:
X.nf
X
X.ne 5
X    open(passwd, \'/etc/passwd\');
X    while (<passwd>) {
X.ie t \{\
X        ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(\|/\|:\|/\|);
X'br\}
X.el \{\
X        ($login, $passwd, $uid, $gid, $gcos, $home, $shell)
X            = split(\|/\|:\|/\|);
X'br\}
X        .\|.\|.
X    }
X
X.fi
X(Note that $shell above will still have a newline on it.  See chop().)
XSee also
X.IR join .
X.Ip "sprintf(FORMAT,LIST)" 8 4
XReturns a string formatted by the usual printf conventions.
XThe * character is not supported.
X.Ip "sqrt(EXPR)" 8 4
X.Ip "sqrt EXPR" 8
XReturn the square root of EXPR.
XIf EXPR is omitted, returns square root of $_.
X.Ip "srand(EXPR)" 8 4
X.Ip "srand EXPR" 8
XSets the random number seed for the
X.I rand
Xoperator.
XIf EXPR is omitted, does srand(time).
X.Ip "stat(FILEHANDLE)" 8 8
X.Ip "stat FILEHANDLE" 8
X.Ip "stat(EXPR)" 8
X.Ip "stat SCALARVARIABLE" 8
XReturns a 13-element array giving the statistics for a file, either the file
Xopened via FILEHANDLE, or named by EXPR.
XTypically used as follows:
X.nf
X
X.ne 3
X    ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
X       $atime,$mtime,$ctime,$blksize,$blocks)
X           = stat($filename);
X
X.fi
XIf stat is passed the special filehandle consisting of an underline,
Xno stat is done, but the current contents of the stat structure from
Xthe last stat or filetest are returned.
XExample:
X.nf
X
X.ne 3
X    if (-x $file && (($d) = stat(_)) && $d < 0) {
X        print "$file is executable NFS file\en";
X    }
X
X.fi
X.Ip "study(SCALAR)" 8 6
X.Ip "study SCALAR" 8
X.Ip "study"
XTakes extra time to study SCALAR ($_ if unspecified) in anticipation of
Xdoing many pattern matches on the string before it is next modified.
XThis may or may not save time, depending on the nature and number of patterns
Xyou are searching on, and on the distribution of character frequencies in
Xthe string to be searched\*(--you probably want to compare runtimes with and
Xwithout it to see which runs faster.
XThose loops which scan for many short constant strings (including the constant
Xparts of more complex patterns) will benefit most.
XYou may have only one study active at a time\*(--if you study a different
Xscalar the first is \*(L"unstudied\*(R".
X(The way study works is this: a linked list of every character in the string
Xto be searched is made, so we know, for example, where all the \*(L'k\*(R' characters
Xare.
XFrom each search string, the rarest character is selected, based on some
Xstatic frequency tables constructed from some C programs and English text.
XOnly those places that contain this \*(L"rarest\*(R" character are examined.)
X.Sp
XFor example, here is a loop which inserts index producing entries before any line
Xcontaining a certain pattern:
X.nf
X
X.ne 8
X    while (<>) {
X        study;
X        print ".IX foo\en" if /\ebfoo\eb/;
X        print ".IX bar\en" if /\ebbar\eb/;
X        print ".IX blurfl\en" if /\ebblurfl\eb/;
X        .\|.\|.
X        print;
X    }
X
X.fi
XIn searching for /\ebfoo\eb/, only those locations in $_ that contain \*(L'f\*(R'
Xwill be looked at, because \*(L'f\*(R' is rarer than \*(L'o\*(R'.
XIn general, this is a big win except in pathological cases.
XThe only question is whether it saves you more time than it took to build
Xthe linked list in the first place.
X.Sp
XNote that if you have to look for strings that you don't know till runtime,
Xyou can build an entire loop as a string and eval that to avoid recompiling
Xall your patterns all the time.
XTogether with undefining $/ to input entire files as one record, this can
Xbe very fast, often faster than specialized programs like fgrep.
XThe following scans a list of files (@files)
Xfor a list of words (@words), and prints out the names of those files that
Xcontain a match:
X.nf
X
X.ne 12
X    $search = \'while (<>) { study;\';
X    foreach $word (@words) {
X        $search .= "++\e$seen{\e$ARGV} if /\eb$word\eb/;\en";
X    }
X    $search .= "}";
X    @ARGV = @files;
X    undef $/;
X    eval $search;        # this screams
X    $/ = "\en";        # put back to normal input delim
X    foreach $file (sort keys(%seen)) {
X        print $file, "\en";
X    }
X
X.fi
X.Ip "substr(EXPR,OFFSET,LEN)" 8 2
X.Ip "substr(EXPR,OFFSET)" 8 2
XExtracts a substring out of EXPR and returns it.
XFirst character is at offset 0, or whatever you've set $[ to.
XIf OFFSET is negative, starts that far from the end of the string.
XIf LEN is omitted, returns everything to the end of the string.
XYou can use the substr() function as an lvalue, in which case EXPR must
Xbe an lvalue.
XIf you assign something shorter than LEN, the string will shrink, and
Xif you assign something longer than LEN, the string will grow to accommodate it.
XTo keep the string the same length you may need to pad or chop your value using
Xsprintf().
X.Ip "symlink(OLDFILE,NEWFILE)" 8 2
XCreates a new filename symbolically linked to the old filename.
XReturns 1 for success, 0 otherwise.
XOn systems that don't support symbolic links, produces a fatal error at
Xrun time.
XTo check for that, use eval:
X.nf
X
X    $symlink_exists = (eval \'symlink("","");\', $@ eq \'\');
X
X.fi
X.Ip "syscall(LIST)" 8 6
X.Ip "syscall LIST" 8
XCalls the system call specified as the first element of the list, passing
Xthe remaining elements as arguments to the system call.
XIf unimplemented, produces a fatal error.
XThe arguments are interpreted as follows: if a given argument is numeric,
Xthe argument is passed as an int.
XIf not, the pointer to the string value is passed.
XYou are responsible to make sure a string is pre-extended long enough
Xto receive any result that might be written into a string.
XIf your integer arguments are not literals and have never been interpreted
Xin a numeric context, you may need to add 0 to them to force them to look
Xlike numbers.
X.nf
X
X    require 'syscall.ph';        # may need to run h2ph
X    syscall(&SYS_write, fileno(STDOUT), "hi there\en", 9);
X
X.fi
X.Ip "sysread(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5
X.Ip "sysread(FILEHANDLE,SCALAR,LENGTH)" 8 5
XAttempts to read LENGTH bytes of data into variable SCALAR from the specified
XFILEHANDLE, using the system call read(2).
XIt bypasses stdio, so mixing this with other kinds of reads may cause
Xconfusion.
XReturns the number of bytes actually read, or undef if there was an error.
XSCALAR will be grown or shrunk to the length actually read.
XAn OFFSET may be specified to place the read data at some other place
Xthan the beginning of the string.
X.Ip "system(LIST)" 8 6
X.Ip "system LIST" 8
XDoes exactly the same thing as \*(L"exec LIST\*(R" except that a fork
Xis done first, and the parent process waits for the child process to complete.
XNote that argument processing varies depending on the number of arguments.
XThe return value is the exit status of the program as returned by the wait()
Xcall.
XTo get the actual exit value divide by 256.
XSee also
X.IR exec .
X.Ip "syswrite(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5
X.Ip "syswrite(FILEHANDLE,SCALAR,LENGTH)" 8 5
XAttempts to write LENGTH bytes of data from variable SCALAR to the specified
XFILEHANDLE, using the system call write(2).
XIt bypasses stdio, so mixing this with prints may cause
Xconfusion.
XReturns the number of bytes actually written, or undef if there was an error.
XAn OFFSET may be specified to place the read data at some other place
Xthan the beginning of the string.
X.Ip "tell(FILEHANDLE)" 8 6
X.Ip "tell FILEHANDLE" 8 6
X.Ip "tell" 8
XReturns the current file position for FILEHANDLE.
XFILEHANDLE may be an expression whose value gives the name of the actual
Xfilehandle.
XIf FILEHANDLE is omitted, assumes the file last read.
X.Ip "telldir(DIRHANDLE)" 8 5
X.Ip "telldir DIRHANDLE" 8
XReturns the current position of the readdir() routines on DIRHANDLE.
XValue may be given to seekdir() to access a particular location in
Xa directory.
XHas the same caveats about possible directory compaction as the corresponding
Xsystem library routine.
X.Ip "time" 8 4
XReturns the number of non-leap seconds since 00:00:00 UTC, January 1, 1970.
XSuitable for feeding to gmtime() and localtime().
X.Ip "times" 8 4
XReturns a four-element array giving the user and system times, in seconds, for this
Xprocess and the children of this process.
X.Sp
X    ($user,$system,$cuser,$csystem) = times;
X.Sp
X.Ip "tr/SEARCHLIST/REPLACEMENTLIST/cds" 8 5
X.Ip "y/SEARCHLIST/REPLACEMENTLIST/cds" 8
XTranslates all occurrences of the characters found in the search list with
Xthe corresponding character in the replacement list.
XIt returns the number of characters replaced or deleted.
XIf no string is specified via the =~ or !~ operator,
Xthe $_ string is translated.
X(The string specified with =~ must be a scalar variable, an array element,
Xor an assignment to one of those, i.e. an lvalue.)
XFor
X.I sed
Xdevotees,
X.I y
Xis provided as a synonym for
X.IR tr .
X.Sp
XIf the c modifier is specified, the SEARCHLIST character set is complemented.
XIf the d modifier is specified, any characters specified by SEARCHLIST that
Xare not found in REPLACEMENTLIST are deleted.
X(Note that this is slightly more flexible than the behavior of some
X.I tr
Xprograms, which delete anything they find in the SEARCHLIST, period.)
XIf the s modifier is specified, sequences of characters that were translated
Xto the same character are squashed down to 1 instance of the character.
X.Sp
XIf the d modifier was used, the REPLACEMENTLIST is always interpreted exactly
Xas specified.
XOtherwise, if the REPLACEMENTLIST is shorter than the SEARCHLIST,
Xthe final character is replicated till it is long enough.
XIf the REPLACEMENTLIST is null, the SEARCHLIST is replicated.
XThis latter is useful for counting characters in a class, or for squashing
Xcharacter sequences in a class.
X.Sp
XExamples:
X.nf
X
X    $ARGV[1] \|=~ \|y/A\-Z/a\-z/;    \h'|3i'# canonicalize to lower case
X
X    $cnt = tr/*/*/;        \h'|3i'# count the stars in $_
X
X    $cnt = tr/0\-9//;        \h'|3i'# count the digits in $_
X
X    tr/a\-zA\-Z//s;    \h'|3i'# bookkeeper \-> bokeper
X
X    ($HOST = $host) =~ tr/a\-z/A\-Z/;
X
X    y/a\-zA\-Z/ /cs;    \h'|3i'# change non-alphas to single space
X
X    tr/\e200\-\e377/\e0\-\e177/;\h'|3i'# delete 8th bit
X
X.fi
X.Ip "truncate(FILEHANDLE,LENGTH)" 8 4
X.Ip "truncate(EXPR,LENGTH)" 8
XTruncates the file opened on FILEHANDLE, or named by EXPR, to the specified
Xlength.
XProduces a fatal error if truncate isn't implemented on your system.
X.Ip "umask(EXPR)" 8 4
X.Ip "umask EXPR" 8
X.Ip "umask" 8
XSets the umask for the process and returns the old one.
XIf EXPR is omitted, merely returns current umask.
X.Ip "undef(EXPR)" 8 6
X.Ip "undef EXPR" 8
X.Ip "undef" 8
XUndefines the value of EXPR, which must be an lvalue.
XUse only on a scalar value, an entire array, or a subroutine name (using &).
X(Undef will probably not do what you expect on most predefined variables or
Xdbm array values.)
XAlways returns the undefined value.
XYou can omit the EXPR, in which case nothing is undefined, but you still
Xget an undefined value that you could, for instance, return from a subroutine.
XExamples:
X.nf
X
X.ne 6
X    undef $foo;
X    undef $bar{'blurfl'};
X    undef @ary;
X    undef %assoc;
X    undef &mysub;
X    return (wantarray ? () : undef) if $they_blew_it;
X
X.fi
X.Ip "unlink(LIST)" 8 4
X.Ip "unlink LIST" 8
XDeletes a list of files.
XReturns the number of files successfully deleted.
X.nf
X
X.ne 2
X    $cnt = unlink \'a\', \'b\', \'c\';
X    unlink @goners;
X    unlink <*.bak>;
X
X.fi
XNote: unlink will not delete directories unless you are superuser and the
X.B \-U
Xflag is supplied to
X.IR perl .
XEven if these conditions are met, be warned that unlinking a directory
Xcan inflict damage on your filesystem.
XUse rmdir instead.
X.Ip "unpack(TEMPLATE,EXPR)" 8 4
XUnpack does the reverse of pack: it takes a string representing
Xa structure and expands it out into an array value, returning the array
Xvalue.
X(In a scalar context, it merely returns the first value produced.)
XThe TEMPLATE has the same format as in the pack function.
XHere's a subroutine that does substring:
X.nf
X
X.ne 4
X    sub substr {
X        local($what,$where,$howmuch) = @_;
X        unpack("x$where a$howmuch", $what);
X    }
X
X.ne 3
Xand then there's
X
X    sub ord { unpack("c",$_[0]); }
X
X.fi
XIn addition, you may prefix a field with a %<number> to indicate that
Xyou want a <number>-bit checksum of the items instead of the items themselves.
XDefault is a 16-bit checksum.
XFor example, the following computes the same number as the System V sum program:
X.nf
X
X.ne 4
X    while (<>) {
X        $checksum += unpack("%16C*", $_);
X    }
X    $checksum %= 65536;
X
X.fi
X.Ip "unshift(ARRAY,LIST)" 8 4
XDoes the opposite of a
X.IR shift .
XOr the opposite of a
X.IR push ,
Xdepending on how you look at it.
XPrepends list to the front of the array, and returns the number of elements
Xin the new array.
X.nf
X
X    unshift(ARGV, \'\-e\') unless $ARGV[0] =~ /^\-/;
X
X.fi
X.Ip "utime(LIST)" 8 2
X.Ip "utime LIST" 8 2
XChanges the access and modification times on each file of a list of files.
XThe first two elements of the list must be the NUMERICAL access and
Xmodification times, in that order.
XReturns the number of files successfully changed.
XThe inode modification time of each file is set to the current time.
XExample of a \*(L"touch\*(R" command:
X.nf
X
X.ne 3
X    #!/usr/bin/perl
X    $now = time;
X    utime $now, $now, @ARGV;
X
X.fi
X.Ip "values(ASSOC_ARRAY)" 8 6
X.Ip "values ASSOC_ARRAY" 8
XReturns a normal array consisting of all the values of the named associative
Xarray.
XThe values are returned in an apparently random order, but it is the same order
Xas either the keys() or each() function would produce on the same array.
XSee also keys() and each().
X.Ip "vec(EXPR,OFFSET,BITS)" 8 2
XTreats a string as a vector of unsigned integers, and returns the value
Xof the bitfield specified.
XMay also be assigned to.
XBITS must be a power of two from 1 to 32.
X.Sp
XVectors created with vec() can also be manipulated with the logical operators
X|, & and ^,
Xwhich will assume a bit vector operation is desired when both operands are
Xstrings.
XThis interpretation is not enabled unless there is at least one vec() in
Xyour program, to protect older programs.
X.Sp
XTo transform a bit vector into a string or array of 0's and 1's, use these:
X.nf
X
X    $bits = unpack("b*", $vector);
X    @bits = split(//, unpack("b*", $vector));
X
X.fi
XIf you know the exact length in bits, it can be used in place of the *.
X.Ip "wait" 8 6
XWaits for a child process to terminate and returns the pid of the deceased
Xprocess, or -1 if there are no child processes.
XThe status is returned in $?.
X.Ip "waitpid(PID,FLAGS)" 8 6
XWaits for a particular child process to terminate and returns the pid of the deceased
Xprocess, or -1 if there is no such child process.
XThe status is returned in $?.
XIf you say
X.nf
X
X    require "sys/wait.h";
X    .\|.\|.
X    waitpid(-1,&WNOHANG);
X
X.fi
Xthen you can do a non-blocking wait for any process.  Non-blocking wait
Xis only available on machines supporting either the
X.I waitpid (2)
Xor
X.I wait4 (2)
Xsystem calls.
XHowever, waiting for a particular pid with FLAGS of 0 is implemented
Xeverywhere.  (Perl emulates the system call by remembering the status
Xvalues of processes that have exited but have not been harvested by the
XPerl script yet.)
X.Ip "wantarray" 8 4
XReturns true if the context of the currently executing subroutine
Xis looking for an array value.
XReturns false if the context is looking for a scalar.
X.nf
X
X    return wantarray ? () : undef;
X
X.fi
X.Ip "warn(LIST)" 8 4
X.Ip "warn LIST" 8
XProduces a message on STDERR just like \*(L"die\*(R", but doesn't exit.
X.Ip "write(FILEHANDLE)" 8 6
X.Ip "write(EXPR)" 8
X.Ip "write" 8
XWrites a formatted record (possibly multi-line) to the specified file,
Xusing the format associated with that file.
XBy default the format for a file is the one having the same name is the
Xfilehandle, but the format for the current output channel (see
X.IR select )
Xmay be set explicitly
Xby assigning the name of the format to the $~ variable.
X.Sp
XTop of form processing is handled automatically:
Xif there is insufficient room on the current page for the formatted
Xrecord, the page is advanced by writing a form feed,
Xa special top-of-page format is used
Xto format the new page header, and then the record is written.
XBy default the top-of-page format is \*(L"top\*(R", but it
Xmay be set to the
Xformat of your choice by assigning the name to the $^ variable.
XThe number of lines remaining on the current page is in variable $-, which
Xcan be set to 0 to force a new page.
X.Sp
XIf FILEHANDLE is unspecified, output goes to the current default output channel,
Xwhich starts out as
X.I STDOUT
Xbut may be changed by the
X.I select
Xoperator.
XIf the FILEHANDLE is an EXPR, then the expression is evaluated and the
Xresulting string is used to look up the name of the FILEHANDLE at run time.
XFor more on formats, see the section on formats later on.
X.Sp
XNote that write is NOT the opposite of read.
X''' Beginning of part 4
X''' $RCSfile: perl.man,v $$Revision: 4.0.1.1 $$Date: 91/04/11 17:50:44 $
X'''
X''' $Log:    perl.man,v $
X''' Revision 4.0.1.1  91/04/11  17:50:44  lwall
X''' patch1: fixed some typos
X'''
X''' Revision 4.0  91/03/20  01:38:08  lwall
X''' 4.0 baseline.
X'''
X''' Revision 3.0.1.14  91/01/11  18:18:53  lwall
X''' patch42: started an addendum and errata section in the man page
X'''
X''' Revision 3.0.1.13  90/11/10  01:51:00  lwall
X''' patch38: random cleanup
X'''
X''' Revision 3.0.1.12  90/10/20  02:15:43  lwall
X''' patch37: patch37: fixed various typos in man page
X'''
X''' Revision 3.0.1.11  90/10/16  10:04:28  lwall
X''' patch29: added @###.## fields to format
X'''
X''' Revision 3.0.1.10  90/08/09  04:47:35  lwall
X''' patch19: added require operator
X''' patch19: added numeric interpretation of $]
X'''
X''' Revision 3.0.1.9  90/08/03  11:15:58  lwall
X''' patch19: Intermediate diffs for Randal
X'''
X''' Revision 3.0.1.8  90/03/27  16:19:31  lwall
X''' patch16: MSDOS support
X'''
X''' Revision 3.0.1.7  90/03/14  12:29:50  lwall
X''' patch15: man page falsely states that you can't subscript array values
X'''
X''' Revision 3.0.1.6  90/03/12  16:54:04  lwall
X''' patch13: improved documentation of *name
X'''
X''' Revision 3.0.1.5  90/02/28  18:01:52  lwall
X''' patch9: $0 is now always the command name
X'''
X''' Revision 3.0.1.4  89/12/21  20:12:39  lwall
X''' patch7: documented that package'filehandle works as well as $package'variable
X''' patch7: documented which identifiers are always in package main
X'''
X''' Revision 3.0.1.3  89/11/17  15:32:25  lwall
X''' patch5: fixed some manual typos and indent problems
X''' patch5: clarified difference between $! and $@
X'''
X''' Revision 3.0.1.2  89/11/11  04:46:40  lwall
X''' patch2: made some line breaks depend on troff vs. nroff
X''' patch2: clarified operation of ^ and $ when $* is false
X'''
X''' Revision 3.0.1.1  89/10/26  23:18:43  lwall
X''' patch1: documented the desirability of unnecessary parentheses
X'''
X''' Revision 3.0  89/10/18  15:21:55  lwall
X''' 3.0 baseline
X'''
X.Sh "Precedence"
X.I Perl
Xoperators have the following associativity and precedence:
X.nf
X
Xnonassoc\h'|1i'print printf exec system sort reverse
X\h'1.5i'chmod chown kill unlink utime die return
Xleft\h'|1i',
Xright\h'|1i'= += \-= *= etc.
Xright\h'|1i'?:
Xnonassoc\h'|1i'.\|.
Xleft\h'|1i'||
Xleft\h'|1i'&&
Xleft\h'|1i'| ^
Xleft\h'|1i'&
Xnonassoc\h'|1i'== != <=> eq ne cmp
Xnonassoc\h'|1i'< > <= >= lt gt le ge
Xnonassoc\h'|1i'chdir exit eval reset sleep rand umask
Xnonassoc\h'|1i'\-r \-w \-x etc.
Xleft\h'|1i'<< >>
Xleft\h'|1i'+ \- .
Xleft\h'|1i'* / % x
Xleft\h'|1i'=~ !~
Xright\h'|1i'! ~ and unary minus
Xright\h'|1i'**
Xnonassoc\h'|1i'++ \-\|\-
Xleft\h'|1i'\*(L'(\*(R'
X
X.fi
XAs mentioned earlier, if any list operator (print, etc.) or
Xany unary operator (chdir, etc.)
Xis followed by a left parenthesis as the next token on the same line,
Xthe operator and arguments within parentheses are taken to
Xbe of highest precedence, just like a normal function call.
XExamples:
X.nf
X
X    chdir $foo || die;\h'|3i'# (chdir $foo) || die
X    chdir($foo) || die;\h'|3i'# (chdir $foo) || die
X    chdir ($foo) || die;\h'|3i'# (chdir $foo) || die
X    chdir +($foo) || die;\h'|3i'# (chdir $foo) || die
X
Xbut, because * is higher precedence than ||:
X
X    chdir $foo * 20;\h'|3i'# chdir ($foo * 20)
X    chdir($foo) * 20;\h'|3i'# (chdir $foo) * 20
X    chdir ($foo) * 20;\h'|3i'# (chdir $foo) * 20
X    chdir +($foo) * 20;\h'|3i'# chdir ($foo * 20)
X
X    rand 10 * 20;\h'|3i'# rand (10 * 20)
X    rand(10) * 20;\h'|3i'# (rand 10) * 20
X    rand (10) * 20;\h'|3i'# (rand 10) * 20
X    rand +(10) * 20;\h'|3i'# rand (10 * 20)
X
X.fi
XIn the absence of parentheses,
Xthe precedence of list operators such as print, sort or chmod is
Xeither very high or very low depending on whether you look at the left
Xside of operator or the right side of it.
XFor example, in
X.nf
X
X    @ary = (1, 3, sort 4, 2);
X    print @ary;        # prints 1324
X
X.fi
Xthe commas on the right of the sort are evaluated before the sort, but
Xthe commas on the left are evaluated after.
XIn other words, list operators tend to gobble up all the arguments that
Xfollow them, and then act like a simple term with regard to the preceding
Xexpression.
XNote that you have to be careful with parens:
X.nf
X
X.ne 3
X    # These evaluate exit before doing the print:
X    print($foo, exit);    # Obviously not what you want.
X    print $foo, exit;    # Nor is this.
X
X.ne 4
X    # These do the print before evaluating exit:
X    (print $foo), exit;    # This is what you want.
X    print($foo), exit;    # Or this.
X    print ($foo), exit;    # Or even this.
X
XAlso note that
X
X    print ($foo & 255) + 1, "\en";
X
X.fi
Xprobably doesn't do what you expect at first glance.
X.Sh "Subroutines"
XA subroutine may be declared as follows:
X.nf
X
X    sub NAME BLOCK
X
X.fi
X.PP
XAny arguments passed to the routine come in as array @_,
Xthat is ($_[0], $_[1], .\|.\|.).
XThe array @_ is a local array, but its values are references to the
Xactual scalar parameters.
XThe return value of the subroutine is the value of the last expression
Xevaluated, and can be either an array value or a scalar value.
XAlternately, a return statement may be used to specify the returned value and
Xexit the subroutine.
XTo create local variables see the
X.I local
Xoperator.
X.PP
XA subroutine is called using the
X.I do
Xoperator or the & operator.
X.nf
X
X.ne 12
XExample:
X
X    sub MAX {
X        local($max) = pop(@_);
X        foreach $foo (@_) {
X            $max = $foo \|if \|$max < $foo;
X        }
X        $max;
X    }
X
X    .\|.\|.
X    $bestday = &MAX($mon,$tue,$wed,$thu,$fri);
X
X.ne 21
XExample:
X
X    # get a line, combining continuation lines
X    #  that start with whitespace
X    sub get_line {
X        $thisline = $lookahead;
X        line: while ($lookahead = <STDIN>) {
X            if ($lookahead \|=~ \|/\|^[ \^\e\|t]\|/\|) {
X                $thisline \|.= \|$lookahead;
X            }
X            else {
X                last line;
X            }
X        }
X        $thisline;
X    }
X
X    $lookahead = <STDIN>;    # get first line
X    while ($_ = do get_line(\|)) {
X        .\|.\|.
X    }
X
X.fi
X.nf
X.ne 6
XUse array assignment to a local list to name your formal arguments:
X
X    sub maybeset {
X        local($key, $value) = @_;
X        $foo{$key} = $value unless $foo{$key};
X    }
X
X.fi
XThis also has the effect of turning call-by-reference into call-by-value,
Xsince the assignment copies the values.
X.Sp
XSubroutines may be called recursively.
XIf a subroutine is called using the & form, the argument list is optional.
XIf omitted, no @_ array is set up for the subroutine; the @_ array at the
Xtime of the call is visible to subroutine instead.
X.nf
X
X    do foo(1,2,3);        # pass three arguments
X    &foo(1,2,3);        # the same
X
X    do foo();        # pass a null list
X    &foo();            # the same
X    &foo;            # pass no arguments\*(--more efficient
X
X.fi
X.Sh "Passing By Reference"
XSometimes you don't want to pass the value of an array to a subroutine but
Xrather the name of it, so that the subroutine can modify the global copy
Xof it rather than working with a local copy.
XIn perl you can refer to all the objects of a particular name by prefixing
Xthe name with a star: *foo.
XWhen evaluated, it produces a scalar value that represents all the objects
Xof that name, including any filehandle, format or subroutine.
XWhen assigned to within a local() operation, it causes the name mentioned
Xto refer to whatever * value was assigned to it.
XExample:
X.nf
X
X    sub doubleary {
X        local(*someary) = @_;
X        foreach $elem (@someary) {
X        $elem *= 2;
X        }
X    }
X    do doubleary(*foo);
X    do doubleary(*bar);
X
X.fi
XAssignment to *name is currently recommended only inside a local().
XYou can actually assign to *name anywhere, but the previous referent of
X*name may be stranded forever.
XThis may or may not bother you.
X.Sp
!STUFFY!FUNK!
echo " "
echo "End of kit 8 (of 36)"
cat /dev/null >kit8isdone
run=''
config=''
for iskit in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36; do
    if test -f kit${iskit}isdone; then
    run="$run $iskit"
    else
    todo="$todo $iskit"
    fi
done
case $todo in
    '')
    echo "You have run all your kits.  Please read README and then type Configure."
    for combo in *:AA; do
        if test -f "$combo"; then
        realfile=`basename $combo :AA`
        cat $realfile:[A-Z][A-Z] >$realfile
        rm -rf $realfile:[A-Z][A-Z]
        fi
    done
    rm -rf kit*isdone
    chmod 755 Configure
    ;;
    *)  echo "You have run$run."
    echo "You still need to run$todo."
    ;;
esac
: Someone might mail this, so...
exit

exit 0 # Just in case...
--
Kent Landfield                   INTERNET: [e-mail]
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    [phone]         FAX:      [phone]
Please send comp.sources.misc-related mail to [e-mail].