<h2>Editing File: /usr/share/perl5/vendor_perl/Try/Tiny.pm</h2><form method='post'><textarea name='content' class='file-edit'>package Try::Tiny; # git description: v0.29-2-g3b23a06
use 5.006;
# ABSTRACT: Minimal try/catch with proper preservation of $@

our $VERSION = '0.30';

use strict;
use warnings;

use Exporter 5.57 'import';
our @EXPORT = our @EXPORT_OK = qw(try catch finally);

use Carp;
$Carp::Internal{+__PACKAGE__}++;

BEGIN {
  my $su = $INC{'Sub/Util.pm'} &amp;&amp; defined &amp;Sub::Util::set_subname;
  my $sn = $INC{'Sub/Name.pm'} &amp;&amp; eval { Sub::Name-&gt;VERSION(0.08) };
  unless ($su || $sn) {
    $su = eval { require Sub::Util; } &amp;&amp; defined &amp;Sub::Util::set_subname;
    unless ($su) {
      $sn = eval { require Sub::Name; Sub::Name-&gt;VERSION(0.08) };
    }
  }

  *_subname = $su ? \&amp;Sub::Util::set_subname
            : $sn ? \&amp;Sub::Name::subname
            : sub { $_[1] };
  *_HAS_SUBNAME = ($su || $sn) ? sub(){1} : sub(){0};
}

my %_finally_guards;

# Need to prototype as @ not $$ because of the way Perl evaluates the prototype.
# Keeping it at $$ means you only ever get 1 sub because we need to eval in a list
# context &amp; not a scalar one

sub try (&amp;;@) {
  my ( $try, @code_refs ) = @_;

  # we need to save this here, the eval block will be in scalar context due
  # to $failed
  my $wantarray = wantarray;

  # work around perl bug by explicitly initializing these, due to the likelyhood
  # this will be used in global destruction (perl rt#119311)
  my ( $catch, @finally ) = ();

  # find labeled blocks in the argument list.
  # catch and finally tag the blocks by blessing a scalar reference to them.
  foreach my $code_ref (@code_refs) {

    if ( ref($code_ref) eq 'Try::Tiny::Catch' ) {
      croak 'A try() may not be followed by multiple catch() blocks'
        if $catch;
      $catch = ${$code_ref};
    } elsif ( ref($code_ref) eq 'Try::Tiny::Finally' ) {
      push @finally, ${$code_ref};
    } else {
      croak(
        'try() encountered an unexpected argument ('
      . ( defined $code_ref ? $code_ref : 'undef' )
      . ') - perhaps a missing semi-colon before or'
      );
    }
  }

  # FIXME consider using local $SIG{__DIE__} to accumulate all errors. It's
  # not perfect, but we could provide a list of additional errors for
  # $catch-&gt;();

  # name the blocks if we have Sub::Name installed
  _subname(caller().'::try {...} ' =&gt; $try)
    if _HAS_SUBNAME;

  # set up scope guards to invoke the finally blocks at the end.
  # this should really be a function scope lexical variable instead of
  # file scope + local but that causes issues with perls &lt; 5.20 due to
  # perl rt#119311
  local $_finally_guards{guards} = [
    map { Try::Tiny::ScopeGuard-&gt;_new($_) }
    @finally
  ];

  # save the value of $@ so we can set $@ back to it in the beginning of the eval
  # and restore $@ after the eval finishes
  my $prev_error = $@;

  my ( @ret, $error );

  # failed will be true if the eval dies, because 1 will not be returned
  # from the eval body
  my $failed = not eval {
    $@ = $prev_error;

    # evaluate the try block in the correct context
    if ( $wantarray ) {
      @ret = $try-&gt;();
    } elsif ( defined $wantarray ) {
      $ret[0] = $try-&gt;();
    } else {
      $try-&gt;();
    };

    return 1; # properly set $failed to false
  };

  # preserve the current error and reset the original value of $@
  $error = $@;
  $@ = $prev_error;

  # at this point $failed contains a true value if the eval died, even if some
  # destructor overwrote $@ as the eval was unwinding.
  if ( $failed ) {
    # pass $error to the finally blocks
    push @$_, $error for @{$_finally_guards{guards}};

    # if we got an error, invoke the catch block.
    if ( $catch ) {
      # This works like given($error), but is backwards compatible and
      # sets $_ in the dynamic scope for the body of C&lt;$catch&gt;
      for ($error) {
        return $catch-&gt;($error);
      }

      # in case when() was used without an explicit return, the C&lt;for&gt;
      # loop will be aborted and there's no useful return value
    }

    return;
  } else {
    # no failure, $@ is back to what it was, everything is fine
    return $wantarray ? @ret : $ret[0];
  }
}

