Provided by: libprogress-any-perl_0.220-1_all bug

NAME

       Progress::Any - Record progress to any output

VERSION

       This document describes version 0.220 of Progress::Any (from Perl distribution Progress-
       Any), released on 2022-10-18.

SYNOPSIS

       Example of using in a script with terminal progress bar as output (progress bar will be
       cleared on "finish()") (you'll need to install Progress::Any::Output::TermProgressBarColor
       as well):

        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:

        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=>scalar @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(scalar @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 (you'll need to install one of the
       output modules as they are not included in this minimal distribution). 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:

       •   multiple progress indicators

           You can use different indicator for each task/subtask.

       •   customizable output

           Output is handled by one of "Progress::Any::Output::*" modules. Currently available
           outputs: "Null" (no output), "TermMessage" (display as simple message on terminal),
           "TermProgressBarColor" (display as color progress bar on terminal), "LogAny" (log
           using Log::Any), "Callback" (call a subroutine).  Other possible output ideas:
           IM/Twitter/SMS, GUI, web/AJAX, remote/RPC (over Riap for example, so that
           Perinci::CmdLine-based command-line clients can display progress update from remote
           functions).

       •   multiple outputs

           One or more outputs can be used to display one or more indicators.

       •   hierarchical progress

           A task can be divided into subtasks. If a subtask is updated, its parent task (and its
           parent, and so on) are also updated proportionally.

       •   message

           Aside from setting a number/percentage, allow including a message when updating
           indicator.

       •   undefined target

           Target can be undefined, so a bar output might not show any bar (or show them, but
           without percentage indicator), but can still show messages.

       •   retargetting

           Target can be changed in the middle of things.

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:

       •   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.

FAQ

ENVIRONMENT

   PROGRESS
       Boolean. Default 1. Can be set to 0 to supress 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>.

SEE ALSO

       Progress::Any::Examples distribution contains example scripts.

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

       Output modules: "Progress::Any::Output::*". You need to install at least one module to
       actually see progress being outputted/displayed somewhere, e.g. <> to
       Progress::Any::Output::TermProgressBarColor.

       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>

CONTRIBUTOR

       Steven Haryanto <stevenharyanto@gmail.com>

CONTRIBUTING

       To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

       Most of the time, you don't need to build the distribution yourself. You can simply modify
       the code, then test via:

        % prove -l

       If you want to build the distribution (e.g. to try to install it locally on your system),
       you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR,
       Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla-
       and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug
       and can be reported to me.

COPYRIGHT AND LICENSE

       This software is copyright (c) 2022, 2020, 2018, 2015, 2014, 2013, 2012 by perlancar
       <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.

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.