1/// A style is a collection of properties that can format a string
2/// using ANSI escape codes.
3///
4/// # Examples
5///
6/// ```
7/// use ansi_term::{Style, Colour};
8///
9/// let style = Style::new().bold().on(Colour::Black);
10/// println!("{}", style.paint("Bold on black"));
11/// ```
12#[derive(PartialEq, Clone, Copy)]
13#[cfg_attr(feature = "derive_serde_style", derive(serde::Deserialize, serde::Serialize))]
14pub struct Style {
15
16 /// The style's foreground colour, if it has one.
17 pub foreground: Option<Colour>,
18
19 /// The style's background colour, if it has one.
20 pub background: Option<Colour>,
21
22 /// Whether this style is bold.
23 pub is_bold: bool,
24
25 /// Whether this style is dimmed.
26 pub is_dimmed: bool,
27
28 /// Whether this style is italic.
29 pub is_italic: bool,
30
31 /// Whether this style is underlined.
32 pub is_underline: bool,
33
34 /// Whether this style is blinking.
35 pub is_blink: bool,
36
37 /// Whether this style has reverse colours.
38 pub is_reverse: bool,
39
40 /// Whether this style is hidden.
41 pub is_hidden: bool,
42
43 /// Whether this style is struckthrough.
44 pub is_strikethrough: bool
45}
46
47impl Style {
48
49 /// Creates a new Style with no properties set.
50 ///
51 /// # Examples
52 ///
53 /// ```
54 /// use ansi_term::Style;
55 ///
56 /// let style = Style::new();
57 /// println!("{}", style.paint("hi"));
58 /// ```
59 pub fn new() -> Style {
60 Style::default()
61 }
62
63 /// Returns a `Style` with the bold property set.
64 ///
65 /// # Examples
66 ///
67 /// ```
68 /// use ansi_term::Style;
69 ///
70 /// let style = Style::new().bold();
71 /// println!("{}", style.paint("hey"));
72 /// ```
73 pub fn bold(&self) -> Style {
74 Style { is_bold: true, .. *self }
75 }
76
77 /// Returns a `Style` with the dimmed property set.
78 ///
79 /// # Examples
80 ///
81 /// ```
82 /// use ansi_term::Style;
83 ///
84 /// let style = Style::new().dimmed();
85 /// println!("{}", style.paint("sup"));
86 /// ```
87 pub fn dimmed(&self) -> Style {
88 Style { is_dimmed: true, .. *self }
89 }
90
91 /// Returns a `Style` with the italic property set.
92 ///
93 /// # Examples
94 ///
95 /// ```
96 /// use ansi_term::Style;
97 ///
98 /// let style = Style::new().italic();
99 /// println!("{}", style.paint("greetings"));
100 /// ```
101 pub fn italic(&self) -> Style {
102 Style { is_italic: true, .. *self }
103 }
104
105 /// Returns a `Style` with the underline property set.
106 ///
107 /// # Examples
108 ///
109 /// ```
110 /// use ansi_term::Style;
111 ///
112 /// let style = Style::new().underline();
113 /// println!("{}", style.paint("salutations"));
114 /// ```
115 pub fn underline(&self) -> Style {
116 Style { is_underline: true, .. *self }
117 }
118
119 /// Returns a `Style` with the blink property set.
120 /// # Examples
121 ///
122 /// ```
123 /// use ansi_term::Style;
124 ///
125 /// let style = Style::new().blink();
126 /// println!("{}", style.paint("wazzup"));
127 /// ```
128 pub fn blink(&self) -> Style {
129 Style { is_blink: true, .. *self }
130 }
131
132 /// Returns a `Style` with the reverse property set.
133 ///
134 /// # Examples
135 ///
136 /// ```
137 /// use ansi_term::Style;
138 ///
139 /// let style = Style::new().reverse();
140 /// println!("{}", style.paint("aloha"));
141 /// ```
142 pub fn reverse(&self) -> Style {
143 Style { is_reverse: true, .. *self }
144 }
145
146 /// Returns a `Style` with the hidden property set.
147 ///
148 /// # Examples
149 ///
150 /// ```
151 /// use ansi_term::Style;
152 ///
153 /// let style = Style::new().hidden();
154 /// println!("{}", style.paint("ahoy"));
155 /// ```
156 pub fn hidden(&self) -> Style {
157 Style { is_hidden: true, .. *self }
158 }
159
160 /// Returns a `Style` with the strikethrough property set.
161 ///
162 /// # Examples
163 ///
164 /// ```
165 /// use ansi_term::Style;
166 ///
167 /// let style = Style::new().strikethrough();
168 /// println!("{}", style.paint("yo"));
169 /// ```
170 pub fn strikethrough(&self) -> Style {
171 Style { is_strikethrough: true, .. *self }
172 }
173
174 /// Returns a `Style` with the foreground colour property set.
175 ///
176 /// # Examples
177 ///
178 /// ```
179 /// use ansi_term::{Style, Colour};
180 ///
181 /// let style = Style::new().fg(Colour::Yellow);
182 /// println!("{}", style.paint("hi"));
183 /// ```
184 pub fn fg(&self, foreground: Colour) -> Style {
185 Style { foreground: Some(foreground), .. *self }
186 }
187
188 /// Returns a `Style` with the background colour property set.
189 ///
190 /// # Examples
191 ///
192 /// ```
193 /// use ansi_term::{Style, Colour};
194 ///
195 /// let style = Style::new().on(Colour::Blue);
196 /// println!("{}", style.paint("eyyyy"));
197 /// ```
198 pub fn on(&self, background: Colour) -> Style {
199 Style { background: Some(background), .. *self }
200 }
201
202 /// Return true if this `Style` has no actual styles, and can be written
203 /// without any control characters.
204 ///
205 /// # Examples
206 ///
207 /// ```
208 /// use ansi_term::Style;
209 ///
210 /// assert_eq!(true, Style::default().is_plain());
211 /// assert_eq!(false, Style::default().bold().is_plain());
212 /// ```
213 pub fn is_plain(self) -> bool {
214 self == Style::default()
215 }
216}
217
218impl Default for Style {
219
220 /// Returns a style with *no* properties set. Formatting text using this
221 /// style returns the exact same text.
222 ///
223 /// ```
224 /// use ansi_term::Style;
225 /// assert_eq!(None, Style::default().foreground);
226 /// assert_eq!(None, Style::default().background);
227 /// assert_eq!(false, Style::default().is_bold);
228 /// assert_eq!("txt", Style::default().paint("txt").to_string());
229 /// ```
230 fn default() -> Style {
231 Style {
232 foreground: None,
233 background: None,
234 is_bold: false,
235 is_dimmed: false,
236 is_italic: false,
237 is_underline: false,
238 is_blink: false,
239 is_reverse: false,
240 is_hidden: false,
241 is_strikethrough: false,
242 }
243 }
244}
245
246
247// ---- colours ----
248
249/// A colour is one specific type of ANSI escape code, and can refer
250/// to either the foreground or background colour.
251///
252/// These use the standard numeric sequences.
253/// See <http://invisible-island.net/xterm/ctlseqs/ctlseqs.html>
254#[derive(PartialEq, Clone, Copy, Debug)]
255#[cfg_attr(feature = "derive_serde_style", derive(serde::Deserialize, serde::Serialize))]
256pub enum Colour {
257
258 /// Colour #0 (foreground code `30`, background code `40`).
259 ///
260 /// This is not necessarily the background colour, and using it as one may
261 /// render the text hard to read on terminals with dark backgrounds.
262 Black,
263
264 /// Colour #1 (foreground code `31`, background code `41`).
265 Red,
266
267 /// Colour #2 (foreground code `32`, background code `42`).
268 Green,
269
270 /// Colour #3 (foreground code `33`, background code `43`).
271 Yellow,
272
273 /// Colour #4 (foreground code `34`, background code `44`).
274 Blue,
275
276 /// Colour #5 (foreground code `35`, background code `45`).
277 Purple,
278
279 /// Colour #6 (foreground code `36`, background code `46`).
280 Cyan,
281
282 /// Colour #7 (foreground code `37`, background code `47`).
283 ///
284 /// As above, this is not necessarily the foreground colour, and may be
285 /// hard to read on terminals with light backgrounds.
286 White,
287
288 /// A colour number from 0 to 255, for use in 256-colour terminal
289 /// environments.
290 ///
291 /// - Colours 0 to 7 are the `Black` to `White` variants respectively.
292 /// These colours can usually be changed in the terminal emulator.
293 /// - Colours 8 to 15 are brighter versions of the eight colours above.
294 /// These can also usually be changed in the terminal emulator, or it
295 /// could be configured to use the original colours and show the text in
296 /// bold instead. It varies depending on the program.
297 /// - Colours 16 to 231 contain several palettes of bright colours,
298 /// arranged in six squares measuring six by six each.
299 /// - Colours 232 to 255 are shades of grey from black to white.
300 ///
301 /// It might make more sense to look at a [colour chart][cc].
302 ///
303 /// [cc]: https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg
304 Fixed(u8),
305
306 /// A 24-bit RGB color, as specified by ISO-8613-3.
307 RGB(u8, u8, u8),
308}
309
310
311impl Colour {
312
313 /// Returns a `Style` with the foreground colour set to this colour.
314 ///
315 /// # Examples
316 ///
317 /// ```
318 /// use ansi_term::Colour;
319 ///
320 /// let style = Colour::Red.normal();
321 /// println!("{}", style.paint("hi"));
322 /// ```
323 pub fn normal(self) -> Style {
324 Style { foreground: Some(self), .. Style::default() }
325 }
326
327 /// Returns a `Style` with the foreground colour set to this colour and the
328 /// bold property set.
329 ///
330 /// # Examples
331 ///
332 /// ```
333 /// use ansi_term::Colour;
334 ///
335 /// let style = Colour::Green.bold();
336 /// println!("{}", style.paint("hey"));
337 /// ```
338 pub fn bold(self) -> Style {
339 Style { foreground: Some(self), is_bold: true, .. Style::default() }
340 }
341
342 /// Returns a `Style` with the foreground colour set to this colour and the
343 /// dimmed property set.
344 ///
345 /// # Examples
346 ///
347 /// ```
348 /// use ansi_term::Colour;
349 ///
350 /// let style = Colour::Yellow.dimmed();
351 /// println!("{}", style.paint("sup"));
352 /// ```
353 pub fn dimmed(self) -> Style {
354 Style { foreground: Some(self), is_dimmed: true, .. Style::default() }
355 }
356
357 /// Returns a `Style` with the foreground colour set to this colour and the
358 /// italic property set.
359 ///
360 /// # Examples
361 ///
362 /// ```
363 /// use ansi_term::Colour;
364 ///
365 /// let style = Colour::Blue.italic();
366 /// println!("{}", style.paint("greetings"));
367 /// ```
368 pub fn italic(self) -> Style {
369 Style { foreground: Some(self), is_italic: true, .. Style::default() }
370 }
371
372 /// Returns a `Style` with the foreground colour set to this colour and the
373 /// underline property set.
374 ///
375 /// # Examples
376 ///
377 /// ```
378 /// use ansi_term::Colour;
379 ///
380 /// let style = Colour::Purple.underline();
381 /// println!("{}", style.paint("salutations"));
382 /// ```
383 pub fn underline(self) -> Style {
384 Style { foreground: Some(self), is_underline: true, .. Style::default() }
385 }
386
387 /// Returns a `Style` with the foreground colour set to this colour and the
388 /// blink property set.
389 ///
390 /// # Examples
391 ///
392 /// ```
393 /// use ansi_term::Colour;
394 ///
395 /// let style = Colour::Cyan.blink();
396 /// println!("{}", style.paint("wazzup"));
397 /// ```
398 pub fn blink(self) -> Style {
399 Style { foreground: Some(self), is_blink: true, .. Style::default() }
400 }
401
402 /// Returns a `Style` with the foreground colour set to this colour and the
403 /// reverse property set.
404 ///
405 /// # Examples
406 ///
407 /// ```
408 /// use ansi_term::Colour;
409 ///
410 /// let style = Colour::Black.reverse();
411 /// println!("{}", style.paint("aloha"));
412 /// ```
413 pub fn reverse(self) -> Style {
414 Style { foreground: Some(self), is_reverse: true, .. Style::default() }
415 }
416
417 /// Returns a `Style` with the foreground colour set to this colour and the
418 /// hidden property set.
419 ///
420 /// # Examples
421 ///
422 /// ```
423 /// use ansi_term::Colour;
424 ///
425 /// let style = Colour::White.hidden();
426 /// println!("{}", style.paint("ahoy"));
427 /// ```
428 pub fn hidden(self) -> Style {
429 Style { foreground: Some(self), is_hidden: true, .. Style::default() }
430 }
431
432 /// Returns a `Style` with the foreground colour set to this colour and the
433 /// strikethrough property set.
434 ///
435 /// # Examples
436 ///
437 /// ```
438 /// use ansi_term::Colour;
439 ///
440 /// let style = Colour::Fixed(244).strikethrough();
441 /// println!("{}", style.paint("yo"));
442 /// ```
443 pub fn strikethrough(self) -> Style {
444 Style { foreground: Some(self), is_strikethrough: true, .. Style::default() }
445 }
446
447 /// Returns a `Style` with the foreground colour set to this colour and the
448 /// background colour property set to the given colour.
449 ///
450 /// # Examples
451 ///
452 /// ```
453 /// use ansi_term::Colour;
454 ///
455 /// let style = Colour::RGB(31, 31, 31).on(Colour::White);
456 /// println!("{}", style.paint("eyyyy"));
457 /// ```
458 pub fn on(self, background: Colour) -> Style {
459 Style { foreground: Some(self), background: Some(background), .. Style::default() }
460 }
461}
462
463impl From<Colour> for Style {
464
465 /// You can turn a `Colour` into a `Style` with the foreground colour set
466 /// with the `From` trait.
467 ///
468 /// ```
469 /// use ansi_term::{Style, Colour};
470 /// let green_foreground = Style::default().fg(Colour::Green);
471 /// assert_eq!(green_foreground, Colour::Green.normal());
472 /// assert_eq!(green_foreground, Colour::Green.into());
473 /// assert_eq!(green_foreground, Style::from(Colour::Green));
474 /// ```
475 fn from(colour: Colour) -> Style {
476 colour.normal()
477 }
478}
479
480#[cfg(test)]
481#[cfg(feature = "derive_serde_style")]
482mod serde_json_tests {
483 use super::{Style, Colour};
484
485 #[test]
486 fn colour_serialization() {
487
488 let colours = &[
489 Colour::Red,
490 Colour::Blue,
491 Colour::RGB(123, 123, 123),
492 Colour::Fixed(255),
493 ];
494
495 assert_eq!(serde_json::to_string(&colours).unwrap(), String::from("[\"Red\",\"Blue\",{\"RGB\":[123,123,123]},{\"Fixed\":255}]"));
496 }
497
498 #[test]
499 fn colour_deserialization() {
500 let colours = &[
501 Colour::Red,
502 Colour::Blue,
503 Colour::RGB(123, 123, 123),
504 Colour::Fixed(255),
505 ];
506
507 for colour in colours.into_iter() {
508 let serialized = serde_json::to_string(&colour).unwrap();
509 let deserialized: Colour = serde_json::from_str(&serialized).unwrap();
510
511 assert_eq!(colour, &deserialized);
512 }
513 }
514
515 #[test]
516 fn style_serialization() {
517 let style = Style::default();
518
519 assert_eq!(serde_json::to_string(&style).unwrap(), "{\"foreground\":null,\"background\":null,\"is_bold\":false,\"is_dimmed\":false,\"is_italic\":false,\"is_underline\":false,\"is_blink\":false,\"is_reverse\":false,\"is_hidden\":false,\"is_strikethrough\":false}".to_string());
520 }
521}
522