NAME
Bio::Root::IOManager - Input and output manager for Perl5 objects.
SYNOPSIS
Object Creation
The creation of Bio::Root::IOManager.pm objects is handled by Bio::Root::Object.pm which delegates various I/O tasks to this module.
use Bio::Root::IOManager;
$myIO = new Bio::Root::IOManager(-WHERE =>'/usr/tmp/data.out',
-PARENT =>$self);INSTALLATION
This module is included with the central Bioperl distribution:
http://bio.perl.org/Core/Latest
ftp://bio.perl.org/pub/DISTFollow the installation instructions included in the README file.
DESCRIPTION
This module encapsulates the data and methods necessary for regulating input/output (I/O) of data from Perl objects. It is concerned with "where" to get input or send output as opposed to "what" to get. IOManager.pm is intended to consolidate various I/O issues for Perl objects and provide an object-oriented way to do I/O things such as:
passing filehandles between objects,
opening and reading input from files or STDIN,
routine file management (compressing, uncompressing, and deleting).
Subclasses of Bio::Root::Object.pm have access to all methods defined in IOManager.pm since Bio::Root::Object.pm employs Bio::Root::IOManager.pm by a delegation mechanism.
It is not clear yet how much objects really need to do the fancy I/O gymnastics as supported by IOManager. Most of the time, objects simply send output to STDOUT which is managed at the script/program level. The fancy I/O manipulations are considered experimental and have not been adequately tested or utilized. I'm not really satisfied with the current display()/set_display() strategy. The additional functionality is not often utilized in typical applications. Is the extra complexity worth it?
The API for this module is under development.
Generic Data Access & Manipulation
The read() method provided permits the following:
read from a file or STDIN.
read a single record or a stream containing multiple records.
specify a record separator.
store all input data in memory or process the data stream as it is being read.
DEPENDENCIES
Bio::Root::IOManager.pm inherits from Bio::Root::Object.pm and uses FileHandle.pm. Bio::Root::Utilities.pm is also used for routine file manipulations compression/uncompression/deletion.
SEE ALSO
Bio::Root::Object.pm - Core object
Bio::Root::Utilities.pm - Generic utilty object
Bio::Root::Global.pm - Manages global variables/constants
http://bio.perl.org/Projects/modules.html - Online module documentation
http://bio.perl.org/ - Bioperl Project Homepage
FileHandle.pm (included in the Perl distribution or CPAN).TODO
Experiment with using the newer IO.pm included in the Perl distribution, instead of FileHandle.pm.
FEEDBACK
Mailing Lists
User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated.
bioperl-l@bioperl.org - General discussion
http://bioperl.org/MailList.shtml - About the mailing listsReporting Bugs
Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via email or the web:
bioperl-bugs@bio.perl.org
http://bio.perl.org/bioperl-bugs/AUTHOR
Steve Chervitz <sac@bioperl.org>
See the FEEDBACK section for where to send bug reports and comments.
VERSION
Bio::Root::IOManager.pm, 0.043
ACKNOWLEDGEMENTS
This module was developed under the auspices of the Saccharomyces Genome Database: http://genome-www.stanford.edu/Saccharomyces
COPYRIGHT
Copyright (c) 1997-98 Steve Chervitz. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
APPENDIX
Methods beginning with a leading underscore are considered private and are intended for internal use by this module. They are not considered part of the public interface and are described here for documentation purposes only.
file
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.See Also : compress_file(), uncompress_file(), delete_file()
set_fh
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 : ExperimentalSee also : set_read(), set_display().
set_display
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.See also : display(), set_fh()
set_read
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.See also : read(), set_display()
set_display_err
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 TESTEDSee also : set_display(), set_read()
show
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/aSee also : set_display()
fh
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 : ExperimentalSee also : set_display(), set_read(), set_fh(), set_display_err()
read
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 <GEN0> at /tools/perl/5.003/lib/FileHandle.pm line 255."See Also : file(), Bio::Root::Utilities::create_filehandle()
display
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.See also : set_display()
_print_stats_header
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 : Experimentalfile_date
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.See Also : file(), Bio::Root::Utilities::file_date()
compress_file
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.See Also : uncompress_file(), file(), Bio::Root::Utilities::compress()
uncompress_file
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.See Also : compress_file(), file(), Bio::Root::Utilities::uncompress()
delete_file
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.See Also : file(), Bio::Root::Utilities::delete()
FOR DEVELOPERS ONLY
Data Members
Information about the various data members of this module is provided for those wishing to modify or understand the code. Two things to bear in mind:
- 1 Do NOT rely on these in any code outside of this module.
-
All data members are prefixed with an underscore to signify that they are private. Always use accessor methods. If the accessor doesn't exist or is inadequate, create or modify an accessor (and let me know, too!).
- 2 This documentation may be incomplete and out of date.
-
It is easy for this documentation to become obsolete as this module is still evolving. Always double check this info and search for members not described here.
An instance of Bio::Root::IOManager.pm is a blessed reference to a hash containing all or some of the following fields:
FIELD VALUE
------------------------------------------------------------------------
_show Selects display options.
_fh FileHandle object for redirecting STDIN or STDOUT.
_fherr FileHandle object for error data. Append mode.
_fh_name The arguments used to create fh.
_fherr_name The arguments used to create fherr.
INHERITED DATA MEMBERS
_parent (From Bio::Root::Object.pm> Object reference for the owner of this IOManager.