NAME Exception::SEH - rich try/catch/finally semantics without source filtering SYNOPSIS use Exception::SEH; try { <...> or die YourException; } catch (SomeException $e) { } catch (YourException $e where { $_->param > 10 }) { log($e->message); } finally { } 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 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.