termion/README.md

182 lines
5.0 KiB
Markdown
Raw Normal View History

2016-12-19 16:33:09 +00:00
<p align="center">
2016-12-19 16:34:48 +00:00
<img alt="Termion logo" src="https://rawgit.com/ticki/termion/master/logo.svg" />
2016-12-19 16:34:09 +00:00
</p>
2016-12-19 16:33:09 +00:00
2016-12-19 16:39:41 +00:00
[![Build Status](https://travis-ci.org/ticki/termion.svg?branch=master)](https://travis-ci.org/ticki/termion) [![Latest Version](https://img.shields.io/crates/v/termion.svg)](https://crates.io/crates/termion) &emsp; | [Documentation](https://docs.rs/termion) | [Examples](https://github.com/Ticki/termion/tree/master/examples) | [Changelog](https://github.com/Ticki/termion/tree/master/CHANGELOG.md) | [Tutorial](http://ticki.github.io/blog/making-terminal-applications-in-rust-with-termion/)
2016-12-19 16:36:29 +00:00
|----|----|----|----|----
2016-09-07 10:39:32 +01:00
2016-09-07 10:39:32 +01:00
**Termion** is a pure Rust, bindless library for low-level handling, manipulating
2016-07-02 14:42:18 +01:00
and reading information about terminals. This provides a full-featured
alternative to Termbox.
2016-07-02 14:42:18 +01:00
Termion aims to be simple and yet expressive. It is bindless, meaning that it
is not a front-end to some other library (e.g., ncurses or termbox), but a
standalone library directly talking to the TTY.
2016-12-19 15:59:28 +00:00
Termion is quite convenient, due to its complete coverage of essential TTY
2016-07-23 23:32:21 +01:00
features, providing one consistent API. Termion is rather low-level containing
2016-12-19 15:59:28 +00:00
only abstraction aligned with what actually happens behind the scenes. For
2016-07-23 23:32:21 +01:00
something more high-level, refer to inquirer-rs, which uses Termion as backend.
2016-03-07 21:19:35 +00:00
2016-07-23 23:32:21 +01:00
Termion generates escapes and API calls for the user. This makes it a whole lot
cleaner to use escapes.
Supports Redox, Mac OS X, BSD, and Linux (or, in general, ANSI terminals).
2016-07-02 14:06:47 +01:00
## A note on stability
2016-03-08 18:44:31 +00:00
2016-10-02 21:33:06 +01:00
This crate is stable.
2016-03-08 18:44:31 +00:00
2016-07-03 12:27:07 +01:00
## Cargo.toml
```toml
2016-07-23 23:32:21 +01:00
[dependencies]
2016-08-01 10:55:24 +01:00
termion = "1.0"
2016-07-03 12:27:07 +01:00
```
2016-07-23 23:32:21 +01:00
## 0.1.0 to 1.0.0 guide
2016-10-02 21:33:06 +01:00
This sample table gives an idea of how to go about converting to the new major
2016-07-23 23:32:21 +01:00
version of Termion.
| 0.1.0 | 1.0.0
|--------------------------------|---------------------------
| `use termion::IntoRawMode` | `use termion::raw::IntoRawMode`
2016-07-27 19:42:59 +01:00
| `use termion::TermRead` | `use termion::input::TermRead`
2016-07-23 23:32:21 +01:00
| `stdout.color(color::Red);` | `write!(stdout, "{}", color::Fg(color::Red));`
| `stdout.color_bg(color::Red);` | `write!(stdout, "{}", color::Bg(color::Red));`
| `stdout.goto(x, y);` | `write!(stdout, "{}", cursor::Goto(x, y));`
| `color::rgb(r, g, b);` | `color::Rgb(r, g, b)` (truecolor)
| `x.with_mouse()` | `MouseTerminal::from(x)`
2016-07-02 14:06:47 +01:00
## Features
- Raw mode.
2016-07-23 16:32:08 +01:00
- TrueColor.
2016-06-14 13:29:31 +01:00
- 256-color mode.
- Cursor movement.
- Text formatting.
- Console size.
2016-07-29 18:49:29 +01:00
- TTY-only stream.
- Control sequences.
- Termios control.
- Password input.
2016-03-08 18:44:31 +00:00
- Redox support.
2016-07-23 16:32:08 +01:00
- Safe `isatty` wrapper.
2016-03-08 18:44:31 +00:00
- Panic-free error handling.
2016-03-15 19:32:25 +00:00
- Special keys events (modifiers, special keys, etc.).
2016-06-14 13:29:31 +01:00
- Allocation-free.
2016-03-15 19:32:25 +00:00
- Asynchronous key events.
- Mouse input.
2016-07-02 14:06:47 +01:00
- Carefully tested.
- Detailed documentation on every item.
2016-03-08 18:44:31 +00:00
and much more.
2016-07-23 23:32:21 +01:00
## Examples
### Style and colors.
2016-07-02 14:06:47 +01:00
```rust
extern crate termion;
use termion::{color, style};
2016-07-02 14:06:47 +01:00
use std::io;
fn main() {
println!("{}Red", color::Fg(color::Red));
println!("{}Blue", color::Fg(color::Blue));
println!("{}Blue'n'Bold{}", style::Bold, style::Reset);
println!("{}Just plain italic", style::Italic);
2016-07-02 14:06:47 +01:00
}
```
2016-07-23 23:32:21 +01:00
### Moving the cursor
```rust
extern crate termion;
fn main() {
print!("{}{}Stuff", termion::clear::All, termion::cursor::Goto(1, 1));
}
```
### Mouse
```rust
extern crate termion;
use termion::event::{Key, Event, MouseEvent};
use termion::input::{TermRead, MouseTerminal};
use termion::raw::IntoRawMode;
use std::io::{Write, stdout, stdin};
fn main() {
let stdin = stdin();
let mut stdout = MouseTerminal::from(stdout().into_raw_mode().unwrap());
write!(stdout, "{}{}q to exit. Click, click, click!", termion::clear::All, termion::cursor::Goto(1, 1)).unwrap();
stdout.flush().unwrap();
for c in stdin.events() {
let evt = c.unwrap();
match evt {
Event::Key(Key::Char('q')) => break,
Event::Mouse(me) => {
match me {
MouseEvent::Press(_, x, y) => {
write!(stdout, "{}x", termion::cursor::Goto(x, y)).unwrap();
},
_ => (),
}
}
_ => {}
}
stdout.flush().unwrap();
}
}
```
### Read a password
```rust
extern crate termion;
use termion::input::TermRead;
use std::io::{Write, stdout, stdin};
fn main() {
let stdout = stdout();
let mut stdout = stdout.lock();
let stdin = stdin();
let mut stdin = stdin.lock();
stdout.write_all(b"password: ").unwrap();
2016-07-23 23:32:21 +01:00
stdout.flush().unwrap();
let pass = stdin.read_passwd(&mut stdout);
if let Ok(Some(pass)) = pass {
stdout.write_all(pass.as_bytes()).unwrap();
stdout.write_all(b"\n").unwrap();
2016-07-23 23:32:21 +01:00
} else {
stdout.write_all(b"Error\n").unwrap();
2016-07-23 23:32:21 +01:00
}
}
```
2016-07-02 14:06:47 +01:00
## Usage
2016-03-15 19:39:08 +00:00
See `examples/`, and the documentation, which can be rendered using `cargo doc`.
2016-04-02 21:48:12 +01:00
For 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.
2016-03-15 19:39:08 +00:00
2016-07-02 14:06:47 +01:00
<img src="image.png" width="200">
2016-03-16 07:14:58 +00:00
2016-07-02 14:06:47 +01:00
## License
2016-03-06 13:55:01 +00:00
2016-07-02 14:06:47 +01:00
MIT/X11.