1POE::Wheel::ReadLine(3)User Contributed Perl DocumentatioPnOE::Wheel::ReadLine(3)
2
3
4

NAME

6       POE::Wheel::ReadLine - non-blocking Term::ReadLine for POE
7

SYNOPSIS

9         #!perl
10
11         use warnings;
12         use strict;
13
14         use POE qw(Wheel::ReadLine);
15
16         POE::Session->create(
17           inline_states=> {
18             _start => \&setup_console,
19             got_user_input => \&handle_user_input,
20           }
21         );
22
23         POE::Kernel->run();
24         exit;
25
26         sub handle_user_input {
27           my ($input, $exception) = @_[ARG0, ARG1];
28           my $console = $_[HEAP]{console};
29
30           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
37           $console->put("  You entered: $input");
38           $console->addhistory($input);
39           $console->get("Go: ");
40         }
41
42         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

DESCRIPTION

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
60       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
66       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
73       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

PUBLIC METHODS

79   Constructor
80       Most of POE::Wheel::ReadLine's interaction is through its constructor,
81       new().
82
83       new
84
85       new() creates and returns a new POE::Wheel::ReadLine object.  Be sure
86       to instantiate only one, as multiple console readers would conflict.
87
88       InputEvent
89
90       "InputEvent" names the event that will indicate a new line of console
91       input.  See "PUBLIC EVENTS" for more details.
92
93       PutMode
94
95       "PutMode" controls how output is displayed when put() is called during
96       user input.
97
98       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
102       The "after" "PutMode" tells put() to wait until after the user enters
103       or cancels her input.
104
105       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
110       IdleTime
111
112       "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
117       AppName
118
119       "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
123         # 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
132   History List Management
133       POE::Wheel::ReadLine supports an input history, with searching.
134
135       add_history
136
137       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
142       get_history
143
144       get_history() returns a list containing POE::Wheel::ReadLine's current
145       input history.  It may not contain everything entered into the wheel
146
147       write_history
148
149       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
154       Returns true on success, or false if not.
155
156       The "SYNOPSIS" shows an example of write_history() and the
157       corresponding read_history().
158
159       read_history
160
161       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
168       Returns true on success, or false if not.
169
170       The "SYNOPSIS" shows an example of read_history() and the corresponding
171       write_history().
172
173       Read the first ten history lines:
174
175         $_[HEAP]{console}->read_history("filename", 0, 9);
176
177       history_truncate_file
178
179       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
185       The file to be truncated defaults to ~/.history.  So calling
186       history_truncate_file() with no parameters clears ~/.history.
187
188       Returns true on success, or false if not.
189
190       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
194       Keep ~/.history down to a manageable 100 lines:
195
196         $_[HEAP]{console}->history_truncate_file(undef, 100);
197
198   Key Binding Methods
199       bind_key
200
201       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
208       add_defun NAME FN
209
210       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
214   Console I/O Methods
215       clear
216
217       Clears the terminal.
218
219       terminal_size
220
221       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
225         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
233       get
234
235       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
239       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
244       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
248       See the "SYNOPSIS" for sample usage.
249
250       put
251
252       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
256       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
262   ReadLine Option Methods
263       attribs
264
265       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
269       option
270
271       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

PUBLIC EVENTS

276       POE::Wheel::ReadLine emits only a single event.
277
278   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
283       $_[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
288       $_[ARG1] describes an exception, if one occurred.  It may contain one
289       of the following strings:
290
291       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
296       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
301       interrupt
302         "interrupt" is sent as a result of the user pressing C-c (^C) or
303         otherwise triggering the "interrupt" function.
304
305       Finally, $_[ARG2] contains the ID for the POE::Wheel::ReadLine object
306       that sent the "InputEvent".
307

CUSTOM BINDINGS

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
313         POE::Wheel::ReadLine->add_defun('reverse-line', \&reverse_line);
314
315       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
319       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
325       This is less than ideal, and it may change in the future.
326

CUSTOM COMPLETION

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
334       The completion function should return a list of possible matches.  For
335       example:
336
337         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
343       This is the only form of completion currently supported.
344

IMPLEMENTATION DIFFERENCES

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
352       The function 'tab-insert' is not implemented, nor are tabs displayed
353       properly.
354

SEE ALSO

356       POE::Wheel describes the basic operations of all wheels in more depth.
357       You need to know this.
358
359       readline(3), Term::Cap, Term::ReadKey.
360
361       The SEE ALSO section in POE contains a table of contents covering the
362       entire POE distribution.
363
364       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

BUGS

369       POE::Wheel::ReadLine has some known issues:
370
371   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
377       <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
381         #!/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
396   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
401   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
405       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

GOTCHAS / FAQ

411   Lost Prompts
412       Q: Why do I lose my prompt every time I send output to the screen?
413
414       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
419   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
424       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
433   Lack of Windows Support
434       Q: Why doesn't POE::Wheel::ReadLine work on Windows?  Term::ReadLine
435       does.
436
437       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
444       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
449   Cygwin Support
450       Q: Why does POE::Wheel::ReadLine complain about my "dumb" terminal?
451
452       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
458       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
463         SET TERM=cygwin
464
465       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
469       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
474       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

AUTHORS & COPYRIGHTS

479       POE::Wheel::ReadLine was originally written by Rocco Caputo.
480
481       Nick Williams virtually rewrote it to support a larger subset of GNU
482       readline.
483
484       Please see POE for more information about other authors and
485       contributors.
486
487
488
489perl v5.36.0                      2022-07-22           POE::Wheel::ReadLine(3)
Impressum