Provided by: libio-pager-perl_2.10-1_all 
NAME
IO::Pager::Perl - Page text a screenful at a time, like more or less
SYNOPSIS
use Term:ReadKey; #Optional, but recommended
use IO::Pager::Perl;
my $t = IO::Pager::Perl->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 using the shortcuts you expect.
IO::Pager::Perl is an enhanced fork of Term::Pager.
USAGE
Create the Pager
$t = IO::Pager::Perl->new( option => value, ... );
If no options are specified, sensible default values will be used. The following options
are recognized, and shown with the default value:
rows =>25?
The number of rows on your terminal. The terminal is queried directly with
Term::ReadKey if loaded or "stty" or "tput", and if these fail it defaults to 25.
cols =>80?
The number of columns on your terminal. The terminal is queried directly with
Term::ReadKey if loaded or "stty" or "tput", and if these fail it defaults to 80.
speed =>38400?
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.
eof =>0
Exit at end of file.
fold =>1
Fold long lines with Text::Wrap.
lineNo =>0
If true, line numbering is added to the output.
pause =>0
If defined, the pager will pause when the this character sequence is encountered in
the input text. Set to ^L i.e; "\cL" to mimic traditional behavior of "1" in more.
raw =>0
Pass control characters from input unadulterated to the terminal. By default,
chracters other than tab and newline will be converted to caret notation e.g; ^@ for
null or ^L for form feed.
scrollBar =>0
--scrollbar
Display an interactive scrollbar in the right-most column.
squeeze =>0
Collapse multiple blank lines into one.
statusCol =>0
Add a column with markers indicating which row match a search expression.
visualBell =>0
Flash the screen when beeping.
Accessors
There are accessors for all of the above properties, however those for rows, cols, speed,
fold and squeeze are read only.
#Is visualBell set?
$t->visualBell();
#Enable line numbering
$t->lineNo(1);
Adding Text
You will need some text to page through. You can specify text as as a parameter to the
constructor:
text => $text
Or even add text later:
$t->add_text( $text );
If you wish 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.
Callback
You can also pass a code reference to the text attribute of the constructor which will be
called when reaching the "end of file"; consequently, it is not possible to set the eof
flag to exit at end of file if doing so.
$t->new( text=>sub{ } ); #eof=>0 is implied
Alternatively, you may supply a reference to a two element array. The first is an initial
chunk of text to load, and the second the callback.
#Fibonacci
my($m, $n)=(1,1);
$t->new( text=> ["1\n", sub{ ($m,$n)=($n,$m+$n); return "$n\n"} ] );
User Interface
There are multiple special bookmarks (marks) that can be used in navigation.
^ Beginning of file
$ End of file
' Previous location
" List user-created marks
"add_text" will automatically create special numeric marks when it encounters a special
character sequence, allowing the user to jump to predetermined points in the buffer.
Sequence that match the following regular expression
/\cF\c]\cL\cE \[(\d+)\// #e.g; ^F^]^L^E [3/4]
will have marks matching $1 created that point at the line of the buffer the sequence
occurs on.
CUSTOMIZATION
add_func
It is possible to extend the features of IO::Pager::Perl 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 mappings
are listed below, and lengthier descriptions are available in tp.
General
&help - "h" or "H"
&close - "q" or "Q" or ":q" or ":Q"
&refresh - "r" or "C-l" or "C-R"
&flush_buffer - "R"
&write_buffer - ":w"
&open_file - ":e"
Navigation
&downline - "ENTER" or "e" or "j" or "J" or "C-e" or "C-n" or "down arrow"
&downhalf - "d" or "C-d"
&downpage - "SPACE" "f" or "z" or "C-f" or "C-v" or "M-space" or "PgDn"
&uppage - "b" or "w" or "C-b" or "M-v" or "PgUp"
&uphalf - "u" or "C-u"
&upline - "k" or "y" or "K" or "Y" or "C-K" or "C-P" or "C-Y" or "up arrow"
&to_bott - "G" or "$" or ">" or "M->" or "End"
&to_top - "g" or "<" or "M-<"
&tab_left - "left arrow"
&shift_left - "S-left arrow"
&tab_right - "right arrow"
&shift_right - "S-right arrow"
&next_file - ":n" or "S-M-right arrow"
&prev_file - ":p" or "S-M-left arrow"
And a special sequence of a number followed by enter analogous to:
'/(\d+)/' => \&jump(\1)
if the value for that key is true.
Bookmarks
&save_mark - "m" or "Ins"
&goto_mark - "'"
Search
&search - /
&hcraes - ?
&next_match - n or P
&prev_match - p or N
&grep - &
Options
&toggle_num - #
&toggle_fold - S
&toggle_raw - C
I18N
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 = IO::Pager::Perl->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('minihelp', "<h> help");
Current text elements available for customization are:
404 - search text not found dialog
continue - text to display at the bottom of the help dialog
help - help dialog text, a list of keys and their functions
minihelp - basic instructions displayed at the bottom of the screen
status - brief message to include in the status line
top - start of file prompt
bottom - end of file prompt
searchwrap - message that pager is about to loop for more matches
prompt is intended for sharing short messages not worthy of a dialog e.g; when debugging.
You will need to call the "status" method after setting it to refresh the status line of
the display, then void prompt and call "status" again to clear the message.
Scalability
The help text will be split in two horizontally on a null character if the text is wider
than the display, and shown in two sequential dialogs.
Similarly, the status text will be cropped at a null character for narrow displays.
CAVEATS
UN*X
This modules currently only works in a UN*X-like environment.
Performance
For simplicity, the current implementation loads the entire message to view at once; thus
not requiring a distinction between piped contents and files. This may require
significant memory for large files.
Termcap
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.
Eventually, support for Terminfo may also be added.
Signals
IO::Pager::Perl sets a global signal handler for SIGWINCH, this is the only way it can
effectively detect and accommodate changes in terminal size. If you also need
notification of this signal, the handler will trigger any callback assigned to the WINCH
attribute of the "new" method.
WINCH is not available on Windows. You will need to manually refresh your screen ^L if you
resize the terminal in Windows to clean up the text however, this will not change the size
of the pager itself.
ENVIRONMENT
IO::Pager::Perl checks the TERM and TERMCAP variables.
SEE ALSO
IO::Pager, Term::Cap, Term::ReadKey, termcap(5), stty(1), tput(1), less(1)
AUTHORS
Jerrad Pierce jpierce@cpan.org
Jeff Weisberg - http://www.tcp4me.com
LICENSE
This software may be copied and distributed under the terms found in the Perl "Artistic
License".
A copy of the "Artistic License" may be found in the standard Perl distribution.