File Coverage

blib/lib/Feature/Compat/Try.pm

Criterion	Covered	Total	%
statement	15	15	100.0
branch			n/a
condition			n/a
subroutine	5	5	100.0
pod			n/a
total	20	20	100.0

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2021-2022 -- [e-mail]

package Feature::Compat::Try 0.05;

use v5.14;
use warnings;
use feature ();

# Core's use feature 'try' only supports 'finally' since 5.35.8
use constant HAVE_FEATURE_TRY => $] >= 5.035008;

=head1 NAME

C - make C syntax available

=head1 SYNOPSIS

   use Feature::Compat::Try;

   sub foo
   {
      try {
         attempt_a_thing();
         return "success";
      }
      catch ($e) {
         warn "It failed - $e";
         return "failure";
      }
   }

=head1 DESCRIPTION

This module makes syntax support for C control flow easily
available.

Perl added such syntax at version 5.34.0, and extended it to support optional
C blocks at 5.35.9, which is enabled by

   use feature 'try';

On that version of perl or later, this module simply enables the core feature
equivalent to using it directly. On such perls, this module will install with
no non-core dependencies, and requires no C compiler.

On older versions of perl before such syntax is available, it is currently
provided instead using the L module, imported with a
special set of options to configure it to recognise exactly and only the same
syntax as the core perl feature, thus ensuring that any code using it will
still continue to function on that newer perl.

=cut

=head1 KEYWORDS

=head2 try

   try {
      STATEMENTS...
   }
   ...

A C statement provides the main body of code that will be invoked, and
must be followed by a C statement. It may optionally be followed by
a C statement.

Execution of the C statement itself begins from the block given to the
statement and continues until either it throws an exception, or completes
successfully by reaching the end of the block.

The body of a C block may contain a C expression. If executed,
such an expression will cause the entire containing function to return with
the value provided. This is different from a plain C block, in which
circumstance only the C itself would return, not the entire function.

The body of a C block may contain loop control expressions (C,
C, C) which will have their usual effect on any loops that the
C block is contained by.

The parsing rules for the set of statements (the C block and its
associated C) are such that they are parsed as a self-contained
statement. Because of this, there is no need to end with a terminating
semicolon.

Even though it parses as a statement and not an expression, a C block can
still yield a value if it appears as the final statement in its containing
C or C block. For example:

   my $result = do {
      try { attempt_func() }
      catch ($e) { "Fallback Value" }
   };

=head2 catch

   ...
   catch ($var) {
      STATEMENTS...
   }

A C statement provides a block of code to the preceding C
statement that will be invoked in the case that the main block of code throws
an exception. A new lexical variable is created to store the exception in.

Presence of this C statement causes any exception thrown by the
preceding C block to be non-fatal to the surrounding code. If the
C block wishes to optionally handle some exceptions but not others, it
can re-raise it (or another exception) by calling C in the usual manner.

As with C, the body of a C block may also contain a C
expression, which as before, has its usual meaning, causing the entire
containing function to return with the given value. The body may also contain
loop control expressions (C, C or C) which also have their
usual effect.

=head2 finally

   ...
   finally {
      STATEMENTS...
   }

A C statement provides an optional block of code to the preceding
C/C pair which is executed afterwards, both in the case of a
normal execution or a thrown exception. This code block may be used to
provide whatever clean-up operations might be required by preceding code.

Because it is executed during a stack cleanup operation, a C block
may not cause the containing function to return, or to alter the return value
of it. It also cannot see the containing function's C<@_> arguments array
(though as it is block scoped within the function, it will continue to share
any normal lexical variables declared up until that point). It is protected
from disturbing the value of C<$@>. If the C block code throws an
exception, this will be printed as a warning and discarded, leaving C<$@>
containing the original exception, if one existed.
=cut

sub import
{
   if( HAVE_FEATURE_TRY ) {
      feature->import(qw( try ));
      require warnings;
      warnings->unimport(qw( experimental::try ));
   }
   else {
      require Syntax::Keyword::Try;
      Syntax::Keyword::Try->VERSION( '0.27' );
      Syntax::Keyword::Try->import(qw( try -require_catch -require_var ));
   }
}

=head1 COMPATIBILITY NOTES

This module may use either L or the perl core C
feature to implement its syntax. While the two behave very similarly, and both
conform to the description given above, the following differences should be
noted.

=over 4

=item * Visibility to C

The C module implements C blocks by using C
frames. As a result, they are visible to the C function and hence to
things like C when viewed as stack traces.

By comparison, core's C creates a new kind of context stack
entry that is ignored by C and hence these blocks do not show up in
stack traces.

This should not matter to most use-cases - e.g. even C will be
fine here. But if you are using C with calculated indexes to inspect
the state of callers to your code and there may be C frames in the way,
you will need to somehow account for the difference in stack height.

=item * C

The core C is implemented by emitting real opcodes that
represent its behaviour, which is recognised by the version of L
that ships with core perl. As a result, any code using this implementation
will deparse currently with tools like C, or others
related to it such as coverage checkers.

By comparison, since C uses C it is not
recognised by C and so attempts to deparse this will result in
error messages like

   unexpected OP_CUSTOM (catch) at ...

This is rather unavoidable due to the way that C is implemented
and does not easily support custom operators.

See also L.

=back

=cut

=head1 AUTHOR

Paul Evans

=cut

0x55AA;