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
: likebar
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 integerlen
: renders the total length of the bar as integerbytes
: 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 asHH:MM:SS
.elapased
: renders the elapsed time as42s
,1m
etc.eta_precise
: the remaining time (likeelapsed_precise
).eta
: the remaining time (likeelapsed
).
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 |
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. |