NAME
Log::Progress - Conveniently write progress messages to logger or file handle
VERSION
version 0.000_001
SYNOPSIS
my $p= Log::Progress->new(to => \*STDERR); # The default
$p->squelch(.1); # only emit messages every 10%
my $max= 1000;
for (my $i= 0; $i < $max; $i++) {
# do the thing
...;
$p->progress(($i+1)/$max);
# -or-
$p->progress_ratio($i+1, $max);
}DESCRIPTION
This module assists with writing the Log::Progress protocol, which can then be parsed with the Log::Progress::Parser. It can write to file handles, log objects (like Log::Any), a coderef, or any object with a "print" method.
Note that this module enables autoflush if you give it a file handle.
ATTRIBUTES
to
The destination for progress messages. \*STDERR is the default. You can pass any file handle, coderef, or object with a 'info' method.
precision
The progress number is written as text, with "precision" digits after the decimal point. The default precision is 2. This default corresponds with a default "squelch" of 0.01, so that calls to ->progress with less than 1% change from the previous call are suppressed.
If you set precision but not squelch, the second will use a default to match the one you specified. For example, setting a precision of 5 results in a default squelch of .00001, or a default squelch of 350 results in a precision of 3.
Once set, precision will not receive a default value from changes to squelch. (but you can un-define it)
squelch
You can prevent spamming your log file with tiny progress updates using "squelch", which limits progress messages to one per some fraction of overall progress. For example, the default squelch of .01 will only emit at most 101 progress messages. (unless you start reporting negative progress)
If you set squelch but not precision, the second will use a sensible default. See example in "precision"
Once set, squelch will not receive a default value from changing precision. (but you can un-define it)
step_id
If this object is reporting the progress of a sub-step, set this ID to the step name.
The default value for this field comes from $ENV{PROGRESS_STEP_ID}, so that programs that perform simple progress reporting can be nested as child processes of a larger job without having to specifically plan for that ability in the child process.
METHODS
progress
$p->progress( $ratio );
$p->progress( $ratio, $message );Report progress (but only if the progress since the last output is greater than squelch). Ratio is clamped to the range 0..1. Message is optional.
progress_ratio
$p->progress_ratio( $count, $total )
$p->progress_ratio( $count, $total, $message )Report progress as a discrete count of things. This style gives the consumer a little more metadata to work with vs. printing the count in the message, and is preferred for the common case where you are iterating a known quantity.
data
If you want to write any progress-associated data, use this method. The data must be a hashref.
substep
my $substep_progress= $progress->substep( $id, $contribution, $title );Create a named sub-step progress object, and declare it on the output.
$id and $title are required. $contribution is recommended (in order for the progress of the sub-step to automatically update the parent) but not required.
Note that the sub-step gets declared on the output stream each time you call this method, but it isn't harmful to do so multiple times for the same step.
AUTHOR
Michael Conrad <mike@nrdvana.net>
COPYRIGHT AND LICENSE
This software is copyright (c) 2016 by Michael Conrad.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.