Source code
Revision control
Copy as Markdown
Other Tools
//! Allows non-fatal errors in a tree of subfunctions to easily be collected by a caller
//!
//! Provides the [`error_graph::ErrorList<E>`][ErrorList] type to hold a list of non-fatal errors
//! that occurred while a function was running.
//!
//! It has a [`subwriter()`][WriteErrorList::subwriter] method that can be passed as a parameter to
//! a subfunction and allows that subfunction to record all the non-fatal errors it encounters.
//! When the subfunction is done running, its error list will be mapped to the caller's error type
//! and added to the caller's [ErrorList] automatically.
//!
//! Since subfunctions may in-turn also use the [`subwriter()`][WriteErrorList::subwriter]
//! function on the writter given to them by their caller, this creates a tree of non-fatal errors
//! that occurred during the execution of an entire call graph.
//!
//! # Usage
//!
//! ```
//! # use error_graph::{ErrorList, WriteErrorList, strategy::{DontCare, ErrorOccurred}};
//! enum UpperError {
//! Upper,
//! Middle(ErrorList<MiddleError>),
//! }
//! enum MiddleError {
//! Middle,
//! Lower(ErrorList<LowerError>),
//! }
//! enum LowerError {
//! Lower,
//! }
//! fn upper() {
//! let mut errors = ErrorList::default();
//! errors.push(UpperError::Upper);
//! // Map the ErrorList<MiddleError> to our UpperError::Middle variant
//! middle(errors.subwriter(UpperError::Middle));
//! errors.push(UpperError::Upper);
//!
//! // Some callers just don't want to know if things went wrong or not
//! middle(DontCare);
//!
//! // Some callers are only interested in whether an error occurred or not
//! let mut error_occurred = ErrorOccurred::default();
//! middle(&mut error_occurred);
//! if error_occurred.as_bool() {
//! errors.push(UpperError::Upper);
//! }
//! }
//! fn middle(mut errors: impl WriteErrorList<MiddleError>) {
//! // We can pass a sublist by mutable reference if we need to manipulate it before and after
//! let mut sublist = errors.sublist(MiddleError::Lower);
//! lower(&mut sublist);
//! let num_errors = sublist.len();
//! sublist.finish();
//! if num_errors > 10 {
//! errors.push(MiddleError::Middle);
//! }
//! // We can pass a reference directly to our error list for peer functions
//! middle_2(&mut errors);
//! }
//! fn middle_2(mut errors: impl WriteErrorList<MiddleError>) {
//! errors.push(MiddleError::Middle);
//! }
//! fn lower(mut errors: impl WriteErrorList<LowerError>) {
//! errors.push(LowerError::Lower);
//! }
//! ```
//!
//! # Motivation
//!
//! In most call graphs, a function that encounters an error will early-return and pass an
//! error type to its caller. The caller will often respond by passing that error further up the
//! call stack up to its own caller (possibly after wrapping it in its own error type). That
//! continues so-on-and-so-forth until some caller finally handles the error, returns from `main`,
//! or panics. Ultimately, the result is that some interested caller will receive a linear chain of
//! errors that led to the failure.
//!
//! But, not all errors are fatal -- Sometimes, a function might be able to continue working after
//! it encounters an error and still be able to at-least-partially achieve its goals. Calling it
//! again - or calling other functions in the same API - is still permissible and may also result
//! in full or partial functionality.
//!
//! In that case, the function may still choose to return `Result::Ok`; however, that leaves the
//! function with a dilemma -- How can it report the non-fatal errors to the caller?
//!
//! 1. **Return a tuple in its `Result::Ok` type**: that wouldn't capture the non-fatal errors in
//! the case that a fatal error occurs, so it would also have to be added to the `Result::Err`
//! type as well.
//!
//! That adds a bunch of boilerplate, as the function needs to allocate the list and map it
//! into the return type for every error return and good return. It also makes the function
//! signature much more noisy.
//!
//! 2. **Take a list as a mutable reference?**: Better, but now the caller has to allocate the
//! list, and there's no way for it to opt out if it doesn't care about the non-fatal errors.
//!
//! 3. **Maybe add an `Option` to it?** Okay, so a parameter like `errors: Option<&mut Vec<E>>`?
//! Getting warmer, but now the child has to do a bunch of
//! `if let Some(v) = errors { v.push(error); }` all over the place.
//!
//! And what about the caller side of it? For a simple caller, the last point isn't too bad: The
//! caller just has to allocate the list, pass `Some(&mut errors)` to the child, and check it upon
//! return.
//!
//! But often, the caller itself is keeping its own list of non-fatal errors and may also be a
//! subfunction to some other caller, and so-on-and-so-forth. In this case, we no longer have
//! a simple chain of errors, but instead we have a tree of errors -- Each level in the tree
//! contains all the non-fatal errors that occurred during execution of a function and all
//! subfunctions in its call graph.
//!
//! # Solution
//!
//! The main behavior we want is captured by the [WriteErrorList] trait in this crate. It can be
//! passed as a parameter to any function that wants to be able to report non-fatal errors to its
//! caller, and it gives the caller flexibility to decide what it wants to do with that
//! information.
//!
//! The main concrete type in this crate is [ErrorList], which stores a list of a single type of
//! error. Any time a list of errors needs to be stored in memory, this is the type to use. It will
//! usually be created by the top-level caller using [ErrorList::default], and any subfunction will
//! give an [ErrorList] of its own error type to the `map_fn` that was passed in by its caller upon
//! return.
//!
//! However, [ErrorList] should rarely be passed as a parameter to a function, as that wouldn't
//! provide the caller with the flexiblity to decide what strategy it actually wants
//! to use when collecting its subfunction's non-fatal errors. The caller may want to pass direct
//! reference to its own error list, it may want to pass a [Sublist] type that automatically
//! pushes the subfunction's error list to its own error list after mapping, or it may want to
//! pass the [DontCare] type if it doesn't want to know anything about the
//! subfunction's non-fatal errors.
//!
//! Instead, subfunctions should take `impl WriteErrorList<E>` as a parameter.
//! This allows any of those types above, as well as mutable references to those types, to be
//! passed in by the caller. This also allows future caller strategies to be implemented, like
//! a caller that only cares how many non-fatal errors occurred but doesn't care about the details.
//!
//! # Serde
//!
//! (This section only applies if the `serde` feature is enabled)
//!
//! [ErrorList] implements the `Serialize` trait if the errors it contains do, and
//! likewise with the `Deserialize` trait. This means that if every error type in the tree
//! implements these traits then the entire tree can be sent over the wire and recreated elsewhere.
//! Very useful if the errors are to be examined remotely!
use {
std::{
error::Error,
fmt::{self, Debug, Display, Formatter},
},
strategy::*,
};
#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};
pub mod strategy;
/// Types that are capable of having errors and sublists of errors pushed onto them
///
/// This is the main trait that allows a function to record a list of non-fatal errors it
/// encounters during its execution. Generally, the [WriteErrorList::push] method will be used when
/// such an error occurs to record the error and any relevant information.
///
/// Often, a function will want to call a subfunction and add any non-fatal errors encountered
/// to its own list of errors. There are 2 strategies it could use:
///
/// 1. **Let the subfunction directly push onto its error list** For functions that are at the same
/// level of abstraction and use the same error type, it might make the most sense for them
/// to just share an error list. In this case, simply pass a mutable reference to the error
/// list. For any type that implements this trait, a mutable reference to it implements the
/// trait too. This allows a single function to be a composition of a bunch of functions that
/// each share a single flat error list.
///
/// 2. **Map the subfunction's error list to the caller** For a subfunction that is at a different
/// level of abstraction than the caller and uses its own error type, this makes the most sense;
/// consume the subfunction's entire error list and store it as a single error of the
/// caller's higher-level error type. Of course, those subfunctions may implement this same
/// strategy for subfunctions they call, creating a hierarchy of errors.
///
/// In this case, call the [WriteErrorList::subwriter()] function as a parameter to
/// the subfunction. If you need to manipulate the list after the subfunction has returned,
/// instead call [WriteErrorList::sublist] and pass a mutable reference as a parameter.
///
/// Function parameters should always prefer to take an object by this trait, and should rarely
/// take parameters as concrete types like [ErrorList] or [Sublist].
/// Doing so would prevent callers from being able to decide what strategy they want to use
/// to merge the subfunction's errors with its own, and would also prevent them from using the
/// [DontCare] call if they want to opt out of receiving non-fatal error information.
///
/// Passing by this trait may also help prevent logic errors: Directly passing a [Sublist] allows
/// the subfunction to query the contents of the list it's passed. Functions may incorrectly rely on
/// the fact that they are always passed an empty list, and will suddenly break if that assumption
/// doesn't hold.
pub trait WriteErrorList<E>: Sized + private::Sealed<E> {
/// Add an error to the list of errors
fn push(&mut self, error: E);
/// Create a new mapping error writer with this as its parent
///
/// Creates a error writer for use by a subfunction. When the subfunction is finished,
/// either by explicitly calling [WriteErrorList::finish] or by letting it drop, the list
/// of errors it has written using [WriteErrorList::push] will be passed as an
/// [`ErrorList<SubErr>`][ErrorList] to the given `map_fn`, which is expected to map it to
/// our error type, `E`.
///
/// Use of this function should always be preferred to [WriteErrorList::sublist] when the
/// caller does not need to inspect or manipulate the list returned by the subfunction and
/// simply wants to pass it upward to its own caller, as this function will pass forward
/// alternate strategies for collecting the errors, like [DontCare] (which turns
/// [WriteErrorList::push] into a no-op). In constrast, [WriteErrorList::sublist] actually
/// materializes a list that will collect all the errors of all the lists below it, even
/// if the caller above it passed in a [DontCare].
fn subwriter<'sub, SubMapFn, SubErr: 'sub>(
&'sub mut self,
map_fn: SubMapFn,
) -> impl WriteErrorList<SubErr> + 'sub
where
SubMapFn: FnOnce(ErrorList<SubErr>) -> E + 'sub;
/// Start a new error list with this error list as its parent
///
/// This works in a very similar manner to [WriteErrorList::subwriter], but it materializes
/// an actual concrete [Sublist] type. This function
/// should only be used if the function needs to be able to inspect or manipulate the errors
/// returned by the subfunction, as it always collects all errors written by the subfunction's
/// call graph. Otherwise, [WriteErrorList::subwriter] should be used.
fn sublist<SubMapFn, SubErr>(
&mut self,
map_fn: SubMapFn,
) -> Sublist<'_, SubErr, SubMapFn, Self, E>
where
SubMapFn: FnOnce(ErrorList<SubErr>) -> E,
{
Sublist::new(map_fn, self)
}
/// Finish this error list
///
/// This doesn't normally need to be called, as the [Drop] implementation will take care of
/// all the details of cleaning up and ensuring that sublists are mapped up to their parent.
///
/// This is mostly useful when a caller maintains a binding to a subfunction's error list
/// and passes it by mutable reference instead of by value. Before the caller can continue
/// to use its own error list, the sublist must release its exclusive reference.
///
/// This function simply calls [drop()], but it's just a bit more clear about the intent.
fn finish(self) {
drop(self)
}
}
impl<E, T: WriteErrorList<E>> private::Sealed<E> for &mut T {}
impl<E, T: WriteErrorList<E>> WriteErrorList<E> for &mut T {
fn push(&mut self, error: E) {
WriteErrorList::push(*self, error)
}
fn subwriter<'sub, SubMapFn, SubErr: 'sub>(
&'sub mut self,
map_fn: SubMapFn,
) -> impl WriteErrorList<SubErr> + 'sub
where
SubMapFn: FnOnce(ErrorList<SubErr>) -> E + 'sub,
{
WriteErrorList::subwriter(*self, map_fn)
}
}
/// The main type that holds a list of errors.
///
/// See the module-level docs and the docs for [WriteErrorList].
#[derive(Debug, Eq, Hash, PartialEq)]
pub struct ErrorList<E> {
errors: Vec<E>,
}
#[cfg(feature = "serde")]
impl<E: Serialize> Serialize for ErrorList<E> {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
Serialize::serialize(&self.errors, serializer)
}
}
#[cfg(feature = "serde")]
impl<'de, E: Deserialize<'de>> Deserialize<'de> for ErrorList<E> {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
Ok(ErrorList {
errors: Deserialize::deserialize(deserializer)?,
})
}
}
impl<E> ErrorList<E> {
/// Returns whether the error list is empty
pub fn is_empty(&self) -> bool {
self.errors.is_empty()
}
/// Return the length of the error list
pub fn len(&self) -> usize {
self.errors.len()
}
/// Iterate the error list, returning immutable references
pub fn iter<'a>(&'a self) -> impl Iterator<Item = &'a E>
where
E: 'a,
{
self.errors.iter()
}
/// Iterate the error list, returning mutable references
pub fn iter_mut<'a>(&'a mut self) -> impl Iterator<Item = &'a mut E>
where
E: 'a,
{
self.errors.iter_mut()
}
}
impl<E> private::Sealed<E> for ErrorList<E> {}
impl<E> WriteErrorList<E> for ErrorList<E> {
fn push(&mut self, error: E) {
self.errors.push(error);
}
fn subwriter<'sub, SubMapFn, SubErr: 'sub>(
&'sub mut self,
map_fn: SubMapFn,
) -> impl WriteErrorList<SubErr> + 'sub
where
SubMapFn: FnOnce(ErrorList<SubErr>) -> E + 'sub,
{
self.sublist(map_fn)
}
}
impl<E> Default for ErrorList<E> {
fn default() -> Self {
Self { errors: Vec::new() }
}
}
impl<E: Error> Display for ErrorList<E> {
fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
writeln!(f, "one or more errors occurred:")?;
writeln!(f)?;
for (i, e) in self.errors.iter().enumerate() {
writeln!(f, " {i}:")?;
for line in e.to_string().lines() {
writeln!(f, " {line}")?;
}
writeln!(f)?;
let mut source = e.source();
while let Some(e) = source {
writeln!(f, " caused by:")?;
for line in e.to_string().lines() {
writeln!(f, " {line}")?;
}
writeln!(f)?;
source = e.source();
}
}
Ok(())
}
}
impl<E: Error> Error for ErrorList<E> {}
impl<E> IntoIterator for ErrorList<E> {
type Item = <Vec<E> as IntoIterator>::Item;
type IntoIter = <Vec<E> as IntoIterator>::IntoIter;
fn into_iter(self) -> Self::IntoIter {
self.errors.into_iter()
}
}
mod private {
/// Prevent users of this crate from implementing traits for their own types
pub trait Sealed<E> {}
}