Struct fyi_msg::Progless

source · [−]
pub struct Progless { /* private fields */ }
Available on crate feature 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);
});

// ... snip

Implementations

Constants.

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.

Total Error.

This is the error message that is returned when a total is too high for a Progless instance.

Construction/Destruction.

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();
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…

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();
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();

Passthrough Setters.

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();
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.

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.

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.

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.

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.

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…

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

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Converts to this type from the input type.
Into Msg

This provides a simple way to convert a (finished) Progless instance into a generic summary Msg that can e.g. be printed.

For a more advanced summary, use the Progless::summary method.

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.