ex:error-safe

Notation

The ex: prefix used in this document is bound to the namespace URI http://www.fgeorges.org/exslt2. The notation of the elements and functions is similar to the notation used in [XSLT20].

Element Syntax

<ex:error-safe>
  <!-- Content: (ex:try, ex:catch+) -->
</ex:error-safe>

<ex:try>
  <!-- Content: (sequence-constructor) -->
</ex:try>

<ex:catch
  errors? = NameTest+>
  <!-- Content: (sequence-constructor) -->
</ex:catch>

Description

ex:error-safe can appear as a member of any sequence constructor. Its purpose is to catch errors thrown by the standard XPath function error^FO, or by the implementation in case of standard errors. That behaviour provides a mechanism similar to the exception model found in many other languages, such as Java, C++ or Common Lisp for instances.

The evaluation of ex:error-safe instruction begins by evaluating the sequence-constructor within the ex:try. If there is no error while evaluating it, the result of the whole ex:error-safe instruction is the sequence obtained as result of evaluating the ex:try. If there was an error, an error handler is looked for. If no one is found, the error is propagated outside the ex:error-safe (it will maybe be caught by another ex:error-safe higher in the evaluation stack). If an error handler is found, its associated sequence-constructor is evaluated and the resulting sequence becomes the result of the whole ex:error-safe.

[Definition: The element ex:catch defines an error handler. An error handler is composed of an error matching list and a sequence constructor. The error matching list is the content of the errors attribute and is a whitespace-separated list of one or more NameTest^XP.]

How is an error handler looked for when an error is raised while the evaluation of an ex:try? The error is identified by a QName (see error^FO). The several error handlers that are siblings of the ex:try are considered in sequence, in the same order they appear in the stylesheet. An error hanlder matches an error iff one of the NameTest of its error matching list matches the QName of the error (with the usual XPath rules defining when a NameTest matches a QName). The first error handler that matches the error is the matching error handler (its following siblings are not tested for matching).

Function Syntax

ex:current-error() as item()+

Description

This function is aimed to return information about the error currently caught. Its first item is a parentless element node whose the structure is defined below. The following items, if any, are the sequence passed as the $error-object parameter of the fourth signature of the XPath function error^FO.

The structure of the first item, an element, is as follow:

<error name="QName">
  <description>The description passed to the error function</description>
  <!-- zero or more implementation-defined nodes -->
</error>

Editor's notes

Think about the way to use this instruction in a portable way (is there a way to tell other processors to evaluate only the content of the ex:try?)

Describe the URI used to catch Java exceptions.