1Term::ProgressBar(3)  User Contributed Perl Documentation Term::ProgressBar(3)
2
3
4

NAME

6       Term::ProgressBar - provide a progress meter on a standard terminal
7

VERSION

9       Version 2.23
10

SYNOPSIS

12           use Term::ProgressBar;
13
14           my $progress = Term::ProgressBar->new ({count => 10_000});
15           $progress->update(5_000);
16

DESCRIPTION

18       Term::ProgressBar provides a simple progress bar on the terminal, to
19       let the user know that something is happening, roughly how much stuff
20       has been done, and maybe an estimate at how long remains.
21
22       A typical use sets up the progress bar with a number of items to do,
23       and then calls update to update the bar whenever an item is processed.
24
25       Often, this would involve updating the progress bar many times with no
26       user-visible change.  To avoid unnecessary work, the update method
27       returns a value, being the update value at which the user will next see
28       a change.  By only calling update when the current value exceeds the
29       next update value, the call overhead is reduced.
30
31       Remember to call the "$progress->update($max_value)" when the job is
32       done to get a nice 100% done bar.
33
34       A progress bar by default is simple; it just goes from left-to-right,
35       filling the bar with '=' characters.  These are called major
36       characters.  For long-running jobs, this may be too slow, so two
37       additional features are available: a linear completion time estimator,
38       and/or a minor character: this is a character that moves from left-to-
39       right on the progress bar (it does not fill it as the major character
40       does), traversing once for each major-character added.  This
41       exponentially increases the granularity of the bar for the same width.
42

EXAMPLES

