Expand description
strides is an async-first crate to support building command line tools which display progress to the user. The purpose is similar to that of the widely used indicatif crate but focuses on integrating with async futures and streams and drive progress animations based on polling state.
Instead of integrating progress bar and spinner UI elements along an asynchronous program,
strides provides utilities to integrate these elements as part of the Future and
Stream abstractions.
§Spinners
A spinner is a UI element that represents ongoing work. It is usually iconified as a circular
motion but anything that streams Unicode characters can be used. To create a spinner, import
the Spinner struct and pass it a string slice:
let abc = strides::spinner::Spinner::new("abc");The ticks() method returns an infinite stream that cycles
through the characters of the string slice. The rate at which characters are cycled is set to
every 80ms and can be changed with the
with_interval() function.
The spinner::styles module provides a few pre-defined spinner
styles.
§Progress styles
A ProgressStyle bundles a Spinner
and a Bar into a single configuration object that can be passed to both
the futures and streams progress APIs:
let style = strides::style::ProgressStyle::new()
.with_bar(strides::bar::styles::PARALLELOGRAM)
.with_spinner(strides::spinner::styles::DOTS_3);A bare Spinner can also be passed directly wherever a
ProgressStyle is expected.
§Streams
Import the StreamExt extension to use the
progress() and
progress_with_messages() APIs. The second
parameter is a closure used to calculate the progress as a fraction between 0.0 and 1.0. The
closure receives two parameters: the monotonically increasing item number and a reference to
the item itself. The former is useful if the number of stream items is known upfront and
determines the overall progress, whereas the second is useful to determine progress based on
the item itself. For example, the number of downloaded bytes.
§Examples
§Single future is in progress
In the simplest case, you can use strides to display that a Future has not completed yet. For
that import the FutureExt extension trait that adds the
progress() and
progress_with_messages() methods to
futures which show a spinner, an optional progress bar and a message:
use strides::future::FutureExt;
use strides::spinner::styles::DOTS_3;
use std::time::Duration;
std::pin::pin!(async {
// Simulate work by waiting for three seconds.
async_io::Timer::after(Duration::from_secs(3)).await;
})
.progress(DOTS_3, "this will take some time")
.await;