
Updated 5/22/2002, 1:27:11 AM

The code:  File::Util (a file handling utilities code library)
@File::Util::ISA qw( Handy::DANDY ) and implements expt_handler.pm as well

Get each module in the packaged archive format of your preference at
<http://ooopps.sourceforge.net/cgi-bin/archive.pl/pub/bundles/>


==================================================
INVOKE THE FILE UTILITIES LIBRARY
--------------------------------------------------
   use File::Util;
   my($fu) = File::Util->new();


==================================================
HOW TO READ FILES
--------------------------------------------------

   ===============================================
   GET FILE CONTENTS AS A STRING
   -----------------------------------------------
      my($filecontents) = $fu->load_file('../path/to/your.file');


   ===============================================
   GET FILE CONTENTS LINE BY LINE
   -----------------------------------------------
      my(@filelines) = $fu->load_file('../path/to/your.file','--as-list');


   ===============================================
   CHANGE DEFAULT MAXIMUM LIMIT (in bytes) FOR FILE READS
   -----------------------------------------------
      $File::Util::readlimit = 15000000; # reads files only 15 megs or smaller.
                                         # the default is 10 megs


   ===============================================
   LOAD THE CONTENTS OF EACH FILE IN A DIRECTORY INTO A HASHREF
   -----------------------------------------------
      ...where the keys are the names of each file and the values of
      the keys are the contents of each file as strings. The readlimit
      argument (see above) will apply to every file individually when
      loaded.  Adjust the readlimit as necessary.
         my($files) = $fu->load_dir('directory/to/load/up/');

      ...that creates a hashref that looks like this, supposing that
         the files in the loaded directory were named 'a.txt', 'b.html',
         'c.dat', and 'd.conf'...
         $files =
            {
               'a.txt'  => "everything found in the file a.txt",
               'b.html' => "everything found in the file b.html",
               'c.dat'  => "everything found in the file c.dat",
               'd.conf' => "everything found in the file d.conf",
            };


   ===============================================
   LOAD THE CONTENTS OF EACH FILE IN A DIRECTORY INTO AN ARRAY
   -----------------------------------------------
         my(@files) = $fu->load_dir('directory/to/load/','--as-list');

   ...where the contents of each file are members of the list,
      located at the indicie pertaining to the order of the files
      sorted alphabetically by name, as returned by sort()


   ===============================================
   LOAD THE CONTENTS OF EACH FILE IN A DIRECTORY INTO A LISTREF
   -----------------------------------------------
         my($files) = $fu->load_dir('directory/to/load/','--as-listref');

      ...where the contents of each file are members of the list,
      located at the indicie pertaining to the order of the files
      sorted alphabetically by name, as returned by sort()


   ===============================================
   GET NUMBER OF LINES IN A FILE
   -----------------------------------------------
      my($lines) = $fu->lines_in_file('./directory/or/filename');


==================================================
HOW TO WRITE TO FILES:
--------------------------------------------------

   ===============================================
   CREATE AND WRITE TO A NEW FILE:
   -----------------------------------------------
      $fu->write_file
         (
            'filename'  => '../path/to/new.file',
            'content'   => $new_content,
            'mode'      => 'write',
         );


   ===============================================
   OVERWRITE AN EXISTING FILE (the same as above)
   -----------------------------------------------
      $fu->write_file
         (
            'filename'  => 'path/to/existing.file',
            'content'   => $new_content,
            'mode'      => 'write',
         );


   ===============================================
   APPEND TO A FILE:
   -----------------------------------------------
      $fu->write_file
         (
            'filename'  => '/path/to/existing.file',
            'content'   => $new_content,
            'mode'      => 'append',
         );


   ===============================================
   CLEAR THE CONTENTS OF A FILE
   -----------------------------------------------
      $fu->ftruncate('./delete/everything/inthis.file');


   ===============================================
   ALLOW EMPTY WRITES
   -----------------------------------------------
      (File::Util won't let you open a file for writing unless you provide
       the content.  You can allow empty writes by doing this)

      $File::Util::empty_writes = 0;


==================================================
GET AN OPEN FILEHANDLE:
--------------------------------------------------

   NOTE: 'mode' arguments passed to write_file() and open_to_FH()
         can be either 'write' or 'append'.  without a mode argument
         a mode of 'write' is assumed


   ===============================================
   OPEN FILEHANDLE FOR WRITING ON A FILE
   -----------------------------------------------
   $fu->open_to_FH
      (
         'filename'  => './make_new/or/use_existant.file',
         'mode'      => 'write,'
      );


   ===============================================
   OPEN FILEHANDLE FOR APPENDING TO A FILE
   -----------------------------------------------
   $fu->open_to_FH
      (
         'filename'  => './make_new/or/use_existant.file',
         'mode'      => 'append'
      );


