Struct Readline

pub struct Readline {
    pub output_device: OutputDevice,
    pub input_device: InputDevice,
    pub safe_line_state: SafeLineState,
    pub history_sender: UnboundedSender<String>,
    pub history_receiver: UnboundedReceiver<String>,
    pub safe_history: SafeHistory,
    pub safe_is_paused_buffer: SafePauseBuffer,
    pub safe_spinner_is_active: Arc<StdMutex<Option<Sender<()>>>>,
}

Mental model and overview

This is a replacement for a std::io::BufRead::read_line function. It is async. It supports other tasks concurrently writing to the terminal output (via SharedWriters). It also supports being paused so that crate::Spinner can display an indeterminate progress spinner. Then it can be resumed so that the user can type in the terminal. Upon resumption, any queued output from the SharedWriters is printed out.

When you call Self::readline() it enters an infinite loop. During which you can type things into the multiline editor, which also displays the prompt. You can press up, down, left, right, etc. While in this loop other tasks can send messages to the Readline task via the line channel, using the SharedWriter::line_state_control_channel_sender.

When you create a new Readline instance, a task, is started via manage_shared_writer_output::spawn_task_to_monitor_line_state_signals(). This task monitors the line channel, and processes any messages that are sent to it. This allows the task to be paused, and resumed, and to flush the output from the SharedWriters.

When to terminate the session

There is no close() function on Readline. You simply drop it. This will cause the the terminal to come out of raw mode. And all the buffers will be flushed. However, there are 2 ways to use this Readline::readline() in a loop or just as a one off. Each time this function is called, you have to await it to return the user input or Interrupted or Eof signal.

When creating a new crate::TerminalAsync instance, you can use this repeatedly before dropping it. This is because the r3bl_core::SharedWriter is cloned, and the terminal is kept in raw mode until the associated crate::Readline is dropped.

Inputs and dependency injection

There are 2 main resources that must be passed into Self::new():

1. InputDevice which contains a resource that implements r3bl_core::PinnedInputStream - This trait represents an async stream of events. It is typically implemented by crossterm::event::EventStream. This is used to get input from the user. However for testing you can provide your own implementation of this trait.
2. OutputDevice which contains a resources that implements crate::SafeRawTerminal - This trait represents a raw terminal. It is typically implemented by std::io::Stdout. This is used to write to the terminal. However for testing you can provide your own implementation of this trait.

Support for testing

Almost all the fields of this struct contain Safe in their names. This is because they are wrapped in a Mutex and Arc, so that they can be shared between tasks. This makes it easier to test this struct, because you can mock the terminal output, and the input stream. You can also mock the history, and the pause buffer. This is all possible because of the dependency injection that this struct uses. See the tests for how this is used. If there are some fields that seem a bit uneconomic, in where they come from, it is probably due to the requirement for every part of this system to be testable (easily).

Pause and resume

When the terminal is paused, then any output from the SharedWriters will not be printed to the terminal. This is useful when you want to display a spinner, or some other indeterminate progress indicator. The user input from the terminal is not going to be accepted either. Only Ctrl+C, and Ctrl+D are accepted while paused. This ensures that the user can’t enter any input while the terminal is paused. And output from a crate::Spinner won’t clobber the output from the SharedWriters or from the user input prompt while crate::Readline::readline() (or crate::TerminalAsync::get_readline_event) is being awaited.

When the terminal is resumed, then the output from the SharedWriters will be printed to the terminal by the manage_shared_writer_output::flush_internal() method, which drains a buffer that holds any output that was generated while paused, of type PauseBuffer. The user input prompt will be displayed again, and the user can enter input.

This is possible, because while paused, the manage_shared_writer_output::process_line_control_signal() method doesn’t actually print anything to the display. When resumed, the manage_shared_writer_output::flush_internal() method is called, which drains the PauseBuffer (if there are any messages in it, and prints them out) so nothing is lost!

See the crate::LineState for more information on exactly how the terminal is paused and resumed, when it comes to accepting or rejecting user input, and rendering output or not.

See the crate::TerminalAsync module docs for more information on the mental mode and architecture of this.

Usage details

Struct for reading lines of input from a terminal while lines are output to the terminal concurrently.

Terminal input is retrieved by calling Readline::readline(), which returns each complete line of input once the user presses Enter.

Each Readline instance is associated with one or more SharedWriter instances.

Lines written to an associated SharedWriter are output:

1. While retrieving input with readline().
2. By calling manage_shared_writer_output::flush_internal().

You can provide your own implementation of crate::SafeRawTerminal, like OutputDevice, via dependency injection, so that you can mock terminal output for testing. You can also extend this struct to adapt your own terminal output using this mechanism. Essentially anything that compiles with dyn std::io::Write + Send trait bounds can be used.

Fields

output_device: OutputDevice

