1Term::ProgressBar(3) User Contributed Perl Documentation Term::ProgressBar(3)
2
6 Term::ProgressBar - provide a progress meter on a standard terminal
7
9 Version 2.23
10
12 use Term::ProgressBar;
13 my $progress = Term::ProgressBar->new ({count => 10_000});
15 $progress->update(5_000);
16
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 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 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 Remember to call the "$progress->update($max_value)" when the job is
32 done to get a nice 100% done bar.
33 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
44 A really simple use
45 #!/usr/bin/perl
46 use Term::ProgressBar 2.00;
48 use constant MAX => 100_000;
49 my $progress = Term::ProgressBar->new(MAX);
51 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 if ($is_power) {
59 $progress->update($_);
60 }
61 }
62 see eg/simle_use.pl
64 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 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 A smoother bar update
75 my $progress = Term::ProgressBar->new($max);
76 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 $progress->update($_)
84 }
85 See eg/smooth_bar.pl
87 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 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 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 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 $next_update = $progress->update($_) if $_ >= $next_update;
110 }
111 $progress->update($max) if $max >= $next_update;
113 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 This example also sets the name of the progress bar.
123 This example also demonstrates the use of the 'remove' flag, which
125 removes the progress bar from the terminal when done.
126 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 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 some_command --arg value | my_script.pl | some_other_command
137 Or ...
139 my_script.pl input_file output_file
141 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 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 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 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 my $progress = Term::ProgressBar->new({
170 name => 'file processor',
171 count => $num_lines,
172 remove => 1,
173 fh => $message_fh,
174 });
175 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 $progress->update($num_lines);
184 print $message_fh "Finished\n";
186 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 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 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 $next_update = $progress->update($_)
211 if $_ > $next_update;
212 }
213 $progress->update($max)
214 if $max >= $next_update;
215 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 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 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
229 new
230 Create & return a new Term::ProgressBar instance.
231 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 count
239 The item count. The progress is marked at 100% when update
240 count is invoked, and proportionally until then.
241 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 name
250 A name to prefix the progress bar with.
251 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 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 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 Instead, tell the constructor you want it to be silent and you
268 don't need to change the rest of your program:
269 my $progress = Term::ProgressBar->new( { count => $count, silent => $silent } );
271 # later
272 $progress->update; # does nothing
273 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 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 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 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 The available values for this are:
305 undef
307 Do not do estimation. The default.
308 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 EXAMPLES
316 my $progress = Term::ProgressBar->new(100); # count from 1 to 100
317 my $progress = Term::ProgressBar->new({ count => 100 }); # same
318 # 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
326 Scalar Components.
327 See "get_set" in Class::MethodMaker for usage.
328 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 $p = Term::ProgressBar({count => 20});
335 # Halfway
336 $p->update(10);
337 # Double scale
338 $p->target(40)
339 $p->update(21);
340 will cause the progress bar to update to 52.5%
342 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 Boolean Components
349 See "get_set" in Class::MethodMaker for usage.
350 minor
352 Default: set. If unset, no minor scale will be calculated or
353 updated.
354 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 See examples/powers4 and examples/powers3 to see minor characters
365 in action, and not in action, respectively.
366 Configuration
368 lbrack
369 Left bracket ( defaults to [ )
370 $progress->lbrack('<');
372 rbrack
374 Right bracket ( defaults to ] )
375 $progress->rbrack('>');
377
379 update
380 Update the progress bar.
381 ARGUMENTS
383 so_far
384 Current progress point, in whatever units were passed to "new".
385 If not defined, assumed to be 1+ whatever was the value last
387 time "update" was called (starting at 0).
388 RETURNS
390 next_call
391 The next value of so_far at which to call "update".
392 message
394 Output a message. This is very much like print, but we try not to
395 disturb the terminal.
396 ARGUMENTS
398 string
399 The message to output.
400
402 via RT: <https://rt.cpan.org/Dist/Display.html?Name=Term-ProgressBar>
403
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
413 Martyn J. Pearce fluffy@cpan.org
414 Significant contributions from Ed Avis, amongst others.
416
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.
424perl v5.36.0 2023-01-20 Term::ProgressBar(3)