👀 Watch Rust 🦀 live coding videos on our YouTube Channel.

The r3bl_terminal_async library lets your CLI program be asynchronous and interactive without blocking the main thread. Your spawned tasks can use it to concurrently write to the display output, pause and resume it. You can also display of colorful animated spinners ⌛🌈 for long running tasks. With it, you can create beautiful, powerful, and interactive REPLs (read execute print loops) with ease.

Why use this crate #

  • Because read_line() is blocking. And there is no way to terminate an OS thread that is blocking in Rust. To do this you have to exit the process (who’s thread is blocked in read_line()).
  • Another annoyance is that when a thread is blocked in read_line(), and you have to display output to stdout concurrently, this poses some challenges.

Demo of this in action #

Here’s a screen capture of the types of interactive REPLs that you can expect to build in Rust, using this crate.

A couple of things to note about this demo:

  1. You can use up, down to access history in the multi-line editor.
  2. You can use left, right, ctrl+left, ctrl+right, to jump around in the multi-line editor.
  3. You can edit content in this multi-line editor without blocking the main thread, and while other tasks (started via tokio::spawn are concurrently producing output to the display.
  4. You can pause the output while spinners are being displayed, and these spinners support many different kinds of animations!

Example of using this crate #

There are great examples in the examples folder of the repo here. Let’s walk through a simple example of using this crate. Let’s create a new example using the following commands:

cargo new --bin async-cli
cd async-cli
cargo add r3bl_terminal_async
cargo add miette --features fancy
cargo add tokio --features full

Now, let’s add a main.rs file in the src folder.

use std::time::Duration;

use r3bl_terminal_async::{tracing_setup, TerminalAsync, TracingConfig};
use tokio::time::interval;

#[tokio::main]
async fn main() -> miette::Result<()> {
    let maybe_terminal_async = TerminalAsync::try_new("> ").await?;

    // If the terminal is not fully interactive, then return early.
    let mut terminal_async = match maybe_terminal_async {
        None => return Ok(()),
        _ => maybe_terminal_async.unwrap(),
    };

    // Initialize tracing w/ the "async stdout".
    tracing_setup::init(TracingConfig::new(Some(
        terminal_async.clone_shared_writer(),
    )))?;

    // Start tasks.
    let mut interval_1_task = interval(Duration::from_secs(1));
    let mut interval_2_task = interval(Duration::from_secs(4));

    terminal_async
        .println("Welcome to your async repl! press Ctrl+D or Ctrl+C to exit.")
        .await;

    loop {
        tokio::select! {
            _ = interval_1_task.tick() => {
                terminal_async.println("interval_1_task ticked").await;
            },
            _ = interval_2_task.tick() => {
                terminal_async.println("interval_1_task ticked").await;
            },
            user_input = terminal_async.get_readline_event() => match user_input {
                Ok(readline_event) => {
                    match readline_event {
                        r3bl_terminal_async::ReadlineEvent::Eof => break,
                        r3bl_terminal_async::ReadlineEvent::Interrupted => break,
                        _ => (),
                    }

                    let msg = format!("{:?}", readline_event);
                    terminal_async.println(msg).await;
                },
                Err(err) => {
                    let msg = format!("Received err: {:?}. Exiting.", err);
                    terminal_async.println(msg).await;
                    break;
                },
            }
        }
    }

    // Flush all writers to stdout
    let _ = terminal_async.flush().await;

    Ok(())
}

You can then run this program using cargo run. Play with it to get a sense of the asynchronous and non blocking nature of the REPL. Press Ctrl+C, or Ctrl+D to exit this program.

Video series on developerlife.com YouTube channel on building this crate with Naz #

You can watch a video series on building this crate with Naz on the developerlife.com YouTube channel.

Here’s the video that is tied to this blog post:

#cli #rust #server
📦 Install our useful Rust command line apps using cargo install r3bl-cmdr (they are from the r3bl-open-core project):
  • 🐱giti: run interactive git commands with confidence in your terminal
  • 🦜edi: edit Markdown with style in your terminal

giti in action

edi in action

Related Posts