Struct r3bl_terminal_async::public_api::terminal_async::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 "> ".

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/spinner.rs (line 54)

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 126)

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(),
    };

    // 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.
    let display_preference = DisplayPreference::SharedWriter(terminal_async.shared_writer.clone());
    let config = TracingConfig::new(display_preference);
    tracing_setup::init(config)?;

    // 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())?;
            },
            user_input = terminal_async.get_readline_event() => match user_input {
                Ok(readline_event) => {
                    let continuation = process_input_event::process_readline_event(
                        readline_event, &mut state, &mut terminal_async.clone_shared_writer(), &mut terminal_async.readline
                    )?;
                    if let ControlFlow::Break(_) = continuation { 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;
                },
            }
        }
    }

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

    Ok(())
}

pub fn clone_shared_writer(&self) -> SharedWriter

Examples found in repository

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 156)

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(),
    };

    // 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.
    let display_preference = DisplayPreference::SharedWriter(terminal_async.shared_writer.clone());
    let config = TracingConfig::new(display_preference);
    tracing_setup::init(config)?;

    // 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())?;
            },
            user_input = terminal_async.get_readline_event() => match user_input {
                Ok(readline_event) => {
                    let continuation = process_input_event::process_readline_event(
                        readline_event, &mut state, &mut terminal_async.clone_shared_writer(), &mut terminal_async.readline
                    )?;
                    if let ControlFlow::Break(_) = continuation { 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;
                },
            }
        }
    }

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

    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/terminal_async.rs (line 161)

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(),
    };

    // 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.
    let display_preference = DisplayPreference::SharedWriter(terminal_async.shared_writer.clone());
    let config = TracingConfig::new(display_preference);
    tracing_setup::init(config)?;

    // 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())?;
            },
            user_input = terminal_async.get_readline_event() => match user_input {
                Ok(readline_event) => {
                    let continuation = process_input_event::process_readline_event(
                        readline_event, &mut state, &mut terminal_async.clone_shared_writer(), &mut terminal_async.readline
                    )?;
                    if let ControlFlow::Break(_) = continuation { 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;
                },
            }
        }
    }

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

    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 151)

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(),
    };

    // 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.
    let display_preference = DisplayPreference::SharedWriter(terminal_async.shared_writer.clone());
    let config = TracingConfig::new(display_preference);
    tracing_setup::init(config)?;

    // 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())?;
            },
            user_input = terminal_async.get_readline_event() => match user_input {
                Ok(readline_event) => {
                    let continuation = process_input_event::process_readline_event(
                        readline_event, &mut state, &mut terminal_async.clone_shared_writer(), &mut terminal_async.readline
                    )?;
                    if let ControlFlow::Break(_) = continuation { 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;
                },
            }
        }
    }

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

    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.

Examples found in repository

examples/terminal_async.rs (line 180)

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(),
    };

    // 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.
    let display_preference = DisplayPreference::SharedWriter(terminal_async.shared_writer.clone());
    let config = TracingConfig::new(display_preference);
    tracing_setup::init(config)?;

    // 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())?;
            },
            user_input = terminal_async.get_readline_event() => match user_input {
                Ok(readline_event) => {
                    let continuation = process_input_event::process_readline_event(
                        readline_event, &mut state, &mut terminal_async.clone_shared_writer(), &mut terminal_async.readline
                    )?;
                    if let ControlFlow::Break(_) = continuation { 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;
                },
            }
        }
    }

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

    Ok(())
}

pub async fn pause(&mut self)

pub async fn resume(&mut self)

pub fn close(&mut self)

Close the underlying Readline instance. This will terminate all the tasks that are managing SharedWriter tasks. This is useful when you want to exit the CLI event loop, typically when the user requests it.

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