1<p align="center"> 2<img alt="Termion logo" src="https://rawgit.com/redox-os/termion/master/logo.svg" /> 3</p> 4 5[![Build Status](https://travis-ci.org/redox-os/termion.svg?branch=master)](https://travis-ci.org/redox-os/termion) [![Latest Version](https://img.shields.io/crates/v/termion.svg)](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