Struct snafu::Report

pub struct Report<E>(/* private fields */);

Opinionated solution to format an error in a user-friendly way. Useful as the return type from main and test functions.

Most users will use the snafu::report procedural macro instead of directly using this type, but you can if you do not wish to use the macro.

Rust 1.61 and up

Change the return type of the function to Report and wrap the body of your function with Report::capture.

Rust before 1.61

Use Report as the error type inside of Result and then call either Report::capture_into_result or Report::from_error.

Nightly Rust

Enabling the unstable-try-trait feature flag will allow you to use the ? operator directly:

use snafu::{prelude::*, Report};

fn main() -> Report<PlaceholderError> {
    let _v = may_fail_with_placeholder_error()?;

    Report::ok()
}

Interaction with the Provider API

If you return a Report from your function and enable the unstable-provider-api feature flag, additional capabilities will be added:

1. If provided, a Backtrace will be included in the output.
2. If provided, a ExitCode will be used as the return value.

Stability of the output

The exact content and format of a displayed Report are not stable, but this type strives to print the error and as much user-relevant information in an easily-consumable manner

Implementations

impl<E> Report<E>

pub fn from_error(error: E) -> Self

Convert an error into a Report.

Recommended if you support versions of Rust before 1.61.

use snafu::{prelude::*, Report};

#[derive(Debug, Snafu)]
struct PlaceholderError;

fn main() -> Result<(), Report<PlaceholderError>> {
    let _v = may_fail_with_placeholder_error().map_err(Report::from_error)?;
    Ok(())
}

fn may_fail_with_placeholder_error() -> Result<u8, PlaceholderError> {
    Ok(42)
}

pub fn capture_into_result<T>( body: impl FnOnce() -> Result<T, E>, ) -> Result<T, Self>

Executes a closure that returns a Result, converting the error variant into a Report.

Recommended if you support versions of Rust before 1.61.

use snafu::{prelude::*, Report};

#[derive(Debug, Snafu)]
struct PlaceholderError;

fn main() -> Result<(), Report<PlaceholderError>> {
    Report::capture_into_result(|| {
        let _v = may_fail_with_placeholder_error()?;

        Ok(())
    })
}

fn may_fail_with_placeholder_error() -> Result<u8, PlaceholderError> {
    Ok(42)
}

pub fn capture(body: impl FnOnce() -> Result<(), E>) -> Self

Executes a closure that returns a Result, converting any error to a Report.

Recommended if you only support Rust version 1.61 or above.

use snafu::{prelude::*, Report};

#[derive(Debug, Snafu)]
struct PlaceholderError;

fn main() -> Report<PlaceholderError> {
    Report::capture(|| {
        let _v = may_fail_with_placeholder_error()?;

        Ok(())
    })
}

fn may_fail_with_placeholder_error() -> Result<u8, PlaceholderError> {
    Ok(42)
}

pub const fn ok() -> Self

A Report that indicates no error occurred.

Trait Implementations

impl<E> Debug for Report<E>

where E: Error,

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

Formats the value using the given formatter.

impl<E> Display for Report<E>

where E: Error,

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

Formats the value using the given formatter.

impl<E> From<Result<(), E>> for Report<E>

fn from(other: Result<(), E>) -> Self

Converts to this type from the input type.