|
Term::ProgressBar - provide a progress meter on a standard terminal |
Term::ProgressBar - provide a progress meter on a standard terminal
use Term::ProgressBar;
$progress = Term::ProgressBar->new ({count => $count});
$progress->update ($so_far);
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 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.
#!/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.
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.
my $progress = Term::ProgressBar->new({name => 'Powers', count => $max});
$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.
The complete text of this example is in examples/powers3 in the distribution set (it is not installed as part of the module.
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.
Create & return a new Term::ProgressBar instance.
count key.
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:
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
my $progress = Term::ProgressBar->new({ count => 200,
fh => \*STDOUT });
See get_set in the Class::MethodMaker manpage for usage.
$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%
See get_set in the Class::MethodMaker manpage for usage.
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.
Update the progress bar.
new.
If not defined, assumed to be 1+ whatever was the value last time update
was called (starting at 0).
update.
Output a message. This is very much like print, but we try not to disturb the terminal.
Email the author.
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.
Martyn J. Pearce fluffy@cpan.org
Copyright (c) 2001, 2002, 2003 Martyn J. Pearce. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
|
Term::ProgressBar - provide a progress meter on a standard terminal |