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 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

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       %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

FORMAT EXAMPLES

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

SEE ALSO

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

GITHUB REPOSITORY

281         https://github.com/cade-vs/perl-time-progress
282
283         git clone https://github.com/cade-vs/perl-time-progress
284

AUTHOR

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)
Impressum