1Term::ProgressBar(3) User Contributed Perl Documentation Term::ProgressBar(3)
2
6 Term::ProgressBar - provide a progress meter on a standard terminal
7
9 use Term::ProgressBar;
10 $progress = Term::ProgressBar->new ({count => $count});
12 $progress->update ($so_far);
13
15 Term::ProgressBar provides a simple progress bar on the terminal, to
16 let the user know that something is happening, roughly how much stuff
17 has been done, and maybe an estimate at how long remains.
18 A typical use sets up the progress bar with a number of items to do,
20 and then calls update to update the bar whenever an item is processed.
21 Often, this would involve updating the progress bar many times with no
23 user-visible change. To avoid uneccessary work, the update method
24 returns a value, being the update value at which the user will next see
25 a change. By only calling update when the current value exceeds the
26 next update value, the call overhead is reduced.
27 Remember to call the "$progress->update($max_value)" when the job is
29 done to get a nice 100% done bar.
30 A progress bar by default is simple; it just goes from left-to-right,
32 filling the bar with '=' characters. These are called major charac‐
33 ters. For long-running jobs, this may be too slow, so two additional
34 features are available: a linear completion time estimator, and/or a
35 minor character: this is a character that moves from left-to-right on
36 the progress bar (it does not fill it as the major character does),
37 traversing once for each major-character added. This exponentially
38 increases the granularity of the bar for the same width.
39
41 A really simple use
42 #!/usr/bin/perl
44 use Term::ProgressBar 2.00;
46 use constant MAX => 100_000;
48 my $progress = Term::ProgressBar->new(MAX);
50 for (0..MAX) {
52 my $is_power = 0;
53 for(my $i = 0; 2**$i <= $_; $i++) {
54 $is_power = 1
55 if 2**$i == $_;
56 }
57 if ( $is_power ) {
59 $progress->update($_);
60 }
61 }
62 Here is a simple example. The process considers all the numbers
64 between 0 and MAX, and updates the progress bar whenever it finds one.
65 Note that the progress bar update will be very erratic. See below for
66 a smoother example. Note also that the progress bar will never com‐
67 plete; see below to solve this.
68 The complete text of this example is in examples/powers in the distri‐
70 bution set (it is not installed as part of the module).
71 A smoother bar update
73 my $progress = Term::ProgressBar->new($max);
75 for (0..$max) {
77 my $is_power = 0;
78 for(my $i = 0; 2**$i <= $_; $i++) {
79 $is_power = 1
80 if 2**$i == $_;
81 }
82 $progress->update($_)
84 }
85 This example calls update for each value considered. This will result
87 in a much smoother progress update, but more program time is spent
88 updating the bar than doing the "real" work. See below to remedy this.
89 This example does not call "$progress->update($max);" at the end, since
90 it is unnecessary, and ProgressBar will throw an exception at an
91 attempt to update a finished bar.
92 The complete text of this example is in examples/powers2 in the distri‐
94 bution set (it is not installed as part of the module.
95 A (much) more efficient update
97 my $progress = Term::ProgressBar->new({name => 'Powers', count => $max, remove => 1});
99 $progress->minor(0);
100 my $next_update = 0;
101 for (0..$max) {
103 my $is_power = 0;
104 for(my $i = 0; 2**$i <= $_; $i++) {
105 $is_power = 1
106 if 2**$i == $_;
107 }
108 $next_update = $progress->update($_)
110 if $_ >= $next_update;
111 }
112 $progress->update($max)
113 if $max >= $next_update;
114 This example does two things to improve efficiency: firstly, it uses
116 the value returned by update to only call it again when needed; sec‐
117 ondly, it switches off the use of minor characters to update a lot less
118 frequently ("$progress->minor(0);". The use of the return value of
119 update means that the call of "$progress->update($max);" at the end is
120 required to ensure that the bar ends on 100%, which gives the user a
121 nice feeling.
122 This example also sets the name of the progress bar.
124 This example also demonstrates the use of the 'remove' flag, which
126 removes the progress bar from the terminal when done.
127 The complete text of this example is in examples/powers3 in the distri‐
129 bution set (it is not installed as part of the module.
130 Using Completion Time Estimation
132 my $progress = Term::ProgressBar->new({name => 'Powers',
134 count => $max,
135 ETA => linear, });
136 $progress->max_update_rate(1);
137 my $next_update = 0;
138 for (0..$max) {
140 my $is_power = 0;
141 for(my $i = 0; 2**$i <= $_; $i++) {
142 if ( 2**$i == $_ ) {
143 $is_power = 1;
144 $progress->message(sprintf "Found %8d to be 2 ** %2d", $_, $i);
145 }
146 }
147 $next_update = $progress->update($_)
149 if $_ > $next_update;
150 }
151 $progress->update($max)
152 if $max >= $next_update;
153 This example uses the ETA option to switch on completion estimation.
155 Also, the update return is tuned to try to update the bar approximately
156 once per second, with the max_update_rate call. See the documentation
157 for the new method for details of the format(s) used.
158 This example also provides an example of the use of the message func‐
160 tion to output messages to the same filehandle whilst keeping the
161 progress bar intact
162 The complete text of this example is in examples/powers5 in the distri‐
164 bution set (it is not installed as part of the module.
165
167
170 new
173 Create & return a new Term::ProgressBar instance.
175 ARGUMENTS
177 If one argument is provided, and it is a hashref, then the hash is
178 treated as a set of key/value pairs, with the following keys; oth‐
179 erwise, it is treated as a number, being equivalent to the "count"
180 key.
181 count
183 The item count. The progress is marked at 100% when update
184 count is invoked, and proportionally until then.
185 name
187 A name to prefix the progress bar with.
188 fh The filehandle to output to. Defaults to stderr. Do not try
190 to use *foo{THING} syntax if you want Term capabilities; it
191 does not work. Pass in a globref instead.
192 ETA A total time estimation to use. If enabled, a time finished
194 estimation is printed on the RHS (once sufficient updates have
195 been performed to make such an estimation feasible). Natu‐
196 rally, this is an estimate; no guarantees are made. The format
197 of the estimate
198 Note that the format is intended to be as compact as possible
200 while giving over the relevant information. Depending upon the
201 time remaining, the format is selected to provide some resolu‐
202 tion whilst remaining compact. Since the time remaining
203 decreases, the format typically changes over time.
204 As the ETA approaches, the format will state minutes & seconds
206 left. This is identifiable by the word 'Left' at the RHS of
207 the line. If the ETA is further away, then an estimate time of
208 completion (rather than time left) is given, and is identifi‐
209 able by 'ETA' at the LHS of the ETA box (on the right of the
210 progress bar). A time or date may be presented; these are of
211 the form of a 24 hour clock, e.g. '13:33', a time plus days
212 (e.g., ' 7PM+3' for around in over 3 days time) or a day/date,
213 e.g. ' 1Jan' or '27Feb'.
214 If ETA is switched on, the return value of update is also
216 affected: the idea here is that if the progress bar seems to be
217 moving quicker than the eye would normally care for (and thus a
218 great deal of time is spent doing progress updates rather than
219 "real" work), the next value is increased to slow it. The max‐
220 imum rate aimed for is tunable via the max_update_rate compo‐
221 nent.
222 The available values for this are:
224 undef
226 Do not do estimation. The default.
227 linear
229 Perform linear estimation. This is simply that the amount
230 of time between the creation of the progress bar and now is
231 divided by the current amount done, and completion esti‐
232 mated linearly.
233 EXAMPLES
235 my $progress = Term::ProgressBar->new(100); # count from 1 to 100
236 my $progress = Term::ProgressBar->new({ count => 100 }); # same
237 # Count to 200 thingies, outputting to stdout instead of stderr,
239 # prefix bar with 'thingy'
240 my $progress = Term::ProgressBar->new({ count => 200,
241 fh => \*STDOUT,
242 name => 'thingy' });
243
245 Scalar Components.
246 See "get_set" in Class::MethodMaker for usage.
248 target
250 The final target. Updates are measured in terms of this. Changes
251 will have no effect until the next update, but the next update
252 value should be relative to the new target. So
253 $p = Term::ProgressBar({count => 20});
255 # Halfway
256 $p->update(10);
257 # Double scale
258 $p->target(40)
259 $p->update(21);
260 will cause the progress bar to update to 52.5%
262 max_update_rate
264 This value is taken as being the maximum speed between updates to
265 aim for. It is only meaningful if ETA is switched on. It defaults
266 to 0.5, being the number of seconds between updates.
267 Boolean Components
269 See "get_set" in Class::MethodMaker for usage.
271 minor
273 Default: set. If unset, no minor scale will be calculated or
274 updated.
275 Minor characters are used on the progress bar to give the user the
277 idea of progress even when there are so many more tasks than the
278 terminal is wide that the granularity would be too great. By
279 default, Term::ProgressBar makes a guess as to when minor charac‐
280 ters would be valuable. However, it may not always guess right, so
281 this method may be called to force it one way or the other. Of
282 course, the efficiency saving is minimal unless the client is uti‐
283 lizing the return value of update.
284 See examples/powers4 and examples/powers3 to see minor characters
286 in action, and not in action, respectively.
287
289 update
292 Update the progress bar.
294 ARGUMENTS
296 so_far
297 Current progress point, in whatever units were passed to "new".
298 If not defined, assumed to be 1+ whatever was the value last
300 time "update" was called (starting at 0).
301 RETURNS
303 next_call
304 The next value of so_far at which to call "update".
305 message
307 Output a message. This is very much like print, but we try not to dis‐
309 turb the terminal.
310 ARGUMENTS
312 string
313 The message to output.
314
316
319 Email the author.
320
322 If exactly two arguments are provided, then new operates in v1 compati‐
323 bility mode: the arguments are considered to be name, and item count.
324 Various other defaults are set to emulate version one (e.g., the major
325 output character is '#', the bar width is set to 50 characters and the
326 output filehandle is not treated as a terminal). This mode is depre‐
327 cated.
328
330 Martyn J. Pearce fluffy@cpan.org
331 Significant contributions from Ed Avis, amongst others.
333
335 Copyright (c) 2001, 2002, 2003, 2004, 2005 Martyn J. Pearce. This pro‐
336 gram is free software; you can redistribute it and/or modify it under
337 the same terms as Perl itself.
338
340perl v5.8.8 2006-09-19 Term::ProgressBar(3)