This is Info file pm.info, produced by Makeinfo version 1.68 from the
input file bigpm.texi.
File: pm.info, Node: Bio/Root/Err, Next: Bio/Root/Global, Prev: Bio/RangeI, Up: Module List
Exception class for Perl 5 objects
**********************************
NAME
====
Bio::Root::Err.pm - Exception class for Perl 5 objects
SYNOPSIS
========
Object Creation
---------------
*Bio::Root::Object.pm* is a wrapper for Bio::Root::Err.pm objects so
clients do not have to create these objects directly. Please see
*Bio::Root::Object::throw()* as well as `_initialize' in this node() for a
more complete treatment of how to create Bio::Root::Err.pm objects.
use Bio::Root::Err;
$err = Bio::Root::Err->new(-MSG =>"Bad data: $data",
-STACK =>[\caller(0), \caller(1), ...],
);
To use the `throw' in this node() method directly:
use Bio::Root::Err (:std);
throw( $object_ref, 'Error message', 'additional note', 'technical note');
The `$object_ref' argument should be a reference to a
Bio::Root::Object.pm.
See also `USAGE' in this node.
INSTALLATION
============
This module is included with the central Bioperl distribution:
http://bio.perl.org/Core/Latest
ftp://bio.perl.org/pub/DIST
Follow the installation instructions included in the README file.
DESCRIPTION
===========
A Bio::Root::Err.pm object encapsulates data and methods that facilitate
working with errors and exceptional conditions that arise in Perl objects.
There are no biological semantics in this module, as one may suspect from
its location in the Bio:: hierarchy. The location of this module serves to
separate it from the namespaces of other Perl Error modules. It also makes
it convenient for use by Bio:: objects.
The motivation for having an error object is to allow Perl 5 objects to
deal with errors or exceptional conditions that can arise during their
construction or manipulation. For example:
(1) A complex object can break in many ways.
(2) Tracking errors within a set of nested objects can be difficult.
(3) The way an error is reported should be context-sensitive:
a web-user needs different information than does the
software engineer.
Bio::Root::Err.pm, along with *Bio::Root::Object.pm*, attempt to make
such problems tractable. Please see the *Bio::Root::Object.pm*
documentation for more about my error handling philosophy.
A *Bio::Root::Err.pm* object is an example of a Vector-Object: This
module inherits both from *Bio::Root::Object.pm* and
*Bio::Root::Vector.pm*. This permits a single Err object to exist within a
linked list of Err objects OR alone. See the *Bio::Root::Vector.pm*
documentation for more about Vector-Objects.
*The API for this module is not complete since the module is under
development.*
Other Exception Strategies
--------------------------
Exception handling with Perl 5 objects is currently not as evolved as
one would like. The error handling used by *Bio::Root::Object.pm* and
Bio::Root::Err.pm relies on Perl's built-in error/exception handling with
eval/die, which is not very object-aware. What I've attempted to do with
these modules is to make eval/die more object-savvy, as well as make Perl 5
objects more eval/die-savvy (but the current strategy is basically a hack).
It would be great if Perl could throw an object reference with die().
This would permit more intelligent and easy to write exception handlers.
For now the Err.pm object is reconstructed from the output of `string' in
this node().
There are some other third-party Exception classes such as Torsten
Ekedahl's *Experimental::Exception.pm* or Ken Steven's Throwable.pm or
Graham Barr's Error.pm (see `Other Exception Modules' in this node). These
modules attempt to introduce a traditional "try-catch-throw" exception
handling mechanism into Perl. Future version of my modules (and perhaps
erl itself) may utilize one of these.
USAGE
=====
A demo script that illustrates working with Bio::Root::Err objects is
available at:
http://bio.perl.org/Core/Examples/Root_object/error.pl
DEPENDENCIES
============
Bio::Root::Err.pm inherits from *Bio::Root::Object.pm* and
*Bio::Root::Vector.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 lists
Reporting 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 A. Chervitz, sac@genome.stanford.edu
See the `FEEDBACK' in this node section for where to send bug reports
and comments.
VERSION
=======
Bio::Root::Err.pm, 0.041
SEE ALSO
========
Bio::Root::Object.pm - Core object
Bio::Root::Vector.pm - Vector 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
Other Exception Modules
-----------------------
Experimental::Exception.pm - ftp://ftp.matematik.su.se/pub/teke/
Error.pm - http://www.cpan.org/authors/id/GBARR/
Throwable.pm - mailto:kstevens@globeandmail.ca
http://genome-www.stanford.edu/perlOOP/exceptions.html
ACKNOWLEDGEMENTS
================
This module was developed under the auspices of the Saccharomyces Genome
Database: http://genome-www.stanford.edu/Saccharomyces
Other Bioperl developers contributed ideas including Ewan Birney, Ian
Korf, Chris Dagdigian, Georg Fuellen, and Steven Brenner.
COPYRIGHT
=========
Copyright (c) 1996-8 Steve A. Chervitz. All Rights Reserved. This
module is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
TODO
====
* Improve documentation.
* Experiment with other Exception modules.
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.
_initialize
-----------
Usage : n/a; automatically called by Bio::Root::Object::new()
Purpose : Initializes key Bio::Root::Err.pm data.
Returns : String (the -MAKE constructor option.)
Argument : Named parameters passed from new()
: (PARAMETER TAGS CAN BE UPPER OR LOWER CASE).
: -MSG => basic description of the exception.
: -NOTE => additional note to indicate cause of exception
: or provide information about how to fix/report it
: -TECH => addition note with technical information
: of interest to developer.
: -STACK => array reference containing caller() data
: -TYPE => string, one of @Bio::Root::Err::ERR_TYPES
: (default = exception).
: -CONTEXT => array reference
: -OBJ => Err object to be cloned.
See Also : *Bio::Root::Object::_set_err()*
_set_clone
----------
Usage : n/a; internal method used by _initialize()
Purpose : Copy all Bio::Root::Err.pm data members into a new object reference.
Argument : object ref for object to be cloned.
Comments : Does not cloning the vector since this method is
: typically used to extract a single Err object from its vector.
_build_from_string
------------------
Usage : n/a; called by _initialize()
Purpose : Re-create an Err.pm object from a string containing Err data.
Returns : boolean, (was the Err.pm object rebuilt?)
Argument : message, note, tech passed from _initialize()
: The message is examined to see if it contains a stringified error.
See Also : `_initialize' in this node(), `string' in this node(),
`_has_err' in this node()
_has_err
--------
Usage : n/a; internal method called by _build_from_string()
Purpose : Deterimine if an Err has already been set to prevent duplicate Errs.
Returns : boolean
See Also : `_build_from_string' in this node()
_set_type
---------
Usage : n/a; internal method
Purpose : Sets the type of Err (warning, exception, fatal)
: Called by _initialize()
Argument : string
_set_list_data
--------------
Usage : n/a; internal method used by set().
: $err->_set_list_data( $member, $data);
Purpose : For data members which are anonymous arrays: note, tech, stack,
: adds the given data to the list.
Arguments : $member = any of qw(note tech stack)
: $data = string
Comments : Splits $data on tab. Each item
: of the split is a new entry.
: To clobber the current data (unusual situation), you must first
: call set() with no data then call again with desired data.
_set_context
------------
Usage : n/a; internal method used by set().
Purpose : Sets the object containment context for the exception.
: (this is the hierarchy of objects in which the
: exception occurred.)
set
---
Usage : $err->set( $member, $data );
Purpose : General accessor for setting any Err.pm data member.
Example : $err->set('note', 'this is an additional note.');
Returns : n/a
Argument : $member = string, any of qw(msg type note tech stack)
: $data = string
Throws : n/a
Comments : Note, tech, and stack items are appended to any existing
: notes, tech notes, and stack.
: There should be no need to mess with the stack.
msg
---
Usage : $message = $err->msg;
Purpose : Get the main message associated with the exception.
Returns : String
Argument : optional string to be used as a delimiter.
See Also : `get' in this node(), `string' in this node()
type
----
Usage : $type = $err->type;
Purpose : Get the type of Err (warning, exception, fatal)
Returns : String
Argument : optional string to be used as a delimiter.
See Also : `get' in this node(), `string' in this node()
note
----
Usage : $note = $err->note;
: $note = $err->note('');
Purpose : Get any general note associated with the exception.
Returns : String
Argument : optional string to be used as a delimiter.
See Also : `get' in this node(), `string' in this node()
tech
----
Usage : $tech = $err->tech;
: $tech = $err->tech('
');
Purpose : Get any technical note associate with the exception.
Returns : String
Argument : optional string to be used as a delimiter.
See Also : `get' in this node(), `string' in this node()
stack
-----
Usage : $stack = $err->stack;
: $stack = $err->stack('
');
Purpose : Get the call stack for the exception.
Returns : String
Argument : optional string to be used as a delimiter.
See Also : `get' in this node(), `string' in this node()
context
-------
Usage : $context = $err->context;
: $context = $err->context('
');
Purpose : Get the containment context of the object which generated the exception.
Returns : String
Argument : optional string to be used as a delimiter.
See Also : `get' in this node(), `string' in this node()
get
---
Usage : $err->get($member, $delimiter);
Purpose : Get specific data from the Err.pm object.
Returns : String in scalar context.
: Array in list context.
Argument : $member = any of qw(msg type note tech stack context) or combination.
: $delimiter = optional string to be used as a delimiter
: between member data.
See Also : `string' in this node(), `msg' in this node(), `note' in
this node(), `tech' in this node(), `type' in this node(), `context' in
this node(), `stack' in this node()
_get_list_data
--------------
Usage : n/a; internal method used by get()
Purpose : Gets data for members which are list refs (note, tech, stack, context)
Returns : Array
Argument : ($member, $delimiter)
See Also : `get' in this node()
get_all
-------
Usage : (same as get())
Purpose : Get specific data from all errors in an Err.pm object.
Returns : Array in list context.
: String in scalar context.
Argument : (same as get())
See Also : `get' in this node()
_add_note
---------
Usage : n/a; internal method called by _add_list_data()
Purpose : adds a new note.
See Also : `_add_list_data' in this node()
_add_list_data
--------------
Usage : n/a; called by _set_list_data()
Purpose : adds a new note or tech note.
See Also : `_set_list_data' in this node()
print
-----
Usage : $err->print;
Purpose : Prints Err data to STDOUT or a FileHandle.
Returns : Call to print
Argument : Named parameters for string()
Comments : Uses string() to get data.
See Also : `string' in this node()
string
------
Usage : $err->string( %named_parameters);
Purpose : Stringify the data contained in the Err.pm object.
Example : print STDERR $err->string;
Returns : String
Argument : Named parameters (optional) passed to
: Bio::Root::IOManager::set_display().
See Also : `print' in this node(), `_build_from_string' in this
node(), *Bio::Root::IOManager::set_display()*
is_fatal
--------
Usage : $err->is_fatal;
Purpose : Determine if the error is of type 'FATAL'
Returns : Boolean
Status : Experimental, Deprecated
throw
-----
Usage : throw($object, [message], [note], [technical note]);
: This method is exported.
Purpose : Class method version of Bio::Root::Object::throw().
Returns : die()s with the contents of the Err object in a string.
: If the global strictness is less than -1, die is not called and
: the error is printed to STDERR.
Argument : [0] = object throwing the error.
: [1] = optional message about the error.
: [2] = optional note about the error.
: [3] = optional technical note about the error.
Comments : The glogal verbosity level is not used. For verbosity-sensitive
: behavior, use Bio::Root::Object::throw().
Status : Experimental
: This method is an alternative to Bio::Root::Object::throw()
: and is not as well developed or documented as that method.
See Also : `warning' in this node(), *Bio::Root::Object::throw()*
*Bio::Root::Global::strictness*()
warning
-------
Usage : warning($object, [message], [note], [technical note]);
: This method is exported.
Purpose : Class method version of Bio::Root::Object::warn().
Returns : Prints the contents of the error to STDERR and returns false (0).
: If the global strictness() is > 1, warn() calls are converted
: into throw() calls.
Argument : [0] = object producing the warning.
: [1] = optional message about the error.
: [2] = optional note about the error.
: [3] = optional technical note about the error.
:
Comments : The glogal verbosity level is not used. For verbosity-sensitive
: behavior, use Bio::Root::Object::warn().
Status : Experimental
: This method is an alternative to Bio::Root::Object::warn()
: and is not as well developed or documented as that method.
See Also : `throw' in this node, *Bio::Root::Object::warn()*,
*Bio::Root::Global::strictness()*
format_stack_entry
------------------
Usage : &format_stack_entry(,,,,,)
: This function is exported.
Purpose : Creates a single stack entry given a caller() list.
Argument : List of scalars (output of the caller() method).
Returns : String = class_method($line)
: e.g., Bio::Root::Object::name(1234)
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::Err.pm is a blessed reference to a hash
containing all or some of the following fields:
FIELD VALUE
------------------------------------------------------------------------
_type fatal | warning | exception (one of @Bio::Root::Err::ERR_TYPES).
_msg Terse description: Main cause of error.
_note List reference. Verbose description: probable cause & troubleshooting for user.
_tech List reference. Technical notes of interest to programmer.
_stack List reference. Stack trace: list of "class::method(line number)" strings.
File: pm.info, Node: Bio/Root/Global, Next: Bio/Root/IO, Prev: Bio/Root/Err, Up: Module List
Global variables and utility functions
**************************************
NAME
====
Bio::Root::Global - Global variables and utility functions
SYNOPSIS
========
# no real synopsis - see Bio::Root::Object
DESCRIPTION
===========
The Bio::Root::Global file contains all the global flags about erro
warning etc, and also utility functions, eg to map numbers to roman
numerals.
These functions are generally called by Bio::Root::Object or somewhere
similar, and not directly
INSTALLATION
============
This module is included with the central Bioperl distribution:
http://bio.perl.org/Core/Latest
ftp://bio.perl.org/pub/DIST
Follow the installation instructions included in the README file.
File: pm.info, Node: Bio/Root/IO, Next: Bio/Root/IOManager, Prev: Bio/Root/Global, Up: Module List
module providing several methods often needed when dealing with file IO
***********************************************************************
NAME
====
Bio::Root::IO - module providing several methods often needed when
dealing with file IO
SYNOPSIS
========
# utilize stream I/O in your module
$self->{'io'} = Bio::Root::IO->new(-file => "myfile");
$self->{'io'}->_print("some stuff");
$line = $self->{'io'}->_readline();
$self->{'io'}->_pushback($line);
$self->{'io'}->close();
# obtain platform-compatible filenames
$path = Bio::Root::IO->catfile($dir, $subdir, $filename);
# obtain a temporary file (created in $TEMPDIR)
($handle) = $io->tempfile();
DESCRIPTION
===========
This module provides methods that will usually be needed for any sort
of file- or stream-related input/output, e.g., keeping track of a file
handle, transient printing and reading from the file handle, a close
method, automatically closing the handle on garbage collection, etc.
To use this for your own code you will either want to inherit from this
module, or instantiate an object for every file or stream you are dealing
with. In the first case this module will most likely not be the first
class off which your class inherits; therefore you need to call
_initialize_io() with the named parameters in order set file handle, open
file, etc automatically.
Most methods start with an underscore, indicating they are private. In
OO speak, they are not private but protected, that is, use them in your
module code, but a client code of your module will usually not want to
call them (except those not starting with an underscore).
In addition this module contains a couple of convenience methods for
cross-platform safe tempfile creation and similar tasks. There are some
CPAN modules related that may be not be available on all platforms. At
present, File::Spec and File::Temp are attempted. This module exports
$TEMPFILE and $ROOTDIR, which will always be set, $PATHSEP, which will be
set if File::Spec fails, and $OPENFLAGS, which will be set if either of
File::Spec or File::Temp fails.
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://bio.perl.org/MailList.html - About the mailing lists
Reporting 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 - Hilmar Lapp
====================
Email hlapp@gmx.net
Describe contact details here
APPENDIX
========
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
new
---
Title : new
Usage :
Function: Overridden here to automatically call _initialize_io().
Example :
Returns : new instance of this class
Args : named parameters
_initialize_io
--------------
Title : initialize_io
Usage : $self->_initialize_io(@params);
Function: Initializes filehandle and other properties.
Currently recognized the following named parameters: -file, -fh
Example :
Returns : TRUE
Args : named parameters
_fh
---
Title : _fh
Usage : $obj->_fh($newval)
Function:
Example :
Returns : value of _filehandle
Args : newvalue (optional)
_print
------
Title : _print
Usage : $obj->_print(@lines)
Function:
Example :
Returns : writes output
_readline
---------
Title : _readline
Usage : $obj->_readline
Function: Reads a line of input.
Note that this method implicitely uses the value of $/ that is
in effect when called.
Note also that the current implementation does not handle pushed
back input correctly unless the pushed back input ends with the
value of $/.
Example :
Returns :
_pushback
---------
Title : _pushback
Usage : $obj->_pushback($newvalue)
Function: puts a line previously read with _readline back into a buffer
Example :
Returns :
Args : newvalue
close
-----
Title : close
Usage : $seqio->close()
Function: Closes the file handle associated with this seqio system
Example :
Returns :
Args :
tempfile
--------
Title : tempfile
Usage : my ($handle,$tempfile) = $io->tempfile();
Function: Returns a temporary filename and a handle opened for writing and
and reading.
Caveats : If you do not have File::Temp on your system you should avoid
specifying TEMPLATE and SUFFIX. (We don't want to recode
everything, okay?)
Returns : a 2-element array, consisting of temporary handle and temporary
file name
Args : named parameters compatible with File::Temp: DIR (defaults to
$Bio::Root::IO::TEMPDIR), TEMPLATE, SUFFIX.
tempdir
-------
Title : tempdir
Usage : my ($tempdir) = $io->tempdir(CLEANUP=>1);
Function: Creates and returns the name of a new temporary directory.
Note that you should not use this function for obtaining "the"
temp directory. Use $Bio::Root::IO::TEMPDIR for that. Calling this
method will in fact create a new directory.
Returns : The name of a new temporary directory.
Args : args - ( key CLEANUP ) indicates whether or not to cleanup
dir on object destruction, other keys as specified by File::Temp
catfile
-------
Title : catfile
Usage : $path = Bio::Root::IO->catfile(@dirs,$filename);
Function: Constructs a full pathname in a cross-platform safe way.
If File::Spec exists on your system, this routine will merely
delegate to it. Otherwise it tries to make a good guess.
You should use this method whenever you construct a path name
from directory and filename. Otherwise you risk cross-platform
compatibility of your code.
You can call this method both as a class and an instance method.
Returns : a string
Args : components of the pathname (directories and filename, NOT an
extension)
File: pm.info, Node: Bio/Root/IOManager, Next: Bio/Root/Object, Prev: Bio/Root/IO, Up: Module List
Input and output manager for Perl5 objects.
*******************************************
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/DIST
Follow 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' in this node()/`set_display' in this node() 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' in this node() 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 lists
Reporting 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 A. Chervitz, sac@genome.stanford.edu
See the `FEEDBACK' in this node 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 A. 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' in this node(), `uncompress_file' in this
node(), `delete_file' in this node()
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 : Experimental
See also : `_open_fh' in this node(), `set_read' in this node(),
`set_display' in this node().
_open_fh
--------
Purpose : Creates a new FileHandle object and returns it.
: This method can be used when you need to
: pass FileHandles between objects.
Returns : The new FileHandle object.
Throws : Exception: if the call to new FileHandle fails.
Examples : $self->_open_fh(); # Create anonymous FileHandle object
: $self->_open_fh('fileName'); # Open for reading
: $self->_open_fh('>fileName'); # Open for writing
Status : Experimental
See also : `set_fh' in this node(), `fh' in this node(), `set_read'
in this node(), `set_display' in this node()
_close_fh
---------
Purpose : Destroy a FileHandle object.
Returns : n/a
Status : Experimental
See also : `_open_fh' in this node(), `set_fh' in this node()
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' in this node(), `set_fh' in this node()
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' in this node(), `set_display' in this node()
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 TESTED
See also : `set_display' in this node(), `set_read' in this node()
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/a
See also : `set_display' in this node()
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 : Experimental
See also : `set_display' in this node(), `set_read' in this node(),
`set_fh' in this node(), `set_display_err' in this node()
read
----
Usage : $object->read();
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."
See Also : `file' in this node(), `create_filehandle' in this node()
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' in this node(), `_print_stats_header' in
this node()
_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 : Experimental
file_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' in this node(), *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' in this node(), `file' in this node(),
*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' in this node(), `file' in this node(),
*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' in this node(), *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.