oracular (3) Feature::Compat::Try.3pm.gz

Provided by: libfeature-compat-try-perl_0.05-1_all bug

NAME

       "Feature::Compat::Try" - make "try/catch" syntax available

SYNOPSIS

          use Feature::Compat::Try;

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

DESCRIPTION

       This module makes syntax support for "try/catch" control flow easily available.

       Perl added such syntax at version 5.34.0, and extended it to support optional "finally" 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
       Syntax::Keyword::Try 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.

KEYWORDS

   try
          try {
             STATEMENTS...
          }
          ...

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

       Execution of the "try" 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 "try {}" block may contain a "return" expression. If executed, such an expression will
       cause the entire containing function to return with the value provided. This is different from a plain
       "eval {}" block, in which circumstance only the "eval" itself would return, not the entire function.

       The body of a "try {}" block may contain loop control expressions ("redo", "next", "last") which will
       have their usual effect on any loops that the "try {}" block is contained by.

       The parsing rules for the set of statements (the "try" block and its associated "catch") 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 "try" block can still yield a value if it
       appears as the final statement in its containing "sub" or "do" block. For example:

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

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

       A "catch" statement provides a block of code to the preceding "try" 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 "catch" statement causes any exception thrown by the preceding "try" block to be non-
       fatal to the surrounding code. If the "catch" block wishes to optionally handle some exceptions but not
       others, it can re-raise it (or another exception) by calling "die" in the usual manner.

       As with "try", the body of a "catch {}" block may also contain a "return" 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 ("redo", "next" or "last") which also have their usual effect.

   finally
          ...
          finally {
             STATEMENTS...
          }

       A "finally" statement provides an optional block of code to the preceding "try"/"catch" 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 "finally {}" 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 @_ 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 $@. If the "finally {}" block code throws an exception, this will be printed as a warning and
       discarded, leaving $@ containing the original exception, if one existed.

COMPATIBILITY NOTES

       This module may use either Syntax::Keyword::Try or the perl core "try" 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.

       •   Visibility to "caller()"

           The "Syntax::Keyword::Try" module implements "try" blocks by using "eval" frames. As a result, they
           are visible to the "caller()" function and hence to things like "Carp::longmess" when viewed as stack
           traces.

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

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

       •   "B::Deparse"

           The core "feature 'try'" is implemented by emitting real opcodes that represent its behaviour, which
           is recognised by the version of B::Deparse that ships with core perl. As a result, any code using
           this implementation will deparse currently with tools like "perl -MO=Deparse ...", or others related
           to it such as coverage checkers.

           By comparison, since "Syntax::Keyword::Try" uses "OP_CUSTOM" it is not recognised by "B::Deparse" 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 "B::Deparse" is implemented and does not easily
           support custom operators.

           See also <https://rt.cpan.org/Ticket/Display.html?id=134812>.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>