pub struct Progless { /* private fields */ }progress only.Expand description
§Progless.
This is a simple, thread-safe, steady-ticking CLI progress bar that can be used to entertain users while long jobs are running.
To use it, enable the progress crate flag.
§Examples
Initialize and use as follows:
use fyi_msg::Progless;
// You can use [`Progless::try_from`] for any unsigned integer type, or the
// infallible [`Progless::from`] on an [`std::num::NonZeroU32`].
let pbar = Progless::try_from(1001_u32).unwrap();
// Iterate your taskwork or whatever.
for i in 0..1001 {
// Do some work.
// ...
// Increment the count.
pbar.increment();
}
// Close it off.
pbar.finish();Progless is thread-safe so can be called from parallel iterators like
those from rayon without any special fuss.
When doing parallel work, many tasks might be “in progress” simultaneously.
To that end, you may wish to use the Progless::add and Progless::remove
methods at the start and end of each iteration instead of manually
incrementing the counts.
Doing this, a list of active tasks will be maintained and printed along
with the progress. Removing a task automatically increments the done count,
so if you’re tracking tasks, you should not call Progless::increment.
// ... snip
// Iterate in Parallel.
(0..1001).into_par_iter().for_each(|i| {
let task: String = format!("Task #{}.", i);
pbar.add(&task);
// Do some work.
pbar.remove(&task);
});
// ... snipImplementations§
source§impl Progless
impl Progless
§Constants.
sourcepub const MAX_TOTAL_ERROR: ProglessError = ProglessError::TotalOverflow
pub const MAX_TOTAL_ERROR: ProglessError = ProglessError::TotalOverflow
source§impl Progless
impl Progless
§Construction/Destruction.
sourcepub fn with_title<S>(self, title: Option<S>) -> Self
pub fn with_title<S>(self, title: Option<S>) -> Self
§With Title.
Add a title to the progress bar. When present, this will print on its own line immediately before the progress line.
Titles are formatted as Msg objects. You can pass a Msg
directly, or something that implements AsRef<str> or Borrow<str>.
As this takes an Option, you can pass None to unset the title
entirely.
§Examples
use fyi_msg::{Msg, Progless};
// Initialize with a `u32` total.
let pbar = Progless::try_from(1001_u32).unwrap()
.with_title(Some(Msg::info("Doing things!")));
// Iterate your taskwork or whatever.
for i in 0..1001 {
// Do some work.
// ...
// Increment the done count.
pbar.increment();
}
pbar.finish();sourcepub fn with_reticulating_splines<S>(self, app: S) -> Self
pub fn with_reticulating_splines<S>(self, app: S) -> Self
§Set Title As X: Reticulating Splines…
This is simply shorthand for generating a “Reticulating Splines…” title, where X is the value passed in (usually the app name).
It’s a sort of default…
sourcepub fn finish(&self) -> Duration
pub fn finish(&self) -> Duration
§Stop.
Finish the progress bar, shut down the steady ticker, and return the time elapsed.
Calling this method will also erase any previously-printed progress information from the CLI screen.
§Examples
use fyi_msg::Progless;
// Initialize with a `u32` total.
let pbar = Progless::try_from(1001_u32).unwrap();
// Iterate your taskwork or whatever.
for i in 0..1001 {
// Do some work.
// ...
// Increment the done count.
pbar.increment();
}
// Finish it off!
pbar.finish();sourcepub fn summary<S>(&self, kind: MsgKind, singular: S, plural: S) -> Msg
pub fn summary<S>(&self, kind: MsgKind, singular: S, plural: S) -> Msg
§Summarize.
Generate a formatted Msg summary of the (finished) progress using
the supplied verb and noun.
If you just want a generic “Finished in X.” message, use Msg::from
instead.
Note: if you called Progless::reset anywhere along the way, this
won’t include totals from the previous run(s). (The duration is the
only constant.)
§Examples
use fyi_msg::{MsgKind, Progless};
// Initialize with a `u32` total.
let pbar = Progless::try_from(1001_u32).unwrap();
// Iterate your taskwork or whatever.
for i in 0..1001 {
// Do some work.
// ...
// Increment the done count.
pbar.increment();
}
pbar.finish();
// Print something like "Crunched X files in Y seconds."
pbar.summary(MsgKind::Crunched, "file", "files").print();source§impl Progless
impl Progless
§Passthrough Setters.
sourcepub fn add<S>(&self, txt: S)
pub fn add<S>(&self, txt: S)
§Add a task.
The progress bar can optionally keep track of tasks that are actively “in progress”, which can be particularly useful when operating in parallel.
Any AsRef<str> value will do. See the module documentation for
example usage.
§Examples
use fyi_msg::Progless;
// Initialize with a `u32` total.
let pbar = Progless::try_from(1001_u32).unwrap();
// Iterate your taskwork or whatever.
for i in 0..1001 {
let task: String = format!("Task #{}.", i);
pbar.add(&task);
// Do some work.
pbar.remove(&task);
}
pbar.finish();sourcepub fn increment(&self)
pub fn increment(&self)
§Increment Done.
Increase the completed count by exactly one. This is safer to use than
set_done() in cases where multiple tasks are happening at once as it
will not accidentally decrease the value, etc.
See the various examples all over this page for more information.
sourcepub fn increment_n(&self, n: u32)
pub fn increment_n(&self, n: u32)
§Increment Done by N.
Increase the completed count by n. This is safer to use than set_done()
and more efficient than calling increment() a million times in a row.
sourcepub fn push_msg<S>(&self, msg: S, stderr: bool)
pub fn push_msg<S>(&self, msg: S, stderr: bool)
§Push Message.
“Insert” (print) a line before the running progress bar, useful for
debug logs, warnings, etc., that would otherwise have to wait for the
Progless instance to finish hogging the display.
Note: This will add a \n to the end of the string.
The message will be printed to STDERR if stderr, otherwise STDOUT.
sourcepub fn remove<S>(&self, txt: S)
pub fn remove<S>(&self, txt: S)
§Remove a task.
This is the equal and opposite companion to Progless::add. Calling
this will automatically increment the done count by one, so should not
be used in cases where you’re triggering done changes manually.
See Progless::add for more details. If you use one, you must use
both.
sourcepub fn reset(&self, total: u32) -> Result<(), ProglessError>
pub fn reset(&self, total: u32) -> Result<(), ProglessError>
§Reset.
Stop the current run (if any), clear the done/doing metrics, and assign
a new total so you can re-use the Progless instance for a new set
of tasks.
Note: the start/elapsed times for a given Progless instance are
continuous. If you need the time counter to reset to [00:00:00],
you need start a brand new instance instead of resetting an existing
one.
§Errors
This will return an error if the new total is zero.
sourcepub fn set_done(&self, done: u32)
pub fn set_done(&self, done: u32)
§Set Done.
Set the done count to a specific value.
In general, you should either use Progless::add/Progless::remove
or Progless::increment rather than this method, as they ensure any
changes made are relative.
This method overrides the done value instead, so can cause regressions if you’re doing task work in parallel and one thread finishes before another, etc.
sourcepub fn set_title<S>(&self, title: Option<S>)
pub fn set_title<S>(&self, title: Option<S>)
§Set Title.
Give the progress bar a title, which will be shown above the progress bits while progress is progressing, and removed afterward with everything else.
See Progless::with_title for more details.
sourcepub fn set_reticulating_splines<S>(&self, app: S)
pub fn set_reticulating_splines<S>(&self, app: S)
§Set Title As X: Reticulating Splines…
This is simply shorthand for generating a “Reticulating Splines…” title, where X is the value passed in (usually the app name).
It’s a sort of default…
sourcepub fn sigint(&self)
pub fn sigint(&self)
§Set SIGINT.
This method is used to indicate that a SIGINT was received and that the tasks are being wound down (early).
For the running Progless, all this really means is that the title
will be changed to “Early shutdown in progress.” (This is purely a
visual thing.)
The caller must still run Progless::finish to close everything up
when the early shutdown actually arrives.