1 // Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! Terminal formatting library.
13 //! This crate provides the `Terminal` trait, which abstracts over an [ANSI
14 //! Terminal][ansi] to provide color printing, among other things. There are two implementations,
15 //! the `TerminfoTerminal`, which uses control characters from a
16 //! [terminfo][ti] database, and `WinConsole`, which uses the [Win32 Console
22 //! extern crate term;
25 //! let mut t = term::stdout().unwrap();
27 //! t.fg(term::color::GREEN).unwrap();
28 //! (write!(t, "hello, ")).unwrap();
30 //! t.fg(term::color::RED).unwrap();
31 //! (writeln!(t, "world!")).unwrap();
33 //! t.reset().unwrap();
37 //! [ansi]: https://en.wikipedia.org/wiki/ANSI_escape_code
38 //! [win]: http://msdn.microsoft.com/en-us/library/windows/desktop/ms682010%28v=vs.85%29.aspx
39 //! [ti]: https://en.wikipedia.org/wiki/Terminfo
41 #![crate_name = "term"]
42 #![unstable(feature = "rustc_private",
43 reason = "use the crates.io `term` library instead")]
45 #![crate_type = "rlib"]
46 #![crate_type = "dylib"]
47 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
48 html_favicon_url = "http://www.rust-lang.org/favicon.ico",
49 html_root_url = "http://doc.rust-lang.org/nightly/",
50 html_playground_url = "http://play.rust-lang.org/")]
51 #![deny(missing_docs)]
53 #![feature(box_syntax)]
54 #![feature(collections)]
58 #![feature(rustc_private)]
59 #![feature(staged_api)]
63 #![cfg_attr(windows, feature(libc))]
65 #[macro_use] extern crate log;
67 pub use terminfo::TerminfoTerminal;
69 pub use win::WinConsole;
71 use std::old_io::IoResult;
78 /// A hack to work around the fact that `Box<Writer + Send>` does not
79 /// currently implement `Writer`.
80 pub struct WriterWrapper {
81 wrapped: Box<Writer + Send>,
84 impl Writer for WriterWrapper {
86 fn write_all(&mut self, buf: &[u8]) -> IoResult<()> {
87 self.wrapped.write_all(buf)
91 fn flush(&mut self) -> IoResult<()> {
97 /// Return a Terminal wrapping stdout, or None if a terminal couldn't be
99 pub fn stdout() -> Option<Box<Terminal<WriterWrapper> + Send>> {
100 TerminfoTerminal::new(WriterWrapper {
101 wrapped: box std::old_io::stdout() as Box<Writer + Send>,
106 /// Return a Terminal wrapping stdout, or None if a terminal couldn't be
108 pub fn stdout() -> Option<Box<Terminal<WriterWrapper> + Send>> {
109 let ti = TerminfoTerminal::new(WriterWrapper {
110 wrapped: box std::old_io::stdout() as Box<Writer + Send>,
116 WinConsole::new(WriterWrapper {
117 wrapped: box std::old_io::stdout() as Box<Writer + Send>,
124 /// Return a Terminal wrapping stderr, or None if a terminal couldn't be
126 pub fn stderr() -> Option<Box<Terminal<WriterWrapper> + Send>> {
127 TerminfoTerminal::new(WriterWrapper {
128 wrapped: box std::old_io::stderr() as Box<Writer + Send>,
133 /// Return a Terminal wrapping stderr, or None if a terminal couldn't be
135 pub fn stderr() -> Option<Box<Terminal<WriterWrapper> + Send>> {
136 let ti = TerminfoTerminal::new(WriterWrapper {
137 wrapped: box std::old_io::stderr() as Box<Writer + Send>,
143 WinConsole::new(WriterWrapper {
144 wrapped: box std::old_io::stderr() as Box<Writer + Send>,
151 /// Terminal color definitions
153 /// Number for a terminal color
154 pub type Color = u16;
156 pub const BLACK: Color = 0u16;
157 pub const RED: Color = 1u16;
158 pub const GREEN: Color = 2u16;
159 pub const YELLOW: Color = 3u16;
160 pub const BLUE: Color = 4u16;
161 pub const MAGENTA: Color = 5u16;
162 pub const CYAN: Color = 6u16;
163 pub const WHITE: Color = 7u16;
165 pub const BRIGHT_BLACK: Color = 8u16;
166 pub const BRIGHT_RED: Color = 9u16;
167 pub const BRIGHT_GREEN: Color = 10u16;
168 pub const BRIGHT_YELLOW: Color = 11u16;
169 pub const BRIGHT_BLUE: Color = 12u16;
170 pub const BRIGHT_MAGENTA: Color = 13u16;
171 pub const BRIGHT_CYAN: Color = 14u16;
172 pub const BRIGHT_WHITE: Color = 15u16;
175 /// Terminal attributes
177 pub use self::Attr::*;
179 /// Terminal attributes for use with term.attr().
181 /// Most attributes can only be turned on and must be turned off with term.reset().
182 /// The ones that can be turned off explicitly take a boolean value.
183 /// Color is also represented as an attribute for convenience.
186 /// Bold (or possibly bright) mode
188 /// Dim mode, also called faint or half-bright. Often not supported
190 /// Italics mode. Often not supported
196 /// Standout mode. Often implemented as Reverse, sometimes coupled with Bold
198 /// Reverse mode, inverts the foreground and background colors
200 /// Secure mode, also called invis mode. Hides the printed text
202 /// Convenience attribute to set the foreground color
203 ForegroundColor(super::color::Color),
204 /// Convenience attribute to set the background color
205 BackgroundColor(super::color::Color)
209 /// A terminal with similar capabilities to an ANSI Terminal
210 /// (foreground/background colors etc).
211 pub trait Terminal<T: Writer>: Writer {
212 /// Sets the foreground color to the given color.
214 /// If the color is a bright color, but the terminal only supports 8 colors,
215 /// the corresponding normal color will be used instead.
217 /// Returns `Ok(true)` if the color was set, `Ok(false)` otherwise, and `Err(e)`
218 /// if there was an I/O error.
219 fn fg(&mut self, color: color::Color) -> IoResult<bool>;
221 /// Sets the background color to the given color.
223 /// If the color is a bright color, but the terminal only supports 8 colors,
224 /// the corresponding normal color will be used instead.
226 /// Returns `Ok(true)` if the color was set, `Ok(false)` otherwise, and `Err(e)`
227 /// if there was an I/O error.
228 fn bg(&mut self, color: color::Color) -> IoResult<bool>;
230 /// Sets the given terminal attribute, if supported. Returns `Ok(true)`
231 /// if the attribute was supported, `Ok(false)` otherwise, and `Err(e)` if
232 /// there was an I/O error.
233 fn attr(&mut self, attr: attr::Attr) -> IoResult<bool>;
235 /// Returns whether the given terminal attribute is supported.
236 fn supports_attr(&self, attr: attr::Attr) -> bool;
238 /// Resets all terminal attributes and color to the default.
240 fn reset(&mut self) -> IoResult<()>;
242 /// Gets an immutable reference to the stream inside
243 fn get_ref<'a>(&'a self) -> &'a T;
245 /// Gets a mutable reference to the stream inside
246 fn get_mut<'a>(&'a mut self) -> &'a mut T;
249 /// A terminal which can be unwrapped.
250 pub trait UnwrappableTerminal<T: Writer>: Terminal<T> {
251 /// Returns the contained stream, destroying the `Terminal`
252 fn unwrap(self) -> T;