Linux Certif

Toute la documentation sur la certification Linux LPI

Bio::Root::RootI.3pm

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";
   }
 
   # Using throw_not_implemented() within a RootI-based interface module:
 
   package Foo;
   use base qw(Bio::Root::RootI);
 
   sub foo {
       my $self = shift;
       $self->throw_not_implemented;
   }
 
 

DESCRIPTION

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

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

Using throw_not_implemented()

The method throw_not_implemented() should be called by all methods within interface modules that extend RootI so that if an implementation fails to override them, an exception will be thrown.

For example, say there is an interface module called "FooI" that provides a method called "foo()". Since this method is considered abstract within FooI and should be implemented by any module claiming to implement "FooI", the "FooI::foo()" method should consist of the following:

     sub foo {
         my $self = shift;
         $self->throw_not_implemented;
     }
 
 

So, if an implementer of "FooI" forgets to implement "foo()" and a user of the implementation calls "foo()", a Bio::Exception::NotImplemented exception will result.

Unfortunately, failure to implement a method can only be determined at run time (i.e., you can't verify that an implementation is complete by running "perl -wc" on it). So it should be standard practice for a test of an implementation to check each method and verify that it doesn't throw a Bio::Exception::NotImplemented.

CONTACT

Functions originally from Steve Chervitz. Refactored by Ewan Birney. Re-refactored by Lincoln Stein.

APPENDIX

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

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    :
 
 

deprecated

  Title   : deprecated
  Usage   : $obj->deprecated("Method X is deprecated");
  Function: Prints a message about deprecation 
            unless verbose is < 0 (which means be quiet)
  Returns : none
  Args    : Message string to print to STDERR
 
 

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,
                :                 -desc     => $d,
                :                 -id       => $i);
  Returns   : @params - an array of parameters in the requested order.
            : The above example would return ($s, $i, $d).
            : Unspecified parameters will return undef. For example, if
            :        @param = (-sequence => $s);
            : the above _rearrange call would return ($s, undef, undef)
  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 Chervitz,
            : then migrated into Bio::Root::RootI.pm by Ewan Birney.
  Comments  :
            : Uppercase tags are the norm, 
            : (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 key names stand out better, and there are no method naming 
            : conflicts.
            : The drawbacks are that it's not as easy to type as lowercase,
            : and lots of uppercase can be hard to read.
            :
            : Regardless of the style, it greatly helps to line
                : the parameters up vertically for long/complex lists.
            :
            : Note that if @param is a single string that happens to start with
            : a dash, it will be treated as a hash key and probably fail to
            : match anything in the array_ref, so not be returned as normally
            : happens when @param is a simple list and not an associative array.
 
 

_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 code reference
 
 

The code reference will be invoked with the object as the first argument, as per a method. You may register an unlimited number of cleanup methods.

_unregister_for_cleanup

  Title   : _unregister_for_cleanup
  Usage   : -- internal --
  Function: Remove a method that has previously been registered to be called
            at DESTROY time.  If called with a method to be called at DESTROY time.
            Has no effect if the code reference has not previously been registered.
  Returns : nothing
  Args    : a code reference
 
 

_cleanup_methods

  Title   : _cleanup_methods
  Usage   : -- internal --
  Function: Return current list of registered cleanup methods.
  Returns : list of coderefs
  Args    : none
 
 

throw_not_implemented

  Purpose : Throws a Bio::Root::NotImplemented exception.
            Intended for use in the method definitions of 
            abstract interface modules where methods are defined
            but are intended to be overridden by subclasses.
  Usage   : $object->throw_not_implemented();
  Example : sub method_foo { 
              $self = shift; 
              $self->throw_not_implemented();
            }
  Returns : n/a
  Args    : n/a
  Throws  : A Bio::Root::NotImplemented exception.
            The message of the exception contains
              - the name of the method 
              - the name of the interface 
              - the name of the implementing class 
 
            If this object has a throw() method, $self->throw will be used.
            If the object doesn't have a throw() method, 
            Carp::confess() will be used.
 
 

warn_not_implemented

  Purpose : Generates a warning that a method has not been implemented.
            Intended for use in the method definitions of 
            abstract interface modules where methods are defined
            but are intended to be overridden by subclasses.
            Generally, throw_not_implemented() should be used,
            but warn_not_implemented() may be used if the method isn't
            considered essential and convenient no-op behavior can be 
            provided within the interface.
  Usage   : $object->warn_not_implemented( method-name-string );
  Example : $self->warn_not_implemented( "get_foobar" );
  Returns : Calls $self->warn on this object, if available.
            If the object doesn't have a warn() method,
            Carp::carp() will be used.
  Args    : n/a