Device used to write rendered display output to (usually stdout).

input_device: InputDevice

Device used to get stream of events from user (usually stdin).

safe_line_state: SafeLineState

Current line.

history_sender: UnboundedSender<String>

Use to send history updates.

history_receiver: UnboundedReceiver<String>

Use to receive history updates.

safe_history: SafeHistory

Manages the history.

safe_is_paused_buffer: SafePauseBuffer

Collects lines that are written to the terminal while the terminal is paused.

safe_spinner_is_active: Arc<StdMutex<Option<Sender<()>>>>

• Is Some if a crate::Spinner is currently active. This works with the signal LineStateControlSignal::SpinnerActive; this is used to set the crate::Spinner::shutdown_sender. Also works with the LineStateControlSignal::Pause signal.
• Is None if no crate::Spinner is active. Also works with the LineStateControlSignal::Resume signal.

Implementations

impl Readline

pub fn new( prompt: String, output_device: OutputDevice, input_device: InputDevice, ) -> Result<(Self, SharedWriter), ReadlineError>

Create a new instance with an associated SharedWriter. To customize the behavior of this instance, you can use the following methods:

• Self::should_print_line_on
• Self::set_max_history

pub fn update_prompt(&mut self, prompt: &str) -> Result<(), ReadlineError>

Change the prompt.

pub fn clear(&mut self) -> Result<(), ReadlineError>

Clear the screen.

pub fn set_max_history(&mut self, max_size: usize)

Set maximum history length. The default length is crate::HISTORY_SIZE_MAX.

pub fn should_print_line_on(&mut self, enter: bool, control_c: bool)

Set whether the input line should remain on the screen after events.

If enter is true, then when the user presses “Enter”, the prompt and the text they entered will remain on the screen, and the cursor will move to the next line. If enter is false, the prompt & input will be erased instead. The default value for this is true.

control_c similarly controls the behavior for when the user presses Ctrl-C. The default value for this is false.

Examples found in repository

examples/terminal_async.rs (line 309)

    pub fn process(
        user_input: String,
        state: &mut State,
        shared_writer: &mut SharedWriter,
        readline: &mut Readline,
    ) -> miette::Result<ControlFlow<()>> {
        // Add to history.
        let line = user_input.trim();
        readline.add_history_entry(line.to_string());

        // Convert line to command. And process it.
        let result_command = Command::from_str(&line.trim().to_lowercase());
        match result_command {
            Err(_) => {
                writeln!(shared_writer, "Unknown command!").into_diagnostic()?;
                return Ok(ControlFlow::Continue(()));
            }
            Ok(command) => match command {
                Command::Exit => {
                    return Ok(ControlFlow::Break(()));
                }
                Command::StartTask1 => {
                    state.task_1_state.is_running = true;
                    writeln!(
                        shared_writer,
                        "First task started! This prints to SharedWriter."
                    )
                    .into_diagnostic()?;
                }
                Command::StopTask1 => {
                    state.task_1_state.is_running = false;
                    writeln!(shared_writer, "First task stopped!").into_diagnostic()?;
                }
                Command::StartTask2 => {
                    state.task_2_state.is_running = true;
                    writeln!(
                        shared_writer,
                        "Second task started! This generates logs which print to DisplayPreference (SharedWriter) and file."
                    )
                    .into_diagnostic()?;
                }
                Command::StopTask2 => {
                    state.task_2_state.is_running = false;
                    writeln!(shared_writer, "Second task stopped!").into_diagnostic()?;
                }
                Command::StartPrintouts => {
                    writeln!(shared_writer, "Printouts started!").into_diagnostic()?;
                    readline.should_print_line_on(true, true);
                }
                Command::StopPrintouts => {
                    writeln!(shared_writer, "Printouts stopped!").into_diagnostic()?;
                    readline.should_print_line_on(false, false);
                }
                Command::Info => {
                    writeln!(shared_writer, "{}", get_info_message())
                        .into_diagnostic()?;
                }
                Command::Spinner => {
                    writeln!(shared_writer, "Spinner started! Pausing terminal...")
                        .into_diagnostic()?;
                    long_running_task::spawn_task_that_shows_spinner(
                        shared_writer,
                        readline,
                        "Spinner task",
                        Duration::from_millis(100),
                    );
                }
                Command::Tree => {
                    let mut shared_writer_clone = shared_writer.clone();
                    tokio::spawn(async move {
                        let mut_shared_writer = &mut shared_writer_clone;
                        match file_walker::get_current_working_directory() {
                            Ok((root_path, _)) => {
                                match file_walker::display_tree(
                                    root_path,
                                    mut_shared_writer,
                                    true,
                                )
                                .await
                                {
                                    Ok(_) => {}
                                    Err(_) => todo!(),
                                };
                            }
                            Err(_) => todo!(),
                        }
                    });
                }
            },
        }

        Ok(ControlFlow::Continue(()))
    }

