Term::ProgressBar provides a simple progress bar on the terminal, to let the
user know that something is happening, roughly how much stuff has been done,
and maybe an estimate at how long remains.

A typical use sets up the progress bar with a number of items to do, and then
calls update to update the bar whenever an item is processed.

Often, this would involve updating the progress bar many times with no
user-visible change. To avoid unnecessary work, the update method returns a
value, being the update value at which the user will next see a change. By
only calling update when the current value exceeds the next update value, the
call overhead is reduced.

Remember to call the "$progress->update($max_value)" when the job
is done to get a nice 100% done bar.

A progress bar by default is simple; it just goes from left-to-right, filling
the bar with '=' characters. These are called major characters. For
long-running jobs, this may be too slow, so two additional features are
available: a linear completion time estimator, and/or a minor
character: this is a character that moves from left-to-right on the
progress bar (it does not fill it as the major character does), traversing
once for each major-character added. This exponentially increases the
granularity of the bar for the same width.

Here is a simple example. The process considers all the numbers between 0 and
MAX, and updates the progress bar whenever it finds one. Note that the
progress bar update will be very erratic. See below for a smoother example.
Note also that the progress bar will never complete; see below to solve this.

The complete text of this example is in examples/powers in the
distribution set (it is not installed as part of the module).

This example calls update for each value considered. This will result in a much
smoother progress update, but more program time is spent updating the bar than
doing the "real" work. See below to remedy this. This example does
not call "$progress->update($max);" at the end, since it
is unnecessary, and ProgressBar will throw an exception at an attempt to
update a finished bar.

The complete text of this example is in examples/powers2 in the
distribution set (it is not installed as part of the module.

This example does two things to improve efficiency: firstly, it uses the value
returned by update to only call it again when needed; secondly, it switches
off the use of minor characters to update a lot less frequently
("$progress->minor(0);". The use of the return value of update
means that the call of "$progress->update($max);" at the end is
required to ensure that the bar ends on 100%, which gives the user a nice
feeling.

This example also sets the name of the progress bar.

This example also demonstrates the use of the 'remove' flag, which removes the
progress bar from the terminal when done.

The complete text of this example is in examples/powers3 in the
distribution set (it is not installed as part of the module.

Sometimes you may wish to use the progress bar when the number of items may or
may not be known. One common example is when you write a script that can take
input piped from the output of another command, and then pipe the output to
yet another command. eg:

some_command --arg value | my_script.pl | some_other_command

Or ...

my_script.pl input_file output_file

This example shows how you can iterate over a file specified on the command line
with the progress bar. Since the input file may be read from STDIN, the number
of lines may not be known. Term::ProgressBar handles this by just taking '-1'
as the count value and with no further changes to the code. By calling update
with the same count value, you ensure the progress bar is removed afterwards.

When the file is defined explicitly, the progress bar displays the linewise
progress through the file. Since the progress bar by default prints output to
stderr, your scripts output to STDOUT will not be affected.

This example uses the ETA option to switch on completion estimation. Also, the
update return is tuned to try to update the bar approximately once per second,
with the max_update_rate call. See the documentation for the new method for
details of the format(s) used.

This example also provides an example of the use of the message function to
output messages to the same filehandle whilst keeping the progress bar intact

The complete text of this example is in examples/powers5 in the
distribution set (it is not installed as part of the module.

If one argument is provided, and it is a hashref, then the hash is treated
as a set of key/value pairs, with the following keys; otherwise, it is
treated as a number, being equivalent to the "count" key.

count

The item count. The progress is marked at 100% when update count is
invoked, and proportionally until then.

If you specify a count less than zero, just the name (if specified) will be
displayed and (if the remove flag is set) removed when the progress bar is
updated with a number lower than zero. This allows you to use the progress
bar when the count is sometimes known and sometimes not without making
multiple changes throughout your code.

name

A name to prefix the progress bar with.

fh

The filehandle to output to. Defaults to stderr. Do not try to use
*foo{THING} syntax if you want Term capabilities; it does not work. Pass
in a globref instead.

term_width

Sometimes we can't correctly determine the terminal width. You can use
this parameter to force a term width of a particular size. Use a positive
integer, please :)

silent

If passed a true value, Term::ProgressBar will do nothing at all. Useful
in scripts where the progress bar is optional (or just plain doesn't work
due to issues with modules it relies on).

Instead, tell the constructor you want it to be silent and you don't need to
change the rest of your program:

A total time estimation to use. If enabled, a time finished estimation is
printed on the RHS (once sufficient updates have been performed to make
such an estimation feasible). Naturally, this is an estimate; no
guarantees are made. The format of the estimate

Note that the format is intended to be as compact as possible while giving
over the relevant information. Depending upon the time remaining, the
format is selected to provide some resolution whilst remaining compact.
Since the time remaining decreases, the format typically changes over
time.

As the ETA approaches, the format will state minutes & seconds left.
This is identifiable by the word 'Left' at the RHS of the line. If the ETA
is further away, then an estimate time of completion (rather than time
left) is given, and is identifiable by 'ETA' at the LHS of the ETA box (on
the right of the progress bar). A time or date may be presented; these are
of the form of a 24 hour clock, e.g. '13:33', a time plus days (e.g., '
7PM+3' for around in over 3 days time) or a day/date, e.g. ' 1Jan' or
'27Feb'.

If ETA is switched on, the return value of update is also affected: the idea
here is that if the progress bar seems to be moving quicker than the eye
would normally care for (and thus a great deal of time is spent doing
progress updates rather than "real" work), the next value is
increased to slow it. The maximum rate aimed for is tunable via the
max_update_rate component.

The available values for this are:

undef

Do not do estimation. The default.

linear

Perform linear estimation. This is simply that the amount of time between
the creation of the progress bar and now is divided by the current amount
done, and completion estimated linearly.

Minor characters are used on the progress bar to give the user the idea of
progress even when there are so many more tasks than the terminal is wide
that the granularity would be too great. By default, Term::ProgressBar
makes a guess as to when minor characters would be valuable. However, it
may not always guess right, so this method may be called to force it one
way or the other. Of course, the efficiency saving is minimal unless the
client is utilizing the return value of update.

See examples/powers4 and examples/powers3 to see minor
characters in action, and not in action, respectively.

If exactly two arguments are provided, then new operates in v1 compatibility
mode: the arguments are considered to be name, and item count. Various other
defaults are set to emulate version one (e.g., the major output character is
'#', the bar width is set to 50 characters and the output filehandle is not
treated as a terminal). This mode is deprecated.