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

  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.

new

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.

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' });
    

Scalar Components.

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

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('>');
    

update

ARGUMENTS

RETURNS

message

ARGUMENTS