README.md
1<h1 align="center"><img width="440" src="docs/crossterm_full.png" /></h1>
2
3[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=Z8QK6XU749JB2) ![Travis][s7] [![Latest Version][s1]][l1] [![MIT][s2]][l2] [![docs][s3]][l3] ![Lines of Code][s6] [![Join us on Discord][s5]][l5]
4
5# Cross-platform Terminal Manipulation Library
6
7Crossterm is a pure-rust, terminal manipulation library that makes it possible to write cross-platform text-based interfaces (see [features](#features)). It supports all UNIX and Windows terminals down to Windows 7 (not all terminals are tested,
8see [Tested Terminals](#tested-terminals) for more info).
9
10## Table of Contents
11
12* [Features](#features)
13 * [Tested Terminals](#tested-terminals)
14* [Getting Started](#getting-started)
15 * [Feature Flags](#feature-flags)
16* [Other Resources](#other-resources)
17* [Used By](#used-by)
18* [Contributing](#contributing)
19
20## Features
21
22- Cross-platform
23- Multi-threaded (send, sync)
24- Detailed documentation
25- Few dependencies
26- Full control over writing and flushing output buffer
27- Is tty
28- Cursor
29 - Move the cursor N times (up, down, left, right)
30 - Move to previous / next line
31 - Move to column
32 - Set/get the cursor position
33 - Store the cursor position and restore to it later
34 - Hide/show the cursor
35 - Enable/disable cursor blinking (not all terminals do support this feature)
36- Styled output
37 - Foreground color (16 base colors)
38 - Background color (16 base colors)
39 - 256 (ANSI) color support (Windows 10 and UNIX only)
40 - RGB color support (Windows 10 and UNIX only)
41 - Text attributes like bold, italic, underscore, crossed, etc
42- Terminal
43 - Clear (all lines, current line, from cursor down and up, until new line)
44 - Scroll up, down
45 - Set/get the terminal size
46 - Exit current process
47 - Alternate screen
48 - Raw screen
49 - Set terminal title
50 - Enable/disable line wrapping
51- Event
52 - Input Events
53 - Mouse Events (press, release, position, button, drag)
54 - Terminal Resize Events
55 - Advanced modifier (SHIFT | ALT | CTRL) support for both mouse and key events and
56 - futures Stream (feature 'event-stream')
57 - Poll/read API
58
59<!--
60WARNING: Do not change following heading title as it's used in the URL by other crates!
61-->
62
63### Tested Terminals
64
65- Console Host
66 - Windows 10 (Pro)
67 - Windows 8.1 (N)
68- Ubuntu Desktop Terminal
69 - Ubuntu 17.10
70 - Pop!_OS ( Ubuntu ) 20.04
71- (Arch, Manjaro) KDE Konsole
72- (Arch) Kitty
73- Linux Mint
74- OpenSuse/Linux Alacritty
75
76This crate supports all UNIX terminals and Windows terminals down to Windows 7; however, not all of the
77terminals have been tested. If you have used this library for a terminal other than the above list without
78issues, then feel free to add it to the above list - I really would appreciate it!
79
80## Getting Started
81_see the [examples directory](examples/) and [documentation](https://docs.rs/crossterm/) for more advanced examples._
82
83<details>
84<summary>
85Click to show Cargo.toml.
86</summary>
87
88```toml
89[dependencies]
90crossterm = "0.20"
91```
92
93</details>
94<p></p>
95
96```rust
97use std::io::{stdout, Write};
98
99use crossterm::{
100 execute,
101 style::{Color, Print, ResetColor, SetBackgroundColor, SetForegroundColor},
102 ExecutableCommand, Result,
103 event,
104};
105
106fn main() -> Result<()> {
107 // using the macro
108 execute!(
109 stdout(),
110 SetForegroundColor(Color::Blue),
111 SetBackgroundColor(Color::Red),
112 Print("Styled text here."),
113 ResetColor
114 )?;
115
116 // or using functions
117 stdout()
118 .execute(SetForegroundColor(Color::Blue))?
119 .execute(SetBackgroundColor(Color::Red))?
120 .execute(Print("Styled text here."))?
121 .execute(ResetColor)?;
122
123 Ok(())
124}
125```
126
127Checkout this [list](https://docs.rs/crossterm/0.14.0/crossterm/index.html#supported-commands) with all possible commands.
128
129### Feature Flags
130
131To optional feature flags.
132
133```toml
134[dependencies.crossterm]
135version = "0.17"
136features = ["event-stream"]
137```
138
139| Feature | Description |
140| :----- | :----- |
141| `event-stream` | `futures::Stream` producing `Result<Event>`.|
142
143### Dependency Justification
144
145| Dependency | Used for | Included |
146| :----- | :----- | :-----
147| `bitflags` | `KeyModifiers`, those are differ based on input.| always
148| `parking_lot` | locking `RwLock`s with a timeout, const mutexes. | always
149| `libc` | UNIX terminal_size/raw modes/set_title and several other lowlevel functionality. | UNIX only
150| `Mio` | event readiness polling, waking up poller | UNIX only
151| `signal-hook`| signalhook is used to handle terminal resize SIGNAL with Mio. | UNIX only
152| `winapi`| Used for low-level windows system calls which ANSI codes can't replace| windows only
153| `futures`| Can be used to for async stream of events | only with a feature flag
154| `serde`| Se/dese/realizing of events | only with a feature flag
155
156
157### Other Resources
158
159- [API documentation](https://docs.rs/crossterm/)
160- [Deprecated examples repository](https://github.com/crossterm-rs/examples)
161
162## Used By
163
164- [Broot](https://dystroy.org/broot/)
165- [Cursive](https://github.com/gyscos/Cursive)
166- [TUI](https://github.com/fdehau/tui-rs)
167- [Rust-sloth](https://github.com/ecumene/rust-sloth)
168- [Rusty-rain](https://github.com/cowboy8625/rusty-rain)
169
170## Contributing
171
172We highly appreciate when anyone contributes to this crate. Before you do, please,
173read the [Contributing](docs/CONTRIBUTING.md) guidelines.
174
175## Authors
176
177* **Timon Post** - *Project Owner & creator*
178
179## License
180
181This project, `crossterm` and all its sub-crates: `crossterm_screen`, `crossterm_cursor`, `crossterm_style`,
182`crossterm_input`, `crossterm_terminal`, `crossterm_winapi`, `crossterm_utils` are licensed under the MIT
183License - see the [LICENSE](https://github.com/crossterm-rs/crossterm/blob/master/LICENSE) file for details.
184
185[s1]: https://img.shields.io/crates/v/crossterm.svg
186[l1]: https://crates.io/crates/crossterm
187
188[s2]: https://img.shields.io/badge/license-MIT-blue.svg
189[l2]: ./LICENSE
190
191[s3]: https://docs.rs/crossterm/badge.svg
192[l3]: https://docs.rs/crossterm/
193
194[s3]: https://docs.rs/crossterm/badge.svg
195[l3]: https://docs.rs/crossterm/
196
197[s5]: https://img.shields.io/discord/560857607196377088.svg?logo=discord
198[l5]: https://discord.gg/K4nyTDB
199
200[s6]: https://tokei.rs/b1/github/crossterm-rs/crossterm?category=code
201[s7]: https://travis-ci.org/crossterm-rs/crossterm.svg?branch=master
202