Path: utzoo!utgpu!attcan!uunet!husc6!purdue!i.cc.purdue.edu!j.cc.purdue.edu!ain
From: ain@j.cc.purdue.edu (Patrick White)
Newsgroups: comp.binaries.amiga
Subject: perl (docs 2 of 4)
Keywords: perl, script language, nroffed docs, nroff source
Message-ID: <7499@j.cc.purdue.edu>
Date: 3 Aug 88 14:10:26 GMT
Organization: PUCC Land, USA
Lines: 1164
Approved: ain@j.cc.purdue.edu	(Patrick White)

Submitted by:	rminnich@udel.edu (Ron Minnich)
Summary:	A script language.  (a port from it's counterpart on unix)
Poster Boy:	Patrick White	(ain@j.cc.purdue.edu)
Archive Name:	binaries/amiga/volume8/perl.doc.sh2.Z
tested..
 
NOTES:
   I didn't want ot learn a new language just to test this, so I only tried
a "hello world" program.  It worked.  THerefore, this has not been extensively
tested.
   The docs are apparently a copyy of the unix ones -- I don't know if there
is anything missing from Amiga Perl that is in Unix Perl.
   As for the docs, I'm posting an nroffed copy for those that don't have
nroff, and the nroff source in case anybody wants it... you probably only
want to keep one version of the docs.
.
 
 
-- Pat White   (co-moderator comp.sources/binaries.amiga)
ARPA/UUCP: j.cc.purdue.edu!ain  BITNET: PATWHITE@PURCCVM  PHONE: (317) 743-8421
U.S.  Mail:  320 Brown St. apt. 406,    West Lafayette, IN 47906
[archives at: j.cc.purdue.edu.ARPA]
 
========================================
 
#	This is a shell archive.
#	Remove everything above and including the cut line.
#	Then run the rest of the file through sh.
#----cut here-----cut here-----cut here-----cut here----#
#!/bin/sh
# shar:	Shell Archiver
#	Run the following text with /bin/sh to create:
#	perl.cat.ab
# This archive created: Mon Aug  1 12:53:58 1988
# By:	Patrick White (PUCC Land, USA)
cat << \SHAR_EOF > perl.cat.ab
             tening the array by 1.

     print FILEHANDLE LIST

     print LIST

     print   Prints a string or comma-separated list of strings.
             If FILEHANDLE is omitted, prints by default to stan-
             dard output (or to the last selected output
             channel--see select()).  If LIST is also omitted,



Printed 7/26/88               LOCAL                            20






PERL(1)             UNIX Programmer's Manual              PERL(1)



             prints $_ to stdout.  LIST may also be an array
             value.  To set the default output channel to some-
             thing other than stdout use the select operation.

     printf FILEHANDLE LIST

     printf LIST
             Equivalent to a "print FILEHANDLE sprintf(LIST)".

     push(ARRAY,EXPR)
             Treats ARRAY (@ is optional) as a stack, and pushes
             the value of EXPR onto the end of ARRAY.  The length
             of ARRAY increases by 1.  Has the same effect as

                 $ARRAY[$#ARRAY+1] = EXPR;

             but is more efficient.

     redo LABEL

     redo    The redo command restarts the loop block without
             evaluating the conditional again.  The continue
             block, if any, is not executed.  If the LABEL is
             omitted, the command refers to the innermost enclos-
             ing loop.  This command is normally used by programs
             that want to lie to themselves about what was just
             input:

                  # a simpleminded Pascal comment stripper
                  # (warning: assumes no { or } in strings)
                  line: while (<stdin>) {
                       while (s|({.*}.*){.*}|$1 |) {}
                       s|{.*}| |;
                       if (s|{.*| |) {
                            $front = $_;
                            while (<stdin>) {
                                 if (/}/) {     # end of comment?
                                      s|^|$front{|;
                                      redo line;
                                 }
                            }
                       }
                       print;
                  }


     rename(OLDNAME,NEWNAME)
             Changes the name of a file.  Returns 1 for success,
             0 otherwise.

     reset EXPR
             Generally used in a continue block at the end of a



Printed 7/26/88               LOCAL                            21






PERL(1)             UNIX Programmer's Manual              PERL(1)



             loop to clear variables and reset ?? searches so
             that they work again.  The expression is interpreted
             as a list of single characters (hyphens allowed for
             ranges).  All string variables beginning with one of
             those letters are set to the null string.  If the
             expression is omitted, one-match searches (?pat-
             tern?) are reset to match again.  Always returns 1.
             Examples:

                 reset 'X';      # reset all X variables
                 reset 'a-z';    # reset lower case variables
                 reset;          # just reset ?? searches


     s/PATTERN/REPLACEMENT/gi
             Searches a string for a pattern, and if found,
             replaces that pattern with the replacement text and
             returns the number of substitutions made.  Otherwise
             it returns false (0).  The "g" is optional, and if
             present, indicates that all occurences of the pat-
             tern are to be replaced.  The "i" is also optional,
             and if present, indicates that matching is to be
             done in a case-insensitive manner.  Any delimiter
             may replace the slashes; if single quotes are used,
             no interpretation is done on the replacement string.
             If no string is specified via the =~ or !~ operator,
             the $_ string is searched and modified.  (The string
             specified with =~ must be a string variable or array
             element, i.e. an lvalue.) If the pattern contains a
             $ that looks like a variable rather than an end-of-
             string test, the variable will be interpolated into
             the pattern at run-time.  See also the section on
             regular expressions.  Examples:

                 s/\bgreen\b/mauve/g;      # don't change wintergreen

                 $path =~ s|/usr/bin|/usr/local/bin|;

                 s/Login: $foo/Login: $bar/; # run-time pattern

                 s/([^ ]*) *([^ ]*)/$2 $1/;     # reverse 1st two fields

             (Note the use of $ instead of \ in the last example.
             See section on regular expressions.)

     seek(FILEHANDLE,POSITION,WHENCE)
             Randomly positions the file pointer for FILEHANDLE,
             just like the fseek() call of stdio.  Returns 1 upon
             success, 0 otherwise.

     select(FILEHANDLE)
             Sets the current default filehandle for output.



Printed 7/26/88               LOCAL                            22






PERL(1)             UNIX Programmer's Manual              PERL(1)



             This has two effects: first, a write or a print
             without a filehandle will default to this FILEHAN-
             DLE.  Second, references to variables related to
             output will refer to this output channel.  For exam-
             ple, if you have to set the top of form format for
             more than one output channel, you might do the fol-
             lowing:

                 select(report1);
                 $^ = 'report1_top';
                 select(report2);
                 $^ = 'report2_top';

             Select happens to return TRUE if the file is
             currently open and FALSE otherwise, but this has no
             effect on its operation.

     shift(ARRAY)

     shift ARRAY

     shift   Shifts the first value of the array off and returns
             it, shortening the array by 1 and moving everything
             down.  If ARRAY is omitted, shifts the ARGV array.
             See also unshift(), push() and pop().  Shift() and
             unshift() do the same thing to the left end of an
             array that push() and pop() do to the right end.

     sleep EXPR

     sleep   Causes the script to sleep for EXPR seconds, or for-
             ever if no EXPR.  May be interrupted by sending the
             process a SIGALARM.  Returns the number of seconds
             actually slept.

     split(/PATTERN/,EXPR)

     split(/PATTERN/)

     split   Splits a string into an array of strings, and
             returns it.  If EXPR is omitted, splits the $_
             string.  If PATTERN is also omitted, splits on whi-
             tespace (/[ \t\n]+/).  Anything matching PATTERN is
             taken to be a delimiter separating the fields.
             (Note that the delimiter may be longer than one
             character.) Trailing null fields are stripped, which
             potential users of pop() would do well to remember.
             A pattern matching the null string (not to be con-
             fused with a null pattern) will split the value of
             EXPR into separate characters at each point it
             matches that way.  For example:




Printed 7/26/88               LOCAL                            23






PERL(1)             UNIX Programmer's Manual              PERL(1)



                  print join(':',split(/ */,'hi there'));

             produces the output 'h:i:t:h:e:r:e'.

             The pattern /PATTERN/ may be replaced with an
             expression to specify patterns that vary at runtime.
             As a special case, specifying a space (' ') will
             split on white space just as split with no arguments
             does, but leading white space does NOT produce a
             null first field.  Thus, split(' ') can be used to
             emulate awk's default behavior, whereas split(/ /)
             will give you as many null initial fields as there
             are leading spaces.

             Example:

                  open(passwd, '/etc/passwd');
                  while (<passwd>) {
                       ($login, $passwd, $uid, $gid, $gcos, $home, $shell)
                            = split(/:/);
                       ...
                  }

             (Note that $shell above will still have a newline on
             it.  See chop().) See also join.

     sprintf(FORMAT,LIST)
             Returns a string formatted by the usual printf con-
             ventions.  The * character is not supported.

     sqrt(EXPR)
             Return the square root of EXPR.

     stat(FILEHANDLE)

     stat(EXPR)
             Returns a 13-element array giving the statistics for
             a file, either the file opened via FILEHANDLE, or
             named by EXPR.  Typically used as follows:

                 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
                    $atime,$mtime,$ctime,$blksize,$blocks)
                        = stat($filename);


     substr(EXPR,OFFSET,LEN)
             Extracts a substring out of EXPR and returns it.
             First character is at offset 0, or whatever you've
             set $[ to.

     system LIST
             Does exactly the same thing as "exec LIST" except



Printed 7/26/88               LOCAL                            24






PERL(1)             UNIX Programmer's Manual              PERL(1)



             that a fork is done first, and the parent process
             waits for the child process to complete.  Note that
             argument processing varies depending on the number
             of arguments.  The return value is the exit status
             of the program as returned by the wait() call.  To
             get the actual exit value divide by 256.  See also
             exec.

     symlink(OLDFILE,NEWFILE)
             Creates a new filename symbolically linked to the
             old filename.  Returns 1 for success, 0 otherwise.
             On systems that don't support symbolic links, pro-
             duces a fatal error.

     tell(FILEHANDLE)

     tell    Returns the current file position for FILEHANDLE.
             If FILEHANDLE is omitted, assumes the file last
             read.

     time    Returns the number of seconds since January 1, 1970.
             Suitable for feeding to gmtime() and localtime().

     times   Returns a four-element array giving the user and
             system times, in seconds, for this process and the
             children of this process.

                 ($user,$system,$cuser,$csystem) = times;


     tr/SEARCHLIST/REPLACEMENTLIST/

     y/SEARCHLIST/REPLACEMENTLIST/
             Translates all occurences of the characters found in
             the search list with the corresponding character in
             the replacement list.  It returns the number of
             characters replaced.  If no string is specified via
             the =~ or !~ operator, the $_ string is translated.
             (The string specified with =~ must be a string vari-
             able or array element, i.e. an lvalue.) For sed
             devotees, y is provided as a synonym for tr.  Exam-
             ples:

                 $ARGV[1] =~ y/A-Z/a-z/;   # canonicalize to lower case

                 $cnt = tr/*/*/;           # count the stars in $_


     umask(EXPR)
             Sets the umask for the process and returns the old
             one.




Printed 7/26/88               LOCAL                            25






PERL(1)             UNIX Programmer's Manual              PERL(1)



     unlink LIST
             Deletes a list of files.  LIST may be an array.
             Returns the number of files successfully deleted.
             Note: in order to use the value you must put the
             whole thing in parentheses:

                  $cnt = (unlink 'a','b','c');


     unshift(ARRAY,LIST)
             Does the opposite of a shift.  Prepends list to the
             front of the array, and returns the number of ele-
             ments in the new array.

                  unshift(ARGV,'-e') unless $ARGV[0] =~ /^-/;


     values(ASSOC_ARRAY)
             Returns a normal array consisting of all the values
             of the named associative array.  The values are
             returned in an apparently random order, but it is
             the same order as either the keys() or each() func-
             tion produces (given that the associative array has
             not been modified).  See also keys() and each().

     write(FILEHANDLE)

     write(EXPR)

     write() Writes a formatted record (possibly multi-line) to
             the specified file, using the format associated with
             that file.  By default the format for a file is the
             one having the same name is the filehandle, but the
             format for the current output channel (see select)
             may be set explicitly by assigning the name of the
             format to the $~ variable.

             Top of form processing is handled automatically: if
             there is insufficient room on the current page for
             the formatted record, the page is advanced, a spe-
             cial top-of-page format is used to format the new
             page header, and then the record is written.  By
             default the top-of-page format is "top", but it may
             be set to the format of your choice by assigning the
             name to the $^ variable.

             If FILEHANDLE is unspecified, output goes to the
             current default output channel, which starts out as
             stdout but may be changed by the select operator.
             If the FILEHANDLE is an EXPR, then the expression is
             evaluated and the resulting string is used to look
             up the name of the FILEHANDLE at run time.  For more



Printed 7/26/88               LOCAL                            26






PERL(1)             UNIX Programmer's Manual              PERL(1)



             on formats, see the section on formats later on.

     Subroutines

     A subroutine may be declared as follows:

         sub NAME BLOCK


     Any arguments passed to the routine come in as array @_,
     that is ($_[0], $_[1], ...).  The return value of the sub-
     routine is the value of the last expression evaluated.
     There are no local variables--everything is a global vari-
     able.

     A subroutine is called using the do operator.  (CAVEAT: For
     efficiency reasons recursive subroutine calls are not
     currently supported.  This restriction may go away in the
     future.  Then again, it may not.)

     Example:

          sub MAX {
               $max = pop(@_);
               while ($foo = pop(@_)) {
                    $max = $foo if $max < $foo;
               }
               $max;
          }

          ...
          $bestday = do MAX($mon,$tue,$wed,$thu,$fri);























Printed 7/26/88               LOCAL                            27






PERL(1)             UNIX Programmer's Manual              PERL(1)



     Example:

          # get a line, combining continuation lines
          #  that start with whitespace
          sub get_line {
               $thisline = $lookahead;
               line: while ($lookahead = <stdin>) {
                    if ($lookahead =~ /^[ \t]/) {
                         $thisline .= $lookahead;
                    }
                    else {
                         last line;
                    }
               }
               $thisline;
          }

          $lookahead = <stdin>;    # get first line
          while ($_ = get_line()) {
               ...
          }

     Use array assignment to name your formal arguments:

          sub maybeset {
               ($key,$value) = @_;
               $foo{$key} = $value unless $foo{$key};
          }


     Regular Expressions

     The patterns used in pattern matching are regular expres-
     sions such as those used by egrep(1).  In addition, \w
     matches an alphanumeric character and \W a nonalphanumeric.
     Word boundaries may be matched by \b, and non-boundaries by
     \B.  The bracketing construct ( ... ) may also be used,
     $<digit> matches the digit'th substring, where digit can
     range from 1 to 9.  (You can also use the old standby
     \<digit> in search patterns, but $<digit> also works in
     replacement patterns and in the block controlled by the
     current conditional.) $+ returns whatever the last bracket
     match matched.  $& returns the entire matched string.  Up to
     10 alternatives may given in a pattern, separated by |, with
     the caveat that ( ... | ... ) is illegal.  Examples:

          s/^([^ ]*) *([^ ]*)/$2 $1/;   # swap first two words








Printed 7/26/88               LOCAL                            28






PERL(1)             UNIX Programmer's Manual              PERL(1)



          if (/Time: (..):(..):(..)/) {
               $hours = $1;
               $minutes = $2;
               $seconds = $3;
          }

     By default, the ^ character matches only the beginning of
     the string, and perl does certain optimizations with the
     assumption that the string contains only one line.  You may,
     however, wish to treat a string as a multi-line buffer, such
     that the ^ will match after any newline within the string.
     At the cost of a little more overhead, you can do this by
     setting the variable $* to 1.  Setting it back to 0 makes
     perl revert to its old behavior.

     Formats

     Output record formats for use with the write operator may
     declared as follows:

         format NAME =
         FORMLIST
         .

     If name is omitted, format "stdout" is defined.  FORMLIST
     consists of a sequence of lines, each of which may be of one
     of three types:

     1.  A comment.

     2.  A "picture" line giving the format for one output line.

     3.  An argument line supplying values to plug into a picture
         line.

     Picture lines are printed exactly as they look, except for
     certain fields that substitute values into the line.  Each
     picture field starts with either @ or ^.  The @ field (not
     to be confused with the array marker @) is the normal case;
     ^ fields are used to do rudimentary multi-line text block
     filling.  The length of the field is supplied by padding out
     the field with multiple <, >, or | characters to specify,
     respectively, left justfication, right justification, or
     centering.  If any of the values supplied for these fields
     contains a newline, only the text up to the newline is
     printed.  The special field @* can be used for printing
     multi-line values.  It should appear by itself on a line.

     The values are specified on the following line, in the same
     order as the picture fields.  They must currently be either
     string variable names or string literals (or pseudo-
     literals).  Currently you can separate values with spaces,



Printed 7/26/88               LOCAL                            29






PERL(1)             UNIX Programmer's Manual              PERL(1)



     but commas may be placed between values to prepare for pos-
     sible future versions in which full expressions are allowed
     as values.

     Picture fields that begin with ^ rather than @ are treated
     specially.  The value supplied must be a string variable
     name which contains a text string.  Perl puts as much text
     as it can into the field, and then chops off the front of
     the string so that the next time the string variable is
     referenced, more of the text can be printed.  Normally you
     would use a sequence of fields in a vertical stack to print
     out a block of text.  If you like, you can end the final
     field with ..., which will appear in the output if the text
     was too long to appear in its entirety.

     Since use of ^ fields can produce variable length records if
     the text to be formatted is short, you can suppress blank
     lines by putting the tilde (~) character anywhere in the
     line.  (Normally you should put it in the front if possi-
     ble.) The tilde will be translated to a space upon output.

     Examples:

     # a report on the /etc/passwd file
     format top =
                             Passwd File
     Name                Login    Office   Uid   Gid Home
     ------------------------------------------------------------------
     .
     format stdout =
     @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
     $name               $login   $office $uid $gid  $home
     .






















Printed 7/26/88               LOCAL                            30






PERL(1)             UNIX Programmer's Manual              PERL(1)



     # a report from a bug report form
     format top =
                             Bug Reports
     @<<<<<<<<<<<<<<<<<<<<<<<     @|||         @>>>>>>>>>>>>>>>>>>>>>>>
     $system;                      $%;         $date
     ------------------------------------------------------------------
     .
     format stdout =
     Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
              $subject
     Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
            $index                        $description
     Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
               $priority         $date    $description
     From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
           $from                          $description
     Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                  $programmer             $description
     ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                          $description
     ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                          $description
     ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                          $description
     ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                          $description
     ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...
                                          $description
     .

     It is possible to intermix prints with writes on the same output channel,
     but you'll have to handle $- (lines left on the page) yourself.

     If you are printing lots of fields that are usually blank,
     you should consider using the reset operator between
     records.  Not only is it more efficient, but it can prevent
     the bug of adding another field and forgetting to zero it.

     Predefined Names

     The following names have special meaning to perl.  I could
     have used alphabetic symbols for some of these, but I didn't
     want to take the chance that someone would say reset "a-zA-
     Z" and wipe them all out.  You'll just have to suffer along
     with these silly symbols.  Most of them have reasonable
     mnemonics, or analogues in one of the shells.

     $_      The default input and pattern-searching space.  The
             following pairs are equivalent:

                  while (<>) {...     # only equivalent in while!
                  while ($_ = <>) {...



Printed 7/26/88               LOCAL                            31






PERL(1)             UNIX Programmer's Manual              PERL(1)



                  /^Subject:/
                  $_ =~ /^Subject:/

                  y/a-z/A-Z/
                  $_ =~ y/a-z/A-Z/

                  chop
                  chop($_)

             (Mnemonic: underline is understood in certain opera-
             tions.)

     $.      The current input line number of the last file that
             was read.  Readonly.  (Mnemonic: many programs use .
             to mean the current line number.)

     $/      The input record separator, newline by default.
             Works like awk's RS variable, including treating
             blank lines as delimiters if set to the null string.
             If set to a value longer than one character, only
             the first character is used.  (Mnemonic: / is used
             to delimit line boundaries when quoting poetry.)

     $,      The output field separator for the print operator.
             Ordinarily the print operator simply prints out the
             comma separated fields you specify.  In order to get
             behavior more like awk, set this variable as you
             would set awk's OFS variable to specify what is
             printed between fields.  (Mnemonic: what is printed
             when there is a , in your print statement.)

     $\      The output record separator for the print operator.
             Ordinarily the print operator simply prints out the
             comma separated fields you specify, with no trailing
             newline or record separator assumed.  In order to
             get behavior more like awk, set this variable as you
             would set awk's ORS variable to specify what is
             printed at the end of the print.  (Mnemonic: you set
             $\ instead of adding \n at the end of the print.
             Also, it's just like /, but it's what you get "back"
             from perl.)

     $#      The output format for printed numbers.  This vari-
             able is a half-hearted attempt to emulate awk's OFMT
             variable.  There are times, however, when awk and
             perl have differing notions of what is in fact
             numeric.  Also, the initial value is %.20g rather
             than %.6g, so you need to set $# explicitly to get
             awk's value.  (Mnemonic: # is the number sign.)

     $%      The current page number of the currently selected
             output channel.  (Mnemonic: % is page number in



Printed 7/26/88               LOCAL                            32






PERL(1)             UNIX Programmer's Manual              PERL(1)



             nroff.)

     $=      The current page length (printable lines) of the
             currently selected output channel.  Default is 60.
             (Mnemonic: = has horizontal lines.)

     $-      The number of lines left on the page of the
             currently selected output channel.  (Mnemonic:
             lines_on_page - lines_printed.)

     $~      The name of the current report format for the
             currently selected output channel.  (Mnemonic:
             brother to $^.)

     $^      The name of the current top-of-page format for the
             currently selected output channel.  (Mnemonic:
             points to top of page.)

     $|      If set to nonzero, forces a flush after every write
             or print on the currently selected output channel.
             Default is 0.  Note that stdout will typically be
             line buffered if output is to the terminal and block
             buffered otherwise.  Setting this variable is useful
             primarily when you are outputting to a pipe, such as
             when you are running a perl script under rsh and
             want to see the output as it's happening.
             (Mnemonic: when you want your pipes to be piping
             hot.)

     $$      The process number of the perl running this script.
             (Mnemonic: same as shells.)

     $?      The status returned by the last backtick (``) com-
             mand.  (Mnemonic: same as sh and ksh.)

     $+      The last bracket matched by the last search pattern.
             This is useful if you don't know which of a set of
             alternative patterns matched.  For example:

                 /Version: (.*)|Revision: (.*)/ && ($rev = $+);

             (Mnemonic: be positive and forward looking.)

     $*      Set to 1 to do multiline matching within a string, 0
             to assume strings contain a single line.  Default is
             0.  (Mnemonic: * matches multiple things.)

     $0      Contains the name of the file containing the perl
             script being executed.  The value should be copied
             elsewhere before any pattern matching happens, which
             clobbers $0.  (Mnemonic: same as sh and ksh.)




Printed 7/26/88               LOCAL                            33






PERL(1)             UNIX Programmer's Manual              PERL(1)



     $<digit>
             Contains the subpattern from the corresponding set
             of parentheses in the last pattern matched, not
             counting patterns matched in nested blocks that have
             been exited already.  (Mnemonic: like \digit.)

     $[      The index of the first element in an array, and of
             the first character in a substring.  Default is 0,
             but you could set it to 1 to make perl behave more
             like awk (or Fortran) when subscripting and when
             evaluating the index() and substr() functions.
             (Mnemonic: [ begins subscripts.)

     $!      The current value of errno, with all the usual
             caveats.  (Mnemonic: What just went bang?)

     $@      The error message from the last eval command.  If
             null, the last eval parsed and executed correctly.
             (Mnemonic: Where was the syntax error "at"?)

     @ARGV   The array ARGV contains the command line arguments
             intended for the script.  Note that $#ARGV is the
             generally number of arguments minus one, since
             $ARGV[0] is the first argument, NOT the command
             name.  See $0 for the command name.

     $ENV{expr}
             The associative array ENV contains your current
             environment.  Setting a value in ENV changes the
             environment for child processes.

     $SIG{expr}
             The associative array SIG is used to set signal
             handlers for various signals.  Example:

                  sub handler {  # 1st argument is signal name
                       ($sig) = @_;
                       print "Caught a SIG$sig--shutting down0;
                       close(log);
                       exit(0);
                  }

                  $SIG{'INT'} = 'handler';
                  $SIG{'QUIT'} = 'handler';
                  ...
                  $SIG{'INT'} = 'DEFAULT'; # restore default action
                  $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT


ENVIRONMENT
     Perl currently uses no environment variables, except to make
     them available to the script being executed, and to child



Printed 7/26/88               LOCAL                            34






PERL(1)             UNIX Programmer's Manual              PERL(1)



     processes.  However, scripts running setuid would do well to
     execute the following lines before doing anything else, just
     to keep people honest:

         $ENV{'PATH'} = '/bin:/usr/bin';    # or whatever you need
         $ENV{'SHELL'} = '/bin/sh' if $ENV{'SHELL'};
         $ENV{'IFS'} = '' if $ENV{'IFS'};


AUTHOR
     Larry Wall <lwall@jpl-devvax.Jpl.Nasa.Gov>

FILES
     /tmp/perl-eXXXXXX   temporary file for -e commands.

SEE ALSO
     a2p  awk to perl translator
     s2p  sed to perl translator
     perldb    interactive perl debugger

DIAGNOSTICS
     Compilation errors will tell you the line number of the
     error, with an indication of the next token or token type
     that was to be examined.  (In the case of a script passed to
     perl via -e switches, each -e is counted as one line.)

TRAPS
     Accustomed awk users should take special note of the follow-
     ing:

     *   Semicolons are required after all simple statements in
         perl.  Newline is not a statement delimiter.

     *   Curly brackets are required on ifs and whiles.

     *   Variables begin with $ or @ in perl.

     *   Arrays index from 0 unless you set $[.  Likewise string
         positions in substr() and index().

     *   You have to decide whether your array has numeric or
         string indices.

     *   You have to decide whether you want to use string or
         numeric comparisons.

     *   Reading an input line does not split it for you.  You
         get to split it yourself to an array.  And split has
         different arguments.

     *   The current input line is normally in $_, not $0.  It
         generally does not have the newline stripped.  ($0 is



Printed 7/26/88               LOCAL                            35






PERL(1)             UNIX Programmer's Manual              PERL(1)



         initially the name of the program executed, then the
         last matched string.)

     *   The current filename is $ARGV, not $FILENAME.  NR, RS,
         ORS, OFS, and OFMT have equivalents with other symbols.
         FS doesn't have an equivalent, since you have to be
         explicit about split statements.

     *   $<digit> does not refer to fields--it refers to sub-
         strings matched by the last match pattern.

     *   The print statement does not add field and record
         separators unless you set $, and $\.

     *   You must open your files before you print to them.

     *   The range operator is "..", not comma.  (The comma
         operator works as in C.)

     *   The match operator is "=~", not "~".  ("~" is the one's
         complement operator.)

     *   The concatenation operator is ".", not the null string.
         (Using the null string would render "/pat/ /pat/"
         unparseable, since the third slash would be interpreted
         as a division operator--the tokener is in fact slightly
         context sensitive for operators like /, ?, and <.  And
         in fact, . itself can be the beginning of a number.)

     *   The \nnn construct in patterns must be given as [\nnn]
         to avoid interpretation as a backreference.

     *   Next, exit, and continue work differently.

     *   When in doubt, run the awk construct through a2p and see
         what it gives you.

     Cerebral C programmers should take note of the following:

     *   Curly brackets are required on ifs and whiles.

     *   You should use "elsif" rather than "else if"

     *   Break and continue become last and next, respectively.

     *   There's no switch statement.

     *   Variables begin with $ or @ in perl.

     *   Printf does not implement *.





Printed 7/26/88               LOCAL                            36






PERL(1)             UNIX Programmer's Manual              PERL(1)



     *   Comments begin with #, not /*.

     *   You can't take the address of anything.

     *   Subroutines are not reentrant.

     *   ARGV must be capitalized.

     *   The "system" calls link, unlink, rename, etc. return 1
         for success, not 0.

     *   Signal handlers deal with signal names, not numbers.

     Seasoned sed programmers should take note of the following:

     *   Backreferences in substitutions use $ rather than \.

     *   The pattern matching metacharacters (, ), and | do not
         have backslashes in front.

BUGS
     You can't currently dereference array elements inside a
     double-quoted string.  You must assign them to a temporary
     and interpolate that.

     Associative arrays really ought to be first class objects.

     Recursive subroutines are not currently supported, due to
     the way temporary values are stored in the syntax tree.

     Arrays ought to be passable to subroutines just as strings
     are.

     The array literal consisting of one element is currently
     misinterpreted, i.e.

          @array = (123);

     doesn't work right.

     Perl actually stands for Pathologically Eclectic Rubbish
     Lister, but don't tell anyone I said that.


Printed 7/26/88               LOCAL                            37
SHAR_EOF
#	End of shell archive
exit 0