Struct miette::Report

pub struct Report { /* private fields */ }

Core Diagnostic wrapper type.

eyre Users

You can just replace uses of eyre::Report with miette::Report.

Implementations

impl Report

pub fn new<E>(error: E) -> Selfwhere
    E: Diagnostic + Send + Sync + 'static,

Create a new error object from any error type.

The error type must be thread safe and 'static, so that the Report will be as well.

If the error type does not provide a backtrace, a backtrace will be created here to ensure that a backtrace exists.

pub fn msg<M>(message: M) -> Selfwhere
    M: Display + Debug + Send + Sync + 'static,

Create a new error object from a printable error message.

If the argument implements std::error::Error, prefer Report::new instead which preserves the underlying error’s cause chain and backtrace. If the argument may or may not implement std::error::Error now or in the future, use miette!(err) which handles either way correctly.

Report::msg("...") is equivalent to miette!("...") but occasionally convenient in places where a function is preferable over a macro, such as iterator or stream combinators:

use futures::stream::{Stream, StreamExt, TryStreamExt};
use miette::{Report, Result};

async fn demo<S>(stream: S) -> Result<Vec<Output>>
where
    S: Stream<Item = Input>,
{
    stream
        .then(ffi::do_some_work) // returns Result<Output, &str>
        .map_err(Report::msg)
        .try_collect()
        .await
}

pub fn wrap_err<D>(self, msg: D) -> Selfwhere
    D: Display + Send + Sync + 'static,

Create a new error from an error message to wrap the existing error.

For attaching a higher level error message to a Result as it is propagated, the crate::WrapErr extension trait may be more convenient than this function.

The primary reason to use error.wrap_err(...) instead of result.wrap_err(...) via the WrapErr trait would be if the message needs to depend on some data held by the underlying error:

pub fn context<D>(self, msg: D) -> Selfwhere
    D: Display + Send + Sync + 'static,

Compatibility re-export of wrap_err for interop with anyhow

pub fn chain(&self) -> Chain<'_>

An iterator of the chain of source errors contained by this Report.

This iterator will visit every error in the cause chain of this error object, beginning with the error that this error object was created from.

Example

use miette::Report;
use std::io;

pub fn underlying_io_error_kind(error: &Report) -> Option<io::ErrorKind> {
    for cause in error.chain() {
        if let Some(io_error) = cause.downcast_ref::<io::Error>() {
            return Some(io_error.kind());
        }
    }
    None
}

pub fn root_cause(&self) -> &(dyn StdError + 'static)

The lowest level cause of this error — this error’s cause’s cause’s cause etc.

The root cause is the last error in the iterator produced by chain().

pub fn is<E>(&self) -> boolwhere
    E: Display + Debug + Send + Sync + 'static,

Returns true if E is the type held by this error object.

For errors constructed from messages, this method returns true if E matches the type of the message D or the type of the error on which the message has been attached. For details about the interaction between message and downcasting, see here.

pub fn downcast<E>(self) -> Result<E, Self>where
    E: Display + Debug + Send + Sync + 'static,

Attempt to downcast the error object to a concrete type.

pub fn downcast_ref<E>(&self) -> Option<&E>where
    E: Display + Debug + Send + Sync + 'static,

Downcast this error object by reference.

Example

// If the error was caused by redaction, then return a tombstone instead
// of the content.
match root_cause.downcast_ref::<DataStoreError>() {
    Some(DataStoreError::Censored(_)) => Ok(Poll::Ready(REDACTED_CONTENT)),
    None => Err(error),
}

pub fn downcast_mut<E>(&mut self) -> Option<&mut E>where
    E: Display + Debug + Send + Sync + 'static,

Downcast this error object by mutable reference.

pub fn handler(&self) -> &dyn ReportHandler

Get a reference to the Handler for this Report.

pub fn handler_mut(&mut self) -> &mut dyn ReportHandler

Get a mutable reference to the Handler for this Report.

pub fn with_source_code(
    self,
    source_code: impl SourceCode + Send + Sync + 'static
) -> Report

Provide source code for this error

Trait Implementations

impl AsRef<dyn Diagnostic + 'static> for Report

fn as_ref(&self) -> &(dyn Diagnostic + 'static)

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<dyn Diagnostic + Send + Sync + 'static> for Report

fn as_ref(&self) -> &(dyn Diagnostic + Send + Sync + 'static)

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<dyn Diagnostic + 'static> for Report

fn borrow(&self) -> &(dyn Diagnostic + 'static)

Immutably borrows from an owned value.

impl Debug for Report

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for Report

type Target = dyn Diagnostic + Send + Sync + 'static

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Report

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Display for Report

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Report

fn drop(&mut self)

Executes the destructor for this type.

impl<E> From<E> for Reportwhere
    E: Diagnostic + Send + Sync + 'static,

fn from(error: E) -> Self

Converts to this type from the input type.

impl From<Report> for Box<dyn Diagnostic + 'static>

fn from(error: Report) -> Self

Converts to this type from the input type.

impl From<Report> for Box<dyn Diagnostic + Send + Sync + 'static>

fn from(error: Report) -> Self

Converts to this type from the input type.

impl From<Report> for Box<dyn StdError + 'static>

fn from(error: Report) -> Self

Converts to this type from the input type.

impl From<Report> for Box<dyn StdError + Send + Sync + 'static>

fn from(error: Report) -> Self

Converts to this type from the input type.