Struct TerminalAsync

pub struct TerminalAsync {
    pub readline: Readline,
    pub shared_writer: SharedWriter,
}

Fields

readline: Readline

shared_writer: SharedWriter

Implementations

impl TerminalAsync

pub async fn try_new(prompt: &str) -> Result<Option<TerminalAsync>>

Create a new instance of TerminalAsync. Example of prompt is "> ".

Example

Here’s an example of how to use this method:

async fn foo() -> miette::Result<()> {
    use r3bl_terminal_async::TerminalAsync;
    let terminal_async = TerminalAsync::try_new("> ")
        .await?
        .ok_or_else(|| miette::miette!("Failed to create terminal"))?;
    r3bl_core::ok!()
}

Another example:

async fn foo() -> miette::Result<()> {
    use r3bl_terminal_async::TerminalAsync;
    let Some(mut terminal_async) = TerminalAsync::try_new("> ").await? else {
        return Err(miette::miette!("Failed to create terminal"));
    };
    r3bl_core::ok!()
}

Returns

1. If the terminal is not fully interactive then it will return None, and won’t create the Readline. This is when the terminal is not considered fully interactive:
   • stdout is piped, eg: echo "foo" | cargo run --example spinner.
   • or all three stdin, stdout, stderr are not is_tty, eg when running in cargo test.
2. Otherwise, it will return a TerminalAsync instance.
3. In case there are any issues putting the terminal into raw mode, or getting the terminal size, it will return an error.

More info on terminal piping:

• https://unix.stackexchange.com/questions/597083/how-does-piping-affect-stdin

Examples found in repository

examples/shell_async.rs (line 292)

    pub async fn new(pid: u32) -> miette::Result<TerminalAsyncHandle> {
        let prompt = {
            let prompt_seg_1 = "╭".magenta().on_dark_grey().to_string();
            let prompt_seg_2 = format!("┤{pid}├").magenta().on_dark_grey().to_string();
            let prompt_seg_3 = "╮".magenta().on_dark_grey().to_string();
            format!("{}{}{} ", prompt_seg_1, prompt_seg_2, prompt_seg_3)
        };

        let Ok(Some(terminal_async)) = TerminalAsync::try_new(prompt.as_str()).await
        else {
            miette::bail!("Failed to create TerminalAsync instance");
        };

        let shared_writer = terminal_async.clone_shared_writer();

        ok!(TerminalAsyncHandle {
            terminal_async,
            shared_writer
        })
    }

examples/spinner.rs (line 62)

async fn example_with_concurrent_output(style: SpinnerStyle) -> miette::Result<()> {
    let terminal_async = TerminalAsync::try_new("$ ").await?;
    let terminal_async = terminal_async.expect("terminal is not fully interactive");
    let address = "127.0.0.1:8000";
    let message_trying_to_connect = format!(
        "This is a sample indeterminate progress message: trying to connect to server on {}",
        &address
    );

    let mut shared_writer = terminal_async.clone_shared_writer();

    // Start spinner. Automatically pauses the terminal.
    let mut maybe_spinner = Spinner::try_start(
        message_trying_to_connect.clone(),
        DELAY_UNIT,
        style,
        Arc::new(StdMutex::new(stderr())),
        shared_writer.clone(),
    )
    .await?;

    // Start another task, to simulate some async work, that uses a interval to display
    // output, for a fixed amount of time, using `terminal_async.println_prefixed()`.
    let _ = try_join!(tokio::spawn(async move {
        // To calculate the delay.
        let duration = ARTIFICIAL_UI_DELAY;
        let start = Instant::now();

        // Dropping the interval cancels it.
        let mut interval = tokio::time::interval(Duration::from_millis(DELAY_MS * 5));

        loop {
            interval.tick().await;
            let elapsed = start.elapsed();
            if elapsed >= duration {
                break;
            }
            let _ = writeln!(shared_writer, "⏳foo");
        }
    }));

    // Stop spinner. Automatically resumes the terminal.
    if let Some(spinner) = maybe_spinner.as_mut() {
        spinner
            .stop("This is a sample final message for the spinner component: Connected to server")
            .await?;
    }

    tokio::time::sleep(Duration::from_millis(500)).await;

    Ok(())
}

examples/terminal_async.rs (line 145)

async fn main() -> miette::Result<()> {
    let prompt = {
        let prompt_seg_1 = "╭>╮".magenta().on_dark_grey().to_string();
        let prompt_seg_2 = " ".to_string();
        format!("{}{}", prompt_seg_1, prompt_seg_2)
    };

    let maybe_terminal_async = TerminalAsync::try_new(prompt.as_str()).await?;

    // If the terminal is not fully interactive, then return early.
    let Some(mut terminal_async) = maybe_terminal_async else {
        return Ok(());
    };

    // Pre-populate the readline's history with some entries.
    for command in Command::iter() {
        terminal_async
            .readline
            .add_history_entry(command.to_string());
    }

    // Initialize tracing w/ the "async stdout" (SharedWriter), and file writer.
    TracingConfig::new_file_and_display(
        None,
        DisplayPreference::SharedWriter(terminal_async.clone_shared_writer()),
    )
    .install_global()?;

    // Start tasks.
    let mut state = State::default();
    let mut interval_1_task = interval(state.task_1_state.interval_delay);
    let mut interval_2_task = interval(state.task_2_state.interval_delay);

    terminal_async.println(get_info_message().to_string()).await;

    loop {
        select! {
            _ = interval_1_task.tick() => {
                task_1::tick(&mut state, &mut terminal_async.clone_shared_writer())?;
            },
            _ = interval_2_task.tick() => {
                task_2::tick(&mut state, &mut terminal_async.clone_shared_writer())?;
            },
            result_readline_event = terminal_async.get_readline_event() => {
                match result_readline_event {
                    Ok(readline_event) => {
                        match readline_event {
                            // User input event.
                            ReadlineEvent::Line(user_input) => {
                                let mut_state = &mut state;
                                let shared_writer = &mut terminal_async.clone_shared_writer();
                                let readline = &mut terminal_async.readline;
                                let control_flow = process_input_event::process(
                                    user_input, mut_state, shared_writer, readline)?;
                                if let ControlFlow::Break(_) = control_flow {
                                    break;
                                }
                            }
                            // Resize event.
                            ReadlineEvent::Resized => {
                                let shared_writer = &mut terminal_async.clone_shared_writer();
                                writeln!(shared_writer, "{}", "Terminal resized!".yellow()).into_diagnostic()?;
                            }
                            // Ctrl+D, Ctrl+C.
                            ReadlineEvent::Eof | ReadlineEvent::Interrupted => {
                                break;
                            }
                        }
                    },
                    Err(err) => {
                        let msg_1 = format!("Received err: {}", format!("{:?}",err).red());
                        let msg_2 = format!("{}", "Exiting...".red());
                        terminal_async.println(msg_1).await;
                        terminal_async.println(msg_2).await;
                        break;
                    },
                }
            }
        }
    }

    // There's no need to close terminal_async or readline. Drop will take care of
    // cleaning up (closing raw mode).

    Ok(())
}

pub fn clone_shared_writer(&self) -> SharedWriter

Examples found in repository

examples/shell_async.rs (line 297)

    pub async fn new(pid: u32) -> miette::Result<TerminalAsyncHandle> {
        let prompt = {
            let prompt_seg_1 = "╭".magenta().on_dark_grey().to_string();
            let prompt_seg_2 = format!("┤{pid}├").magenta().on_dark_grey().to_string();
            let prompt_seg_3 = "╮".magenta().on_dark_grey().to_string();
            format!("{}{}{} ", prompt_seg_1, prompt_seg_2, prompt_seg_3)
        };

        let Ok(Some(terminal_async)) = TerminalAsync::try_new(prompt.as_str()).await
        else {
            miette::bail!("Failed to create TerminalAsync instance");
        };

        let shared_writer = terminal_async.clone_shared_writer();

        ok!(TerminalAsyncHandle {
            terminal_async,
            shared_writer
        })
    }

examples/spinner.rs (line 70)

