.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Root::Root 3pm"
.TH Bio::Root::Root 3pm "2021-08-15" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Root::Root \- implementation of Bio::Root::RootI interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  # Any Bioperl\-compliant object is a RootI compliant object
\&
\&  # Here\*(Aqs how to throw and catch an exception using the eval\-based syntax.
\&
\&  $obj\->throw("This is an exception");
\&
\&  eval {
\&      $obj\->throw("This is catching an exception");
\&  };
\&
\&  if( $@ ) {
\&      print "Caught exception";
\&  } else {
\&      print "no exception";
\&  }
\&
\&  # Alternatively, using the new typed exception syntax in the throw() call:
\&
\&  $obj\->throw( \-class => \*(AqBio::Root::BadParameter\*(Aq,
\&               \-text  => "Can not open file $file",
\&               \-value  => $file );
\&
\&  # Want to see debug() outputs for this object
\&
\&  my $obj = Bio::Object\->new(\-verbose=>1);
\&
\&  my $obj = Bio::Object\->new(%args);
\&  $obj\->verbose(2);
\&
\&  # Print debug messages which honour current verbosity setting
\&
\&  $obj\->debug("Boring output only to be seen if verbose > 0\en");
\&
\&  # Deep\-object copy
\&
\&  my $clone = $obj\->clone;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a hashref-based implementation of the Bio::Root::RootI
interface.  Most Bioperl objects should inherit from this.
.PP
See the documentation for Bio::Root::RootI for most of the methods
implemented by this module.  Only overridden methods are described
here.
.SS "Throwing Exceptions"
.IX Subsection "Throwing Exceptions"
One of the functionalities that Bio::Root::RootI provides is the
ability to throw() exceptions with pretty stack traces. Bio::Root::Root
enhances this with the ability to use Error (available from \s-1CPAN\s0)
if it has also been installed.
.PP
If Error has been installed, throw() will use it. This causes an
Error.pm\-derived object to be thrown. This can be caught within a
\&\f(CW\*(C`catch{}\*(C'\fR block, from which you can extract useful bits of
information. If Error is not installed, it will use the
Bio::Root::RootI\-based exception throwing facilty.
.SS "Typed Exception Syntax"
.IX Subsection "Typed Exception Syntax"
The typed exception syntax of throw() has the advantage of plainly
indicating the nature of the trouble, since the name of the class
is included in the title of the exception output.
.PP
To take advantage of this capability, you must specify arguments
as named parameters in the throw() call. Here are the parameters:
.IP "\-class" 4
.IX Item "-class"
name of the class of the exception.
This should be one of the classes defined in Bio::Root::Exception,
or a custom error of yours that extends one of the exceptions
defined in Bio::Root::Exception.
.IP "\-text" 4
.IX Item "-text"
a sensible message for the exception
.IP "\-value" 4
.IX Item "-value"
the value causing the exception or $!, if appropriate.
.PP
Note that Bio::Root::Exception does not need to be imported into
your module (or script) namespace in order to throw exceptions
via \fBBio::Root::Root::throw()\fR, since Bio::Root::Root imports it.
.SS "Try-Catch-Finally Support"
.IX Subsection "Try-Catch-Finally Support"
In addition to using an eval{} block to handle exceptions, you can
also use a try-catch-finally block structure if Error has been
installed in your system (available from \s-1CPAN\s0).  See the documentation
for Error for more details.
.PP
Here's an example. See the Bio::Root::Exception module for
other pre-defined exception types:
.PP
.Vb 10
\&   my $IN;
\&   try {
\&    open $IN, \*(Aq<\*(Aq, $file or $obj\->throw( \-class => \*(AqBio::Root::FileOpenException\*(Aq,
\&                                         \-text  => "Cannot read file \*(Aq$file\*(Aq",
\&                                         \-value => $!);
\&   }
\&   catch Bio::Root::BadParameter with {
\&       my $err = shift;   # get the Error object
\&       # Perform specific exception handling code for the FileOpenException
\&   }
\&   catch Bio::Root::Exception with {
\&       my $err = shift;   # get the Error object
\&       # Perform general exception handling code for any Bioperl exception.
\&   }
\&   otherwise {
\&       # A catch\-all for any other type of exception
\&   }
\&   finally {
\&       # Any code that you want to execute regardless of whether or not
\&       # an exception occurred.
\&   };
\&   # the ending semicolon is essential!
.Ve
.SH "AUTHOR Steve Chervitz"
.IX Header "AUTHOR Steve Chervitz"
Ewan Birney, Lincoln Stein
.SS "new"
.IX Subsection "new"
.Vb 2
\& Purpose   : generic instantiation function can be overridden if
\&             special needs of a module cannot be done in _initialize
.Ve
.SS "clone"
.IX Subsection "clone"
.Vb 10
\& Title   : clone
\& Usage   : my $clone = $obj\->clone();
\&           or
\&           my $clone = $obj\->clone( \-start => 110 );
\& Function: Deep recursion copying of any object via Storable dclone()
\& Returns : A cloned object.
\& Args    : Any named parameters provided will be set on the new object.
\&           Unnamed parameters are ignored.
\& Comments: Where possible, faster clone methods are used, in order:
\&           Clone::Fast::clone(), Clone::clone(), Storable::dclone.  If neither
\&           is present, a pure perl fallback (not very well tested) is used
\&           instead. Storable dclone() cannot clone CODE references.  Therefore,
\&           any CODE reference in your original object will remain, but will not
\&           exist in the cloned object.  This should not be used for anything
\&           other than cloning of simple objects. Developers of subclasses are
\&           encouraged to override this method with one of their own.
.Ve
.SS "_dclone"
.IX Subsection "_dclone"
.Vb 10
\& Title   : clone
\& Usage   : my $clone = $obj\->_dclone($ref);
\&           or
\&           my $clone = $obj\->_dclone($ref);
\& Function: Returns a copy of the object passed to it (a deep clone)
\& Returns : clone of passed argument
\& Args    : Anything
\& NOTE    : This differs from clone significantly in that it does not clone
\&           self, but the data passed to it.  This code may need to be optimized
\&           or overridden as needed.
\& Comments: This is set in the BEGIN block to take advantage of optimized
\&           cloning methods if Clone or Storable is present, falling back to a
\&           pure perl kludge. May be moved into a set of modules if the need
\&           arises. At the moment, code ref cloning is not supported.
.Ve
.SS "verbose"
.IX Subsection "verbose"
.Vb 9
\& 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 : The current verbosity setting (integer between \-1 to 2)
\& Args    : \-1,0,1 or 2
.Ve
.SS "_register_for_cleanup"
.IX Subsection "_register_for_cleanup"
.SS "_unregister_for_cleanup"
.IX Subsection "_unregister_for_cleanup"
.SS "_cleanup_methods"
.IX Subsection "_cleanup_methods"
.SS "throw"
.IX Subsection "throw"
.Vb 10
\& Title   : throw
\& Usage   : $obj\->throw("throwing exception message");
\&           or
\&           $obj\->throw( \-class => \*(AqBio::Root::Exception\*(Aq,
\&                        \-text  => "throwing exception message",
\&                        \-value => $bad_value  );
\& Function: Throws an exception, which, if not caught with an eval or
\&           a try block will provide a nice stack trace to STDERR
\&           with the message.
\&           If Error.pm is installed, and if a \-class parameter is
\&           provided, Error::throw will be used, throwing an error
\&           of the type specified by \-class.
\&           If Error.pm is installed and no \-class parameter is provided
\&           (i.e., a simple string is given), A Bio::Root::Exception
\&           is thrown.
\& Returns : n/a
\& Args    : A string giving a descriptive error message, optional
\&           Named parameters:
\&           \*(Aq\-class\*(Aq  a string for the name of a class that derives
\&                     from Error.pm, such as any of the exceptions
\&                     defined in Bio::Root::Exception.
\&                     Default class: Bio::Root::Exception
\&           \*(Aq\-text\*(Aq   a string giving a descriptive error message
\&           \*(Aq\-value\*(Aq  the value causing the exception, or $! (optional)
\&
\&           Thus, if only a string argument is given, and Error.pm is available,
\&           this is equivalent to the arguments:
\&                 \-text  => "message",
\&                 \-class => Bio::Root::Exception
\& Comments : If Error.pm is installed, and you don\*(Aqt want to use it
\&            for some reason, you can block the use of Error.pm by
\&            Bio::Root::Root::throw() by defining a scalar named
\&            $main::DONT_USE_ERROR (define it in your main script
\&            and you don\*(Aqt need the main:: part) and setting it to
\&            a true value; you must do this within a BEGIN subroutine.
.Ve
.SS "debug"
.IX Subsection "debug"
.Vb 5
\& Title   : debug
\& Usage   : $obj\->debug("This is debugging output");
\& Function: Prints a debugging message when verbose is > 0
\& Returns : none
\& Args    : message string(s) to print to STDERR
.Ve
.SS "_load_module"
.IX Subsection "_load_module"
.Vb 6
\& Title   : _load_module
\& Usage   : $self\->_load_module("Bio::SeqIO::genbank");
\& Function: Loads up (like use) the specified module at run time on demand.
\& Example :
\& Returns : TRUE on success. Throws an exception upon failure.
\& Args    : The module to load (_without_ the trailing .pm).
.Ve
.SS "\s-1DESTROY\s0"
.IX Subsection "DESTROY"