.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Try::Tiny::SmartCatch 3pm"
.TH Try::Tiny::SmartCatch 3pm "2013-01-03" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Try::Tiny::SmartCatch \- lightweight Perl module for powerful exceptions handling
.SH "VERSION"
.IX Header "VERSION"
Version 0.5
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Try::Tiny::SmartCatch;
\&
\&    try sub {}, # at least one try block
\&    catch_when \*(AqExceptionName\*(Aq => sub {}, # zero or more catch_when blocks
\&    catch_when \*(Aqexception message\*(Aq => 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(\*(Aqsome exception\*(Aq);
\&    throw(SomeException\->new (\*(Aqmessage\*(Aq));
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
When raised exception is an object, Try::Tiny::SmartCatch will test for
exception type (using \f(CW\*(C`UNIVERSAL::isa\*(C'\fR). When raised exception is just
a text message (like: \f(CW\*(C`die (\*(Aqmessage\*(Aq)\*(C'\fR), there can be specified part of
message to test for.
.PP
There are also explicit \f(CW\*(C`sub\*(C'\fR blocks. In opposite to \f(CW\*(C`Try::Tiny\*(C'\fR,
every block in \f(CW\*(C`Try::Tiny::SmartCatch\*(C'\fR: \f(CW\*(C`try\*(C'\fR, \f(CW\*(C`catch_when\*(C'\fR, \f(CW\*(C`catch_default\*(C'\fR,
\&\f(CW\*(C`then\*(C'\fR and \f(CW\*(C`finally\*(C'\fR must have explicit subroutines specified. Thanks to trick
with function prototype, calling \f(CW\*(C`Try::Tiny::try\*(C'\fR or \f(CW\*(C`Try::Tiny::catch\*(C'\fR
creates implicit subroutines:
.PP
.Vb 7
\&    sub test_function {
\&        try {
\&            # yes, here is implicit subroutine!
\&            # return statement here exits just from try block,
\&            # not from test_function!
\&            return 1;
\&        };
\&    
\&        say \*(AqHello!\*(Aq;
\&    }
\&    
\&    test_function();
.Ve
.PP
Above snippet produces us text on \s-1STDOUT: \s0\f(CW\*(C`Hello!\*(C'\fR
.PP
But more obvious would be no output... (by \f(CW\*(C`return\*(C'\fR statement). This is because of
implicit subroutine created with braces: \f(CW\*(C`{}\*(C'\fR after \f(CW\*(C`try\*(C'\fR,
 \f(CW\*(C`catch\*(C'\fR or \f(CW\*(C`finally\*(C'\fR from \f(CW\*(C`Try::Tiny\*(C'\fR. \f(CW\*(C`Try::Tiny::SmartCatch\*(C'\fR is
more explicit \- you must always use \f(CW\*(C`sub\*(C'\fR when defining blocks (look
at [Syntax](#Syntax) above).
.PP
An exception object or message is passed to defined blocks in two ways:
* in \f(CW$_\fR variable
* as function arguments, so through \f(CW@_\fR array.
.PP
Try::Tiny::SmartCatch defines also \f(CW\*(C`throw\*(C'\fR function (not imported
by default). Currently it is an alias for \f(CW\*(C`die\*(C'\fR, but is more explicit then \f(CW\*(C`die\*(C'\fR :)
.PP
It can be imported separately:
.PP
.Vb 1
\&    use Try::Tiny::SmartCatch qw/throw/;
.Ve
.PP
Or with rest of functions:
.PP
.Vb 1
\&    use Try::Tiny::SmartCatch qw/:all/;
.Ve
.SH "EXPORT"
.IX Header "EXPORT"
By default exported are functions:
.IP "try" 4
.IX Item "try"
.PD 0
.IP "catch_when" 4
.IX Item "catch_when"
.IP "catch_default" 4
.IX Item "catch_default"
.IP "then" 4
.IX Item "then"
.IP "finally" 4
.IX Item "finally"
.PD
.PP
You can also explicit import \f(CW\*(C`throw\*(C'\fR function:
.PP
.Vb 1
\&    use Try::Tiny::SmartCatch qw/throw/;
.Ve
.PP
Or all functions at all:
.PP
.Vb 1
\&    use Try::Tiny::SmartCatch qw/:all/;
.Ve
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "try($;@)"
.IX Subsection "try($;@)"
Works like Try::Tiny \f(CW\*(C`try\*(C'\fR subroutine, here is nothing to add :)
.PP
The only difference is that here must be given evident sub reference, not anonymous block:
.PP
.Vb 3
\&    try sub {
\&        # some code
\&    };
.Ve
.SS "catch_when($$;@)"
.IX Subsection "catch_when($$;@)"
Intended to be used in the second argument position of \f(CW\*(C`try\*(C'\fR.
.PP
Works similarly to Try::Tiny \f(CW\*(C`catch\*(C'\fR subroutine, but have a little different syntax:
.PP
.Vb 9
\&    try sub {
\&        # some code
\&    },
\&    catch_when \*(AqException1\*(Aq => sub {
\&        # catch only Exception1 exception
\&    },
\&    catch_when [\*(AqException1\*(Aq, \*(AqException2\*(Aq] => sub {
\&        # catch Exception2 or Exception3 exceptions
\&    };
.Ve
.PP
If raised exception is a blessed reference (or object), \f(CW\*(C`Exception1\*(C'\fR means that exception
class has to be or inherits from \f(CW\*(C`Exception1\*(C'\fR class. In other case, it search for given
string in exception message (using \f(CW\*(C`index\*(C'\fR function or regular expressions \- depending on
type of given operator). For example:
.PP
.Vb 6
\&    try sub {
\&        throw(\*(Aqsome exception message\*(Aq);
\&    },
\&    catch_when \*(Aqexception\*(Aq => sub {
\&        say \*(Aqexception caught!\*(Aq;
\&    };
.Ve
.PP
Other case:
.PP
.Vb 6
\&    try sub {
\&        throw(\*(Aqsome exception3 message\*(Aq);
\&    },
\&    catch_when qr/exception\ed/ => sub {
\&        say \*(Aqexception caught!\*(Aq;
\&    };
.Ve
.PP
Or:
.PP
.Vb 7
\&    try sub {
\&        # ValueError extends RuntimeError
\&        throw(ValueError\->new (\*(AqSome error message\*(Aq));
\&    },
\&    catch_when \*(AqRuntimeError\*(Aq => sub {
\&        say \*(AqRuntimeError exception caught!\*(Aq;
\&    };
.Ve
.SS "catch_default($;@)"
.IX Subsection "catch_default($;@)"
Works exactly like Try::Tiny \f(CW\*(C`catch\*(C'\fR function (\s-1OK,\s0 there is difference:
need to specify evident sub block instead of anonymous block):
.PP
.Vb 6
\&    try sub {
\&        # some code
\&    },
\&    catch_default sub {
\&        say \*(Aqcaught every exception\*(Aq;
\&    };
.Ve
.SS "then($;@)"
.IX Subsection "then($;@)"
\&\f(CW\*(C`then\*(C'\fR block is executed after \f(CW\*(C`try\*(C'\fR clause, if none of \f(CW\*(C`catch_when\*(C'\fR or
\&\f(CW\*(C`catch_default\*(C'\fR blocks was executed (it means, if no exception occured).
It's executed before \f(CW\*(C`finally\*(C'\fR blocks.
.PP
.Vb 12
\&    try sub {
\&        # some code
\&    },
\&    catch_when \*(AqMyException\*(Aq => sub {
\&        say \*(Aqcaught MyException exception\*(Aq;
\&    },
\&    then sub {
\&        say \*(AqNo exception was raised\*(Aq;
\&    },
\&    finally sub {
\&        say \*(Aqexecuted always\*(Aq;
\&    };
.Ve
.SS "finally($;@)"
.IX Subsection "finally($;@)"
Works exactly like Try::Tiny \f(CW\*(C`finally\*(C'\fR function (\s-1OK,\s0 again, explicit sub
instead of implicit):
.PP
.Vb 6
\&    try sub {
\&        # some code
\&    },
\&    finally sub {
\&        say \*(Aqexecuted always\*(Aq;
\&    };
.Ve
.SS "throw"
.IX Subsection "throw"
Currently it's an alias to \f(CW\*(C`die\*(C'\fR function, but \f(CW\*(C`throw\*(C'\fR is more obvious then \f(CW\*(C`die\*(C'\fR when working with exceptions :)
.PP
In future it also can do more then just call \f(CW\*(C`die\*(C'\fR.
.PP
It's not exported by default (see: \*(L"\s-1EXPORT\*(R"\s0)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "<https://github.com/mysz/try\-tiny\-smartcatch>" 4
.IX Item "<https://github.com/mysz/try-tiny-smartcatch>"
Try::Tiny::SmartCatch home.
.IP "Try::Tiny" 4
.IX Item "Try::Tiny"
Minimal try/catch with proper localization of $@, base of Try::Tiny::SmartCatch
.IP "TryCatch" 4
.IX Item "TryCatch"
First class try catch semantics for Perl, without source filters.
.SH "AUTHOR"
.IX Header "AUTHOR"
Marcin Sztolcman, \f(CW\*(C`<marcin at urzenia.net>\*(C'\fR
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests through the web interface at
<http://github.com/mysz/try\-tiny\-smartcatch/issues>.
.SH "SUPPORT"
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&    perldoc Try::Tiny::SmartCatch
.Ve
.PP
You can also look for information at:
.IP "\(bu" 4
Try::Tiny::SmartCatch home & source code
.Sp
<http://github.com/mysz/try\-tiny\-smartcatch>
.IP "\(bu" 4
Issue tracker (report bugs here)
.Sp
<http://github.com/mysz/try\-tiny\-smartcatch/issues>
.IP "\(bu" 4
Search \s-1CPAN\s0
.Sp
<http://search.cpan.org/dist/Try\-Tiny\-SmartCatch/>
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
.IP "Yuval Kogman" 4
.IX Item "Yuval Kogman"
for his Try::Tiny module
.IP "mst \- Matt S Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>" 4
.IX Item "mst - Matt S Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>"
for good package name and few great features
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
.Vb 1
\&    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.
.Ve