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

      # 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;
        # $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->with(value=>9)) { warn "something happened"; }
        elsif ($e->with(qr/^Error/)) { warn "some error based on regex"; }
        else { $e->throw; } # rethrow the exception
      }

      # try/catch (15x slower method)
      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->with(value=>9)) { warn "something happened"; }
        elsif ($e->with(qr/^Error/)) { warn "some error based on regex"; }
        else { $e->throw; } # rethrow the exception
      }

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

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

      # try with array context
      @v = try [eval { do_something_returning_array(); }];

      # catch only IO errors, rethrow immediately others
      try eval { File::Stat::Moose->stat("/etc/passwd") };
      catch my $e, ['Exception::IO'];

      # immediately rethrow all caught exceptions and eval errors
      try eval { die "Bang!\n" };
      catch my $e, [];

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

      # 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 does not depend on other
    modules like Exception::Class and it is more powerful than
    Class::Throwable. Also it does not use closures as Error and does not
    polute namespace as Exception::Class::TryCatch. It is also much faster
    than Exception::Class and Error.

    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 <dexter@debian.org>

LICENSE
    Copyright (C) 2007, 2008 by Piotr Roszatycki <dexter@debian.org>.

    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