README.md
1<p align="center">
2<img alt="Termion logo" src="https://rawgit.com/redox-os/termion/master/logo.svg" />
3</p>
4
5[](https://travis-ci.org/redox-os/termion) [](https://crates.io/crates/termion) | [Documentation](https://docs.rs/termion) | [Examples](https://github.com/redox-os/termion/tree/master/examples) | [Changelog](https://github.com/redox-os/termion/tree/master/CHANGELOG.md) | [Tutorial](http://ticki.github.io/blog/making-terminal-applications-in-rust-with-termion/)
6|----|----|----|----|----
7
8
9**Termion** is a pure Rust, bindless library for low-level handling, manipulating
10and reading information about terminals. This provides a full-featured
11alternative to Termbox.
12
13Termion aims to be simple and yet expressive. It is bindless, meaning that it
14is not a front-end to some other library (e.g., ncurses or termbox), but a
15standalone library directly talking to the TTY.
16
17Termion is quite convenient, due to its complete coverage of essential TTY
18features, providing one consistent API. Termion is rather low-level containing
19only abstraction aligned with what actually happens behind the scenes. For
20something more high-level, refer to inquirer-rs, which uses Termion as backend.
21
22Termion generates escapes and API calls for the user. This makes it a whole lot
23cleaner to use escapes.
24
25Supports Redox, Mac OS X, BSD, and Linux (or, in general, ANSI terminals).
26
27## A note on stability
28
29This crate is stable.
30
31## Cargo.toml
32
33```toml
34[dependencies]
35termion = "*"
36```
37
38## 0.1.0 to 1.0.0 guide
39
40This sample table gives an idea of how to go about converting to the new major
41version of Termion.
42
43| 0.1.0 | 1.0.0
44|--------------------------------|---------------------------
45| `use termion::IntoRawMode` | `use termion::raw::IntoRawMode`
46| `use termion::TermRead` | `use termion::input::TermRead`
47| `stdout.color(color::Red);` | `write!(stdout, "{}", color::Fg(color::Red));`
48| `stdout.color_bg(color::Red);` | `write!(stdout, "{}", color::Bg(color::Red));`
49| `stdout.goto(x, y);` | `write!(stdout, "{}", cursor::Goto(x, y));`
50| `color::rgb(r, g, b);` | `color::Rgb(r, g, b)` (truecolor)
51| `x.with_mouse()` | `MouseTerminal::from(x)`
52
53## Features
54
55- Raw mode.
56- TrueColor.
57- 256-color mode.
58- Cursor movement.
59- Text formatting.
60- Console size.
61- TTY-only stream.
62- Control sequences.
63- Termios control.
64- Password input.
65- Redox support.
66- Safe `isatty` wrapper.
67- Panic-free error handling.
68- Special keys events (modifiers, special keys, etc.).
69- Allocation-free.
70- Asynchronous key events.
71- Mouse input.
72- Carefully tested.
73- Detailed documentation on every item.
74
75and much more.
76
77## Examples
78
79### Style and colors.
80
81```rust
82extern crate termion;
83
84use termion::{color, style};
85
86use std::io;
87
88fn main() {
89 println!("{}Red", color::Fg(color::Red));
90 println!("{}Blue", color::Fg(color::Blue));
91 println!("{}Blue'n'Bold{}", style::Bold, style::Reset);
92 println!("{}Just plain italic", style::Italic);
93}
94```
95
96### Moving the cursor
97
98```rust
99extern crate termion;
100
101fn main() {
102 print!("{}{}Stuff", termion::clear::All, termion::cursor::Goto(1, 1));
103}
104
105```
106
107### Mouse
108
109```rust
110extern crate termion;
111
112use termion::event::{Key, Event, MouseEvent};
113use termion::input::{TermRead, MouseTerminal};
114use termion::raw::IntoRawMode;
115use std::io::{Write, stdout, stdin};
116
117fn main() {
118 let stdin = stdin();
119 let mut stdout = MouseTerminal::from(stdout().into_raw_mode().unwrap());
120
121 write!(stdout, "{}{}q to exit. Click, click, click!", termion::clear::All, termion::cursor::Goto(1, 1)).unwrap();
122 stdout.flush().unwrap();
123
124 for c in stdin.events() {
125 let evt = c.unwrap();
126 match evt {
127 Event::Key(Key::Char('q')) => break,
128 Event::Mouse(me) => {
129 match me {
130 MouseEvent::Press(_, x, y) => {
131 write!(stdout, "{}x", termion::cursor::Goto(x, y)).unwrap();
132 },
133 _ => (),
134 }
135 }
136 _ => {}
137 }
138 stdout.flush().unwrap();
139 }
140}
141```
142
143### Read a password
144
145```rust
146extern crate termion;
147
148use termion::input::TermRead;
149use std::io::{Write, stdout, stdin};
150
151fn main() {
152 let stdout = stdout();
153 let mut stdout = stdout.lock();
154 let stdin = stdin();
155 let mut stdin = stdin.lock();
156
157 stdout.write_all(b"password: ").unwrap();
158 stdout.flush().unwrap();
159
160 let pass = stdin.read_passwd(&mut stdout);
161
162 if let Ok(Some(pass)) = pass {
163 stdout.write_all(pass.as_bytes()).unwrap();
164 stdout.write_all(b"\n").unwrap();
165 } else {
166 stdout.write_all(b"Error\n").unwrap();
167 }
168}
169```
170
171## Usage
172
173See `examples/`, and the documentation, which can be rendered using `cargo doc`.
174
175For a more complete example, see [a minesweeper implementation](https://github.com/redox-os/games-for-redox/blob/master/src/minesweeper/main.rs), that I made for Redox using termion.
176
177<img src="image.png" width="200">
178
179## License
180
181MIT/X11.
182
){kind=link}
){kind=link}
