This is a shim to get the features of a modernized Term::Pager into IO::Pager, providing a self-contained executable pure perl pager. It will die if Term::Pager is ever updated, or the shim can be reworked into a forking branch of IO::Pager::Perl; early attempts of which are in __DATA__ of that module.

NAME

Term::Pager - Page through text, a screenful at a time, like more or less

SYNOPSIS

    use Term:ReadKey; #Optional, but recommended
    use Term::Pager;

    my $t = Term::Pager->new( rows => 25, cols => 80 );
    $t->add_text( $text );
    $t->more();

DESCRIPTION

This is a module for paging through text one screenful at a time. It supports the features you expect, including backwards movement and searching. It uses the keys you expect.

USAGE

Create the Pager

    $t = Term::Pager->new( option => value, ... );

If no options are specified, sensible default values will be used. The following options are recognized:

rows

The number of rows on your terminal. The terminal is queried directly with Term::ReadKey if loaded or stty, and if these fail it defaults to 25.

cols

The number of columns on your terminal. The terminal is queried directly with Term::ReadKey if loaded or stty, and if these fail it defaults to 80.

speed

The speed (baud rate) of your terminal. The terminal is queried directly with Term::ReadKey if loaded or stty, and if these fail it defaults to a sensible value.

Adding Text

You will need some text to page through. You can specify text as as a parameter to the constructor:

    text => $text

Or add text later:

    $t->add_text( $text );

To continuously add text to the pager, you must setup your own event loop, and indicate to more that it should relinquish control e.g;

    eval{
        while( $t->more(RT=>.05) ){
          ...
          $t->add_text("More text to page");
        }
    };

The eval block captures the exception thrown upon termination of the pager so that your own program may continue. The RT parameter indicates that you wish to provide content in real time. This value is also passed to "ReadKey" in Term::ReadKey as the maximum blocking time per keypress and should be between 0 and 1, with larger values trading greater interface responsiveness for slight delays in output. A value of -1 may also be used to request non-blocking polls, but likely will not behave as you would hope.

NOTE: If Term::ReadKey is not loaded but RT is true, screen updates will only occur on keypress.

Adding Functionality and Internationalization (I18N)

It is possible to extend the features of Term::Pager by supplying the add_func method with a hash of character keys and callback values to be invoked upon matching keypress; where \c? represents Control-? and \e? represents Alt-? The existing pairings are:

        "\n"=> \&downline, #also "\e[B"
        ' ' => \&downpage, #also "\cv"
        'd' => \&downhalf,
        'q' => \&done,
        'b' => \&uppage,   #also "\ev"
        'y' => \&upline,   #also "\e[A"
        'u' => \&uphalf,
        'r' => \&refresh,  #also "\cl"
        'h' => \&help,
        'g' => \&to_top,   #also '<'
        'G' => \&to_bott,  #also '>'
        '/' => \&search,
        '?' => \&hcraes,   #reverse search
        'n' => \&next_match,#also 'P'
        'p' => \&prev_match,#also 'N'
        "\e[D" => \&move_left,
        "\e[C" => \&move_right,

And a special sequence of a number followed by enter analogous to:

        '/(\d+)/'   => \&jump(\1)        

if the value for that key is true.

The dialog method may be particularly useful when enhancing the pager. It accepts a string to display, and an optional timeout to sleep for before the dialog is cleared. If the timeout is missing or 0, the dialog remains until a key is pressed.

    my $t = Term::Pager->new();
    $t->add_text("Text to display");
    $t->add_func('!'=>\&boo);
    $t->more();

    sub boo{ my $self = shift; $self->dialog("BOO!", 1); }

Should you add additional functionality to your pager, you will likely want to change the contents of the help dialog or possibly the status line. Use the I18N method to replace the default text or save text for your own interface.

    #Get the default help text
    my $help = $t->I18N('help');

    #Minimal status line
    $t->I18N('status', "<h> help");

Current text elements available for customization are:

    404    - search text not found dialog
    status - displayed at the bottom of the screen
    top    - status line start of file indicator
    bottom - status line end of file indicator
    help   - help dialog text, a list of keys and their functions

CAVEATS

This module uses Termcap, which has been deprecated the Open Group, and may not be supported by your operating system for much longer.

If the termcap entry for your ancient esoteric terminal is wrong or incomplete, this module may either fill your screen with unintelligible gibberish, or drop back to a feature-free mode.

SEE ALSO

    Term::Cap, Term::ReadKey, termcap(5), stty(1), more(1), less(1)
    Yellowstone National Park

AUTHORS

    Jeff Weisberg - http://www.tcp4me.com

    Jerrad Pierce

cpanm IO::Pager

perl -MCPAN -e shell
install IO::Pager