Provided by: libterm-progressbar-perl_2.21-1_all bug

NAME

       Term::ProgressBar - provide a progress meter on a standard terminal

VERSION

       Version 2.21

SYNOPSIS

           use Term::ProgressBar;

           my $progress = Term::ProgressBar->new ({count => 10_000});
           $progress->update(5_000);

DESCRIPTION

       Term::ProgressBar provides a simple progress bar on the terminal, to let the user know
       that something is happening, roughly how much stuff has been done, and maybe an estimate
       at how long remains.

       A typical use sets up the progress bar with a number of items to do, and then calls update
       to update the bar whenever an item is processed.

       Often, this would involve updating the progress bar many times with no user-visible
       change.  To avoid unnecessary work, the update method returns a value, being the update
       value at which the user will next see a change.  By only calling update when the current
       value exceeds the next update value, the call overhead is reduced.

       Remember to call the "$progress->update($max_value)" when the job is done to get a nice
       100% done bar.

       A progress bar by default is simple; it just goes from left-to-right, filling the bar with
       '=' characters.  These are called major characters.  For long-running jobs, this may be
       too slow, so two additional features are available: a linear completion time estimator,
       and/or a minor character: this is a character that moves from left-to-right on the
       progress bar (it does not fill it as the major character does), traversing once for each
       major-character added.  This exponentially increases the granularity of the bar for the
       same width.

EXAMPLES

   A really simple use
           #!/usr/bin/perl

           use Term::ProgressBar 2.00;
           use constant MAX => 100_000;

           my $progress = Term::ProgressBar->new(MAX);

           for (0..MAX) {
               my $is_power = 0;
               for (my $i = 0; 2**$i <= $_; $i++) {
                   $is_power = 1 if 2**$i == $_;
               }

               if ($is_power) {
                   $progress->update($_);
               }
           }

       see eg/simle_use.pl

       Here is a simple example.  The process considers all the numbers between 0 and MAX, and
       updates the progress bar whenever it finds one.  Note that the progress bar update will be
       very erratic.  See below for a smoother example.  Note also that the progress bar will
       never complete; see below to solve this.

       The complete text of this example is in examples/powers in the distribution set (it is not
       installed as part of the module).

   A smoother bar update
           my $progress = Term::ProgressBar->new($max);

           for (0..$max) {
               my $is_power = 0;
               for (my $i = 0; 2**$i <= $_; $i++) {
                   $is_power = 1 if 2**$i == $_;
               }

               $progress->update($_)
           }

       See eg/smooth_bar.pl

       This example calls update for each value considered.  This will result in a much smoother
       progress update, but more program time is spent updating the bar than doing the "real"
       work.  See below to remedy this.  This example does not call "$progress->update($max);" at
       the end, since it is unnecessary, and ProgressBar will throw an exception at an attempt to
       update a finished bar.

       The complete text of this example is in examples/powers2 in the distribution set (it is
       not installed as part of the module.

   A (much) more efficient update
           my $progress = Term::ProgressBar->new({name => 'Powers', count => $max, remove => 1});
           $progress->minor(0);
           my $next_update = 0;

           for (0..$max) {
               my $is_power = 0;
               for (my $i = 0; 2**$i <= $_; $i++) {
                   $is_power = 1 if 2**$i == $_;
               }

               $next_update = $progress->update($_) if $_ >= $next_update;
           }

           $progress->update($max) if $max >= $next_update;

       This example does two things to improve efficiency: firstly, it uses the value returned by
       update to only call it again when needed; secondly, it switches off the use of minor
       characters to update a lot less frequently ("$progress->minor(0);".  The use of the return
       value of update means that the call of "$progress->update($max);" at the end is required
       to ensure that the bar ends on 100%, which gives the user a nice feeling.

       This example also sets the name of the progress bar.

       This example also demonstrates the use of the 'remove' flag, which removes the progress
       bar from the terminal when done.

       The complete text of this example is in examples/powers3 in the distribution set (it is
       not installed as part of the module.

   When the maximum number of items is sometimes unknown
       Sometimes you may wish to use the progress bar when the number of items may or may not be
       known. One common example is when you write a script that can take input piped from the
       output of another command, and then pipe the output to yet another command. eg:

         some_command --arg value | my_script.pl | some_other_command

       Or ...

         my_script.pl input_file output_file

       This example shows how you can iterate over a file specified on the command line with the
       progress bar. Since the input file may be read from STDIN, the number of lines may not be
       known. Term::ProgressBar handles this by just taking '-1' as the count value and with no
       further changes to the code. By calling update with the same count value, you ensure the
       progress bar is removed afterwards.

           my $input_file = shift;
           my $output_file = shift;
           my $in_fh = \*STDIN;
           my $out_fh = \*STDOUT;
           my $message_fh = \*STDERR;
           my $num_lines = -1;

           if (defined($input_file) and $input_file ne '-') {
               open($in_fh, $input_file) or die "Couldn't open file, '$input_file': $!";
               my $wc_output = `wc -l $input_file`;
               chomp($wc_output);
               $wc_output =~ /^\s*(\d+)(\D.*)?/ or die "Couldn't parse wc output: $wc_output";
               $num_lines = $1;
           }

           if(defined($output_file)) {
               !-f $output_file or die "Specified output file, '$output_file', already exists";
               open($out_fh, '>', $output_file) or die "Couldn't open output file, '$output_file': $!";
           }

           my $progress = Term::ProgressBar->new({
               name   => 'file processor',
               count  => $num_lines,
               remove => 1,
               fh     => $message_fh,
           });

           while (my $line = <$in_fh>) {
               chomp($line);
               print $out_fh "I found a line: $line\n";
               $progress->message("Found 10000!") if($line =~ /10000/);
               $progress->update();
           }

           $progress->update($num_lines);

           print $message_fh "Finished\n";

       When the file is defined explicitly, the progress bar displays the linewise progress
       through the file. Since the progress bar by default prints output to stderr, your scripts
       output to STDOUT will not be affected.

   Using Completion Time Estimation
           my $progress = Term::ProgressBar->new({
               name  => 'Powers',
               count => $max,
               ETA   => 'linear',
           });
           $progress->max_update_rate(1);
           my $next_update = 0;

           for (0..$max) {
               my $is_power = 0;
               for (my $i = 0; 2**$i <= $_; $i++) {
               if ( 2**$i == $_ ) {
                   $is_power = 1;
                   $progress->message(sprintf "Found %8d to be 2 ** %2d", $_, $i);
               }
           }

           $next_update = $progress->update($_)
             if $_ > $next_update;
         }
         $progress->update($max)
             if $max >= $next_update;

       This example uses the ETA option to switch on completion estimation.  Also, the update
       return is tuned to try to update the bar approximately once per second, with the
       max_update_rate call.  See the documentation for the new method for details of the
       format(s) used.

       This example also provides an example of the use of the message function to output
       messages to the same filehandle whilst keeping the progress bar intact

       The complete text of this example is in examples/powers5 in the distribution set (it is
       not installed as part of the module.

INSTANCE CONSTRUCTION

   new
       Create & return a new Term::ProgressBar instance.

       ARGUMENTS
           If one argument is provided, and it is a hashref, then the hash is treated as a set of
           key/value pairs, with the following keys; otherwise, it is treated as a number, being
           equivalent to the "count" key.

           count
               The item count.  The progress is marked at 100% when update count is invoked, and
               proportionally until then.

               If you specify a count less than zero, just the name (if specified) will be
               displayed and (if the remove flag is set) removed when the progress bar is updated
               with a number lower than zero. This allows you to use the progress bar when the
               count is sometimes known and sometimes not without making multiple changes
               throughout your code.

           name
               A name to prefix the progress bar with.

           fh  The filehandle to output to.  Defaults to stderr.  Do not try to use *foo{THING}
               syntax if you want Term capabilities; it does not work.  Pass in a globref
               instead.

           term_width
               Sometimes we can't correctly determine the terminal width. You can use this
               parameter to force a term width of a particular size. Use a positive integer,
               please :)

           silent
               If passed a true value, Term::ProgressBar will do nothing at all. Useful in
               scripts where the progress bar is optional (or just plain doesn't work due to
               issues with modules it relies on).

               Instead, tell the constructor you want it to be silent and you don't need to
               change the rest of your program:

                   my $progress = Term::ProgressBar->new( { count => $count, silent => $silent } );
                   # later
                   $progress->update; # does nothing

           ETA A total time estimation to use.  If enabled, a time finished estimation is printed
               on the RHS (once sufficient updates have been performed to make such an estimation
               feasible).  Naturally, this is an estimate; no guarantees are made.  The format of
               the estimate

               Note that the format is intended to be as compact as possible while giving over
               the relevant information.  Depending upon the time remaining, the format is
               selected to provide some resolution whilst remaining compact.  Since the time
               remaining decreases, the format typically changes over time.

               As the ETA approaches, the format will state minutes & seconds left.  This is
               identifiable by the word 'Left' at the RHS of the line.  If the ETA is further
               away, then an estimate time of completion (rather than time left) is given, and is
               identifiable by 'ETA' at the LHS of the ETA box (on the right of the progress
               bar).  A time or date may be presented; these are of the form of a 24 hour clock,
               e.g. '13:33', a time plus days (e.g., ' 7PM+3' for around in over 3 days time) or
               a day/date, e.g. ' 1Jan' or '27Feb'.

               If ETA is switched on, the return value of update is also affected: the idea here
               is that if the progress bar seems to be moving quicker than the eye would normally
               care for (and thus a great deal of time is spent doing progress updates rather
               than "real" work), the next value is increased to slow it.  The maximum rate aimed
               for is tunable via the max_update_rate component.

               The available values for this are:

               undef
                   Do not do estimation.  The default.

               linear
                   Perform linear estimation.  This is simply that the amount of time between the
                   creation of the progress bar and now is divided by the current amount done,
                   and completion estimated linearly.

       EXAMPLES
             my $progress = Term::ProgressBar->new(100); # count from 1 to 100
             my $progress = Term::ProgressBar->new({ count => 100 }); # same

             # Count to 200 thingies, outputting to stdout instead of stderr,
             # prefix bar with 'thingy'
             my $progress = Term::ProgressBar->new({ count => 200,
                                                     fh    => \*STDOUT,
                                                     name  => 'thingy' });

INSTANCE COMPONENTS

   Scalar Components.
       See "get_set" in Class::MethodMaker for usage.

       target
           The final target.  Updates are measured in terms of this.  Changes will have no effect
           until the next update, but the next update value should be relative to the new target.
           So

             $p = Term::ProgressBar({count => 20});
             # Halfway
             $p->update(10);
             # Double scale
             $p->target(40)
             $p->update(21);

           will cause the progress bar to update to 52.5%

       max_update_rate
           This value is taken as being the maximum speed between updates to aim for.  It is only
           meaningful if ETA is switched on. It defaults to 0.5, being the number of seconds
           between updates.

   Boolean Components
       See "get_set" in Class::MethodMaker for usage.

       minor
           Default: set.  If unset, no minor scale will be calculated or updated.

           Minor characters are used on the progress bar to give the user the idea of progress
           even when there are so many more tasks than the terminal is wide that the granularity
           would be too great.  By default, Term::ProgressBar makes a guess as to when minor
           characters would be valuable.  However, it may not always guess right, so this method
           may be called to force it one way or the other.  Of course, the efficiency saving is
           minimal unless the client is utilizing the return value of update.

           See examples/powers4 and examples/powers3 to see minor characters in action, and not
           in action, respectively.

   Configuration
       lbrack
           Left bracket ( defaults to [ )

            $progress->lbrack('<');

       rbrack
           Right bracket ( defaults to ] )

            $progress->rbrack('>');

INSTANCE HIGHER-LEVEL PROCEDURES

   update
       Update the progress bar.

       ARGUMENTS
           so_far
               Current progress point, in whatever units were passed to "new".

               If not defined, assumed to be 1+ whatever was the value last time "update" was
               called (starting at 0).

       RETURNS
           next_call
               The next value of so_far at which to call "update".

   message
       Output a message.  This is very much like print, but we try not to disturb the terminal.

       ARGUMENTS
           string
               The message to output.

REPORTING BUGS

       via RT: <https://rt.cpan.org/Dist/Display.html?Name=Term-ProgressBar>

COMPATIBILITY

       If exactly two arguments are provided, then new operates in v1 compatibility mode: the
       arguments are considered to be name, and item count.  Various other defaults are set to
       emulate version one (e.g., the major output character is '#', the bar width is set to 50
       characters and the output filehandle is not treated as a terminal). This mode is
       deprecated.

AUTHOR

       Martyn J. Pearce fluffy@cpan.org

       Significant contributions from Ed Avis, amongst others.

MAINTAINER

       Gabor Szabo <http://szabgab.com/> <http://perlmaven.com/>

LICENSE AND COPYRIGHT

       Copyright (c) 2001, 2002, 2003, 2004, 2005 Martyn J. Pearce.  This program is free
       software; you can redistribute it and/or modify it under the same terms as Perl itself.