async fn example_with_concurrent_output(style: SpinnerStyle) -> miette::Result<()> {
    let terminal_async = TerminalAsync::try_new("$ ").await?;
    let terminal_async = terminal_async.expect("terminal is not fully interactive");
    let address = "127.0.0.1:8000";
    let message_trying_to_connect = format!(
        "This is a sample indeterminate progress message: trying to connect to server on {}",
        &address
    );

    let mut shared_writer = terminal_async.clone_shared_writer();

    // Start spinner. Automatically pauses the terminal.
    let mut maybe_spinner = Spinner::try_start(
        message_trying_to_connect.clone(),
        DELAY_UNIT,
        style,
        Arc::new(StdMutex::new(stderr())),
        shared_writer.clone(),
    )
    .await?;

    // Start another task, to simulate some async work, that uses a interval to display
    // output, for a fixed amount of time, using `terminal_async.println_prefixed()`.
    let _ = try_join!(tokio::spawn(async move {
        // To calculate the delay.
        let duration = ARTIFICIAL_UI_DELAY;
        let start = Instant::now();

        // Dropping the interval cancels it.
        let mut interval = tokio::time::interval(Duration::from_millis(DELAY_MS * 5));

        loop {
            interval.tick().await;
            let elapsed = start.elapsed();
            if elapsed >= duration {
                break;
            }
            let _ = writeln!(shared_writer, "⏳foo");
        }
    }));

    // Stop spinner. Automatically resumes the terminal.
    if let Some(spinner) = maybe_spinner.as_mut() {
        spinner
            .stop("This is a sample final message for the spinner component: Connected to server")
            .await?;
    }

    tokio::time::sleep(Duration::from_millis(500)).await;

    Ok(())
}

examples/terminal_async.rs (line 162)

async fn main() -> miette::Result<()> {
    let prompt = {
        let prompt_seg_1 = "╭>╮".magenta().on_dark_grey().to_string();
        let prompt_seg_2 = " ".to_string();
        format!("{}{}", prompt_seg_1, prompt_seg_2)
    };

    let maybe_terminal_async = TerminalAsync::try_new(prompt.as_str()).await?;

    // If the terminal is not fully interactive, then return early.
    let Some(mut terminal_async) = maybe_terminal_async else {
        return Ok(());
    };

    // Pre-populate the readline's history with some entries.
    for command in Command::iter() {
        terminal_async
            .readline
            .add_history_entry(command.to_string());
    }

    // Initialize tracing w/ the "async stdout" (SharedWriter), and file writer.
    TracingConfig::new_file_and_display(
        None,
        DisplayPreference::SharedWriter(terminal_async.clone_shared_writer()),
    )
    .install_global()?;

    // Start tasks.
    let mut state = State::default();
    let mut interval_1_task = interval(state.task_1_state.interval_delay);
    let mut interval_2_task = interval(state.task_2_state.interval_delay);

    terminal_async.println(get_info_message().to_string()).await;

    loop {
        select! {
            _ = interval_1_task.tick() => {
                task_1::tick(&mut state, &mut terminal_async.clone_shared_writer())?;
            },
            _ = interval_2_task.tick() => {
                task_2::tick(&mut state, &mut terminal_async.clone_shared_writer())?;
            },
            result_readline_event = terminal_async.get_readline_event() => {
                match result_readline_event {
                    Ok(readline_event) => {
                        match readline_event {
                            // User input event.
                            ReadlineEvent::Line(user_input) => {
                                let mut_state = &mut state;
                                let shared_writer = &mut terminal_async.clone_shared_writer();
                                let readline = &mut terminal_async.readline;
                                let control_flow = process_input_event::process(
                                    user_input, mut_state, shared_writer, readline)?;
                                if let ControlFlow::Break(_) = control_flow {
                                    break;
                                }
                            }
                            // Resize event.
                            ReadlineEvent::Resized => {
                                let shared_writer = &mut terminal_async.clone_shared_writer();
                                writeln!(shared_writer, "{}", "Terminal resized!".yellow()).into_diagnostic()?;
                            }
                            // Ctrl+D, Ctrl+C.
                            ReadlineEvent::Eof | ReadlineEvent::Interrupted => {
                                break;
                            }
                        }
                    },
                    Err(err) => {
                        let msg_1 = format!("Received err: {}", format!("{:?}",err).red());
                        let msg_2 = format!("{}", "Exiting...".red());
                        terminal_async.println(msg_1).await;
                        terminal_async.println(msg_2).await;
                        break;
                    },
                }
            }
        }
    }

    // There's no need to close terminal_async or readline. Drop will take care of
    // cleaning up (closing raw mode).

    Ok(())
}

