The Perl Library

                    CHAPTER 20: THE PERL LIBRARY


   The Perl Library

     - Perl comes with a set of subroutines and packages that provide
       many useful functions

     - These subroutines can be made available to a Perl script using
       the require operator

     - See the Perl man pages for details on the packages available


   The Require Operator

     - Includes and executes any Perl code found in a specified file

     - require (EXPR)
       require EXPR
       require 

     - Returns True if the contents of the file specified by the EXPR
       execute ok and the last expression evaluated in the file is True.  
       Causes a fatal error if the contents of the file do NOT execute 
       ok OR the last expression evaluated in the file is False.  For 
       this reason, a library file ends with the line "1;" to ensure 
       require returns True if the file executed ok.

     - If EXPR is omitted, the contents of $_ is used for the filename.

     - Does not include the file if it has already been included

     - Searches the include path stored in the special @INC array

     - Typical use:

         require "getopts.pl";


   @INC

     - The special @INC array contains the list of directories to search
       for a file to be included by the require operator

     - The @INC array is only used if the argument to the require
       operator is a relative pathname

     - The @INC array initially consists of the arguments to any "-I"
       command line options, followed by the default Perl library
       directory (usually /usr/local/lib/perl), followed by ".".

     - To add new directories to the end of the search list use:

           push (@INC, "dirname");
 
     - To add new directories to the beginning of the search list use:

           unshift (@INC, "dirname");
 

   %INC

     - The special %INC associative array contains the list of files
       that have been included by the require operator

     - The require operator uses this array to determine if a file has
       already been included or not


   The Perl Library Packages

         abbrev.pl      Defines an associative array with all possible
                          mappings of unique abbreviations to full names
         bigint.pl      Arbitrary-sized integer arithmetic
         bigfloat.pl    Arbitrary-sized floating-point arithmetic
         bigrat.pl      Arbitrary-sized rational arithmetic
         cacheout.pl    Substitute for open() that allows more output
                          files than your system allows
         complete.pl    Filename completion similar to the C shell
         ctime.pl       Human-readable date from a UNIX encoded timestamp
         dumpvar.pl     Dump of variable values for a specified package
         find.pl        File system tree traversal (list files on way
                          down)
         finddepth.pl   File system tree traversal (list files on way
                          back up)
         flush.pl       Output flushing for a specified filehandle
         getopt.pl      Process command line options (only handles
                          options that take an argument)
         getopts.pl     Process command line options 
         importenv.pl   Create Perl variables that are similar to the
                          corresponding environment variables
         look.pl        Binary search
         perldb.pl      Perl debugger
         pwd.pl         Track the current working directory
         shellwords.pl  Split a line (or array of lines) into words like
                          the shell would
         stat.pl        Convenience package for stat()
         syslog.pl      Logging functions
         termcap.pl     Termcap ioctl() functions
         timelocal.pl   Human-readable date to a UNIX encoded timestamp
         validate.pl    File tests


   Example Use Of A Library Package

     - Here is an example using the getopts package:

       #! /usr/bin/perl

       require "getopts.pl";       # Include the getopts.pl package

       &Getopts ("mt:");           # Invoke the Getopts() subroutine.
                                   #   This is similar to the shell
                                   #   getopts built-in.  Here we
                                   #   are allowing a -m option with
                                   #   does not take an argument and 
                                   #   a -t option which does take an
                                   #   argument.  If the -m option is
                                   #   present, the Getopts() subroutine
                                   #   sets $opt_m to 1, else $opt_m 
                                   #   remains undef.  If the -t option is 
                                   #   present, $opt_t is set to the
                                   #   argument for the -t option.

       $interval = 30;             # Set a default interval value
       $interval = $opt_t if ($opt_t);  # Set a new interval value if
                                        #   specified with the -t option

       print ("m option is :$opt_m:\n");
       print ("interval is :$interval:\n");


       Suppose the above script is called testopts.

       If invoked as "testopts -m" the output would be:

         m options is :1:
         interval is :30:

       If invoked as "testopts -t 10" the output would be:

         m options is ::
         interval is :10: