README.md 4.64 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
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.

ticki's avatar
ticki committed
11 12 13 14
Termion is quite convinient, due to its complete coverage of essential TTY
features, providing one consistent API. Termion is rather low-level containing
only abstraction aligned with what actually happens behind the scenes, for
something more high-level, refer to inquirer-rs, which uses Termion as backend.
Ticki's avatar
Ticki committed
15

ticki's avatar
ticki committed
16 17 18 19 20 21
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).

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

ticki's avatar
ticki committed
23
## A note on stability
Ticki's avatar
Ticki committed
24

ticki's avatar
ticki committed
25 26
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
27

ticki's avatar
ticki committed
28 29 30
## Cargo.toml

```toml
ticki's avatar
ticki committed
31
[dependencies]
ticki's avatar
ticki committed
32
termion = "1.0.3"
ticki's avatar
ticki committed
33 34
```

ticki's avatar
ticki committed
35 36 37 38 39 40 41 42
## 0.1.0 to 1.0.0 guide

This sample table gives an idea of how to go bu converting to the new major
version of Termion.

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

- Raw mode.
ticki's avatar
ticki committed
53
- TrueColor.
ticki's avatar
ticki committed
54
- 256-color mode.
55 56 57 58 59 60
- Cursor movement.
- Text formatting.
- Console size.
- Control sequences.
- Termios control.
- Password input.
Ticki's avatar
Ticki committed
61
- Redox support.
ticki's avatar
ticki committed
62
- Safe `isatty` wrapper.
Ticki's avatar
Ticki committed
63
- Panic-free error handling.
Ticki's avatar
Ticki committed
64
- Special keys events (modifiers, special keys, etc.).
ticki's avatar
ticki committed
65
- Allocation-free.
Ticki's avatar
Ticki committed
66
- Asynchronous key events.
IGI-111's avatar
IGI-111 committed
67
- Mouse input
ticki's avatar
ticki committed
68
- Carefully tested.
Ticki's avatar
Ticki committed
69 70

and much more.
71

ticki's avatar
ticki committed
72 73 74
## Examples

### Style and colors.
ticki's avatar
ticki committed
75 76 77 78

```rust
extern crate termion;

79
use termion::{color, style};
ticki's avatar
ticki committed
80 81 82 83

use std::io;

fn main() {
84 85 86 87
    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
88 89 90
}
```

ticki's avatar
ticki committed
91 92 93 94 95 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 157 158 159 160 161 162 163 164 165
### 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
166
## Usage
Ticki's avatar
Ticki committed
167 168 169

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

Antonin Carette's avatar
Antonin Carette committed
170
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
171

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

ticki's avatar
ticki committed
174
## License
Ticki's avatar
Ticki committed
175

ticki's avatar
ticki committed
176
MIT/X11.