|
| 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 | + |
| 15 | +use std::io::{self, prelude::*}; |
| 16 | + |
| 17 | +pub(crate) use terminfo::TerminfoTerminal; |
| 18 | +#[cfg(windows)] |
| 19 | +pub(crate) use win::WinConsole; |
| 20 | + |
| 21 | +pub(crate) mod terminfo; |
| 22 | + |
| 23 | +#[cfg(windows)] |
| 24 | +mod win; |
| 25 | + |
| 26 | +/// Alias for stdout terminals. |
| 27 | +pub(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. |
| 32 | +pub(crate) fn stdout() -> Option<Box<StdoutTerminal>> { |
| 33 | + TerminfoTerminal::new(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. |
| 39 | +pub(crate) fn stdout() -> Option<Box<StdoutTerminal>> { |
| 40 | + TerminfoTerminal::new(io::stdout()) |
| 41 | + .map(|t| Box::new(t) as Box<StdoutTerminal>) |
| 42 | + .or_else(|| WinConsole::new(io::stdout()).ok().map(|t| Box::new(t) as Box<StdoutTerminal>)) |
| 43 | +} |
| 44 | + |
| 45 | +/// Terminal color definitions |
| 46 | +#[allow(missing_docs)] |
| 47 | +#[cfg_attr(not(windows), allow(dead_code))] |
| 48 | +pub(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). |
| 64 | +pub 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 | +} |
0 commit comments