1IO::Pager::Perl(3)    User Contributed Perl Documentation   IO::Pager::Perl(3)
2
3
4

NAME

6       IO::Pager::Perl - Page text a screenful at a time, like more or less
7

SYNOPSIS

9           use Term:ReadKey; #Optional, but recommended
10           use IO::Pager::Perl;
11
12           my $t = IO::Pager::Perl->new( rows => 25, cols => 80 );
13           $t->add_text( $text );
14           $t->more();
15

DESCRIPTION

17       This is a module for paging through text one screenful at a time.  It
18       supports the features you expect using the shortcuts you expect.
19
20       IO::Pager::Perl is an enhanced fork of Term::Pager.
21

USAGE

23   Create the Pager
24           $t = IO::Pager::Perl->new( option => value, ... );
25
26       If no options are specified, sensible default values will be used.  The
27       following options are recognized, and shown with the default value:
28
29       rows =>25?
30           The number of rows on your terminal.  The terminal is queried
31           directly with Term::ReadKey if loaded or "stty" or "tput", and if
32           these fail it defaults to 25.
33
34       cols =>80?
35           The number of columns on your terminal. The terminal is queried
36           directly with Term::ReadKey if loaded or "stty" or "tput", and if
37           these fail it defaults to 80.
38
39       speed =>38400?
40           The speed (baud rate) of your terminal. The terminal is queried
41           directly with Term::ReadKey if loaded or "stty", and if these fail
42           it defaults to a sensible value.
43
44       eof =>0
45           Exit at end of file.
46
47       fold =>1
48           Fold long lines with Text::Wrap.
49
50       lineNo =>0
51           If true, line numbering is added to the output.
52
53       pause =>0
54           If defined, the pager will pause when the this character sequence
55           is encountered in the input text. Set to ^L i.e; "\cL" to mimic
56           traditional behavior of "1" in more.
57
58       raw =>0
59           Pass control characters from input unadulterated to the terminal.
60           By default, chracters other than tab and newline will be converted
61           to caret notation e.g; ^@ for null or ^L for form feed.
62
63       scrollBar =>0
64       --scrollbar
65           Display an interactive scrollbar in the right-most column.
66
67       squeeze =>0
68           Collapse multiple blank lines into one.
69
70       statusCol =>0
71           Add a column with markers indicating which row match a search
72           expression.
73
74       visualBell =>0
75           Flash the screen when beeping.
76
77       Accessors
78
79       There are accessors for all of the above properties, however those for
80       rows, cols, speed, fold and squeeze are read only.
81
82         #Is visualBell set?
83         $t->visualBell();
84
85         #Enable line numbering
86         $t->lineNo(1);
87
88   Adding Text
89       You will need some text to page through. You can specify text as as a
90       parameter to the constructor:
91
92           text => $text
93
94       Or even add text later:
95
96           $t->add_text( $text );
97
98       If you wish to continuously add text to the pager, you must setup your
99       own event loop, and indicate to "more" that it should relinquish
100       control e.g;
101
102           eval{
103               while( $t->more(RT=>.05) ){
104                 ...
105                 $t->add_text("More text to page");
106               }
107           };
108
109       The eval block captures the exception thrown upon termination of the
110       pager so that your own program may continue. The RT parameter indicates
111       that you wish to provide content in real time. This value is also
112       passed to "ReadKey" in Term::ReadKey as the maximum blocking time per
113       keypress and should be between 0 and 1, with larger values trading
114       greater interface responsiveness for slight delays in output. A value
115       of -1 may also be used to request non-blocking polls, but likely will
116       not behave as you would hope.
117
118       NOTE: If Term::ReadKey is not loaded but RT is true, screen updates
119       will only occur on keypress.
120
121       Callback
122
123       You can also pass a code reference to the text attribute of the
124       constructor which will be called when reaching the "end of file";
125       consequently, it is not possible to set the eof flag to exit at end of
126       file if doing so.
127
128           $t->new( text=>sub{ } ); #eof=>0 is implied
129
130       Alternatively, you may supply a reference to a two element array. The
131       first is an initial chunk of text to load, and the second the callback.
132
133           #Fibonacci
134           my($m, $n)=(1,1);
135           $t->new( text=> ["1\n", sub{ ($m,$n)=($n,$m+$n); return "$n\n"} ] );
136
137   User Interface
138       There are multiple special bookmarks (marks) that can be used in
139       navigation.
140
141       ^ Beginning of file
142       $ End of file
143       ' Previous location
144       " List user-created marks
145
146       "add_text" will automatically create special numeric marks when it
147       encounters a special character sequence, allowing the user to jump to
148       predetermined points in the buffer. Sequence that match the following
149       regular expression
150
151            /\cF\c]\cL\cE \[(\d+)\// #e.g; ^F^]^L^E [3/4]
152
153       will have marks matching $1 created that point at the line of the
154       buffer the sequence occurs on.
155

CUSTOMIZATION

157   add_func
158       It is possible to extend the features of IO::Pager::Perl by supplying
159       the "add_func" method with a hash of character keys and callback values
160       to be invoked upon matching keypress; where \c? represents Control-?
161       and \e?  represents Alt-? The existing mappings are listed below, and
162       lengthier descriptions are available in tp.
163
164       General
165
166       &help - "h" or "H"
167       &close - "q" or "Q" or ":q" or ":Q"
168       &refresh - "r" or "C-l" or "C-R"
169       &flush_buffer - "R"
170       &write_buffer - ":w"
171       &open_file - ":e"
172
173       Navigation
174
175       &downline - "ENTER" or "e" or "j" or "J" or "C-e" or "C-n" or "down
176       arrow"
177       &downhalf - "d" or "C-d"
178       &downpage - "SPACE" "f" or "z" or "C-f" or "C-v" or "M-space" or "PgDn"
179       &uppage - "b" or "w" or "C-b" or "M-v" or "PgUp"
180       &uphalf - "u" or "C-u"
181       &upline - "k" or "y" or "K" or "Y" or "C-K" or "C-P" or "C-Y" or "up
182       arrow"
183       &to_bott - "G" or "$" or ">" or "M->" or "End"
184       &to_top - "g" or "<" or "M-<"
185       &tab_left - "left arrow"
186       &shift_left - "S-left arrow"
187       &tab_right - "right arrow"
188       &shift_right - "S-right arrow"
189       &next_file - ":n" or "S-M-right arrow"
190       &prev_file - ":p" or "S-M-left arrow"
191
192       And a special sequence of a number followed by enter analogous to:
193
194               '/(\d+)/'   => \&jump(\1)
195
196       if the value for that key is true.
197
198       Bookmarks
199
200       &save_mark - "m" or "Ins"
201       &goto_mark - "'"
202
203       Search
204
205       &search - /
206       &hcraes - ?
207       &next_match - n or P
208       &prev_match - p or N
209       &grep - &
210
211       Options
212
213       &toggle_num - #
214       &toggle_fold - S
215       &toggle_raw - C
216
217   I18N
218       The "dialog" method may be particularly useful when enhancing the
219       pager.  It accepts a string to display, and an optional timeout to
220       sleep for before the dialog is cleared. If the timeout is missing or 0,
221       the dialog remains until a key is pressed.
222
223           my $t = IO::Pager::Perl->new();
224           $t->add_text("Text to display");
225           $t->add_func('!'=>\&boo);
226           $t->more();
227
228           sub boo{ my $self = shift; $self->dialog("BOO!", 1); }
229
230       Should you add additional functionality to your pager, you will likely
231       want to change the contents of the help dialog or possibly the status
232       line. Use the "I18N" method to replace the default text or save text
233       for your own interface.
234
235           #Get the default help text
236           my $help = $t->I18N('help');
237
238           #Minimal status line
239           $t->I18N('minihelp', "<h> help");
240
241       Current text elements available for customization are:
242
243           404        - search text not found dialog
244           continue   - text to display at the bottom of the help dialog
245           help       - help dialog text, a list of keys and their functions
246           minihelp   - basic instructions displayed at the bottom of the screen
247           status     - brief message to include in the status line
248           top        - start of file prompt
249           bottom     - end of file prompt
250           searchwrap - message that pager is about to loop for more matches
251
252       prompt is intended for sharing short messages not worthy of a dialog
253       e.g; when debugging. You will need to call the "status" method after
254       setting it to refresh the status line of the display, then void prompt
255       and call "status" again to clear the message.
256
257       Scalability
258
259       The help text will be split in two horizontally on a null character if
260       the text is wider than the display, and shown in two sequential
261       dialogs.
262
263       Similarly, the status text will be cropped at a null character for
264       narrow displays.
265

CAVEATS

267   UN*X
268       This modules currently only works in a UN*X-like environment.
269
270   Performance
271       For simplicity, the current implementation loads the entire message to
272       view at once; thus not requiring a distinction between piped contents
273       and files.  This may require significant memory for large files.
274
275   Termcap
276       This module uses Termcap, which has been deprecated the Open Group, and
277       may not be supported by your operating system for much longer.
278
279       If the termcap entry for your ancient esoteric terminal is wrong or
280       incomplete, this module may either fill your screen with unintelligible
281       gibberish, or drop back to a feature-free mode.
282
283       Eventually, support for Terminfo may also be added.
284
285   Signals
286       IO::Pager::Perl sets a global signal handler for SIGWINCH, this is the
287       only way it can effectively detect and accommodate changes in terminal
288       size.  If you also need notification of this signal, the handler will
289       trigger any callback assigned to the WINCH attribute of the "new"
290       method.
291
292       WINCH is not available on Windows. You will need to manually refresh
293       your screen ^L if you resize the terminal in Windows to clean up the
294       text however, this will not change the size of the pager itself.
295

ENVIRONMENT

297       IO::Pager::Perl checks the TERM and TERMCAP variables.
298

SEE ALSO

300       IO::Pager, Term::Cap, Term::ReadKey, termcap(5), stty(1), tput(1),
301       less(1)
302

AUTHORS

304           Jerrad Pierce jpierce@cpan.org
305
306           Jeff Weisberg - http://www.tcp4me.com
307

LICENSE

309       This software may be copied and distributed under the terms found in
310       the Perl "Artistic License".
311
312       A copy of the "Artistic License" may be found in the standard Perl
313       distribution.
314
315
316
317perl v5.36.0                      2022-07-22                IO::Pager::Perl(3)
Impressum