local-lib5/man/man3/Try::Tiny.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Try::Tiny 3"
 132 .TH Try::Tiny 3 "2009-09-02" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Try::Tiny \- minimal try/catch with proper localization of $@
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 6
 138 \&        # handle errors with a catch handler
 139 \&        try {
 140 \&                die "foo";
 141 \&        } catch {
 142 \&                warn "caught error: $_";
 143 \&        };
 144 .Ve
 145 .PP
 146 .Vb 4
 147 \&        # just silence errors
 148 \&        try {
 149 \&                die "foo";
 150 \&        };
 151 .Ve
 152 .SH "DESCRIPTION"
 153 .IX Header "DESCRIPTION"
 154 This module provides bare bones \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`catch\*(C'\fR statements that are designed to
 155 minimize common mistakes with eval blocks, and \s-1NOTHING\s0 else.
 156 .PP
 157 This is unlike TryCatch which provides a nice syntax and avoids adding
 158 another call stack layer, and supports calling \f(CW\*(C`return\*(C'\fR from the try block to
 159 return from the parent subroutine. These extra features come at a cost of a few
 160 dependencies, namely Devel::Declare and Scope::Upper which are
 161 occasionally problematic, and the additional catch filtering uses Moose
 162 type constraints which may not be desirable either.
 163 .PP
 164 The main focus of this module is to provide simple and reliable error handling
 165 for those having a hard time installing TryCatch, but who still want to
 166 write correct \f(CW\*(C`eval\*(C'\fR blocks without 5 lines of boilerplate each time.
 167 .PP
 168 It's designed to work as correctly as possible in light of the various
 169 pathological edge cases (see \s-1BACKGROUND\s0) and to be compatible with any style
 170 of error values (simple strings, references, objects, overloaded objects, etc).
 171 .SH "EXPORTS"
 172 .IX Header "EXPORTS"
 173 All functions are exported by default using Exporter.
 174 .PP
 175 In the future Sub::Exporter may be used to allow the keywords to be renamed,
 176 but this technically does not satisfy Adam Kennedy's definition of \*(L"Tiny\*(R".
 177 .IP "try (&;$)" 4
 178 .IX Item "try (&;$)"
 179 Takes one mandatory try subroutine and one optional catch subroutine.
 180 .Sp
 181 The mandatory subroutine is evaluated in the context of an \f(CW\*(C`eval\*(C'\fR block.
 182 .Sp
 183 If no error occurred the value from the first block is returned, preserving
 184 list/scalar context.
 185 .Sp
 186 If there was an error and the second subroutine was given it will be invoked
 187 with the error in \f(CW$_\fR (localized) and as that block's first and only
 188 argument.
 189 .Sp
 190 Note that the error may be false, but if that happens the \f(CW\*(C`catch\*(C'\fR block will
 191 still be invoked..
 192 .IP "catch (&)" 4
 193 .IX Item "catch (&)"
 194 Intended to be used in the second argument position of \f(CW\*(C`try\*(C'\fR.
 195 .Sp
 196 Just returns the subroutine it was given.
 197 .Sp
 198 .Vb 1
 199 \&        catch { ... }
 200 .Ve
 201 .Sp
 202 is the same as
 203 .Sp
 204 .Vb 1
 205 \&        sub { ... }
 206 .Ve
 207 .SH "BACKGROUND"
 208 .IX Header "BACKGROUND"
 209 There are a number of issues with \f(CW\*(C`eval\*(C'\fR.
 210 .Sh "Clobbering $@"
 211 .IX Subsection "Clobbering $@"
 212 When you run an eval block and it succeeds, \f(CW$@\fR will be cleared, potentially
 213 clobbering an error that is currently being caught.
 214 .PP
 215 This causes action at a distance, clearing previous errors your caller may have
 216 not yet handled.
 217 .PP
 218 \&\f(CW$@\fR must be properly localized before invoking \f(CW\*(C`eval\*(C'\fR in order to avoid this
 219 issue.
 220 .Sh "Localizing $@ silently masks errors"
 221 .IX Subsection "Localizing $@ silently masks errors"
 222 Inside an eval block \f(CW\*(C`die\*(C'\fR behaves sort of like:
 223 .PP
 224 .Vb 4
 225 \&        sub die {
 226 \&                $@_ = $_[0];
 227 \&                return_undef_from_eval();
 228 \&        }
 229 .Ve
 230 .PP
 231 This means that if you were polite and localized \f(CW$@\fR you can't die in that
 232 scope, or your error will be discarded (printing \*(L"Something's wrong\*(R" instead).
 233 .PP
 234 The workaround is very ugly:
 235 .PP
 236 .Vb 5
 237 \&        my $error = do {
 238 \&                local $@;
 239 \&                eval { ... };
 240 \&                $@;
 241 \&        };
 242 .Ve
 243 .PP
 244 .Vb 2
 245 \&        ...
 246 \&        die $error;
 247 .Ve
 248 .Sh "$@ might not be a true value"
 249 .IX Subsection "$@ might not be a true value"
 250 This code is wrong:
 251 .PP
 252 .Vb 3
 253 \&        if ( $@ ) {
 254 \&                ...
 255 \&        }
 256 .Ve
 257 .PP
 258 because due to the previous caveats it may have been unset.
 259 .PP
 260 \&\f(CW$@\fR could also an overloaded error object that evaluates to false, but that's
 261 asking for trouble anyway.
 262 .PP
 263 The classic failure mode is:
 264 .PP
 265 .Vb 3
 266 \&        sub Object::DESTROY {
 267 \&                eval { ... }
 268 \&        }
 269 .Ve
 270 .PP
 271 .Vb 2
 272 \&        eval {
 273 \&                my $obj = Object\->new;
 274 .Ve
 275 .PP
 276 .Vb 2
 277 \&                die "foo";
 278 \&        };
 279 .Ve
 280 .PP
 281 .Vb 1
 282 \&        if ( $@ ) {
 283 .Ve
 284 .PP
 285 .Vb 1
 286 \&        }
 287 .Ve
 288 .PP
 289 In this case since \f(CW\*(C`Object::DESTROY\*(C'\fR is not localizing \f(CW$@\fR but still uses
 290 \&\f(CW\*(C`eval\*(C'\fR it will set \f(CW$@\fR to \f(CW""\fR.
 291 .PP
 292 The destructor is called when the stack is unwound, after \f(CW\*(C`die\*(C'\fR sets \f(CW$@\fR to
 293 \&\f(CW"foo at Foo.pm line 42\en"\fR, so by the time \f(CW\*(C`if ( $@ )\*(C'\fR is evaluated it has
 294 been cleared by \f(CW\*(C`eval\*(C'\fR in the destructor.
 295 .PP
 296 The workaround for this is even uglier than the previous ones. Even though we
 297 can't save the value of \f(CW$@\fR from code that doesn't localize, we can at least
 298 be sure the eval was aborted due to an error:
 299 .PP
 300 .Vb 2
 301 \&        my $failed = not eval {
 302 \&                ...
 303 .Ve
 304 .PP
 305 .Vb 2
 306 \&                return 1;
 307 \&        };
 308 .Ve
 309 .PP
 310 This is because an \f(CW\*(C`eval\*(C'\fR that caught a \f(CW\*(C`die\*(C'\fR will always return a false
 311 value.
 312 .SH "SHINY SYNTAX"
 313 .IX Header "SHINY SYNTAX"
 314 Using Perl 5.10 you can use \*(L"Switch statements\*(R" in perlsyn.
 315 .PP
 316 The \f(CW\*(C`catch\*(C'\fR block is invoked in a topicalizer context (like a \f(CW\*(C`given\*(C'\fR block),
 317 but note that you can't return a useful value from \f(CW\*(C`catch\*(C'\fR using the \f(CW\*(C`when\*(C'\fR
 318 blocks without an explicit \f(CW\*(C`return\*(C'\fR.
 319 .PP
 320 This is somewhat similar to Perl 6's \f(CW\*(C`CATCH\*(C'\fR blocks. You can use it to
 321 concisely match errors:
 322 .PP
 323 .Vb 6
 324 \&        try {
 325 \&                require Foo;
 326 \&        } catch {
 327 \&                when (/^Can't locate .*?\e.pm in \e@INC/) { } # ignore
 328 \&                default { die $_ }
 329 \&        };
 330 .Ve
 331 .SH "CAVEATS"
 332 .IX Header "CAVEATS"
 333 .IP "\(bu" 4
 334 \&\f(CW\*(C`try\*(C'\fR introduces another caller stack frame. Sub::Uplevel is not used. Carp
 335 will report this when using full stack traces. This lack of magic is considered
 336 a feature.
 337 .IP "\(bu" 4
 338 The value of \f(CW$_\fR in the \f(CW\*(C`catch\*(C'\fR block is not guaranteed to be preserved,
 339 there is no safe way to ensure this if \f(CW\*(C`eval\*(C'\fR is used unhygenically in
 340 destructors. It's only guaranteeed that the \f(CW\*(C`catch\*(C'\fR will be called.
 341 .SH "SEE ALSO"
 342 .IX Header "SEE ALSO"
 343 .IP "TryCatch" 4
 344 .IX Item "TryCatch"
 345 Much more feature complete, more convenient semantics, but at the cost of
 346 implementation complexity.
 347 .IP "autodie" 4
 348 .IX Item "autodie"
 349 Automatic error throwing for builtin functions and more. Also designed to
 350 work well with \f(CW\*(C`given\*(C'\fR/\f(CW\*(C`when\*(C'\fR.
 351 .IP "Throwable" 4
 352 .IX Item "Throwable"
 353 A lightweight role for rolling your own exception classes.
 354 .IP "Error" 4
 355 .IX Item "Error"
 356 Exception object implementation with a \f(CW\*(C`try\*(C'\fR statement. Does not localize
 357 \&\f(CW$@\fR.
 358 .IP "Exception::Class::TryCatch" 4
 359 .IX Item "Exception::Class::TryCatch"
 360 Provides a \f(CW\*(C`catch\*(C'\fR statement, but properly calling \f(CW\*(C`eval\*(C'\fR is your
 361 responsibility.
 362 .Sp
 363 The \f(CW\*(C`try\*(C'\fR keyword pushes \f(CW$@\fR onto an error stack, avoiding some of the
 364 issues with \f(CW$@\fR but you still need to localize to prevent clobbering.
 365 .SH "VERSION CONTROL"
 366 .IX Header "VERSION CONTROL"
 367 <http://github.com/nothingmuch/try\-tiny/>
 368 .SH "AUTHOR"
 369 .IX Header "AUTHOR"
 370 Yuval Kogman <nothingmuch@woobling.org>
 371 .SH "COPYRIGHT"
 372 .IX Header "COPYRIGHT"
 373 .Vb 3
 374 \&        Copyright (c) 2009 Yuval Kogman. All rights reserved.
 375 \&        This program is free software; you can redistribute
 376 \&        it and/or modify it under the terms of the MIT license.
 377 .Ve