miette/
handler.rs

1use std::fmt;
2
3use crate::highlighters::Highlighter;
4use crate::highlighters::MietteHighlighter;
5use crate::protocol::Diagnostic;
6use crate::GraphicalReportHandler;
7use crate::GraphicalTheme;
8use crate::NarratableReportHandler;
9use crate::ReportHandler;
10use crate::ThemeCharacters;
11use crate::ThemeStyles;
12
13/// Settings to control the color format used for graphical rendering.
14#[derive(Copy, Clone, Debug, Eq, PartialEq, Default)]
15pub enum RgbColors {
16    /// Use RGB colors even if the terminal does not support them
17    Always,
18    /// Use RGB colors instead of ANSI if the terminal supports RGB
19    Preferred,
20    /// Always use ANSI, regardless of terminal support for RGB
21    #[default]
22    Never,
23}
24
25/**
26Create a custom [`MietteHandler`] from options.
27
28## Example
29
30```no_run
31miette::set_hook(Box::new(|_| {
32    Box::new(miette::MietteHandlerOpts::new()
33        .terminal_links(true)
34        .unicode(false)
35        .context_lines(3)
36        .build())
37}))
38# .unwrap();
39```
40*/
41#[derive(Default, Debug, Clone)]
42pub struct MietteHandlerOpts {
43    pub(crate) linkify: Option<bool>,
44    pub(crate) width: Option<usize>,
45    pub(crate) theme: Option<GraphicalTheme>,
46    pub(crate) force_graphical: Option<bool>,
47    pub(crate) force_narrated: Option<bool>,
48    pub(crate) rgb_colors: RgbColors,
49    pub(crate) color: Option<bool>,
50    pub(crate) unicode: Option<bool>,
51    pub(crate) footer: Option<String>,
52    pub(crate) context_lines: Option<usize>,
53    pub(crate) tab_width: Option<usize>,
54    pub(crate) with_cause_chain: Option<bool>,
55    pub(crate) break_words: Option<bool>,
56    pub(crate) wrap_lines: Option<bool>,
57    pub(crate) word_separator: Option<textwrap::WordSeparator>,
58    pub(crate) word_splitter: Option<textwrap::WordSplitter>,
59    pub(crate) highlighter: Option<MietteHighlighter>,
60    pub(crate) show_related_as_nested: Option<bool>,
61}
62
63impl MietteHandlerOpts {
64    /// Create a new `MietteHandlerOpts`.
65    pub fn new() -> Self {
66        Default::default()
67    }
68
69    /// If true, specify whether the graphical handler will make codes be
70    /// clickable links in supported terminals. Defaults to auto-detection
71    /// based on known supported terminals.
72    pub fn terminal_links(mut self, linkify: bool) -> Self {
73        self.linkify = Some(linkify);
74        self
75    }
76
77    /// Set a graphical theme for the handler when rendering in graphical mode.
78    /// Use [`force_graphical()`](`MietteHandlerOpts::force_graphical) to force
79    /// graphical mode. This option overrides
80    /// [`color()`](`MietteHandlerOpts::color).
81    pub fn graphical_theme(mut self, theme: GraphicalTheme) -> Self {
82        self.theme = Some(theme);
83        self
84    }
85
86    /// Set a syntax highlighter when rendering in graphical mode.
87    /// Use [`force_graphical()`](MietteHandlerOpts::force_graphical()) to
88    /// force graphical mode.
89    ///
90    /// Syntax highlighting is disabled by default unless the
91    /// `syntect-highlighter` feature is enabled. Call this method
92    /// to override the default and use a custom highlighter
93    /// implementation instead.
94    ///
95    /// Use
96    /// [`without_syntax_highlighting()`](MietteHandlerOpts::without_syntax_highlighting())
97    /// To disable highlighting completely.
98    ///
99    /// Setting this option will not force color output. In all cases, the
100    /// current color configuration via
101    /// [`color()`](MietteHandlerOpts::color()) takes precedence over
102    /// highlighter configuration.
103    pub fn with_syntax_highlighting(
104        mut self,
105        highlighter: impl Highlighter + Send + Sync + 'static,
106    ) -> Self {
107        self.highlighter = Some(MietteHighlighter::from(highlighter));
108        self
109    }
110
111    /// Disables syntax highlighting when rendering in graphical mode.
112    /// Use [`force_graphical()`](MietteHandlerOpts::force_graphical()) to
113    /// force graphical mode.
114    ///
115    /// Syntax highlighting is disabled by default unless the
116    /// `syntect-highlighter` feature is enabled. Call this method if you want
117    /// to disable highlighting when building with this feature.
118    pub fn without_syntax_highlighting(mut self) -> Self {
119        self.highlighter = Some(MietteHighlighter::nocolor());
120        self
121    }
122
123    /// Sets the width to wrap the report at. Defaults to 80.
124    pub fn width(mut self, width: usize) -> Self {
125        self.width = Some(width);
126        self
127    }
128
129    /// If true, long lines can be wrapped.
130    ///
131    /// If false, long lines will not be broken when they exceed the width.
132    ///
133    /// Defaults to true.
134    pub fn wrap_lines(mut self, wrap_lines: bool) -> Self {
135        self.wrap_lines = Some(wrap_lines);
136        self
137    }
138
139    /// If true, long words can be broken when wrapping.
140    ///
141    /// If false, long words will not be broken when they exceed the width.
142    ///
143    /// Defaults to true.
144    pub fn break_words(mut self, break_words: bool) -> Self {
145        self.break_words = Some(break_words);
146        self
147    }
148    /// Sets the `textwrap::WordSeparator` to use when determining wrap points.
149    pub fn word_separator(mut self, word_separator: textwrap::WordSeparator) -> Self {
150        self.word_separator = Some(word_separator);
151        self
152    }
153
154    /// Sets the `textwrap::WordSplitter` to use when determining wrap points.
155    pub fn word_splitter(mut self, word_splitter: textwrap::WordSplitter) -> Self {
156        self.word_splitter = Some(word_splitter);
157        self
158    }
159    /// Include the cause chain of the top-level error in the report.
160    pub fn with_cause_chain(mut self) -> Self {
161        self.with_cause_chain = Some(true);
162        self
163    }
164
165    /// Do not include the cause chain of the top-level error in the report.
166    pub fn without_cause_chain(mut self) -> Self {
167        self.with_cause_chain = Some(false);
168        self
169    }
170
171    /// Show related errors as siblings.
172    pub fn show_related_errors_as_siblings(mut self) -> Self {
173        self.show_related_as_nested = Some(false);
174        self
175    }
176
177    /// Show related errors as nested errors.
178    pub fn show_related_errors_as_nested(mut self) -> Self {
179        self.show_related_as_nested = Some(true);
180        self
181    }
182
183    /// If true, colors will be used during graphical rendering, regardless
184    /// of whether or not the terminal supports them.
185    ///
186    /// If false, colors will never be used.
187    ///
188    /// If unspecified, colors will be used only if the terminal supports them.
189    ///
190    /// The actual format depends on the value of
191    /// [`MietteHandlerOpts::rgb_colors`].
192    pub fn color(mut self, color: bool) -> Self {
193        self.color = Some(color);
194        self
195    }
196
197    /// Controls which color format to use if colors are used in graphical
198    /// rendering.
199    ///
200    /// The default is `Never`.
201    ///
202    /// This value does not control whether or not colors are being used in the
203    /// first place. That is handled by the [`MietteHandlerOpts::color`]
204    /// setting. If colors are not being used, the value of `rgb_colors` has
205    /// no effect.
206    pub fn rgb_colors(mut self, color: RgbColors) -> Self {
207        self.rgb_colors = color;
208        self
209    }
210
211    /// If true, forces unicode display for graphical output. If set to false,
212    /// forces ASCII art display.
213    pub fn unicode(mut self, unicode: bool) -> Self {
214        self.unicode = Some(unicode);
215        self
216    }
217
218    /// If true, graphical rendering will be used regardless of terminal
219    /// detection.
220    pub fn force_graphical(mut self, force: bool) -> Self {
221        self.force_graphical = Some(force);
222        self
223    }
224
225    /// If true, forces use of the narrated renderer.
226    pub fn force_narrated(mut self, force: bool) -> Self {
227        self.force_narrated = Some(force);
228        self
229    }
230
231    /// Set a footer to be displayed at the bottom of the report.
232    pub fn footer(mut self, footer: String) -> Self {
233        self.footer = Some(footer);
234        self
235    }
236
237    /// Sets the number of context lines before and after a span to display.
238    pub fn context_lines(mut self, context_lines: usize) -> Self {
239        self.context_lines = Some(context_lines);
240        self
241    }
242
243    /// Set the displayed tab width in spaces.
244    pub fn tab_width(mut self, width: usize) -> Self {
245        self.tab_width = Some(width);
246        self
247    }
248
249    /// Builds a [`MietteHandler`] from this builder.
250    pub fn build(self) -> MietteHandler {
251        let graphical = self.is_graphical();
252        let width = self.get_width();
253        if !graphical {
254            let mut handler = NarratableReportHandler::new();
255            if let Some(footer) = self.footer {
256                handler = handler.with_footer(footer);
257            }
258            if let Some(context_lines) = self.context_lines {
259                handler = handler.with_context_lines(context_lines);
260            }
261            if let Some(with_cause_chain) = self.with_cause_chain {
262                if with_cause_chain {
263                    handler = handler.with_cause_chain();
264                } else {
265                    handler = handler.without_cause_chain();
266                }
267            }
268            MietteHandler {
269                inner: Box::new(handler),
270            }
271        } else {
272            let linkify = self.use_links();
273            let characters = match self.unicode {
274                Some(true) => ThemeCharacters::unicode(),
275                Some(false) => ThemeCharacters::ascii(),
276                None if syscall::supports_unicode() => ThemeCharacters::unicode(),
277                None => ThemeCharacters::ascii(),
278            };
279            let styles = if self.color == Some(false) {
280                ThemeStyles::none()
281            } else if let Some(color_has_16m) = syscall::supports_color_has_16m() {
282                match self.rgb_colors {
283                    RgbColors::Always => ThemeStyles::rgb(),
284                    RgbColors::Preferred if color_has_16m => ThemeStyles::rgb(),
285                    _ => ThemeStyles::ansi(),
286                }
287            } else if self.color == Some(true) {
288                match self.rgb_colors {
289                    RgbColors::Always => ThemeStyles::rgb(),
290                    _ => ThemeStyles::ansi(),
291                }
292            } else {
293                ThemeStyles::none()
294            };
295            #[cfg(not(feature = "syntect-highlighter"))]
296            let highlighter = self.highlighter.unwrap_or_else(MietteHighlighter::nocolor);
297            #[cfg(feature = "syntect-highlighter")]
298            let highlighter = if self.color == Some(false) {
299                MietteHighlighter::nocolor()
300            } else if self.color == Some(true) || syscall::supports_color() {
301                match self.highlighter {
302                    Some(highlighter) => highlighter,
303                    None => match self.rgb_colors {
304                        // Because the syntect highlighter currently only supports 24-bit truecolor,
305                        // respect RgbColor::Never by disabling the highlighter.
306                        // TODO: In the future, find a way to convert the RGB syntect theme
307                        // into an ANSI color theme.
308                        RgbColors::Never => MietteHighlighter::nocolor(),
309                        _ => MietteHighlighter::syntect_truecolor(),
310                    },
311                }
312            } else {
313                MietteHighlighter::nocolor()
314            };
315            let theme = self.theme.unwrap_or(GraphicalTheme { characters, styles });
316            let mut handler = GraphicalReportHandler::new_themed(theme)
317                .with_width(width)
318                .with_links(linkify);
319            handler.highlighter = highlighter;
320            if let Some(with_cause_chain) = self.with_cause_chain {
321                if with_cause_chain {
322                    handler = handler.with_cause_chain();
323                } else {
324                    handler = handler.without_cause_chain();
325                }
326            }
327            if let Some(footer) = self.footer {
328                handler = handler.with_footer(footer);
329            }
330            if let Some(context_lines) = self.context_lines {
331                handler = handler.with_context_lines(context_lines);
332            }
333            if let Some(w) = self.tab_width {
334                handler = handler.tab_width(w);
335            }
336            if let Some(b) = self.break_words {
337                handler = handler.with_break_words(b)
338            }
339            if let Some(b) = self.wrap_lines {
340                handler = handler.with_wrap_lines(b)
341            }
342            if let Some(s) = self.word_separator {
343                handler = handler.with_word_separator(s)
344            }
345            if let Some(s) = self.word_splitter {
346                handler = handler.with_word_splitter(s)
347            }
348            if let Some(b) = self.show_related_as_nested {
349                handler = handler.with_show_related_as_nested(b)
350            }
351
352            MietteHandler {
353                inner: Box::new(handler),
354            }
355        }
356    }
357
358    pub(crate) fn is_graphical(&self) -> bool {
359        if let Some(force_narrated) = self.force_narrated {
360            !force_narrated
361        } else if let Some(force_graphical) = self.force_graphical {
362            force_graphical
363        } else if let Ok(env) = std::env::var("NO_GRAPHICS") {
364            env == "0"
365        } else {
366            true
367        }
368    }
369
370    // Detects known terminal apps based on env variables and returns true if
371    // they support rendering links.
372    pub(crate) fn use_links(&self) -> bool {
373        if let Some(linkify) = self.linkify {
374            linkify
375        } else {
376            syscall::supports_hyperlinks()
377        }
378    }
379
380    pub(crate) fn get_width(&self) -> usize {
381        self.width
382            .unwrap_or_else(|| syscall::terminal_width().unwrap_or(80))
383    }
384}
385
386/**
387A [`ReportHandler`] that displays a given [`Report`](crate::Report) in a
388quasi-graphical way, using terminal colors, unicode drawing characters, and
389other such things.
390
391This is the default reporter bundled with `miette`.
392
393This printer can be customized by using
394[`GraphicalReportHandler::new_themed()`] and handing it a [`GraphicalTheme`] of
395your own creation (or using one of its own defaults).
396
397See [`set_hook`](crate::set_hook) for more details on customizing your global
398printer.
399*/
400#[allow(missing_debug_implementations)]
401pub struct MietteHandler {
402    inner: Box<dyn ReportHandler + Send + Sync>,
403}
404
405impl MietteHandler {
406    /// Creates a new [`MietteHandler`] with default settings.
407    pub fn new() -> Self {
408        Default::default()
409    }
410}
411
412impl Default for MietteHandler {
413    fn default() -> Self {
414        MietteHandlerOpts::new().build()
415    }
416}
417
418impl ReportHandler for MietteHandler {
419    fn debug(&self, diagnostic: &(dyn Diagnostic), f: &mut fmt::Formatter<'_>) -> fmt::Result {
420        if f.alternate() {
421            return fmt::Debug::fmt(diagnostic, f);
422        }
423
424        self.inner.debug(diagnostic, f)
425    }
426}
427
428mod syscall {
429    use cfg_if::cfg_if;
430
431    #[inline]
432    pub(super) fn terminal_width() -> Option<usize> {
433        cfg_if! {
434            if #[cfg(any(feature = "fancy-no-syscall", miri))] {
435                None
436            } else {
437                terminal_size::terminal_size().map(|size| size.0 .0 as usize)
438            }
439        }
440    }
441
442    #[inline]
443    pub(super) fn supports_hyperlinks() -> bool {
444        cfg_if! {
445            if #[cfg(feature = "fancy-no-syscall")] {
446                false
447            } else {
448                supports_hyperlinks::on(supports_hyperlinks::Stream::Stderr)
449            }
450        }
451    }
452
453    #[cfg(feature = "syntect-highlighter")]
454    #[inline]
455    pub(super) fn supports_color() -> bool {
456        cfg_if! {
457            if #[cfg(feature = "fancy-no-syscall")] {
458                false
459            } else {
460                supports_color::on(supports_color::Stream::Stderr).is_some()
461            }
462        }
463    }
464
465    #[inline]
466    pub(super) fn supports_color_has_16m() -> Option<bool> {
467        cfg_if! {
468            if #[cfg(feature = "fancy-no-syscall")] {
469                None
470            } else {
471                supports_color::on(supports_color::Stream::Stderr).map(|color| color.has_16m)
472            }
473        }
474    }
475
476    #[inline]
477    pub(super) fn supports_unicode() -> bool {
478        cfg_if! {
479            if #[cfg(feature = "fancy-no-syscall")] {
480                false
481            } else {
482                supports_unicode::on(supports_unicode::Stream::Stderr)
483            }
484        }
485    }
486}
miette/handler.rs

miette/
handler.rs
