Module error
Standard error handling types and traits for Yo.
Stability
unstable — the Error trait, AnyError, Exception and the IoExn
bundle are the core of every fallible API in std and their shapes are
settled. What is missing is the part a real error story needs and this one
does not have: ErrorChain and root_cause cannot be written today,
and it is a compiler defect rather than a design gap
(issues/self-trait-in-a-return-type-loses-the-trait-on-an-erased-receiver.md,
filed as #521). Both must store what source() returned as an AnyError,
and on a Dyn(Error) receiver that value's STATIC type has lost the
Error trait — so a caller can follow one link and print it, but cannot
store, re-erase, downcast or re-throw it. Spelling Dyn(Error) instead
of Dyn(SelfTrait) is not available either: Error is unbound inside its
own definition.
So source() exists and works one level deep, and the walk over it does
not. Freezing before that is decided would freeze a trait whose defining
use case is still blocked.
Types
Type-erased dynamic error type. Wraps any type implementing Error.
An error that adds a message to the one underneath it — Rust's
anyhow::Context / .context(...).
This is the type that makes Error.source worth having: nothing else in
the tree overrides it, so before this every error chain was one link long.
to_string renders the whole chain, innermost last:
e := Context.new(`while loading the config`, dyn(io_err));
println(e.to_string()); // while loading the config: no such file
Fields
| Name | Type | Description |
|---|---|---|
message | String | What was being attempted. |
cause | dyn(Error + ToString) | The error that caused it. |
Trait Implementations
impl(generic(T : Type), where(T <: ToString), T : (ToString))
impl(generic(T : Type), where(T <: ToString), T : (ToString), Format)
format : fn(self : Self, spec : str) -> StringRender self under spec. An unrecognised spec degrades to the plain
to_string() rendering rather than failing.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Self | |
spec | str |
Returns: String
impl(Context, ...)
impl(Context, ToString(...))
to_string : (Context) fn(self : Context) -> Stringimpl(Context, Error(...))
source : (Context) fn(self : Context) -> Option(dyn(Error + ToString))The error that caused this one, or .None at the root of the chain.
Rust's Error::source. Defaulted to .None, so an error with nothing
underneath it implements the trait by saying only what it is; a wrapper
overrides it to hand back what it wrapped. Walking the chain to the root
cause is not expressible yet — the returned Dyn loses the Error
trait on an erased receiver, so a caller can print one link but cannot
follow it (#521,
issues/self-trait-in-a-return-type-loses-the-trait-on-an-erased-receiver.md).
Parameters
| Name | Type | Notes |
|---|---|---|
self | Context |
Non-resumable exception handling effect record.
Use throw to raise an AnyError and abort the current computation.
throw is ctl(...) — handler body may contain unwind, and the
handler value is frame-bound (see plans/archive/EXPLICIT_EFFECTS.md §4).
Fields
| Name | Type | Description |
|---|---|---|
throw | fn(generic(ResumeType) error : dyn(Error + ToString)) -> ResumeType |
Creates a resumable exception effect record parameterized by the resume type.
Unlike Exception, the handler can return a value to resume the computation.
throw is still ctl(...) because the handler MAY choose to unwind;
regular fn returns are also valid via subtyping fn <: ctl.
Type Parameters
| Name | Type | Notes |
|---|---|---|
ResumeType | Type | comptime |
Traits / Modules
Standard error trait for typed error propagation.
All error types should implement this trait along with ToString.
Methods
source : fn(self : Self : (ToString)) -> Option(dyn( + ToString))The error that caused this one, or .None at the root of the chain.
Rust's Error::source. Defaulted to .None, so an error with nothing
underneath it implements the trait by saying only what it is; a wrapper
overrides it to hand back what it wrapped. Walking the chain to the root
cause is not expressible yet — the returned Dyn loses the Error
trait on an erased receiver, so a caller can print one link but cannot
follow it (#521,
issues/self-trait-in-a-return-type-loses-the-trait-on-an-erased-receiver.md).
Parameters
| Name | Type | Notes |
|---|---|---|
self | Self : (ToString) |
Implementors
Functions
True when the type-erased err is really a T — Rust's dyn Error::is.
A FREE function rather than a method because a blanket inherent method over
E <: Error resolves on a Dyn(Error) receiver and then miscompiles: codegen
treats every method call on a Dyn value as a trait method and emits a
vtable indirection for a slot that does not exist. See
issues/blanket-inherent-method-on-a-dyn-receiver-dispatches-through-the-vtable.md;
when that is fixed this becomes err.is(T).
cond(
error_is(err, NotFound) => recover(),
true => rethrow(err)
);
To use the value and not just test for it, reach for the downcast(err, T)
builtin this is written over — it returns Option(T).
Parameters
| Name | Type | Notes |
|---|---|---|
err | AnyError | |
T | Type | comptime |
Returns: bool