Skip to content

Latest commit

 

History

History
72 lines (48 loc) · 2.21 KB

catch.adoc

File metadata and controls

72 lines (48 loc) · 2.21 KB
Raw

catch

since version 2.1.0

This macro will execute its input if there was an error caught by a try macro. The macro catch can be used to handle errors in a macro file.

Jamal source
{@try {@include} file name is missing}{@catch there was an error}

will result in

output
there was an error

The general rule is that you should use the catch macro in the same scope where the try macro is used. However, it can also be used a bit more complex than that. Here are the detailed rules:

  • A catch executes the content if there was an error executing the last try on the same level as the catch, and it was not caught yet by another catch on the same level.

  • A catch executes the content is there was an error executing a try on a higher level, and it was not caught by another catch on the same or higher level as the catch is and there was no non-failing try.

  • A catch executing clears the error on the level where the catch is.

  • Errors are automatically cleared when a scope closes.

These rules may seem complex, but it is easy to understand if you know how the error handling is implemented.

The error handling is implemented using the option try$caught$error. When an error is detected by a try macro, this option is set. If there is no error, then the option is reset, hence clearing any error on the same level. When catch is executed, it checks the value of the option and resets it. When executing in a nested scope, the reset will not clear the error on the higher level.

The name of the option was chosen to be user-friendly so that you can

  • export it to higher scopes,

  • query its value, presumably in an if macro,

  • set and reset it using the options macro.

Here is a simple example that uses this option by the name directly:

Jamal source
{@try {@include}}{#if/{try$caught$error}/there was an error}
{#if/{try$caught$error}/still there is an error, not cleared}{@catch}
{#if/{try$caught$error}/no, this one will not be displayed/error cleared}

will result in

output
there was an error
still there is an error, not cleared
error cleared