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 sub {
        # some code
    };

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

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

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

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

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

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

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

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.