View on
MetaCPAN
search.cpan.org is shutting down
For details read Perl NOC. After June 25th this page will redirect to MetaCPAN.org
perlancar > Progress-Any > Progress::Any

Download:
Progress-Any-0.214.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.214   Source  

NAME ^

Progress::Any - Record progress to any output

VERSION ^

This document describes version 0.214 of Progress::Any (from Perl distribution Progress-Any), released on 2018-03-26.

SYNOPSIS ^

Example of using in a script with terminal progress bar as output (progress bar will be cleared on finish()):

 use Progress::Any '$progress';
 use Progress::Any::Output 'TermProgressBarColor';

 $progress->target(10);
 for (1..10) {
     $progress->update(message => "Doing item $_");
     sleep 1;
 }
 $progress->finish();

Sample output:

 % ./script.pl
  60% [Doing item 6====           ]3s left

Another example, this time with terminal message as output (see :

 use Progress::Any '$progress';
 use Progress::Any::Output 'TermMessage', template => '[%n] %P/%T (%6.2p%%) %m';

 $progress->target(10);
 for (1..10) {
     $progress->update(message => "Item $_/10");
     sleep 1;
 }
 sleep 1;
 $progress->finish(message => "Finished!");

Sample output:

 % ./script.pl
 [] 1/10 ( 10.00%) Item 1/10
 [] 2/10 ( 20.00%) Item 2/10
 ...
 [] 10/10 (100.00%) Item 10/10
 [] 10/10 (100.00%) Finished!

Example of using in a module as well as script:

 # in lib/MyApp.pm
 package MyApp;
 use Progress::Any;

 sub download {
     my @urls = @_;
     return unless @urls;
     my $progress = Progress::Any->get_indicator(
         task => "download", pos=>0, target=>~~@urls);
     for my $url (@urls) {
         # download the $url ...
         $progress->update(message => "Downloaded $url");
     }
     $progress->finish;
 }

 # in script.pl
 use MyApp;
 use Progress::Any::Output;
 Progress::Any::Output->set('TermProgressBarColor');

 MyApp::download("url1", "url2", "url3", "url4", "url5");

Sample output:

 % ./script.pl
  20% [====== Downloaded url1           ]0m00s Left

Example that demonstrates multiple indicator objects:

 use Progress::Any;
 use Progress::Any::Output;

 my $pdl = Progress::Any->get_indicator(task => 'download');
 Progress::Any::Output->set({task=>'download'}, 'TermMessage', template => '[%-8t] [%P/%2T] %m');
 my $pcp = Progress::Any->get_indicator(task => 'copy');
 Progress::Any::Output->set({task=>'copy'    }, 'TermMessage', template => '[%-8t] [%P/%2T] %m');

 $pdl->target(10);
 $pdl->update(message => "downloading A");
 $pcp->update(message => "copying A");
 sleep 1;
 $pdl->update(message => "downloading B");
 $pcp->update(message => "copying B");

will show something like:

 [download] [1/10] downloading A
 [copy    ] [1/ ?] copying A
 [download] [2/10] downloading B
 [copy    ] [2/ ?] copying B

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(~~@ent);
     for (@ent) {
         # do the check ...
         $progress->update(message => $_);
         sleep 1;
     }
     $progress->finish;
     [200];
 }
 Perinci::CmdLine->new(url => '/main/check_dir')->run;

DESCRIPTION ^

Progress::Any is an interface for applications that want to display progress to users. It decouples progress updating and output, rather similar to how Log::Any decouples log producers and consumers (output). The API is also rather similar to Log::Any, except Adapter is called Output and category is called task.

Progress::Any records position/target and calculates elapsed time, estimated remaining time, and percentage of completion. One or more output modules (Progress::Any::Output::*) display this information.

In your modules, you typically only need to use Progress::Any, get one or more indicators, set target and update it during work. In your application, you use Progress::Any::Output and set/add one or more outputs to display the progress. By setting output only in the application and not in modules, you separate the formatting/display concern from the logic.

Screenshots:

STATUS ^

API might still change, will be stabilized in 1.0.

The list of features:

EXPORTS ^

$progress => OBJ

The root indicator. Equivalent to:

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

ATTRIBUTES ^

Below are the attributes of an 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.

METHODS ^

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:

finish

Usage:

 $progress->finish(%args)

Equivalent to:

 $progress->update(
     ( pos => $progress->target ) x !!defined($progress->target),
     state => 'finished',
     %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:

FAQ ^

ENVIRONMENT ^

PROGRESS

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

HOMEPAGE ^

Please visit the project's homepage at https://metacpan.org/release/Progress-Any.

SOURCE ^

Source repository is at https://github.com/perlancar/perl-Progress-Any.

BUGS ^

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Progress-Any

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO ^

Other progress modules on CPAN: Term::ProgressBar, Term::ProgressBar::Simple, Time::Progress, among others.

Output modules: Progress::Any::Output::*

See examples on how Progress::Any is used by other modules: Perinci::CmdLine (supplying progress object to functions), Git::Bunch (using progress object).

AUTHOR ^

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2018, 2015, 2014, 2013, 2012 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: