1//! Terminal formatting module.
2//!
3//! This module provides the `Terminal` trait, which abstracts over an [ANSI
4//! Terminal][ansi] to provide color printing, among other things. There are two
5//! implementations, the `TerminfoTerminal`, which uses control characters from
6//! a [terminfo][ti] database, and `WinConsole`, which uses the [Win32 Console
7//! API][win].
8//!
9//! [ansi]: https://en.wikipedia.org/wiki/ANSI_escape_code
10//! [win]: https://docs.microsoft.com/en-us/windows/console/character-mode-applications
11//! [ti]: https://en.wikipedia.org/wiki/Terminfo
12
13#![deny(missing_docs)]
14
15use std::io::{self, prelude::*};
16
17pub(crate) use terminfo::TerminfoTerminal;
18#[cfg(windows)]
19pub(crate) use win::WinConsole;
20
21pub(crate) mod terminfo;
22
23#[cfg(windows)]
24mod win;
25
26/// Alias for stdout terminals.
27pub(crate) type StdoutTerminal = dyn Terminal + Send;
28
29#[cfg(not(windows))]
30/// Returns a Terminal wrapping stdout, or None if a terminal couldn't be
31/// opened.
32pub(crate) fn stdout() -> Option<Box<StdoutTerminal>> {
33 TerminfoTerminal::new(out:io::stdout()).map(|t| Box::new(t) as Box<StdoutTerminal>)
34}
35
36#[cfg(windows)]
37/// Returns a Terminal wrapping stdout, or None if a terminal couldn't be
38/// opened.
39pub(crate) fn stdout() -> Option<Box<StdoutTerminal>> {
40 TerminfoTerminal::new(io::stdout())
41 .map(|t| Box::new(t) as Box<StdoutTerminal>)
42 .or_else(|| Some(Box::new(WinConsole::new(io::stdout())) as Box<StdoutTerminal>))
43}
44
45/// Terminal color definitions
46#[allow(missing_docs)]
47#[cfg_attr(not(windows), allow(dead_code))]
48pub(crate) mod color {
49 /// Number for a terminal color
50 pub(crate) type Color = u32;
51
52 pub(crate) const BLACK: Color = 0;
53 pub(crate) const RED: Color = 1;
54 pub(crate) const GREEN: Color = 2;
55 pub(crate) const YELLOW: Color = 3;
56 pub(crate) const BLUE: Color = 4;
57 pub(crate) const MAGENTA: Color = 5;
58 pub(crate) const CYAN: Color = 6;
59 pub(crate) const WHITE: Color = 7;
60}
61
62/// A terminal with similar capabilities to an ANSI Terminal
63/// (foreground/background colors etc).
64pub trait Terminal: Write {
65 /// Sets the foreground color to the given color.
66 ///
67 /// If the color is a bright color, but the terminal only supports 8 colors,
68 /// the corresponding normal color will be used instead.
69 ///
70 /// Returns `Ok(true)` if the color was set, `Ok(false)` otherwise, and `Err(e)`
71 /// if there was an I/O error.
72 fn fg(&mut self, color: color::Color) -> io::Result<bool>;
73
74 /// Resets all terminal attributes and colors to their defaults.
75 ///
76 /// Returns `Ok(true)` if the terminal was reset, `Ok(false)` otherwise, and `Err(e)` if there
77 /// was an I/O error.
78 ///
79 /// *Note: This does not flush.*
80 ///
81 /// That means the reset command may get buffered so, if you aren't planning on doing anything
82 /// else that might flush stdout's buffer (e.g., writing a line of text), you should flush after
83 /// calling reset.
84 fn reset(&mut self) -> io::Result<bool>;
85}
86