Add try-catch.

This commit is contained in:
Stephen Chung
2020-10-20 23:16:03 +08:00
parent 5ee9dfc5cd
commit 07bdb824fe
12 changed files with 343 additions and 35 deletions

View File

@@ -82,7 +82,8 @@ The Rhai Scripting Language
12. [For Loop](language/for.md)
13. [Return Values](language/return.md)
14. [Throw Exception on Error](language/throw.md)
15. [Functions](language/functions.md)
15. [Catch Exceptions](language/try-catch.md)
16. [Functions](language/functions.md)
1. [Call Method as Function](language/method.md)
2. [Overloading](language/overload.md)
3. [Namespaces](language/fn-namespaces.md)
@@ -90,11 +91,11 @@ The Rhai Scripting Language
5. [Currying](language/fn-curry.md)
6. [Anonymous Functions](language/fn-anon.md)
7. [Closures](language/fn-closure.md)
16. [Print and Debug](language/print-debug.md)
17. [Modules](language/modules/index.md)
17. [Print and Debug](language/print-debug.md)
18. [Modules](language/modules/index.md)
1. [Export Variables, Functions and Sub-Modules](language/modules/export.md)
2. [Import Modules](language/modules/import.md)
18. [Eval Statement](language/eval.md)
19. [Eval Statement](language/eval.md)
6. [Safety and Protection](safety/index.md)
1. [Checked Arithmetic](safety/checked.md)
2. [Sand-Boxing](safety/sandbox.md)

View File

@@ -21,6 +21,8 @@ Keywords List
| `break` | break out of loop iteration | | no | |
| `return` | return value | | no | |
| `throw` | throw exception | | no | |
| `try` | trap exception | | no | |
| `catch` | catch exception | | no | |
| `import` | import module | [`no_module`] | no | |
| `export` | export variable | [`no_module`] | no | |
| `as` | alias for variable export | [`no_module`] | no | |
@@ -55,8 +57,6 @@ Reserved Keywords
| `case` | matching |
| `public` | function/field access |
| `new` | constructor |
| `try` | trap exception |
| `catch` | catch exception |
| `use` | import namespace |
| `with` | scope |
| `module` | module |

View File

@@ -29,5 +29,24 @@ let result = engine.eval::<i64>(r#"
}
"#);
println!(result); // prints "Runtime error: 42 (line 5, position 15)"
println!("{}", result); // prints "Runtime error: 42 (line 5, position 15)"
```
Catch a Thrown Exception
------------------------
It is possible to _catch_ an exception instead of having it abort the evaluation
of the entire script via the [`try` ... `catch`]({{rootUrl}}/language/try-catch.md)
statement common to many C-like languages.
```rust
try
{
throw 42;
}
catch (err) // 'err' captures the thrown exception value
{
print(err); // prints 42
}
```

View File

@@ -0,0 +1,104 @@
Catch Exceptions
================
{{#include ../links.md}}
When an [exception] is thrown via a `throw` statement, evaluation of the script halts
and the [`Engine`] returns with `Err(Box<EvalAltResult::ErrorRuntime>)` containing the
exception value that has been thrown.
It is possible, via the `try` ... `catch` statement, to _catch_ exceptions.
```rust
// 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 catch 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
}
```
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.
```rust
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
}
```
Catchable Exceptions
--------------------
Many script-oriented exceptions can be caught via `try` ... `catch`:
* Runtime error thrown by a `throw` statement
* Arithmetic error
* Variable not found
* [Function] not found
* [Module] not found
* Unbound [`this`]
* Data type mismatch
* [Array]/[string] indexing out-of-bounds
* Indexing with an inappropriate type
* `for` statement without an iterator
* Error in an `in` expression
* Data race detected
* Assignment to a calculated value/constant value
* Dot expression error
Non-Catchable Exceptions
------------------------
Some exceptions _cannot_ be caught:
* Syntax error during parsing
* System error - e.g. script file not found
* Script evaluation over [limits]({{rootUrl}}/safety/index.md)
* [Stack overflow][maximum call stack depth]
* Script evaluation manually terminated

View File

@@ -89,6 +89,8 @@
[function overloading]: {{rootUrl}}/rust/functions.md#function-overloading
[fallible function]: {{rootUrl}}/rust/fallible.md
[fallible functions]: {{rootUrl}}/rust/fallible.md
[exception]: {{rootUrl}}/language/throw.md
[exceptions]: {{rootUrl}}/language/throw.md
[function pointer]: {{rootUrl}}/language/fn-ptr.md
[function pointers]: {{rootUrl}}/language/fn-ptr.md
[currying]: {{rootUrl}}/language/fn-curry.md