NAME

Term::Activity - Process Activity Display Module

SYNOPSIS

This module is designed to produce informational STDERR output while a process is funinctioning over many iterations or outputs. It is instanced with an optional name and other configurable values and is then called on each iterative loop.

DESCRIPTION

The information displayed is the current time processed (measured since the instancing of the module), the number of actions second, a text-graphic indicator of activity (skinnable), and the total count of actions thus far.

An example output (on a small terminal) might appear like this:

  03:13:54 1 : [~~~~~~~~~~~~~~~~~\_______________] 9,461

Showing that nearly three hours and 14 minues have occured with a current rate of 1 action per second, for a total of 9,461 total actions. (For the curious, the skin shown is the default skin, AKA 'wave')

The display occurs on a single line that is updated regularly. The display automatically calibrates itself so that it appears to update approximately once a second.

When the Term::Activity module passes out of scope it updates the display with the final time, count, and a newline before exiting.

Term::Activity can resize itself to the width of the current window if Term::Size is installed. If not, it defaults to an 80-character display. Term::Size is thouroughly reccomended.

USAGE

Basic Usage:

  my $ta = new Term::Activity;

  while ( doing stuff ) {
    $ta->tick;
  }

Process labels:

You can label the output with a string to be displayed along with the other output. This is handy for scripts that go through multiple processess.

You can either instance them as a scalar value:

  my $ta = new Term::Activity 'Batch7';

Or via a configuration hash reference:

  my $ta = new Term::Activity ({ label => 'Batch7' });

Also, through the course of processing, you can change the label.

  $ta->relabel("New Label");

Skins:

Skins can be selected via a configuration hash reference. Currently there are two skins 'wave' and 'flat.' "Wave" is the default skin.

  my $ta = new Term::Activity ({ skin => 'flat' });

The "flat" skin cycles through a series of characters. You may also provide an arrayreference of your favorite characters if you'd like different ones:

  my $ta = new Term::Activity ({ 
     skin  => 'flat',
     chars => [ '-', '=', '%', '=', '-' ]
  });

Start Time:

The start time for the process timer is initialized when the Term::Activity is created. Sometimes, with longer programs you want the count to remain constant through several different forms of processing. You can set the start time to a previous start time to do this.

The parameter is called 'time' in the initilization hash:

  my $start_time = time;

  # Stuff happens

  my $ta = new Term::Activity ({ 
     time => $start_time
  });
  

Count:

As with the time, you might want to start at a later count, so you can keep track of total count across several runs.

The parameter to change the starting count is called 'count' in the initialization hash:

  my $ta = new Term::Activity ({ 
     count => $start_count
  });

Interval:

The interval is how often the screen is updated to reflect changes. By default, Term::Activity auto-tunes this towards an update approximately each second.

Initially, however, there is no way of knowing how often you will call tick(), so an assumed interval of 100 iterations before update is the starting value.

For slower processes, you probably want to start this at 1 - that is, a visual update at each call of tick()

  my $ta = new Term::Activity ({ 
     interval => 1
  });

Debug:

By setting the debug parameter to 1 a very verbose debug output is produced along with the regular output to let you see settings have been selected and what computations are being performed.

  my $ta = new Term::Activity ({ 
     debug => 1
  });

Multiple Instances:

As stated above, when the Term::Activity module passes out of scope it updates the display with the final time, count, and a newline before exiting. Consuquently if you would like to use Term::Activity multiple times in a single program you will need to undefine the object and reinstance it:

  my $ta = new Term::Activity;

  while ( doing stuff ) {
    $ta->tick;
  }

  $ta = undef;
  $ta = new Term::Activity;

  while ( doing more stuff ) {
    $ta->tick;
  }

  (lather. rinse. repeat.)

KNOWN ISSUES

Resizing the window during execution may cause the status bar to stop refreshing properly.

Is the window is too small to accomodate the time, label, count, and basic spacing (that is, there is less that 0 spaces for the activity to be displayed) the effect, while being preety in a watching-the-car-wreck way, it is not informative. Remember to keep your label strings short.

BUGS AND SOURCE

        Bug tracking for this module: https://rt.cpan.org/Dist/Display.html?Name=Term-Activity
        
        Source hosting: http://www.github.com/bennie/perl-Term-Activity

VERSION

        Term::Activity v1.21 2022/01/06

COPYRIGHT

    (c) 2003-2022, Phillip Pollard <bennie@cpan.org>

LICENSE

This source code is released under the "Perl Artistic License 2.0," the text of which is included in the LICENSE file of this distribution. It may also be reviewed here: http://opensource.org/licenses/artistic-license-2.0

AUTHORSHIP

    Additional contributions by Kristina Davis <krd@menagerie.tf>

    Derived from Util::Status 1.12 2003/09/08
    With permission granted from Health Market Science, Inc.

SEE ALSO:

  Term::ProgressBar

cpanm Term::Activity

perl -MCPAN -e shell
install Term::Activity