109 lines
4.9 KiB
Markdown
109 lines
4.9 KiB
Markdown
Catch Exceptions
|
|
================
|
|
|
|
When an [exception](throw.md) is thrown via a [`throw`](throw.md) statement, the script halts with
|
|
the exception value.
|
|
|
|
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`](throw.md) 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`](throw.md) statement | value in [`throw`](throw.md) statement |
|
|
| Arithmetic error | [object map](object-maps.md) |
|
|
| [Variable](variables.md) not found | [object map](object-maps.md) |
|
|
| [Function](functions.md) not found | [object map](object-maps.md) |
|
|
| [Module](modules/index.md) not found | [object map](object-maps.md) |
|
|
| Unbound `this` | [object map](object-maps.md) |
|
|
| Data type mismatch | [object map](object-maps.md) |
|
|
| Assignment to a calculated/[constant](constants.md) value | [object map](object-maps.md) |
|
|
| [Array](arrays.md)/[string](strings-chars.md)/[bit-field](bit-fields.md) indexing out-of-bounds | [object map](object-maps.md) |
|
|
| Indexing with an inappropriate data type | [object map](object-maps.md) |
|
|
| Error in property access | [object map](object-maps.md) |
|
|
| [`for`](for.md) statement on a type that is not iterable | [object map](object-maps.md) |
|
|
| Data race detected | [object map](object-maps.md) |
|
|
| Other runtime error | [object map](object-maps.md) |
|
|
|
|
The error value in the `catch` clause is an [object map](object-maps.md) containing information on
|
|
the particular error, including its type, line and character position (if any), and source etc.
|
|
```
|
|
|
|
```admonish failure "Non-catchable exceptions"
|
|
|
|
Some system 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 |
|
|
```
|