NAME

Bio::Root::RootI - Abstract interface to root object code

SYNOPSIS

# any bioperl or bioperl compliant object is a RootI 
# compliant object

$obj->throw("This is an exception");

eval {
    $obj->throw("This is catching an exception");
};

if( $@ ) {
    print "Caught exception";
} else {
    print "no exception";
}

DESCRIPTION

This is just a set of methods which do not assumme anything about the object they are on. The methods provide the ability to throw exceptions with nice stack traces.

This is what should be inherieted by all bioperl compliant interfaces, even if they are exotic XS/CORBA/Other perl systems.

CONTACT

Functions originally from Steve Chervitz. Refactored by Ewan Birney.

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

new

Purpose   : generic intantiation function can be overridden if 
            special needs of a module cannot be done in _initialize

throw

Title   : throw
Usage   : $obj->throw("throwing exception message")
Function: Throws an exception, which, if not caught with an eval brace
          will provide a nice stack trace to STDERR with the message
Returns : nothing
Args    : A string giving a descriptive error message

warn

Title   : warn
Usage   : $object->warn("Warning message");
Function: Places a warning. What happens now is down to the
          verbosity of the object  (value of $obj->verbose) 
           verbosity 0 or not set => small warning
           verbosity -1 => no warning
           verbosity 1 => warning with stack trace
           verbosity 2 => converts warnings into throw
Example :
Returns : 
Args    :

verbose

Title   : verbose
Usage   : $self->verbose(1)
Function: Sets verbose level for how ->warn behaves
          -1 = no warning
           0 = standard, small warning
           1 = warning with stack trace
           2 = warning becomes throw
Returns : nothing
Args    : -1,0,1 or 2

stack_trace_dump

Title   : stack_trace_dump
Usage   :
Function:
Example :
Returns : 
Args    :

stack_trace

Title   : stack_trace
Usage   : @stack_array_ref= $self->stack_trace
Function: gives an array to a reference of arrays with stack trace info
          each coming from the caller(stack_number) call
Returns : array containing a reference of arrays
Args    : none

_rearrange

 Usage     : $object->_rearrange( array_ref, list_of_arguments)
 Purpose   : Rearranges named parameters to requested order.
 Example   : $self->_rearrange([qw(SEQUENCE ID DESC)],@param);
           : Where @param = (-sequence => $s, 
	   :                 -id       => $i, 
	   :	             -desc     => $d);
 Returns   : @params - an array of parameters in the requested order.
           : The above example would return ($s, $i, $d)
 Argument  : $order : a reference to an array which describes the desired
           :          order of the named parameters.
           : @param : an array of parameters, either as a list (in
           :          which case the function simply returns the list),
           :          or as an associative array with hyphenated tags
           :          (in which case the function sorts the values 
           :          according to @{$order} and returns that new array.)
	   :	      The tags can be upper, lower, or mixed case
           :          but they must start with a hyphen (at least the
           :          first one should be hyphenated.)
 Source    : This function was taken from CGI.pm, written by Dr. Lincoln
           : Stein, and adapted for use in Bio::Seq by Richard Resnick and
           : then adapted for use in Bio::Root::Object.pm by Steve A. Chervitz.
 Comments  : (SAC)
           : This method may not be appropriate for method calls that are
           : within in an inner loop if efficiency is a concern.
           :
           : Parameters can be specified using any of these formats:
           :  @param = (-name=>'me', -color=>'blue');
           :  @param = (-NAME=>'me', -COLOR=>'blue');
           :  @param = (-Name=>'me', -Color=>'blue');
           :  @param = ('me', 'blue');  
           : A leading hyphenated argument is used by this function to 
           : indicate that named parameters are being used.
           : Therefore, the ('me', 'blue') list will be returned as-is.
           :
	   : Note that Perl will confuse unquoted, hyphenated tags as 
           : function calls if there is a function of the same name 
           : in the current namespace:
           :    -name => 'foo' is interpreted as -&name => 'foo'
	   :
           : For ultimate safety, put single quotes around the tag:
	   :    ('-name'=>'me', '-color' =>'blue');
           : This can be a bit cumbersome and I find not as readable
           : as using all uppercase, which is also fairly safe:
	   :    (-NAME=>'me', -COLOR =>'blue');
	   :
           : Personal note (SAC): I have found all uppercase tags to
           : be more managable: it involves less single-quoting,
           : the code is more readable, and there are no method naming conlicts.
           : Regardless of the style, it greatly helps to line
	   : the parameters up vertically for long/complex lists.

See Also : _initialize()

_register_for_cleanup

Title   : _register_for_cleanup
Usage   : -- internal --
Function: Register a method to be called at DESTROY time. This is useful
          and sometimes essential in the case of multiple inheritance for
          classes coming second in the sequence of inheritance.
Returns : 
Args    : a reference to a method