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.
Platform support:
- Linux
- OS X
- Windows (colors require Windows 10)
Crate Contents
- Progress bars
ProgressBar
for bars and spinnersMultiProgress
for multiple bars
- Terminal support
Term
for controlling the terminaluser_attended
for checking if there is a terminalmeasure_text_width
for calculating text width
- Colors and Styling
colors_enabled
for checking if colors are onset_colors_enabled
for turning colors off and onstrip_ansi_codes
for stripping ANSI codes from a stringstyle
/Style
for coloring stuff
- Data Formatting
HumanBytes
for formatting bytesHumanDuration
for formatting durations
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).
To wet your appetite, this is what this can look like:
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(1); // ... } bar.finish();
General progress bar behaviors:
- if a non terminal is detected the progress bar will be completely hidden. This makes piping programs to logfiles make sense out of the box.
- progress bars should be explicitly finished to reset the rendering for others. Either by also clearing them or by replacing them with a new message / retaining the current message.
- the default template renders neither message nor prefix.
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.
Example configuration:
bar.set_style(ProgressStyle::default_bar() .template("[{elapsed_precise}] {bar:40.cyan/blue} {pos:>7}/{len:7} {msg}") .progress_chars("##-"));
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)prefix
: renders the prefix set on the progress bar.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. The template can be set by changing a
ProgressStyle
and attaching it to the progress bar.
Terminal Access
The library provides a basic abstraction over working with terminals
through the Term
object. For instance you can use it to move
cursors or clear contents.
Colors and Styles
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.
Example usage:
use indicatif::style; println!("This is {} neat", style("fo").cyan());
Human Readable Formatting
There are some formatting wrappers for showing elapsed time and file sizes for human users:
use std::time::Instant; use indicatif::{HumanDuration, HumanBytes}; let started = Instant::now(); println!("The file is {} large", HumanBytes(file.size)); println!("The script took {}", HumanDuration(started.elapsed()));
Structs
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. |
ProgressDrawTarget |
Target for draw operations |
ProgressStyle |
Controls the rendering style of progress bars. |
Style |
A stored style that can be applied. |
StyledObject |
A formatting wrapper that can be styled for a terminal. |
Term |
Abstraction around a terminal. |
Enums
Attribute |
A terminal style attribute. |
Color |
A terminal color. |
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. |
user_attended |
A fast way to check if the application has a user attended. |