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
33 characters. For long-running jobs, this may be too slow, so two
34 additional features are available: a linear completion time estimator,
35 and/or a minor character: this is a character that moves from left-to-
36 right on the progress bar (it does not fill it as the major character
37 does), traversing once for each major-character added. This
38 exponentially increases the granularity of the bar for the same width.
39
41 A really simple use
42 #!/usr/bin/perl
43 use Term::ProgressBar 2.00;
45 use constant MAX => 100_000;
47 my $progress = Term::ProgressBar->new(MAX);
49 for (0..MAX) {
51 my $is_power = 0;
52 for(my $i = 0; 2**$i <= $_; $i++) {
53 $is_power = 1
54 if 2**$i == $_;
55 }
56 if ( $is_power ) {
58 $progress->update($_);
59 }
60 }
61 Here is a simple example. The process considers all the numbers
63 between 0 and MAX, and updates the progress bar whenever it finds one.
64 Note that the progress bar update will be very erratic. See below for
65 a smoother example. Note also that the progress bar will never
66 complete; see below to solve this.
67 The complete text of this example is in examples/powers in the
69 distribution set (it is not installed as part of the module).
70 A smoother bar update
72 my $progress = Term::ProgressBar->new($max);
73 for (0..$max) {
75 my $is_power = 0;
76 for(my $i = 0; 2**$i <= $_; $i++) {
77 $is_power = 1
78 if 2**$i == $_;
79 }
80 $progress->update($_)
82 }
83 This example calls update for each value considered. This will result
85 in a much smoother progress update, but more program time is spent
86 updating the bar than doing the "real" work. See below to remedy this.
87 This example does not call "$progress->update($max);" at the end, since
88 it is unnecessary, and ProgressBar will throw an exception at an
89 attempt to update a finished bar.
90 The complete text of this example is in examples/powers2 in the
92 distribution set (it is not installed as part of the module.
93 A (much) more efficient update
95 my $progress = Term::ProgressBar->new({name => 'Powers', count => $max, remove => 1});
96 $progress->minor(0);
97 my $next_update = 0;
98 for (0..$max) {
100 my $is_power = 0;
101 for(my $i = 0; 2**$i <= $_; $i++) {
102 $is_power = 1
103 if 2**$i == $_;
104 }
105 $next_update = $progress->update($_)
107 if $_ >= $next_update;
108 }
109 $progress->update($max)
110 if $max >= $next_update;
111 This example does two things to improve efficiency: firstly, it uses
113 the value returned by update to only call it again when needed;
114 secondly, it switches off the use of minor characters to update a lot
115 less frequently ("$progress->minor(0);". The use of the return value
116 of update means that the call of "$progress->update($max);" at the end
117 is required to ensure that the bar ends on 100%, which gives the user a
118 nice feeling.
119 This example also sets the name of the progress bar.
121 This example also demonstrates the use of the 'remove' flag, which
123 removes the progress bar from the terminal when done.
124 The complete text of this example is in examples/powers3 in the
126 distribution set (it is not installed as part of the module.
127 Using Completion Time Estimation
129 my $progress = Term::ProgressBar->new({name => 'Powers',
130 count => $max,
131 ETA => linear, });
132 $progress->max_update_rate(1);
133 my $next_update = 0;
134 for (0..$max) {
136 my $is_power = 0;
137 for(my $i = 0; 2**$i <= $_; $i++) {
138 if ( 2**$i == $_ ) {
139 $is_power = 1;
140 $progress->message(sprintf "Found %8d to be 2 ** %2d", $_, $i);
141 }
142 }
143 $next_update = $progress->update($_)
145 if $_ > $next_update;
146 }
147 $progress->update($max)
148 if $max >= $next_update;
149 This example uses the ETA option to switch on completion estimation.
151 Also, the update return is tuned to try to update the bar approximately
152 once per second, with the max_update_rate call. See the documentation
153 for the new method for details of the format(s) used.
154 This example also provides an example of the use of the message
156 function to output messages to the same filehandle whilst keeping the
157 progress bar intact
158 The complete text of this example is in examples/powers5 in the
160 distribution set (it is not installed as part of the module.
161
164 new
165 Create & return a new Term::ProgressBar instance.
166 ARGUMENTS
168 If one argument is provided, and it is a hashref, then the hash is
169 treated as a set of key/value pairs, with the following keys;
170 otherwise, it is treated as a number, being equivalent to the
171 "count" key.
172 count
174 The item count. The progress is marked at 100% when update
175 count is invoked, and proportionally until then.
176 name
178 A name to prefix the progress bar with.
179 fh The filehandle to output to. Defaults to stderr. Do not try
181 to use *foo{THING} syntax if you want Term capabilities; it
182 does not work. Pass in a globref instead.
183 ETA A total time estimation to use. If enabled, a time finished
185 estimation is printed on the RHS (once sufficient updates have
186 been performed to make such an estimation feasible).
187 Naturally, this is an estimate; no guarantees are made. The
188 format of the estimate
189 Note that the format is intended to be as compact as possible
191 while giving over the relevant information. Depending upon the
192 time remaining, the format is selected to provide some
193 resolution whilst remaining compact. Since the time remaining
194 decreases, the format typically changes over time.
195 As the ETA approaches, the format will state minutes & seconds
197 left. This is identifiable by the word 'Left' at the RHS of
198 the line. If the ETA is further away, then an estimate time of
199 completion (rather than time left) is given, and is
200 identifiable by 'ETA' at the LHS of the ETA box (on the right
201 of the progress bar). A time or date may be presented; these
202 are of the form of a 24 hour clock, e.g. '13:33', a time plus
203 days (e.g., ' 7PM+3' for around in over 3 days time) or a
204 day/date, e.g. ' 1Jan' or '27Feb'.
205 If ETA is switched on, the return value of update is also
207 affected: the idea here is that if the progress bar seems to be
208 moving quicker than the eye would normally care for (and thus a
209 great deal of time is spent doing progress updates rather than
210 "real" work), the next value is increased to slow it. The
211 maximum rate aimed for is tunable via the max_update_rate
212 component.
213 The available values for this are:
215 undef
217 Do not do estimation. The default.
218 linear
220 Perform linear estimation. This is simply that the amount
221 of time between the creation of the progress bar and now is
222 divided by the current amount done, and completion
223 estimated linearly.
224 EXAMPLES
226 my $progress = Term::ProgressBar->new(100); # count from 1 to 100
227 my $progress = Term::ProgressBar->new({ count => 100 }); # same
228 # Count to 200 thingies, outputting to stdout instead of stderr,
230 # prefix bar with 'thingy'
231 my $progress = Term::ProgressBar->new({ count => 200,
232 fh => \*STDOUT,
233 name => 'thingy' });
234
236 Scalar Components.
237 See "get_set" in Class::MethodMaker for usage.
238 target
240 The final target. Updates are measured in terms of this. Changes
241 will have no effect until the next update, but the next update
242 value should be relative to the new target. So
243 $p = Term::ProgressBar({count => 20});
245 # Halfway
246 $p->update(10);
247 # Double scale
248 $p->target(40)
249 $p->update(21);
250 will cause the progress bar to update to 52.5%
252 max_update_rate
254 This value is taken as being the maximum speed between updates to
255 aim for. It is only meaningful if ETA is switched on. It defaults
256 to 0.5, being the number of seconds between updates.
257 Boolean Components
259 See "get_set" in Class::MethodMaker for usage.
260 minor
262 Default: set. If unset, no minor scale will be calculated or
263 updated.
264 Minor characters are used on the progress bar to give the user the
266 idea of progress even when there are so many more tasks than the
267 terminal is wide that the granularity would be too great. By
268 default, Term::ProgressBar makes a guess as to when minor
269 characters would be valuable. However, it may not always guess
270 right, so this method may be called to force it one way or the
271 other. Of course, the efficiency saving is minimal unless the
272 client is utilizing the return value of update.
273 See examples/powers4 and examples/powers3 to see minor characters
275 in action, and not in action, respectively.
276
278 update
279 Update the progress bar.
280 ARGUMENTS
282 so_far
283 Current progress point, in whatever units were passed to "new".
284 If not defined, assumed to be 1+ whatever was the value last
286 time "update" was called (starting at 0).
287 RETURNS
289 next_call
290 The next value of so_far at which to call "update".
291 message
293 Output a message. This is very much like print, but we try not to
294 disturb the terminal.
295 ARGUMENTS
297 string
298 The message to output.
299
302 Email the author.
303
305 If exactly two arguments are provided, then new operates in v1
306 compatibility mode: the arguments are considered to be name, and item
307 count. Various other defaults are set to emulate version one (e.g.,
308 the major output character is '#', the bar width is set to 50
309 characters and the output filehandle is not treated as a terminal).
310 This mode is deprecated.
311
313 Martyn J. Pearce fluffy@cpan.org
314 Significant contributions from Ed Avis, amongst others.
316
318 Copyright (c) 2001, 2002, 2003, 2004, 2005 Martyn J. Pearce. This
319 program is free software; you can redistribute it and/or modify it
320 under the same terms as Perl itself.
321
323perl v5.10.1 2011-10-04 Term::ProgressBar(3)