NAME
   Exception::Base - Lightweight exceptions

SYNOPSIS
     # Use module and create needed exceptions
     use Exception::Base
        'Exception::Runtime',              # create new module
        'Exception::System',               # load existing module
        'Exception::IO',          => {
            isa => 'Exception::System' },  # create new based on existing
        'Exception::FileNotFound' => {
            isa => 'Exception::IO',        # create new based on previous
            message => 'File not found',   # override default message
            has => [ 'filename' ],         # define new rw attribute
            stringify_attributes => [ 'message', 'filename' ],
        };                                 # output message and filename

     # eval/$@ (fastest method)
     eval {
       open my $file, '/etc/passwd'
         or Exception::FileNotFound->throw(
               message=>'Something wrong',
               filename=>'/etc/passwd');
     };
     if ($@) {
       my $e = Exception::Base->catch;   # convert $@ into exception
       if ($e->isa('Exception::IO')) { warn "IO problem"; }
       elsif ($e->isa('Exception::Eval')) { warn "eval died"; }
       elsif ($e->isa('Exception::Runtime')) { warn "some runtime was caught"; }
       elsif ($e->matches({value=>9})) { warn "something happened"; }
       elsif ($e->matches(qr/^Error/)) { warn "some error based on regex"; }
       else { $e->throw; } # rethrow the exception
     }
     # alternative syntax for Perl 5.10
     use feature 'switch';
     if ($@) {
       given (my $e = Exception::Base->catch) {
         when (['Exception::IO']) { warn "IO problem"; }
         when (['Exception::Eval']) { warn "eval died"; }
         when (['Exception::Runtime']) { warn "some runtime was caught"; }
         when ({value=>9}) { warn "something happened"; }
         when (qr/^Error/) { warn "some error based on regex"; }
         default { $e->throw; } # rethrow the exception
       }
     }

     # try/catch (15x slower)
     use Exception::Base ':all';   # import try/catch/throw
     try eval {
       open my $file, '/etc/passwd'
         or throw 'Exception::FileNotFound' =>
                       message=>'Something wrong',
                       filename=>'/etc/passwd';
     };
     if (catch my $e) {
       # $e is an exception object so no need to check if is blessed
       if ($e->isa('Exception::IO')) { warn "IO problem"; }
       elsif ($e->isa('Exception::Eval')) { warn "eval died"; }
       elsif ($e->isa('Exception::Runtime')) { warn "some runtime was caught"; }
       elsif ($e->matches({value=>9})) { warn "something happened"; }
       elsif ($e->matches(qr/^Error/)) { warn "some error based on regex"; }
       else { $e->throw; } # rethrow the exception
     }

     # $@ has to be recovered ASAP!
     eval { die "this die will be caught" };
     my $e = Exception::Base->catch;
     eval { die "this die will be ignored" };
     if ($e) {
        (...)
     }

     # try/catch can be separated with another eval
     try eval { die "this die will be caught" };
     do { eval { die "this die will be ignored" } };
     catch my $e;   # only first die is recovered

     # the exception can be thrown later
     my $e = Exception::Base->new;
     # (...)
     $e->throw;

     # try returns eval's value for scalar or array context
     $v = try eval { do_something_returning_scalar(); };
     @v = try [eval { do_something_returning_array(); }];

     # ignore our package in stack trace
     package My::Package;
     use Exception::Base '+ignore_package' => __PACKAGE__;

     # define new exception in separate module
     package Exception::My;
     use Exception::Base (__PACKAGE__) => {
         has => ['myattr'],
     };

     # run Perl with changed verbosity for debugging purposes
     $ perl -MException::Base=verbosity,4 script.pl

DESCRIPTION
   This class implements a fully OO exception mechanism similar to
   Exception::Class or Class::Throwable. It provides a simple interface
   allowing programmers to declare exception classes. These classes can be
   thrown and caught. Each uncaught exception prints full stack trace if
   the default verbosity is uppered for debugging purposes.

   The features of Exception::Base:

   * fast implementation of the exception class

   * fully OO without closures and source code filtering

   * does not mess with $SIG{__DIE__} and $SIG{__WARN__}

   * no external modules dependencies, requires core Perl modules only

   * implements error stack, the try/catch blocks can be nested

   * the default behaviour of exception class can be changed globally or
     just for the thrown exception

   * matching the exception by class, message or other attributes

   * matching with string, regex or closure function

   * creating automatically the derived exception classes ("use" interface)

   * easly expendable, see Exception::System class for example

   * prints just an error message or dumps full stack trace

   * can propagate (rethrow) an exception

AUTHOR
   Piotr Roszatycki <[email protected]>

LICENSE
   Copyright (C) 2007, 2008 by Piotr Roszatycki <[email protected]>.

   This program is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself.

   See http://www.perl.com/perl/misc/Artistic.html

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.