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 format
35 specifier and the iteration count, and get back a string that
36 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 %s current speed in items per second
173 %S current min/max speeds (calculated after first 1% of the progress)
175 Parameters can be omitted and then default format set with attr will be
177 used.
178 Sequences 'L', 'l', 'E' and 'e' can have width also:
180 %10e
182 %5l
183 ...
184 Estimate time calculations can be used only if min and max values are
186 set (see attr method) and current item is passed to report! if you want
187 to use the default format but still have estimates use it like this:
188 $p->format( undef, 45 );
190 If you don't give current item (step) or didn't set proper min/max
192 value then all estimate sequences will have value `n/a'.
193 You can freely mix reports during the same event.
195 elapsed($item)
197 Returns the time elapsed, in seconds. This help function, and those
198 described below, take one argument: the current item number.
199 estimate($item)
201 Returns an estimate of the time remaining, in seconds.
202 elapsed_str($item)
204 Returns elapsed time as a formatted string:
205 "elapsed time is MM:SS min.\n"
207 estimate_str($item)
209 Returns estimated remaining time, as a formatted string:
210 "remaining time is MM:SS min.\n"
212
214 # $c is current element (step) reached
215 # for the examples: min = 0, max = 100, $c = 33.3
216 print $p->report( "done %p elapsed: %L (%l sec), ETA %E (%e sec)\n", $c );
218 # prints:
219 # done 33.3% elapsed time 0:05 (5 sec), ETA 0:07 (7 sec)
220 print $p->report( "%45b %p\r", $c );
222 # prints:
223 # ###############.............................. 33.3%
224 print $p->report( "done %p ETA %f\n", $c );
226 # prints:
227 # done 33.3% ETA Sun Oct 21 16:50:57 2001
228 print $p->report( "%30b %p %s/sec (%S) %L ETA: %E" );
230 # .............................. 0.7% 924/sec (938/951) 1:13 ETA: 173:35
231
233 The first thing you need to know about Smart::Comments is that it was
234 written by Damian Conway, so you should expect to be a little bit
235 freaked out by it. It looks for certain format comments in your code,
236 and uses them to display progress messages. Includes support for
237 progress meters.
238 Progress::Any separates the calculation of stats from the display of
240 those stats, so you can have different back-ends which display progress
241 is different ways. There are a number of separate back-ends on CPAN.
242 Term::ProgressBar displays a progress meter to a standard terminal.
244 Term::ProgressBar::Quiet uses "Term::ProgressBar" if your code is
246 running in a terminal. If not running interactively, then no progress
247 bar is shown.
248 Term::ProgressBar::Simple provides a simple interface where you get a
250 $progress object that you can just increment in a long-running loop.
251 It builds on "Term::ProgressBar::Quiet", so displays nothing when not
252 running interactively.
253 Term::Activity displays a progress meter with timing information, and
255 two different skins.
256 Text::ProgressBar is another customisable progress meter, which comes
258 with a number of 'widgets' for display progress information in
259 different ways.
260 ProgressBar::Stack handles the case where a long-running process has a
262 number of sub-processes, and you want to record progress of those too.
263 String::ProgressBar provides a simple progress bar, which shows
265 progress using a bar of ASCII characters, and the percentage complete.
266 Term::Spinner is simpler than most of the other modules listed here, as
268 it just displays a 'spinner' to the terminal. This is useful if you
269 just want to show that something is happening, but can't predict how
270 many more operations will be required.
271 Term::Pulse shows a pulsed progress bar in your terminal, using a child
273 process to pulse the progress bar until your job is complete.
274 Term::YAP a fork of "Term::Pulse".
276 Term::StatusBar is another progress bar module, but it hasn't seen a
278 release in the last 12 years.
279
281 https://github.com/cade-vs/perl-time-progress
282 git clone https://github.com/cade-vs/perl-time-progress
284
286 Vladi Belperchinov-Shabanski "Cade"
287 <cade@bis.bg> <cade@cpan.org>
289 http://cade.datamax.bg
291
293 This software is (c) 2001-2019 by Vladi Belperchinov-Shabanski
294 <cade@bis.bg> <cade@cpan.org>.
295 This is free software; you can redistribute it and/or modify it under
297 the same terms as the Perl 5 programming language system itself.
298perl v5.38.0 2023-07-21 Time::Progress(3)