Term::Activity - Process Activity Display Module - v 1.01

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

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 => [ '-', '=', '%', '=', '-' ]
  });


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:
================================================================================

Min size:

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.

Global hell:

The goal is to reduce the amount of computations that occur on each pass 
so that the display has minimal impact on actual processing. To that end a 
symbol table rewrite is used to keep from having to dynamically catch the 
selected skin on every tick(). Due to this, and the accompanying lack of 
$self the code gets nigh unreadable and lots of global variables in the 
mask of module-level 'our's abound. A better way shall be found.

================================================================================
AUTHORSHIP:
================================================================================

  Phillip Pollard <phil@crescendo.net>
  Kristina Davis <krd@menagerie.tf>

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