pub struct HookBuilder { /* private fields */ }
Expand description

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

Implementations§

source§

impl HookBuilder

source

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();
source

pub fn blank() -> Self

Construct a HookBuilder with minimal features enabled

source

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.

source

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()
source

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"
}
source

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();
source

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();
source

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();
source

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

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

source

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

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

source

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.

source

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();
source

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

Install the given Hook as the global error report hook

source

pub fn add_default_filters(self) -> Self

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

source

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.

source

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§

source§

impl Default for HookBuilder

source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<D> OwoColorize for D

source§

fn fg<C>(&self) -> FgColorDisplay<'_, C, Self>
where C: Color,

Set the foreground color generically Read more
source§

fn bg<C>(&self) -> BgColorDisplay<'_, C, Self>
where C: Color,

Set the background color generically. Read more
source§

fn black<'a>(&'a self) -> FgColorDisplay<'a, Black, Self>

Change the foreground color to black
source§

fn on_black<'a>(&'a self) -> BgColorDisplay<'a, Black, Self>

Change the background color to black
source§

fn red<'a>(&'a self) -> FgColorDisplay<'a, Red, Self>

Change the foreground color to red
source§

fn on_red<'a>(&'a self) -> BgColorDisplay<'a, Red, Self>

Change the background color to red
source§

fn green<'a>(&'a self) -> FgColorDisplay<'a, Green, Self>

Change the foreground color to green
source§

fn on_green<'a>(&'a self) -> BgColorDisplay<'a, Green, Self>

Change the background color to green
source§

fn yellow<'a>(&'a self) -> FgColorDisplay<'a, Yellow, Self>

Change the foreground color to yellow
source§

fn on_yellow<'a>(&'a self) -> BgColorDisplay<'a, Yellow, Self>

Change the background color to yellow
source§

fn blue<'a>(&'a self) -> FgColorDisplay<'a, Blue, Self>

Change the foreground color to blue
source§

fn on_blue<'a>(&'a self) -> BgColorDisplay<'a, Blue, Self>

Change the background color to blue
source§

fn magenta<'a>(&'a self) -> FgColorDisplay<'a, Magenta, Self>

Change the foreground color to magenta
source§

fn on_magenta<'a>(&'a self) -> BgColorDisplay<'a, Magenta, Self>

Change the background color to magenta
source§

fn purple<'a>(&'a self) -> FgColorDisplay<'a, Magenta, Self>

Change the foreground color to purple
source§

fn on_purple<'a>(&'a self) -> BgColorDisplay<'a, Magenta, Self>

Change the background color to purple
source§

fn cyan<'a>(&'a self) -> FgColorDisplay<'a, Cyan, Self>

Change the foreground color to cyan
source§

fn on_cyan<'a>(&'a self) -> BgColorDisplay<'a, Cyan, Self>

Change the background color to cyan
source§

fn white<'a>(&'a self) -> FgColorDisplay<'a, White, Self>

Change the foreground color to white
source§

fn on_white<'a>(&'a self) -> BgColorDisplay<'a, White, Self>

Change the background color to white
source§

fn default_color<'a>(&'a self) -> FgColorDisplay<'a, Default, Self>

Change the foreground color to the terminal default
source§

fn on_default_color<'a>(&'a self) -> BgColorDisplay<'a, Default, Self>

Change the background color to the terminal default
source§

fn bright_black<'a>(&'a self) -> FgColorDisplay<'a, BrightBlack, Self>

Change the foreground color to bright black
source§

fn on_bright_black<'a>(&'a self) -> BgColorDisplay<'a, BrightBlack, Self>

Change the background color to bright black
source§

fn bright_red<'a>(&'a self) -> FgColorDisplay<'a, BrightRed, Self>

Change the foreground color to bright red
source§

fn on_bright_red<'a>(&'a self) -> BgColorDisplay<'a, BrightRed, Self>

Change the background color to bright red
source§

fn bright_green<'a>(&'a self) -> FgColorDisplay<'a, BrightGreen, Self>

