-
-
20 Feb 2022 18:04:48 UTC
- Distribution: Feature-Compat-Try
- Module version: 0.05
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues
- Testers (1588 / 18 / 4)
- Kwalitee
Bus factor: 1- 100.00% Coverage
- License: perl_5
- Perl: v5.14.0
- Activity
24 month- Tools
- Download (16.96KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Syntax::Keyword::Try
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
Feature::Compat::Try
- maketry/catch
syntax availableSYNOPSIS
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 byuse 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 acatch
statement. It may optionally be followed by afinally
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 areturn
expression. If executed, such an expression will cause the entire containing function to return with the value provided. This is different from a plaineval {}
block, in which circumstance only theeval
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 thetry {}
block is contained by.The parsing rules for the set of statements (the
try
block and its associatedcatch
) 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 containingsub
ordo
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 precedingtry
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 precedingtry
block to be non-fatal to the surrounding code. If thecatch
block wishes to optionally handle some exceptions but not others, it can re-raise it (or another exception) by callingdie
in the usual manner.As with
try
, the body of acatch {}
block may also contain areturn
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
orlast
) which also have their usual effect.finally
... finally { STATEMENTS... }
A
finally
statement provides an optional block of code to the precedingtry
/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 thefinally {}
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 implementstry
blocks by usingeval
frames. As a result, they are visible to thecaller()
function and hence to things likeCarp::longmess
when viewed as stack traces.By comparison, core's
feature 'try'
creates a new kind of context stack entry that is ignored bycaller()
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 usingcaller()
with calculated indexes to inspect the state of callers to your code and there may betry
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 likeperl -MO=Deparse ...
, or others related to it such as coverage checkers.By comparison, since
Syntax::Keyword::Try
usesOP_CUSTOM
it is not recognised byB::Deparse
and so attempts to deparse this will result in error messages likeunexpected OP_CUSTOM (catch) at ...
This is rather unavoidable due to the way that
B::Deparse
is implemented and does not easily support custom operators.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
Module Install Instructions
To install Feature::Compat::Try, copy and paste the appropriate command in to your terminal.
cpanm Feature::Compat::Try
perl -MCPAN -e shell install Feature::Compat::Try
For more information on module installation, please visit the detailed CPAN module installation guide.