README.md 4.97 KB
Newer Older
ticki's avatar
ticki committed
1 2 3 4 5
<p align="center">
![Termion logo](https://rawgit.com/ticki/tfs/master/icon.svg)

[![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)
</p>
Ticki's avatar
Ticki committed
6

ticki's avatar
ticki committed
7 8
[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/)
|----|----|----|----
ticki's avatar
ticki committed
9

Alexandre Bury's avatar
Alexandre Bury committed
10

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

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

ticki's avatar
ticki committed
24 25 26 27 28
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
29
## A note on stability
Ticki's avatar
Ticki committed
30

ticki's avatar
ticki committed
31
This crate is stable.
Ticki's avatar
Ticki committed
32

ticki's avatar
ticki committed
33 34 35
## Cargo.toml

```toml
ticki's avatar
ticki committed
36
[dependencies]
ticki's avatar
ticki committed
37
termion = "1.0"
ticki's avatar
ticki committed
38 39
```

ticki's avatar
ticki committed
40 41
## 0.1.0 to 1.0.0 guide

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

| 0.1.0                          | 1.0.0
|--------------------------------|---------------------------
| `use termion::IntoRawMode`     | `use termion::raw::IntoRawMode`
48
| `use termion::TermRead`        | `use termion::input::TermRead`
ticki's avatar
ticki committed
49 50 51 52 53 54
| `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
55
## Features
56 57

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

and much more.
78

ticki's avatar
ticki committed
79 80 81
## Examples

### Style and colors.
ticki's avatar
ticki committed
82 83 84 85

```rust
extern crate termion;

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

use std::io;

fn main() {
91 92 93 94
    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
95 96 97
}
```

ticki's avatar
ticki committed
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 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
### 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(b"password: ").unwrap();
    stdout.flush().unwrap();

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

    if let Ok(Some(pass)) = pass {
        stdout.write(pass.as_bytes()).unwrap();
        stdout.write(b"\n").unwrap();
    } else {
        stdout.write(b"Error\n").unwrap();
    }
}
```

ticki's avatar
ticki committed
173
## Usage
Ticki's avatar
Ticki committed
174 175 176

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

Antonin Carette's avatar
Antonin Carette committed
177
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
178

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

ticki's avatar
ticki committed
181
## License
Ticki's avatar
Ticki committed
182

ticki's avatar
ticki committed
183
MIT/X11.