/ 
Object-InsideOut-4.01
River stage two • 23 direct dependents • 38 total dependents
/ Term::YAPI

NAME

Term::YAPI - Yet Another Progress Indicator

SYNOPSIS

use Term::YAPI;

# Synchronous progress indicator: .o0o.o0o.o0o.
my $yapi = Term::YAPI->new('type' => 'dots', 'yapi' => [ qw(. o 0 o) ]);
$yapi->start('Working: ');
foreach (1..10) {
    sleep(1);
    $yapi->progress();
}
$yapi->done('done');

# Asynchronous (threaded) incrementing counter
my $yapi = Term::YAPI->new('type' => 'count', 'async' => 1);
$yapi->start('Waiting 10 sec.: ');
sleep(10);
$yapi->erase();

DESCRIPTION

Term::YAPI provides progress indicators on the terminal to let the user know that something is happening. The indicator can be in incrementing counter, or can consist of one or more elements that are displayed cyclically one after another.

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

The 'type' parameter specifies the type of progress indicator to be used:

'type' => 'anim'

An animated indicator - defaults to the twirling bar indicator. This is the default indicator type.

'type' => 'dots'

A character sequence indicator - defaults to a line of periods/dots: .....

'type' => 'count'

An incrementing counter that starts at 0.

'type' => 'countdown'

An decrementing counter. The starting value is specified using a (mandatory) 'from' parameter:

my $yapi = Term::YAPI->new('type' => 'countdown', 'from' => 15);
my $yapi = Term::YAPI->new('yapi' => $indicator_array_ref)

The 'yapi' parameter supplies an array reference containing the elements to be used for the indicator. Examples:

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

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

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

This parameter is ignored for 'type' => 'count' indicators.

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

Creates a new asynchronous progress indicator object.

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

Indicates that the entire line occupied by the indicator is to be erased when the indicator is terminated.

$yapi->start($start_msg)

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

For an asynchronous progress indicator, the progress elements display at one second intervals.

$yapi->progress()

Displays the next progress indicator element.

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).

$yapi->endtime()

Terminates the indicator as with the ->done() method, and prints out the elapsed time for the indicator.

$yapi->erase()

Terminates the indicator, and erases the entire line the indicator was on.

The progress indicator object is reusable. In other words, after using it once, you can use it again just by using $yapi->start($start_msg).

EXAMPLE

Term::YAPI will even support using ANSI color sequences in the progress indicator elements:

use Term::YAPI;
use Term::ANSIColor ':constants';

my $l = BOLD . BLUE . '<' . RESET;
my $r = BOLD . BLUE . '>' . RESET;
my $x1 = RED . '.' . RESET;
my $x2 = RED . 'o' . RESET;
my $x3 = RED . '0' . RESET;

my $yapi = Term::YAPI->new('type' => 'anim',
                           'yapi' => [ "$l$x1    $r",
                                       "$l $x2   $r",
                                       "$l  $x3  $r",
                                       "$l   $x2 $r",
                                       "$l    $x1$r",
                                       "$l   $x2 $r",
                                       "$l  $x3  $r",
                                       "$l $x2   $r" ],
                           'async' => 1);

$yapi->start(GREEN . 'Watch this ' . RESET);
sleep(10);
$yapi->done(YELLOW . '- cool, eh?' . RESET);

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/

or as part of the Object::InsideOut installation process:

perl Makefile.PL
make
make yapi
make install

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 not cause an error, but will only display 'wait...'.

SEE ALSO

Object::InsideOut, threads, Thread::Queue

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright 2005 - 2012 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.