clarify docs re switch statements, given
[p5sagit/Try-Tiny.git] / README.pod
CommitLineData
cb57845a 1=pod
2
3=encoding UTF-8
4
5=head1 NAME
6
fae6bce6 7Try::Tiny - Minimal try/catch with proper preservation of $@
cb57845a 8
9=head1 VERSION
10
fae6bce6 11version 0.28
cb57845a 12
13=head1 SYNOPSIS
14
15You can use Try::Tiny's C<try> and C<catch> to expect and handle exceptional
16conditions, avoiding quirks in Perl and common mistakes:
17
18 # handle errors with a catch handler
19 try {
20 die "foo";
21 } catch {
22 warn "caught error: $_"; # not $@
23 };
24
25You can also use it like a standalone C<eval> to catch and ignore any error
26conditions. Obviously, this is an extreme measure not to be undertaken
27lightly:
28
29 # just silence errors
30 try {
31 die "foo";
32 };
33
34=head1 DESCRIPTION
35
36This module provides bare bones C<try>/C<catch>/C<finally> statements that are designed to
37minimize common mistakes with eval blocks, and NOTHING else.
38
39This is unlike L<TryCatch> which provides a nice syntax and avoids adding
40another call stack layer, and supports calling C<return> from the C<try> block to
41return from the parent subroutine. These extra features come at a cost of a few
42dependencies, namely L<Devel::Declare> and L<Scope::Upper> which are
43occasionally problematic, and the additional catch filtering uses L<Moose>
44type constraints which may not be desirable either.
45
46The main focus of this module is to provide simple and reliable error handling
47for those having a hard time installing L<TryCatch>, but who still want to
48write correct C<eval> blocks without 5 lines of boilerplate each time.
49
50It's designed to work as correctly as possible in light of the various
51pathological edge cases (see L</BACKGROUND>) and to be compatible with any style
52of error values (simple strings, references, objects, overloaded objects, etc).
53
54If the C<try> block dies, it returns the value of the last statement executed in
55the C<catch> block, if there is one. Otherwise, it returns C<undef> in scalar
56context or the empty list in list context. The following examples all
57assign C<"bar"> to C<$x>:
58
59 my $x = try { die "foo" } catch { "bar" };
60 my $x = try { die "foo" } || "bar";
61 my $x = (try { die "foo" }) // "bar";
62
63 my $x = eval { die "foo" } || "bar";
64
65You can add C<finally> blocks, yielding the following:
66
67 my $x;
68 try { die 'foo' } finally { $x = 'bar' };
69 try { die 'foo' } catch { warn "Got a die: $_" } finally { $x = 'bar' };
70
71C<finally> blocks are always executed making them suitable for cleanup code
72which cannot be handled using local. You can add as many C<finally> blocks to a
73given C<try> block as you like.
74
75Note that adding a C<finally> block without a preceding C<catch> block
76suppresses any errors. This behaviour is consistent with using a standalone
77C<eval>, but it is not consistent with C<try>/C<finally> patterns found in
78other programming languages, such as Java, Python, Javascript or C#. If you
79learnt the C<try>/C<finally> pattern from one of these languages, watch out for
80this.
81
82=head1 EXPORTS
83
84All functions are exported by default using L<Exporter>.
85
86If you need to rename the C<try>, C<catch> or C<finally> keyword consider using
87L<Sub::Import> to get L<Sub::Exporter>'s flexibility.
88
89=over 4
90
91=item try (&;@)
92
93Takes one mandatory C<try> subroutine, an optional C<catch> subroutine and C<finally>
94subroutine.
95
96The mandatory subroutine is evaluated in the context of an C<eval> block.
97
98If no error occurred the value from the first block is returned, preserving
99list/scalar context.
100
101If there was an error and the second subroutine was given it will be invoked
102with the error in C<$_> (localized) and as that block's first and only
103argument.
104
105C<$@> does B<not> contain the error. Inside the C<catch> block it has the same
106value it had before the C<try> block was executed.
107
108Note that the error may be false, but if that happens the C<catch> block will
109still be invoked.
110
111Once all execution is finished then the C<finally> block, if given, will execute.
112
113=item catch (&;@)
114
115Intended to be used in the second argument position of C<try>.
116
117Returns a reference to the subroutine it was given but blessed as
118C<Try::Tiny::Catch> which allows try to decode correctly what to do
119with this code reference.
120
121 catch { ... }
122
123Inside the C<catch> block the caught error is stored in C<$_>, while previous
124value of C<$@> is still available for use. This value may or may not be
125meaningful depending on what happened before the C<try>, but it might be a good
126idea to preserve it in an error stack.
127
128For code that captures C<$@> when throwing new errors (i.e.
129L<Class::Throwable>), you'll need to do:
130
131 local $@ = $_;
132
133=item finally (&;@)
134
135 try { ... }
136 catch { ... }
137 finally { ... };
138
139Or
140
141 try { ... }
142 finally { ... };
143
144Or even
145
146 try { ... }
147 finally { ... }
148 catch { ... };
149
150Intended to be the second or third element of C<try>. C<finally> blocks are always
151executed in the event of a successful C<try> or if C<catch> is run. This allows
152you to locate cleanup code which cannot be done via C<local()> e.g. closing a file
153handle.
154
155When invoked, the C<finally> block is passed the error that was caught. If no
156error was caught, it is passed nothing. (Note that the C<finally> block does not
157localize C<$_> with the error, since unlike in a C<catch> block, there is no way
158to know if C<$_ == undef> implies that there were no errors.) In other words,
159the following code does just what you would expect:
160
161 try {
162 die_sometimes();
163 } catch {
164 # ...code run in case of error
165 } finally {
166 if (@_) {
167 print "The try block died with: @_\n";
168 } else {
169 print "The try block ran without error.\n";
170 }
171 };
172
173B<You must always do your own error handling in the C<finally> block>. C<Try::Tiny> will
174not do anything about handling possible errors coming from code located in these
175blocks.
176
177Furthermore B<exceptions in C<finally> blocks are not trappable and are unable
178to influence the execution of your program>. This is due to limitation of
179C<DESTROY>-based scope guards, which C<finally> is implemented on top of. This
180may change in a future version of Try::Tiny.
181
182In the same way C<catch()> blesses the code reference this subroutine does the same
183except it bless them as C<Try::Tiny::Finally>.
184
185=back
186
187=head1 BACKGROUND
188
189There are a number of issues with C<eval>.
190
191=head2 Clobbering $@
192
193When you run an C<eval> block and it succeeds, C<$@> will be cleared, potentially
194clobbering an error that is currently being caught.
195
196This causes action at a distance, clearing previous errors your caller may have
197not yet handled.
198
199C<$@> must be properly localized before invoking C<eval> in order to avoid this
200issue.
201
202More specifically, C<$@> is clobbered at the beginning of the C<eval>, which
203also makes it impossible to capture the previous error before you die (for
204instance when making exception objects with error stacks).
205
206For this reason C<try> will actually set C<$@> to its previous value (the one
207available before entering the C<try> block) in the beginning of the C<eval>
208block.
209
210=head2 Localizing $@ silently masks errors
211
212Inside an C<eval> block, C<die> behaves sort of like:
213
214 sub die {
215 $@ = $_[0];
216 return_undef_from_eval();
217 }
218
219This means that if you were polite and localized C<$@> you can't die in that
220scope, or your error will be discarded (printing "Something's wrong" instead).
221
222The workaround is very ugly:
223
224 my $error = do {
225 local $@;
226 eval { ... };
227 $@;
228 };
229
230 ...
231 die $error;
232
233=head2 $@ might not be a true value
234
235This code is wrong:
236
237 if ( $@ ) {
238 ...
239 }
240
241because due to the previous caveats it may have been unset.
242
243C<$@> could also be an overloaded error object that evaluates to false, but
244that's asking for trouble anyway.
245
246The classic failure mode is:
247
248 sub Object::DESTROY {
249 eval { ... }
250 }
251
252 eval {
253 my $obj = Object->new;
254
255 die "foo";
256 };
257
258 if ( $@ ) {
259
260 }
261
262In this case since C<Object::DESTROY> is not localizing C<$@> but still uses
263C<eval>, it will set C<$@> to C<"">.
264
265The destructor is called when the stack is unwound, after C<die> sets C<$@> to
266C<"foo at Foo.pm line 42\n">, so by the time C<if ( $@ )> is evaluated it has
267been cleared by C<eval> in the destructor.
268
269The workaround for this is even uglier than the previous ones. Even though we
270can't save the value of C<$@> from code that doesn't localize, we can at least
271be sure the C<eval> was aborted due to an error:
272
273 my $failed = not eval {
274 ...
275
276 return 1;
277 };
278
279This is because an C<eval> that caught a C<die> will always return a false
280value.
281
282=head1 SHINY SYNTAX
283
284Using Perl 5.10 you can use L<perlsyn/"Switch statements">.
285
286=for stopwords topicalizer
287
288The C<catch> block is invoked in a topicalizer context (like a C<given> block),
289but note that you can't return a useful value from C<catch> using the C<when>
290blocks without an explicit C<return>.
291
292This is somewhat similar to Perl 6's C<CATCH> blocks. You can use it to
293concisely match errors:
294
295 try {
296 require Foo;
297 } catch {
298 when (/^Can't locate .*?\.pm in \@INC/) { } # ignore
299 default { die $_ }
300 };
301
302=head1 CAVEATS
303
304=over 4
305
306=item *
307
308C<@_> is not available within the C<try> block, so you need to copy your
309argument list. In case you want to work with argument values directly via C<@_>
310aliasing (i.e. allow C<$_[1] = "foo">), you need to pass C<@_> by reference:
311
312 sub foo {
313 my ( $self, @args ) = @_;
314 try { $self->bar(@args) }
315 }
316
317or
318
319 sub bar_in_place {
320 my $self = shift;
321 my $args = \@_;
322 try { $_ = $self->bar($_) for @$args }
323 }
324
325=item *
326
327C<return> returns from the C<try> block, not from the parent sub (note that
328this is also how C<eval> works, but not how L<TryCatch> works):
329
330 sub parent_sub {
331 try {
332 die;
333 }
334 catch {
335 return;
336 };
337
338 say "this text WILL be displayed, even though an exception is thrown";
339 }
340
341Instead, you should capture the return value:
342
343 sub parent_sub {
344 my $success = try {
345 die;
346 1;
347 };
348 return unless $success;
349
350 say "This text WILL NEVER appear!";
351 }
352 # OR
353 sub parent_sub_with_catch {
354 my $success = try {
355 die;
356 1;
357 }
358 catch {
359 # do something with $_
360 return undef; #see note
361 };
362 return unless $success;
363
364 say "This text WILL NEVER appear!";
365 }
366
367Note that if you have a C<catch> block, it must return C<undef> for this to work,
368since if a C<catch> block exists, its return value is returned in place of C<undef>
369when an exception is thrown.
370
371=item *
372
373C<try> introduces another caller stack frame. L<Sub::Uplevel> is not used. L<Carp>
374will not report this when using full stack traces, though, because
375C<%Carp::Internal> is used. This lack of magic is considered a feature.
376
377=for stopwords unhygienically
378
379=item *
380
381The value of C<$_> in the C<catch> block is not guaranteed to be the value of
382the exception thrown (C<$@>) in the C<try> block. There is no safe way to
383ensure this, since C<eval> may be used unhygienically in destructors. The only
384guarantee is that the C<catch> will be called if an exception is thrown.
385
386=item *
387
388The return value of the C<catch> block is not ignored, so if testing the result
389of the expression for truth on success, be sure to return a false value from
390the C<catch> block:
391
392 my $obj = try {
393 MightFail->new;
394 } catch {
395 ...
396
397 return; # avoid returning a true value;
398 };
399
400 return unless $obj;
401
402=item *
403
404C<$SIG{__DIE__}> is still in effect.
405
406Though it can be argued that C<$SIG{__DIE__}> should be disabled inside of
407C<eval> blocks, since it isn't people have grown to rely on it. Therefore in
408the interests of compatibility, C<try> does not disable C<$SIG{__DIE__}> for
409the scope of the error throwing code.
410
411=item *
412
413Lexical C<$_> may override the one set by C<catch>.
414
415For example Perl 5.10's C<given> form uses a lexical C<$_>, creating some
416confusing behavior:
417
418 given ($foo) {
419 when (...) {
420 try {
421 ...
422 } catch {
423 warn $_; # will print $foo, not the error
424 warn $_[0]; # instead, get the error like this
425 }
426 }
427 }
428
429Note that this behavior was changed once again in L<Perl5 version 18
430|https://metacpan.org/module/perldelta#given-now-aliases-the-global-_>.
431However, since the entirety of lexical C<$_> is now L<considered experimental
432|https://metacpan.org/module/perldelta#Lexical-_-is-now-experimental>, it
433is unclear whether the new version 18 behavior is final.
434
435=back
436
437=head1 SEE ALSO
438
439=over 4
440
441=item L<TryCatch>
442
443Much more feature complete, more convenient semantics, but at the cost of
444implementation complexity.
445
446=item L<autodie>
447
448Automatic error throwing for builtin functions and more. Also designed to
449work well with C<given>/C<when>.
450
451=item L<Throwable>
452
453A lightweight role for rolling your own exception classes.
454
455=item L<Error>
456
457Exception object implementation with a C<try> statement. Does not localize
458C<$@>.
459
460=item L<Exception::Class::TryCatch>
461
462Provides a C<catch> statement, but properly calling C<eval> is your
463responsibility.
464
465The C<try> keyword pushes C<$@> onto an error stack, avoiding some of the
466issues with C<$@>, but you still need to localize to prevent clobbering.
467
468=back
469
470=head1 LIGHTNING TALK
471
472I gave a lightning talk about this module, you can see the slides (Firefox
473only):
474
475L<http://web.archive.org/web/20100628040134/http://nothingmuch.woobling.org/talks/takahashi.xul>
476
477Or read the source:
478
479L<http://web.archive.org/web/20100305133605/http://nothingmuch.woobling.org/talks/yapc_asia_2009/try_tiny.yml>
480
cb57845a 481=head1 SUPPORT
482
483Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Try-Tiny>
484(or L<bug-Try-Tiny@rt.cpan.org|mailto:bug-Try-Tiny@rt.cpan.org>).
485
486=head1 AUTHORS
487
488=over 4
489
490=item *
491
492יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
493
494=item *
495
496Jesse Luehrs <doy@tozt.net>
497
498=back
499
500=head1 CONTRIBUTORS
501
fae6bce6 502=for stopwords Karen Etheridge Peter Rabbitson Ricardo Signes Mark Fowler Graham Knop Lukas Mai Dagfinn Ilmari Mannsåker Paul Howarth Rudolf Leermakers anaxagoras awalker chromatic Alex cm-perl Andrew Yates David Lowe Glenn Hans Dieter Pearcey Jonathan Yu Marc Mims Stosberg Pali
cb57845a 503
504=over 4
505
506=item *
507
08068486 508Karen Etheridge <ether@cpan.org>
cb57845a 509
510=item *
511
08068486 512Peter Rabbitson <ribasushi@cpan.org>
cb57845a 513
514=item *
515
516Ricardo Signes <rjbs@cpan.org>
517
518=item *
519
520Mark Fowler <mark@twoshortplanks.com>
521
522=item *
523
524Graham Knop <haarg@haarg.org>
525
526=item *
527
a3769675 528Lukas Mai <l.mai@web.de>
cb57845a 529
530=item *
531
a3769675 532Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
cb57845a 533
534=item *
535
fae6bce6 536Paul Howarth <paul@city-fan.org>
537
538=item *
539
cb57845a 540Rudolf Leermakers <rudolf@hatsuseno.org>
541
542=item *
543
544anaxagoras <walkeraj@gmail.com>
545
546=item *
547
548awalker <awalker@sourcefire.com>
549
550=item *
551
552chromatic <chromatic@wgz.org>
553
554=item *
555
556Alex <alex@koban.(none)>
557
558=item *
559
560cm-perl <cm-perl@users.noreply.github.com>
561
562=item *
563
564Andrew Yates <ayates@haddock.local>
565
566=item *
567
568David Lowe <davidl@lokku.com>
569
570=item *
571
572Glenn Fowler <cebjyre@cpan.org>
573
574=item *
575
576Hans Dieter Pearcey <hdp@weftsoar.net>
577
578=item *
579
580Jonathan Yu <JAWNSY@cpan.org>
581
582=item *
583
584Marc Mims <marc@questright.com>
585
586=item *
587
588Mark Stosberg <mark@stosberg.com>
589
a3769675 590=item *
591
fae6bce6 592Pali <pali@cpan.org>
a3769675 593
cb57845a 594=back
595
596=head1 COPYRIGHT AND LICENCE
597
598This software is Copyright (c) 2009 by יובל קוג'מן (Yuval Kogman).
599
600This is free software, licensed under:
601
602 The MIT (X11) License
603
604=cut