Trait cross::errors::Section

pub trait Section: Sealed {
    type Return;

    fn section<D>(self, section: D) -> Self::Return
    where
        D: Display + Send + Sync + 'static;
    fn with_section<D, F>(self, section: F) -> Self::Return
    where
        D: Display + Send + Sync + 'static,
        F: FnOnce() -> D;
    fn error<E>(self, error: E) -> Self::Return
    where
        E: Error + Send + Sync + 'static;
    fn with_error<E, F>(self, error: F) -> Self::Return
    where
        F: FnOnce() -> E,
        E: Error + Send + Sync + 'static;
    fn note<D>(self, note: D) -> Self::Return
    where
        D: Display + Send + Sync + 'static;
    fn with_note<D, F>(self, f: F) -> Self::Return
    where
        D: Display + Send + Sync + 'static,
        F: FnOnce() -> D;
    fn warning<D>(self, warning: D) -> Self::Return
    where
        D: Display + Send + Sync + 'static;
    fn with_warning<D, F>(self, f: F) -> Self::Return
    where
        D: Display + Send + Sync + 'static,
        F: FnOnce() -> D;
    fn suggestion<D>(self, suggestion: D) -> Self::Return
    where
        D: Display + Send + Sync + 'static;
    fn with_suggestion<D, F>(self, f: F) -> Self::Return
    where
        D: Display + Send + Sync + 'static,
        F: FnOnce() -> D;
}

A helper trait for attaching informational sections to error reports to be displayed after the chain of errors

Details

color_eyre provides two types of help text that can be attached to error reports: custom sections and pre-configured sections. Custom sections are added via the section and with_section methods, and give maximum control over formatting.

