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" if
107 the user can't stop typing long enough. This is POE::Wheel::ReadLine's
108 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 "PutMode" 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 write_history
148 write_history() writes the current input history to a file. It accepts
150 one optional parameter: the name of the file where the input history
151 will be written. write_history() will write to ~/.history if no file
152 name is specified.
153 Returns true on success, or false if not.
155 The "SYNOPSIS" shows an example of write_history() and the
157 corresponding read_history().
158 read_history
160 read_history(FILENAME, START, END) reads a previously saved input
162 history from a named file, or from ~/.history if no file name is
163 specified. It may also read a subset of the history file if it's given
164 optional START and END parameters. The file will be read from the
165 beginning if START is omitted or zero. It will be read to the end if
166 END is omitted or earlier than START.
167 Returns true on success, or false if not.
169 The "SYNOPSIS" shows an example of read_history() and the corresponding
171 write_history().
172 Read the first ten history lines:
174 $_[HEAP]{console}->read_history("filename", 0, 9);
176 history_truncate_file
178 history_truncate_file() truncates a history file to a certain number of
180 lines. It accepts two parameters: the name of the file to truncate,
181 and the maximum number of history lines to leave in the file. The
182 history file will be cleared entirely if the line count is zero or
183 omitted.
184 The file to be truncated defaults to ~/.history. So calling
186 history_truncate_file() with no parameters clears ~/.history.
187 Returns true on success, or false if not.
189 Note that history_trucate_file() removes the earliest lines from the
191 file. The later lines remain intact since they were the ones most
192 recently entered.
193 Keep ~/.history down to a manageable 100 lines:
195 $_[HEAP]{console}->history_truncate_file(undef, 100);
197 Key Binding Methods
199 bind_key
200 bind_key(KEYSTROKE, FUNCTION) binds a FUNCTION to a named KEYSTROKE
202 sequence. The keystroke sequence can be in any of the forms defined
203 within readline(3). The function should either be a pre-defined name,
204 such as "self-insert" or a function reference. The binding is made in
205 the current keymap. Use the rl_set_keymap() method to change keymaps,
206 if desired.
207 add_defun NAME FN
209 add_defun(NAME, FUNCTION) defines a new global FUNCTION, giving it a
211 specific NAME. The function may then be bound to keystrokes by that
212 NAME.
213 Console I/O Methods
215 clear
216 Clears the terminal.
218 terminal_size
220 Returns what POE::Wheel::ReadLine thinks are the current dimensions of
222 the terminal. Returns a list of two values: the number of columns and
223 number of rows, respectively.
224 sub some_event_handler {
226 my ($columns, $rows) = $_[HEAP]{console}->terminal_size;
227 $_[HEAP]{console}->put(
228 "Terminal columns: $columns",
229 "Terminal rows: $rows",
230 );
231 }
232 get
234 get() causes POE::Wheel::ReadLine to display a prompt and then wait for
236 input. Input is not noticed unless get() has enabled the wheel's
237 internal I/O watcher.
238 After get() is called, the next line of input or exception on the
240 console will trigger an "InputEvent" with the appropriate parameters.
241 POE::Wheel::ReadLine will then enter an inactive state until get() is
242 called again.
243 Calls to get() without an argument will preserve the current prompt.
245 Calling get() with an argument before a whole line of input is received
246 will change the prompt on the fly.
247 See the "SYNOPSIS" for sample usage.
249 put
251 put() accepts a list of lines to put on the terminal.
253 POE::Wheel::ReadLine is line-based. See POE::Wheel::Curses for more
254 funky display options.
255 Please do not use print() with POE::Wheel::ReadLine. print()
257 invariably gets the newline wrong, leaving an application's output to
258 stairstep down the terminal. Also, put() understands when a user is
259 entering text, and "PutMode" may be used to avoid interrupting the
260 user.
261 ReadLine Option Methods
263 attribs
264 attribs() returns a reference to a hash of readline options. The
266 returned hash may be used to query or modify POE::Wheel::ReadLine's
267 behavior.
268 option
270 option(NAME) returns a specific member of the hash returned by
272 attribs(). It's a more convenient way to query POE::Wheel::ReadLine
273 options.
274
276 POE::Wheel::ReadLine emits only a single event.
277 InputEvent
279 "InputEvent" names the event that will be emitted upon any kind of
280 complete terminal input. Every "InputEvent" handler receives three
281 parameters:
282 $_[ARG0] contains a line of input. It may be an empty string if the
284 user entered an empty line. An undefined $_[ARG0] indicates some
285 exception such as end-of-input or the fact that the user canceled their
286 input or pressed C-c (^C).
287 $_[ARG1] describes an exception, if one occurred. It may contain one
289 of the following strings:
290 cancel
292 The "cancel" exception indicates when a user has canceled a line of
293 input. It's sent when the user triggers the "abort" function, which
294 is bound to C-g (^G) by default.
295 eot
297 "eot" is the ASCII code for "end of tape". It's emitted when the
298 user requests that the terminal be closed. By default, it's
299 triggered when the user presses C-d (^D) on an empty line.
300 interrupt
302 "interrupt" is sent as a result of the user pressing C-c (^C) or
303 otherwise triggering the "interrupt" function.
304 Finally, $_[ARG2] contains the ID for the POE::Wheel::ReadLine object
306 that sent the "InputEvent".
307
309 POE::Wheel::ReadLine allows custom functions to be bound to keystrokes.
310 The function must be made visible to the wheel before it can be bound.
311 To register a function, use POE::Wheel::ReadLine's add_defun() method:
312 POE::Wheel::ReadLine->add_defun('reverse-line', \&reverse_line);
314 When adding a new defun, an optional third parameter may be provided
316 which is a key sequence to bind to. This should be in the same format
317 as that understood by the inputrc parsing.
318 Bound functions receive three parameters: A reference to the wheel
320 object itself, the key sequence that triggered the function (in
321 printable form), and the raw key sequence. The bound function is
322 expected to dig into the POE::Wheel::ReadLine data members to do its
323 work and display the new line contents itself.
324 This is less than ideal, and it may change in the future.
326
328 An application may modify POE::Wheel::ReadLine's "completion_function"
329 in order to customize how input should be completed. The new
330 completion function must accept three scalar parameters: the word being
331 completed, the entire input text, and the position within the input
332 text of the word being completed.
333 The completion function should return a list of possible matches. For
335 example:
336 my $attribs = $wheel->attribs();
338 $attribs->{completion_function} = sub {
339 my ($text, $line, $start) = @_;
340 return qw(a list of candidates to complete);
341 }
342 This is the only form of completion currently supported.
344
346 Although POE::Wheel::ReadLine is modeled after the readline(3) library,
347 there are some areas which have not been implemented. The only option
348 settings which have effect in this implementation are: bell-style,
349 editing-mode, isearch-terminators, comment-begin, print-completions-
350 horizontally, show-all-if-ambiguous and completion_function.
351 The function 'tab-insert' is not implemented, nor are tabs displayed
353 properly.
354
356 POE::Wheel describes the basic operations of all wheels in more depth.
357 You need to know this.
358 readline(3), Term::Cap, Term::ReadKey.
360 The SEE ALSO section in POE contains a table of contents covering the
362 entire POE distribution.
363 Term::Visual is an alternative to POE::Wheel::ReadLine. It provides
365 scrollback and a status bar in addition to editable user input.
366 Term::Visual supports POE despite the lack of "POE" in its name.
367
369 POE::Wheel::ReadLine has some known issues:
370 Perl 5.8.0 is Broken
372 Non-blocking input with Term::ReadKey does not work with Perl 5.8.0,
373 especially on Linux systems for some reason. Upgrading Perl will fix
374 things. If you can't upgrade Perl, consider alternative input methods,
375 such as Term::Visual.
376 <http://rt.cpan.org/Ticket/Display.html?id=4524> and related tickets
378 explain the issue in detail. If you suspect your system is one where
379 Term::ReadKey fails, you can run this test program to be sure.
380 #!/usr/bin/perl
382 use Term::ReadKey;
383 print "Press 'q' to quit this test.\n";
384 ReadMode 5; # Turns off controls keys
385 while (1) {
386 while (not defined ($key = ReadKey(-1))) {
387 print "Didn't get a key. Sleeping 1 second.\015\012";
388 sleep (1);
389 }
390 print "Got key: $key\015\012";
391 ($key eq 'q') and last;
392 }
393 ReadMode 0; # Reset tty mode before exiting
394 exit;
395 Non-Optimal Code
397 Dissociating the input and display cursors introduced a lot of code.
398 Much of this code was thrown in hastily, and things can probably be
399 done with less work.
400 Unimplemented Features
402 Input editing is not kept on one line. If it wraps, and a terminal
403 cannot wrap back through a line division, the cursor will become lost.
404 Unicode support. I feel real bad about throwing away native
406 representation of all the 8th-bit-set characters. I also have no idea
407 how to do this, and I don't have a system to test this. Patches are
408 very much welcome.
409
411 Lost Prompts
412 Q: Why do I lose my prompt every time I send output to the screen?
413 A: You probably are using print or printf to write screen output.
415 ReadLine doesn't track STDOUT itself, so it doesn't know when to
416 refresh the prompt after you do this. Use ReadLine's put() method to
417 write lines to the console.
418 Edit Keystrokes Display as ^C
420 Q: None of the editing keystrokes work. Ctrl-C displays "^c" rather
421 than generating an interrupt. The arrow keys don't scroll through my
422 input history. It's generally a bad experience.
423 A: You're probably a vi/vim user. In the absence of a ~/.inputrc file,
425 POE::Wheel::ReadLine checks your EDITOR environment variable for clues
426 about your editing preference. If it sees /vi/ in there, it starts in
427 vi mode. You can override this by creating a ~/.inputrc file
428 containing the line "set editing-mode emacs", or adding that line to
429 your existing ~/.inputrc. While you're in there, you should totally
430 get acquainted with all the other cool stuff you can do with .inputrc
431 files.
432 Lack of Windows Support
434 Q: Why doesn't POE::Wheel::ReadLine work on Windows? Term::ReadLine
435 does.
436 A: POE::Wheel::ReadLine requires select(), because that's what POE uses
438 by default to detect keystrokes without blocking. About half the
439 flavors of Perl on Windows implement select() in terms of the same
440 function in the WinSock library, which limits select() to working only
441 with sockets. Your console isn't a socket, so select() doesn't work
442 with your version of Perl on Windows.
443 Really good workarounds are possible but don't exist as of this
445 writing. They involve writing a special POE::Loop for Windows that
446 either uses a Win32-specific module for better multiplexing, that polls
447 for input, or that uses blocking I/O watchers in separate threads.
448 Cygwin Support
450 Q: Why does POE::Wheel::ReadLine complain about my "dumb" terminal?
451 A: Do you have Strawberry Perl installed? Due to the way it works, on
453 installation it sets a global environment variable in MSWin32 for
454 TERM=dumb. ( it may be fixed in a future version, but it's here to stay
455 for now, ha! ) In this case, logging into the Cygwin shell via the
456 cygwin.bat launcher results in a nonfunctional readline.
457 Normally, Cygwin will set TERM=cygwin in the launcher. However, if the
459 TERM was already set it will not alter the value. Hence, the "bug"
460 appears! What you can do is to hack the cygwin.bat file to add this
461 line:
462 SET TERM=cygwin
464 Other users reported that you can have better results by editing the
466 ~/.bash_profile file to set TERM=cygwin because on a Cygwin upgrade it
467 overwrites the cygwin.bat file.
468 Alternatively, you could install different terminals like "xterm" or
470 "rxvt" as shown here: <http://c2.com/cgi/wiki?BetterCygwinTerminal>.
471 Please let us know if you encounter problems using any terminal other
472 than "dumb".
473 If you feel brave, you can peruse the RT ticket at
475 <http://rt.cpan.org/Ticket/Display.html?id=55365> for more information
476 on this problem.
477
479 POE::Wheel::ReadLine was originally written by Rocco Caputo.
480 Nick Williams virtually rewrote it to support a larger subset of GNU
482 readline.
483 Please see POE for more information about other authors and
485 contributors.
486perl v5.32.1 2021-01-27 POE::Wheel::ReadLine(3)