errors

std/errors — building and adding to error values.

An error in Kite is an ordinary value: nil, or something describing a failure. errors.new is a compiler builtin because constructing one is the only thing that needs to be; everything else is written here.

• wrap
• of
• chain
• root
• mentions
• message_or

wrap

pub fn wrap(err: error, context: str) -> error

err with context in front of it, or nil when err is nil.

Returning nil for nil is what lets this compose with check directly:

let (bytes, err) = fs.read(path)
check errors.wrap(err, "loading config from \(path)")

of

pub fn of(subject: str, problem: str) -> error

An error whose message is built from parts, for a caller that would otherwise interpolate into errors.new at every site.

chain

pub fn chain(err: error) -> [str]

Every message in the chain, outermost first.

wrap keeps what it wrapped, so a failure that crossed four layers reads as the four sentences that produced it rather than one run-on line.

// Unqualified because this example is compiled inside this module, where
// its siblings are in scope by name. A caller writes `errors.chain(…)`.
let outer = wrap(errors.new("no such file"), "loading config")
io.print(join(chain(outer), " <- "))

root

pub fn root(err: error) -> error

The innermost failure — what actually went wrong, under the context.

mentions

pub fn mentions(err: error, needle: str) -> bool

Whether an error's message mentions needle.

Weaker than naming a type — NotFound.is(err) asks the question this approximates — and still here for the errors that carry no type of their own, which is every one built by errors.new.

message_or

pub fn message_or(err: error, absent: str) -> str

The message, or a stand-in for nil, so a caller can print without testing.