44   A really simple use
45           #!/usr/bin/perl
46
47           use Term::ProgressBar 2.00;
48           use constant MAX => 100_000;
49
50           my $progress = Term::ProgressBar->new(MAX);
51
52           for (0..MAX) {
53               my $is_power = 0;
54               for (my $i = 0; 2**$i <= $_; $i++) {
55                   $is_power = 1 if 2**$i == $_;
56               }
57
58               if ($is_power) {
59                   $progress->update($_);
60               }
61           }
62
63       see eg/simle_use.pl
64
65       Here is a simple example.  The process considers all the numbers
66       between 0 and MAX, and updates the progress bar whenever it finds one.
67       Note that the progress bar update will be very erratic.  See below for
68       a smoother example.  Note also that the progress bar will never
69       complete; see below to solve this.
70
71       The complete text of this example is in examples/powers in the
72       distribution set (it is not installed as part of the module).
73
74   A smoother bar update
75           my $progress = Term::ProgressBar->new($max);
76
77           for (0..$max) {
78               my $is_power = 0;
79               for (my $i = 0; 2**$i <= $_; $i++) {
80                   $is_power = 1 if 2**$i == $_;
81               }
82
83               $progress->update($_)
84           }
85
86       See eg/smooth_bar.pl
87
88       This example calls update for each value considered.  This will result
89       in a much smoother progress update, but more program time is spent
90       updating the bar than doing the "real" work.  See below to remedy this.
91       This example does not call "$progress->update($max);" at the end, since
92       it is unnecessary, and ProgressBar will throw an exception at an
93       attempt to update a finished bar.
94
95       The complete text of this example is in examples/powers2 in the
96       distribution set (it is not installed as part of the module.
97
98   A (much) more efficient update
99           my $progress = Term::ProgressBar->new({name => 'Powers', count => $max, remove => 1});
100           $progress->minor(0);
101           my $next_update = 0;
102
103           for (0..$max) {
104               my $is_power = 0;
105               for (my $i = 0; 2**$i <= $_; $i++) {
106                   $is_power = 1 if 2**$i == $_;
107               }
108
109               $next_update = $progress->update($_) if $_ >= $next_update;
110           }
111
112           $progress->update($max) if $max >= $next_update;
113
114       This example does two things to improve efficiency: firstly, it uses
115       the value returned by update to only call it again when needed;
116       secondly, it switches off the use of minor characters to update a lot
117       less frequently ("$progress->minor(0);".  The use of the return value
118       of update means that the call of "$progress->update($max);" at the end
119       is required to ensure that the bar ends on 100%, which gives the user a
120       nice feeling.
121
122       This example also sets the name of the progress bar.
123
124       This example also demonstrates the use of the 'remove' flag, which
125       removes the progress bar from the terminal when done.
126
127       The complete text of this example is in examples/powers3 in the
128       distribution set (it is not installed as part of the module.
129
130   When the maximum number of items is sometimes unknown
131       Sometimes you may wish to use the progress bar when the number of items
132       may or may not be known. One common example is when you write a script
133       that can take input piped from the output of another command, and then
134       pipe the output to yet another command. eg:
135
136         some_command --arg value | my_script.pl | some_other_command
137
138       Or ...
139
140         my_script.pl input_file output_file
141
142       This example shows how you can iterate over a file specified on the
143       command line with the progress bar. Since the input file may be read
144       from STDIN, the number of lines may not be known. Term::ProgressBar
145       handles this by just taking '-1' as the count value and with no further
146       changes to the code. By calling update with the same count value, you
147       ensure the progress bar is removed afterwards.
148
149           my $input_file = shift;
150           my $output_file = shift;
151           my $in_fh = \*STDIN;
152           my $out_fh = \*STDOUT;
153           my $message_fh = \*STDERR;
154           my $num_lines = -1;
155
156           if (defined($input_file) and $input_file ne '-') {
157               open($in_fh, $input_file) or die "Couldn't open file, '$input_file': $!";
158               my $wc_output = `wc -l $input_file`;
159               chomp($wc_output);
160               $wc_output =~ /^\s*(\d+)(\D.*)?/ or die "Couldn't parse wc output: $wc_output";
161               $num_lines = $1;
162           }
163
164           if(defined($output_file)) {
165               !-f $output_file or die "Specified output file, '$output_file', already exists";
166               open($out_fh, '>', $output_file) or die "Couldn't open output file, '$output_file': $!";
167           }
168
169           my $progress = Term::ProgressBar->new({
170               name   => 'file processor',
171               count  => $num_lines,
172               remove => 1,
173               fh     => $message_fh,
174           });
175
176           while (my $line = <$in_fh>) {
177               chomp($line);
178               print $out_fh "I found a line: $line\n";
179               $progress->message("Found 10000!") if($line =~ /10000/);
180               $progress->update();
181           }
182
183           $progress->update($num_lines);
184
185           print $message_fh "Finished\n";
186
187       When the file is defined explicitly, the progress bar displays the
188       linewise progress through the file. Since the progress bar by default
189       prints output to stderr, your scripts output to STDOUT will not be
190       affected.
191
192   Using Completion Time Estimation
193           my $progress = Term::ProgressBar->new({
194               name  => 'Powers',
195               count => $max,
196               ETA   => 'linear',
197           });
198           $progress->max_update_rate(1);
199           my $next_update = 0;
200
201           for (0..$max) {
202               my $is_power = 0;
203               for (my $i = 0; 2**$i <= $_; $i++) {
204               if ( 2**$i == $_ ) {
205                   $is_power = 1;
206                   $progress->message(sprintf "Found %8d to be 2 ** %2d", $_, $i);
207               }
208           }
209
210           $next_update = $progress->update($_)
211             if $_ > $next_update;
212         }
213         $progress->update($max)
214             if $max >= $next_update;
215
216       This example uses the ETA option to switch on completion estimation.
217       Also, the update return is tuned to try to update the bar approximately
218       once per second, with the max_update_rate call.  See the documentation
219       for the new method for details of the format(s) used.
220
221       This example also provides an example of the use of the message
222       function to output messages to the same filehandle whilst keeping the
223       progress bar intact
224
225       The complete text of this example is in examples/powers5 in the
226       distribution set (it is not installed as part of the module.
227

INSTANCE CONSTRUCTION

229   new
230       Create & return a new Term::ProgressBar instance.
231
232       ARGUMENTS
233           If one argument is provided, and it is a hashref, then the hash is
234           treated as a set of key/value pairs, with the following keys;
235           otherwise, it is treated as a number, being equivalent to the
236           "count" key.
237
238           count
239               The item count.  The progress is marked at 100% when update
240               count is invoked, and proportionally until then.
241
242               If you specify a count less than zero, just the name (if
243               specified) will be displayed and (if the remove flag is set)
244               removed when the progress bar is updated with a number lower
245               than zero. This allows you to use the progress bar when the
246               count is sometimes known and sometimes not without making
247               multiple changes throughout your code.
248
249           name
250               A name to prefix the progress bar with.
251
252           fh  The filehandle to output to.  Defaults to stderr.  Do not try
253               to use *foo{THING} syntax if you want Term capabilities; it
254               does not work.  Pass in a globref instead.
255
256           term_width
257               Sometimes we can't correctly determine the terminal width. You
258               can use this parameter to force a term width of a particular
259               size. Use a positive integer, please :)
260
261           silent
262               If passed a true value, Term::ProgressBar will do nothing at
263               all. Useful in scripts where the progress bar is optional (or
264               just plain doesn't work due to issues with modules it relies
265               on).
266
267               Instead, tell the constructor you want it to be silent and you
268               don't need to change the rest of your program:
269
270                   my $progress = Term::ProgressBar->new( { count => $count, silent => $silent } );
271                   # later
272                   $progress->update; # does nothing
273
274           ETA A total time estimation to use.  If enabled, a time finished
275               estimation is printed on the RHS (once sufficient updates have
276               been performed to make such an estimation feasible).
277               Naturally, this is an estimate; no guarantees are made.  The
278               format of the estimate
279
280               Note that the format is intended to be as compact as possible
281               while giving over the relevant information.  Depending upon the
282               time remaining, the format is selected to provide some
283               resolution whilst remaining compact.  Since the time remaining
284               decreases, the format typically changes over time.
285
286               As the ETA approaches, the format will state minutes & seconds
287               left.  This is identifiable by the word 'Left' at the RHS of
288               the line.  If the ETA is further away, then an estimate time of
289               completion (rather than time left) is given, and is
290               identifiable by 'ETA' at the LHS of the ETA box (on the right
291               of the progress bar).  A time or date may be presented; these
292               are of the form of a 24 hour clock, e.g. '13:33', a time plus
293               days (e.g., ' 7PM+3' for around in over 3 days time) or a
294               day/date, e.g. ' 1Jan' or '27Feb'.
295
296               If ETA is switched on, the return value of update is also
297               affected: the idea here is that if the progress bar seems to be
298               moving quicker than the eye would normally care for (and thus a
299               great deal of time is spent doing progress updates rather than
300               "real" work), the next value is increased to slow it.  The
301               maximum rate aimed for is tunable via the max_update_rate
302               component.
303
304               The available values for this are:
305
306               undef
307                   Do not do estimation.  The default.
308
309               linear
310                   Perform linear estimation.  This is simply that the amount
311                   of time between the creation of the progress bar and now is
312                   divided by the current amount done, and completion
313                   estimated linearly.
314
315       EXAMPLES
316             my $progress = Term::ProgressBar->new(100); # count from 1 to 100
317             my $progress = Term::ProgressBar->new({ count => 100 }); # same
318
319             # Count to 200 thingies, outputting to stdout instead of stderr,
320             # prefix bar with 'thingy'
321             my $progress = Term::ProgressBar->new({ count => 200,
322                                                     fh    => \*STDOUT,
323                                                     name  => 'thingy' });
324

INSTANCE COMPONENTS

326   Scalar Components.
327       See "get_set" in Class::MethodMaker for usage.
328
329       target
330           The final target.  Updates are measured in terms of this.  Changes
331           will have no effect until the next update, but the next update
332           value should be relative to the new target.  So
333
334             $p = Term::ProgressBar({count => 20});
335             # Halfway
336             $p->update(10);
337             # Double scale
338             $p->target(40)
339             $p->update(21);
340
341           will cause the progress bar to update to 52.5%
342
343       max_update_rate
344           This value is taken as being the maximum speed between updates to
345           aim for.  It is only meaningful if ETA is switched on. It defaults
346           to 0.5, being the number of seconds between updates.
347
348   Boolean Components
349       See "get_set" in Class::MethodMaker for usage.
350
351       minor
352           Default: set.  If unset, no minor scale will be calculated or
353           updated.
354
355           Minor characters are used on the progress bar to give the user the
356           idea of progress even when there are so many more tasks than the
357           terminal is wide that the granularity would be too great.  By
358           default, Term::ProgressBar makes a guess as to when minor
359           characters would be valuable.  However, it may not always guess
360           right, so this method may be called to force it one way or the
361           other.  Of course, the efficiency saving is minimal unless the
362           client is utilizing the return value of update.
363
364           See examples/powers4 and examples/powers3 to see minor characters
365           in action, and not in action, respectively.
366
367   Configuration
368       lbrack
369           Left bracket ( defaults to [ )
370
371            $progress->lbrack('<');
372
373       rbrack
374           Right bracket ( defaults to ] )
375
376            $progress->rbrack('>');
377

INSTANCE HIGHER-LEVEL PROCEDURES

379   update
380       Update the progress bar.
381
382       ARGUMENTS
383           so_far
384               Current progress point, in whatever units were passed to "new".
385
386               If not defined, assumed to be 1+ whatever was the value last
387               time "update" was called (starting at 0).
388
389       RETURNS
390           next_call
391               The next value of so_far at which to call "update".
392
393   message
394       Output a message.  This is very much like print, but we try not to
395       disturb the terminal.
396
397       ARGUMENTS
398           string
399               The message to output.
400

REPORTING BUGS

402       via RT: <https://rt.cpan.org/Dist/Display.html?Name=Term-ProgressBar>
403

COMPATIBILITY

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

AUTHOR

413       Martyn J. Pearce fluffy@cpan.org
414
415       Significant contributions from Ed Avis, amongst others.
416

MAINTAINER

418       Gabor Szabo <http://szabgab.com/> <http://perlmaven.com/>
419
421       Copyright (c) 2001, 2002, 2003, 2004, 2005 Martyn J. Pearce.  This
422       program is free software; you can redistribute it and/or modify it
423       under the same terms as Perl itself.
424
425
426
427perl v5.36.0                      2023-01-20              Term::ProgressBar(3)
Impressum