NAME

Term::Sprog - Perl extension for displaying a progress indicator on a terminal.

SYNOPSIS

  use Term::Sprog;

  my $ctr = Term::Sprog->new('%d Elapsed: %8t %21b %4p %2d (%8c of %11m)',
    {quiet => 0, freq => 10, base => 0, target => 100, pdisp => '!'})
    or die "Error 0010: Term::Sprog->new, ".
           "(code $Term::Sprog::errcode) ".
           "$Term::Sprog::errmsg";

  $ctr->up for (1..100);

  $ctr->down for (1..100);

  $ctr->whisper('abc'); 

  my last_line = $ctr->get_line;

  $ctr->close;

DESCRIPTION

Term::Sprog is a class to implement a progress indicator ("Sprog" is a short form for "Show PROGress"). This is used to provide immediate feedback for long running processes.

A sample code fragment that uses Term::Sprog:

  use Term::Sprog;

  print qq{This is a test of "Term::Sprog"\n\n};

  my $target = 2_845;
  my $format = '%2d Elapsed: %8t %21b %4p %2d (%8c of %11m)';

  my $ctr = Term::Sprog->new($format,
    {freq => 10, base => 0, target => $target, pdisp => '!'})
    or die "Error 0010: Term::Sprog->new, ".
           "(code $Term::Sprog::errcode) ".
           "$Term::Sprog::errmsg";

  for (1..$target) {
      $ctr->up;
      do_something();
  }

  $ctr->close;

  sub do_something {
      my $test = 0;
      for my $i (0..10_000) {
          $test += sin($i) * cos($i);
      }
  }

Another example that counts upwards:

  use Term::Sprog;

  my $format = '%21b %4p';

  my $ctr = Term::Sprog->new($format, {freq => 's', base => 0, target => 70})
    or die "Error 0010: Term::Sprog->new, (code $Term::Sprog::errcode) $Term::Sprog::errmsg";

  for (1..10) {
      $ctr->up(7);
      sleep 1;
  }

  $ctr->close;

This example uses a simple progress bar in quiet mode (nothing is printed to STDOUT), but instead, the content of what would have been printed can now be extracted using the get_line() method:

  use Term::Sprog;

  my $format = 'Ctr %4c';

  my $ctr = Term::Sprog->new($format, {freq => 2, base => 0, target => 10, quiet => 1})
    or die "Error 0010: Term::Sprog->new, (code $Term::Sprog::errcode) $Term::Sprog::errmsg";

  my $line = $ctr->get_line;
  $line =~ s/\010/</g;
  print "This is what would have been printed upon new(): [$line]\n";

  for my $i (1..10) {
      $ctr->up;

      $line = $ctr->get_line;
      $line =~ s/\010/</g;
      print "This is what would have been printed upon $i. call to up(): [$line]\n";
  }

  $ctr->close;

  $line = $ctr->get_line;
  $line =~ s/\010/</g;
  print "This is what would have been printed upon close(): [$line]\n";

The first parameter to new() is the format string which contains the following special characters:

characters '%d'

a revolving dash, format '/-\|'

characters '%t'

time elapsed, format 'hh:mm:ss'

characters '%b'

progress bar, format '#####_____'

characters '%p'

Progress in percentage, format '999%'

characters '%c'

Actual counter value (commified by '_'), format '99_999_999'

characters '%m'

Target maximum value (commified by '_'), format '99_999_999'

characters '%P'

The '%' character itself

The second parameter are the following options:

option {freq => 999}

This option sets the refresh-frequency on STDOUT to every 999 up() or down() calls. If {freq => 999} is not specified at all, then the refresh-frequency is set by default to every up() or down() call.

option {freq => 's'}

This is a special case whereby the refresh-frequency on STDOUT is set to every second.

option {base => 0}

This specifies the base value from which to count. The default is 0

option {target => 10_000}

This specifies the maximum value to which to count. The default is 10_000.

option {pdisp => '!'}

This option (with the exclamation mark) forces the progress bar to display special ASCII characters to simulate blocks, rather than the sharp-symbol ('#'). (Does not work on all terminals)

option {quiet => 1}

This option disables any printing to STDOUT, but the content of the would be printed line is still available using the method get_line()

The new() method immediately displays the initial values on screen. From now on, nothing must be printed to STDOUT and/or STDERR. However, you can write to STDOUT during the operation using the method whisper().

We can either count upwards, $ctr->up, or downwards, $ctr->down. Everytime we do so, the value is either incremented or decremented and the new value is replaced on STDOUT. We should do so regularly during the process. Both methods, $ctr->up(99) and $ctr->down(99) can take an optional argument, in which case the value is incremented/decremented by the specified amount.

When our process has finished, we must close the counter ($ctr->close). By doing so, the last displayed value is removed from STDOUT, as if nothing had happened. Now we are allowed to print again to STDOUT and/or STDERR.

AUTHOR

Klaus Eichner, January 2008

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Klaus Eichner

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.