.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Time::Progress 3pm" .TH Time::Progress 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Time::Progress \- Elapsed and estimated finish time reporting. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Time::Progress; \& \& my ($min, $max) = (0, 4); \& my $p = Time::Progress\->new(min => $min, max => $max); \& \& for (my $c = $min; $c <= $max; $c++) { \& print STDERR $p\->report("\er%20b ETA: %E", $c); \& # do some work \& } \& print STDERR "\en"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module displays progress information for long-running processes. This can be percentage complete, time elapsed, estimated time remaining, an \s-1ASCII\s0 progress bar, or any combination of those. .PP It is useful for code where you perform a number of steps, or iterations of a loop, where the number of iterations is known before you start the loop. .PP The typical usage of this module is: .IP "\(bu" 4 Create an instance of \f(CW\*(C`Time::Progress\*(C'\fR, specifying min and max count values. .IP "\(bu" 4 At the head of the loop, you call the \f(CW\*(C`report()\*(C'\fR method with a format specifier and the iteration count, and get back a string that should be displayed. .PP If you include a carriage return character (\er) in the format string, then the message will be over-written at each step. Putting \er at the start of the format string, as in the \s-1SYNOPSIS,\s0 results in the cursor sitting at the end of the message. .PP If you display to \s-1STDOUT,\s0 then remember to enable auto-flushing: .PP .Vb 2 \& use IO::Handle; \& STDOUT\->autoflush(1); .Ve .PP The shortest time interval that can be measured is 1 second. .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" .Vb 1 \& my $p = Time::Progress\->new(%options); .Ve .PP Returns new object of Time::Progress class and starts the timer. It also sets min and max values to 0 and 100, so the next \fBreport\fR calls will default to percents range. .PP You can configure the instance with the following parameters: .IP "min" 4 .IX Item "min" Sets the \fBmin\fR attribute, as described in the \f(CW\*(C`attr\*(C'\fR section below. .IP "max" 4 .IX Item "max" Sets the \fBmax\fR attribute, as described in the \f(CW\*(C`attr\*(C'\fR section below. .IP "smoothing" 4 .IX Item "smoothing" If set to a true value, then the estimated time remaining is smoothed in a simplistic way: if the time remaining ever goes up, by less than 10% of the previous estimate, then we just stick with the previous estimate. This prevents flickering estimates. By default this feature is turned off. .IP "smoothing_delta" 4 .IX Item "smoothing_delta" Sets smoothing delta parameter. Default value is 0.1 (i.e. 10%). See 'smoothing' parameter for more details. .SS "restart" .IX Subsection "restart" Restarts the timer and clears the stop mark. Optionally \fBrestart()\fR may act also as \fBattr()\fR for setting attributes: .PP .Vb 1 \& $p\->restart( min => 1, max => 5 ); .Ve .PP is the same as: .PP .Vb 2 \& $p\->attr( min => 1, max => 5 ); \& $p\->restart(); .Ve .PP If you need to count things, you can set just 'max' attribute since 'min' is already set to 0 when object is constructed by \fBnew()\fR: .PP .Vb 1 \& $p\->restart( max => 42 ); .Ve .SS "stop" .IX Subsection "stop" Sets the stop mark. This is only useful if you do some work, then finish, then do some work that shouldn't be timed and finally report. Something like: .PP .Vb 6 \& $p\->restart; \& # do some work here... \& $p\->stop; \& # do some post\-work here \& print $p\->report; \& # \`post\-work\*(Aq will not be timed .Ve .PP Stop is useless if you want to report time as soon as work is finished like: .PP .Vb 3 \& $p\->restart; \& # do some work here... \& print $p\->report; .Ve .SS "continue" .IX Subsection "continue" Clears the stop mark. (mostly useless, perhaps you need to \fBrestart\fR?) .SS "attr" .IX Subsection "attr" Sets and returns internal values for attributes. Available attributes are: .IP "min" 4 .IX Item "min" This is the min value of the items that will follow (used to calculate estimated finish time) .IP "max" 4 .IX Item "max" This is the max value of all items in the even (also used to calculate estimated finish time) .IP "format" 4 .IX Item "format" This is the default \fBreport\fR format. It is used if \fBreport\fR is called without parameters. .PP \&\fBattr\fR returns array of the set attributes: .PP .Vb 1 \& my ( $new_min, $new_max ) = $p\->attr( min => 1, max => 5 ); .Ve .PP If you want just to get values use undef: .PP .Vb 1 \& my $old_format = $p\->attr( format => undef ); .Ve .PP This way of handling attributes is a bit heavy but saves a lot of attribute handling functions. \fBattr\fR will complain if you pass odd number of parameters. .SS "report" .IX Subsection "report" This is the most complex method in this package :) .PP The expected arguments are: .PP .Vb 1 \& $p\->report( format, [current_item] ); .Ve .PP \&\fIformat\fR is string that will be used for the result string. Recognized special sequences are: .ie n .IP "%l" 4 .el .IP "\f(CW%l\fR" 4 .IX Item "%l" elapsed seconds .ie n .IP "%L" 4 .el .IP "\f(CW%L\fR" 4 .IX Item "%L" elapsed time in minutes in format \s-1MM:SS\s0 .ie n .IP "%e" 4 .el .IP "\f(CW%e\fR" 4 .IX Item "%e" remaining seconds .ie n .IP "%E" 4 .el .IP "\f(CW%E\fR" 4 .IX Item "%E" remaining time in minutes in format \s-1MM:SS\s0 .ie n .IP "%p" 4 .el .IP "\f(CW%p\fR" 4 .IX Item "%p" percentage done in format \s-1PPP\s0.P% .ie n .IP "%f" 4 .el .IP "\f(CW%f\fR" 4 .IX Item "%f" estimated finish time in format returned by \fB\fBlocaltime()\fB\fR .ie n .IP "%b" 4 .el .IP "\f(CW%b\fR" 4 .IX Item "%b" .PD 0 .ie n .IP "%B" 4 .el .IP "\f(CW%B\fR" 4 .IX Item "%B" .PD progress bar which looks like: .Sp .Vb 1 \& ##############...................... .Ve .Sp \&\f(CW%b\fR takes optional width: .Sp .Vb 3 \& %40b \-\- 40\-chars wide bar \& %9b \-\- 9\-chars wide bar \& %b \-\- 79\-chars wide bar (default) .Ve .PP Parameters can be omitted and then default format set with \fBattr\fR will be used. .PP Sequences 'L', 'l', 'E' and 'e' can have width also: .PP .Vb 3 \& %10e \& %5l \& ... .Ve .PP Estimate time calculations can be used only if min and max values are set (see \fBattr\fR method) and current item is passed to \fBreport\fR! if you want to use the default format but still have estimates use it like this: .PP .Vb 1 \& $p\->format( undef, 45 ); .Ve .PP If you don't give current item (step) or didn't set proper min/max value then all estimate sequences will have value `n/a'. .PP You can freely mix reports during the same event. .SS "elapsed($item)" .IX Subsection "elapsed($item)" Returns the time elapsed, in seconds. This help function, and those described below, take one argument: the current item number. .SS "estimate($item)" .IX Subsection "estimate($item)" Returns an estimate of the time remaining, in seconds. .SS "elapsed_str($item)" .IX Subsection "elapsed_str($item)" Returns elapsed time as a formatted string: .PP .Vb 1 \& "elapsed time is MM:SS min.\en" .Ve .SS "estimate_str($item)" .IX Subsection "estimate_str($item)" Returns estimated remaining time, as a formatted string: .PP .Vb 1 \& "remaining time is MM:SS min.\en" .Ve .SH "FORMAT EXAMPLES" .IX Header "FORMAT EXAMPLES" .Vb 2 \& # $c is current element (step) reached \& # for the examples: min = 0, max = 100, $c = 33.3 \& \& print $p\->report( "done %p elapsed: %L (%l sec), ETA %E (%e sec)\en", $c ); \& # prints: \& # done 33.3% elapsed time 0:05 (5 sec), ETA 0:07 (7 sec) \& \& print $p\->report( "%45b %p\er", $c ); \& # prints: \& # ###############.............................. 33.3% \& \& print $p\->report( "done %p ETA %f\en", $c ); \& # prints: \& # done 33.3% ETA Sun Oct 21 16:50:57 2001 .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" The first thing you need to know about Smart::Comments is that it was written by Damian Conway, so you should expect to be a little bit freaked out by it. It looks for certain format comments in your code, and uses them to display progress messages. Includes support for progress meters. .PP Progress::Any separates the calculation of stats from the display of those stats, so you can have different back-ends which display progress is different ways. There are a number of separate back-ends on \s-1CPAN.\s0 .PP Term::ProgressBar displays a progress meter to a standard terminal. .PP Term::ProgressBar::Quiet uses \f(CW\*(C`Term::ProgressBar\*(C'\fR if your code is running in a terminal. If not running interactively, then no progress bar is shown. .PP Term::ProgressBar::Simple provides a simple interface where you get a \f(CW$progress\fR object that you can just increment in a long-running loop. It builds on \f(CW\*(C`Term::ProgressBar::Quiet\*(C'\fR, so displays nothing when not running interactively. .PP Term::Activity displays a progress meter with timing information, and two different skins. .PP Text::ProgressBar is another customisable progress meter, which comes with a number of 'widgets' for display progress information in different ways. .PP ProgressBar::Stack handles the case where a long-running process has a number of sub-processes, and you want to record progress of those too. .PP String::ProgressBar provides a simple progress bar, which shows progress using a bar of \s-1ASCII\s0 characters, and the percentage complete. .PP Term::Spinner is simpler than most of the other modules listed here, as it just displays a 'spinner' to the terminal. This is useful if you just want to show that something is happening, but can't predict how many more operations will be required. .PP Term::Pulse shows a pulsed progress bar in your terminal, using a child process to pulse the progress bar until your job is complete. .PP Term::YAP a fork of \f(CW\*(C`Term::Pulse\*(C'\fR. .PP Term::StatusBar is another progress bar module, but it hasn't seen a release in the last 12 years. .SH "GITHUB REPOSITORY" .IX Header "GITHUB REPOSITORY" .SH "AUTHOR" .IX Header "AUTHOR" Vladi Belperchinov-Shabanski \*(L"Cade\*(R" .PP .PP .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2001\-2015 by Vladi Belperchinov-Shabanski . .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.