1//! indicatif is a library for Rust that helps you build command line
2//! interfaces that report progress to users. It comes with various
3//! tools and utilities for formatting anything that indicates progress.
4//!
5//! Platform support:
6//!
7//! * Linux
8//! * macOS
9//! * Windows (colors require Windows 10)
10//!
11//! Best paired with other libraries in the family:
12//!
13//! * [console](https://docs.rs/console)
14//! * [dialoguer](https://docs.rs/dialoguer)
15//!
16//! # Crate Contents
17//!
18//! * **Progress bars**
19//! * [`ProgressBar`](struct.ProgressBar.html) for bars and spinners
20//! * [`MultiProgress`](struct.MultiProgress.html) for multiple bars
21//! * **Data Formatting**
22//! * [`HumanBytes`](struct.HumanBytes.html) for formatting bytes
23//! * [`DecimalBytes`](struct.DecimalBytes.html) for formatting bytes using SI prefixes
24//! * [`BinaryBytes`](struct.BinaryBytes.html) for formatting bytes using ISO/IEC prefixes
25//! * [`HumanDuration`](struct.HumanDuration.html) for formatting durations
26//! * [`HumanCount`](struct.HumanCount.html) for formatting large counts
27//! * [`HumanFloatCount`](struct.HumanFloatCount.html) for formatting large float counts
28//!
29//! # Progress Bars and Spinners
30//!
31//! indicatif comes with a [`ProgressBar`] type that supports both bounded
32//! progress bar uses as well as unbounded "spinner" type progress reports.
33//! Progress bars are [`Sync`] and [`Send`] objects which means that they are
34//! internally locked and can be passed from thread to thread.
35//!
36//! Additionally a [`MultiProgress`] utility is provided that can manage
37//! rendering multiple progress bars at once (eg: from multiple threads).
38//!
39//! To whet your appetite, this is what this can look like:
40//!
41//! <img src="https://github.com/console-rs/indicatif/raw/main/screenshots/yarn.gif?raw=true" width="60%">
42//!
43//! Progress bars are manually advanced and by default draw to stderr.
44//! When you are done, the progress bar can be finished either visibly
45//! (eg: the progress bar stays on the screen) or cleared (the progress
46//! bar will be removed).
47//!
48//! ```rust
49//! use indicatif::ProgressBar;
50//!
51//! let bar = ProgressBar::new(1000);
52//! for _ in 0..1000 {
53//! bar.inc(1);
54//! // ...
55//! }
56//! bar.finish();
57//! ```
58//!
59//! Spinners can be manually advanced with [`tick`](ProgressBar::tick), or you can set them up
60//! to spin automatically with [`enable_steady_tick`](ProgressBar::enable_steady_tick):
61//!
62//! ```rust
63//! use std::time::Duration;
64//! use indicatif::ProgressBar;
65//!
66//! let bar = ProgressBar::new_spinner();
67//! bar.enable_steady_tick(Duration::from_millis(100));
68//! // ... do some work
69//! bar.finish();
70//! ```
71//!
72//! General progress bar behaviors:
73//!
74//! * if a non terminal is detected the progress bar will be completely
75//! hidden. This makes piping programs to logfiles make sense out of
76//! the box.
77//! * a progress bar only starts drawing when [`set_message`](ProgressBar::set_message),
78//! [`inc`](ProgressBar::inc), [`set_position`](ProgressBar::set_position)
79//! or [`tick`](ProgressBar::tick) are called. In some situations you
80//! might have to call [`tick`](ProgressBar::tick) once to draw it.
81//! * progress bars should be explicitly finished to reset the rendering
82//! for others. Either by also clearing them or by replacing them with
83//! a new message / retaining the current message.
84//! * the default template renders neither message nor prefix.
85//!
86//! # Iterators
87//!
88//! Similar to [tqdm](https://github.com/tqdm/tqdm), progress bars can be
89//! associated with an iterator. For example:
90//!
91//! ```rust
92//! use indicatif::ProgressIterator;
93//!
94//! for _ in (0..1000).progress() {
95//! // ...
96//! }
97//! ```
98//!
99//! See the [`ProgressIterator`](trait.ProgressIterator.html) trait for more
100//! methods to configure the number of elements in the iterator or change
101//! the progress bar style. Indicatif also has optional support for parallel
102//! iterators with [Rayon](https://github.com/rayon-rs/rayon). In your
103//! `Cargo.toml`, use the "rayon" feature:
104//!
105//! ```toml
106//! [dependencies]
107//! indicatif = {version = "*", features = ["rayon"]}
108//! ```
109//!
110//! And then use it like this:
111//!
112//! ```rust,ignore
113//! # extern crate rayon;
114//! use indicatif::ParallelProgressIterator;
115//! use rayon::iter::{ParallelIterator, IntoParallelRefIterator};
116//!
117//! let v: Vec<_> = (0..100000).collect();
118//! let v2: Vec<_> = v.par_iter().progress_count(v.len() as u64).map(|i| i + 1).collect();
119//! assert_eq!(v2[0], 1);
120//! ```
121//!
122//! Or if you'd like to customize the progress bar:
123//!
124//! ```rust,ignore
125//! # extern crate rayon;
126//! use indicatif::{ProgressBar, ParallelProgressIterator, ProgressStyle};
127//! use rayon::iter::{ParallelIterator, IntoParallelRefIterator};
128//!
129//! // Alternatively, use `ProgressBar::new().with_style()`
130//! let style = ProgressStyle::default_bar();
131//! let v: Vec<_> = (0..100000).collect();
132//! let v2: Vec<_> = v.par_iter().progress_with_style(style).map(|i| i + 1).collect();
133//! assert_eq!(v2[0], 1);
134//! ```
135//!
136//! # Templates
137//!
138//! Progress bars can be styled with simple format strings similar to the
139//! ones in Rust itself. The format for a placeholder is `{key:options}`
140//! where the `options` part is optional. If provided the format is this:
141//!
142//! ```text
143//! <^> for an optional alignment specification (left, center and right respectively)
144//! WIDTH an optional width as positive integer
145//! ! an optional exclamation mark to enable truncation
146//! .STYLE an optional dot separated style string
147//! /STYLE an optional dot separated alternative style string
148//! ```
149//!
150//! For the style component see [`Style::from_dotted_str`](https://docs.rs/console/0.7.5/console/struct.Style.html#method.from_dotted_str)
151//! for more information. Indicatif uses the `console` base crate for all
152//! colorization and formatting options.
153//!
154//! Some examples for templates:
155//!
156//! ```text
157//! [{elapsed_precise}] {bar:40.cyan/blue} {pos:>7}/{len:7} {msg}
158//! ```
159//!
160//! This sets a progress bar that is 40 characters wide and has cyan
161//! as primary style color and blue as alternative style color.
162//! Alternative styles are currently only used for progress bars.
163//!
164//! Example configuration:
165//!
166//! ```rust
167//! # use indicatif::{ProgressBar, ProgressStyle};
168//! # let bar = ProgressBar::new(0);
169//! bar.set_style(ProgressStyle::with_template("[{elapsed_precise}] {bar:40.cyan/blue} {pos:>7}/{len:7} {msg}")
170//! .unwrap()
171//! .progress_chars("##-"));
172//! ```
173//!
174//! The following keys exist:
175//!
176//! * `bar`: renders a progress bar. By default 20 characters wide. The
177//! style string is used to color the elapsed part, the alternative
178//! style is used for the bar that is yet to render.
179//! * `wide_bar`: like `bar` but always fills the remaining space. It should not be used with `wide_msg`.
180//! * `spinner`: renders the spinner (current tick string). Note that spinners do not automatically tick by default. You either
181//! need to call `enable_steady_tick` or manually call `tick`.
182//! * `prefix`: renders the prefix set on the progress bar.
183//! * `msg`: renders the currently set message on the progress bar.
184//! * `wide_msg`: like `msg` but always fills the remaining space and truncates. It should not be used
185//! with `wide_bar`.
186//! * `pos`: renders the current position of the bar as integer
187//! * `human_pos`: renders the current position of the bar as an integer, with commas as the
188//! thousands separator.
189//! * `len`: renders the amount of work to be done as an integer
190//! * `human_len`: renders the total length of the bar as an integer, with commas as the thousands
191//! separator.
192//! * `percent`: renders the current position of the bar as a percentage of the total length (as an integer).
193//! * `percent_precise`: renders the current position of the bar as a percentage of the total length (with 3 fraction digits).
194//! * `bytes`: renders the current position of the bar as bytes (alias of `binary_bytes`).
195//! * `total_bytes`: renders the total length of the bar as bytes (alias of `binary_total_bytes`).
196//! * `decimal_bytes`: renders the current position of the bar as bytes using
197//! power-of-10 units, i.e. `MB`, `kB`, etc.
198//! * `decimal_total_bytes`: renders the total length of the bar as bytes using
199//! power-of-10 units, i.e. `MB`, `kB`, etc.
200//! * `binary_bytes`: renders the current position of the bar as bytes using
201//! power-of-two units, i.e. `MiB`, `KiB`, etc.
202//! * `binary_total_bytes`: renders the total length of the bar as bytes using
203//! power-of-two units, i.e. `MiB`, `KiB`, etc.
204//! * `elapsed_precise`: renders the elapsed time as `HH:MM:SS`.
205//! * `elapsed`: renders the elapsed time as `42s`, `1m` etc.
206//! * `per_sec`: renders the speed in steps per second.
207//! * `bytes_per_sec`: renders the speed in bytes per second (alias of `binary_bytes_per_sec`).
208//! * `decimal_bytes_per_sec`: renders the speed in bytes per second using
209//! power-of-10 units, i.e. `MB`, `kB`, etc.
210//! * `binary_bytes_per_sec`: renders the speed in bytes per second using
211//! power-of-two units, i.e. `MiB`, `KiB`, etc.
212//! * `eta_precise`: the remaining time (like `elapsed_precise`).
213//! * `eta`: the remaining time (like `elapsed`).
214//! * `duration_precise`: the extrapolated total duration (like `elapsed_precise`).
215//! * `duration`: the extrapolated total duration time (like `elapsed`).
216//!
217//! If the list above does not contain the value you need, consider creating a custom
218//! [`ProgressTracker`][crate::style::ProgressTracker] implementation.
219//!
220//! The design of the progress bar can be altered with the integrated
221//! template functionality. The template can be set by changing a
222//! [`ProgressStyle`] and attaching it to the progress bar.
223//!
224//! # Human Readable Formatting
225//!
226//! There are some formatting wrappers for showing elapsed time and
227//! file sizes for human users:
228//!
229//! ```rust
230//! # use std::time::Duration;
231//! use indicatif::{HumanBytes, HumanCount, HumanDuration, HumanFloatCount};
232//!
233//! assert_eq!("3.00 MiB", HumanBytes(3*1024*1024).to_string());
234//! assert_eq!("8 seconds", HumanDuration(Duration::from_secs(8)).to_string());
235//! assert_eq!("33,857,009", HumanCount(33857009).to_string());
236//! assert_eq!("33,857,009.1235", HumanFloatCount(33857009.123456).to_string());
237//! ```
238//!
239//! # Feature Flags
240//!
241//! * `rayon`: adds rayon support
242//! * `improved_unicode`: adds improved unicode support (graphemes, better width calculation)
243
244#![cfg_attr(docsrs, feature(doc_cfg))]
245#![warn(unreachable_pub)]
246
247mod draw_target;
248mod format;
249#[cfg(feature = "in_memory")]
250mod in_memory;
251mod iter;
252mod multi;
253mod progress_bar;
254#[cfg(feature = "rayon")]
255mod rayon;
256mod state;
257pub mod style;
258mod term_like;
259
260pub use crate::draw_target::ProgressDrawTarget;
261pub use crate::format::{
262 BinaryBytes, DecimalBytes, FormattedDuration, HumanBytes, HumanCount, HumanDuration,
263 HumanFloatCount,
264};
265#[cfg(feature = "in_memory")]
266pub use crate::in_memory::InMemoryTerm;
267pub use crate::iter::{ProgressBarIter, ProgressIterator};
268pub use crate::multi::{MultiProgress, MultiProgressAlignment};
269pub use crate::progress_bar::{ProgressBar, WeakProgressBar};
270#[cfg(feature = "rayon")]
271pub use crate::rayon::ParallelProgressIterator;
272pub use crate::state::{ProgressFinish, ProgressState};
273pub use crate::style::ProgressStyle;
274pub use crate::term_like::TermLike;
275