error-stack: implementing conditional fmt::Display behaviour based on ColorMode for an attachment

[mkatychev]

I am adding an attachment called Type to my error reporting library:

/// wrapper attachment that is used to refer to the type of an object
/// rather than the value
pub struct Type(&'static str);

impl Type {
    // const fn when `std::any::type_name` is const fn in stable
    pub fn of<T>() -> Self {
        Self(std::any::type_name::<T>())
    }
}

impl std::fmt::Display for Type {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "<{}>", self.0)
    }
}

impl std::fmt::Debug for Type {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_tuple("Type").field(&self.0).finish()
    }
}

I would like to evaluate the colour mode for each attachment that I display:

const GREEN_LT: &'static str = '<'.green();
// const ...
impl std::fmt::Display for Type {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match somehow_get_color_mode() {
            ColorMode::None => write!(f, "<{}>", self.0),
            ColorMode::Color => write!(f, "{GREEN_LT}{}{GREEN_GT}"}, self.0),
            ColorMode::Emphasis => write!(f, "{BOLD_LT}{}{BOLD_GT}", self.0),
        }
    }
}

The suggested approach for dealing with conditional formatting is use HookContext data from within Report::install_debug_hook::<Type>, the issue here is that it requires an explicit invocation for each attachment type anytime you might use the attachment.

Location, Backtrace and SpanTrace do not need to declare debug hooks since they have a prelude that calls the hooks for them error_stack::fmt::hook::default::install_builtin_hooks:

hash/libs/error-stack/src/fmt/hook.rs

Lines 497 to 507 in 1c930a0

	INSTALL_BUILTIN.call_once(|| {
	INSTALL_BUILTIN_RUNNING.store(true, Ordering::Release);
	Report::install_debug_hook::<Location>(location);
	#[cfg(all(feature = "std", rust_1_65))]
	Report::install_debug_hook::<Backtrace>(backtrace);
	#[cfg(feature = "spantrace")]
	Report::install_debug_hook::<SpanTrace>(span_trace);
	});

I'm curious if there's a good way to allow attachments to define their own conditional formatting and have them be instantiated into the prelude along with the builtin types.

[indietyp]

I apologize for the late reply; this completely flew under my radar.

Report::install_debug_hook is the thing you're looking for; it is invoked for every attachment type T and provides the color mode as well as charset. You will need to call install_debug_hook at the start of your application (just as you would when you're trying to configure tracing).

In the first iteration of the output, we actually thought about utilizing Display for this exact purpose but came to the conclusion that it wouldn't be of much help and that we needed to create a separate way to do this. This is because we cannot "smuggle" any data into the Formatter without sacrificing quite a bit of general usability. We also want to avoid exposing the current charset and color mode via a global variable. This is because it opens up error-stack to a sort of "abuse" in a sense, where instead of being an error-reporting library, it becomes yet another library that provides a color mode and charset that you can refer to. Which then is confusing to the end user; the idea is that the color mode is chosen by, e.g., clap or another library (same with charset) and then propagated to error-stack, instead of error-stack being the source of truth for the selected charset and color mode.

The other question is: Why don't we use inventory or linkme to install the debug hooks automatically? This is a much more subjective question, and the reason is that we dislike ctor / live before main. It also breaks WASM compatibility in some significant ways. In my personal opinion, it also goes very much against the spirit of Rust, where you have explicit rather than implicit control, as implicit control makes it harder to reason about code (for example, what should happen if you accidentally register two different implementations via inventory for the same type?). Ultimately, we left it up to the ecosystem to create a companion crate that could fill the role.