Build interactive and non blocking CLI apps with ease in Rust
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:
- You can use up, down to access history in the multi-line editor.
- You can use left, right, ctrl+left, ctrl+right, to jump around in the multi-line editor.
- You can edit content in this multi-line editor without blocking the main thread, and while other tasks (started via
tokio::spawnare concurrently producing output to the display. - 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 fullNow, 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.