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 squeeze =>0
64 Collapse multiple blank lines into one.
65 statusCol =>0
67 Add a column with markers indicating which row match a search
68 expression.
69 visualBell =>0
71 Flash the screen when beeping.
72 Accessors
74 There are accessors for all of the above properties, however those for
76 rows, cols, speed, fold and squeeze are read only.
77 #Is visualBell set?
79 $t->visualBell();
80 #Enable line numbering
82 $t->lineNo(1);
83 Adding Text
85 You will need some text to page through. You can specify text as as a
86 parameter to the constructor:
87 text => $text
89 Or even add text later:
91 $t->add_text( $text );
93 If you wish to continuously add text to the pager, you must setup your
95 own event loop, and indicate to "more" that it should relinquish
96 control e.g;
97 eval{
99 while( $t->more(RT=>.05) ){
100 ...
101 $t->add_text("More text to page");
102 }
103 };
104 The eval block captures the exception thrown upon termination of the
106 pager so that your own program may continue. The RT parameter indicates
107 that you wish to provide content in real time. This value is also
108 passed to "ReadKey" in Term::ReadKey as the maximum blocking time per
109 keypress and should be between 0 and 1, with larger values trading
110 greater interface responsiveness for slight delays in output. A value
111 of -1 may also be used to request non-blocking polls, but likely will
112 not behave as you would hope.
113 NOTE: If Term::ReadKey is not loaded but RT is true, screen updates
115 will only occur on keypress.
116 Callback
118 You can also pass a code reference to the text attribute of the
120 constructor which will be called when reaching the "end of file";
121 consequently, it is not possible to set the eof flag to exit at end of
122 file if doing so.
123 $t->new( text=>sub{ } ); #eof=>0 is implied
125 Alternatively, you may supply a reference to a two element array. The
127 first is an initial chunk of text to load, and the second the callback.
128 #Fibonacci
130 my($m, $n)=(1,1);
131 $t->new( text=> ["1\n", sub{ ($m,$n)=($n,$m+$n); return "$n\n"} ] );
132 User Interface
134 There are multiple special bookmarks (marks) that can be used in
135 navigation.
136 ^ Beginning of file
138 $ End of file
139 ' Previous location
140 " List user-created marks
141 "add_text" will automatically create special numeric marks when it
143 encounters a special character sequence, allowing the user to jump to
144 predetermined points in the buffer. Sequence that match the following
145 regular expression
146 /\cF\c]\cL\cE \[(\d+)\// #e.g; ^F^]^L^E [3/4]
148 will have marks matching $1 created that point at the line of the
150 buffer the sequence occurs on.
151
153 add_func
154 It is possible to extend the features of IO::Pager::Perl by supplying
155 the "add_func" method with a hash of character keys and callback values
156 to be invoked upon matching keypress; where \c? represents Control-?
157 and \e? represents Alt-? The existing mappings are listed below, and
158 lengthier descriptions are available in tp.
159 General
161 &help - "h" or "H"
163 &close - "q" or "Q" or ":q" or ":Q"
164 &refresh - "r" or "C-l" or "C-R"
165 &flush_buffer - "R"
166 &write_buffer - ":w"
167 Navigation
169 &downline - "ENTER" or "e" or "j" or "J" or "C-e" or "C-n" or "down
171 arrow"
172 &downhalf - "d" or "C-d"
173 &downpage - "SPACE" "f" or "z" or "C-f" or "C-v" or "M-space" or "PgDn"
174 &uppage - "b" or "w" or "C-b" or "M-v" or "PgUp"
175 &uphalf - "u" or "C-u"
176 &upline - "k" or "y" or "K" or "Y" or "C-K" or "C-P" or "C-Y" or "up
177 arrow"
178 &to_bott - "G" or "$" or ">" or "M->" or "End"
179 &to_top - "g" or "<" or "M-<"
180 &tab_left - "left arrow"
181 &shift_left - "S-left arrow"
182 &tab_right - "right arrow"
183 &shift_right - "S-right arrow"
184 &next_file - ":n" or "S-M-right arrow"
185 &prev_file - ":p" or "S-M-left arrow"
186 And a special sequence of a number followed by enter analogous to:
188 '/(\d+)/' => \&jump(\1)
190 if the value for that key is true.
192 Bookmarks
194 &save_mark - "m" or "Ins"
196 &goto_mark - "'"
197 Search
199 &search - /
201 &hcraes - ?
202 &next_match - n or P
203 &prev_match - p or N
204 &grep - &
205 Options
207 &toggle_num - #
209 &toggle_fold - S
210 &toggle_raw - C
211 I18N
213 The "dialog" method may be particularly useful when enhancing the
214 pager. It accepts a string to display, and an optional timeout to
215 sleep for before the dialog is cleared. If the timeout is missing or 0,
216 the dialog remains until a key is pressed.
217 my $t = IO::Pager::Perl->new();
219 $t->add_text("Text to display");
220 $t->add_func('!'=>\&boo);
221 $t->more();
222 sub boo{ my $self = shift; $self->dialog("BOO!", 1); }
224 Should you add additional functionality to your pager, you will likely
226 want to change the contents of the help dialog or possibly the status
227 line. Use the "I18N" method to replace the default text or save text
228 for your own interface.
229 #Get the default help text
231 my $help = $t->I18N('help');
232 #Minimal status line
234 $t->I18N('prompt', "<h> help");
235 Current text elements available for customization are:
237 404 - search text not found dialog
239 bottom - prompt line end of file indicator
240 continue - text to display at the bottom of the help dialog
241 help - help dialog text, a list of keys and their functions
242 prompt - displayed at the bottom of the screen
243 status - brief message to include in the status line
244 top - prompt line start of file indicator
245 bottom - prompt line end of file indicator
246 searchwrap - message that pager is about to loop for more matches
247 nowrap - notice that missing Text::Wrap prevents folding toggle
248 status is intended for sharing short messages not worthy of a dialog
250 e.g; when debugging. You will need to call the "prompt" method after
251 setting it to refresh the status line of the display, then void status
252 and call "prompt" again to clear the message.
253 Scalability
255 The help text will be split in two horizontally on a null character if
257 the text is wider than the display, and shown in two sequential
258 dialogs.
259 Similarly, the status text will be cropped at a null character for
261 narrow displays.
262
264 UN*X
265 This modules currently only works in a UN*X-like environment.
266 Performance
268 For simplicity, the current implementation loads the entire message to
269 view at once; thus not requiring a distinction between piped contents
270 and files. This may require significant memory for large files.
271 Termcap
273 This module uses Termcap, which has been deprecated the Open Group, and
274 may not be supported by your operating system for much longer.
275 If the termcap entry for your ancient esoteric terminal is wrong or
277 incomplete, this module may either fill your screen with unintelligible
278 gibberish, or drop back to a feature-free mode.
279 Eventually, support for Terminfo may also be added.
281 Signals
283 IO::Pager::Perl sets a global signal handler for SIGWINCH, this is the
284 only way it can effectively detect and accommodate changes in terminal
285 size. If you also need notification of this signal, the handler will
286 trigger any callback assigned to the WINCH attribute of the "new"
287 method.
288
290 IO::Pager::Perl checks the TERM and TERMCAP variables.
291
293 IO::Pager, Term::Cap, Term::ReadKey, termcap(5), stty(1), tput(1),
294 less(1)
295
297 Jerrad Pierce jpierce@cpan.org
298 Jeff Weisberg - http://www.tcp4me.com
300
302 This software may be copied and distributed under the terms found in
303 the Perl "Artistic License".
304 A copy of the "Artistic License" may be found in the standard Perl
306 distribution.
307perl v5.32.0 2020-07-28 IO::Pager::Perl(3)