==================================================
COPY A FILE:
--------------------------------------------------
   $fu->write_file
      (
         'filename'  => 'path/to/copyof.file',
         'content'   => $fu->load_file('/file/to.copy'),
         'mode'      => 'write',
      );


%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%
%    NOTE ON FILE LOCKING WITH flock()
% - - - - - - - - - - - - - - - - - - - -
%    flock() is automatically implemented in all read/write operations
%    performed by File::Util based on whether or not your system supports it.
%    You can bypass the locking on read/write operations by passing the
%    option '--no-flock' when you call load_file(), write_file(),
%    open_to_FH(), and load_dir().  flock is not used when calling
%    lines_in_file()
%
%    the use of flock() can be globally disabled in all File::Util I/O by
%    passing the option '--no-flock' in when you invoke File::Util
%       my($fu) = File::Util->new('--no-flock');
%
%    if your system does not support flock() it will not cause fatal
%    errors or warnings to occur when you use File::Util  The use of
%    flock() is silently bypassed in such circumstances.  You can
%    test for yourself to see if flock() is supported by your system
%    by calling the 'can_flock' method.
%       my($system_supports_flock) = $fu->can_flock();
%
%    OPTIONS ON I/O RACE CONDITION POLICY
%      set @File::Util::onflockfail to any of the following strings:
%
%        --fatal      fails with stack trace
%        --fail       same as above
%        --warn       warns() about the error with a stack trace
%        --ignore     ignores the failure to get an exclusive lock
%        --undef      returns undef
%        --0          returns 0
%        --wait*      waits to try getting an exclusive lock
%        --block*     same as above
%
%      ex.- @File::Util::onflockfail = qw( wait fail );
%
%   * used in tandem with another option.  You must specify another option to
%     fall back on if blocking should fail.  Otherwise File::Util will throw
%     a fatal error and dump a stack trace before exiting the process with
%     a zero (0) status.
%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%=%


==================================================
HOW TO TELL IF FILE LOCKING IS SUPPORTED
--------------------------------------------------
   my($can_use_flock) = $fu->can_flock();


==================================================
HOW TO USE THE RIGHT DIRECTORY PATH SEPERATOR
--------------------------------------------------
   this is different on windows, mac, EBCDIC, linux/unix, vms, etc

   my($correct_SL) = $fu->SL();


==================================================
HOW TO USE THE RIGHT NEWLINE CHARACTER
--------------------------------------------------
   this varies from system to system as well

   my($newline) = $fu->n();


==================================================
HOW TO LIST DIRECTORIES
--------------------------------------------------
   my(@files_in_dir) = $fu->list_dir('/directory/name');

   NOTE:
      All File::Util functions/methods which pertain to
      the listing of directories may be combined as
      desired.  Options are:
         --files-only
         --dirs-only
         --with-paths
         --sl-after-dirs
         --follow or --recurse
         --no-fsdots
         --as-ref
         --dirs-as-ref
         --files-as-ref
         --no-fancy *
         --raw *

      * pertains only to print_dir()


   ===============================================
   LIST DIRECTORY WITH THE PATHNAMES OF ITS FILES
   -----------------------------------------------
      my(@files_w_paths) = $fu->list_dir('/directory/name');


   ===============================================
   LIST A DIRECTORY WITH IT'S FILES ONLY
   -----------------------------------------------
      my(@files) = $fu->list_dir('/directory/name', '--files-only');


   ===============================================
   LIST A DIRECTORY WITH IT'S SUBDIRECTORIES ONLY
   -----------------------------------------------
      my(@dirs) = $fu->list_dir('/directory/name', '--dirs-only');


   ===============================================
   LIST A DIRECTORY WITH NO '..' or '.' ENTRIES
   -----------------------------------------------
      my(@files) = $fu->list_dir('/directory/name', '--no-fsdots');


   ===============================================
   PRETTY-PRINT A DIRECTORY
   -----------------------------------------------
      print($fu->print_dir('/directory/name'));

      This renders a directory listing that looks something like this:
         +-----------------------------+
         |  Directory listing for /home
         +-----------------------------+
         | .
         | ..
         | .cpan/
         | .ssh/
         | mail/
         | apache-conf/
         | oneliners/
         | .bash_history
         | .perltidyrc
         +-----------------------------+


   ===============================================
   MAKE A DIRECTORY (ONE OR MANY RECURSIVELY)
   -----------------------------------------------
      $fu->
         makedir('./new/directory/and/maybe/some/others/inside/it',[bitmask]);

         NOTE: bitmask is the permission's mode. eg- 0755, 0664, etc.
               this is merged with the effective UID of the current process


==================================================
GET FILE ATTRIBUTES
--------------------------------------------------

   ===============================================
   GET A FILE'S LAST MODIFIED DATE/TIME
   -----------------------------------------------

      my($lastmod) = $fu->last_mod('./directory/or/filename',[format]);

      NOTE: If you want the time in human-readable format, the optional
            [format] argument is one of these strings, where each
            is listed with the format of the timestamp it renders

            --short                 5/15/02, 4:22 pm
            --formal                Saturday, June 15, 2002, 4:22 pm
            --long                  same as '--formal'
            --succinct              Sat 5/15/02 16:22:43
            --iso                   Sat, 15 Jun 2002 16.22.43 GMT
            --filename              -June-15-2002-16.22.43
            --file                  same as '--filename'
            --mdy                   5/15/02
            --hm                    4:22 pm
            --hms                   4:22:43 pm
            --24hms                 16:22:43
            --dayofmonth            15
            --dayofyear             134 (1 - 365)
            --dayofweek             Saturday
            --dayofweek, --num      7
            --month                 June
            --month, --num          6
            --year                  2002
            --shortyear             02
            --minute                22
            --hour                  16 (0 - 24)
            --second                43

      Without the [format] argument this will return the last modified
      time of the file in seconds as an offset of localtime(time).
      This pertains to all other functions/methods that have to do
      with the time-sensitive attributes of a file.


   ===============================================
   GET A FILE'S CREATION TIME
   -----------------------------------------------
      my($created) = $fu->created('./directory/or/filename',[fmt]);


   ===============================================
   GET A FILE'S LAST ACCESSED TIME
   -----------------------------------------------
      my($lastaccss) = $fu->last_access('./directory/or/filename',[fmt]);


   ===============================================
   GET FILE TYPE
   -----------------------------------------------
      my($type) = $fu->type('./directory/or/filename',[fmt]);


   ===============================================
   GET FILE SIZE
   -----------------------------------------------
      my($size) = $fu->fsize('./directory/or/filename',[fmt]);


==================================================
MISCELLANEOUS
--------------------------------------------------

   ===============================================
   ESCAPE FILENAME TO A SINGLE STRING (for saving file uploads mainly)
   -----------------------------------------------
      my($upload_name) = $fu->escape_filename('./directory/or/filename');


   ===============================================
   STRIP THE PATH FROM A FILE NAME
   -----------------------------------------------
      my($file) = $fu->strip_filename('strip/path/leave/last/filename');


==================================================
REFERENCE MATERIAL
--------------------------------------------------

   PERL FILE CHECKS REFERENCE

    -r  File is readable by effective uid/gid.
    -w  File is writable by effective uid/gid.
    -x  File is executable by effective uid/gid.
    -o  File is owned by effective uid.
    -R  File is readable by real uid/gid.
    -W  File is writable by real uid/gid.
    -X  File is executable by real uid/gid.
    -O  File is owned by real uid.
    -e  File exists.
    -z  File has zero size.
    -s  File has non-zero size (returns size).
    -f  File is a plain file.
    -d  File is a directory.
    -l  File is a symbolic link.
    -p  File is a named pipe (FIFO).
    -S  File is a socket.
    -b  File is a block special file.
    -c  File is a character special file.
    -t  Filehandle is opened to a tty.
    -u  File has setuid bit set.
    -g  File has setgid bit set.
    -k  File has sticky bit set.
    -T  File is a text file.
    -B  File is a binary file (opposite of -T).
    -M  Age of file in days when script started.
    -A  Same for access time.
    -C  Same for inode change time.


   SYSTEM FLOCK SUPPORT DEFINES

   d_fcntl_can_lock
      From d_fcntl_can_lock.U:
         This variable conditionally defines the FCNTL_CAN_LOCK symbol
         and indicates whether file locking with fcntl() works.

   d_flock
      From d_flock.U:
         This variable conditionally defines HAS_FLOCK if flock() is
         available to do file locking.

   d_lockf
      From d_lockf.U:
         This variable conditionally defines HAS_LOCKF if lockf() is
         available to do file locking.

         /FLOCKING CONSTANTS/

            classic values for these constants are as listed,
            but this can vary from system to system
               LOCK_EX 2
               LOCK_UN 8
               LOCK_NB 4
               LOCK_SH 1