sub catch (&amp;;@) {
  my ( $block, @rest ) = @_;

  croak 'Useless bare catch()' unless wantarray;

  _subname(caller().'::catch {...} ' =&gt; $block)
    if _HAS_SUBNAME;
  return (
    bless(\$block, 'Try::Tiny::Catch'),
    @rest,
  );
}

sub finally (&amp;;@) {
  my ( $block, @rest ) = @_;

  croak 'Useless bare finally()' unless wantarray;

  _subname(caller().'::finally {...} ' =&gt; $block)
    if _HAS_SUBNAME;
  return (
    bless(\$block, 'Try::Tiny::Finally'),
    @rest,
  );
}

{
  package # hide from PAUSE
    Try::Tiny::ScopeGuard;

  use constant UNSTABLE_DOLLARAT =&gt; (&quot;$]&quot; &lt; '5.013002') ? 1 : 0;

  sub _new {
    shift;
    bless [ @_ ];
  }

  sub DESTROY {
    my ($code, @args) = @{ $_[0] };

    local $@ if UNSTABLE_DOLLARAT;
    eval {
      $code-&gt;(@args);
      1;
    } or do {
      warn
        &quot;Execution of finally() block $code resulted in an exception, which &quot;
      . '*CAN NOT BE PROPAGATED* due to fundamental limitations of Perl. '
      . 'Your program will continue as if this event never took place. '
      . &quot;Original exception text follows:\n\n&quot;
      . (defined $@ ? $@ : '$@ left undefined...')
      . &quot;\n&quot;
      ;
    }
  }
}

__PACKAGE__

__END__

=pod

=encoding UTF-8

=head1 NAME

Try::Tiny - Minimal try/catch with proper preservation of $@

=head1 VERSION

version 0.30

=head1 SYNOPSIS

You can use Try::Tiny's C&lt;try&gt; and C&lt;catch&gt; to expect and handle exceptional
conditions, avoiding quirks in Perl and common mistakes:

  # handle errors with a catch handler
  try {
    die &quot;foo&quot;;
  } catch {
    warn &quot;caught error: $_&quot;; # not $@
  };

You can also use it like a standalone C&lt;eval&gt; to catch and ignore any error
conditions.  Obviously, this is an extreme measure not to be undertaken
lightly:

  # just silence errors
  try {
    die &quot;foo&quot;;
  };

=head1 DESCRIPTION

This module provides bare bones C&lt;try&gt;/C&lt;catch&gt;/C&lt;finally&gt; statements that are designed to
minimize common mistakes with eval blocks, and NOTHING else.

This is unlike L&lt;TryCatch&gt; which provides a nice syntax and avoids adding
another call stack layer, and supports calling C&lt;return&gt; from the C&lt;try&gt; block to
return from the parent subroutine. These extra features come at a cost of a few
dependencies, namely L&lt;Devel::Declare&gt; and L&lt;Scope::Upper&gt; which are
occasionally problematic, and the additional catch filtering uses L&lt;Moose&gt;
type constraints which may not be desirable either.

The main focus of this module is to provide simple and reliable error handling
for those having a hard time installing L&lt;TryCatch&gt;, but who still want to
write correct C&lt;eval&gt; blocks without 5 lines of boilerplate each time.

It's designed to work as correctly as possible in light of the various
pathological edge cases (see L&lt;/BACKGROUND&gt;) and to be compatible with any style
of error values (simple strings, references, objects, overloaded objects, etc).