pub async fn readline(&mut self) -> Result<ReadlineEvent, ReadlineError>

This function returns when Ctrl+D, Ctrl+C, or Enter is pressed with some user input.

Note that this function can be called repeatedly in a loop. It will return each line of input as it is entered (and return / exit). The crate::TerminalAsync can be re-used, since the r3bl_core::SharedWriter is cloned and the terminal is kept in raw mode until the associated crate::Readline is dropped.

Polling function for Self::readline, manages all input and output. Returns either an ReadlineEvent or an ReadlineError.

pub fn add_history_entry(&mut self, entry: String) -> Option<()>

Add a line to the input history.

Examples found in repository

examples/terminal_async.rs (line 156)

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

/// This task simply uses [writeln] and [SharedWriter] to print to stdout.
mod task_1 {
    use super::*;

    pub fn tick(state: &mut State, stdout: &mut SharedWriter) -> miette::Result<()> {
        if !state.task_1_state.is_running {
            return Ok(());
        };

        let counter_1 = state.task_1_state.counter;
        writeln!(stdout, "[{counter_1}] First interval went off!").into_diagnostic()?;
        state.task_1_state.counter += 1;

        Ok(())
    }
}

/// This task uses [tracing] to log to stdout (via [SharedWriter]).
mod task_2 {
    use super::*;

    pub fn tick(state: &mut State, _stdout: &mut SharedWriter) -> miette::Result<()> {
        if !state.task_2_state.is_running {
            return Ok(());
        };

        let counter_2 = state.task_2_state.counter;
        info!("[{counter_2}] Second interval went off!");
        state.task_2_state.counter += 1;

        Ok(())
    }
}

mod process_input_event {
    use super::*;

    pub fn process(
        user_input: String,
        state: &mut State,
        shared_writer: &mut SharedWriter,
        readline: &mut Readline,
    ) -> miette::Result<ControlFlow<()>> {
        // Add to history.
        let line = user_input.trim();
        readline.add_history_entry(line.to_string());

        // Convert line to command. And process it.
        let result_command = Command::from_str(&line.trim().to_lowercase());
        match result_command {
            Err(_) => {
                writeln!(shared_writer, "Unknown command!").into_diagnostic()?;
                return Ok(ControlFlow::Continue(()));
            }
            Ok(command) => match command {
                Command::Exit => {
                    return Ok(ControlFlow::Break(()));
                }
                Command::StartTask1 => {
                    state.task_1_state.is_running = true;
                    writeln!(
                        shared_writer,
                        "First task started! This prints to SharedWriter."
                    )
                    .into_diagnostic()?;
                }
                Command::StopTask1 => {
                    state.task_1_state.is_running = false;
                    writeln!(shared_writer, "First task stopped!").into_diagnostic()?;
                }
                Command::StartTask2 => {
                    state.task_2_state.is_running = true;
                    writeln!(
                        shared_writer,
                        "Second task started! This generates logs which print to DisplayPreference (SharedWriter) and file."
                    )
                    .into_diagnostic()?;
                }
                Command::StopTask2 => {
                    state.task_2_state.is_running = false;
                    writeln!(shared_writer, "Second task stopped!").into_diagnostic()?;
                }
                Command::StartPrintouts => {
                    writeln!(shared_writer, "Printouts started!").into_diagnostic()?;
                    readline.should_print_line_on(true, true);
                }
                Command::StopPrintouts => {
                    writeln!(shared_writer, "Printouts stopped!").into_diagnostic()?;
                    readline.should_print_line_on(false, false);
                }
                Command::Info => {
                    writeln!(shared_writer, "{}", get_info_message())
                        .into_diagnostic()?;
                }
                Command::Spinner => {
                    writeln!(shared_writer, "Spinner started! Pausing terminal...")
                        .into_diagnostic()?;
                    long_running_task::spawn_task_that_shows_spinner(
                        shared_writer,
                        readline,
                        "Spinner task",
                        Duration::from_millis(100),
                    );
                }
                Command::Tree => {
                    let mut shared_writer_clone = shared_writer.clone();
                    tokio::spawn(async move {
                        let mut_shared_writer = &mut shared_writer_clone;
                        match file_walker::get_current_working_directory() {
                            Ok((root_path, _)) => {
                                match file_walker::display_tree(
                                    root_path,
                                    mut_shared_writer,
                                    true,
                                )
                                .await
                                {
                                    Ok(_) => {}
                                    Err(_) => todo!(),
                                };
                            }
                            Err(_) => todo!(),
                        }
                    });
                }
            },
        }

        Ok(ControlFlow::Continue(()))
    }

Trait Implementations

impl Drop for Readline

fn drop(&mut self)

Executes the destructor for this type.