Example of using with Perinci::CmdLine¶

If you use Perinci::CmdLine, you can mark your function as expecting a Progress::Any object and it will be supplied to you in a special argument "-progress":

 use File::chdir;
 use Perinci::CmdLine;
 $SPEC{check_dir} = {
     v => 1.1,
     args => {
         dir => {summary=>"Path to check", schema=>"str*", req=>1, pos=>0},
     },
     features => {progress=>1},
 };
 sub check_dir {
     my %args = @_;
     my $progress = $args{-progress};
     my $dir = $args{dir};
     (-d $dir) or return [412, "No such dir: $dir"];
     local $CWD = $dir;
     opendir my($dh), $dir;
     my @ent = readdir($dh);
     $progress->pos(0);
     $progress->target(scalar @ent);
     for (@ent) {
         # do the check ...
         $progress->update(message => $_);
         sleep 1;
     }
     $progress->finish;
     [200];
 }
 Perinci::CmdLine->new(url => '/main/check_dir')->run;

$progress => OBJ¶

The root indicator. Equivalent to:

 Progress::Any->get_indicator(task => '')

task¶

String. Default: from caller's package, or "main".

Task name. If not specified will be set to caller's package ("::" will be replaced with "."), e.g. if you are calling this method from "Foo::Bar::baz()", then task will be set to "Foo.Bar". If caller is code inside eval, "main" will be used instead.

title¶

String. Default: task name.

Specify task title. Task title is a longer description for a task and can contain spaces and other characters. It is displayed in some outputs, as well as using %t in "fill_template()". For example, for a task called "copy", its title might be "Copying files to remote server".

target¶

Non-negative number. Default: 0.

The total number of items to finish. Can be set to undef to mean that we don't know (yet) how many items there are to finish (in which case, we cannot estimate percent of completion and remaining time).

pos¶

Non-negative number. Default: 0.

The number of items that are already done. It cannot be larger than "target", if "target" is defined. If "target" is set to a value smaller than "pos" or "pos" is set to a value larger than "target", "pos" will be changed to be "target".

state¶

String. Default: "stopped".

State of task/indicator. Either: "stopped", "started", or "finished". Initially it will be set to "stopped", which means elapsed time won't be running and will stay at 0. "update()" will set the state to "started" to get elapsed time to run. At the end of task, you can call "finish()" (or alternatively set "state" to "finished") to stop the elapsed time again.

The difference between "stopped" and "finished" is: when "target" and "pos" are both at 0, percent completed is assumed to be 0% when state is "stopped", but 100% when state is "finished".

get_indicator¶

Usage:

 Progress::Any->get_indicator(%args) => obj

Get a progress indicator for a certain task. %args contain attribute values, at least "task" must be specified.

Note that this module maintains a list of indicator singleton objects for each task (in %indicators package variable), so subsequent "get_indicator()" for the same task will return the same object.

update¶

Usage:

 $progress->update(%args)

Update indicator. Will also, usually, update associated output(s) if necessary.

Arguments:

• pos => NUM

  Set the new position. If unspecified, defaults to current position + 1. If pos is larger than target, outputs will generally still show 100%. Note that fractions are allowed.

• message => str|code

  Set a message to be displayed when updating indicator.

  Aside from a string, you can also pass a coderef here. It can be used to delay costly calculation. The message will only be calculated when actually sent to output.

• priority => str ("normal"|"low"|"high", default: "normal")

  Set importance level of this update. Default is "normal". Output can choose to ignore updates lower than a certain level.

• state => STR

  Can be set to "finished" to finish a task.

• force_update => BOOL

  Default false. Some outputs choose only to update themselves after a certain amount of time or number of updates have passed; this forces their update.

finish¶

Usage:

 $progress->finish(%args)

Equivalent to:

 $progress->update(
     ( pos => $progress->target ) x !!defined($progress->target),
     state => 'finished',
     %args,
 );

reset¶

Usage:

 $progress->reset(%args)

Equivalent to:

 $progress->update(
     pos => 0,
     state => 'started',
     %args,
 );

start¶

Usage:

 $progress->start()

Set state to "started".

stop¶

Usage:

 $progress->stop()

Set state to "stopped".

elapsed¶

Usage:

 $progress->elapsed() => float

Get elapsed time. Just like a stop-watch, when state is "started" elapsed time will run and when state is "stopped", it will freeze.

remaining¶

Usage:

 $progress->remaining() => undef|float

Give estimated remaining time until task is finished, which will depend on how fast the "update()" is called, i.e. how fast "pos" is approaching "target". Will be undef if "target" is undef.

total_remaining¶

Usage:

 $progress->total_remaining() => undef|FLOAT

Give estimated remaining time added by all its subtasks' remaining. Return undef if any one of those time is undef.

total_pos¶

Usage:

 $progress->total_pos() => float

Total of indicator's pos and all of its subtasks'.

total_target¶

Usage:

 $progress->total_target() => undef|float

Total of indicator's target and all of its subtasks'. Return undef if any one of those is undef.

percent_complete¶

Usage:

 $progress->percent_complete() => undef|float

Give percentage of completion, calculated using "total_pos / total_target * 100". Undef if total_target is undef.

fill_template¶

Usage:

 $progress->fill_template($template) => str

Fill template with values, like in "sprintf()". Usually used by output modules. Available templates:

• "%(width)n"

  Task name (the value of the "task" attribute). "width" is optional, an integer, like in "sprintf()", can be negative to mean left-justify instead of right.

• "%(width)t"

  Task title (the value of the "title" attribute).

• "%(width)e"

  Elapsed time (the result from the "elapsed()" method). Currently using Time::Duration concise format, e.g. 10s, 1m40s, 16m40s, 1d4h, and so on. Format might be configurable and localizable in the future. Default width is -8. Examples:

   2m30s
   10s
      

• "%(width)r"

  Estimated remaining time (the result of the "total_remaining()" method). Currently using Time::Duration concise format, e.g. 10s, 1m40s, 16m40s, 1d4h, and so on. Will show "?" if unknown. Format might be configurable and localizable in the future. Default width is -8. Examples:

   1m40s
   5s
      

• "%(width)R"

  Estimated remaining time or elapsed time, if estimated remaining time is not calculatable (e.g. when target is undefined). Format might be configurable and localizable in the future. Default width is -(8+1+7). Examples:

   30s left
   1m40s elapsed
      

• "%(width).(prec)p"

  Percentage of completion (the result of the "percent_complete()" method). "width" and "precision" are optional, like %f in Perl's "sprintf()", default is "%3.0p". If percentage is unknown (due to target being undef), will show "?".

• "%(width)P"

  Current position (the result of the "total_pos()" method).

• "%(width)T"

  Target (the result of the "total_target()" method). If undefined, will show "?".

• %m

  Message (the "update()" parameter). If message is unspecified, will show empty string.

• "%%"

  A literal "%" sign.

PROGRESS¶

Boolean. Default 1. Can be set to 0 to supress display progress output.