vendor/termion-1.5.1/README.md

   1 <p align="center">
   2 <img alt="Termion logo" src="https://rawgit.com/ticki/termion/master/logo.svg" />
   3 </p>
   4
   5 [![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) | [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/)
   6 |----|----|----|----|----
   7
   8
   9 **Termion** is a pure Rust, bindless library for low-level handling, manipulating
  10 and reading information about terminals. This provides a full-featured
  11 alternative to Termbox.
  12
  13 Termion aims to be simple and yet expressive. It is bindless, meaning that it
  14 is not a front-end to some other library (e.g., ncurses or termbox), but a
  15 standalone library directly talking to the TTY.
  16
  17 Termion is quite convenient, due to its complete coverage of essential TTY
  18 features, providing one consistent API. Termion is rather low-level containing
  19 only abstraction aligned with what actually happens behind the scenes. For
  20 something more high-level, refer to inquirer-rs, which uses Termion as backend.
  21
  22 Termion generates escapes and API calls for the user. This makes it a whole lot
  23 cleaner to use escapes.
  24
  25 Supports Redox, Mac OS X, BSD, and Linux (or, in general, ANSI terminals).
  26
  27 ## A note on stability
  28
  29 This crate is stable.
  30
  31 ## Cargo.toml
  32
  33 ```toml
  34 [dependencies]
  35 termion = "*"
  36 ```
  37
  38 ## 0.1.0 to 1.0.0 guide
  39
  40 This sample table gives an idea of how to go about converting to the new major
  41 version of Termion.
  42
  43 | 0.1.0                          | 1.0.0
  44 |--------------------------------|---------------------------
  45 | `use termion::IntoRawMode`     | `use termion::raw::IntoRawMode`
  46 | `use termion::TermRead`        | `use termion::input::TermRead`
  47 | `stdout.color(color::Red);`    | `write!(stdout, "{}", color::Fg(color::Red));`
  48 | `stdout.color_bg(color::Red);` | `write!(stdout, "{}", color::Bg(color::Red));`
  49 | `stdout.goto(x, y);`           | `write!(stdout, "{}", cursor::Goto(x, y));`
  50 | `color::rgb(r, g, b);`         | `color::Rgb(r, g, b)` (truecolor)
  51 | `x.with_mouse()`               | `MouseTerminal::from(x)`
  52
  53 ## Features
  54
  55 - Raw mode.
  56 - TrueColor.
  57 - 256-color mode.
  58 - Cursor movement.
  59 - Text formatting.
  60 - Console size.
  61 - TTY-only stream.
  62 - Control sequences.
  63 - Termios control.
  64 - Password input.
  65 - Redox support.
  66 - Safe `isatty` wrapper.
  67 - Panic-free error handling.
  68 - Special keys events (modifiers, special keys, etc.).
  69 - Allocation-free.
  70 - Asynchronous key events.
  71 - Mouse input.
  72 - Carefully tested.
  73 - Detailed documentation on every item.
  74
  75 and much more.
  76
  77 ## Examples
  78
  79 ### Style and colors.
  80
  81 ```rust
  82 extern crate termion;
  83
  84 use termion::{color, style};
  85
  86 use std::io;
  87
  88 fn main() {
  89     println!("{}Red", color::Fg(color::Red));
  90     println!("{}Blue", color::Fg(color::Blue));
  91     println!("{}Blue'n'Bold{}", style::Bold, style::Reset);
  92     println!("{}Just plain italic", style::Italic);
  93 }
  94 ```
  95
  96 ### Moving the cursor
  97
  98 ```rust
  99 extern crate termion;
 100
 101 fn main() {
 102     print!("{}{}Stuff", termion::clear::All, termion::cursor::Goto(1, 1));
 103 }
 104
 105 ```
 106
 107 ### Mouse
 108
 109 ```rust
 110 extern crate termion;
 111
 112 use termion::event::{Key, Event, MouseEvent};
 113 use termion::input::{TermRead, MouseTerminal};
 114 use termion::raw::IntoRawMode;
 115 use std::io::{Write, stdout, stdin};
 116
 117 fn main() {
 118     let stdin = stdin();
 119     let mut stdout = MouseTerminal::from(stdout().into_raw_mode().unwrap());
 120
 121     write!(stdout, "{}{}q to exit. Click, click, click!", termion::clear::All, termion::cursor::Goto(1, 1)).unwrap();
 122     stdout.flush().unwrap();
 123
 124     for c in stdin.events() {
 125         let evt = c.unwrap();
 126         match evt {
 127             Event::Key(Key::Char('q')) => break,
 128             Event::Mouse(me) => {
 129                 match me {
 130                     MouseEvent::Press(_, x, y) => {
 131                         write!(stdout, "{}x", termion::cursor::Goto(x, y)).unwrap();
 132                     },
 133                     _ => (),
 134                 }
 135             }
 136             _ => {}
 137         }
 138         stdout.flush().unwrap();
 139     }
 140 }
 141 ```
 142
 143 ### Read a password
 144
 145 ```rust
 146 extern crate termion;
 147
 148 use termion::input::TermRead;
 149 use std::io::{Write, stdout, stdin};
 150
 151 fn main() {
 152     let stdout = stdout();
 153     let mut stdout = stdout.lock();
 154     let stdin = stdin();
 155     let mut stdin = stdin.lock();
 156
 157     stdout.write_all(b"password: ").unwrap();
 158     stdout.flush().unwrap();
 159
 160     let pass = stdin.read_passwd(&mut stdout);
 161
 162     if let Ok(Some(pass)) = pass {
 163         stdout.write_all(pass.as_bytes()).unwrap();
 164         stdout.write_all(b"\n").unwrap();
 165     } else {
 166         stdout.write_all(b"Error\n").unwrap();
 167     }
 168 }
 169 ```
 170
 171 ## Usage
 172
 173 See `examples/`, and the documentation, which can be rendered using `cargo doc`.
 174
 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.
 176
 177 <img src="image.png" width="200">
 178
 179 ## License
 180
 181 MIT/X11.