strides/lib.rs
1//! strides is an async-first crate to support building command line tools which display progress to
2//! the user. The purpose is similar to that of the widely used indicatif crate but focuses on
3//! integrating with async futures and streams and drive progress animations based on polling
4//! state.
5//!
6//! Instead of integrating progress bar and spinner UI elements along an asynchronous program,
7//! strides provides utilities to integrate these elements as part of the [`Future`] and
8//! [`Stream`](futures_lite::Stream) abstractions.
9//!
10//! ## Spinners
11//!
12//! A spinner is a UI element that represents ongoing work. It is usually iconified as a circular
13//! motion but anything that streams Unicode characters can be used. To create a spinner, import
14//! the [`Spinner`](crate::spinner::Spinner) struct and pass it a string slice:
15//!
16//! ```rust
17//! let abc = strides::spinner::Spinner::new("abc");
18//! ```
19//!
20//! The [`ticks()`](crate::spinner::Spinner::ticks) method returns an infinite stream that cycles
21//! through the characters of the string slice. The rate at which characters are cycled is set to
22//! every 80ms and can be changed with the
23//! [`with_interval()`](crate::spinner::Spinner::with_interval) function.
24//!
25//! The [`spinner::styles`] module provides a few pre-defined spinner
26//! styles.
27//!
28//! ## Progress styles
29//!
30//! A [`ProgressStyle`](crate::style::ProgressStyle) bundles a [`Spinner`](crate::spinner::Spinner)
31//! and a [`Bar`](crate::bar::Bar) into a single configuration object that can be passed to both
32//! the futures and streams progress APIs:
33//!
34//! ```rust
35//! let style = strides::style::ProgressStyle::new()
36//! .with_bar(strides::bar::styles::PARALLELOGRAM)
37//! .with_spinner(strides::spinner::styles::DOTS_3);
38//! ```
39//!
40//! A bare [`Spinner`](crate::spinner::Spinner) can also be passed directly wherever a
41//! [`ProgressStyle`](crate::style::ProgressStyle) is expected.
42//!
43//! ## Streams
44//!
45//! Import the [`StreamExt`](crate::stream::StreamExt) extension to use the
46//! [`progress()`](crate::stream::StreamExt::progress) and
47//! [`progress_with_messages()`](crate::stream::StreamExt::progress_with_messages) APIs. The second
48//! parameter is a closure used to calculate the progress as a fraction between 0.0 and 1.0. The
49//! closure receives two parameters: the monotonically increasing item number and a reference to
50//! the item itself. The former is useful if the number of stream items is known upfront and
51//! determines the overall progress, whereas the second is useful to determine progress based on
52//! the item itself. For example, the number of downloaded bytes.
53//!
54//! ## Examples
55//!
56//! ### Single future is in progress
57//!
58//! In the simplest case, you can use strides to display that a [`Future`] has not completed yet. For
59//! that import the [`FutureExt`](crate::future::FutureExt) extension trait that adds the
60//! [`progress()`](crate::future::FutureExt::progress) and
61//! [`progress_with_messages()`](crate::future::FutureExt::progress_with_messages) methods to
62//! futures which show a spinner, an optional progress bar and a message:
63//!
64//! ```rust,no_run
65//! use strides::future::FutureExt;
66//! use strides::spinner::styles::DOTS_3;
67//! use std::time::Duration;
68//!
69//! # futures_lite::future::block_on(async {
70//! std::pin::pin!(async {
71//! // Simulate work by waiting for three seconds.
72//! async_io::Timer::after(Duration::from_secs(3)).await;
73//! })
74//! .progress(DOTS_3, "this will take some time")
75//! .await;
76//! # });
77//! ```
78
79pub mod bar;
80pub mod future;
81pub mod spinner;
82pub mod stream;
83pub mod style;
84
85mod term;