NAME

       Try::Tiny::SmartCatch - lightweight Perl module for powerful exceptions handling

VERSION

       Version 0.5

SYNOPSIS

           use Try::Tiny::SmartCatch;

           try sub {}, # at least one try block
           catch_when 'ExceptionName' => sub {}, # zero or more catch_when blocks
           catch_when 'exception message' => sub {},
           catch_when qr/exception  message regexp/ => sub {},
           catch_default sub {}, # zero or one catch_default block
           then sub {}, # if no exception is raised, execute then block
           finally sub {}; #zero or more finally blocks

           use Try::Tiny::SmartCatch qw/throw/; # import only throw
           # You can import also all function at once:
           # use Try::Tiny::SmartCatch qw/:all/;
           throw('some exception');
           throw(SomeException->new ('message'));

DESCRIPTION

       Goals are mostly the same as Try::Tiny module, but there are few changes to it's specification. Main
       difference is possibility to catch just some kinds of exceptions in place of catching everything. Another
       one is slightly changed syntax.

       When raised exception is an object, Try::Tiny::SmartCatch will test for exception type (using
       "UNIVERSAL::isa"). When raised exception is just a text message (like: "die ('message')"), there can be
       specified part of message to test for.

       There are also explicit "sub" blocks. In opposite to "Try::Tiny", every block in "Try::Tiny::SmartCatch":
       "try", "catch_when", "catch_default", "then" and "finally" must have explicit subroutines specified.
       Thanks to trick with function prototype, calling "Try::Tiny::try" or "Try::Tiny::catch" creates implicit
       subroutines:

           sub test_function {
               try {
                   # yes, here is implicit subroutine!
                   # return statement here exits just from try block,
                   # not from test_function!
                   return 1;
               };

               say 'Hello!';
           }

           test_function();

       Above snippet produces us text on STDOUT: "Hello!"

       But more obvious would be no output... (by "return" statement). This is because of implicit subroutine
       created with braces: "{}" after "try",
        "catch" or "finally" from "Try::Tiny". "Try::Tiny::SmartCatch" is more explicit - you must always use
       "sub" when defining blocks (look at [Syntax](#Syntax) above).

       An exception object or message is passed to defined blocks in two ways: * in $_ variable * as function
       arguments, so through @_ array.

       Try::Tiny::SmartCatch defines also "throw" function (not imported by default). Currently it is an alias
       for "die", but is more explicit then "die" :)

       It can be imported separately:

           use Try::Tiny::SmartCatch qw/throw/;

       Or with rest of functions:

           use Try::Tiny::SmartCatch qw/:all/;

EXPORT

       By default exported are functions:

       try
       catch_when
       catch_default
       then
       finally

       You can also explicit import "throw" function:

           use Try::Tiny::SmartCatch qw/throw/;

       Or all functions at all:

           use Try::Tiny::SmartCatch qw/:all/;

SUBROUTINES/METHODS

   try($;@)
       Works like Try::Tiny "try" subroutine, here is nothing to add :)

       The only difference is that here must be given evident sub reference, not anonymous block:

           try sub {
               # some code
           };

   catch_when($$;@)
       Intended to be used in the second argument position of "try".

       Works similarly to Try::Tiny "catch" subroutine, but have a little different syntax:

           try sub {
               # some code
           },
           catch_when 'Exception1' => sub {
               # catch only Exception1 exception
           },
           catch_when ['Exception1', 'Exception2'] => sub {
               # catch Exception2 or Exception3 exceptions
           };

       If raised exception is a blessed reference (or object), "Exception1" means that exception class has to be
       or  inherits  from  "Exception1"  class.  In  other case, it search for given string in exception message
       (using "index" function or regular expressions - depending on type of given operator). For example:

           try sub {
               throw('some exception message');
           },
           catch_when 'exception' => sub {
               say 'exception caught!';
           };

       Other case:

           try sub {
               throw('some exception3 message');
           },
           catch_when qr/exception\d/ => sub {
               say 'exception caught!';
           };

       Or:

           try sub {
               # ValueError extends RuntimeError
               throw(ValueError->new ('Some error message'));
           },
           catch_when 'RuntimeError' => sub {
               say 'RuntimeError exception caught!';
           };

   catch_default($;@)
       Works exactly like Try::Tiny "catch" function (OK, there is difference: need to specify evident sub block
       instead of anonymous block):

           try sub {
               # some code
           },
           catch_default sub {
               say 'caught every exception';
           };

   then($;@)
       "then" block is executed after "try" clause, if  none  of  "catch_when"  or  "catch_default"  blocks  was
       executed (it means, if no exception occured).  It's executed before "finally" blocks.

           try sub {
               # some code
           },
           catch_when 'MyException' => sub {
               say 'caught MyException exception';
           },
           then sub {
               say 'No exception was raised';
           },
           finally sub {
               say 'executed always';
           };

   finally($;@)
       Works exactly like Try::Tiny "finally" function (OK, again, explicit sub instead of implicit):

           try sub {
               # some code
           },
           finally sub {
               say 'executed always';
           };

   throw
       Currently  it's  an  alias  to  "die"  function, but "throw" is more obvious then "die" when working with
       exceptions :)

       In future it also can do more then just call "die".

       It's not exported by default (see: "EXPORT")

SEE ALSO

       <https://github.com/mysz/try-tiny-smartcatch>
           Try::Tiny::SmartCatch home.

       Try::Tiny
           Minimal try/catch with proper localization of $@, base of Try::Tiny::SmartCatch

       TryCatch
           First class try catch semantics for Perl, without source filters.

AUTHOR

       Marcin Sztolcman, "<marcin at urzenia.net>"

BUGS

       Please    report    any    bugs    or    feature    requests    through    the    web    interface     at
       <http://github.com/mysz/try-tiny-smartcatch/issues>.

SUPPORT

       You can find documentation for this module with the perldoc command.

           perldoc Try::Tiny::SmartCatch

       You can also look for information at:

       •   Try::Tiny::SmartCatch home & source code

           <http://github.com/mysz/try-tiny-smartcatch>

       •   Issue tracker (report bugs here)

           <http://github.com/mysz/try-tiny-smartcatch/issues>

       •   Search CPAN

           <http://search.cpan.org/dist/Try-Tiny-SmartCatch/>

ACKNOWLEDGEMENTS

       Yuval Kogman
           for his Try::Tiny module

       mst - Matt S Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
           for good package name and few great features

LICENSE AND COPYRIGHT

           Copyright (c) 2012-2013 Marcin Sztolcman. All rights reserved.

           Base code is borrowed from Yuval Kogman L<Try::Tiny> module,
           released under MIT License.

           This program is free software; you can redistribute
           it and/or modify it under the terms of the MIT license.

perl v5.20.1                                       2013-01-03                         Try::Tiny::SmartCatch(3pm)