termcolor/
traits.rs

1use crate::{ColorSpec, HyperlinkSpec};
2use std::io;
3
4/// This trait describes the behavior of writers that support colored output.
5pub trait WriteColor: io::Write {
6    /// Returns true if and only if the underlying writer supports colors.
7    fn supports_color(&self) -> bool;
8
9    /// Set the color settings of the writer.
10    ///
11    /// Subsequent writes to this writer will use these settings until either
12    /// `reset` is called or new color settings are set.
13    ///
14    /// If there was a problem setting the color settings, then an error is
15    /// returned.
16    fn set_color(&mut self, spec: &ColorSpec) -> io::Result<()>;
17
18    /// Reset the current color settings to their original settings.
19    ///
20    /// If there was a problem resetting the color settings, then an error is
21    /// returned.
22    ///
23    /// Note that this does not reset hyperlinks. Those need to be
24    /// reset on their own, e.g., by calling `set_hyperlink` with
25    /// [`HyperlinkSpec::none`].
26    fn reset(&mut self) -> io::Result<()>;
27
28    /// Set the current hyperlink of the writer.
29    ///
30    /// The typical way to use this is to first call it with a
31    /// [`HyperlinkSpec::open`] to write the actual URI to a tty that supports
32    /// [OSC-8]. At this point, the caller can now write the label for the
33    /// hyperlink. This may include coloring or other styles. Once the caller
34    /// has finished writing the label, one should call this method again with
35    /// [`HyperlinkSpec::close`].
36    ///
37    /// If there was a problem setting the hyperlink, then an error is
38    /// returned.
39    ///
40    /// This defaults to doing nothing.
41    ///
42    /// [OSC8]: https://github.com/Alhadis/OSC8-Adoption/
43    fn set_hyperlink(&mut self, _link: &HyperlinkSpec) -> io::Result<()> {
44        Ok(())
45    }
46
47    /// Returns true if and only if the underlying writer supports hyperlinks.
48    ///
49    /// This can be used to avoid generating hyperlink URIs unnecessarily.
50    ///
51    /// This defaults to `false`.
52    fn supports_hyperlinks(&self) -> bool {
53        false
54    }
55
56    /// Returns true if and only if the underlying writer must synchronously
57    /// interact with an end user's device in order to control colors. By
58    /// default, this always returns `false`.
59    ///
60    /// In particular, this returns true when the underlying writer is a
61    /// Windows console that was created before Windows 10 build 14931 (2016).
62    fn is_synchronous(&self) -> bool {
63        false
64    }
65}
66
67impl<T: ?Sized + WriteColor> WriteColor for &mut T {
68    fn supports_color(&self) -> bool {
69        (**self).supports_color()
70    }
71    fn supports_hyperlinks(&self) -> bool {
72        (**self).supports_hyperlinks()
73    }
74    fn set_color(&mut self, spec: &ColorSpec) -> io::Result<()> {
75        (**self).set_color(spec)
76    }
77    fn set_hyperlink(&mut self, link: &HyperlinkSpec) -> io::Result<()> {
78        (**self).set_hyperlink(link)
79    }
80    fn reset(&mut self) -> io::Result<()> {
81        (**self).reset()
82    }
83}
84
85impl<T: ?Sized + WriteColor> WriteColor for Box<T> {
86    fn supports_color(&self) -> bool {
87        (**self).supports_color()
88    }
89    fn supports_hyperlinks(&self) -> bool {
90        (**self).supports_hyperlinks()
91    }
92    fn set_color(&mut self, spec: &ColorSpec) -> io::Result<()> {
93        (**self).set_color(spec)
94    }
95    fn set_hyperlink(&mut self, link: &HyperlinkSpec) -> io::Result<()> {
96        (**self).set_hyperlink(link)
97    }
98    fn reset(&mut self) -> io::Result<()> {
99        (**self).reset()
100    }
101}
termcolor/traits.rs

termcolor/
traits.rs