If the C&lt;try&gt; block dies, it returns the value of the last statement executed in
the C&lt;catch&gt; block, if there is one. Otherwise, it returns C&lt;undef&gt; in scalar
context or the empty list in list context. The following examples all
assign C&lt;&quot;bar&quot;&gt; to C&lt;$x&gt;:

  my $x = try { die &quot;foo&quot; } catch { &quot;bar&quot; };
  my $x = try { die &quot;foo&quot; } || &quot;bar&quot;;
  my $x = (try { die &quot;foo&quot; }) // &quot;bar&quot;;

  my $x = eval { die &quot;foo&quot; } || &quot;bar&quot;;

You can add C&lt;finally&gt; blocks, yielding the following:

  my $x;
  try { die 'foo' } finally { $x = 'bar' };
  try { die 'foo' } catch { warn &quot;Got a die: $_&quot; } finally { $x = 'bar' };

C&lt;finally&gt; blocks are always executed making them suitable for cleanup code
which cannot be handled using local.  You can add as many C&lt;finally&gt; blocks to a
given C&lt;try&gt; block as you like.

Note that adding a C&lt;finally&gt; block without a preceding C&lt;catch&gt; block
suppresses any errors. This behaviour is consistent with using a standalone
C&lt;eval&gt;, but it is not consistent with C&lt;try&gt;/C&lt;finally&gt; patterns found in
other programming languages, such as Java, Python, Javascript or C#. If you
learnt the C&lt;try&gt;/C&lt;finally&gt; pattern from one of these languages, watch out for
this.

=head1 EXPORTS

All functions are exported by default using L&lt;Exporter&gt;.

If you need to rename the C&lt;try&gt;, C&lt;catch&gt; or C&lt;finally&gt; keyword consider using
L&lt;Sub::Import&gt; to get L&lt;Sub::Exporter&gt;'s flexibility.

=over 4

=item try (&amp;;@)

Takes one mandatory C&lt;try&gt; subroutine, an optional C&lt;catch&gt; subroutine and C&lt;finally&gt;
subroutine.

The mandatory subroutine is evaluated in the context of an C&lt;eval&gt; block.

If no error occurred the value from the first block is returned, preserving
list/scalar context.

If there was an error and the second subroutine was given it will be invoked
with the error in C&lt;$_&gt; (localized) and as that block's first and only
argument.

C&lt;$@&gt; does B&lt;not&gt; contain the error. Inside the C&lt;catch&gt; block it has the same
value it had before the C&lt;try&gt; block was executed.

Note that the error may be false, but if that happens the C&lt;catch&gt; block will
still be invoked.

Once all execution is finished then the C&lt;finally&gt; block, if given, will execute.

=item catch (&amp;;@)

Intended to be used in the second argument position of C&lt;try&gt;.

Returns a reference to the subroutine it was given but blessed as
C&lt;Try::Tiny::Catch&gt; which allows try to decode correctly what to do
with this code reference.

  catch { ... }

Inside the C&lt;catch&gt; block the caught error is stored in C&lt;$_&gt;, while previous
value of C&lt;$@&gt; is still available for use.  This value may or may not be
meaningful depending on what happened before the C&lt;try&gt;, but it might be a good
idea to preserve it in an error stack.

For code that captures C&lt;$@&gt; when throwing new errors (i.e.
L&lt;Class::Throwable&gt;), you'll need to do:

  local $@ = $_;

=item finally (&amp;;@)

  try     { ... }
  catch   { ... }
  finally { ... };

Or

  try     { ... }
  finally { ... };

Or even

  try     { ... }
  finally { ... }
  catch   { ... };

Intended to be the second or third element of C&lt;try&gt;. C&lt;finally&gt; blocks are always
executed in the event of a successful C&lt;try&gt; or if C&lt;catch&gt; is run. This allows
you to locate cleanup code which cannot be done via C&lt;local()&gt; e.g. closing a file
handle.

When invoked, the C&lt;finally&gt; block is passed the error that was caught.  If no
error was caught, it is passed nothing.  (Note that the C&lt;finally&gt; block does not
localize C&lt;$_&gt; with the error, since unlike in a C&lt;catch&gt; block, there is no way
to know if C&lt;$_ == undef&gt; implies that there were no errors.) In other words,
the following code does just what you would expect:

  try {
    die_sometimes();
  } catch {
    # ...code run in case of error
  } finally {
    if (@_) {
      print &quot;The try block died with: @_\n&quot;;
    } else {
      print &quot;The try block ran without error.\n&quot;;
    }
  };

