Catch Exceptions
================

{{#include ../links.md}}


When an [exception] is thrown via a [`throw`] statement, evaluation of the script halts and the
[`Engine`] returns with `EvalAltResult::ErrorRuntime` containing the exception value thrown.

It is possible, via the `try` ... `catch` statement, to _catch_ exceptions, optionally with an
_error variable_.

> `try` `{` ... `}` `catch` `{` ... `}`
>
> `try` `{` ... `}` `catch` `(` _error variable_ `)` `{` ... `}`

```js
// Catch an exception and capturing its value
try
{
    throw 42;
}
catch (err)         // 'err' captures the thrown exception value
{
    print(err);     // prints 42
}

// Catch an exception without capturing its value
try
{
    print(42/0);    // deliberate divide-by-zero exception
}
catch               // no error variable - exception value is discarded
{
    print("Ouch!");
}

// Exception in the 'catch' block
try
{
    print(42/0);    // throw divide-by-zero exception
}
catch
{
    print("You seem to be dividing by zero here...");

    throw "die";    // a 'throw' statement inside a 'catch' block
                    // throws a new exception
}
```


~~~admonish tip "Tip: Re-throw exception"

Like the `try` ... `catch` syntax in most languages, it is possible to _re-throw_ an exception
within the `catch` block simply by another [`throw`] statement without a value.

```js
try
{
    // Call something that will throw an exception...
    do_something_bad_that_throws();
}
catch
{
    print("Oooh! You've done something real bad!");

    throw;          // 'throw' without a value within a 'catch' block
                    // re-throws the original exception
}

```
~~~

```admonish success "Catchable exceptions"

Many script-oriented exceptions can be caught via `try` ... `catch`.

| Error type                                            |         Error value          |
| ----------------------------------------------------- | :--------------------------: |
| Runtime error thrown by a [`throw`] statement         | value in [`throw`] statement |
| Arithmetic error                                      |         [object map]         |
| [Variable] not found                                  |         [object map]         |
| [Function] not found                                  |         [object map]         |
| [Module] not found                                    |         [object map]         |
| Unbound `this`                                        |         [object map]         |
| Data type mismatch                                    |         [object map]         |
| Assignment to a calculated/[constant] value           |         [object map]         |
| [Array]/[string]/[bit-field] indexing out-of-bounds   |         [object map]         |
| Indexing with an inappropriate data type              |         [object map]         |
| Error in property access                              |         [object map]         |
| [`for`] statement on a type without a [type iterator] |         [object map]         |
| Data race detected                                    |         [object map]         |
| Other runtime error                                   |         [object map]         |

The error value in the `catch` clause is an [object map] containing information on the particular error,
including its type, line and character position (if any), and source etc.

When the [`no_object`] feature is turned on, however, the error value is a simple [string] description.
```

```admonish failure "Non-catchable exceptions"

Some exceptions _cannot_ be caught.

| Error type                                                              | Notes                             |
| ----------------------------------------------------------------------- | --------------------------------- |
| System error – e.g. script file not found                         | system errors are not recoverable |
| Syntax error during parsing                                             | invalid script                    |
| [Custom syntax] mismatch error                                          | incompatible [`Engine`] instance  |
| Script evaluation metrics exceeding [limits][safety]                    | [safety] protection               |
| Script evaluation manually [terminated]({{rootUrl}}/safety/progress.md) | [safety] protection               |
```