Struct color_eyre::config::HookBuilder

pub struct HookBuilder { /* private fields */ }

Builder for customizing the behavior of the global panic and error report hooks

Implementations

impl HookBuilder

pub fn new() -> Self

Construct a HookBuilder

Details

By default this function calls add_default_filters() and capture_span_trace_by_default(true). To get a HookBuilder with all features disabled by default call HookBuilder::blank().

Example

use color_eyre::config::HookBuilder;

HookBuilder::new()
    .install()
    .unwrap();

pub fn blank() -> Self

Construct a HookBuilder with minimal features enabled

pub fn theme(self, theme: Theme) -> Self

Set the global styles that color_eyre should use.

Tip: You can test new styles by editing examples/theme.rs in the color-eyre repository.

pub fn panic_section<S: Display + Send + Sync + 'static>( self, section: S ) -> Self

Add a custom section to the panic hook that will be printed in the panic message.

Examples

color_eyre::config::HookBuilder::default()
    .panic_section("consider reporting the bug at https://github.com/eyre-rs/eyre/issues")
    .install()
    .unwrap()

pub fn panic_message<S: PanicMessage>(self, section: S) -> Self

Overrides the main error message printing section at the start of panic reports

Examples

use std::{panic::Location, fmt};
use color_eyre::section::PanicMessage;
use owo_colors::OwoColorize;

struct MyPanicMessage;

color_eyre::config::HookBuilder::default()
    .panic_message(MyPanicMessage)
    .install()
    .unwrap();

impl PanicMessage for MyPanicMessage {
    fn display(&self, pi: &std::panic::PanicInfo<'_>, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        writeln!(f, "{}", "The application panicked (crashed).".red())?;

        // Print panic message.
        let payload = pi
            .payload()
            .downcast_ref::<String>()
            .map(String::as_str)
            .or_else(|| pi.payload().downcast_ref::<&str>().cloned())
            .unwrap_or("<non string panic payload>");

        write!(f, "Message:  ")?;
        writeln!(f, "{}", payload.cyan())?;

        // If known, print panic location.
        write!(f, "Location: ")?;
        if let Some(loc) = pi.location() {
            write!(f, "{}", loc.file().purple())?;
            write!(f, ":")?;
            write!(f, "{}", loc.line().purple())?;

            write!(f, "\n\nConsider reporting the bug at {}", custom_url(loc, payload))?;
        } else {
            write!(f, "<unknown>")?;
        }

        Ok(())
    }
}

fn custom_url(location: &Location<'_>, message: &str) -> impl fmt::Display {
    "todo"
}

pub fn issue_url<S: ToString>(self, url: S) -> Self

Available on crate feature issue-url only.

Set an upstream github repo and enable issue reporting url generation

Details

Once enabled, color-eyre will generate urls that will create customized issues pre-populated with information about the associated error report.

Additional information can be added to the metadata table in the generated urls by calling add_issue_metadata when configuring the HookBuilder.

Examples

color_eyre::config::HookBuilder::default()
    .issue_url(concat!(env!("CARGO_PKG_REPOSITORY"), "/issues/new"))
    .install()
    .unwrap();

pub fn add_issue_metadata<K, V>(self, key: K, value: V) -> Self

where K: Display, V: Display + Send + Sync + 'static,

Available on crate feature issue-url only.

Add a new entry to the metadata table in generated github issue urls

Note: this metadata will be ignored if no issue_url is set.

Examples

color_eyre::config::HookBuilder::default()
    .issue_url(concat!(env!("CARGO_PKG_REPOSITORY"), "/issues/new"))
    .add_issue_metadata("version", env!("CARGO_PKG_VERSION"))
    .install()
    .unwrap();

pub fn issue_filter<F>(self, predicate: F) -> Self

where F: Fn(ErrorKind<'_>) -> bool + Send + Sync + 'static,

Available on crate feature issue-url only.

Configures a filter for disabling issue url generation for certain kinds of errors

If the closure returns true, then the issue url will be generated.

Examples

color_eyre::config::HookBuilder::default()
    .issue_url(concat!(env!("CARGO_PKG_REPOSITORY"), "/issues/new"))
    .issue_filter(|kind| match kind {
        color_eyre::ErrorKind::NonRecoverable(payload) => {
            let payload = payload
                .downcast_ref::<String>()
                .map(String::as_str)
                .or_else(|| payload.downcast_ref::<&str>().cloned())
                .unwrap_or("<non string panic payload>");

            !payload.contains("my irrelevant error message")
        },
        color_eyre::ErrorKind::Recoverable(error) => !error.is::<std::fmt::Error>(),
    })
    .install()
    .unwrap();

pub fn capture_span_trace_by_default(self, cond: bool) -> Self

Configures the default capture mode for SpanTraces in error reports and panics

pub fn display_env_section(self, cond: bool) -> Self

Configures the enviroment varible info section and whether or not it is displayed

pub fn display_location_section(self, cond: bool) -> Self

Available on crate feature track-caller only.

Configures the location info section and whether or not it is displayed.

Notes

This will not disable the location section in a panic message.

pub fn add_frame_filter(self, filter: Box<FilterCallback>) -> Self

Add a custom filter to the set of frame filters

Examples

color_eyre::config::HookBuilder::default()
    .add_frame_filter(Box::new(|frames| {
        let filters = &[
            "uninteresting_function",
        ];

        frames.retain(|frame| {
            !filters.iter().any(|f| {
                let name = if let Some(name) = frame.name.as_ref() {
                    name.as_str()
                } else {
                    return true;
                };

                name.starts_with(f)
            })
        });
    }))
    .install()
    .unwrap();

pub fn install(self) -> Result<(), Report>

Install the given Hook as the global error report hook

pub fn add_default_filters(self) -> Self

Add the default set of filters to this HookBuilder’s configuration

pub fn into_hooks(self) -> (PanicHook, EyreHook)

Create a PanicHook and EyreHook from this HookBuilder. This can be used if you want to combine these handlers with other handlers.

pub fn try_into_hooks(self) -> Result<(PanicHook, EyreHook), Report>

Create a PanicHook and EyreHook from this HookBuilder. This can be used if you want to combine these handlers with other handlers.

Trait Implementations

impl Default for HookBuilder

fn default() -> Self

Returns the “default value” for a type.