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

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.