Skip to content

Unified API for different terminal manipulation libraries.

Notifications You must be signed in to change notification settings

crossterm-rs/terminal

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

32 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Donate Latest Version docs Lines of Code MIT Join us on Discord Stable Status Beta Status

Unified API over different TUI libraries.

This library offers a universal API over various terminal libraries such as termion, crossterm, ncurses, pancurses, and console.

Why would I need this library? Three main reasons:

  1. Being less dependent on a specific terminal library with certain features.
  2. Support different features depending on the chosen backend and allow you to change at any given time.
  3. Hides implementation details (raw mode, write to the buffer, batch operations).
  4. Hides the differences (cursor 0 or 1 based, cleaning resources, event handling, performing actions. )
  5. Reduces backend mapping duplication in the ecosystem (cursive, tui, termimad, ...)

This library is still quite young. If you experience problems, feel free to make an issue. I'd fix it as soon as possible.

Table of Contents

Features

  • Batching multiple terminal commands before executing (flush).
  • Complete control over the underlying buffer.
  • Locking the terminal for a certain duration.
  • Backend of your choice.

Implemented Backends

  • Crossterm (Pure rust and crossplatform)
  • Termion (Pure rust for UNIX systems)
  • Crosscurses (crossplatform but requires ncurses C dependency (fork pancurses))

Use one of the below feature flags to choose an backend.

Feature Description
crossterm-backend crossterm backend will be used.
termion-backend termion backend will be used.
crosscurses-backend crosscurses backend will be used.

like

[dependencies.terminal]
version = "0.2"
features = ["crossterm-backend"] 

In the backend-specification document you will find each backend and it's benefits described.

Yet to Implement

Getting Started

Click to show Cargo.toml.
[dependencies]
terminal = "0.2"
features = ["your_backend_choice"] 

use terminal::{Action, Clear, error, Retrieved, Value};
use std::io::Write;

pub fn main() -> error::Result<()> {
    let mut terminal = terminal::stdout();

    // perform an single action.
    terminal.act(Action::ClearTerminal(Clear::All))?;

    // batch multiple actions.
    for i in 0..20 {
        terminal.batch(Action::MoveCursorTo(0, i))?;
        terminal.write(format!("{}", i).as_bytes());
    }

    // execute batch.
    terminal.flush_batch();

    // get an terminal value.
    if let Retrieved::TerminalSize(x, y) = terminal.get(Value::TerminalSize)? {
        println!("\nx: {}, y: {}", x, y);
    }

    Ok(())
}

Other Resources

Contributing

I would appreciate any kind of contribution. Before you do, please, read the Contributing guidelines.

Authors

  • Timon Post - Project Owner & creator

License

This project, terminal are licensed under the MIT License - see the LICENSE file for details.

About

Unified API for different terminal manipulation libraries.

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages