path: root/README

NAME
    Progress::Any - Record progress to any output

VERSION
    This document describes version 0.216 of Progress::Any (from Perl
    distribution Progress-Any), released on 2020-07-09.

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:

    *   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 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
    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::*"

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