pub async fn get_readline_event(&mut self) -> Result<ReadlineEvent>

Replacement for std::io::Stdin::read_line() (this is async and non blocking).

Examples found in repository

examples/shell_async.rs (line 199)

    pub async fn start_event_loop(
        mut stdin: tokio::process::ChildStdin,
        mut terminal_async: TerminalAsync,
        mut child: tokio::process::Child,
        shutdown_sender: tokio::sync::broadcast::Sender<()>,
    ) {
        let mut shutdown_receiver = shutdown_sender.subscribe();

        loop {
            tokio::select! {
                // Branch: Monitor shutdown signal. This is cancel safe as `recv()` is
                // cancel safe.
                _ = shutdown_receiver.recv() => {
                    break;
                }

                // Branch: Monitor terminal_async for user input. This is cancel safe as
                // `get_readline_event()` is cancel safe.
                result_readline_event = terminal_async.get_readline_event() => {
                    match ControlFlow::from(result_readline_event) {
                        ControlFlow::ShutdownKillChild => {
                            _ = child.kill().await;
                            _= shutdown_sender.send(());
                            break;
                        }
                        ControlFlow::ProcessLine(input) => {
                            let input = format!("{}\n", input);
                            _ = stdin.write_all(input.as_bytes()).await;
                            _ = stdin.flush().await;
                        }
                        ControlFlow::Resized => {}
                    }
                }
            }
        }
    }

examples/terminal_async.rs (line 181)

async fn main() -> miette::Result<()> {
    let prompt = {
        let prompt_seg_1 = "╭>╮".magenta().on_dark_grey().to_string();
        let prompt_seg_2 = " ".to_string();
        format!("{}{}", prompt_seg_1, prompt_seg_2)
    };

    let maybe_terminal_async = TerminalAsync::try_new(prompt.as_str()).await?;

    // If the terminal is not fully interactive, then return early.
    let Some(mut terminal_async) = maybe_terminal_async else {
        return Ok(());
    };

    // Pre-populate the readline's history with some entries.
    for command in Command::iter() {
        terminal_async
            .readline
            .add_history_entry(command.to_string());
    }

    // Initialize tracing w/ the "async stdout" (SharedWriter), and file writer.
    TracingConfig::new_file_and_display(
        None,
        DisplayPreference::SharedWriter(terminal_async.clone_shared_writer()),
    )
    .install_global()?;

    // Start tasks.
    let mut state = State::default();
    let mut interval_1_task = interval(state.task_1_state.interval_delay);
    let mut interval_2_task = interval(state.task_2_state.interval_delay);

    terminal_async.println(get_info_message().to_string()).await;

    loop {
        select! {
            _ = interval_1_task.tick() => {
                task_1::tick(&mut state, &mut terminal_async.clone_shared_writer())?;
            },
            _ = interval_2_task.tick() => {
                task_2::tick(&mut state, &mut terminal_async.clone_shared_writer())?;
            },
            result_readline_event = terminal_async.get_readline_event() => {
                match result_readline_event {
                    Ok(readline_event) => {
                        match readline_event {
                            // User input event.
                            ReadlineEvent::Line(user_input) => {
                                let mut_state = &mut state;
                                let shared_writer = &mut terminal_async.clone_shared_writer();
                                let readline = &mut terminal_async.readline;
                                let control_flow = process_input_event::process(
                                    user_input, mut_state, shared_writer, readline)?;
                                if let ControlFlow::Break(_) = control_flow {
                                    break;
                                }
                            }
                            // Resize event.
                            ReadlineEvent::Resized => {
                                let shared_writer = &mut terminal_async.clone_shared_writer();
                                writeln!(shared_writer, "{}", "Terminal resized!".yellow()).into_diagnostic()?;
                            }
                            // Ctrl+D, Ctrl+C.
                            ReadlineEvent::Eof | ReadlineEvent::Interrupted => {
                                break;
                            }
                        }
                    },
                    Err(err) => {
                        let msg_1 = format!("Received err: {}", format!("{:?}",err).red());
                        let msg_2 = format!("{}", "Exiting...".red());
                        terminal_async.println(msg_1).await;
                        terminal_async.println(msg_2).await;
                        break;
                    },
                }
            }
        }
    }

    // There's no need to close terminal_async or readline. Drop will take care of
    // cleaning up (closing raw mode).

    Ok(())
}

