]>
git.proxmox.com Git - rustc.git/blob - src/libterm/lib.rs
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 //! # #![feature(rustc_private)]
23 //! extern crate term;
25 //! use std::io::prelude::*;
28 //! let mut t = term::stdout().unwrap();
30 //! t.fg(term::color::GREEN).unwrap();
31 //! (write!(t, "hello, ")).unwrap();
33 //! t.fg(term::color::RED).unwrap();
34 //! (writeln!(t, "world!")).unwrap();
36 //! t.reset().unwrap();
40 //! [ansi]: https://en.wikipedia.org/wiki/ANSI_escape_code
41 //! [win]: http://msdn.microsoft.com/en-us/library/windows/desktop/ms682010%28v=vs.85%29.aspx
42 //! [ti]: https://en.wikipedia.org/wiki/Terminfo
44 // Do not remove on snapshot creation. Needed for bootstrap. (Issue #22364)
45 #![cfg_attr(stage0, feature(custom_attribute))]
46 #![crate_name = "term"]
47 #![unstable(feature = "rustc_private",
48 reason
= "use the crates.io `term` library instead")]
50 #![crate_type = "rlib"]
51 #![crate_type = "dylib"]
52 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
53 html_favicon_url
= "https://doc.rust-lang.org/favicon.ico",
54 html_root_url
= "http://doc.rust-lang.org/nightly/",
55 html_playground_url
= "http://play.rust-lang.org/")]
56 #![deny(missing_docs)]
58 #![feature(box_syntax)]
59 #![feature(owned_ascii_ext)]
61 #![feature(rustc_private)]
62 #![feature(staged_api)]
64 #![feature(vec_push_all)]
65 #![cfg_attr(windows, feature(libc))]
67 #[macro_use] extern crate log;
69 pub use terminfo
::TerminfoTerminal
;
71 pub use win
::WinConsole
;
73 use std
::io
::prelude
::*;
81 /// A hack to work around the fact that `Box<Write + Send>` does not
82 /// currently implement `Write`.
83 pub struct WriterWrapper
{
84 wrapped
: Box
<Write
+ Send
>,
87 impl Write
for WriterWrapper
{
89 fn write(&mut self, buf
: &[u8]) -> io
::Result
<usize> {
90 self.wrapped
.write(buf
)
94 fn flush(&mut self) -> io
::Result
<()> {
100 /// Return a Terminal wrapping stdout, or None if a terminal couldn't be
102 pub fn stdout() -> Option
<Box
<Terminal
<WriterWrapper
> + Send
>> {
103 TerminfoTerminal
::new(WriterWrapper
{
104 wrapped
: box std
::io
::stdout(),
109 /// Return a Terminal wrapping stdout, or None if a terminal couldn't be
111 pub fn stdout() -> Option
<Box
<Terminal
<WriterWrapper
> + Send
>> {
112 let ti
= TerminfoTerminal
::new(WriterWrapper
{
113 wrapped
: box std
::io
::stdout(),
119 WinConsole
::new(WriterWrapper
{
120 wrapped
: box std
::io
::stdout(),
127 /// Return a Terminal wrapping stderr, or None if a terminal couldn't be
129 pub fn stderr() -> Option
<Box
<Terminal
<WriterWrapper
> + Send
>> {
130 TerminfoTerminal
::new(WriterWrapper
{
131 wrapped
: box std
::io
::stderr(),
136 /// Return a Terminal wrapping stderr, or None if a terminal couldn't be
138 pub fn stderr() -> Option
<Box
<Terminal
<WriterWrapper
> + Send
>> {
139 let ti
= TerminfoTerminal
::new(WriterWrapper
{
140 wrapped
: box std
::io
::stderr(),
146 WinConsole
::new(WriterWrapper
{
147 wrapped
: box std
::io
::stderr(),
154 /// Terminal color definitions
156 /// Number for a terminal color
157 pub type Color
= u16;
159 pub const BLACK
: Color
= 0;
160 pub const RED
: Color
= 1;
161 pub const GREEN
: Color
= 2;
162 pub const YELLOW
: Color
= 3;
163 pub const BLUE
: Color
= 4;
164 pub const MAGENTA
: Color
= 5;
165 pub const CYAN
: Color
= 6;
166 pub const WHITE
: Color
= 7;
168 pub const BRIGHT_BLACK
: Color
= 8;
169 pub const BRIGHT_RED
: Color
= 9;
170 pub const BRIGHT_GREEN
: Color
= 10;
171 pub const BRIGHT_YELLOW
: Color
= 11;
172 pub const BRIGHT_BLUE
: Color
= 12;
173 pub const BRIGHT_MAGENTA
: Color
= 13;
174 pub const BRIGHT_CYAN
: Color
= 14;
175 pub const BRIGHT_WHITE
: Color
= 15;
178 /// Terminal attributes
180 pub use self::Attr
::*;
182 /// Terminal attributes for use with term.attr().
184 /// Most attributes can only be turned on and must be turned off with term.reset().
185 /// The ones that can be turned off explicitly take a boolean value.
186 /// Color is also represented as an attribute for convenience.
187 #[derive(Copy, Clone)]
189 /// Bold (or possibly bright) mode
191 /// Dim mode, also called faint or half-bright. Often not supported
193 /// Italics mode. Often not supported
199 /// Standout mode. Often implemented as Reverse, sometimes coupled with Bold
201 /// Reverse mode, inverts the foreground and background colors
203 /// Secure mode, also called invis mode. Hides the printed text
205 /// Convenience attribute to set the foreground color
206 ForegroundColor(super::color
::Color
),
207 /// Convenience attribute to set the background color
208 BackgroundColor(super::color
::Color
)
212 /// A terminal with similar capabilities to an ANSI Terminal
213 /// (foreground/background colors etc).
214 pub trait Terminal
<T
: Write
>: Write
{
215 /// Sets the foreground color to the given color.
217 /// If the color is a bright color, but the terminal only supports 8 colors,
218 /// the corresponding normal color will be used instead.
220 /// Returns `Ok(true)` if the color was set, `Ok(false)` otherwise, and `Err(e)`
221 /// if there was an I/O error.
222 fn fg(&mut self, color
: color
::Color
) -> io
::Result
<bool
>;
224 /// Sets the background color to the given color.
226 /// If the color is a bright color, but the terminal only supports 8 colors,
227 /// the corresponding normal color will be used instead.
229 /// Returns `Ok(true)` if the color was set, `Ok(false)` otherwise, and `Err(e)`
230 /// if there was an I/O error.
231 fn bg(&mut self, color
: color
::Color
) -> io
::Result
<bool
>;
233 /// Sets the given terminal attribute, if supported. Returns `Ok(true)`
234 /// if the attribute was supported, `Ok(false)` otherwise, and `Err(e)` if
235 /// there was an I/O error.
236 fn attr(&mut self, attr
: attr
::Attr
) -> io
::Result
<bool
>;
238 /// Returns whether the given terminal attribute is supported.
239 fn supports_attr(&self, attr
: attr
::Attr
) -> bool
;
241 /// Resets all terminal attributes and color to the default.
243 fn reset(&mut self) -> io
::Result
<()>;
245 /// Gets an immutable reference to the stream inside
246 fn get_ref
<'a
>(&'a
self) -> &'a T
;
248 /// Gets a mutable reference to the stream inside
249 fn get_mut
<'a
>(&'a
mut self) -> &'a
mut T
;
252 /// A terminal which can be unwrapped.
253 pub trait UnwrappableTerminal
<T
: Write
>: Terminal
<T
> {
254 /// Returns the contained stream, destroying the `Terminal`
255 fn unwrap(self) -> T
;