++ed by:
ADAMJS DBOOK KES ABRAXXA TEAM

7 PAUSE users
1 non-PAUSE user.

Paul Evans

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.

catch

   ...
   catch {
      STATEMENTS...
   }

A catch statement provides a block of code to the preceeding 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 preceeding 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 preceeding 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 preceeding 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" }
     }->();

OTHER MODULES

There are already quite a number of modules on CPAN that provide a try/catch-like syntax for Perl.

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.

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.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>