1Time::Progress(3)     User Contributed Perl Documentation    Time::Progress(3)
2
3
4

NAME

6       Time::Progress - Elapsed and estimated finish time reporting.
7

SYNOPSIS

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

DESCRIPTION

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
35           format specifier and the iteration count, and get back a string
36           that 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

METHODS

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       Parameters can be ommited and then default format set with attr will be
173       used.
174
175       Sequences 'L', 'l', 'E' and 'e' can have width also:
176
177         %10e
178         %5l
179         ...
180
181       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
185         $p->format( undef, 45 );
186
187       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
190       You can freely mix reports during the same event.
191
192   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
196   estimate($item)
197       Returns an estimate of the time remaining, in seconds.
198
199   elapsed_str($item)
200       Returns elapsed time as a formatted string:
201
202         "elapsed time is MM:SS min.\n"
203
204   estimate_str($item)
205       Returns estimated remaining time, as a formatted string:
206
207         "remaining time is MM:SS min.\n"
208

FORMAT EXAMPLES

210        # $c is current element (step) reached
211        # for the examples: min = 0, max = 100, $c = 33.3
212
213        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
217        print $p->report( "%45b %p\r", $c );
218        # prints:
219        # ###############..............................  33.3%
220
221        print $p->report( "done %p ETA %f\n", $c );
222        # prints:
223        # done  33.3% ETA Sun Oct 21 16:50:57 2001
224

SEE ALSO

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
232       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
236       Term::ProgressBar displays a progress meter to a standard terminal.
237
238       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
242       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
247       Term::Activity displays a progress meter with timing information, and
248       two different skins.
249
250       Text::ProgressBar is another customisable progress meter, which comes
251       with a number of 'widgets' for display progress information in
252       different ways.
253
254       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
257       String::ProgressBar provides a simple progress bar, which shows
258       progress using a bar of ASCII characters, and the percentage complete.
259
260       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
265       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
268       Term::YAP a fork of "Term::Pulse".
269
270       Term::StatusBar is another progress bar module, but it hasn't seen a
271       release in the last 12 years.
272

GITHUB REPOSITORY

274       <https://github.com/cade-vs/perl-time-progress>
275

AUTHOR

277       Vladi Belperchinov-Shabanski "Cade"
278
279       <cade@biscom.net> <cade@datamax.bg> <cade@cpan.org>
280
281       <http://cade.datamax.bg>
282
284       This software is copyright (c) 2001-2015 by Vladi Belperchinov-
285       Shabanski <cade@cpan.org>.
286
287       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.
289
290
291
292perl v5.36.0                      2022-07-22                 Time::Progress(3)
Impressum