Change the foreground color to bright green
source§

fn on_bright_green<'a>(&'a self) -> BgColorDisplay<'a, BrightGreen, Self>

Change the background color to bright green
source§

fn bright_yellow<'a>(&'a self) -> FgColorDisplay<'a, BrightYellow, Self>

Change the foreground color to bright yellow
source§

fn on_bright_yellow<'a>(&'a self) -> BgColorDisplay<'a, BrightYellow, Self>

Change the background color to bright yellow
source§

fn bright_blue<'a>(&'a self) -> FgColorDisplay<'a, BrightBlue, Self>

Change the foreground color to bright blue
source§

fn on_bright_blue<'a>(&'a self) -> BgColorDisplay<'a, BrightBlue, Self>

Change the background color to bright blue
source§

fn bright_magenta<'a>(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>

Change the foreground color to bright magenta
source§

fn on_bright_magenta<'a>(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>

Change the background color to bright magenta
source§

fn bright_purple<'a>(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>

Change the foreground color to bright purple
source§

fn on_bright_purple<'a>(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>

Change the background color to bright purple
source§

fn bright_cyan<'a>(&'a self) -> FgColorDisplay<'a, BrightCyan, Self>

Change the foreground color to bright cyan
source§

fn on_bright_cyan<'a>(&'a self) -> BgColorDisplay<'a, BrightCyan, Self>

Change the background color to bright cyan
source§

fn bright_white<'a>(&'a self) -> FgColorDisplay<'a, BrightWhite, Self>

Change the foreground color to bright white
source§

fn on_bright_white<'a>(&'a self) -> BgColorDisplay<'a, BrightWhite, Self>

Change the background color to bright white
source§

fn bold<'a>(&'a self) -> BoldDisplay<'a, Self>

Make the text bold
source§

fn dimmed<'a>(&'a self) -> DimDisplay<'a, Self>

Make the text dim
source§

fn italic<'a>(&'a self) -> ItalicDisplay<'a, Self>

Make the text italicized
source§

fn underline<'a>(&'a self) -> UnderlineDisplay<'a, Self>

Make the text italicized
Make the text blink
Make the text blink (but fast!)
source§

fn reversed<'a>(&'a self) -> ReversedDisplay<'a, Self>

Swap the foreground and background colors
source§

fn hidden<'a>(&'a self) -> HiddenDisplay<'a, Self>

Hide the text
source§

fn strikethrough<'a>(&'a self) -> StrikeThroughDisplay<'a, Self>

Cross out the text
source§

fn color<Color>(&self, color: Color) -> FgDynColorDisplay<'_, Color, Self>
where Color: DynColor,

Set the foreground color at runtime. Only use if you do not know which color will be used at compile-time. If the color is constant, use either OwoColorize::fg or a color-specific method, such as OwoColorize::green, Read more
source§

fn on_color<Color>(&self, color: Color) -> BgDynColorDisplay<'_, Color, Self>
where Color: DynColor,

Set the background color at runtime. Only use if you do not know what color to use at compile-time. If the color is constant, use either OwoColorize::bg or a color-specific method, such as OwoColorize::on_yellow, Read more
source§

fn fg_rgb<const R: u8, const G: u8, const B: u8>( &self ) -> FgColorDisplay<'_, CustomColor<R, G, B>, Self>

Set the foreground color to a specific RGB value.
source§

fn bg_rgb<const R: u8, const G: u8, const B: u8>( &self ) -> BgColorDisplay<'_, CustomColor<R, G, B>, Self>

Set the background color to a specific RGB value.
source§

fn truecolor(&self, r: u8, g: u8, b: u8) -> FgDynColorDisplay<'_, Rgb, Self>

Sets the foreground color to an RGB value.
source§

fn on_truecolor(&self, r: u8, g: u8, b: u8) -> BgDynColorDisplay<'_, Rgb, Self>

Sets the background color to an RGB value.
source§

fn style(&self, style: Style) -> Styled<&Self>

Apply a runtime-determined style
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more