README.md 5.03 KB
Newer Older
ticki's avatar
ticki committed
1
<p align="center">
2
<img alt="Termion logo" src="https://rawgit.com/redox-os/termion/master/logo.svg" />
ticki's avatar
ticki committed
3
</p>
ticki's avatar
ticki committed
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/)
ticki's avatar
ticki committed
6
|----|----|----|----|----
ticki's avatar
ticki committed
7

Alexandre Bury's avatar
Alexandre Bury committed
8

ticki's avatar
ticki committed
9
**Termion** is a pure Rust, bindless library for low-level handling, manipulating
ticki's avatar
ticki committed
10
11
and reading information about terminals. This provides a full-featured
alternative to Termbox.
12

ticki's avatar
ticki committed
13
14
15
16
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.

Alexandre Bury's avatar
Alexandre Bury committed
17
Termion is quite convenient, due to its complete coverage of essential TTY
ticki's avatar
ticki committed
18
features, providing one consistent API. Termion is rather low-level containing
Alexandre Bury's avatar
Alexandre Bury committed
19
only abstraction aligned with what actually happens behind the scenes. For
ticki's avatar
ticki committed
20
something more high-level, refer to inquirer-rs, which uses Termion as backend.
Ticki's avatar
Ticki committed
21

ticki's avatar
ticki committed
22
23
24
25
26
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).

ticki's avatar
ticki committed
27
## A note on stability
Ticki's avatar
Ticki committed
28

ticki's avatar
ticki committed
29
This crate is stable.
Ticki's avatar
Ticki committed
30

ticki's avatar
ticki committed
31
32
33
## Cargo.toml

```toml
ticki's avatar
ticki committed
34
[dependencies]
ticki's avatar
ticki committed
35
termion = "*"
ticki's avatar
ticki committed
36
37
```

ticki's avatar
ticki committed
38
39
## 0.1.0 to 1.0.0 guide

ticki's avatar
ticki committed
40
This sample table gives an idea of how to go about converting to the new major
ticki's avatar
ticki committed
41
42
43
44
45
version of Termion.

| 0.1.0                          | 1.0.0
|--------------------------------|---------------------------
| `use termion::IntoRawMode`     | `use termion::raw::IntoRawMode`
46
| `use termion::TermRead`        | `use termion::input::TermRead`
ticki's avatar
ticki committed
47
48
49
50
51
52
| `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)`

ticki's avatar
ticki committed
53
## Features
54
55

- Raw mode.
ticki's avatar
ticki committed
56
- TrueColor.
ticki's avatar
ticki committed
57
- 256-color mode.
58
59
60
- Cursor movement.
- Text formatting.
- Console size.
ticki's avatar
ticki committed
61
- TTY-only stream.
62
63
64
- Control sequences.
- Termios control.
- Password input.
Ticki's avatar
Ticki committed
65
- Redox support.
ticki's avatar
ticki committed
66
- Safe `isatty` wrapper.
Ticki's avatar
Ticki committed
67
- Panic-free error handling.
Ticki's avatar
Ticki committed
68
- Special keys events (modifiers, special keys, etc.).
ticki's avatar
ticki committed
69
- Allocation-free.
Ticki's avatar
Ticki committed
70
- Asynchronous key events.
71
- Mouse input.
ticki's avatar
ticki committed
72
- Carefully tested.
73
- Detailed documentation on every item.
Ticki's avatar
Ticki committed
74
75

and much more.
76

ticki's avatar
ticki committed
77
78
79
## Examples

### Style and colors.
ticki's avatar
ticki committed
80
81
82
83

```rust
extern crate termion;

84
use termion::{color, style};
ticki's avatar
ticki committed
85
86
87
88

use std::io;

fn main() {
89
90
91
92
    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);
ticki's avatar
ticki committed
93
94
95
}
```

ticki's avatar
ticki committed
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
### 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();

157
    stdout.write_all(b"password: ").unwrap();
ticki's avatar
ticki committed
158
159
160
161
162
    stdout.flush().unwrap();

    let pass = stdin.read_passwd(&mut stdout);

    if let Ok(Some(pass)) = pass {
163
164
        stdout.write_all(pass.as_bytes()).unwrap();
        stdout.write_all(b"\n").unwrap();
ticki's avatar
ticki committed
165
    } else {
166
        stdout.write_all(b"Error\n").unwrap();
ticki's avatar
ticki committed
167
168
169
170
    }
}
```

ticki's avatar
ticki committed
171
## Usage
Ticki's avatar
Ticki committed
172
173
174

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

Antonin Carette's avatar
Antonin Carette committed
175
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
176

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

ticki's avatar
ticki committed
179
## License
Ticki's avatar
Ticki committed
180

ticki's avatar
ticki committed
181
MIT/X11.