SYNOPSIS

 First example, simple usage in a script

     use Progress::Any '$progress';
     use Progress::Any::Output 'TermProgressBarColor';
    
     $progress->target(10);
     for (1..10) {
         $progress->update(message => "Doing item $_");
         sleep 1;
     }

    Sample output:

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

 Second example, usage in module as well as script

    In your module:

     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 your application:

     use MyApp;
     use Progress::Any::Output;
     Progress::Any::Output->set('TermProgressBarColor');
    
     MyApp::download("url1", "url2", "url3", "url4", "url5");

    sample output, in succession:

     % ./script.pl
      20% [====== Downloaded url1           ]0m00s Left
      40% [=======Downloaded url2           ]0m01s Left
      60% [=======Downloaded url3           ]0m01s Left
      80% [=======Downloaded url4==         ]0m00s Left

    (At 100%, the output automatically cleans up the progress bar).

  Another example, demonstrating multiple indicators and the LogAny output:

     use Progress::Any;
     use Progress::Any::Output;
     use Log::Any::App;
    
     Progress::Any::Output->set('LogAny', template => '[%-8t] [%P/%2T] %m');
     my $pdl = Progress::Any->get_indicator(task => 'download');
     my $pcp = Progress::Any->get_indicator(task => 'copy');
    
     $pdl->pos(10);
     $pdl->target(10);
     $pdl->update(message => "downloading A");
     $pcp->update(message => "copying A");
     $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;

STATUS

    API might still change, will be stabilized in 1.0.

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:

    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 => STR* (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 => STR* (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 => POSNUM (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 => POSNUM* (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 => STR (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

 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.

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

      * level => NUM

      EXPERIMENTAL, NOT YET IMPLEMENTED BY MOST OUTPUTS. Setting the
      importance level of this update. Default is normal (or low for
      fractional update), but can be set to high or low. Output can choose
      to ignore updates lower than a certain level.

      * state => STR

      Can be set to finished to finish a task.

 $progress->finish(%args)

    Equivalent to:

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

 $progress->start()

    Set state to started.

 $progress->stop()

    Set state to stopped.

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

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

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

 $progress->total_pos() => FLOAT

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

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

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

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

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

 $progress->fill_template($template)

    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

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

