#event #color #cli #input #terminal

crossterm

An crossplatform terminal library for manipulating terminals

47 releases (16 breaking)

0.17.7 Jul 13, 2020
0.17.5 May 23, 2020
0.17.1 Mar 28, 2020
0.14.1 Dec 17, 2019
0.2.0 Jan 27, 2018

#8 in Command-line interface

Download history 8740/week @ 2020-04-20 7477/week @ 2020-04-27 8404/week @ 2020-05-04 8793/week @ 2020-05-11 6894/week @ 2020-05-18 6877/week @ 2020-05-25 6265/week @ 2020-06-01 6839/week @ 2020-06-08 5934/week @ 2020-06-15 6766/week @ 2020-06-22 6606/week @ 2020-06-29 8347/week @ 2020-07-06 9417/week @ 2020-07-13 7264/week @ 2020-07-20 8385/week @ 2020-07-27 7807/week @ 2020-08-03

31,283 downloads per month
Used in 165 crates (134 directly)

MIT license

255KB
5K SLoC

Donate Travis Latest Version MIT docs Lines of Code Join us on Discord

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). It supports all UNIX and Windows terminals down to Windows 7 (not all terminals are tested, see Tested Terminals for more info).

Table of Contents

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 and documentation for more advanced examples.

Click to show Cargo.toml.
[dependencies]
crossterm = "0.17"

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 with all possible commands.

Feature Flags

To optional feature flags.

[dependencies.crossterm]
version = "0.17"
features = ["event-stream"] 
Feature Description
event-stream futures::Stream producing Result<Event>.

Dependency Justification

Dependency Used for Included
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

Used By

Contributing

We highly appreciate when anyone contributes to this crate. Before you do, please, read the Contributing 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 file for details.

Dependencies

~0.5–1.2MB
~25K SLoC