Archive Ensembl HomeArchive Ensembl Home
Bio::EnsEMBL::Utils::Exception Class Reference

List of all members.


Class Summary

Synopsis

  use Bio::EnsEMBL::Utils::Exception
    qw(throw warning deprecate verbose try catch);

  or to get all methods just

  use Bio::EnsEMBL::Utils::Exception;

  eval { throw("this is an exception with a stack trace") };
  if ($@) {
    print "Caught exception:\n$@";
  }

  # Or you can us the try/catch confortable syntax instead to deal with
  # throw or die.  Don't forget the ";" after the catch block.  With
  # this syntax, the original $@ is in $_ in the catch subroutine.

  try {
    throw("this is an exception with a stack trace");
  }
  catch { print "Caught exception:\n$_" };

  # silence warnings
  verbose('OFF');

  warning('this is a silent warning');

  #show deprecated and warning messages but not info
  verbose('DEPRECATE');

  warning('this is a warning');

  # show all messages
  verbose('ALL');

  info('this is an informational message');

  sub my_sub { deprecate('use other_sub() instead') }

  verbose('EXCEPTION');
  info( 'This is a high priority info message.', 1000 );

Description

This is derived from the Bio::Root module in BioPerl.  Some formatting
has been changed and the deprecate function has been added.  Most
notably the object methods are now static class methods that can be
called without inheriting from Bio::Root or Bio::EnsEMBL::Root.  This is
especially useful for throwing exceptions with stack traces outside of a
blessed context.
The originaly implementations of these methods were by Steve Chervitz
and refactored by Ewan Birney.
It is recommended that these functions be used instead of inheriting
unnecessarily from the Bio::EnsEMBL::Root or Bio::Root object.  The
functions exported by this package provide a set of useful error
handling methods.
 

Definition at line 68 of file Exception.pm.

Available Methods

public catch ()
public void deprecate ()
public void info ()
public Array stack_trace ()
public String stack_trace_dump ()
public void throw ()
public Depend try ()
public Int verbose ()
public void warning ()

Method Documentation

public Bio::EnsEMBL::Utils::Exception::catch ( )

Undocumented method

Code:
click to view
public void Bio::EnsEMBL::Utils::Exception::deprecate ( )
  Arg [1]    : string $mesg
               A message describing why a method is

Deprecated:

Example : use Bio::EnsEMBL::Utils::Exception qw(deprecate) sub old_sub { deprecate('Please use new_sub() instead'); } Description: Prints a warning to STDERR that the method which called deprecate() is

. Also prints the line number and file from which the

method was called. Deprecated warnings only appear once for each location the method was called from. No message is displayed if the level of verbosity is lower than the level of the warning. Returntype : none Exceptions : warning every time Caller :

methods

 
Code:
click to view
public void Bio::EnsEMBL::Utils::Exception::info ( )
  Arg [1]    : string $string
               The message to be displayed
  Arg [2]    : (optional) int $level
               Override the default level of this message so it is displayed at
               a different level of verbosity than it normally would be.
  Example    : use Bio::EnsEMBL::Utils::Exception qw(verbose info)
  Description: This prints an info message to STDERR if verbosity is higher 
               than the level of the message.  By default info messages are not
               displayed.
  Returntype : none
  Exceptions : none
  Caller     : general
 
Code:
click to view
public Array Bio::EnsEMBL::Utils::Exception::stack_trace ( )
  Arg [1]    : none
  Example    : use Bio::EnsEMBL::Utils::Exception qw(stack_trace)
  Description: Gives an array to a reference of arrays with stack trace info
               each coming from the caller(stack_number) call
  Returntype : array of listrefs of strings
  Exceptions : none
  Caller     : general, stack_trace_dump()
 
Code:
click to view
public String Bio::EnsEMBL::Utils::Exception::stack_trace_dump ( )
  Arg [1]    : (optional) int $levels
               The number of levels to ignore from the top of the stack when
               creating the dump. This is useful when this is called internally
               from a warning or throw function when the immediate caller and 
               stack_trace_dump function calls are themselves uninteresting.
  Example    : use Bio::EnsEMBL::Utils::Exception qw(stack_trace_dump);
               print STDERR stack_trace_dump();
  Description: Returns a stack trace formatted as a string
  Returntype : string
  Exceptions : none
  Caller     : general, throw, warning
 
