feat(color_eyre): add support to specify verbosity in HookBuilder

color-eyre/src/config.rs

@@ -219,9 +219,9 @@
         )?;
 
         let v = if std::thread::panicking() {
-            panic_verbosity()
+            panic_verbosity(None)
         } else {
-            lib_verbosity()
+            lib_verbosity(None)
         };
 
         // Maybe print source.
@@ -386,6 +386,7 @@
 pub struct HookBuilder {
     filters: Vec<Box<FilterCallback>>,
     capture_span_trace_by_default: bool,
+    verbosity: Option<Verbosity>,
     display_env_section: bool,
     #[cfg(feature = "track-caller")]
     display_location_section: bool,
@@ -429,6 +430,7 @@
         HookBuilder {
             filters: vec![],
             capture_span_trace_by_default: false,
+            verbosity: None,
             display_env_section: true,
             #[cfg(feature = "track-caller")]
             display_location_section: true,
@@ -616,6 +618,12 @@
         self
     }
 
+    /// Configures the verbosity to use. Overrides environment variables.
+    pub fn verbosity(mut self, verbosity: Verbosity) -> Self {
+        self.verbosity = Some(verbosity);
+        self
+    }
+
     /// Configures the enviroment varible info section and whether or not it is displayed
     pub fn display_env_section(mut self, cond: bool) -> Self {
         self.display_env_section = cond;
@@ -696,6 +704,7 @@
             section: self.panic_section,
             #[cfg(feature = "capture-spantrace")]
             capture_span_trace_by_default: self.capture_span_trace_by_default,
+            verbosity: self.verbosity,
             display_env_section: self.display_env_section,
             panic_message: self
                 .panic_message
@@ -713,6 +722,7 @@
             filters: panic_hook.filters.clone(),
             #[cfg(feature = "capture-spantrace")]
             capture_span_trace_by_default: self.capture_span_trace_by_default,
+            verbosity: self.verbosity,
             display_env_section: self.display_env_section,
             #[cfg(feature = "track-caller")]
             display_location_section: self.display_location_section,
@@ -790,7 +800,7 @@
 struct DefaultPanicMessage(Theme);
 
 impl PanicMessage for DefaultPanicMessage {
     fn display(&self, pi: &std::panic::PanicInfo<'_>, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         // XXX is my assumption correct that this function is guaranteed to only run after `color_eyre` was setup successfully (including setting `THEME`), and that therefore the following line will never panic? Otherwise, we could return `fmt::Error`, but if the above is true, I like `unwrap` + a comment why this never fails better
         let theme = &self.0;
 
@@ -822,7 +832,7 @@
 /// A type representing an error report for a panic.
 pub struct PanicReport<'a> {
     hook: &'a PanicHook,
     panic_info: &'a std::panic::PanicInfo<'a>,
     backtrace: Option<backtrace::Backtrace>,
     #[cfg(feature = "capture-spantrace")]
     span_trace: Option<tracing_error::SpanTrace>,
@@ -831,7 +841,7 @@
 fn print_panic_info(report: &PanicReport<'_>, f: &mut fmt::Formatter<'_>) -> fmt::Result {
     report.hook.panic_message.display(report.panic_info, f)?;
 
-    let v = panic_verbosity();
+    let v = panic_verbosity(None);
     let capture_bt = v != Verbosity::Minimal;
 
     let mut separated = f.header("\n\n");
@@ -913,6 +923,7 @@
     theme: Theme,
     #[cfg(feature = "capture-spantrace")]
     capture_span_trace_by_default: bool,
+    verbosity: Option<Verbosity>,
     display_env_section: bool,
     #[cfg(feature = "issue-url")]
     issue_url: Option<String>,
@@ -949,7 +960,7 @@
     /// Convert self into the type expected by `std::panic::set_hook`.
     pub fn into_panic_hook(
         self,
     ) -> Box<dyn Fn(&std::panic::PanicInfo<'_>) + Send + Sync + 'static> {
         Box::new(move |panic_info| {
             eprintln!("{}", self.panic_report(panic_info));
         })
@@ -959,9 +970,9 @@
     /// `Display` trait.
     pub fn panic_report<'a>(
         &'a self,
         panic_info: &'a std::panic::PanicInfo<'_>,
     ) -> PanicReport<'a> {
-        let v = panic_verbosity();
+        let v = panic_verbosity(self.verbosity);
         let capture_bt = v != Verbosity::Minimal;
 
         #[cfg(feature = "capture-spantrace")]
@@ -992,6 +1003,7 @@
     filters: Arc<[Box<FilterCallback>]>,
     #[cfg(feature = "capture-spantrace")]
     capture_span_trace_by_default: bool,
+    verbosity: Option<Verbosity>,
     display_env_section: bool,
     #[cfg(feature = "track-caller")]
     display_location_section: bool,
@@ -1014,10 +1026,12 @@
 impl EyreHook {
     #[allow(unused_variables)]
     pub(crate) fn default(&self, error: &(dyn std::error::Error + 'static)) -> crate::Handler {
-        let backtrace = if lib_verbosity() != Verbosity::Minimal {
-            Some(backtrace::Backtrace::new())
-        } else {
-            None
+        let backtrace = {
+            if lib_verbosity(self.verbosity) != Verbosity::Minimal {
+                Some(backtrace::Backtrace::new())
+            } else {
+                None
+            }
         };
 
         #[cfg(feature = "capture-spantrace")]
@@ -1156,22 +1170,37 @@
     }
 }
 
+/// Verbosity of error and panic messages.
+///
+/// For previews or more information see the [crate documentation](crate#multiple-report-format-verbosity-levels)
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy)]
-pub(crate) enum Verbosity {
+pub enum Verbosity {
+    /// Minimal verbosity that does not include a `Backtrace`.
     Minimal,
+    /// The "short format" which additionally captures a `Backtrace`.
     Medium,
+    /// The full verbose format which will include context of the source files where the error
+    /// originated from, assuming it can find them on the disk.
     Full,
 }
 
-pub(crate) fn panic_verbosity() -> Verbosity {
+pub(crate) fn panic_verbosity(verbosity: Option<Verbosity>) -> Verbosity {
+    if let Some(v) = verbosity {
+        return v;
+    }
+
     match env::var("RUST_BACKTRACE") {
         Ok(s) if s == "full" => Verbosity::Full,
         Ok(s) if s != "0" => Verbosity::Medium,
         _ => Verbosity::Minimal,
     }
 }
 
-pub(crate) fn lib_verbosity() -> Verbosity {
+pub(crate) fn lib_verbosity(verbosity: Option<Verbosity>) -> Verbosity {
+    if let Some(v) = verbosity {
+        return v;
+    }
+
     match env::var("RUST_LIB_BACKTRACE").or_else(|_| env::var("RUST_BACKTRACE")) {
         Ok(s) if s == "full" => Verbosity::Full,
         Ok(s) if s != "0" => Verbosity::Medium,

color-eyre/src/writers.rs

@@ -189,9 +189,9 @@ pub(crate) struct EnvSection<'a> {
 impl fmt::Display for EnvSection<'_> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         let v = if std::thread::panicking() {
-            panic_verbosity()
+            panic_verbosity(None)
         } else {
-            lib_verbosity()
+            lib_verbosity(None)
         };
         write!(f, "{}", BacktraceOmited(!self.bt_captured))?;