NAME
    Exception::Base - Lightweight exceptions

SYNOPSIS
      # Use module and create needed exceptions
      use Exception::Base (
        ':all',                            # import try/catch/throw
        'Exception::Runtime',              # create new module
        'Exception::System',               # load existing module
        'Exception::IO',          => {
            isa => 'Exception::System' },  # create new based on existing
        'Exception::FileNotFound' => {
            message => 'File not found',
            isa => 'Exception::IO' },      # create new based on new
      );

      # try / catch
      try eval {
        do_something() or throw 'Exception::FileNotFound' =>
                                message=>'Something wrong',
                                tag=>'something';
      };
      # Catch the Exception::Base and derived, rethrow immediately others
      if (catch my $e) {
        # $e is an exception object for sure, 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(tag=>'something')) { warn "something happened"; }
        elsif ($e->with(qr/^Error/)) { warn "some error based on regex"; }
        else { $e->throw; } # rethrow the exception
      }

      # the exception can be thrown later
      $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, [];

      # don't use syntactic sugar
      use Exception::Base;          # does not import ':all' tag
      Exception::Base->try(eval {
        Exception::IO->throw;
      });
      Exception::Base->catch(my $e);  # catch Exception::Base and derived
      # or
      Exception::IO->catch(my $e);    # catch IO errors and rethrow others

      # run Perl with changed verbosity
      sh$ 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.

    The features of Exception::Base:

    * fast implementation of an exception object

    * 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

    * the exception can be created with defined custom properties

    * matching the exception by class, message or custom properties

    * matching with string, regex or closure function

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

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

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