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//! General progress bar behaviors:
60//!
61//! * if a non terminal is detected the progress bar will be completely
62//! hidden. This makes piping programs to logfiles make sense out of
63//! the box.
64//! * a progress bar only starts drawing when `set_message`, `inc`, `set_position`
65//! or `tick` are called. In some situations you might have to call `tick`
66//! once to draw it.
67//! * progress bars should be explicitly finished to reset the rendering
68//! for others. Either by also clearing them or by replacing them with
69//! a new message / retaining the current message.
70//! * the default template renders neither message nor prefix.
71//!
72//! # Iterators
73//!
74//! Similar to [tqdm](https://github.com/tqdm/tqdm), progress bars can be
75//! associated with an iterator. For example:
76//!
77//! ```rust
78//! use indicatif::ProgressIterator;
79//!
80//! for _ in (0..1000).progress() {
81//! // ...
82//! }
83//! ```
84//!
85//! See the [`ProgressIterator`](trait.ProgressIterator.html) trait for more
86//! methods to configure the number of elements in the iterator or change
87//! the progress bar style. Indicatif also has optional support for parallel
88//! iterators with [Rayon](https://github.com/rayon-rs/rayon). In your
89//! `Cargo.toml`, use the "rayon" feature:
90//!
91//! ```toml
92//! [dependencies]
93//! indicatif = {version = "*", features = ["rayon"]}
94//! ```
95//!
96//! And then use it like this:
97//!
98//! ```rust,ignore
99//! # extern crate rayon;
100//! use indicatif::ParallelProgressIterator;
101//! use rayon::iter::{ParallelIterator, IntoParallelRefIterator};
102//!
103//! let v: Vec<_> = (0..100000).collect();
104//! let v2: Vec<_> = v.par_iter().progress_count(v.len() as u64).map(|i| i + 1).collect();
105//! assert_eq!(v2[0], 1);
106//! ```
107//!
108//! Or if you'd like to customize the progress bar:
109//!
110//! ```rust,ignore
111//! # extern crate rayon;
112//! use indicatif::{ProgressBar, ParallelProgressIterator, ProgressStyle};
113//! use rayon::iter::{ParallelIterator, IntoParallelRefIterator};
114//!
115//! // Alternatively, use `ProgressBar::new().with_style()`
116//! let style = ProgressStyle::default_bar();
117//! let v: Vec<_> = (0..100000).collect();
118//! let v2: Vec<_> = v.par_iter().progress_with_style(style).map(|i| i + 1).collect();
119//! assert_eq!(v2[0], 1);
120//! ```
121//!
122//! # Templates
123//!
124//! Progress bars can be styled with simple format strings similar to the
125//! ones in Rust itself. The format for a placeholder is `{key:options}`
126//! where the `options` part is optional. If provided the format is this:
127//!
128//! ```text
129//! <^> for an optional alignment specification (left, center and right respectively)
130//! WIDTH an optional width as positive integer
131//! ! an optional exclamation mark to enable truncation
132//! .STYLE an optional dot separated style string
133//! /STYLE an optional dot separated alternative style string
134//! ```
135//!
136//! For the style component see [`Style::from_dotted_str`](https://docs.rs/console/0.7.5/console/struct.Style.html#method.from_dotted_str)
137//! for more information. Indicatif uses the `console` base crate for all
138//! colorization and formatting options.
139//!
140//! Some examples for templates:
141//!
142//! ```text
143//! [{elapsed_precise}] {bar:40.cyan/blue} {pos:>7}/{len:7} {msg}
144//! ```
145//!
146//! This sets a progress bar that is 40 characters wide and has cyan
147//! as primary style color and blue as alternative style color.
148//! Alternative styles are currently only used for progress bars.
149//!
150//! Example configuration:
151//!
152//! ```rust
153//! # use indicatif::{ProgressBar, ProgressStyle};
154//! # let bar = ProgressBar::new(0);
155//! bar.set_style(ProgressStyle::with_template("[{elapsed_precise}] {bar:40.cyan/blue} {pos:>7}/{len:7} {msg}")
156//! .unwrap()
157//! .progress_chars("##-"));
158//! ```
159//!
160//! The following keys exist:
161//!
162//! * `bar`: renders a progress bar. By default 20 characters wide. The
163//! style string is used to color the elapsed part, the alternative
164//! style is used for the bar that is yet to render.
165//! * `wide_bar`: like `bar` but always fills the remaining space. It should not be used with
166//! `wide_msg`.
167//! * `spinner`: renders the spinner (current tick string).
168//! * `prefix`: renders the prefix set on the progress bar.
169//! * `msg`: renders the currently set message on the progress bar.
170//! * `wide_msg`: like `msg` but always fills the remaining space and truncates. It should not be used
171//! with `wide_bar`.
172//! * `pos`: renders the current position of the bar as integer
173//! * `human_pos`: renders the current position of the bar as an integer, with commas as the
174//! thousands separator.
175//! * `len`: renders the amount of work to be done as an integer
176//! * `human_len`: renders the total length of the bar as an integer, with commas as the thousands
177//! separator.
178//! * `bytes`: renders the current position of the bar as bytes.
179//! * `percent`: renders the current position of the bar as a percentage of the total length.
180//! * `total_bytes`: renders the total length of the bar as bytes.
181//! * `elapsed_precise`: renders the elapsed time as `HH:MM:SS`.
182//! * `elapsed`: renders the elapsed time as `42s`, `1m` etc.
183//! * `per_sec`: renders the speed in steps per second.
184//! * `bytes_per_sec`: renders the speed in bytes per second.
185//! * `binary_bytes_per_sec`: renders the speed in bytes per second using
186//! power-of-two units, i.e. `MiB`, `KiB`, etc.
187//! * `eta_precise`: the remaining time (like `elapsed_precise`).
188//! * `eta`: the remaining time (like `elapsed`).
189//! * `duration_precise`: the extrapolated total duration (like `elapsed_precise`).
190//! * `duration`: the extrapolated total duration time (like `elapsed`).
191
192//!
193//! The design of the progress bar can be altered with the integrated
194//! template functionality. The template can be set by changing a
195//! `ProgressStyle` and attaching it to the progress bar.
196//!
197//! # Human Readable Formatting
198//!
199//! There are some formatting wrappers for showing elapsed time and
200//! file sizes for human users:
201//!
202//! ```rust
203//! # use std::time::Duration;
204//! use indicatif::{HumanBytes, HumanCount, HumanDuration, HumanFloatCount};
205//!
206//! assert_eq!("3.00 MiB", HumanBytes(3*1024*1024).to_string());
207//! assert_eq!("8 seconds", HumanDuration(Duration::from_secs(8)).to_string());
208//! assert_eq!("33,857,009", HumanCount(33857009).to_string());
209//! assert_eq!("33,857,009.1235", HumanFloatCount(33857009.123456).to_string());
210//! ```
211//!
212//! # Feature Flags
213//!
214//! * `rayon`: adds rayon support
215//! * `improved_unicode`: adds improved unicode support (graphemes, better width calculation)
216
217#![cfg_attr(docsrs, feature(doc_cfg))]
218#![warn(unreachable_pub)]
219
220mod draw_target;
221mod format;
222#[cfg(feature = "in_memory")]
223mod in_memory;
224mod iter;
225mod multi;
226mod progress_bar;
227#[cfg(feature = "rayon")]
228mod rayon;
229mod state;
230pub mod style;
231mod term_like;
232
233pub use crate::draw_target::ProgressDrawTarget;
234pub use crate::format::{
235 BinaryBytes, DecimalBytes, FormattedDuration, HumanBytes, HumanCount, HumanDuration,
236 HumanFloatCount,
237};
238#[cfg(feature = "in_memory")]
239pub use crate::in_memory::InMemoryTerm;
240pub use crate::iter::{ProgressBarIter, ProgressIterator};
241pub use crate::multi::{MultiProgress, MultiProgressAlignment};
242pub use crate::progress_bar::{ProgressBar, WeakProgressBar};
243#[cfg(feature = "rayon")]
244pub use crate::rayon::ParallelProgressIterator;
245pub use crate::state::{ProgressFinish, ProgressState};
246pub use crate::style::ProgressStyle;
247pub use crate::term_like::TermLike;
248