Code:
click to view
public void Bio::EnsEMBL::Utils::Exception::throw ( )
  Arg [1]    : string $msg
  Arg [2]    : (optional) int $level
               override the default level of exception throwing
  Example    : use Bio::EnsEMBL::Utils::Exception qw(throw);
               throw('We have a problem');
  Description: Throws an exception which if not caught by an eval will
               provide a stack trace to STDERR and die.  If the verbosity level
               is lower than the level of the throw, then no error message is
               displayed but the program will still die (unless the exception
               is caught).
  Returntype : none
  Exceptions : thrown every time
  Caller     : generally on error
 
Code:
click to view
public Depend Bio::EnsEMBL::Utils::Exception::try ( )
  Arg [1]    : anonymous subroutine
               the block to be tried
  Arg [2]    : return value of the catch function
  Example    : use Bio::EnsEMBL::Utils::Exception qw(throw try catch)
               The syntax is:
               try { block1 } catch { block2 };
               { block1 } is the 1st argument
               catch { block2 } is the 2nd argument
               e.g.
               try {
                 throw("this is an exception with a stack trace");
               } catch {
                 print "Caught exception:\\n$_";
               };
               In block2, $_ is assigned the value of the first
               throw or die statement executed in block 1.
  Description: Replaces the classical syntax
               eval { block1 };
               if ($@) { block2 }
               by a more confortable one.
               In the try/catch syntax, the original $@ is in $_ in the catch subroutine.
               This try/catch implementation is a copy and paste from
               "Programming Perl" 3rd Edition, July 2000, by L.Wall, T. Christiansen
               & J. Orwant. p227, and is only possible because of subroutine prototypes.
  Returntype : depend on what is implemented the try or catch block
  Exceptions : none
  Caller     : general
 
Code:
click to view
public Int Bio::EnsEMBL::Utils::Exception::verbose ( )
  Arg [1]    : (optional) int 
  Example    : use Bio::EnsEMBL::Utils::Exception qw(verbose warning);
               #turn warnings and everything more important on (e.g. exception)
               verbose('WARNING'); 
               warning("Warning displayed");
               info("This won't be displayed");
               deprecate("This won't be diplayed");
               #turn exception messages on
               verbose('EXCEPTION'); 
               warning("This won't do anything");
               throw("Die with a message");
               #turn everying off
               verbose('OFF'); #same as verbose(0);               
               warning("This won't do anything");
               throw("Die silently without a message");
               #turn on all messages
               verbose('ALL');
               info("All messages are now displayed");
               if(verbose() > 3000) {
                 print "Verbosity is pretty high";
               }
  Description: Gets/Sets verbosity level which defines which messages are
               to be displayed.  An integer value may be passed or one of the
               following strings:
               'OFF'       (= 0)
               'EXCEPTION' (= 1000)
               'WARNING'   (= 2000)
               'DEPRECATE' (= 3000)
               'INFO'      (= 4000)
               'ALL'       (= 1000000)
  Returntype : int 
  Exceptions : none
  Caller     : general
 
Code:
click to view
public void Bio::EnsEMBL::Utils::Exception::warning ( )
  Arg [1]    : string warning(message);
  Arg [2]    : (optional) int level
               Override the default level of this warning changning the level
               of verbosity at which it is displayed.
  Example    : use Bio::EnsEMBL::Utils::Exception qw(warning)
               warning('This is a warning');
  Description: If the verbosity level is higher or equal to the level of this 
               warning then a warning message is printed to STDERR.  If the 
               verbosity lower then nothing is done.  Under the default
               levels of warning and verbosity warnings will be displayed.
  Returntype : none
  Exceptions : warning every time
  Caller     : general
 
Code:
click to view

The documentation for this class was generated from the following file: