Usage     : n/a; internal method.
           : $obj->_print_stats_header(filehandle);
 Purpose   : Prints a header containing basic info about the object
           : such as the class and name of the object followed by a
           : line of hyphens.
 Status    : Experimental

 Usage     : $object->compress_file([filename]);
 Purpose   : Compresses a file if not already compressed.
           : Compresses to a temorary file if user is not owner of supplied file.
 Example   : $object->file('/usr/home/me/data.txt');
           : $object->compress_file();
 Argument  : String (full path name) (optional).
           : If no argument is provided, the file data member is used.
 Returns   : String (compressed file name, full path).
           : Sets the file data member to the compressed name
           : when not operating on a file supplied as an argument.
           : Returns false (undef) if the file is already compressed
           : (binary test).
 Throws    : Exception if no file is specified.
           : Propagates any exception thrown by Bio::Root::Utilities::compress()
           : if the file cannot be compressed().
           : Tests if file is already compressed to avoid trivial error due to
           : the file already being compressed.
           :
 Comments  : Relies on the compress() method of Bio::Root::Utilities.pm
           : to implement the file compression functionality.
           : (Currently, Bio::Root::Utilities::compress() uses gzip.)
           :
           : If the user is not the owner of the file, the file is
           : compressed to a tmp file.
           :
           : All file compressing/uncompressing requests should go through
           : compress_file()/uncompress_file(). This serves to confine the
           : dependency between IOManager.pm module and Utilities.pm
           : which helps maintainability.
           :
 Bugs      : Only compresses text files. This obviates a dependency on
           : particular file suffixes but is not good if you
           : want to compress a binary file.
           :
           : May not be taint-safe.

 Usage     : $object->delete_file([filename]);
 Purpose   : Delete a file.
 Example   : $object->delete_file('/usr/people/me/data.txt');
 Returns   : String (name of file which was deleted) if successful,
           : undef if file does not exist.
           : Sets the file data member to undef
           : when not operating on a file supplied as an argument.
 Argument  : String (full path name) (optional).
           : If no argument is provided, the file data member is used.
 Throws    : Exception if the user is not the owner of the file.
           : Propagates any exception thrown by Bio::Root::Utilities::delete().
           : if the file cannot be deleted.
 Comments  : Be careful with this method: there is no undelete().
           : Relies on the delete() method provided by Bio::Root::Utilities.pm
           : to implement the file deletion functionality.
           : This method is not taint-safe.
           : It is intended for off-line maintenance use only.

 Usage     : $self->set_display(named parameters)
 Purpose   : Provides a default display method which calls set_display()
           : and also invokes methods to display an object's stats
           : if necessary ( _print_stats_header() and _displayStats() ).
 Returns   : True (1).
 Throws    : Propagates any exceptions thrown by set_display().
 Arguments : Named parameters for set_display().
 Comments  : I'm not satisfied with the current display()/set_display() strategy.

 Usage     : $object->fh(['name'])
 Purpose   : Accessor for an object's FileHandle object or the argument used
           : to create that object.
 Returns   : One of the following:
           :   1. The arguments used when the filehandle was created ('fh_name').
           :   2. The FileHandle object reference previously assigned to $self->{'_fh'}.
           :   3. Typeglob reference \*STDIN,  \*STDOUT or \*STDERR.
 Example   : $self->fh();          # returns filehandle for the STDIN/STDOUT path.
           : $self->fh('err');     # returns filehandle for the err file.
           : $self->fh('name');    # returns fh creation arguments.
           : $self->fh('errname'); # returns fh creation arguments for the err file.
 Status    : Experimental

 Usage     : $object->file([filename]);
 Purpose   : Set/Get name of a file associated with an object.
 Example   : $object->file('/usr/home/me/data.txt');
 Returns   : String (full path name)
 Argument  : String (full path name) OR a FileHandle or TypeGlob reference
           : (argument only required for setting)
 Throws    : Exception if the file appears to be empty or non-existent
 Comments  : File can be text or binary.

 Usage     : $object->file_date( %named_parameters);
 Purpose   : Get the last modified date of a file.
 Example   : $object->file_date();
           : $object->file_date(-FMT =>'yyyy-mmm-dd',
				-FILE =>'/usr/people/me/data.txt');
           : $object->file_date(-FMT =>'yyyy-mmm-dd');
 Returns   : String (date)
 Argument  : Named parameters:  (TAGS CAN BE UPPER OR LOWER CASE)
           :   -FILE  => string (filename full path)
           :   -FMT   => string (format for the returned date string)
           :
 Throws    : Exception if no file is specified or the file is non-existent
           : (Propagated from Utilities::file_date())
 Comments  : File can be text or binary.

 Usage     : $object->read(<named parameters>);
 Purpose   : Read raw textual data from a file or STDIN.
           : Optionally process each record it as it is read.
 Example   : $data = $object->read(-FILE    =>'usr/people/me/data.txt',
	   :			   -REC_SEP =>"\n:",
	   :			   -FUNC    =>\&process_rec);
           : $data = $object->read(-FILE  =>\*FILEHANDLE);
           : $data = $object->read(-FILE  =>new FileHandle $file, 'r');
           :
 Argument  : Named parameters: (TAGS CAN BE UPPER OR LOWER CASE)
           :  (all optional)
           :    -FILE    => string (full path to file) or a reference
           :                to a FileHandle object or typeglob. This is an
           :                optional parameter (if not defined, STDIN is used).
           :    -REC_SEP => record separator to be used
           :                when reading in raw data. If none is supplied,
           :                the default record separator is used ($/).
           :                $/ is localized to this method but be careful if
           :                you do any additional file reading in functions
           :                called by this method (see the -FUNC parameter).
           :                Such methods will use the value of $/ set
           :                by read() (if a -RE_SEP is supplied).
           :    -FUNC    => reference to a function to be called for each
           :                record. The return value of this function is now checked:
           :                if false, the reading is terminated.
           :                Typically -FUNC supplies a closure.
           :    -HANDLE  => reference to a FileHandle object or a
           :                typeglob to be use for reading input.
           :                The FileHandle object should be configured to
           :                read from a desired file before calling this
           :                method. If both -handle and -file are defined,
           :                -handle takes precedence.
           :                (The -HANDLE parameter is no longer necessary
           :                 since -FILE can now contain a FileHandle ref.)
           :    -WAIT    => integer (number of seconds to wait for input
           :                before timing out. Default = 20 seconds).
           :
 Returns   : string, array, or undef depending on the arguments.
           : If a function reference is supplied, this function will be
           : called using the contents of each record as it is read in.
           : If no function reference is supplied, the data are returned as a
           : string in scalar context or as a list in array context.
           : The data are not altered; blank lines are not removed.
           :
 Throws    : Exception if no input is read from source.
           : Exception if no input is read within WAIT seconds.
           : Exception if FUNC is not a function reference.
           : Propagates any exceptions thrown by create_filehandle()
           :
 Comments  : Gets the file name from the current file data member.
           : If no file has been defined, this method will attempt to
           : read from STDIN.
           :
           : COMPRESSED FILES:
           :    read() will attempt to use gzip -cd to read the file
           : if it appears to be compressed (binary file test).
           :
           : If the raw data is to be returned, wantarray is used to
           : determine how the data are to be returned (list or string).
           :
           : Sets the file data member to be the supplied file name.
           : (if any is supplied).

           : The read() method is a fairly new implementation
           : and uses a different approach than display().
           : For example, set_read() is not used.

 Bugs      : The following error is generated by Perl's FileHandle.pm module
           : when using the -w switch. It can be ignored for now:
  "Close on unopened file  at /tools/perl/5.003/lib/FileHandle.pm line 255."

 Usage     : $self->set_display([-WHERE=>'path'],
	   :			[-SHOW =>'what is to be displayed'],
	   :			[-MODE =>'file open mode'])
 Purpose   : Sets a new FileHandle object for output.
           : - Sets the objects 'show' data member to 'default' if it is not defined.
           : - Is a wrapper for setting an object's STDOUT filehandle:
           :   Checks the -WHERE parameter and the status of the object's current
           :   filehandle {'_fh'} and does one of three things:
           :    1. If $param{-WHERE} is defined and is not 'STDOUT', it is sent to
           :       set_fh() to open a new fh,
           :    2. else, if 'fh' has already been defined, it is returned,
           :    3. else, if where equals 'STDOUT', \*STDOUT is returned.
           :    4. else, \*STDOUT is returned.
           :
           : Thus, if an object has already set its 'fh' to some location,
           : it can still print to 'STDOUT' by explicitly passing -WHERE='STDOUT'
           : to display().
           :
 Arguments : Named parameters: (TAGS CAN BE UPPER OR LOWER CASE).
           : (all are optional).
           :    -WHERE => full path name of file to write to or 'STDOUT'.
           :    -SHOW  => what data is to be displayed. Becomes $self->{'_show'}
           :                     Default = 'default'. This results in a call to
           :                     _display_stats() method when display() is called
           :    -MODE  => mode for opening file. Default is overwrite '>'.
           :
 Returns   : FileHandle object reference or typglob reference (\*STDOUT).
 Throws    : Exception propagated from set_fh().
 Example   : $self->set_display();
           : $self->set_display(-WHERE=>'./data.out');
           : $self->set_display(-WHERE=>$obj->fh());
 Status    : Experimental
 Comments  : I'm not satisfied with the current display()/set_display() strategy.

 Purpose   : Sets a new FileHandle object for outputing error information.
           : Same logic as set_display() but creates a filehandle in
           : append mode.
 Returns   : The output FileHandle object for saving errors or \*STDERR.
 Status    : Experimental
 WARNING   : NOT TESTED

 Usage     : $self->set_fh( named_parameters )
 Purpose   : Sets various FileHandle data members ('fh', 'fherr').
           : Provides a public interface for _open_fh().
 Returns   : n/a
 Argument  : Named parameters:  (TAGS CAN BE UPPER OR LOWER CASE)
           :   -PATH  => string (filename) or a FileHandle object ref.
           :   -PRE   => string, prefix for opening (e.g., '>', '>>').
           :   -POST  => string, postfix for opening (e.g., '|'), for commands.
           :   -WHICH => string, 'err' for setting output path for errors.
           :
 Throws    : Exception propagated from _open_fh()
 Examples  : $self->set_fh();                   # Create anonymous FileHandle object
           : $self->set_fh(-PATH =>'fileName',  # Open for writing
	   :		   -PRE =>'>');
           : $self->set_fh(-PATH =>'fileName',  # Open error log file in append mode.
	   :		   -PRE  =>'>>',
	   :		   -WHICH =>'err');
           : $self->set_fh(-PATH =>$obj->fh()); # Copy a file handle from another object.
           :
 Comments  : set_read() and set_display() provide
           : interfaces for set_fh().
 Status    : Experimental

 Purpose   : Sets a new FileHandle object for input.
           : Same logic as set_display() but creates filehandle for read only.
 Returns   : The input FileHandle object or \*STDIN.
 Arguments : Named parameters: (TAGS CAN BE UPPER OR LOWER CASE).
           :    $param{-WHERE} = full path name of file to write to.
 Access    : Public
 Status    : Experimental, Deprecated
           :
 WARNING   : THIS METHOD HAS NOT BEEN TESTED AND IS LIKELY UNNECESSARY.
           : USE THE read() METHOD INSTEAD.
           :
           : Note also that set_read() uses the same data member as set_display()
           : so it is currently not possible to simultaneously have
           : different displaying and reading filehandles. This degree of
           : I/O control has not been necessary.

 Usage     : $self->show()
 Purpose   : Get the string used to specify what to display
           : using the display() method.
 Returns   : String or undef if no show data member is defined.
 Arguments : n/a

 Usage     : $object->uncompress_file([filename]);
 Purpose   : Uncompresses the file containing the raw report.
           : Uncompresses to a temorary file if user is not owner of supplied file.
 Example   : $object->file('/usr/home/me/data.txt.gz');
           : $object->uncompress_file();
 Argument  : String (full path name) (optional).
           : If no argument is provided, the file data member is used.
 Returns   : String (uncompressed file name, full path).
           : Sets the file data member to the uncompressed name
           : when not operating on a file supplied as an argument.
           : Returns false (undef) if the file is already uncompressed.
           :
 Throws    : Exception if no file is specified.
           : Propagates any exception thrown by Bio::Root::Utilities::compress()
           : if the file cannot be uncompressed().
           : Tests if file is already uncompressed to avoid trivial error due to
           : the file already being uncompressed.
 Comments  : See comments for compress_file(). They apply here as well.
           :
 Bugs      : Considers all binary files to be compressed. This obviates
           : a dependency on particular file suffixes.
           : May not be taint safe.