pub struct Progless { /* private fields */ }
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.
for i in (0..1001).par_iter() {
let task: String = format!("Task #{}.", i);
pbar.add(&task);
// Do some work.
pbar.remove(&task);
}
// ... snip
Implementations
sourceimpl Progless
impl Progless
sourcepub const MAX_TOTAL: usize = 4_294_967_295usize
pub const MAX_TOTAL: usize = 4_294_967_295usize
Max Total.
A Progless
instance cannot have a total higher than this value.
This is technically u32::MAX
, but in practice usize
is used more
often, so this value reflects whichever of the two is smaller.
Regardless, it’s an awful lot of tasks to try to visualize. Haha.
sourcepub const MAX_TOTAL_ERROR: ProglessError = ProglessError::TotalOverflow
pub const MAX_TOTAL_ERROR: ProglessError = ProglessError::TotalOverflow
Total Error.
This is the error message that is returned when a total is too high for
a Progless
instance.
sourceimpl Progless
impl Progless
sourcepub fn with_title<S>(self, title: Option<S>) -> Self where
S: Into<Msg>,
pub fn with_title<S>(self, title: Option<S>) -> Self where
S: Into<Msg>,
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 where
S: AsRef<str>,
pub fn with_reticulating_splines<S>(self, app: S) -> Self where
S: AsRef<str>,
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)
pub fn finish(&self)
Stop.
Finish the progress bar and shut down the steady ticker.
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 where
S: AsRef<str>,
pub fn summary<S>(&self, kind: MsgKind, singular: S, plural: S) -> Msg where
S: AsRef<str>,
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.
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();
sourceimpl Progless
impl Progless
sourcepub fn add<S>(&self, txt: S) where
S: AsRef<str>,
pub fn add<S>(&self, txt: S) where
S: AsRef<str>,
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 remove<S>(&self, txt: S) where
S: AsRef<str>,
pub fn remove<S>(&self, txt: S) where
S: AsRef<str>,
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 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>) where
S: Into<Msg>,
pub fn set_title<S>(&self, title: Option<S>) where
S: Into<Msg>,
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) where
S: AsRef<str>,
pub fn set_reticulating_splines<S>(&self, app: S) where
S: AsRef<str>,
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.
Trait Implementations
sourceimpl From<NonZeroU32> for Progless
impl From<NonZeroU32> for Progless
sourcefn from(total: NonZeroU32) -> Self
fn from(total: NonZeroU32) -> Self
Converts to this type from the input type.
Auto Trait Implementations
impl !RefUnwindSafe for Progless
impl Send for Progless
impl Sync for Progless
impl Unpin for Progless
impl !UnwindSafe for Progless
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more