Crate indicatif [−] [src]

indicatif is a library for Rust that helps you build command line interfaces that report progress to users. It comes with various tools and utilities for formatting anything that indicates progress.

Progress Bars and Spinners

indicatif comes with a ProgressBar type that support both bounded progress bar uses as well as unbounded "spinner" type progress reports. Progress bars are Sync and Send objects which means that they are internally locked and can be passed from thread to thread.

Additionally a MultiProgress utility is provided that can manage rendering multiple progress bars at once (eg: for instance from multiple threads).

Progress bars are manually advanced and by default draw to stdout. When you are done the progress bar can be finished either visibly (eg: the progress bar stays on the screen) or cleared (the progress bar will be removed).

use indicatif::ProgressBar;

let bar = ProgressBar::new(1000);
for _ in 0..1000 {
    bar.inc();
    // ...
}
bar.finish();

Templates

Progress bars can be styled with simple format strings similar to the ones in Rust itself. The format for a placeholder is {key:options} where the options part is optional. If provided the format is this:

[<^]            for an optional alignment specification
WIDTH           an optional width as positive integer
!               an optional exclamation mark to enable truncation
.STYLE          an optional dot separated style string
/STYLE          an optional dot separated alternative style string

For the style component see Styled::from_dotted_str for more information.

Some examples for templates:

[{elapsed_precise}] {bar:40.cyan/blue} {pos:>7}/{len:7} {msg}

This sets a progress bar that is 40 characters wide and has cyan as primary style color and blue as alternative style color. Alternative styles are currently only used for progress bars.

The following keys exist:

bar: renders a progress bar. By default 20 characters wide. The style string is used to color the elapsed part, the alternative style is used for the bar that is yet to render.
wide_bar: like bar but always fills the remaining space.
spinner: renders the spinner (current tick char)
msg: renders the currently set message on the progress bar.
pos: renders the current position of the bar as integer
len: renders the total length of the bar as integer
bytes: renders the current position of the bar as bytes.
total_bytes: renders the total length of the bar as bytes.
elapsed_precise: renders the elapsed time as HH:MM:SS.
elapased: renders the elapsed time as 42s, 1m etc.
eta_precise: the remaining time (like elapsed_precise).
eta: the remaining time (like elapsed).

The design of the progress bar can be altered with the integrated template functionality.

Colors

indicatif uses clicolors-control to control colors. It also provides higher level wrappers for styling text and other things that can be displayed with the style function.

Structs

DrawState	The drawn state of an element.
FormattedDuration	Wraps an std duration for human basic formatting.
HumanBytes	Formats bytes for human readability
HumanDuration	Wraps an std duration for human readable formatting.
MultiProgress	Manages multiple progress bars from different threads.
ProgressBar	A progress bar or spinner.
ProgressState	The state of a progress bar at a moment in time.
ProgressStyle	Controls the rendering style of progress bars.
Styled	A formatting wrapper that can be styled for a terminal.
Term	Abstraction around a terminal.

Enums

Color	An ANSI color.
DrawTarget	Target for draw operations
Style	An ANSI style.

Functions

colors_enabled	Returns `true` if colors should be enabled.
measure_text_width	Measure the width of a string in terminal characters.
set_colors_enabled	Forces colorization on or off.
strip_ansi_codes	Helper function to strip ansi codes.
style	Wraps an object for formatting for styling.