tree: e9d1f569ffe1293c04fa0f3ec9e8f0182740b3b8 [path history] [tgz]
  1. docs/
  2. examples/
  3. src/
  4. .cargo-checksum.json
  5. CHANGELOG.md
  6. Cargo.lock
  7. Cargo.toml
  8. LICENSE
  9. README.md
third_party/rust_crates/vendor/crossterm/README.md

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.

[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"] 
FeatureDescription
event-streamfutures::Stream producing Result<Event>.

Dependency Justification

DependencyUsed forIncluded
bitflagsKeyModifiers, those are differ based on input.always
lazy_staticoriginal console color, original terminal mode, saved cursor position, supports ANSI on windows, single event reader per application.always
parking_lotused for an RW LOCK.always
libcUNIX terminal_size/raw modes/set_title and several other lowlevel functionality.UNIX only
Mioevent readiness polling, waking up pollerUNIX only
signal-hooksignalhook is used to handle terminal resize SIGNAL with Mio.UNIX only
winapiUsed for low-level windows system calls which ANSI codes can't replacewindows only
futuresCan be used to for async stream of eventsonly with a feature flag
serdeSe/dese/realizing of eventsonly 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.