pub async fn println<T>(&mut self, content: T)

where T: Display,

Don’t change the content. Print it as is. This works concurrently and is async and non blocking. And it is compatible w/ the get_readline_event method.

Examples found in repository

examples/terminal_async.rs (line 171)

async fn main() -> miette::Result<()> {
    let prompt = {
        let prompt_seg_1 = "╭>╮".magenta().on_dark_grey().to_string();
        let prompt_seg_2 = " ".to_string();
        format!("{}{}", prompt_seg_1, prompt_seg_2)
    };

    let maybe_terminal_async = TerminalAsync::try_new(prompt.as_str()).await?;

    // If the terminal is not fully interactive, then return early.
    let Some(mut terminal_async) = maybe_terminal_async else {
        return Ok(());
    };

    // Pre-populate the readline's history with some entries.
    for command in Command::iter() {
        terminal_async
            .readline
            .add_history_entry(command.to_string());
    }

    // Initialize tracing w/ the "async stdout" (SharedWriter), and file writer.
    TracingConfig::new_file_and_display(
        None,
        DisplayPreference::SharedWriter(terminal_async.clone_shared_writer()),
    )
    .install_global()?;

    // Start tasks.
    let mut state = State::default();
    let mut interval_1_task = interval(state.task_1_state.interval_delay);
    let mut interval_2_task = interval(state.task_2_state.interval_delay);

    terminal_async.println(get_info_message().to_string()).await;

    loop {
        select! {
            _ = interval_1_task.tick() => {
                task_1::tick(&mut state, &mut terminal_async.clone_shared_writer())?;
            },
            _ = interval_2_task.tick() => {
                task_2::tick(&mut state, &mut terminal_async.clone_shared_writer())?;
            },
            result_readline_event = terminal_async.get_readline_event() => {
                match result_readline_event {
                    Ok(readline_event) => {
                        match readline_event {
                            // User input event.
                            ReadlineEvent::Line(user_input) => {
                                let mut_state = &mut state;
                                let shared_writer = &mut terminal_async.clone_shared_writer();
                                let readline = &mut terminal_async.readline;
                                let control_flow = process_input_event::process(
                                    user_input, mut_state, shared_writer, readline)?;
                                if let ControlFlow::Break(_) = control_flow {
                                    break;
                                }
                            }
                            // Resize event.
                            ReadlineEvent::Resized => {
                                let shared_writer = &mut terminal_async.clone_shared_writer();
                                writeln!(shared_writer, "{}", "Terminal resized!".yellow()).into_diagnostic()?;
                            }
                            // Ctrl+D, Ctrl+C.
                            ReadlineEvent::Eof | ReadlineEvent::Interrupted => {
                                break;
                            }
                        }
                    },
                    Err(err) => {
                        let msg_1 = format!("Received err: {}", format!("{:?}",err).red());
                        let msg_2 = format!("{}", "Exiting...".red());
                        terminal_async.println(msg_1).await;
                        terminal_async.println(msg_2).await;
                        break;
                    },
                }
            }
        }
    }

    // There's no need to close terminal_async or readline. Drop will take care of
    // cleaning up (closing raw mode).

    Ok(())
}

pub async fn println_prefixed<T>(&mut self, content: T)

where T: Display,

Prefix the content with a color and special characters, then print it.

pub async fn flush(&mut self)

Simply flush the buffer. If there’s a newline in the buffer, it will be printed. Otherwise it won’t.

pub async fn pause(&mut self)

pub async fn resume(&mut self)

pub fn print_exit_message(message: &str) -> Result<()>