library/test/src/term.rs

   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 }