ansi_term/
style.rs

1/// A style is a collection of properties that can format a string
2/// using ANSI escape codes.
3#[derive(PartialEq, Clone, Copy)]
4pub struct Style {
5
6    /// The style's foreground colour, if it has one.
7    pub foreground: Option<Colour>,
8
9    /// The style's background colour, if it has one.
10    pub background: Option<Colour>,
11
12    /// Whether this style is bold.
13    pub is_bold: bool,
14
15    /// Whether this style is dimmed.
16    pub is_dimmed: bool,
17
18    /// Whether this style is italic.
19    pub is_italic: bool,
20
21    /// Whether this style is underlined.
22    pub is_underline: bool,
23
24    /// Whether this style is blinking.
25    pub is_blink: bool,
26
27    /// Whether this style has reverse colours.
28    pub is_reverse: bool,
29
30    /// Whether this style is hidden.
31    pub is_hidden: bool,
32
33    /// Whether this style is struckthrough.
34    pub is_strikethrough: bool
35}
36
37impl Style {
38    /// Creates a new Style with no differences.
39    pub fn new() -> Style {
40        Style::default()
41    }
42
43    /// Returns a `Style` with the bold property set.
44    pub fn bold(&self) -> Style {
45        Style { is_bold: true, .. *self }
46    }
47
48    /// Returns a `Style` with the dimmed property set.
49    pub fn dimmed(&self) -> Style {
50        Style { is_dimmed: true, .. *self }
51    }
52
53    /// Returns a `Style` with the italic property set.
54    pub fn italic(&self) -> Style {
55        Style { is_italic: true, .. *self }
56    }
57
58    /// Returns a `Style` with the underline property set.
59    pub fn underline(&self) -> Style {
60        Style { is_underline: true, .. *self }
61    }
62
63    /// Returns a `Style` with the blink property set.
64    pub fn blink(&self) -> Style {
65        Style { is_blink: true, .. *self }
66    }
67
68    /// Returns a `Style` with the reverse property set.
69    pub fn reverse(&self) -> Style {
70        Style { is_reverse: true, .. *self }
71    }
72
73    /// Returns a `Style` with the hidden property set.
74    pub fn hidden(&self) -> Style {
75        Style { is_hidden: true, .. *self }
76    }
77
78    /// Returns a `Style` with the hidden property set.
79    pub fn strikethrough(&self) -> Style {
80        Style { is_strikethrough: true, .. *self }
81    }
82
83    /// Returns a `Style` with the foreground colour property set.
84    pub fn fg(&self, foreground: Colour) -> Style {
85        Style { foreground: Some(foreground), .. *self }
86    }
87
88    /// Returns a `Style` with the background colour property set.
89    pub fn on(&self, background: Colour) -> Style {
90        Style { background: Some(background), .. *self }
91    }
92
93    /// Return true if this `Style` has no actual styles, and can be written
94    /// without any control characters.
95    pub fn is_plain(self) -> bool {
96        self == Style::default()
97    }
98}
99
100impl Default for Style {
101
102    /// Returns a style with *no* properties set. Formatting text using this
103    /// style returns the exact same text.
104    ///
105    /// ```
106    /// use ansi_term::Style;
107    /// assert_eq!(None,  Style::default().foreground);
108    /// assert_eq!(None,  Style::default().background);
109    /// assert_eq!(false, Style::default().is_bold);
110    /// assert_eq!("txt", Style::default().paint("txt").to_string());
111    /// ```
112    fn default() -> Style {
113        Style {
114            foreground: None,
115            background: None,
116            is_bold: false,
117            is_dimmed: false,
118            is_italic: false,
119            is_underline: false,
120            is_blink: false,
121            is_reverse: false,
122            is_hidden: false,
123            is_strikethrough: false,
124        }
125    }
126}
127
128
129// ---- colours ----
130
131/// A colour is one specific type of ANSI escape code, and can refer
132/// to either the foreground or background colour.
133///
134/// These use the standard numeric sequences.
135/// See <http://invisible-island.net/xterm/ctlseqs/ctlseqs.html>
136#[derive(PartialEq, Clone, Copy, Debug)]
137pub enum Colour {
138
139    /// Colour #0 (foreground code `30`, background code `40`).
140    ///
141    /// This is not necessarily the background colour, and using it as one may
142    /// render the text hard to read on terminals with dark backgrounds.
143    Black,
144
145    /// Colour #1 (foreground code `31`, background code `41`).
146    Red,
147
148    /// Colour #2 (foreground code `32`, background code `42`).
149    Green,
150
151    /// Colour #3 (foreground code `33`, background code `43`).
152    Yellow,
153
154    /// Colour #4 (foreground code `34`, background code `44`).
155    Blue,
156
157    /// Colour #5 (foreground code `35`, background code `45`).
158    Purple,
159
160    /// Colour #6 (foreground code `36`, background code `46`).
161    Cyan,
162
163    /// Colour #7 (foreground code `37`, background code `47`).
164    ///
165    /// As above, this is not necessarily the foreground colour, and may be
166    /// hard to read on terminals with light backgrounds.
167    White,
168
169    /// A colour number from 0 to 255, for use in 256-colour terminal
170    /// environments.
171    ///
172    /// - Colours 0 to 7 are the `Black` to `White` variants respectively.
173    ///   These colours can usually be changed in the terminal emulator.
174    /// - Colours 8 to 15 are brighter versions of the eight colours above.
175    ///   These can also usually be changed in the terminal emulator, or it
176    ///   could be configured to use the original colours and show the text in
177    ///   bold instead. It varies depending on the program.
178    /// - Colours 16 to 231 contain several palettes of bright colours,
179    ///   arranged in six squares measuring six by six each.
180    /// - Colours 232 to 255 are shades of grey from black to white.
181    ///
182    /// It might make more sense to look at a [colour chart][cc].
183    ///
184    /// [cc]: https://upload.wikimedia.org/wikipedia/en/1/15/Xterm_256color_chart.svg
185    Fixed(u8),
186
187    /// A 24-bit RGB color, as specified by ISO-8613-3.
188    RGB(u8, u8, u8),
189}
190
191
192impl Colour {
193    /// Return a `Style` with the foreground colour set to this colour.
194    pub fn normal(self) -> Style {
195        Style { foreground: Some(self), .. Style::default() }
196    }
197
198    /// Returns a `Style` with the bold property set.
199    pub fn bold(self) -> Style {
200        Style { foreground: Some(self), is_bold: true, .. Style::default() }
201    }
202
203    /// Returns a `Style` with the dimmed property set.
204    pub fn dimmed(self) -> Style {
205        Style { foreground: Some(self), is_dimmed: true, .. Style::default() }
206    }
207
208    /// Returns a `Style` with the italic property set.
209    pub fn italic(self) -> Style {
210        Style { foreground: Some(self), is_italic: true, .. Style::default() }
211    }
212
213    /// Returns a `Style` with the underline property set.
214    pub fn underline(self) -> Style {
215        Style { foreground: Some(self), is_underline: true, .. Style::default() }
216    }
217
218    /// Returns a `Style` with the blink property set.
219    pub fn blink(self) -> Style {
220        Style { foreground: Some(self), is_blink: true, .. Style::default() }
221    }
222
223    /// Returns a `Style` with the reverse property set.
224    pub fn reverse(self) -> Style {
225        Style { foreground: Some(self), is_reverse: true, .. Style::default() }
226    }
227
228    /// Returns a `Style` with the hidden property set.
229    pub fn hidden(self) -> Style {
230        Style { foreground: Some(self), is_hidden: true, .. Style::default() }
231    }
232
233    /// Returns a `Style` with the strikethrough property set.
234    pub fn strikethrough(self) -> Style {
235        Style { foreground: Some(self), is_strikethrough: true, .. Style::default() }
236    }
237
238    /// Returns a `Style` with the background colour property set.
239    pub fn on(self, background: Colour) -> Style {
240        Style { foreground: Some(self), background: Some(background), .. Style::default() }
241    }
242}
243
244impl From<Colour> for Style {
245
246    /// You can turn a `Colour` into a `Style` with the foreground colour set
247    /// with the `From` trait.
248    ///
249    /// ```
250    /// use ansi_term::{Style, Colour};
251    /// let green_foreground = Style::default().fg(Colour::Green);
252    /// assert_eq!(green_foreground, Colour::Green.normal());
253    /// assert_eq!(green_foreground, Colour::Green.into());
254    /// assert_eq!(green_foreground, Style::from(Colour::Green));
255    /// ```
256    fn from(colour: Colour) -> Style {
257        colour.normal()
258    }
259}