1Time::Progress(3) User Contributed Perl Documentation Time::Progress(3)
2
6 Time::Progress - Elapsed and estimated finish time reporting.
7
9 use Time::Progress;
10 my ($min, $max) = (0, 4);
12 my $p = Time::Progress->new(min => $min, max => $max);
13 for (my $c = $min; $c <= $max; $c++) {
15 print STDERR $p->report("\r%20b ETA: %E", $c);
16 # do some work
17 }
18 print STDERR "\n";
19
21 This module displays progress information for long-running processes.
22 This can be percentage complete, time elapsed, estimated time
23 remaining, an ASCII progress bar, or any combination of those.
24 It is useful for code where you perform a number of steps, or
26 iterations of a loop, where the number of iterations is known before
27 you start the loop.
28 The typical usage of this module is:
30 • Create an instance of "Time::Progress", specifying min and max
32 count values.
33 • At the head of the loop, you call the "report()" method with a
35 format specifier and the iteration count, and get back a string
36 that should be displayed.
37 If you include a carriage return character (\r) in the format string,
39 then the message will be over-written at each step. Putting \r at the
40 start of the format string, as in the SYNOPSIS, results in the cursor
41 sitting at the end of the message.
42 If you display to STDOUT, then remember to enable auto-flushing:
44 use IO::Handle;
46 STDOUT->autoflush(1);
47 The shortest time interval that can be measured is 1 second.
49
51 new
52 my $p = Time::Progress->new(%options);
53 Returns new object of Time::Progress class and starts the timer. It
55 also sets min and max values to 0 and 100, so the next report calls
56 will default to percents range.
57 You can configure the instance with the following parameters:
59 min Sets the min attribute, as described in the "attr" section below.
61 max Sets the max attribute, as described in the "attr" section below.
63 smoothing
65 If set to a true value, then the estimated time remaining is
66 smoothed in a simplistic way: if the time remaining ever goes up,
67 by less than 10% of the previous estimate, then we just stick with
68 the previous estimate. This prevents flickering estimates. By
69 default this feature is turned off.
70 smoothing_delta
72 Sets smoothing delta parameter. Default value is 0.1 (i.e. 10%).
73 See 'smoothing' parameter for more details.
74 restart
76 Restarts the timer and clears the stop mark. Optionally restart() may
77 act also as attr() for setting attributes:
78 $p->restart( min => 1, max => 5 );
80 is the same as:
82 $p->attr( min => 1, max => 5 );
84 $p->restart();
85 If you need to count things, you can set just 'max' attribute since
87 'min' is already set to 0 when object is constructed by new():
88 $p->restart( max => 42 );
90 stop
92 Sets the stop mark. This is only useful if you do some work, then
93 finish, then do some work that shouldn't be timed and finally report.
94 Something like:
95 $p->restart;
97 # do some work here...
98 $p->stop;
99 # do some post-work here
100 print $p->report;
101 # `post-work' will not be timed
102 Stop is useless if you want to report time as soon as work is finished
104 like:
105 $p->restart;
107 # do some work here...
108 print $p->report;
109 continue
111 Clears the stop mark. (mostly useless, perhaps you need to restart?)
112 attr
114 Sets and returns internal values for attributes. Available attributes
115 are:
116 min This is the min value of the items that will follow (used to
118 calculate estimated finish time)
119 max This is the max value of all items in the even (also used to
121 calculate estimated finish time)
122 format
124 This is the default report format. It is used if report is called
125 without parameters.
126 attr returns array of the set attributes:
128 my ( $new_min, $new_max ) = $p->attr( min => 1, max => 5 );
130 If you want just to get values use undef:
132 my $old_format = $p->attr( format => undef );
134 This way of handling attributes is a bit heavy but saves a lot of
136 attribute handling functions. attr will complain if you pass odd number
137 of parameters.
138 report
140 This is the most complex method in this package :)
141 The expected arguments are:
143 $p->report( format, [current_item] );
145 format is string that will be used for the result string. Recognized
147 special sequences are:
148 %l elapsed seconds
150 %L elapsed time in minutes in format MM:SS
152 %e remaining seconds
154 %E remaining time in minutes in format MM:SS
156 %p percentage done in format PPP.P%
158 %f estimated finish time in format returned by localtime()
160 %b
162 %B progress bar which looks like:
163 ##############......................
165 %b takes optional width:
167 %40b -- 40-chars wide bar
169 %9b -- 9-chars wide bar
170 %b -- 79-chars wide bar (default)
171 Parameters can be ommited and then default format set with attr will be
173 used.
174 Sequences 'L', 'l', 'E' and 'e' can have width also:
176 %10e
178 %5l
179 ...
180 Estimate time calculations can be used only if min and max values are
182 set (see attr method) and current item is passed to report! if you want
183 to use the default format but still have estimates use it like this:
184 $p->format( undef, 45 );
186 If you don't give current item (step) or didn't set proper min/max
188 value then all estimate sequences will have value `n/a'.
189 You can freely mix reports during the same event.
191 elapsed($item)
193 Returns the time elapsed, in seconds. This help function, and those
194 described below, take one argument: the current item number.
195 estimate($item)
197 Returns an estimate of the time remaining, in seconds.
198 elapsed_str($item)
200 Returns elapsed time as a formatted string:
201 "elapsed time is MM:SS min.\n"
203 estimate_str($item)
205 Returns estimated remaining time, as a formatted string:
206 "remaining time is MM:SS min.\n"
208
210 # $c is current element (step) reached
211 # for the examples: min = 0, max = 100, $c = 33.3
212 print $p->report( "done %p elapsed: %L (%l sec), ETA %E (%e sec)\n", $c );
214 # prints:
215 # done 33.3% elapsed time 0:05 (5 sec), ETA 0:07 (7 sec)
216 print $p->report( "%45b %p\r", $c );
218 # prints:
219 # ###############.............................. 33.3%
220 print $p->report( "done %p ETA %f\n", $c );
222 # prints:
223 # done 33.3% ETA Sun Oct 21 16:50:57 2001
224
226 The first thing you need to know about Smart::Comments is that it was
227 written by Damian Conway, so you should expect to be a little bit
228 freaked out by it. It looks for certain format comments in your code,
229 and uses them to display progress messages. Includes support for
230 progress meters.
231 Progress::Any separates the calculation of stats from the display of
233 those stats, so you can have different back-ends which display progress
234 is different ways. There are a number of separate back-ends on CPAN.
235 Term::ProgressBar displays a progress meter to a standard terminal.
237 Term::ProgressBar::Quiet uses "Term::ProgressBar" if your code is
239 running in a terminal. If not running interactively, then no progress
240 bar is shown.
241 Term::ProgressBar::Simple provides a simple interface where you get a
243 $progress object that you can just increment in a long-running loop.
244 It builds on "Term::ProgressBar::Quiet", so displays nothing when not
245 running interactively.
246 Term::Activity displays a progress meter with timing information, and
248 two different skins.
249 Text::ProgressBar is another customisable progress meter, which comes
251 with a number of 'widgets' for display progress information in
252 different ways.
253 ProgressBar::Stack handles the case where a long-running process has a
255 number of sub-processes, and you want to record progress of those too.
256 String::ProgressBar provides a simple progress bar, which shows
258 progress using a bar of ASCII characters, and the percentage complete.
259 Term::Spinner is simpler than most of the other modules listed here, as
261 it just displays a 'spinner' to the terminal. This is useful if you
262 just want to show that something is happening, but can't predict how
263 many more operations will be required.
264 Term::Pulse shows a pulsed progress bar in your terminal, using a child
266 process to pulse the progress bar until your job is complete.
267 Term::YAP a fork of "Term::Pulse".
269 Term::StatusBar is another progress bar module, but it hasn't seen a
271 release in the last 12 years.
272
274 <https://github.com/cade-vs/perl-time-progress>
275
277 Vladi Belperchinov-Shabanski "Cade"
278 <cade@biscom.net> <cade@datamax.bg> <cade@cpan.org>
280 <http://cade.datamax.bg>
282
284 This software is copyright (c) 2001-2015 by Vladi Belperchinov-
285 Shabanski <cade@cpan.org>.
286 This is free software; you can redistribute it and/or modify it under
288 the same terms as the Perl 5 programming language system itself.
289perl v5.36.0 2022-07-22 Time::Progress(3)