<h1 align="center"><img width="440" src="docs/crossterm_full.png" /></h1>
[](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]
# Cross-platform Terminal Manipulation Library
Crossterm 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,
see [Tested Terminals](#tested-terminals) for more info).
## Table of Contents
* [Features](#features)
* [Tested Terminals](#tested-terminals)
* [Getting Started](#getting-started)
* [Feature Flags](#feature-flags)
* [Other Resources](#other-resources)
* [Used By](#used-by)
* [Contributing](#contributing)
## Features
- Cross-platform
- Multi-threaded (send, sync)
- Detailed documentation
- Few dependencies
- Full control over writing and flushing output buffer
- Is tty
- Cursor
- Move the cursor N times (up, down, left, right)
- Move to previous / next line
- Move to column
- Set/get the cursor position
- Store the cursor position and restore to it later
- Hide/show the cursor
- Enable/disable cursor blinking (not all terminals do support this feature)
- Styled output
- Foreground color (16 base colors)
- Background color (16 base colors)
- 256 (ANSI) color support (Windows 10 and UNIX only)
- RGB color support (Windows 10 and UNIX only)
- Text attributes like bold, italic, underscore, crossed, etc
- Terminal
- Clear (all lines, current line, from cursor down and up, until new line)
- Scroll up, down
- Set/get the terminal size
- Exit current process
- Alternate screen
- Raw screen
- Set terminal title
- Event
- Input Events
- Mouse Events (press, release, position, button, drag)
- Terminal Resize Events
- Advanced modifier (SHIFT | ALT | CTRL) support for both mouse and key events and
- futures Stream (feature 'event-stream')
- Poll/read API
### Tested Terminals
- Console Host
- Windows 10 (Pro)
- Windows 8.1 (N)
- Ubuntu Desktop Terminal
- Ubuntu 17.10
- (Arch, Manjaro) KDE Konsole
- (Arch) Kitty
- Linux Mint
This crate supports all UNIX terminals and Windows terminals down to Windows 7; however, not all of the
terminals have been tested. If you have used this library for a terminal other than the above list without
issues, then feel free to add it to the above list - I really would appreciate it!
## Getting Started
_see the [examples directory](examples/) and [documentation](https://docs.rs/crossterm/) for more advanced examples._
<details>
<summary>
Click to show Cargo.toml.
</summary>
```toml
[dependencies]
crossterm = "0.17"
```
</details>
<p></p>
```rust
use std::io::{stdout, Write};
use crossterm::{
execute,
style::{Color, Print, ResetColor, SetBackgroundColor, SetForegroundColor},
ExecutableCommand, Result,
event,
};
fn main() -> Result<()> {
// using the macro
execute!(
stdout(),
SetForegroundColor(Color::Blue),
SetBackgroundColor(Color::Red),
Print("Styled text here."),
ResetColor
)?;
// or using functions
stdout()
.execute(SetForegroundColor(Color::Blue))?
.execute(SetBackgroundColor(Color::Red))?
.execute(Print("Styled text here."))?
.execute(ResetColor)?;
Ok(())
}
```
Checkout this [list](https://docs.rs/crossterm/0.14.0/crossterm/index.html#supported-commands) with all possible commands.
### Feature Flags
To optional feature flags.
```toml
[dependencies.crossterm]
version = "0.17"
features = ["event-stream"]
```
| `event-stream` | `futures::Stream` producing `Result<Event>`.|
### Dependency Justification
| `bitflags` | `KeyModifiers`, those are differ based on input.| always
| `lazy_static` | original console color, original terminal mode, saved cursor position, supports ANSI on windows, single event reader per application.| always
| `parking_lot` | used for an RW LOCK. | always
| `libc` | UNIX terminal_size/raw modes/set_title and several other lowlevel functionality. | UNIX only
| `Mio` | event readiness polling, waking up poller | UNIX only
| `signal-hook`| signalhook is used to handle terminal resize SIGNAL with Mio. | UNIX only
| `winapi`| Used for low-level windows system calls which ANSI codes can't replace| windows only
| `futures`| Can be used to for async stream of events | only with a feature flag
| `serde`| Se/dese/realizing of events | only with a feature flag
### Other Resources
- [API documentation](https://docs.rs/crossterm/)
- [Deprecated examples repository](https://github.com/crossterm-rs/examples)
## Used By
- [Broot](https://dystroy.org/broot/)
- [Cursive](https://github.com/gyscos/Cursive)
- [TUI](https://github.com/fdehau/tui-rs)
- [Rust-sloth](https://github.com/ecumene/rust-sloth)
## Contributing
We highly appreciate when anyone contributes to this crate. Before you do, please,
read the [Contributing](docs/CONTRIBUTING.md) guidelines.
## Authors
* **Timon Post** - *Project Owner & creator*
## License
This project, `crossterm` and all its sub-crates: `crossterm_screen`, `crossterm_cursor`, `crossterm_style`,
`crossterm_input`, `crossterm_terminal`, `crossterm_winapi`, `crossterm_utils` are licensed under the MIT
License - see the [LICENSE](https://github.com/crossterm-rs/crossterm/blob/master/LICENSE) file for details.
[s1]: https://img.shields.io/crates/v/crossterm.svg
[l1]: https://crates.io/crates/crossterm
[s2]: https://img.shields.io/badge/license-MIT-blue.svg
[l2]: ./LICENSE
[s3]: https://docs.rs/crossterm/badge.svg
[l3]: https://docs.rs/crossterm/
[s3]: https://docs.rs/crossterm/badge.svg
[l3]: https://docs.rs/crossterm/
[s5]: https://img.shields.io/discord/560857607196377088.svg?logo=discord
[l5]: https://discord.gg/K4nyTDB
[s6]: https://tokei.rs/b1/github/crossterm-rs/crossterm?category=code
[s7]: https://travis-ci.org/crossterm-rs/crossterm.svg?branch=master