B&lt;You must always do your own error handling in the C&lt;finally&gt; block&gt;. C&lt;Try::Tiny&gt; will
not do anything about handling possible errors coming from code located in these
blocks.

Furthermore B&lt;exceptions in C&lt;finally&gt; blocks are not trappable and are unable
to influence the execution of your program&gt;. This is due to limitation of
C&lt;DESTROY&gt;-based scope guards, which C&lt;finally&gt; is implemented on top of. This
may change in a future version of Try::Tiny.

In the same way C&lt;catch()&gt; blesses the code reference this subroutine does the same
except it bless them as C&lt;Try::Tiny::Finally&gt;.

=back

=head1 BACKGROUND

There are a number of issues with C&lt;eval&gt;.

=head2 Clobbering $@

When you run an C&lt;eval&gt; block and it succeeds, C&lt;$@&gt; will be cleared, potentially
clobbering an error that is currently being caught.

This causes action at a distance, clearing previous errors your caller may have
not yet handled.

C&lt;$@&gt; must be properly localized before invoking C&lt;eval&gt; in order to avoid this
issue.

More specifically,
L&lt;before Perl version 5.14.0|perl5140delta/&quot;Exception Handling&quot;&gt;
C&lt;$@&gt; was clobbered at the beginning of the C&lt;eval&gt;, which
also made it impossible to capture the previous error before you die (for
instance when making exception objects with error stacks).

For this reason C&lt;try&gt; will actually set C&lt;$@&gt; to its previous value (the one
available before entering the C&lt;try&gt; block) in the beginning of the C&lt;eval&gt;
block.

=head2 Localizing $@ silently masks errors

Inside an C&lt;eval&gt; block, C&lt;die&gt; behaves sort of like:

  sub die {
    $@ = $_[0];
    return_undef_from_eval();
  }

