Errors

Error Messages
Error Details
Methods

An error object, err, can be returned by a function to indicate failure.

$err() -> err $err(message: any) -> err $err(format_string: str, *args: any) -> err: Creates a new err object. Every err object has a message string and a details map.

If called with no arguments, returns a new err object with an empty message string.

If called with a single argument, stringifies that argument and uses the result as the error's message string.

Calling this function with more than one argument is equivalent to calling $fmt() on those arguments first and using the result as the error's message string.

You can use the $is_err(arg) function to check if a value is an err. Alternatively, you can use the error-coalescing operator !! to supply a default value for an operation that might return an error, e.g.

var result = might_fail() !! "default";

Error Messages

Stringifying an err returns its message string, e.g.

var err = $err("oh no!");

assert $str(err) == "oh no!";
assert err:message() == "oh no!";

Error Details

An err object contains a details map which you can use to store arbitrary data about the error. You can index into this details map directly on the err object itself, e.g.

var err = $err("oh no!");
err["code"] = 123;

assert $str(err) == "oh no!";
assert err["code"] == 123;

var details = err:details();
assert details["code"] == 123;

The details map of an err object returned by a panicking try expression contains "source" and "line" entries specifying the source ID and line number of the panic, e.g.

var result = try might_panic();

if $is_err(result) {
    echo "source:", result["source"];
    echo "line:", result["line"];
    echo "message:", result;
}

Methods

:details() -> map: Returns the error's details map.
:message() -> str: Returns the error's message string.