nazmulidris/r3bl_terminal_async

Async readline, concurrent stdout writer, and spinner component

This crate has been permanently moved to r3bl_terminal_async.

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.

r3bl_terminal_async's Issues

add more tests for the main components

add more examples that make it easier to see how this library can be used in real world examples

Consider adding the following:

• Create REPL (read execute print loop) programs that do the following. A CLI app that allows the user to type in a string and it can search for the existence of a file or folder by that name (or a fuzzy match of the name). the app can show the current time / date that updates in realtime while a possibly long running search is happening in another tokio task. Visit files and folders breadth first or depth first (use memory arena, and IR-free visitor / streamed versions).

• Create REPL (read execute print loop) programs that do the following. A CLI app that allows the user to type in a zip code and it can perform an HTTP GET operation that produces some results (eg: from the cat api or dog api). It might display some other information in real time (eg: time, or even some other API it pulls information from in another tokio task).

Since these apps are all REPLs, it means that they can manage their application state (similar to a React or Elm app). And they are async and support lots of tasks concurrently writing to stdout, which is what we need this library for.

Look into adding `bats` tests to provide integration & end to end tests for the lib crate

Currently there are no integration or end to end tests in this repo.

It would be great to have bats tests or something similar, that can actually put an entire app that uses this library under test to ensure that it it does what we expect.

Here are bats docs: https://bats-core.readthedocs.io/en/stable/writing-tests.html

enhance spinner

• it animates the entire line of text w/ color gradient (not just the spinner char)
• check why braille chars do not extend to the bottom of the display char height
• https://www.unicode.org/charts/script/chart_Braille.html

Add color gradient animation (using ColorWheel) to the Spinner

Build with Naz video implementing this

Enhance the Spinner component, in Rust, for CLI, using animated color gradients.

Colors

Use ColorWheel in r3bl_tui

in Readline::readline() try and accept a Stream resource

Use a similar pattern of DI used for SafeRawTerminal in Spinner and Readline, but this time, for streams that might be passed in to readline().

A stream might be implemented by:

1. crossterm::EventStream (current behavior)
2. a mock stream that is generated in tests

move this repo into r3bl-open-core repo

• in r3bl-open-core folder
  • land open PR w/ refactor changes
  • create a new branch
  • move the files from this repo
    • update image links in lib.rs and readme.md
  • update Cargo.toml workspace
  • update main readme
  • add run nushell script
  • update the nu run all scripts to make sure tests run
  • update release process md file
• remove all the files from this repo and update the README pointing to the new location
• mark this repo archived
• update links in the descriptions of all YT videos to point to r3bl-open-core location

Add an async spinner component similar to `indicatif` crate

Here is an example of using indicatif crate in a CLI app: create_progress_bar

It would be great to have something similar to this, with a much simpler and more intuitive API and much simpler functionality that works hand-in-hand with rustyline-async.

Add support to detect is TTY and disable itself when appropriate

• Define the behavior for totally uninteractive terminal, and piped stdout for Spinner
• Define the behavior for totally uninteractive terminal, and piped stdin for TerminalAsync

More info on piping:
https://unix.stackexchange.com/questions/597083/how-does-piping-affect-stdin

Refactor the code so that the public api is separated from internal implementation details of the crate

Explore whether it makes sense to support "modal" mode in ProgressBarAsync

This is just an exploratory idea. Would it make sense for ProgressBarAsync to block SharedWriter from Readline? So that while it is outputting its spinners that all other output would stall until the progress spinner completes? This is akin to modal behavior in dialog boxes.

Enhance the animation of the spinner

Build with Naz video implementing this

Add to the animation using dots for the spinner wit the following:

1. braille,
2. blocks (of varying "opacity")

Provide a way to specify the use of either of these when constructing a spinner.

Rewrite the entire crate, and remove all the deps from the original fork

There are too many confusing things in Cargo.toml. Mutex comes from one crate, select! from another, fuse() from yet another. They're all mashed up in there w/ all kinds of strange undefined behaviors and glitchy non deterministic output.

In `tcp-api-server client` the prompt isn't displayed properly

Run tcp-api-server client and you will notice that the prompt is not displayed. Even when the progress bar code is removed, the prompt shows and then disappears.

Something strange is happening with the prompt display and the using stdout or using crossterm to move the caret around.

add unit tests to improve test code coverage

YT video

Currently there really aren't many tests (if any) in the repo.

It would be great to have good code coverage and at tests inline with the code in each .rs file.

Examples of complex unit tests w/ global test fixtures (to test things like is_tty)
https://github.com/r3bl-org/r3bl-open-core/blob/nazmulidris/refactor-deps-in-core/ansi_color/src/detect_color_support.rs#L222

Strategy: Create a shim on top of the underlying functions. Use this shim in the code. Tests can override values in the shim w/out affecting the underlying code.

Links for testing async streams (like input event stream from crossterm):

• https://docs.rs/async-stream/latest/async_stream/
• https://tokio.rs/tokio/tutorial/streams
• https://tokio.rs/tokio/topics/testing
• https://gemini.google.com/app/86b3e898ceff05b3

clip spinner text to terminal width

Clip text to terminal width

• plain text
  • Use UnicodeString to calculate display width and handle clipping: graphemes in tui_core
  • code to clip plain text, r3bl_tuify
• vec of anisstyledtext
  • code for clipping vec of ansistyledtext, in r3bl_tuify

publish to crates.io

• crates.io publish
• TWIR announce
• developerlife.com mailing list announce

Add example that shows how to use ProgressBarAsync

Add animated gifs of examples in lib.rs & README.md

Examples - Replace readline.rs with terminal_async.rs

Currently there's really two "real" example:

• examples/readline.rs
• examples/spinner.rs

TODO:

• Replace readline.rs with terminal_async.rs
• Update lib.rs and README.md with all the new files, symbols, entry points, functions, etc

redesign `SharedWriter` so that it is simpler

More info on Rust async programming for this issue: https://rust-lang.github.io/async-book/01_getting_started/01_chapter.html

Redesign SharedWriter so that it doesn't implement AsyncWrite anymore. This requires changes to the

• Readline struct here and
• SharedWriter here.

Current design

1. The Readline struct creates an mpsc channel. It gets a line_sender and line_receiver.
   1.1. The line_sender is given to the SharedWriter. And as these are cloned and used elsewhere, the data in the buffer is send to the channel.
   1.2. The line_receiver is used by the Readline struct itself to handle the messages that are sent to the channel. This ends up being displayed to the "real" stdout.

New design

As write operations occur on the SharedWriter it sends those Text payloads to the channel. As the receiver, the Readline accumulates these payloads and flushes them to the actual stdout when it has received a \n in the payload. If the TerminalAsync is suspended, then the current behavior shouldn't change.

Changes to the Readline:

• Change line_receiver to type tokio::sync::mpsc::channel. This is async, and affects both the flush(), and readline() methods.
• Match the changes here to the ones in SharedWriter.

Changes to the SharedWriter:

• Drop the implementation of AsyncWrite.
• Change the implementation of Write:
  • drop thingbuf and replace w/ tokio sender
  • to use the tokio::sync::mpsc::Sender::try_send which is NOT async. You might also want to create a custom writer for tracing if this causes issues for stdout tracing. Here's an example.
• Match the changes here to the ones in Readline.

Drop the use of the following crates and just use tokio:

• futures-channel = "0.3"
• futures-util = { version = "0.3", features = ["io"] }
• pin-project = "1.0"
• thingbuf = "0.1"