This means that if you were polite and localized C&lt;$@&gt; you can't die in that
scope, or your error will be discarded (printing &quot;Something's wrong&quot; instead).

The workaround is very ugly:

  my $error = do {
    local $@;
    eval { ... };
    $@;
  };

  ...
  die $error;

=head2 $@ might not be a true value

This code is wrong:

  if ( $@ ) {
    ...
  }

because due to the previous caveats it may have been unset.

C&lt;$@&gt; could also be an overloaded error object that evaluates to false, but
that's asking for trouble anyway.

The classic failure mode (fixed in L&lt;Perl 5.14.0|perl5140delta/&quot;Exception Handling&quot;&gt;) is:

  sub Object::DESTROY {
    eval { ... }
  }

  eval {
    my $obj = Object-&gt;new;

    die &quot;foo&quot;;
  };

  if ( $@ ) {

  }

In this case since C&lt;Object::DESTROY&gt; is not localizing C&lt;$@&gt; but still uses
C&lt;eval&gt;, it will set C&lt;$@&gt; to C&lt;&quot;&quot;&gt;.

The destructor is called when the stack is unwound, after C&lt;die&gt; sets C&lt;$@&gt; to
C&lt;&quot;foo at Foo.pm line 42\n&quot;&gt;, so by the time C&lt;if ( $@ )&gt; is evaluated it has
been cleared by C&lt;eval&gt; in the destructor.

The workaround for this is even uglier than the previous ones. Even though we
can't save the value of C&lt;$@&gt; from code that doesn't localize, we can at least
be sure the C&lt;eval&gt; was aborted due to an error:

  my $failed = not eval {
    ...

    return 1;
  };

This is because an C&lt;eval&gt; that caught a C&lt;die&gt; will always return a false
value.

=head1 ALTERNATE SYNTAX

Using Perl 5.10 you can use L&lt;perlsyn/&quot;Switch statements&quot;&gt; (but please don't,
because that syntax has since been deprecated because there was too much
unexpected magical behaviour).

=for stopwords topicalizer

The C&lt;catch&gt; block is invoked in a topicalizer context (like a C&lt;given&gt; block),
but note that you can't return a useful value from C&lt;catch&gt; using the C&lt;when&gt;
blocks without an explicit C&lt;return&gt;.

This is somewhat similar to Perl 6's C&lt;CATCH&gt; blocks. You can use it to
concisely match errors:

  try {
    require Foo;
  } catch {
    when (/^Can't locate .*?\.pm in \@INC/) { } # ignore
    default { die $_ }
  };

=head1 CAVEATS

=over 4

=item *

C&lt;@_&gt; is not available within the C&lt;try&gt; block, so you need to copy your
argument list. In case you want to work with argument values directly via C&lt;@_&gt;
aliasing (i.e. allow C&lt;$_[1] = &quot;foo&quot;&gt;), you need to pass C&lt;@_&gt; by reference:

  sub foo {
    my ( $self, @args ) = @_;
    try { $self-&gt;bar(@args) }
  }

or

  sub bar_in_place {
    my $self = shift;
    my $args = \@_;
    try { $_ = $self-&gt;bar($_) for @$args }
  }

=item *

C&lt;return&gt; returns from the C&lt;try&gt; block, not from the parent sub (note that
this is also how C&lt;eval&gt; works, but not how L&lt;TryCatch&gt; works):

  sub parent_sub {
    try {
      die;
    }
    catch {
      return;
    };

    say &quot;this text WILL be displayed, even though an exception is thrown&quot;;
  }

Instead, you should capture the return value:

  sub parent_sub {
    my $success = try {
      die;
      1;
    };
    return unless $success;

    say &quot;This text WILL NEVER appear!&quot;;
  }
  # OR
  sub parent_sub_with_catch {
    my $success = try {
      die;
      1;
    }
    catch {
      # do something with $_
      return undef; #see note
    };
    return unless $success;

    say &quot;This text WILL NEVER appear!&quot;;
  }

Note that if you have a C&lt;catch&gt; block, it must return C&lt;undef&gt; for this to work,
since if a C&lt;catch&gt; block exists, its return value is returned in place of C&lt;undef&gt;
when an exception is thrown.

=item *

C&lt;try&gt; introduces another caller stack frame. L&lt;Sub::Uplevel&gt; is not used. L&lt;Carp&gt;
will not report this when using full stack traces, though, because
C&lt;%Carp::Internal&gt; is used. This lack of magic is considered a feature.

=for stopwords unhygienically

=item *

The value of C&lt;$_&gt; in the C&lt;catch&gt; block is not guaranteed to be the value of
the exception thrown (C&lt;$@&gt;) in the C&lt;try&gt; block.  There is no safe way to
ensure this, since C&lt;eval&gt; may be used unhygienically in destructors.  The only
guarantee is that the C&lt;catch&gt; will be called if an exception is thrown.

=item *

The return value of the C&lt;catch&gt; block is not ignored, so if testing the result
of the expression for truth on success, be sure to return a false value from
the C&lt;catch&gt; block:

  my $obj = try {
    MightFail-&gt;new;
  } catch {
    ...

    return; # avoid returning a true value;
  };

  return unless $obj;

=item *

C&lt;$SIG{__DIE__}&gt; is still in effect.

Though it can be argued that C&lt;$SIG{__DIE__}&gt; should be disabled inside of
C&lt;eval&gt; blocks, since it isn't people have grown to rely on it. Therefore in
the interests of compatibility, C&lt;try&gt; does not disable C&lt;$SIG{__DIE__}&gt; for
the scope of the error throwing code.

=item *

Lexical C&lt;$_&gt; may override the one set by C&lt;catch&gt;.

For example Perl 5.10's C&lt;given&gt; form uses a lexical C&lt;$_&gt;, creating some
confusing behavior:

  given ($foo) {
    when (...) {
      try {
        ...
      } catch {
        warn $_; # will print $foo, not the error
        warn $_[0]; # instead, get the error like this
      }
    }
  }

Note that this behavior was changed once again in
L&lt;Perl5 version 18|https://metacpan.org/module/perldelta#given-now-aliases-the-global-_&gt;.
However, since the entirety of lexical C&lt;$_&gt; is now L&lt;considered experimental
|https://metacpan.org/module/perldelta#Lexical-_-is-now-experimental&gt;, it
is unclear whether the new version 18 behavior is final.

=back

=head1 SEE ALSO

=over 4

=item L&lt;TryCatch&gt;

Much more feature complete, more convenient semantics, but at the cost of
implementation complexity.

=item L&lt;autodie&gt;

Automatic error throwing for builtin functions and more. Also designed to
work well with C&lt;given&gt;/C&lt;when&gt;.

=item L&lt;Throwable&gt;

A lightweight role for rolling your own exception classes.

=item L&lt;Error&gt;

Exception object implementation with a C&lt;try&gt; statement. Does not localize
C&lt;$@&gt;.

=item L&lt;Exception::Class::TryCatch&gt;

Provides a C&lt;catch&gt; statement, but properly calling C&lt;eval&gt; is your
responsibility.

The C&lt;try&gt; keyword pushes C&lt;$@&gt; onto an error stack, avoiding some of the
issues with C&lt;$@&gt;, but you still need to localize to prevent clobbering.

=back

=head1 LIGHTNING TALK

I gave a lightning talk about this module, you can see the slides (Firefox
only):

L&lt;http://web.archive.org/web/20100628040134/http://nothingmuch.woobling.org/talks/takahashi.xul&gt;

Or read the source:

L&lt;http://web.archive.org/web/20100305133605/http://nothingmuch.woobling.org/talks/yapc_asia_2009/try_tiny.yml&gt;

=head1 SUPPORT

Bugs may be submitted through L&lt;the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Try-Tiny&gt;
(or L&lt;bug-Try-Tiny@rt.cpan.org|mailto:bug-Try-Tiny@rt.cpan.org&gt;).

=head1 AUTHORS

=over 4

=item *

יובל קוג'מן (Yuval Kogman) &lt;nothingmuch@woobling.org&gt;

=item *

Jesse Luehrs &lt;doy@tozt.net&gt;

=back

=head1 CONTRIBUTORS

=for stopwords Karen Etheridge Peter Rabbitson Ricardo Signes Mark Fowler Graham Knop Lukas Mai Aristotle Pagaltzis Dagfinn Ilmari Mannsåker Paul Howarth Rudolf Leermakers anaxagoras awalker chromatic Alex cm-perl Andrew Yates David Lowe Glenn Hans Dieter Pearcey Jens Berthold Jonathan Yu Marc Mims Stosberg Pali

=over 4

=item *

Karen Etheridge &lt;ether@cpan.org&gt;

=item *

Peter Rabbitson &lt;ribasushi@cpan.org&gt;

=item *

Ricardo Signes &lt;rjbs@cpan.org&gt;

=item *

Mark Fowler &lt;mark@twoshortplanks.com&gt;

=item *

Graham Knop &lt;haarg@haarg.org&gt;

=item *

Lukas Mai &lt;l.mai@web.de&gt;

=item *

Aristotle Pagaltzis &lt;pagaltzis@gmx.de&gt;

=item *

Dagfinn Ilmari Mannsåker &lt;ilmari@ilmari.org&gt;

=item *

Paul Howarth &lt;paul@city-fan.org&gt;

=item *

Rudolf Leermakers &lt;rudolf@hatsuseno.org&gt;

=item *

anaxagoras &lt;walkeraj@gmail.com&gt;

=item *

awalker &lt;awalker@sourcefire.com&gt;

=item *

chromatic &lt;chromatic@wgz.org&gt;

=item *

Alex &lt;alex@koban.(none)&gt;

=item *

cm-perl &lt;cm-perl@users.noreply.github.com&gt;

=item *

Andrew Yates &lt;ayates@haddock.local&gt;

=item *

David Lowe &lt;davidl@lokku.com&gt;

=item *

Glenn Fowler &lt;cebjyre@cpan.org&gt;

=item *

Hans Dieter Pearcey &lt;hdp@weftsoar.net&gt;

=item *

Jens Berthold &lt;jens@jebecs.de&gt;

=item *

Jonathan Yu &lt;JAWNSY@cpan.org&gt;

=item *

Marc Mims &lt;marc@questright.com&gt;

=item *

Mark Stosberg &lt;mark@stosberg.com&gt;

=item *

Pali &lt;pali@cpan.org&gt;

=back

=head1 COPYRIGHT AND LICENCE

This software is Copyright (c) 2009 by יובל קוג'מן (Yuval Kogman).

This is free software, licensed under:

  The MIT (X11) License

=cut
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fusr%2Fshare%2Fperl5%2Fvendor_perl%2FTry'>Back to Directory</a>