README.md 1.87 KB
Newer Older
ticki's avatar
ticki committed
1
# Termion
Ticki's avatar
Ticki committed
2

ticki's avatar
ticki committed
3 4 5
Termion is a pure Rust, bindless library for low-level handling, manipulating
and reading information about terminals. This provides a full-featured
alternative to Termbox.
6

ticki's avatar
ticki committed
7 8 9 10 11
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.

Supports Redox, Mac OS X, and Linux (or, in general, ANSI terminals).
Ticki's avatar
Ticki committed
12

ticki's avatar
ticki committed
13
[Documentation.](http://ticki.github.io/termion/) | [Examples.](https://github.com/Ticki/termion/tree/master/examples)
Ticki's avatar
Ticki committed
14

ticki's avatar
ticki committed
15
## A note on stability
Ticki's avatar
Ticki committed
16

ticki's avatar
ticki committed
17 18
Although small breaking changes might happen, I will try my best to avoid them,
and this crate can generally be considered stable.
Ticki's avatar
Ticki committed
19

ticki's avatar
ticki committed
20 21 22 23
## Cargo.toml

```toml
[dependencies.termion]
ticki's avatar
ticki committed
24
git = "https://github.com/ticki/termion.git"
ticki's avatar
ticki committed
25 26
```

ticki's avatar
ticki committed
27
## Features
28 29

- Raw mode.
ticki's avatar
ticki committed
30
- TrueColor.
ticki's avatar
ticki committed
31
- 256-color mode.
32 33
- Cursor movement.
- Color output.
ticki's avatar
ticki committed
34
- Calculating ANSI escapes.
35 36 37 38 39
- Text formatting.
- Console size.
- Control sequences.
- Termios control.
- Password input.
Ticki's avatar
Ticki committed
40
- Redox support.
ticki's avatar
ticki committed
41
- Safe `isatty` wrapper.
Ticki's avatar
Ticki committed
42
- Panic-free error handling.
Ticki's avatar
Ticki committed
43
- Special keys events (modifiers, special keys, etc.).
ticki's avatar
ticki committed
44
- Allocation-free.
Ticki's avatar
Ticki committed
45
- Asynchronous key events.
IGI-111's avatar
IGI-111 committed
46
- Mouse input
ticki's avatar
ticki committed
47
- Carefully tested.
Ticki's avatar
Ticki committed
48 49

and much more.
50

ticki's avatar
ticki committed
51 52 53 54 55
## Example

```rust
extern crate termion;

56
use termion::{color, style};
ticki's avatar
ticki committed
57 58 59 60

use std::io;

fn main() {
61
    println!("{}Red", color::Fg(color::Red));
ticki's avatar
ticki committed
62

63
    println!("{}Blue", color::Fg(color::Blue));
ticki's avatar
ticki committed
64

65
    println!("{}Blue'n'Bold{}", style::Bold, style::Reset);
ticki's avatar
ticki committed
66

67
    println!("{}Just plain italic", style::Italic);
ticki's avatar
ticki committed
68 69 70 71
}
```

## Usage
Ticki's avatar
Ticki committed
72 73 74

See `examples/`, and the documentation, which can be rendered using `cargo doc`.

Antonin Carette's avatar
Antonin Carette committed
75
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.
Ticki's avatar
Ticki committed
76

ticki's avatar
ticki committed
77
<img src="image.png" width="200">
Ticki's avatar
Resize  
Ticki committed
78

Ticki's avatar
Ticki committed
79

ticki's avatar
ticki committed
80
## License
Ticki's avatar
Ticki committed
81

ticki's avatar
ticki committed
82
MIT/X11.