use error

Errors as values.

A fallible call reports failure through !, ?, or an if/switch arm, and the message and code it failed with live in a channel the arm reads with the err builtin. That channel hands back two loose values and empties itself as it is read, so what a program gets is a pair it cannot keep together: an error cannot be stored, returned, collected, or given context on the way past. Error is that pair as one ordinary value.

Read it first in the failure arm. err empties the channel, and the next fallible call clears it, so error::last has to run before anything else that can fail.

This module is a thin layer over the channel, not a replacement for it: raising is still panic, and a call site still says !, ?, or reads the result with if or switch.

Example:

use error

fn parse_port(s:str -- port:i64)! {
    "" == if { "port is empty" 1 panic }
    8080
}

fn main() {
    "" parse_port ok if {
        print nl
    } else {
        drop error::last <<message print nl
    }
}

Error

A failure: the code an if or switch arm matched on, the message panic was given, and the error this one was wrapped around, if there is one. Fields: code - the code passed to panic; 0 when nothing has failed message - the message passed to panic, with any wrapping context already composed in cause - the error this one wrapped, or null

Struct

Field Type Description
code i64
message str

Constructors

fn last

The error the last fallible call failed with, as one value. Reading empties the channel, so call this once, first, in the failure arm. With nothing to report it answers with code 0 and an empty message.

Signature: ( -- e:Error)

Output Type Description
e Error The error

Example:

error::last  // failure

fn new

Build an error without raising one, for a function that returns a failure as a value.

Signature: (msg:str code:i64 -- e:Error)

Parameter Type Description
msg str The message
code i64 The code
Output Type Description
e Error The error

Example:

"disk full" 5 error::new  // e

Methods

fn root

The error at the bottom of the cause chain -- the one that actually failed.

Signature: (e:Error) root( -- r:Error)

Output Type Description
r Error The root cause, or the error itself when it wrapped nothing

Example:

e error::root <<code  // original_code

fn wrap

Wrap an error in context from the frame that caught it. The wrapped error keeps the original's code, so a caller matching on it in a switch still matches; the message reads "context: original"; and cause holds the error wrapped. Re-raise the result with panic, which the compiler reads as diverging, so the arm needs nothing after it: e <<message e <<code panic.

Signature: (e:Error) wrap(msg:str -- wrapped:Error)

Parameter Type Description
msg str The context to add
Output Type Description
wrapped Error The wrapped error

Example:

e "cannot save the document" error::wrap  // wrapped