Term::ProgressBar(3) User Contributed Perl Documentation Term::ProgressBar(3)NAMETerm::ProgressBar - provide a progress meter on a standard terminal
SYNOPSIS
use Term::ProgressBar;
$progress = Term::ProgressBar->new ({count => $count});
$progress->update ($so_far);
DESCRIPTIONTerm::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 uneccessary 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.
EXAMPLES
A really simple use
#!/usr/bin/perl
use Term::ProgressBar 2.00;
use constant MAX => 100_000;
my $progress = Term::ProgressBar->new(MAX);
for (0..MAX) {
my $is_power = 0;
for(my $i = 0; 2**$i <= $_; $i++) {
$is_power = 1
if 2**$i == $_;
}
if ( $is_power ) {
$progress->update($_);
}
}
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).
A smoother bar update
my $progress = Term::ProgressBar->new($max);
for (0..$max) {
my $is_power = 0;
for(my $i = 0; 2**$i <= $_; $i++) {
$is_power = 1
if 2**$i == $_;
}
$progress->update($_)
}
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.
A (much) more efficient update
my $progress = Term::ProgressBar->new({name => 'Powers', count => $max, remove => 1});
$progress->minor(0);
my $next_update = 0;
for (0..$max) {
my $is_power = 0;
for(my $i = 0; 2**$i <= $_; $i++) {
$is_power = 1
if 2**$i == $_;
}
$next_update = $progress->update($_)
if $_ >= $next_update;
}
$progress->update($max)
if $max >= $next_update;
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.
Using Completion Time Estimation
my $progress = Term::ProgressBar->new({name => 'Powers',
count => $max,
ETA => linear, });
$progress->max_update_rate(1);
my $next_update = 0;
for (0..$max) {
my $is_power = 0;
for(my $i = 0; 2**$i <= $_; $i++) {
if ( 2**$i == $_ ) {
$is_power = 1;
$progress->message(sprintf "Found %8d to be 2 ** %2d", $_, $i);
}
}
$next_update = $progress->update($_)
if $_ > $next_update;
}
$progress->update($max)
if $max >= $next_update;
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.
CLASS CONSTANTSINSTANCE CONSTRUCTION
new
Create & return a new Term::ProgressBar instance.
ARGUMENTS
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.
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.
ETA 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.
EXAMPLES
my $progress = Term::ProgressBar->new(100); # count from 1 to 100
my $progress = Term::ProgressBar->new({ count => 100 }); # same
# Count to 200 thingies, outputting to stdout instead of stderr,
# prefix bar with 'thingy'
my $progress = Term::ProgressBar->new({ count => 200,
fh => \*STDOUT,
name => 'thingy' });
INSTANCE COMPONENTS
Scalar Components.
See "get_set" in Class::MethodMaker for usage.
target
The final target. Updates are measured in terms of this. Changes
will have no effect until the next update, but the next update
value should be relative to the new target. So
$p = Term::ProgressBar({count => 20});
# Halfway
$p->update(10);
# Double scale
$p->target(40)
$p->update(21);
will cause the progress bar to update to 52.5%
max_update_rate
This value is taken as being the maximum speed between updates to
aim for. It is only meaningful if ETA is switched on. It defaults
to 0.5, being the number of seconds between updates.
Boolean Components
See "get_set" in Class::MethodMaker for usage.
minor
Default: set. If unset, no minor scale will be calculated or
updated.
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.
INSTANCE HIGHER-LEVEL PROCEDURES
update
Update the progress bar.
ARGUMENTS
so_far
Current progress point, in whatever units were passed to "new".
If not defined, assumed to be 1+ whatever was the value last
time "update" was called (starting at 0).
RETURNS
next_call
The next value of so_far at which to call "update".
message
Output a message. This is very much like print, but we try not to
disturb the terminal.
ARGUMENTS
string
The message to output.
BUGSREPORTING BUGS
Email the author.
COMPATIBILITY
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.
AUTHOR
Martyn J. Pearce fluffy@cpan.org
Significant contributions from Ed Avis, amongst others.
COPYRIGHT
Copyright (c) 2001, 2002, 2003, 2004, 2005 Martyn J. Pearce. This
program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSOperl v5.14.1 2011-06-24 Term::ProgressBar(3)