The pre-configured sections are provided via suggestion, warning, and note. These sections are displayed after all other sections with no extra newlines between subsequent Help sections. They consist only of a header portion and are prepended with a colored string indicating the kind of section, e.g. `Note: This might have failed due to …“

Required Associated Types

type Return

The return type of each method after adding context

Required Methods

fn section<D>(self, section: D) -> Self::Returnwhere
    D: Display + Send + Sync + 'static,

Add a section to an error report, to be displayed after the chain of errors.

Details

Sections are displayed in the order they are added to the error report. They are displayed immediately after the Error: section and before the SpanTrace and Backtrace sections. They consist of a header and an optional body. The body of the section is indented by default.

Examples

use color_eyre::{eyre::eyre, eyre::Report, Section};

Err(eyre!("command failed"))
    .section("Please report bugs to https://real.url/bugs")?;

fn with_section<D, F>(self, section: F) -> Self::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

Add a Section to an error report, to be displayed after the chain of errors. The closure to create the Section is lazily evaluated only in the case of an error.

Examples

use color_eyre::{eyre::eyre, eyre::Report, Section, SectionExt};

let output = std::process::Command::new("ls")
    .output()?;

let output = if !output.status.success() {
    let stderr = String::from_utf8_lossy(&output.stderr);
    Err(eyre!("cmd exited with non-zero status code"))
        .with_section(move || stderr.trim().to_string().header("Stderr:"))?
} else {
    String::from_utf8_lossy(&output.stdout)
};

println!("{}", output);

fn error<E>(self, error: E) -> Self::Returnwhere
    E: Error + Send + Sync + 'static,

Add an error section to an error report, to be displayed after the primary error message section.

Examples

use color_eyre::{eyre::eyre, eyre::Report, Section};
use thiserror::Error;

#[derive(Debug, Error)]
#[error("{0}")]
struct StrError(&'static str);

Err(eyre!("command failed"))
    .error(StrError("got one error"))
    .error(StrError("got a second error"))?;

fn with_error<E, F>(self, error: F) -> Self::Returnwhere
    F: FnOnce() -> E,
    E: Error + Send + Sync + 'static,

Add an error section to an error report, to be displayed after the primary error message section. The closure to create the Section is lazily evaluated only in the case of an error.

Examples

use color_eyre::{eyre::eyre, eyre::Report, Section};
use thiserror::Error;

#[derive(Debug, Error)]
#[error("{0}")]
struct StringError(String);

Err(eyre!("command failed"))
    .with_error(|| StringError("got one error".into()))
    .with_error(|| StringError("got a second error".into()))?;

fn note<D>(self, note: D) -> Self::Returnwhere
    D: Display + Send + Sync + 'static,

Add a Note to an error report, to be displayed after the chain of errors.

Examples

use color_eyre::Section as _;

fallible_fn().note("This might have failed due to ...")?;

fn with_note<D, F>(self, f: F) -> Self::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

Add a Note to an error report, to be displayed after the chain of errors. The closure to create the Note is lazily evaluated only in the case of an error.

Examples

use color_eyre::Section as _;

fallible_fn().with_note(|| {
        format!("This might have failed due to ... It has failed {} times", 100)
    })?;

fn warning<D>(self, warning: D) -> Self::Returnwhere
    D: Display + Send + Sync + 'static,

Add a Warning to an error report, to be displayed after the chain of errors.

fn with_warning<D, F>(self, f: F) -> Self::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

Add a Warning to an error report, to be displayed after the chain of errors. The closure to create the Warning is lazily evaluated only in the case of an error.

fn suggestion<D>(self, suggestion: D) -> Self::Returnwhere
    D: Display + Send + Sync + 'static,

Add a Suggestion to an error report, to be displayed after the chain of errors.

fn with_suggestion<D, F>(self, f: F) -> Self::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

Add a Suggestion to an error report, to be displayed after the chain of errors. The closure to create the Suggestion is lazily evaluated only in the case of an error.

Implementations on Foreign Types

impl Section for Report

type Return = Report

fn note<D>(self, note: D) -> <Report as Section>::Returnwhere
    D: Display + Send + Sync + 'static,

fn with_note<D, F>(self, note: F) -> <Report as Section>::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

fn warning<D>(self, warning: D) -> <Report as Section>::Returnwhere
    D: Display + Send + Sync + 'static,

fn with_warning<D, F>(self, warning: F) -> <Report as Section>::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

fn suggestion<D>(self, suggestion: D) -> <Report as Section>::Returnwhere
    D: Display + Send + Sync + 'static,

fn with_suggestion<D, F>(self, suggestion: F) -> <Report as Section>::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

fn with_section<D, F>(self, section: F) -> <Report as Section>::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

fn section<D>(self, section: D) -> <Report as Section>::Returnwhere
    D: Display + Send + Sync + 'static,

fn error<E2>(self, error: E2) -> <Report as Section>::Returnwhere
    E2: Error + Send + Sync + 'static,

fn with_error<E2, F>(self, error: F) -> <Report as Section>::Returnwhere
    F: FnOnce() -> E2,
    E2: Error + Send + Sync + 'static,

impl<T, E> Section for Result<T, E>where
    E: Into<Report>,

type Return = Result<T, Report>

fn note<D>(self, note: D) -> <Result<T, E> as Section>::Returnwhere
    D: Display + Send + Sync + 'static,

fn with_note<D, F>(self, note: F) -> <Result<T, E> as Section>::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

fn warning<D>(self, warning: D) -> <Result<T, E> as Section>::Returnwhere
    D: Display + Send + Sync + 'static,

fn with_warning<D, F>(self, warning: F) -> <Result<T, E> as Section>::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

fn suggestion<D>(self, suggestion: D) -> <Result<T, E> as Section>::Returnwhere
    D: Display + Send + Sync + 'static,

fn with_suggestion<D, F>(
    self,
    suggestion: F
) -> <Result<T, E> as Section>::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

fn with_section<D, F>(self, section: F) -> <Result<T, E> as Section>::Returnwhere
    D: Display + Send + Sync + 'static,
    F: FnOnce() -> D,

fn section<D>(self, section: D) -> <Result<T, E> as Section>::Returnwhere
    D: Display + Send + Sync + 'static,

fn error<E2>(self, error: E2) -> <Result<T, E> as Section>::Returnwhere
    E2: Error + Send + Sync + 'static,

fn with_error<E2, F>(self, error: F) -> <Result<T, E> as Section>::Returnwhere
    F: FnOnce() -> E2,
    E2: Error + Send + Sync + 'static,

Implementors