Bio::Root::Root - implementation of Bio::Root::RootI interface

       Ewan Birney, Lincoln Stein

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

   clone
        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.

   _dclone
        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.

   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 : The current verbosity setting (integer between -1 to 2)
        Args    : -1,0,1 or 2

   _register_for_cleanup_unregister_for_cleanup_cleanup_methodsthrow
        Title   : throw
        Usage   : $obj->throw("throwing exception message");
                  or
                  $obj->throw( -class => 'Bio::Root::Exception',
                               -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:
                  '-class'  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
                  '-text'   a string giving a descriptive error message
                  '-value'  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't 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't need the main:: part) and setting it to
                   a true value; you must do this within a BEGIN subroutine.

   debug
        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

   _load_module
        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).

   DESTROY
perl v5.32.1                                       2021-08-15                               Bio::Root::Root(3pm)

       This is a hashref-based implementation of the Bio::Root::RootI interface.  Most Bioperl objects should
       inherit from this.

       See the documentation for Bio::Root::RootI for most of the methods implemented by this module.  Only
       overridden methods are described here.

   ThrowingExceptions
       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 CPAN) if
       it has also been installed.

       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 "catch{}" 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.

   TypedExceptionSyntax
       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.

       To take advantage of this capability, you must specify arguments as named parameters in the throw() call.
       Here are the parameters:

       -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.

       -text
           a sensible message for the exception

       -value
           the value causing the exception or $!, if appropriate.

       Note  that  Bio::Root::Exception  does  not need to be imported into your module (or script) namespace in
       order to throw exceptions via Bio::Root::Root::throw(), since Bio::Root::Root imports it.

   Try-Catch-FinallySupport
       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 CPAN).  See the documentation for
       Error for more details.

       Here's an example. See the Bio::Root::Exception module for other pre-defined exception types:

          my $IN;
          try {
           open $IN, '<', $file or $obj->throw( -class => 'Bio::Root::FileOpenException',
                                                -text  => "Cannot read file '$file'",
                                                -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!

       Bio::Root::Root - implementation of Bio::Root::RootI interface

         # Any Bioperl-compliant object is a RootI compliant object

         # Here's 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 => 'Bio::Root::BadParameter',
                      -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\n");

         # Deep-object copy

         my $clone = $obj->clone;