Public Member Functions
public void	throw ()

public void	warning ()

public void	info ()

public Int	verbose ()

public String	stack_trace_dump ()

public Array	stack_trace ()

public void	deprecate ()

public Depend	try ()

public	catch ()

Detailed Description

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.  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::Root object.  The
functions exported by this package provide a set of useful error
handling methods.

Definition at line 68 of file Exception.pm.

Member Function Documentation

◆ catch()

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

Undocumented method

Code:

click to view

◆ deprecate()

public void Bio::EnsEMBL::Utils::Exception::deprecate ( )

  Arg [1]    : string $mesg
               A message describing why a method is Deprecated:

  Example    : 
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

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 Deprecated:
.  Also prints the line number and 
               file from which the


 
    Code:

click to view
 

sub deprecate {
  my $mesg = shift;
  $mesg = shift if($mesg eq "Bio::EnsEMBL::Utils::Exception"); #skip object if one provided
 
  my $level = shift;
 
  $level = $DEFAULT_DEPRECATE if(!defined($level));
 
  return if($VERBOSITY < $level);
                                 
  my @caller = caller(1);
  my $subname = $caller[3] ;
  my $line = $caller[2];
 
  #use only 2 subdirs for brevity when reporting the filename
  my $file;
  my @path = $caller[1];
  $file = pop(@path);
  my $i = 0;
  while(@path && $i < 2) {
    $i++;
    $file .= pop(@path);
  }
 
  #keep track of who called this method so that the warning is only displayed
  #once per deprecated call
  return if $DEPRECATED{"$line:$file:$subname"};
 
  if ( $VERBOSITY > -1 ) {
    print STDERR
      "\n------------------ DEPRECATED ---------------------\n"
      . "Deprecated method call in file $file line $line.\n"
      . "Method $subname is deprecated.\n"
      . "$mesg\n"
      . "Ensembl API version = "
      . software_version() . "\n"
      . "---------------------------------------------------\n";
  }
 
  $DEPRECATED{"$line:$file:$subname"} = 1;
}

◆ info()

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

◆ stack_trace()

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

◆ stack_trace_dump()

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

◆ throw()

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

◆ try()

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

◆ verbose()

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);               
<br>
               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

◆ warning()

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:

ensembl/modules/Bio/EnsEMBL/Utils/Exception.pm

Public Member Functions

Detailed Description

Synopsis

Description

Member Function Documentation

◆ catch()

◆ deprecate()

◆ info()

◆ stack_trace()

◆ stack_trace_dump()

◆ throw()

◆ try()

◆ verbose()

◆ warning()