NAME

PException - Exception manager

SYNOPSIS

  use PException;

  try {
                throw( AnException->new() )     if $something;
                throw( AnOtherException->new( [] ) )
                        unless  $anotherthing;
        }
        catch   AnException( sub { } ) ,
        onfly   AnOtherException( sub { } ) ;

DESCRIPTION

Methods & Functions

try: execute code until its end or an exception happens.
throw: throw a list of exceptions.
new: create a new instance of an Exception.
catch: execute an subroutine if this kind of exception is thrown
onfly: execute an subroutine and continue the execution of the last try if this kind of exception is thrown
addFlyingHandler: add a flying exception handler. it allows to continue the try block where the exception appear.

Internal Calls

hadWaittingExceptions: return true if there is waitting exceptions, false elsewhere
newTypedCatching: create an object for catching methods. when a catch happens,
checkException: control if there is some exceptions to catch & treat in an stack
handleException: code for handling a exception. it's an empty sub actually. you overload it if you want a default handler for an exception.
__onflyhandler: the handler which intercept __WARN__ or __DIE__ signal

Internal Mechanism

_XCPHDL_ Structure

        local   %_XCPHDL_       = (
                EXCEPTIONS      => [],
                FLYS            => [],
                STACKFLY        => [],
                ONFLY           => 0,
                FRESH           => 0,
                CANDIE          => 0
                );

EXCEPTIONS: @{$PException::_XCPHDL_->{EXCEPTIONS}} is the stack of thrown exceptions.
FLYS: @{$PException::_XCPHDL_->{FLYS}} is the stack of fly exception handler.
STACKFLY: @{$PException::_XCPHDL_->{STACKFLY}} contain a stack of the list of onfly exception. each list is linked to a nested try.
ONFLY: it's a flag which determine if an handler can die when it throws.
FRESH: is up only when fresh exception are thrown.
CANDIE: is up when a die call must be done.

Try mechanism

a try block is a code block which is evaluated.

when you throw a new set of exception, this set is pushed in @{$PException::_XCPHDL_->{EXCEPTIONS}} , the system call die.

Onfly mechanism

then $SIG{__DIE__} check if any waitting may be catched, when it finish and there is waitting exception yet, it die, else it continues the try block ; it's the onfly exception handling.

Catch mechanism

the catching part is the same thing than upside, but you can't continue the execution of the try block.

BUGS

Don't try to change $SIG{__WARN__} and $SIG{__DIE__} inside a try block.

TO DO

Better documentation
Add the waitting exception capacity ( aka warning exceptions which are thrown when others exceptions are thrown )
Overload CORE::warn & CORE::die by other function which don't interact with the engine
Add a ``transaction'' try ( aka try blocks wich are executed totaly or not ) if it's possible
Add other tests ...

COPYRIGHT, LICENCE

 Copyright (c) 1998-2003 Samuel    MOUNIEE

This file is part of PException.

PException is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

PException is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with PException; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

AUTHOR

Samuel Mouniée <mouns@mouns.net>

PException - Exception manager