Trait color_eyre::section::Section

pub trait Section: Sealed {
    type Return;

    // Required methods
    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;
    fn suppress_backtrace(self, suppress: bool) -> Self::Return;
}

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::Return

where 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::Return

where 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::Return

where 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::Return

where 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::Return

where 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::Return

where 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::Return

where 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::Return

where 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::Return

where 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::Return

where 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.

fn suppress_backtrace(self, suppress: bool) -> Self::Return

Whether to suppress printing of collected backtrace (if any).

Useful for reporting “unexceptional” errors for which a backtrace isn’t really necessary.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl Section for Report

type Return = Report

fn note<D>(self, note: D) -> Self::Return

where D: Display + Send + Sync + 'static,

fn with_note<D, F>(self, note: 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, warning: 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, suggestion: F) -> Self::Return

where D: Display + Send + Sync + 'static, F: FnOnce() -> D,

fn with_section<D, F>(self, section: F) -> Self::Return

where D: Display + Send + Sync + 'static, F: FnOnce() -> D,

fn section<D>(self, section: D) -> Self::Return

where D: Display + Send + Sync + 'static,

fn error<E2>(self, error: E2) -> Self::Return

where E2: Error + Send + Sync + 'static,

fn with_error<E2, F>(self, error: F) -> Self::Return

where F: FnOnce() -> E2, E2: Error + Send + Sync + 'static,

fn suppress_backtrace(self, suppress: bool) -> Self::Return

impl<T, E> Section for Result<T, E>

where E: Into<Report>,

type Return = Result<T, Report>

fn note<D>(self, note: D) -> Self::Return

where D: Display + Send + Sync + 'static,

fn with_note<D, F>(self, note: 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, warning: 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, suggestion: F) -> Self::Return

where D: Display + Send + Sync + 'static, F: FnOnce() -> D,

fn with_section<D, F>(self, section: F) -> Self::Return

where D: Display + Send + Sync + 'static, F: FnOnce() -> D,

fn section<D>(self, section: D) -> Self::Return

where D: Display + Send + Sync + 'static,

fn error<E2>(self, error: E2) -> Self::Return

where E2: Error + Send + Sync + 'static,

fn with_error<E2, F>(self, error: F) -> Self::Return

where F: FnOnce() -> E2, E2: Error + Send + Sync + 'static,

fn suppress_backtrace(self, suppress: bool) -> Self::Return

Implementors