NAME

Exception::SEH - rich try/catch/finally semantics without source filtering

SYNOPSIS

        use Exception::SEH;
        try {
                <...> or die YourException;
        } catch (SomeException $e) {
                <catch code>
        } catch (YourException $e where { $_->param > 10 }) {
                log($e->message);
        } finally {
                <cleanup code>
        }

FEATURES

• Rich catch syntax

• No need for trailing ; after try/catch/finally sequence

• return from try/catch - returns from subroutine, not just try/catch block

• finally called in all cases (even after return)

• @_ available for try block

• Nested try/catch

• Not a source filter (magic for syntax is provided by Devel::Declare)

DESCRIPTION

try BLOCK

Evaluates BLOCK, allowing any exceptions inside it to be caught and processed.

catch BLOCK

catch ([[CLASS] $VAR] [where BLOCK]) BLOCK

Catches and processes (using given BLOCK) exception that (optionally) matches some conditions. Rules to determine catch handler are following:

• Search is performed from beginning to end of 'catches' list

• First matched block is executed and the search is stopped

• If exception is not an object, then any condition with CLASS definition is skipped

• If condition has CLASS, then $@-isa(CLASS)> is checked for true value

• If condition has 'where BLOCK' part, then BLOCK is checked for true result, with $_ assigned to caught exception

• catch BLOCK, catch () BLOCK, catch ($e) BLOCK are all the same and captures all possible exceptions

• If no condition matches throwed exception, then it's re-thrown (after finally is done)

Inside BLOCK after catch exception is available as $@ (always) and also as $VAR (lexical to BLOCK), if it was specified in catch signature.

finally BLOCK

Finally block is always executed after either try or catch. Exception in it is available as $@.

Note: if exception was generated inside a catch handler, than in $@ would be new one, not original from a try block.

Note: exit and unhandled signals leads to immidiate program termination (latter even don't allow global destruction to happen) - in these cases, finally is not called.

return EXPRESSION

return behaviour is modifiyed, so when you call it inside try/catch, it returns not from try block, but from the sub try was inside.

Note: this does not apply to finally block.

Note: if both catch and try uses return, than value from last return is used (but you may ommit return in catch block, then return value is left unchanged).

Note: argument for return is executed in the context of sub above try.

Example:

        sub test{
                try{
                        return map { $_ * 2 } @_;
                }
        }
        $a = test(1, 2, 3);     #$a = 3
        @a = test(1, 2, 3);     #@a = (2, 4, 6)

@_

Inisde try, you have full read/write access to surronding sub's @_.

Note: inside catch/finally, you have only read-only access to @_.

CONFIGURATION

When importing Exception::SEH to your module, you can specify one or more of the following keywords: -nosig -noret -safetry, which change default behaviour in some way. These options are tracked on per-package basis.

        use Exception::SEH -nosig, -safetry;

-nosig

By default, Exception::SEH doesn't play with $SIG{__DIE__}, so your handler is normally called. But if you need to suppress it inside try/catch/finally blocks, you can import -nosig.

Note: if exception is re-thrown after finally block, __DIE__ handler is always suppressed for that moment (so it is called only once for each exception - at first occurence).

-safetry

This options changes behaviour for uncaught exceptions after try block. By default, they're re-thrown, but with this option enabled try blocks are always safe - just like eval.

Note: this doesn't refer to exceptions occured in a catch and finally blocks.

-noret

Tells Exception::SEH not to install return hook. This makes try blocks behave like evals, and context for return is determined by context of try, not by context of sub, containing try.

DIAGNOSTICS

All compile-time discovered errors are raised through Carp::croak with (hopefully) meaningful description.

CAVEATS

Currently, three subroutines - try, catch, finally - are injected into caller's namespace.

Currently, it's impossible to use any other module that hooks OP_RETURN OP on XS level - results are unpredictable. This may be fixed in future releases.

Currently, it's probably unsafe to place try/catch blocks around use/catch. This needs further testing, and may be fixed in future releases.

Currently, due to way caller is detected, if you place try/catch/finally inside eval block, return wouldn't work as expected. This will be fixed in future releases.

SEE ALSO

TryCatch

Similar semantics, but it takes the whole Moose with itself - often too much weight. Currently lacks finally block and @_ access inside try{}. But still, decent choice.

Exception::Class::TryCatch

Ugly syntax. Only Exception::Class-derived exceptions.

Exception::Class::TCF

Better syntax. Lacks exception lexical in try block, returns from try{} block. Still only Exception::Class-derived exceptions.

Error::TryCatch

Source filter. No finally{} call after return() from try.

Error

"Error's syntactic sugar tends to break." (c)

AUTHOR

Sergey Aleynikov <sergey.aleynikov@gmail.com>

LICENSE

Copyright (c) 2009 by Sergey Aleynikov. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Some part for parser are taken from Devel::Declare::Context::Simple, (c) Rhesa Rozendaal (?).

Idea how to set up return hook - TryCatch, (c) Ash Berlin.

cpanm Exception::SEH

perl -MCPAN -e shell
install Exception::SEH