1Time::Progress(3) User Contributed Perl Documentation Time::Progress(3)
2
3
4
6 Time::Progress - Elapsed and estimated finish time reporting.
7
9 use Time::Progress;
10
11 my ($min, $max) = (0, 4);
12 my $p = Time::Progress->new(min => $min, max => $max);
13
14 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
25 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
29 The typical usage of this module is:
30
31 • Create an instance of "Time::Progress", specifying min and max
32 count values.
33
34 • 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
38 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
43 If you display to STDOUT, then remember to enable auto-flushing:
44
45 use IO::Handle;
46 STDOUT->autoflush(1);
47
48 The shortest time interval that can be measured is 1 second.
49
51 new
52 my $p = Time::Progress->new(%options);
53
54 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
58 You can configure the instance with the following parameters:
59
60 min Sets the min attribute, as described in the "attr" section below.
61
62 max Sets the max attribute, as described in the "attr" section below.
63
64 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
71 smoothing_delta
72 Sets smoothing delta parameter. Default value is 0.1 (i.e. 10%).
73 See 'smoothing' parameter for more details.
74
75 restart
76 Restarts the timer and clears the stop mark. Optionally restart() may
77 act also as attr() for setting attributes:
78
79 $p->restart( min => 1, max => 5 );
80
81 is the same as:
82
83 $p->attr( min => 1, max => 5 );
84 $p->restart();
85
86 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
89 $p->restart( max => 42 );
90
91 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
96 $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
103 Stop is useless if you want to report time as soon as work is finished
104 like:
105
106 $p->restart;
107 # do some work here...
108 print $p->report;
109
110 continue
111 Clears the stop mark. (mostly useless, perhaps you need to restart?)
112
113 attr
114 Sets and returns internal values for attributes. Available attributes
115 are:
116
117 min This is the min value of the items that will follow (used to
118 calculate estimated finish time)
119
120 max This is the max value of all items in the even (also used to
121 calculate estimated finish time)
122
123 format
124 This is the default report format. It is used if report is called
125 without parameters.
126
127 attr returns array of the set attributes:
128
129 my ( $new_min, $new_max ) = $p->attr( min => 1, max => 5 );
130
131 If you want just to get values use undef:
132
133 my $old_format = $p->attr( format => undef );
134
135 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
139 report
140 This is the most complex method in this package :)
141
142 The expected arguments are:
143
144 $p->report( format, [current_item] );
145
146 format is string that will be used for the result string. Recognized
147 special sequences are:
148
149 %l elapsed seconds
150
151 %L elapsed time in minutes in format MM:SS
152
153 %e remaining seconds
154
155 %E remaining time in minutes in format MM:SS
156
157 %p percentage done in format PPP.P%
158
159 %f estimated finish time in format returned by localtime()
160
161 %b
162 %B progress bar which looks like:
163
164 ##############......................
165
166 %b takes optional width:
167
168 %40b -- 40-chars wide bar
169 %9b -- 9-chars wide bar
170 %b -- 79-chars wide bar (default)
171
172 %s current speed in items per second
173
174 %S current min/max speeds (calculated after first 1% of the progress)
175
176 Parameters can be omitted and then default format set with attr will be
177 used.
178
179 Sequences 'L', 'l', 'E' and 'e' can have width also:
180
181 %10e
182 %5l
183 ...
184
185 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
189 $p->format( undef, 45 );
190
191 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
194 You can freely mix reports during the same event.
195
196 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
200 estimate($item)
201 Returns an estimate of the time remaining, in seconds.
202
203 elapsed_str($item)
204 Returns elapsed time as a formatted string:
205
206 "elapsed time is MM:SS min.\n"
207
208 estimate_str($item)
209 Returns estimated remaining time, as a formatted string:
210
211 "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
217 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
221 print $p->report( "%45b %p\r", $c );
222 # prints:
223 # ###############.............................. 33.3%
224
225 print $p->report( "done %p ETA %f\n", $c );
226 # prints:
227 # done 33.3% ETA Sun Oct 21 16:50:57 2001
228
229 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
239 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
243 Term::ProgressBar displays a progress meter to a standard terminal.
244
245 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
249 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
254 Term::Activity displays a progress meter with timing information, and
255 two different skins.
256
257 Text::ProgressBar is another customisable progress meter, which comes
258 with a number of 'widgets' for display progress information in
259 different ways.
260
261 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
264 String::ProgressBar provides a simple progress bar, which shows
265 progress using a bar of ASCII characters, and the percentage complete.
266
267 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
272 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
275 Term::YAP a fork of "Term::Pulse".
276
277 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
283 git clone https://github.com/cade-vs/perl-time-progress
284
286 Vladi Belperchinov-Shabanski "Cade"
287
288 <cade@bis.bg> <cade@cpan.org>
289
290 http://cade.datamax.bg
291
293 This software is (c) 2001-2019 by Vladi Belperchinov-Shabanski
294 <cade@bis.bg> <cade@cpan.org>.
295
296 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.
298
299
300
301perl v5.38.0 2023-07-21 Time::Progress(3)