Provided by: libsyntax-keyword-try-perl_0.09-1_amd64 
NAME
"Syntax::Keyword::Try" - a "try/catch/finally" syntax for perl
SYNOPSIS
use Syntax::Keyword::Try;
sub foo
{
try {
attempt_a_thing();
return "success";
}
catch {
warn "It failed - $@";
return "failure";
}
}
DESCRIPTION
This module provides a syntax plugin that implements exception-handling semantics in a form familiar to
users of other languages, being built on a block labeled with the "try" keyword, followed by at least one
of a "catch" or "finally" block.
As well as providing a handy syntax for this useful behaviour, this module also serves to contain a
number of code examples for how to implement parser plugins and manipulate optrees to provide new syntax
and behaviours for perl code.
KEYWORDS
try
try {
STATEMENTS...
}
...
A "try" statement provides the main body of code that will be invoked, and must be followed by either a
"catch" statement, a "finally" statement, or both.
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. What will
happen next depends on the presence of a "catch" or "finally" statement immediately following it.
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" and "finally")
are such that they are parsed as a self- contained statement. Because of this, there is no need to end
with a terminating semicolon.
Note (especially to users of Try::Tiny and similar) that the "try {}" block itself does not necessarily
stop exceptions thrown inside it from propagating outside. It is the presence of a later "catch {}" block
which causes this to happen. A "try" with only a "finally" and no "catch" will still propagate exceptions
up to callers as normal.
catch
...
catch {
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. The "catch" block can inspect the raised exception
by looking in $@ in the usual way.
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.
If a "catch" statement is not given, then any exceptions raised by the "try" block are raised to the
caller in the usual way.
finally
...
finally {
STATEMENTS...
}
A "finally" statement provides a block of code to the preceding "try" statement (or "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.
TODO
• Value semantics. It would be nice if a "do {}"-wrapped "try" set could yield a value, in the way other
similar constructs can. For example
my $x = do {
try { attempt(); "success" }
catch { "failure" }
};
A workaround for this current lack is to wrap the "try{} catch{}" pair in an anonymous function which
is then immediately executed:
my $x = sub {
try { attempt(); return "success" }
catch { return "failure" }
}->();
See also <https://rt.cpan.org/Ticket/Display.html?id=121267>.
OTHER MODULES
There are already quite a number of modules on CPAN that provide a "try/catch"-like syntax for Perl.
• Try
• TryCatch
• Try::Tiny
• Syntax::Feature::Try
They are compared here, by feature:
True syntax plugin
Like Try and Syntax::Feature::Try, this module is implemented as a true syntax plugin, allowing it to
provide new parsing rules not available to simple functions. Most notably here it means that the
resulting combination does not need to end in a semicolon.
In comparison, Try::Tiny is plain perl and provides its functionality using regular perl functions; as
such its syntax requires the trailing semicolon.
TryCatch is a hybrid that uses Devel::Declare to parse the syntax tree.
@_ in a try or catch block
Because the "try" and "catch" block code is contained in a true block rather than an entire anonymous
subroutine, invoking it does not interfere with the @_ arguments array. Code inside these blocks can
interact with the containing function's array as before.
This feature is unique among these modules; none of the others listed have this ability.
"return" in a try or catch block
Like TryCatch and Syntax::Feature::Try, the "return" statement has its usual effect within a subroutine
containing syntax provided by this module. Namely, it causes the containing "sub" itself to return.
In comparison, using Try or Try::Tiny mean that a "return" statement will only exit from the "try" block.
"next"/"last"/"redo" in a try or catch block
The loop control keywords of "next", "last" and "redo" have their usual effect on dynamically contained
loops.
Syntax::Feature::Try documents that these do not work there. The other modules make no statement either
way.
Value Semantics
Like Try and Syntax::Feature::Try, the syntax provided by this module only works as a syntax-level
statement and not an expression; you cannot assign from the result of a "try" block. Additionally, final-
expression value semantics do not work, so it cannot be contained by a "do" block to yield this value.
See above for a workaround involving an anonymous sub however.
In comparison, the behaviour implemented by Try::Tiny can be used as a valued expression, such as
assigned to a variable or returned to the caller of its containing function.
"try" without "catch"
Like Syntax::Feature::Try, the syntax provided by this module allows a "try" block to be followed by only
a "finally" block, with no "catch". In this case, exceptions thrown by code contained by the "try" are
not suppressed, instead they propagate as normal to callers. This matches the behaviour familiar to Java
or C++ programmers.
In comparison, the code provided by Try and Try::Tiny always suppress exception propagation even without
an actual "catch" block.
The TryCatch module does not allow a "try" block not followed by "catch".
Typed "catch"
Like Try and Try::Tiny, this module makes no attempt to perform any kind of typed dispatch to distinguish
kinds of exception caught by "catch" blocks.
TryCatch and Syntax::Feature::Try both attempt to provide a kind of typed dispatch where different
classes of exception are caught by different blocks of code, or propagated up entirely to callers.
The author considers the lack of such ability in this module to be a feature. That kind of dispatch on
type matching of a controlling expression is too useful a behaviour to be constrained to exception
catching. If the language is to provide such a facility, it should be more universally applicable as a
stand-alone independent ability.
KNOWN BUGS
Thread-safety at load time cannot be assured before perl 5.16
On perl versions 5.16 and above this module is thread-safe.
On perl version 5.14 this module is thread-safe provided that it is "use"d before any additional threads
are created.
However, when using 5.14 there is a race condition if this module is loaded late in the program startup,
after additional threads have been created. This leads to the potential for it to be started up multiple
times concurrently, which creates data races when modifying internal structures and likely leads to a
segmentation fault, either during load or soon after when more code is compiled.
As a workaround, for any such program that creates multiple threads, loads additional code (such as
dynamically-discovered plugins), and has to run on 5.14, it should make sure to
use Syntax::Keyword::Try;
early on in startup, before it spins out any additional threads.
(See also <https://rt.cpan.org/Public/Bug/Display.html?id=123547>)
ACKNOWLEDGEMENTS
With thanks to "Zefram", "ilmari" and others from "irc.perl.org/#p5p" for assisting with trickier bits of
XS logic.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
perl v5.26.1 2018-01-20 Syntax::Keyword::Try(3pm)