Today marks the official release of the v0.0.2 version of error-kind!
This is a project that initially started out as just some internal utility library, but needed to be factored out for formally releasing another project that I’m working on (similarly to typed-ident).
When releasing 0.0.1, I accidentally didn’t set the
README.mdproperly.It’s my first time publishing a set of crates from a workspace, so the fact that I need to explicitly set the readme caught me by surprise.
This is a very early alpha, v0.0.2 will happen as soon as I’m able to deliver it (after a short vacation to visit family). However, if you would like to play around with this early alpha, you can on crates.io now.
There’s still a lot that needs to be done here. Most importantly, I would like to verify that disabling collection of error diagnostics really compiles away the diagnostic code (that’s a key feature of this crate).
When I return from vacation in a few weeks, I’ll start taking a look at that. So it’s probably fine to experiment with this crate for now, but not depend on it heavily until those aspects are validated.
I just was a bit excited to get it out there to share, is all. :)
You can add the dependency by editing your Cargo.toml:
[dependencies]
error-kind = "0.0.2"
Or by using cargo add:
cargo add error-kind
The most basic usage of error-kind is with a simple error/kind combo.
use error_kind::{Err, Error, ErrorKind};
// The ErrorKind derive requires: `Copy`, `Clone`, and `Debug`.
// It implements `Display` and `ErrorKind` for us.
//
// You can supply more derives if you'd like, such as `PartialEq`.
#[derive(Copy, Clone, Debug, ErrorKind)]
pub enum MyErrorKind {
SomeFailure,
SomeOtherFailure,
// ...
}
#[derive(Clone, Debug, Error)]
pub struct MyError {
error_kind: MyErrorKind,
}
fn some_function(case: u32) -> Result<(), MyError> {
match case {
1 => Err!(MyErrorKind::SomeFailure, "dynamic details: {case}"),
2 => Err!(MyErrorKind::SomeOtherFailure),
_ => Ok(()),
}
}
// This will print:
// error: some failure
println!("error: {}", some_function(1).unwrap_err());
The power of this separation is that you can configure your crate to collect additional information without changing your error kind. This may, however, affect the size and runtime cost of the containing error.
For example, you can opt-into collection of dynamic error descriptions like this (requires alloc feature).
use error_kind::{Err, Error, ErrorKind};
#[derive(Copy, Clone, Debug, ErrorKind)]
pub enum MyErrorKind {
SomeFailure,
SomeOtherFailure,
// ...
}
#[derive(Clone, Debug, Error)]
pub struct MyError {
envelope: error_kind::envelopes::Described<MyErrorKind>,
}
fn some_function(case: u32) -> Result<(), MyError> {
match case {
1 => Err!(MyErrorKind::SomeFailure, "dynamic details: {case}"),
2 => Err!(MyErrorKind::SomeOtherFailure),
_ => Ok(()),
}
}
// Notice we only changed `MyError`?
// This will now print:
// error: some failure: dynamic details: 1
println!("error: {}", some_function(1).unwrap_err());
If you want your users to be able to inspect the error kind, I recommend giving them a function for that.
use error_kind::{Err, Error, ErrorKind};
#[derive(Copy, Clone, Debug, ErrorKind)]
pub enum MyErrorKind {
SomeFailure,
SomeOtherFailure,
// ...
}
#[derive(Clone, Debug, Error)]
pub struct MyError {
envelope: error_kind::envelopes::Described<MyErrorKind>,
}
impl MyError {
// Allow the end-user to inspect the error kind!
pub fn error_kind(&self) -> MyErrorKind {
use error_kind::envelopes::ErrorEnvelope;
self.envelope.error_kind()
}
}
See the full documentation to learn about all the different error envelopes, as well as more complex use-cases like composing and organizing related error kinds into ErrorDomains!
This is certainly not a comprehensive list. As mentioned, this is an early alpha crate.
I just wanted to share a few things I’m thinking about while delivering 0.0.2.
This is going to change.
Originally, I thought it would be nice to be strict about this. But now that I’m getting ready to release, I don’t see the point in being this strict.
If you want to nest some information in the error kind structure, that’s none of my business. I’m going to add this feature in the next version. For now, the derive macro explicitly checks that each variant is a unit variant.
(Though, you can still compose multiple error types together using ErrorDomain.)
use error_kind::ErrorKind;
#[derive(Copy, Clone, Debug, ErrorKind)]
pub enum MyErrorKind {
ThisWontWork(u32),
NeitherWillThis {
uh_oh: bool,
},
}
I’m not sure this is going to change… But maybe.
There’s definitely something more that I could do here to allow for other possibilities. For now, I just error out if you try to have multiple type parameters for your error type, and you try to register one or more error domains with it.
use error_kind::{Error, ErrorDomain, ErrorKind};
#[derive(Copy, Clone, Debug, ErrorKind)]
pub enum MyErrorKind {
Variant,
}
#[derive(Copy, Clone, Debug, ErrorDomain)]
pub enum MyErrorDomain {
Domain1(MyErrorKind),
}
// Can do this! :)
#[derive(Clone, Debug, Error)]
#[error(domains(MyErrorDomain))]
pub struct MyError1<K: ErrorKind> {
#[error_kind]
envelope: K,
value: bool,
}
// Can do this! :)
#[derive(Clone, Debug, Error)]
pub struct MyError2<K: ErrorKind, T> {
#[error_kind]
envelope: K,
value: T,
}
// Can't do this. :(
//
// The combination of #[error(domains())] and a generic
// with more than one type parameter is not allowed...
#[derive(Clone, Debug, Error)]
#[error(domains(MyErrorDomain))]
pub struct MyError3<K: ErrorKind, T> {
#[error_kind]
envelope: K,
value: T,
}
There’s an abstraction present over the description data passed into these types.
pub trait StaticString: sealed::Sealed + Sized + Send + Sync + 'static {
#[cfg(feature = "alloc")]
fn into_cow(self) -> Cow<'static, str>;
#[cfg(feature = "alloc")]
fn into_owned(self) -> String;
fn try_borrow(&self) -> Option<&'static str>;
}
This is intended to allow users to capture descriptions, even in no-alloc environments.
If the description passed in is a static string literal, this trait allows for returning that string, and thus for the surrounding envelope to capture the static reference.
However, this isn’t integrated into the code currently. I think there’s more that could be done with this trait.
Since this is the initial release, there are no iterative changes.
Thank you for taking a look at this project, and I hope you enjoy using it!