1POE::Wheel::ReadLine(3)User Contributed Perl DocumentatioPnOE::Wheel::ReadLine(3)
2
6 POE::Wheel::ReadLine - prompted terminal input
7
9 # Create the wheel.
10 $heap->{wheel} = POE::Wheel::ReadLine->new(
11 InputEvent => got_input, appname => 'mycli'
12 );
13 # Trigger the wheel to read a line of input.
15 $heap->{wheel}->get( 'Prompt: ' );
16 # Add a line to the wheel's input history.
18 $heap->{wheel}->addhistory( $input );
19 # Input handler. If $input is defined, then it contains a line of
21 # input. Otherwise $exception contains a word describing some kind
22 # of user exception. Currently these are 'interrupt' and 'cancel'.
23 sub got_input_handler {
24 my ($heap, $input, $exception) = @_[HEAP, ARG0, ARG1];
25 if (defined $input) {
26 $heap->{wheel}->addhistory($input);
27 $heap->{wheel}->put("\tGot: $input");
28 $heap->{wheel}->get('Prompt: '); # get another line
29 }
30 else {
31 $heap->{wheel}->put("\tException: $exception");
32 }
33 }
34 # Clear the terminal.
36 $heap->{wheel}->clear();
37
39 ReadLine performs non-blocking, event-driven console input, using
40 Term::Cap to interact with the terminal display and Term::ReadKey to
41 interact with its keyboard.
42 ReadLine handles almost all common input editing keys; it provides an
44 input history list; it has both vi and emacs modes; it provides incre‐
45 mental search facilities; it is fully customizable and it is compatible
46 with standard readline(3) implementations such as Term::ReadLine::Gnu.
47 ReadLine is configured by placing commands in an initialization file
49 (the inputrc file). The name of this file is taken from the value of
50 the INPUTRC environment variable. If that variable is unset, the
51 default is ~/.inputrc. When the wheel is instantiated, the init file
52 is read and the key bindings and variables are set. There are only a
53 few basic constructs allowed in the readline init file. Blank lines
54 are ignored. Lines beginning with a '#' are comments. Lines beginning
55 with a '$' indicate conditional constructs. Other lines denote key
56 bindings and variable settings. Each program using this library may
57 add its own commands and bindings. For more detail on the inputrc file,
58 see readline(3).
59 The default editing mode will be emacs-style, although this can be con‐
61 figured by setting the 'editing-mode' variable within the inputrc, or
62 by setting the EDITOR environment variable.
63
65 new new() creates a new wheel, returning the wheels reference.
66
68 History List Management
69 addhistory LIST_OF_LINES
71 Adds a list of lines, presumably from previous input, into the
72 ReadLine wheel's input history.
73 GetHistory
75 Returns the list of all currently known history lines.
76 WriteHistory FILE
78 writes the current history to FILENAME, overwriting FILENAME if
79 necessary. If FILENAME is false, then write the history list to
80 ~/.history. Returns true if successful, or false if not.
81 ReadHistory FILE FROM TO
83 adds the contents of FILENAME to the history list, a line at a
84 time. If FILENAME is false, then read from ~/.history. Start
85 reading at line FROM and end at TO. If FROM is omitted or zero,
86 start at the beginning. If TO is omitted or less than FROM, then
87 read until the end of the file. Returns true if successful, or
88 false if not.
89 history_truncate_file FILE LINES
91 Truncate the number of lines within FILE to be at most that speci‐
92 fied by LINES. FILE defaults to ~/.history. If LINES is not speci‐
93 fied, then the history file is cleared.
94 Miscellaneous Methods
96 clear
98 Clears the terminal.
99 terminal_size
101 Returns what ReadLine thinks are the current dimensions of the ter‐
102 minal. The return value is a list of two elements: the number of
103 columns and number of rows respectively.
104 get PROMPT
106 Provide a prompt and enable input. The wheel will display the
107 prompt and begin paying attention to the console keyboard after
108 this method is called. Once a line or an exception is returned,
109 the wheel will resume its quiescent state wherein it ignores key‐
110 strokes.
111 The quiet period between input events gives a program the opportu‐
113 nity to change the prompt or process lines before the next one
114 arrives.
115 put TEXT
117 Print the given text to the terminal.
118 Attribs
120 Returns a reference to a hash of options that can be configured to
121 modify the readline behaviour.
122 bind_key KEY FN
124 Bind a function to a named key sequence. The key sequence can be in
125 any of the forms defined within readline(3). The function should
126 either be a pre-registered name such as 'self-insert', or it should
127 be a reference to a function. The binding is made in the current
128 keymap. If you wish to change keymaps, then use the rl_set_keymap
129 method.
130 add_defun NAME FN
132 Create a new (global) function definition which may be then bound
133 to a key.
134 option NAME
136 Returns the option named NAME or an empty string.
137
139 InputEvent
140 InputEvent contains the name of the event that will be fired upon
141 successful (or unsuccessful) terminal input. Every InputEvent han‐
142 dler receives two additional parameters, only one of which is ever
143 defined at a time. "ARG0" contains the input line, if one was
144 present. If "ARG0" is not defined, then "ARG1" contains a word
145 describing a user-generated exception:
146 The 'interrupt' exception means a user pressed C-c (^C) to interrupt
148 the program. It's up to the input event's handler to decide what to
149 do next.
150 The 'cancel' exception means a user pressed C-g (^G) to cancel a line
152 of input.
153 The 'eot' exception means the user pressed C-d (^D) while the input
155 line was empty. EOT is the ASCII name for ^D.
156 Finally, "ARG2" contains the ReadLine wheel's unique ID.
158 PutMode
160 PutMode specifies how the wheel will display text when its "put()"
161 method is called.
162 "put()" displays text immediately when the user isn't being prompted
164 for input. It will also pre-empt the user to display text right away
165 when PutMode is "immediate".
166 When PutMode is "after", all "put()" text is held until after the
168 user enters or cancels (See C-g) her input.
169 PutMode can also be "idle". In this mode, text is displayed right
171 away if the keyboard has been idle for a certain period (see the
172 IdleTime parameter). Otherwise it's held as in "after" mode until
173 input is completed or canceled, or until the keyboard becomes idle
174 for at least IdleTime seconds. This is ReadLine's default mode.
175 IdleTime
177 IdleTime specifies how long the keyboard must be idle before "put()"
178 becomes immediate or buffered text is flushed to the display. It is
179 only meaningful when InputMode is "idle". IdleTime defaults to two
180 seconds.
181 appname
183 Registers an application name which is used to get appl-specific key‐
184 bindings from the .inputrc. If not defined, then the default value is
185 'poe-readline'. You may use this in a standard inputrc file to define
186 application specific settings. For example:
187 $if poe-readline
189 # bind the following sequence in emacs mode
190 set keymap emacs
191 # display poe debug data
192 Control-xP: poe-wheel-debug
193 $endif
194
196 To bind keys to your own functions, the function name has to be made
197 visible to the wheel before the binding is attempted. To register a
198 function, use the method POE::Wheel::ReadLine::add_defun:
199 POE::Wheel::ReadLine->add_defun('reverse-line', \&reverse_line);
201 The function will be called with three parameters: a reference to the
203 wheel object itself, the key sequence in a printable form, and the raw
204 key sequence. When adding a new defun, an optional third parameter may
205 be provided which is a key sequence to bind to. This should be in the
206 same format as that understood by the inputrc parsing.
207
209 To configure completion, you need to modify the 'completion_function'
210 value to be a reference to a function. The function should take three
211 scalar parameters: the word being completed, the entire input text and
212 the position within the input text of the word. The return result is
213 expected to be a list of possible matches. An example usage is as fol‐
214 lows:
215 my $attribs = $wheel->Attribs;
217 $attribs->{completion_function} = sub {
218 my ($text, $line, $start) = @_;
219 return qw(a list of candidates to complete);
220 }
221 This is the only form of completion currently supported.
223
225 Although modeled after the readline(3) library, there are some areas
226 which have not been implemented. The only option settings which have
227 effect in this implementation are: bell-style, editing-mode,
228 isearch-terminators, comment-begin, print-completions-horizontally,
229 show-all-if-ambiguous and completion_function.
230 The function 'tab-insert' is not implemented, nor are tabs displayed
232 properly.
233
235 POE::Wheel, readline(3), Term::ReadKey, Term::Visual.
236 The SEE ALSO section in POE contains a table of contents covering the
238 entire POE distribution.
239
241 POE::Wheel::ReadLine has some known issues:
242 Perl 5.8.0 is Broken
244 Non-blocking input with Term::ReadKey does not work with Perl 5.8.0.
246 The problem usually appears on Linux systems. See:
247 http://rt.cpan.org/Ticket/Display.html?id=4524 and all the tickets
248 related to it.
249 If you suspect your system is one where Term::ReadKey fails, you can
251 run this test program to be sure. If you can, upgrade Perl to fix it.
252 If you can't upgrade Perl, consider alternative input methods, such as
253 Term::Visual.
254 #!/usr/bin/perl
256 use Term::ReadKey;
257 print "Press 'q' to quit this test.\n";
258 ReadMode 5; # Turns off controls keys
259 while (1) {
260 while (not defined ($key = ReadKey(-1))) {
261 print "Didn't get a key. Sleeping 1 second.\015\012";
262 sleep (1);
263 }
264 print "Got key: $key\015\012";
265 ($key eq 'q') and last;
266 }
267 ReadMode 0; # Reset tty mode before exiting
268 exit;
269 Non-optimal code2
271 Dissociating the input and display cursors introduced a lot of code.
273 Much of this code was thrown in hastily, and things can probably be
274 done with less work. To do: Apply some thought to what's already been
275 done.
276 The screen should update as quickly as possible, especially on slow
278 systems. Do little or no calculation during displaying; either put it
279 all before or after the display. Do it consistently for each handled
280 keystroke, so that certain pairs of editing commands don't have extra
281 perceived latency.
282 Unimplemented features
284 Input editing is not kept on one line. If it wraps, and a terminal
286 cannot wrap back through a line division, the cursor will become lost.
287 This bites, and it's the next against the wall in my bug hunting.
288 Unicode, or at least European code pages. I feel real bad about throw‐
290 ing away native representation of all the 8th-bit-set characters. I
291 also have no idea how to do this, and I don't have a system to test
292 this. Patches are recommended.
293
295 Q: Why do I lose my ReadLine prompt every time I send output to the
296 screen?
297 A: You probably are using print or printf to write screen output.
299 ReadLine doesn't track STDOUT itself, so it doesn't know when to
300 refresh the prompt after you do this. Use ReadLine's put() method to
301 write lines to the console.
302 Q: None of the editing keystrokes work. Ctrl-C displays "^c" rather
304 than generating an interrupt. The arrow keys don't scroll through my
305 input history. It's generally a bad experience.
306 A: You're probably a vi/vim user. In the absence of a ~/.inputrc file,
308 POE::Wheel::ReadLine checks your EDITOR environment variable for clues
309 about your editing preference. If it sees /vi/ in there, it starts in
310 vi mode. You can override this by creating a ~/.inputrc file contain‐
311 ing the line "set editing-mode emacs", or adding that line to your
312 existing ~/.inputrc. While you're in there, you should totally get
313 acquainted with all the other cool stuff you can do with .inputrc
314 files.
315 Q: Why doesn't POE::Wheel::ReadLine work on Windows? Term::ReadLine
317 does.
318 A: POE::Wheel::ReadLine requires select(), because that's what POE uses
320 by default to detect keystrokes without blocking. About half the fla‐
321 vors of Perl on Windows implement select() in terms of the same func‐
322 tion in the WinSock library, which limits select() to working only with
323 sockets. Your console isn't a socket, so select() doesn't work with
324 your version of Perl on Windows.
325 Really good workarounds are possible but don't exist as of this writ‐
327 ing. They involve writing a special POE::Loop for Windows that either
328 uses a Win32-specific module for better multiplexing, that polls for
329 input, or that uses blocking I/O watchers in separate threads.
330
332 Rocco Caputo - Original author. Nick Williams - Heavy edits, making it
333 gnu readline-alike.
334 Please see POE for more information about other authors and contribu‐
336 tors.
337perl v5.8.8 2006-09-01 POE::Wheel::ReadLine(3)