.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IO::Pager::Perl 3pm"
.TH IO::Pager::Perl 3pm "2020-11-07" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::Pager::Perl \- Page text a screenful at a time, like more or less
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    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();
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
IO::Pager::Perl is an enhanced fork of Term::Pager.
.SH "USAGE"
.IX Header "USAGE"
.SS "Create the Pager"
.IX Subsection "Create the Pager"
.Vb 1
\&    $t = IO::Pager::Perl\->new( option => value, ... );
.Ve
.PP
If no options are specified, sensible default values will be used.
The following options are recognized, and shown with the default value:
.IP "\fIrows\fR =>25?" 4
.IX Item "rows =>25?"
The number of rows on your terminal.  The terminal is queried directly
with Term::ReadKey if loaded or \f(CW\*(C`stty\*(C'\fR or \f(CW\*(C`tput\*(C'\fR, and if these fail
it defaults to 25.
.IP "\fIcols\fR =>80?" 4
.IX Item "cols =>80?"
The number of columns on your terminal. The terminal is queried directly
with Term::ReadKey if loaded or \f(CW\*(C`stty\*(C'\fR or \f(CW\*(C`tput\*(C'\fR, and if these fail it
defaults to 80.
.IP "\fIspeed\fR =>38400?" 4
.IX Item "speed =>38400?"
The speed (baud rate) of your terminal. The terminal is queried directly
with Term::ReadKey if loaded or \f(CW\*(C`stty\*(C'\fR, and if these fail it defaults to
a sensible value.
.IP "\fIeof\fR =>0" 4
.IX Item "eof =>0"
Exit at end of file.
.IP "\fIfold\fR =>1" 4
.IX Item "fold =>1"
Fold long lines with Text::Wrap.
.IP "\fIlineNo\fR =>0" 4
.IX Item "lineNo =>0"
If true, line numbering is added to the output.
.IP "\fIpause\fR =>0" 4
.IX Item "pause =>0"
If defined, the pager will pause when the this character sequence is
encountered in the input text. Set to ^L i.e; \*(L"\ecL\*(R" to mimic traditional
behavior of \*(L"1\*(R" in more.
.IP "\fIraw\fR =>0" 4
.IX Item "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.
.IP "\fIscrollBar\fR =>0" 4
.IX Item "scrollBar =>0"
.PD 0
.IP "\fB\-\-scrollbar\fR" 4
.IX Item "--scrollbar"
.PD
Display an interactive scrollbar in the right-most column.
.IP "\fIsqueeze\fR =>0" 4
.IX Item "squeeze =>0"
Collapse multiple blank lines into one.
.IP "\fIstatusCol\fR =>0" 4
.IX Item "statusCol =>0"
Add a column with markers indicating which row match a search expression.
.IP "\fIvisualBell\fR =>0" 4
.IX Item "visualBell =>0"
Flash the screen when beeping.
.PP
\fIAccessors\fR
.IX Subsection "Accessors"
.PP
There are accessors for all of the above properties, however those for
rows, cols, speed, fold and squeeze are read only.
.PP
.Vb 2
\&  #Is visualBell set?
\&  $t\->visualBell();
\&
\&  #Enable line numbering
\&  $t\->lineNo(1);
.Ve
.SS "Adding Text"
.IX Subsection "Adding Text"
You will need some text to page through. You can specify text as
as a parameter to the constructor:
.PP
.Vb 1
\&    text => $text
.Ve
.PP
Or even add text later:
.PP
.Vb 1
\&    $t\->add_text( $text );
.Ve
.PP
If you wish to continuously add text to the pager, you must setup your own
event loop, and indicate to \f(CW\*(C`more\*(C'\fR that it should relinquish control e.g;
.PP
.Vb 6
\&    eval{
\&        while( $t\->more(RT=>.05) ){
\&          ...
\&          $t\->add_text("More text to page");
\&        }
\&    };
.Ve
.PP
The eval block captures the exception thrown upon termination of the pager
so that your own program may continue. The \fI\s-1RT\s0\fR parameter indicates that
you wish to provide content in real time. This value is also passed to
\&\*(L"ReadKey\*(R" 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.
.PP
\&\s-1NOTE:\s0 If Term::ReadKey is not loaded but \s-1RT\s0 is true, screen updates will only
occur on keypress.
.PP
\fICallback\fR
.IX Subsection "Callback"
.PP
You can also pass a code reference to the \fItext\fR attribute of the constructor
which will be called when reaching the \*(L"end of file\*(R"; consequently, it is not
possible to set the \fIeof\fR flag to exit at end of file if doing so.
.PP
.Vb 1
\&    $t\->new( text=>sub{ } ); #eof=>0 is implied
.Ve
.PP
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.
.PP
.Vb 3
\&    #Fibonacci
\&    my($m, $n)=(1,1);
\&    $t\->new( text=> ["1\en", sub{ ($m,$n)=($n,$m+$n); return "$n\en"} ] );
.Ve
.SS "User Interface"
.IX Subsection "User Interface"
There are multiple special bookmarks (marks) that can be used in navigation.
.IP "^ Beginning of file" 4
.IX Item "^ Beginning of file"
.PD 0
.IP "$ End of file" 4
.IX Item "$ End of file"
.IP "' Previous location" 4
.IX Item "' Previous location"
.IP """ List user-created marks" 4
.IX Item """ List user-created marks"
.PD
.PP
\&\f(CW\*(C`add_text\*(C'\fR 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
.PP
.Vb 1
\&     /\ecF\ec]\ecL\ecE \e[(\ed+)\e// #e.g; ^F^]^L^E [3/4]
.Ve
.PP
will have marks matching \f(CW$1\fR created that point at the line of the buffer the
sequence occurs on.
.SH "CUSTOMIZATION"
.IX Header "CUSTOMIZATION"
.SS "add_func"
.IX Subsection "add_func"
It is possible to extend the features of IO::Pager::Perl by supplying the
\&\f(CW\*(C`add_func\*(C'\fR method with a hash of character keys and callback values to be
invoked upon matching keypress; where \ec? represents Control\-? and \ee?
represents Alt\-? The existing mappings are listed below, and lengthier
descriptions are available in tp.
.PP
\fIGeneral\fR
.IX Subsection "General"
.ie n .IP "&help \- ""h"" or ""H""" 4
.el .IP "&help \- \f(CWh\fR or \f(CWH\fR" 4
.IX Item "&help - h or H"
.PD 0
.ie n .IP "&close \- ""q"" or ""Q"" or "":q"" or "":Q""" 4
.el .IP "&close \- \f(CWq\fR or \f(CWQ\fR or \f(CW:q\fR or \f(CW:Q\fR" 4
.IX Item "&close - q or Q or :q or :Q"
.ie n .IP "&refresh \- ""r"" or ""C\-l"" or ""C\-R""" 4
.el .IP "&refresh \- \f(CWr\fR or \f(CWC\-l\fR or \f(CWC\-R\fR" 4
.IX Item "&refresh - r or C-l or C-R"
.ie n .IP "&flush_buffer \- ""R""" 4
.el .IP "&flush_buffer \- \f(CWR\fR" 4
.IX Item "&flush_buffer - R"
.ie n .IP "&write_buffer \- "":w""" 4
.el .IP "&write_buffer \- \f(CW:w\fR" 4
.IX Item "&write_buffer - :w"
.ie n .IP "&open_file \- "":e""" 4
.el .IP "&open_file \- \f(CW:e\fR" 4
.IX Item "&open_file - :e"
.PD
.PP
\fINavigation\fR
.IX Subsection "Navigation"
.ie n .IP "&downline \- ""ENTER"" or ""e"" or ""j"" or ""J"" or ""C\-e"" or ""C\-n"" or ""down arrow""" 4
.el .IP "&downline \- \f(CWENTER\fR or \f(CWe\fR or \f(CWj\fR or \f(CWJ\fR or \f(CWC\-e\fR or \f(CWC\-n\fR or \f(CWdown arrow\fR" 4
.IX Item "&downline - ENTER or e or j or J or C-e or C-n or down arrow"
.PD 0
.ie n .IP "&downhalf \- ""d"" or ""C\-d""" 4
.el .IP "&downhalf \- \f(CWd\fR or \f(CWC\-d\fR" 4
.IX Item "&downhalf - d or C-d"
.ie n .IP "&downpage \- ""SPACE"" ""f"" or ""z"" or ""C\-f"" or ""C\-v"" or ""M\-space"" or ""PgDn""" 4
.el .IP "&downpage \- \f(CWSPACE\fR \f(CWf\fR or \f(CWz\fR or \f(CWC\-f\fR or \f(CWC\-v\fR or \f(CWM\-space\fR or \f(CWPgDn\fR" 4
.IX Item "&downpage - SPACE f or z or C-f or C-v or M-space or PgDn"
.ie n .IP "&uppage \- ""b"" or ""w"" or ""C\-b"" or ""M\-v"" or ""PgUp""" 4
.el .IP "&uppage \- \f(CWb\fR or \f(CWw\fR or \f(CWC\-b\fR or \f(CWM\-v\fR or \f(CWPgUp\fR" 4
.IX Item "&uppage - b or w or C-b or M-v or PgUp"
.ie n .IP "&uphalf \- ""u"" or ""C\-u""" 4
.el .IP "&uphalf \- \f(CWu\fR or \f(CWC\-u\fR" 4
.IX Item "&uphalf - u or C-u"
.ie n .IP "&upline \- ""k"" or ""y"" or ""K"" or ""Y"" or ""C\-K"" or ""C\-P"" or ""C\-Y"" or ""up arrow""" 4
.el .IP "&upline \- \f(CWk\fR or \f(CWy\fR or \f(CWK\fR or \f(CWY\fR or \f(CWC\-K\fR or \f(CWC\-P\fR or \f(CWC\-Y\fR or \f(CWup arrow\fR" 4
.IX Item "&upline - k or y or K or Y or C-K or C-P or C-Y or up arrow"
.ie n .IP "&to_bott \- ""G"" or ""$"" or "">"" or ""M\->"" or ""End""" 4
.el .IP "&to_bott \- \f(CWG\fR or \f(CW$\fR or \f(CW>\fR or \f(CWM\->\fR or \f(CWEnd\fR" 4
.IX Item "&to_bott - G or $ or > or M-> or End"
.ie n .IP "&to_top \- ""g"" or ""<"" or ""M\-<""" 4
.el .IP "&to_top \- \f(CWg\fR or \f(CW<\fR or \f(CWM\-<\fR" 4
.IX Item "&to_top - g or < or M-<"
.ie n .IP "&tab_left \- ""left arrow""" 4
.el .IP "&tab_left \- \f(CWleft arrow\fR" 4
.IX Item "&tab_left - left arrow"
.ie n .IP "&shift_left \- ""S\-left arrow""" 4
.el .IP "&shift_left \- \f(CWS\-left arrow\fR" 4
.IX Item "&shift_left - S-left arrow"
.ie n .IP "&tab_right \- ""right arrow""" 4
.el .IP "&tab_right \- \f(CWright arrow\fR" 4
.IX Item "&tab_right - right arrow"
.ie n .IP "&shift_right \- ""S\-right arrow""" 4
.el .IP "&shift_right \- \f(CWS\-right arrow\fR" 4
.IX Item "&shift_right - S-right arrow"
.ie n .IP "&next_file \- "":n"" or ""S\-M\-right arrow""" 4
.el .IP "&next_file \- \f(CW:n\fR or \f(CWS\-M\-right arrow\fR" 4
.IX Item "&next_file - :n or S-M-right arrow"
.ie n .IP "&prev_file \- "":p"" or ""S\-M\-left arrow""" 4
.el .IP "&prev_file \- \f(CW:p\fR or \f(CWS\-M\-left arrow\fR" 4
.IX Item "&prev_file - :p or S-M-left arrow"
.PD
.PP
And a special sequence of a number followed by enter analogous to:
.PP
.Vb 1
\&        \*(Aq/(\ed+)/\*(Aq   => \e&jump(\e1)
.Ve
.PP
if the value for that key is true.
.PP
\fIBookmarks\fR
.IX Subsection "Bookmarks"
.ie n .IP "&save_mark \- ""m"" or ""Ins""" 4
.el .IP "&save_mark \- \f(CWm\fR or \f(CWIns\fR" 4
.IX Item "&save_mark - m or Ins"
.PD 0
.ie n .IP "&goto_mark \- ""\*(Aq""" 4
.el .IP "&goto_mark \- \f(CW\*(Aq\fR" 4
.IX Item "&goto_mark - "
.PD
.PP
\fISearch\fR
.IX Subsection "Search"
.IP "&search \- /" 4
.IX Item "&search - /"
.PD 0
.IP "&hcraes \- ?" 4
.IX Item "&hcraes - ?"
.IP "&next_match \- n or P" 4
.IX Item "&next_match - n or P"
.IP "&prev_match \- p or N" 4
.IX Item "&prev_match - p or N"
.IP "&grep \- &" 4
.IX Item "&grep - &"
.PD
.PP
\fIOptions\fR
.IX Subsection "Options"
.IP "&toggle_num \- #" 4
.IX Item "&toggle_num - #"
.PD 0
.IP "&toggle_fold \- S" 4
.IX Item "&toggle_fold - S"
.IP "&toggle_raw \- C" 4
.IX Item "&toggle_raw - C"
.PD
.SS "I18N"
.IX Subsection "I18N"
The \f(CW\*(C`dialog\*(C'\fR 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.
.PP
.Vb 4
\&    my $t = IO::Pager::Perl\->new();
\&    $t\->add_text("Text to display");
\&    $t\->add_func(\*(Aq!\*(Aq=>\e&boo);
\&    $t\->more();
\&
\&    sub boo{ my $self = shift; $self\->dialog("BOO!", 1); }
.Ve
.PP
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
\&\f(CW\*(C`I18N\*(C'\fR method to replace the default text or save text for your own interface.
.PP
.Vb 2
\&    #Get the default help text
\&    my $help = $t\->I18N(\*(Aqhelp\*(Aq);
\&
\&    #Minimal status line
\&    $t\->I18N(\*(Aqminihelp\*(Aq, "<h> help");
.Ve
.PP
Current text elements available for customization are:
.PP
.Vb 8
\&    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
.Ve
.PP
\&\fIprompt\fR is intended for sharing short messages not worthy of a dialog
e.g; when debugging. You will need to call the \f(CW\*(C`status\*(C'\fR method after
setting it to refresh the status line of the display, then void \fIprompt\fR
and call \f(CW\*(C`status\*(C'\fR again to clear the message.
.PP
\fIScalability\fR
.IX Subsection "Scalability"
.PP
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.
.PP
Similarly, the status text will be cropped at a null character for narrow
displays.
.SH "CAVEATS"
.IX Header "CAVEATS"
.SS "UN*X"
.IX Subsection "UN*X"
This modules currently only works in a UN*X\-like environment.
.SS "Performance"
.IX Subsection "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.
.SS "Termcap"
.IX Subsection "Termcap"
This module uses Termcap, which has been deprecated the Open Group,
and may not be supported by your operating system for much longer.
.PP
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.
.PP
Eventually, support for Terminfo may also be added.
.SS "Signals"
.IX Subsection "Signals"
IO::Pager::Perl sets a global signal handler for \fI\s-1SIGWINCH\s0\fR, 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 \fI\s-1WINCH\s0\fR attribute of the \f(CW\*(C`new\*(C'\fR method.
.PP
\&\fI\s-1WINCH\s0\fR is not available on Windows. You will need to manually refresh your
screen \fB^L\fR if you resize the terminal in Windows to clean up the text
however, this will not change the size of the pager itself.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
IO::Pager::Perl checks the \fI\s-1TERM\s0\fR and \fI\s-1TERMCAP\s0\fR variables.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IO::Pager, Term::Cap, Term::ReadKey,
\&\fBtermcap\fR\|(5), \fBstty\fR\|(1), \fBtput\fR\|(1), \fBless\fR\|(1)
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 1
\&    Jerrad Pierce jpierce@cpan.org
\&
\&    Jeff Weisberg \- http://www.tcp4me.com
.Ve
.SH "LICENSE"
.IX Header "LICENSE"
This software may be copied and distributed under the terms
found in the Perl \*(L"Artistic License\*(R".
.PP
A copy of the \*(L"Artistic License\*(R" may be found in the standard
Perl distribution.