NAME

Term::YAPI - Yet Another Progress Indicator

SYNOPSIS

 use Term::YAPI;

 # Synchronous progress indicator
 my $yapi = Term::YAPI->new('yapi' => [ qw(/ - \ |) ]);
 $yapi->start('Working: ');
 foreach (1..10) {
     sleep(1);
     $yapi->progress();
 }
 $yapi->done('done');

 # Asynchronous (threaded) progress indicator
 my $yapi = Term::YAPI->new('async' => 1);
 $yapi->start('Please wait: ');
 sleep(10);
 $yapi->done('done');

DESCRIPTION

Term::YAPI provides a simple progress indicator on the terminal to let the user know that something is happening. The indicator is an animation of single characters displayed cyclically one after the next.

The text cursor is hidden while progress is being displayed, and restored after the progress indicator finishes. A $SIG{'INT'} handler is installed while progress is being displayed so that the text cursor is automatically restored should the user hit ctrl-C.

The progress indicator can be controlled synchronously by the application, or can run asynchronously in a thread.

my $yapi = Term::YAPI->new()

Creates a new synchronous progress indicator object, using the default twirling bar indicator: / - \ |

my $yapi = Term::YAPI->new('yapi' => $indicator_array_ref)

Creates a new synchronous progress indicator object using the characters specified in the supplied array ref. Examples:

 my $yapi = Term::YAPI->new('yapi' => [ qw(^ > v <) ]);

 my $yapi = Term::YAPI->new('yapi' => [ qw(. o O o) ]);

 my $yapi = Term::YAPI->new('yapi' => [ qw(. : | :) ]);

 my $yapi = Term::YAPI->new('yapi' => [ qw(9 8 7 6 5 4 3 2 1 0) ]);

my $yapi = Term::YAPI->new('async' => 1);

my $yapi = Term::YAPI->new('yapi' => $indicator_array_ref, 'async' => 1)

Creates a new asynchronous progress indicator object.

$yapi->start($start_msg)

Sets up the interrupt signal handler, hides the text cursor, and prints out the optional message string followed by the first progress character. The message defaults to 'Working: '.

For an asynchronous progress indicator, the progress characters begin displaying at one second intervals.

$yapi->progress()

Backspaces over the previous progress character, and displays the next character.

This method is not used with asynchronous progress indicators.

$yapi->done($done_msg)

Prints out the optional message (defaults to 'done'), restores the text cursor, and removes the interrupt handler installed by the ->start() method (restoring any previous interrupt handler).

The progress indicator object is reusable.

INSTALLATION

The following will install YAPI.pm under the Term directory in your Perl installation:

 cp YAPI.pm `perl -MConfig -e'print $Config{privlibexp}'`/Term/

LIMITATIONS

Works, as is, on xterm, rxvt, and the like. When used with MSDOS consoles, you need to add the :MSDOS flag to the module declaration line:

 use Term::YAPI ':MSDOS';

When used as such, the text cursor will not be hidden when progress is being displayed.

Generating multiple progress indicator objects and running them at different times in an application is supported. This module will not allow more than one indicator to run at the same time.

Trying to use asynchronous progress indicators on non-threaded Perls will work, but will not display an animated progress character.

SEE ALSO

Object::InsideOut, threads, Thread::Queue

AUTHOR

Jerry D. Hedden, <jdhedden AT cpan DOT org>

COPYRIGHT AND LICENSE

Copyright 2005 - 2007 Jerry D. Hedden. All rights reserved.

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