1POE::Wheel::ReadLine(3)User Contributed Perl DocumentatioPnOE::Wheel::ReadLine(3)
2
6 POE::Wheel::ReadLine - non-blocking Term::ReadLine for POE
7
9 #!perl
10 use warnings;
12 use strict;
13 use POE qw(Wheel::ReadLine);
15 POE::Session->create(
17 inline_states=> {
18 _start => \&setup_console,
19 got_user_input => \&handle_user_input,
20 }
21 );
22 POE::Kernel->run();
24 exit;
25 sub handle_user_input {
27 my ($input, $exception) = @_[ARG0, ARG1];
28 my $console = $_[HEAP]{console};
29 unless (defined $input) {
31 $console->put("$exception caught. B'bye!");
32 $_[KERNEL]->signal($_[KERNEL], "UIDESTROY");
33 $console->write_history("./test_history");
34 return;
35 }
36 $console->put(" You entered: $input");
38 $console->addhistory($input);
39 $console->get("Go: ");
40 }
41 sub setup_console {
43 $_[HEAP]{console} = POE::Wheel::ReadLine->new(
44 InputEvent => 'got_user_input'
45 );
46 $_[HEAP]{console}->read_history("./test_history");
47 $_[HEAP]{console}->clear();
48 $_[HEAP]{console}->put(
49 "Enter some text.",
50 "Ctrl+C or Ctrl+D exits."
51 );
52 $_[HEAP]{console}->get("Go: ");
53 }
54
56 POE::Wheel::ReadLine is a non-blocking form of Term::ReadLine that's
57 compatible with POE. It uses Term::Cap to interact with the terminal
58 display and Term::ReadKey to interact with the keyboard.
59 POE::Wheel::ReadLine handles almost all common input editing keys. It
61 provides an input history list. It has both vi and emacs modes. It
62 supports incremental input search. It's fully customizable, and it's
63 compatible with standard readline(3) implementations such as
64 Term::ReadLine::Gnu.
65 POE::Wheel::ReadLine is configured by placing commands in an "inputrc"
67 initialization file. The file's name is taken from the "INPUTRC"
68 environment variable, or ~/.inputrc by default. POE::Wheel::ReadLine
69 will read the inputrc file and configure itself according to the
70 commands and variables therein. See readline(3) for details about
71 inputrc files.
72 The default editing mode will be emacs-style, although this can be
74 configured by setting the 'editing-mode' variable within an inputrc
75 file. If all else fails, POE::Wheel::ReadLine will determine the
76 user's favorite editor by examining the EDITOR environment variable.
77
79 Constructor
80 Most of POE::Wheel::ReadLine's interaction is through its constructor,
81 new().
82 new
84 new() creates and returns a new POE::Wheel::ReadLine object. Be sure
86 to instantiate only one, as multiple console readers would conflict.
87 InputEvent
89 "InputEvent" names the event that will indicate a new line of console
91 input. See "PUBLIC EVENTS" for more details.
92 PutMode
94 "PutMode" controls how output is displayed when put() is called during
96 user input.
97 When set to "immediate", put() pre-empts the user immediately. The
99 input prompt and user's input to date are redisplayed after put() is
100 done.
101 The "after" "PutMode" tells put() to wait until after the user enters
103 or cancels her input.
104 Finally, "idle" will allow put() to pre-empt user input if the user
106 stops typing for "/IdleTime" seconds. This mode behaves like "after"
107 if the user can't stop typing long enough. This is
108 POE::Wheel::ReadLine's default mode.
109 IdleTime
111 "IdleTime" tells POE::Wheel::ReadLine how long the keyboard must be
113 idle before "put()" becomes immediate or buffered text is flushed to
114 the display. It is only meaningful when "InputMode" is "idle".
115 "IdleTime" defaults to 2 seconds.
116 AppName
118 "AppName" registers an application name which is used to retrieve
120 application-specific key bindings from the inputrc file. The default
121 "AppName" is "poe-readline".
122 # If using POE::Wheel::ReadLine, set
124 # the key mapping to emacs mode and
125 # trigger debugging output on a certain
126 # key sequence.
127 $if poe-readline
128 set keymap emacs
129 Control-xP: poe-wheel-debug
130 $endif
131 History List Management
133 POE::Wheel::ReadLine supports an input history, with searching.
134 add_history
136 add_history() accepts a list of lines to add to the input history.
138 Generally it's called with a single line: the last line of input
139 received from the terminal. The "/SYNOPSIS" shows add_history() in
140 action.
141 get_history
143 get_history() returns a list containing POE::Wheel::ReadLine's current
145 input history. It may not contain everything entered into the wheel
146 TODO - Example.
148 write_history
150 write_history() writes the current input history to a file. It accepts
152 one optional parameter: the name of the file where the input history
153 will be written. write_history() will write to ~/.history if no file
154 name is specified.
155 Returns true on success, or false if not.
157 The "SYNOPSIS" shows an example of write_history() and the
159 corresponding read_history().
160 read_history
162 read_history(FILENAME, START, END) reads a previously saved input
164 history from a named file, or from ~/.history if no file name is
165 specified. It may also read a subset of the history file if it's given
166 optional START and END parameters. The file will be read from the
167 beginning if START is omitted or zero. It will be read to the end if
168 END is omitted or earlier than START.
169 Returns true on success, or false if not.
171 The "SYNOPSIS" shows an example of read_history() and the corresponding
173 write_history().
174 Read the first ten history lines:
176 $_[HEAP]{console}->read_history("filename", 0, 9);
178 history_truncate_file
180 history_truncate_file() truncates a history file to a certain number of
182 lines. It accepts two parameters: the name of the file to truncate,
183 and the maximum number of history lines to leave in the file. The
184 history file will be cleared entirely if the line count is zero or
185 omitted.
186 The file to be truncated defaults to ~/.history. So calling
188 history_truncate_file() with no parameters clears ~/.history.
189 Returns true on success, or false if not.
191 Note that history_trucate_file() removes the earliest lines from the
193 file. The later lines remain intact since they were the ones most
194 recently entered.
195 Keep ~/.history down to a manageable 100 lines:
197 $_[HEAP]{console}->history_truncate_file(undef, 100);
199 Key Binding Methods
201 bind_key
202 bind_key(KEYSTROKE, FUNCTION) binds a FUNCTION to a named KEYSTROKE
204 sequence. The keystroke sequence can be in any of the forms defined
205 within readline(3). The function should either be a pre-defined name,
206 such as "self-insert" or a function reference. The binding is made in
207 the current keymap. Use the rl_set_keymap() method to change keymaps,
208 if desired.
209 add_defun NAME FN
211 add_defun(NAME, FUNCTION) defines a new global FUNCTION, giving it a
213 specific NAME. The function may then be bound to keystrokes by that
214 NAME.
215 Console I/O Methods
217 clear
218 Clears the terminal.
220 terminal_size
222 Returns what POE::Wheel::ReadLine thinks are the current dimensions of
224 the terminal. Returns a list of two values: the number of columns and
225 number of rows, respectively.
226 sub some_event_handler {
228 my ($columns, $rows) = $_[HEAP]{console}->terminal_size;
229 $_[HEAP]{console}->put(
230 "Terminal columns: $columns",
231 "Terminal rows: $rows",
232 );
233 }
234 get
236 get() causes POE::Wheel::ReadLine to display a prompt and then wait for
238 input. Input is not noticed unless get() has enabled the wheel's
239 internal I/O watcher.
240 After get() is called, the next line of input or exception on the
242 console will trigger an "InputEvent" with the appropriate parameters.
243 POE::Wheel::ReadLine will then enter an inactive state until get() is
244 called again.
245 See the "SYNOPSIS" for sample usage.
247 put
249 put() accepts a list of lines to put on the terminal.
251 POE::Wheel::ReadLine is line-based. See POE::Wheel::Curses for more
252 funky display options.
253 Please do not use print() with POE::Wheel::ReadLine. print()
255 invariably gets the newline wrong, leaving an application's output to
256 stairstep down the terminal. Also, put() understands when a user is
257 entering text, and "PutMode" may be used to avoid interrupting the
258 user.
259 ReadLine Option Methods
261 attribs
262 attribs() returns a reference to a hash of readline options. The
264 returned hash may be used to query or modify POE::Wheel::ReadLine's
265 behavior.
266 option
268 option(NAME) returns a specific member of the hash returned by
270 attribs(). It's a more convenient way to query POE::Wheel::ReadLine
271 options.
272
274 POE::Wheel::ReadLine emits only a single event.
275 InputEvent
277 "InputEvent" names the event that will be emitted upon any kind of
278 complete terminal input. Every "InputEvent" handler receives three
279 parameters:
280 $_[ARG0] contains a line of input. It may be an empty string if the
282 user entered an empty line. An undefined $_[ARG0] indicates some
283 exception such as end-of-input or the fact that the user canceled their
284 input or pressed C-c (^C).
285 $_[ARG1] describes an exception, if one occurred. It may contain one
287 of the following strings:
288 cancel
290 The "cancel" exception indicates when a user has canceled a line of
291 input. It's sent when the user triggers the "abort" function, which
292 is bound to C-g (^G) by default.
293 eot
295 "eot" is the ASCII code for "end of tape". It's emitted when the
296 user requests that the terminal be closed. By default, it's
297 triggered when the user presses C-d (^D) on an empty line.
298 interrupt
300 "interrupt" is sent as a result of the user pressing C-c (^C) or
301 otherwise triggering the "interrupt" function.
302 Finally, $_[ARG2] contains the ID for the POE::Wheel::ReadLine object
304 that sent the "InputEvent".
305
307 POE::Wheel::ReadLine allows custom functions to be bound to keystrokes.
308 The function must be made visible to the wheel before it can be bound.
309 To register a function, use POE::Wheel::ReadLine's add_defun() method:
310 POE::Wheel::ReadLine->add_defun('reverse-line', \&reverse_line);
312 When adding a new defun, an optional third parameter may be provided
314 which is a key sequence to bind to. This should be in the same format
315 as that understood by the inputrc parsing.
316 Bound functions receive three parameters: A reference to the wheel
318 object itself, the key sequence that triggered the function (in
319 printable form), and the raw key sequence. The bound function is
320 expected to dig into the POE::Wheel::ReadLine data members to do its
321 work and display the new line contents itself.
322 This is less than ideal, and it may change in the future.
324
326 An application may modify POE::Wheel::ReadLine's "completion_function"
327 in order to customize how input should be completed. The new
328 completion function must accept three scalar parameters: the word being
329 completed, the entire input text, and the position within the input
330 text of the word being completed.
331 The completion function should return a list of possible matches. For
333 example:
334 my $attribs = $wheel->attribs();
336 $attribs->{completion_function} = sub {
337 my ($text, $line, $start) = @_;
338 return qw(a list of candidates to complete);
339 }
340 This is the only form of completion currently supported.
342
344 Although POE::Wheel::ReadLine is modeled after the readline(3) library,
345 there are some areas which have not been implemented. The only option
346 settings which have effect in this implementation are: bell-style,
347 editing-mode, isearch-terminators, comment-begin, print-completions-
348 horizontally, show-all-if-ambiguous and completion_function.
349 The function 'tab-insert' is not implemented, nor are tabs displayed
351 properly.
352
354 POE::Wheel describes the basic operations of all wheels in more depth.
355 You need to know this.
356 readline(3), Term::Cap, Term::ReadKey.
358 The SEE ALSO section in POE contains a table of contents covering the
360 entire POE distribution.
361 Term::Visual is an alternative to POE::Wheel::ReadLine. It provides
363 scrollback and a status bar in addition to editable user input.
364 Term::Visual supports POE despite the lack of "POE" in its name.
365
367 POE::Wheel::ReadLine has some known issues:
368 Perl 5.8.0 is Broken
370 Non-blocking input with Term::ReadKey does not work with Perl 5.8.0,
371 especially on Linux systems for some reason. Upgrading Perl will fix
372 things. If you can't upgrade Perl, consider alternative input methods,
373 such as Term::Visual.
374 <http://rt.cpan.org/Ticket/Display.html?id=4524> and related tickets
376 explain the issue in detail. If you suspect your system is one where
377 Term::ReadKey fails, you can run this test program to be sure.
378 #!/usr/bin/perl
380 use Term::ReadKey;
381 print "Press 'q' to quit this test.\n";
382 ReadMode 5; # Turns off controls keys
383 while (1) {
384 while (not defined ($key = ReadKey(-1))) {
385 print "Didn't get a key. Sleeping 1 second.\015\012";
386 sleep (1);
387 }
388 print "Got key: $key\015\012";
389 ($key eq 'q') and last;
390 }
391 ReadMode 0; # Reset tty mode before exiting
392 exit;
393 Non-Optimal Code
395 Dissociating the input and display cursors introduced a lot of code.
396 Much of this code was thrown in hastily, and things can probably be
397 done with less work.
398 TODO: Apply some thought to what's already been done.
400 TODO: Ensure that the screen updates as quickly as possible, especially
402 on slow systems. Do little or no calculation during displaying; either
403 put it all before or after the display. Do it consistently for each
404 handled keystroke, so that certain pairs of editing commands don't have
405 extra perceived latency.
406 Unimplemented Features
408 Input editing is not kept on one line. If it wraps, and a terminal
409 cannot wrap back through a line division, the cursor will become lost.
410 Unicode support. I feel real bad about throwing away native
412 representation of all the 8th-bit-set characters. I also have no idea
413 how to do this, and I don't have a system to test this. Patches are
414 very much welcome.
415
417 Lost Prompts
418 Q: Why do I lose my prompt every time I send output to the screen?
419 A: You probably are using print or printf to write screen output.
421 ReadLine doesn't track STDOUT itself, so it doesn't know when to
422 refresh the prompt after you do this. Use ReadLine's put() method to
423 write lines to the console.
424 Edit Keystrokes Display as ^C
426 Q: None of the editing keystrokes work. Ctrl-C displays "^c" rather
427 than generating an interrupt. The arrow keys don't scroll through my
428 input history. It's generally a bad experience.
429 A: You're probably a vi/vim user. In the absence of a ~/.inputrc file,
431 POE::Wheel::ReadLine checks your EDITOR environment variable for clues
432 about your editing preference. If it sees /vi/ in there, it starts in
433 vi mode. You can override this by creating a ~/.inputrc file
434 containing the line "set editing-mode emacs", or adding that line to
435 your existing ~/.inputrc. While you're in there, you should totally
436 get acquainted with all the other cool stuff you can do with .inputrc
437 files.
438 Lack of Windows Support
440 Q: Why doesn't POE::Wheel::ReadLine work on Windows? Term::ReadLine
441 does.
442 A: POE::Wheel::ReadLine requires select(), because that's what POE uses
444 by default to detect keystrokes without blocking. About half the
445 flavors of Perl on Windows implement select() in terms of the same
446 function in the WinSock library, which limits select() to working only
447 with sockets. Your console isn't a socket, so select() doesn't work
448 with your version of Perl on Windows.
449 Really good workarounds are possible but don't exist as of this
451 writing. They involve writing a special POE::Loop for Windows that
452 either uses a Win32-specific module for better multiplexing, that polls
453 for input, or that uses blocking I/O watchers in separate threads.
454 Cygwin Support
456 Q: Why does POE::Wheel::ReadLine complain about my "dumb" terminal?
457 A: Do you have Strawberry Perl installed? Due to the way it works, on
459 installation it sets a global environment variable in MSWin32 for
460 TERM=dumb. ( it may be fixed in a future version, but it's here to stay
461 for now, ha! ) In this case, logging into the Cygwin shell via the
462 cygwin.bat launcher results in a nonfunctional readline.
463 Normally, Cygwin will set TERM=cygwin in the launcher. However, if the
465 TERM was already set it will not alter the value. Hence, the "bug"
466 appears! What you can do is to hack the cygwin.bat file to add this
467 line:
468 SET TERM=cygwin
470 Other users reported that you can have better results by editing the
472 ~/.bash_profile file to set TERM=cygwin because on a Cygwin upgrade it
473 overwrites the cygwin.bat file.
474 Alternatively, you could install different terminals like "xterm" or
476 "rxvt" as shown here: <http://c2.com/cgi/wiki?BetterCygwinTerminal>.
477 Please let us know if you encounter problems using any terminal other
478 than "dumb".
479 If you feel brave, you can peruse the RT ticket at
481 <http://rt.cpan.org/Ticket/Display.html?id=55365> for more information
482 on this problem.
483
485 POE::Wheel::ReadLine was originally written by Rocco Caputo.
486 Nick Williams virtually rewrote it to support a larger subset of GNU
488 readline.
489 Please see POE for more information about other authors and
491 contributors.
492perl v5.12.1 2010-04-03 POE::Wheel::ReadLine(3)