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

and much more.
57

ticki's avatar
ticki committed
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
## Example

```rust
extern crate termion;

use termion::{TermWrite, color, Style};

use std::io;

fn main() {
    let stdout = io::stdout();
    let mut stdout = stdout.lock();

    stdout.color(color::Red).unwrap();
    println!("Red");

    stdout.color(color::Blue).unwrap();
    println!("Blue");

    stdout.style(Style::Bold).unwrap();
    println!("Blue'n'Bold");

    stdout.reset().unwrap();
    stdout.style(Style::Italic).unwrap();
    println!("Just plain italic")
}
```

## Usage
Ticki's avatar
Ticki committed
87 88 89

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

Antonin Carette's avatar
Antonin Carette committed
90
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
91

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

Ticki's avatar
Ticki committed
94

ticki's avatar
ticki committed
95
## TODO
96 97

- Mouse input
Ticki's avatar
Ticki committed
98

ticki's avatar
ticki committed
99
## License
Ticki's avatar
Ticki committed
100

ticki's avatar
ticki committed
101
MIT/X11.