1Progress(3) User Contributed Perl Documentation Progress(3)
2
6 Time::Progress - Elapsed and estimated finish time reporting.
7
9 use Time::Progress;
10 # autoflush to get \r working
11 $| = 1;
12 # get new `timer'
13 my $p = new Time::Progress;
14 # restart and report progress
16 $p->restart;
17 sleep 5; # or do some work here
18 print $p->report( "done %p elapsed: %L (%l sec), ETA %E (%e sec)\n", 50 );
19 # set min and max values
21 $p->attr( min => 2, max => 20 );
22 # restart `timer'
23 $p->restart;
24 my $c;
25 for( $c = 2; $c <= 20; $c++ )
26 {
27 # print progress bar and percentage done
28 print $p->report( "eta: %E min, %40b %p\r", $c );
29 sleep 1; # work...
30 }
31 # stop timer
32 $p->stop;
33 # report times
35 print $p->elapsed_str;
36
38 Shortest time interval that can be measured is 1 second. The available
39 methods are:
40 new
42 my $p = new Time::Progress;
43 Returns new object of Time::Progress class and starts the timer. It
45 also sets min and max values to 0 and 100, so the next report calls
46 will default to percents range.
47 restart
49 restarts the timer and clears the stop mark. optionally restart()
50 may act also as attr() for setting attributes:
51 $p->restart( min => 1, max => 5 );
53 is the same as:
55 $p->attr( min => 1, max => 5 );
57 $p->restart();
58 If you need to count things, you can set just 'max' attribute since
60 'min' is already set to 0 when object is constructed by new():
61 $p->restart( max => 42 );
63 stop
65 Sets the stop mark. this is only usefull if you do some work, then
66 finish, then do some work that shouldn't be timed and finally
67 report. Something like:
68 $p->restart;
70 # do some work here...
71 $p->stop;
72 # do some post-work here
73 print $p->report;
74 # `post-work' will not be timed
75 Stop is useless if you want to report time as soon as work is
77 finished like:
78 $p->restart;
80 # do some work here...
81 print $p->report;
82 continue
84 Clears the stop mark. (mostly useless, perhaps you need to
85 restart?)
86 attr
88 Sets and returns internal values for attributes. Available
89 attributes are:
90 min This is the min value of the items that will follow (used to
92 calculate estimated finish time)
93 max This is the max value of all items in the even (also used to
95 calculate estimated finish time)
96 format
98 This is the default report format. It is used if report is
99 called without parameters.
100 attr returns array of the set attributes:
102 my ( $new_min, $new_max ) = $p->attr( min => 1, max => 5 );
104 If you want just to get values use undef:
106 my $old_format = $p->attr( format => undef );
108 This way of handling attributes is a bit heavy but saves a lot of
110 attribute handling functions. attr will complain if you pass odd
111 number of parameters.
112 report
114 report is the most complex method in this package! :)
115 expected arguments are:
117 $p->report( format, [current_item] );
119 format is string that will be used for the result string.
121 Recognized special sequences are:
122 %l elapsed seconds
124 %L elapsed time in minutes in format MM:SS
126 %e remaining seconds
128 %E remaining time in minutes in format MM:SS
130 %p percentage done in format PPP.P%
132 %f estimated finish time in format returned by localtime()
134 %b
136 %B progress bar which looks like:
137 ##############......................
139 %b takes optional width:
141 %40b -- 40-chars wide bar
143 %9b -- 9-chars wide bar
144 %b -- 79-chars wide bar (default)
145 Parameters can be ommited and then default format set with attr
147 will be used.
148 Estimate time calculations can be used only if min and max values
150 are set (see attr method) and current item is passed to report! if
151 you want to use the default format but still have estimates use it
152 like this:
153 $p->format( undef, 45 );
155 If you don't give current item (step) or didn't set proper min/max
157 value then all estimate sequences will have value `n/a'.
158 You can freely mix reports during the same event.
160 elapsed
162 estimated
163 elapsed_str
164 estimated_str
165 helpers -- return elapsed/estimated seconds or string in format:
166 "elapsed time is MM:SS min.\n"
168 "remaining time is MM:SS min.\n"
169
171 # $c is current element (step) reached
172 # for the examples: min = 0, max = 100, $c = 33.3
173 print $p->report( "done %p elapsed: %L (%l sec), ETA %E (%e sec)\n", $c );
175 # prints:
176 # done 33.3% elapsed time 0:05 (5 sec), ETA 0:07 (7 sec)
177 print $p->report( "%45b %p\r", $c );
179 # prints:
180 # ###############.............................. 33.3%
181 print $p->report( "done %p ETA %f\n", $c );
183 # prints:
184 # done 33.3% ETA Sun Oct 21 16:50:57 2001
185
187 Vladi Belperchinov-Shabanski "Cade"
188 <cade@biscom.net> <cade@datamax.bg> <cade@cpan.org>
190 http://cade.datamax.bg
192perl v5.12.0 2009-02-03 Progress(3)