1IO::Pager::Perl(3) User Contributed Perl Documentation IO::Pager::Perl(3)
2
6 IO::Pager::Perl - Page text a screenful at a time, like more or less
7
9 use Term:ReadKey; #Optional, but recommended
10 use IO::Pager::Perl;
11 my $t = IO::Pager::Perl->new( rows => 25, cols => 80 );
13 $t->add_text( $text );
14 $t->more();
15
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 IO::Pager::Perl is an enhanced fork of Term::Pager.
21
23 Create the Pager
24 $t = IO::Pager::Perl->new( option => value, ... );
25 If no options are specified, sensible default values will be used. The
27 following options are recognized, and shown with the default value:
28 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 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 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 eof =>0
45 Exit at end of file.
46 fold =>1
48 Fold long lines with Text::Wrap.
49 lineNo =>0
51 If true, line numbering is added to the output.
52 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 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 scrollBar =>0
64 --scrollbar
65 Display an interactive scrollbar in the right-most column.
66 squeeze =>0
68 Collapse multiple blank lines into one.
69 statusCol =>0
71 Add a column with markers indicating which row match a search
72 expression.
73 visualBell =>0
75 Flash the screen when beeping.
76 Accessors
78 There are accessors for all of the above properties, however those for
80 rows, cols, speed, fold and squeeze are read only.
81 #Is visualBell set?
83 $t->visualBell();
84 #Enable line numbering
86 $t->lineNo(1);
87 Adding Text
89 You will need some text to page through. You can specify text as as a
90 parameter to the constructor:
91 text => $text
93 Or even add text later:
95 $t->add_text( $text );
97 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 eval{
103 while( $t->more(RT=>.05) ){
104 ...
105 $t->add_text("More text to page");
106 }
107 };
108 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 NOTE: If Term::ReadKey is not loaded but RT is true, screen updates
119 will only occur on keypress.
120 Callback
122 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 $t->new( text=>sub{ } ); #eof=>0 is implied
129 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 #Fibonacci
134 my($m, $n)=(1,1);
135 $t->new( text=> ["1\n", sub{ ($m,$n)=($n,$m+$n); return "$n\n"} ] );
136 User Interface
138 There are multiple special bookmarks (marks) that can be used in
139 navigation.
140 ^ Beginning of file
142 $ End of file
143 ' Previous location
144 " List user-created marks
145 "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 /\cF\c]\cL\cE \[(\d+)\// #e.g; ^F^]^L^E [3/4]
152 will have marks matching $1 created that point at the line of the
154 buffer the sequence occurs on.
155
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 General
165 &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 Navigation
174 &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 And a special sequence of a number followed by enter analogous to:
193 '/(\d+)/' => \&jump(\1)
195 if the value for that key is true.
197 Bookmarks
199 &save_mark - "m" or "Ins"
201 &goto_mark - "'"
202 Search
204 &search - /
206 &hcraes - ?
207 &next_match - n or P
208 &prev_match - p or N
209 &grep - &
210 Options
212 &toggle_num - #
214 &toggle_fold - S
215 &toggle_raw - C
216 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 my $t = IO::Pager::Perl->new();
224 $t->add_text("Text to display");
225 $t->add_func('!'=>\&boo);
226 $t->more();
227 sub boo{ my $self = shift; $self->dialog("BOO!", 1); }
229 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 #Get the default help text
236 my $help = $t->I18N('help');
237 #Minimal status line
239 $t->I18N('minihelp', "<h> help");
240 Current text elements available for customization are:
242 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 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 Scalability
258 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 Similarly, the status text will be cropped at a null character for
264 narrow displays.
265
267 UN*X
268 This modules currently only works in a UN*X-like environment.
269 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 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 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 Eventually, support for Terminfo may also be added.
284 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 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
297 IO::Pager::Perl checks the TERM and TERMCAP variables.
298
300 IO::Pager, Term::Cap, Term::ReadKey, termcap(5), stty(1), tput(1),
301 less(1)
302
304 Jerrad Pierce jpierce@cpan.org
305 Jeff Weisberg - http://www.tcp4me.com
307
309 This software may be copied and distributed under the terms found in
310 the Perl "Artistic License".
311 A copy of the "Artistic License" may be found in the standard Perl
313 distribution.
314perl v5.36.0 2022-07-22 IO::Pager::Perl(3)