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 expectcusing 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 Wrap long lines.
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 visualBeep =>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 visualBeep set?
79 $t->visualBeep();
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 Adding Functionality and Internationalization (I18N)
118 It is possible to extend the features of IO::Pager::Perl by supplying
119 the "add_func" method with a hash of character keys and callback values
120 to be invoked upon matching keypress; where \c? represents Control-?
121 and \e? represents Alt-? The existing pairings are:
122 'h' => \&help,
124 'q' => \&done,
125 'r' => \&refresh, #also "\cL"
126 "\n"=> \&downline, #also "\e[B"
127 ' ' => \&downpage, #also "\cv"
128 'd' => \&downhalf,
129 'b' => \&uppage, #also "\ev"
130 'y' => \&upline, #also "\e[A"
131 'u' => \&uphalf,
132 'g' => \&to_top, #also '<'
133 'G' => \&to_bott, #also '>'
134 '/' => \&search,
135 '?' => \&hcraes, #reverse search
136 'n' => \&next_match, #also 'P'
137 'p' => \&prev_match, #also 'N'
138 "\e[D" => \&move_left,
139 "\e[C" => \&move_right,
140 '#' => \&toggle_numbering,
141 And a special sequence of a number followed by enter analogous to:
143 '/(\d+)/' => \&jump(\1)
145 if the value for that key is true.
147 The "dialog" method may be particularly useful when enhancing the
149 pager. It accepts a string to display, and an optional timeout to
150 sleep for before the dialog is cleared. If the timeout is missing or 0,
151 the dialog remains until a key is pressed.
152 my $t = IO::Pager::Perl->new();
154 $t->add_text("Text to display");
155 $t->add_func('!'=>\&boo);
156 $t->more();
157 sub boo{ my $self = shift; $self->dialog("BOO!", 1); }
159 Should you add additional functionality to your pager, you will likely
161 want to change the contents of the help dialog or possibly the status
162 line. Use the "I18N" method to replace the default text or save text
163 for your own interface.
164 #Get the default help text
166 my $help = $t->I18N('help');
167 #Minimal status line
169 $t->I18N('prompt', "<h> help");
170 Current text elements available for customization are:
172 404 - search text not found dialog
174 bottom - prompt line end of file indicator
175 continue - text to display at the bottom of the help dialog
176 help - help dialog text, a list of keys and their functions
177 prompt - displayed at the bottom of the screen
178 status - brief message to include in the status line
179 top - prompt line start of file indicator
180 status is intended for sharing short messages not worthy of a dialog
182 e.g; when debugging. You will need to call the "prompt" method after
183 setting it to refresh the status line of the display, then void status
184 and call "prompt" again to clear the message.
185 Scalability
187 The help text will be split in two horizontally on a null character if
189 the text is wider than the display, and shown in two sequential
190 dialogs.
191 Similarly, the status text will be cropped at a null character for
193 narrow displays.
194
196 UN*X
197 This modules currently only works in UN*X-like environment.
198 Performance
200 For simplicity, the current implementation loads the entire message to
201 view at once; thus not requiring a distinction between piped contents
202 and files. This may require significant memory for large files.
203 Termcap
205 This module uses Termcap, which has been deprecated the Open Group, and
206 may not be supported by your operating system for much longer.
207 If the termcap entry for your ancient esoteric terminal is wrong or
209 incomplete, this module may either fill your screen with unintelligible
210 gibberish, or drop back to a feature-free mode.
211 Eventually, support for Terminfo may also be added.
213 Signals
215 IO::Pager::Perl sets a global signal handler for SIGWINCH, this is the
216 only way it can effectively detect and accommodate changes in terminal
217 size. If you also need notification of this signal, the handler will
218 trigger any callback assigned to the WINCH attribute of the "new"
219 method.
220
222 IO::Pager::Perl checks the TERM and TERMCAP variables.
223
225 IO::Pager, Term::Cap, Term::ReadKey, termcap(5), stty(1), tput(1),
226 less(1)
227
229 Jerrad Pierce jpierce@cpan.org
230 Jeff Weisberg - http://www.tcp4me.com
232
234 This software may be copied and distributed under the terms found in
235 the Perl "Artistic License".
236 A copy of the "Artistic License" may be found in the standard Perl
238 distribution.
239perl v5.30.1 2020-01-30 IO::Pager::Perl(3)