README.md 1.99 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 24 25
## Cargo.toml

For nightly, add

```toml
[dependencies.termion]
ticki's avatar
ticki committed
26
git = "https://github.com/ticki/termion.git"
ticki's avatar
ticki committed
27 28 29 30 31 32
```

For stable,

```toml
[dependencies.termion]
ticki's avatar
ticki committed
33
git = "https://github.com/ticki/termion.git"
ticki's avatar
ticki committed
34 35 36
default-features = false
```

ticki's avatar
ticki committed
37
## Features
38 39

- Raw mode.
40
- Truecolor.
ticki's avatar
ticki committed
41
- 256-color mode.
42 43
- Cursor movement.
- Color output.
ticki's avatar
ticki committed
44
- Calculating ANSI escapes.
45 46 47 48 49
- Text formatting.
- Console size.
- Control sequences.
- Termios control.
- Password input.
Ticki's avatar
Ticki committed
50 51
- Redox support.
- Panic-free error handling.
Ticki's avatar
Ticki committed
52
- Special keys events (modifiers, special keys, etc.).
ticki's avatar
ticki committed
53
- Allocation-free.
Ticki's avatar
Ticki committed
54
- Asynchronous key events.
ticki's avatar
ticki committed
55
- Carefully tested.
Ticki's avatar
Ticki committed
56 57

and much more.
58

ticki's avatar
ticki committed
59 60 61 62 63
## Example

```rust
extern crate termion;

64
use termion::{color, style};
ticki's avatar
ticki committed
65 66 67 68

use std::io;

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

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

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

75
    println!("{}Just plain italic", style::Italic);
ticki's avatar
ticki committed
76 77 78 79
}
```

## Usage
Ticki's avatar
Ticki committed
80 81 82

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

Antonin Carette's avatar
Antonin Carette committed
83
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
84

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

Ticki's avatar
Ticki committed
87

ticki's avatar
ticki committed
88
## TODO
89 90

- Mouse input
Ticki's avatar
Ticki committed
91

ticki's avatar
ticki committed
92
## License
Ticki's avatar
Ticki committed
93

ticki's avatar
ticki committed
94
MIT/X11.