Documentation channel: v0.0.5 at compiler commit 2c9c7e8. The latest tagged release is v0.0.5; pages identify APIs that are new in v0.0.5.

Errors

Checked error types are part of a function signature. A function either handles a checked error or declares that it may propagate it.

Use the checked-error types exposed by the API that can fail, such as HttpError, SqliteError, NetworkError, and FilesystemError, or declare an application-specific error with error Name { ... }. strut api --json lists the contracts for built-in APIs.

Custom checked errors

A custom error is nominal: only values declared with error can appear in checked-error contracts, throw, and typed catches. The first runtime model standardizes optional message and code payload fields; other fields remain useful to the declaring type but are not yet preserved by a caught runtime payload.

error ValidationError {
    string message;
    int code;
}

function validate(int value) -> int : ValidationError {
    if (value < 0) {
        throw ValidationError { message: "negative value", code: 42 };
    }
    return value;
}

function main() -> int {
    try {
        validate(-1);
    } catch (ValidationError err) {
        println(err.message);
        println(err.code);
    }
    return 0;
}

Across a module boundary

Error declarations and checked-error contracts remain nominal when imported from another source module. Here module-error.h declares ModuleError and module_failure; this calling source is compiled and run by the documentation suite.

include "module-error.h";

function main() -> int {
    try {
        module_failure();
    } catch (ModuleError err) {
        println(err.message);
        println(err.code);
    }
    return 0;
}

Declare checked errors

function load(string path) -> Config : IOError {
    // ...
}

Declare multiple errors

function load(string path) -> Config : (IOError, ParseError) {
    // ...
}

Throw

throw IOError("could not read configuration");

Try and typed catch

try {
    config := load("config.json");
} catch (IOError err) {
    err << "I/O failure" << endl;
} catch (ParseError err) {
    err << "invalid configuration" << endl;
}

Catch all

try {
    risky();
} catch {
    err << "operation failed" << endl;
}

Checked errors in function values

A checked-error set is part of a callable's static type, so function and future values preserve it. A named function function risky() -> int : AppError used as a value has type function<() -> int : AppError>.

function<() -> int : AppError> op := risky;
function<() -> int : AppError> allowed := op;  // accepted
function<() -> int> denied := op;               // rejected: AppError is not allowed

Assigning or passing a callable is accepted only when its actual escaping errors are a subset of the destination's allowed errors (actual ⊆ allowed). A non-throwing callable fits any slot; a throwing callable does not fit a narrower one.

Method checked errors propagate the same way through obj.method(), ptr->method(), reference receivers, this.method(), and bare same-owner calls, using the method's declaring owner.

Async checked errors

For an async function the declared checked errors are await-time effects and live inside the returned future type:

async function fetch() -> int : HttpError { /* ... */ }

// fetch() itself requires no synchronous HttpError;
// the returned value has type future<int : HttpError>.

Calling fetch() therefore does not require HttpError, but the resulting future<int : HttpError> does not fit a plain future<int> slot.

Overloaded function values

When a name has multiple overloads, a function value needs enough expected-type context to select one overload. Without it the value is ambiguous rather than resolved by declaration order.

function parse(int x) -> int : AppError { /* ... */ }
function parse(string x) -> string : ParseError { /* ... */ }

function<(int)->int : AppError> as_int := parse;      // selects the int overload
function<(string)->string : ParseError> as_str := parse;  // selects the string overload
// f := parse;  // rejected: ambiguous, provide an expected function type

Extern C function values

Taking an extern "C" function as a value requires an unsafe block, the same as calling it directly.

Strut currently favours explicit handling or explicit propagation in the signature rather than adding a separate terse propagation token before its behaviour is justified by real code.