| Current File : //usr/local/share/man/man3/POE::Wheel::ReadLine.3pm |
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POE::Wheel::ReadLine 3"
.TH POE::Wheel::ReadLine 3 "2022-03-23" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
POE::Wheel::ReadLine \- non\-blocking Term::ReadLine for POE
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #!perl
\&
\& use warnings;
\& use strict;
\&
\& use POE qw(Wheel::ReadLine);
\&
\& POE::Session\->create(
\& inline_states=> {
\& _start => \e&setup_console,
\& got_user_input => \e&handle_user_input,
\& }
\& );
\&
\& POE::Kernel\->run();
\& exit;
\&
\& sub handle_user_input {
\& my ($input, $exception) = @_[ARG0, ARG1];
\& my $console = $_[HEAP]{console};
\&
\& unless (defined $input) {
\& $console\->put("$exception caught. B\*(Aqbye!");
\& $_[KERNEL]\->signal($_[KERNEL], "UIDESTROY");
\& $console\->write_history("./test_history");
\& return;
\& }
\&
\& $console\->put(" You entered: $input");
\& $console\->addhistory($input);
\& $console\->get("Go: ");
\& }
\&
\& sub setup_console {
\& $_[HEAP]{console} = POE::Wheel::ReadLine\->new(
\& InputEvent => \*(Aqgot_user_input\*(Aq
\& );
\& $_[HEAP]{console}\->read_history("./test_history");
\& $_[HEAP]{console}\->clear();
\& $_[HEAP]{console}\->put(
\& "Enter some text.",
\& "Ctrl+C or Ctrl+D exits."
\& );
\& $_[HEAP]{console}\->get("Go: ");
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
POE::Wheel::ReadLine is a non-blocking form of Term::ReadLine that's
compatible with \s-1POE.\s0 It uses Term::Cap to interact with the terminal
display and Term::ReadKey to interact with the keyboard.
.PP
POE::Wheel::ReadLine handles almost all common input editing keys. It
provides an input history list. It has both vi and emacs modes. It
supports incremental input search. It's fully customizable, and it's
compatible with standard \fBreadline\fR\|(3) implementations such as
Term::ReadLine::Gnu.
.PP
POE::Wheel::ReadLine is configured by placing commands in an \*(L"inputrc\*(R"
initialization file. The file's name is taken from the \f(CW\*(C`INPUTRC\*(C'\fR
environment variable, or ~/.inputrc by default. POE::Wheel::ReadLine
will read the inputrc file and configure itself according to the
commands and variables therein. See \fBreadline\fR\|(3) for details about
inputrc files.
.PP
The default editing mode will be emacs-style, although this can be
configured by setting the 'editing\-mode' variable within an inputrc
file. If all else fails, POE::Wheel::ReadLine will determine the
user's favorite editor by examining the \s-1EDITOR\s0 environment variable.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
.SS "Constructor"
.IX Subsection "Constructor"
Most of POE::Wheel::ReadLine's interaction is through its constructor,
\&\fBnew()\fR.
.PP
\fInew\fR
.IX Subsection "new"
.PP
\&\fBnew()\fR creates and returns a new POE::Wheel::ReadLine object. Be sure
to instantiate only one, as multiple console readers would conflict.
.PP
InputEvent
.IX Subsection "InputEvent"
.PP
\&\f(CW\*(C`InputEvent\*(C'\fR names the event that will indicate a new line of console
input. See \*(L"\s-1PUBLIC EVENTS\*(R"\s0 for more details.
.PP
PutMode
.IX Subsection "PutMode"
.PP
\&\f(CW\*(C`PutMode\*(C'\fR controls how output is displayed when \fBput()\fR is called
during user input.
.PP
When set to \*(L"immediate\*(R", \fBput()\fR pre-empts the user immediately. The
input prompt and user's input to date are redisplayed after \fBput()\fR is
done.
.PP
The \*(L"after\*(R" \f(CW\*(C`PutMode\*(C'\fR tells \fBput()\fR to wait until after the user enters
or cancels her input.
.PP
Finally, \*(L"idle\*(R" will allow \fBput()\fR to pre-empt user input if the user
stops typing for \*(L"IdleTime\*(R" seconds. This mode behaves like \*(L"after\*(R"
if the user can't stop typing long enough. This is
POE::Wheel::ReadLine's default mode.
.PP
IdleTime
.IX Subsection "IdleTime"
.PP
\&\f(CW\*(C`IdleTime\*(C'\fR tells POE::Wheel::ReadLine how long the keyboard must be
idle before \f(CW\*(C`put()\*(C'\fR becomes immediate or buffered text is flushed to
the display. It is only meaningful when \*(L"PutMode\*(R" is \*(L"idle\*(R".
\&\f(CW\*(C`IdleTime\*(C'\fR defaults to 2 seconds.
.PP
AppName
.IX Subsection "AppName"
.PP
\&\f(CW\*(C`AppName\*(C'\fR registers an application name which is used to retrieve
application-specific key bindings from the inputrc file. The default
\&\f(CW\*(C`AppName\*(C'\fR is \*(L"poe-readline\*(R".
.PP
.Vb 8
\& # If using POE::Wheel::ReadLine, set
\& # the key mapping to emacs mode and
\& # trigger debugging output on a certain
\& # key sequence.
\& $if poe\-readline
\& set keymap emacs
\& Control\-xP: poe\-wheel\-debug
\& $endif
.Ve
.SS "History List Management"
.IX Subsection "History List Management"
POE::Wheel::ReadLine supports an input history, with searching.
.PP
\fIadd_history\fR
.IX Subsection "add_history"
.PP
\&\fBadd_history()\fR accepts a list of lines to add to the input history.
Generally it's called with a single line: the last line of input
received from the terminal. The \*(L"\s-1SYNOPSIS\*(R"\s0 shows \fBadd_history()\fR in
action.
.PP
\fIget_history\fR
.IX Subsection "get_history"
.PP
\&\fBget_history()\fR returns a list containing POE::Wheel::ReadLine's current
input history. It may not contain everything entered into the wheel
.PP
\fIwrite_history\fR
.IX Subsection "write_history"
.PP
\&\fBwrite_history()\fR writes the current input history to a file. It
accepts one optional parameter: the name of the file where the input
history will be written. \fBwrite_history()\fR will write to ~/.history if
no file name is specified.
.PP
Returns true on success, or false if not.
.PP
The \*(L"\s-1SYNOPSIS\*(R"\s0 shows an example of \fBwrite_history()\fR and the
corresponding \fBread_history()\fR.
.PP
\fIread_history\fR
.IX Subsection "read_history"
.PP
read_history(\s-1FILENAME, START, END\s0) reads a previously saved input
history from a named file, or from ~/.history if no file name is
specified. It may also read a subset of the history file if it's
given optional \s-1START\s0 and \s-1END\s0 parameters. The file will be read from
the beginning if \s-1START\s0 is omitted or zero. It will be read to the end
if \s-1END\s0 is omitted or earlier than \s-1START.\s0
.PP
Returns true on success, or false if not.
.PP
The \*(L"\s-1SYNOPSIS\*(R"\s0 shows an example of \fBread_history()\fR and the
corresponding \fBwrite_history()\fR.
.PP
Read the first ten history lines:
.PP
.Vb 1
\& $_[HEAP]{console}\->read_history("filename", 0, 9);
.Ve
.PP
\fIhistory_truncate_file\fR
.IX Subsection "history_truncate_file"
.PP
\&\fBhistory_truncate_file()\fR truncates a history file to a certain number
of lines. It accepts two parameters: the name of the file to
truncate, and the maximum number of history lines to leave in the
file. The history file will be cleared entirely if the line count is
zero or omitted.
.PP
The file to be truncated defaults to ~/.history. So calling
\&\fBhistory_truncate_file()\fR with no parameters clears ~/.history.
.PP
Returns true on success, or false if not.
.PP
Note that \fBhistory_trucate_file()\fR removes the earliest lines from the
file. The later lines remain intact since they were the ones most
recently entered.
.PP
Keep ~/.history down to a manageable 100 lines:
.PP
.Vb 1
\& $_[HEAP]{console}\->history_truncate_file(undef, 100);
.Ve
.SS "Key Binding Methods"
.IX Subsection "Key Binding Methods"
\fIbind_key\fR
.IX Subsection "bind_key"
.PP
bind_key(\s-1KEYSTROKE, FUNCTION\s0) binds a \s-1FUNCTION\s0 to a named \s-1KEYSTROKE\s0
sequence. The keystroke sequence can be in any of the forms defined
within \fBreadline\fR\|(3). The function should either be a pre-defined name,
such as \*(L"self-insert\*(R" or a function reference. The binding is made in
the current keymap. Use the \fBrl_set_keymap()\fR method to change keymaps,
if desired.
.PP
\fIadd_defun \s-1NAME FN\s0\fR
.IX Subsection "add_defun NAME FN"
.PP
add_defun(\s-1NAME, FUNCTION\s0) defines a new global \s-1FUNCTION,\s0 giving it a
specific \s-1NAME.\s0 The function may then be bound to keystrokes by that
\&\s-1NAME.\s0
.SS "Console I/O Methods"
.IX Subsection "Console I/O Methods"
\fIclear\fR
.IX Subsection "clear"
.PP
Clears the terminal.
.PP
\fIterminal_size\fR
.IX Subsection "terminal_size"
.PP
Returns what POE::Wheel::ReadLine thinks are the current dimensions of
the terminal. Returns a list of two values: the number of columns and
number of rows, respectively.
.PP
.Vb 7
\& sub some_event_handler {
\& my ($columns, $rows) = $_[HEAP]{console}\->terminal_size;
\& $_[HEAP]{console}\->put(
\& "Terminal columns: $columns",
\& "Terminal rows: $rows",
\& );
\& }
.Ve
.PP
\fIget\fR
.IX Subsection "get"
.PP
\&\fBget()\fR causes POE::Wheel::ReadLine to display a prompt and then wait
for input. Input is not noticed unless \fBget()\fR has enabled the wheel's
internal I/O watcher.
.PP
After \fBget()\fR is called, the next line of input or exception on the
console will trigger an \f(CW\*(C`InputEvent\*(C'\fR with the appropriate parameters.
POE::Wheel::ReadLine will then enter an inactive state until \fBget()\fR is
called again.
.PP
Calls to \fBget()\fR without an argument will preserve the current prompt.
Calling \fBget()\fR with an argument before a whole line of input is
received will change the prompt on the fly.
.PP
See the \*(L"\s-1SYNOPSIS\*(R"\s0 for sample usage.
.PP
\fIput\fR
.IX Subsection "put"
.PP
\&\fBput()\fR accepts a list of lines to put on the terminal.
POE::Wheel::ReadLine is line-based. See POE::Wheel::Curses for
more funky display options.
.PP
Please do not use \fBprint()\fR with POE::Wheel::ReadLine. \fBprint()\fR
invariably gets the newline wrong, leaving an application's output to
stairstep down the terminal. Also, \fBput()\fR understands when a user is
entering text, and \f(CW\*(C`PutMode\*(C'\fR may be used to avoid interrupting the
user.
.SS "ReadLine Option Methods"
.IX Subsection "ReadLine Option Methods"
\fIattribs\fR
.IX Subsection "attribs"
.PP
\&\fBattribs()\fR returns a reference to a hash of readline options. The
returned hash may be used to query or modify POE::Wheel::ReadLine's
behavior.
.PP
\fIoption\fR
.IX Subsection "option"
.PP
option(\s-1NAME\s0) returns a specific member of the hash returned by
\&\fBattribs()\fR. It's a more convenient way to query POE::Wheel::ReadLine
options.
.SH "PUBLIC EVENTS"
.IX Header "PUBLIC EVENTS"
POE::Wheel::ReadLine emits only a single event.
.SS "InputEvent"
.IX Subsection "InputEvent"
\&\f(CW\*(C`InputEvent\*(C'\fR names the event that will be emitted upon any kind of
complete terminal input. Every \f(CW\*(C`InputEvent\*(C'\fR handler receives three
parameters:
.PP
\&\f(CW$_[ARG0]\fR contains a line of input. It may be an empty string if
the user entered an empty line. An undefined \f(CW$_[ARG0]\fR indicates
some exception such as end-of-input or the fact that the user canceled
their input or pressed C\-c (^C).
.PP
\&\f(CW$_[ARG1]\fR describes an exception, if one occurred. It may contain
one of the following strings:
.IP "cancel" 2
.IX Item "cancel"
The \*(L"cancel\*(R" exception indicates when a user has canceled a line of
input. It's sent when the user triggers the \*(L"abort\*(R" function, which
is bound to C\-g (^G) by default.
.IP "eot" 2
.IX Item "eot"
\&\*(L"eot\*(R" is the \s-1ASCII\s0 code for \*(L"end of tape\*(R". It's emitted when the user
requests that the terminal be closed. By default, it's triggered when
the user presses C\-d (^D) on an empty line.
.IP "interrupt" 2
.IX Item "interrupt"
\&\*(L"interrupt\*(R" is sent as a result of the user pressing C\-c (^C) or
otherwise triggering the \*(L"interrupt\*(R" function.
.PP
Finally, \f(CW$_[ARG2]\fR contains the \s-1ID\s0 for the POE::Wheel::ReadLine
object that sent the \f(CW\*(C`InputEvent\*(C'\fR.
.SH "CUSTOM BINDINGS"
.IX Header "CUSTOM BINDINGS"
POE::Wheel::ReadLine allows custom functions to be bound to
keystrokes. The function must be made visible to the wheel before it
can be bound. To register a function, use POE::Wheel::ReadLine's
\&\fBadd_defun()\fR method:
.PP
.Vb 1
\& POE::Wheel::ReadLine\->add_defun(\*(Aqreverse\-line\*(Aq, \e&reverse_line);
.Ve
.PP
When adding a new defun, an optional third parameter may be provided
which is a key sequence to bind to. This should be in the same format
as that understood by the inputrc parsing.
.PP
Bound functions receive three parameters: A reference to the wheel
object itself, the key sequence that triggered the function (in
printable form), and the raw key sequence. The bound function is
expected to dig into the POE::Wheel::ReadLine data members to do its
work and display the new line contents itself.
.PP
This is less than ideal, and it may change in the future.
.SH "CUSTOM COMPLETION"
.IX Header "CUSTOM COMPLETION"
An application may modify POE::Wheel::ReadLine's \*(L"completion_function\*(R"
in order to customize how input should be completed. The new
completion function must accept three scalar parameters: the word
being completed, the entire input text, and the position within the
input text of the word being completed.
.PP
The completion function should return a list of possible matches. For
example:
.PP
.Vb 5
\& my $attribs = $wheel\->attribs();
\& $attribs\->{completion_function} = sub {
\& my ($text, $line, $start) = @_;
\& return qw(a list of candidates to complete);
\& }
.Ve
.PP
This is the only form of completion currently supported.
.SH "IMPLEMENTATION DIFFERENCES"
.IX Header "IMPLEMENTATION DIFFERENCES"
Although POE::Wheel::ReadLine is modeled after the \fBreadline\fR\|(3)
library, there are some areas which have not been implemented. The
only option settings which have effect in this implementation are:
bell-style, editing-mode, isearch-terminators, comment-begin,
print-completions-horizontally, show-all-if-ambiguous and
completion_function.
.PP
The function 'tab\-insert' is not implemented, nor are tabs displayed
properly.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
POE::Wheel describes the basic operations of all wheels in more
depth. You need to know this.
.PP
\&\fBreadline\fR\|(3), Term::Cap, Term::ReadKey.
.PP
The \s-1SEE ALSO\s0 section in \s-1POE\s0 contains a table of contents covering
the entire \s-1POE\s0 distribution.
.PP
Term::Visual is an alternative to POE::Wheel::ReadLine. It
provides scrollback and a status bar in addition to editable user
input. Term::Visual supports \s-1POE\s0 despite the lack of \*(L"\s-1POE\*(R"\s0 in its
name.
.SH "BUGS"
.IX Header "BUGS"
POE::Wheel::ReadLine has some known issues:
.SS "Perl 5.8.0 is Broken"
.IX Subsection "Perl 5.8.0 is Broken"
Non-blocking input with Term::ReadKey does not work with Perl 5.8.0,
especially on Linux systems for some reason. Upgrading Perl will fix
things. If you can't upgrade Perl, consider alternative input
methods, such as Term::Visual.
.PP
<http://rt.cpan.org/Ticket/Display.html?id=4524> and related tickets
explain the issue in detail. If you suspect your system is one where
Term::ReadKey fails, you can run this test program to be sure.
.PP
.Vb 10
\& #!/usr/bin/perl
\& use Term::ReadKey;
\& print "Press \*(Aqq\*(Aq to quit this test.\en";
\& ReadMode 5; # Turns off controls keys
\& while (1) {
\& while (not defined ($key = ReadKey(\-1))) {
\& print "Didn\*(Aqt get a key. Sleeping 1 second.\e015\e012";
\& sleep (1);
\& }
\& print "Got key: $key\e015\e012";
\& ($key eq \*(Aqq\*(Aq) and last;
\& }
\& ReadMode 0; # Reset tty mode before exiting
\& exit;
.Ve
.SS "Non-Optimal Code"
.IX Subsection "Non-Optimal Code"
Dissociating the input and display cursors introduced a lot of code.
Much of this code was thrown in hastily, and things can probably be
done with less work.
.SS "Unimplemented Features"
.IX Subsection "Unimplemented Features"
Input editing is not kept on one line. If it wraps, and a terminal
cannot wrap back through a line division, the cursor will become lost.
.PP
Unicode support. I feel real bad about throwing away native
representation of all the 8th\-bit\-set characters. I also have no idea
how to do this, and I don't have a system to test this. Patches are
very much welcome.
.SH "GOTCHAS / FAQ"
.IX Header "GOTCHAS / FAQ"
.SS "Lost Prompts"
.IX Subsection "Lost Prompts"
Q: Why do I lose my prompt every time I send output to the screen?
.PP
A: You probably are using print or printf to write screen output.
ReadLine doesn't track \s-1STDOUT\s0 itself, so it doesn't know when to
refresh the prompt after you do this. Use ReadLine's \fBput()\fR method to
write lines to the console.
.SS "Edit Keystrokes Display as ^C"
.IX Subsection "Edit Keystrokes Display as ^C"
Q: None of the editing keystrokes work. Ctrl-C displays \*(L"^c\*(R" rather
than generating an interrupt. The arrow keys don't scroll through my
input history. It's generally a bad experience.
.PP
A: You're probably a vi/vim user. In the absence of a ~/.inputrc
file, POE::Wheel::ReadLine checks your \s-1EDITOR\s0 environment variable for
clues about your editing preference. If it sees /vi/ in there, it
starts in vi mode. You can override this by creating a ~/.inputrc
file containing the line \*(L"set editing-mode emacs\*(R", or adding that line
to your existing ~/.inputrc. While you're in there, you should
totally get acquainted with all the other cool stuff you can do with
\&.inputrc files.
.SS "Lack of Windows Support"
.IX Subsection "Lack of Windows Support"
Q: Why doesn't POE::Wheel::ReadLine work on Windows? Term::ReadLine
does.
.PP
A: POE::Wheel::ReadLine requires \fBselect()\fR, because that's what \s-1POE\s0
uses by default to detect keystrokes without blocking. About half the
flavors of Perl on Windows implement \fBselect()\fR in terms of the same
function in the WinSock library, which limits \fBselect()\fR to working only
with sockets. Your console isn't a socket, so \fBselect()\fR doesn't work
with your version of Perl on Windows.
.PP
Really good workarounds are possible but don't exist as of this
writing. They involve writing a special POE::Loop for Windows that
either uses a Win32\-specific module for better multiplexing, that
polls for input, or that uses blocking I/O watchers in separate
threads.
.SS "Cygwin Support"
.IX Subsection "Cygwin Support"
Q: Why does POE::Wheel::ReadLine complain about my \*(L"dumb\*(R" terminal?
.PP
A: Do you have Strawberry Perl installed? Due to the way it works, on
installation it sets a global environment variable in MSWin32 for
TERM=dumb. ( it may be fixed in a future version, but it's here to stay
for now, ha! ) In this case, logging into the Cygwin shell via the
cygwin.bat launcher results in a nonfunctional readline.
.PP
Normally, Cygwin will set TERM=cygwin in the launcher. However, if the
\&\s-1TERM\s0 was already set it will not alter the value. Hence, the \*(L"bug\*(R"
appears! What you can do is to hack the cygwin.bat file to add this line:
.PP
.Vb 1
\& SET TERM=cygwin
.Ve
.PP
Other users reported that you can have better results by editing the
~/.bash_profile file to set TERM=cygwin because on a Cygwin upgrade it
overwrites the cygwin.bat file.
.PP
Alternatively, you could install different terminals like \*(L"xterm\*(R" or \*(L"rxvt\*(R"
as shown here: <http://c2.com/cgi/wiki?BetterCygwinTerminal>. Please let
us know if you encounter problems using any terminal other than \*(L"dumb\*(R".
.PP
If you feel brave, you can peruse the \s-1RT\s0 ticket at
<http://rt.cpan.org/Ticket/Display.html?id=55365> for more information
on this problem.
.SH "AUTHORS & COPYRIGHTS"
.IX Header "AUTHORS & COPYRIGHTS"
POE::Wheel::ReadLine was originally written by Rocco Caputo.
.PP
Nick Williams virtually rewrote it to support a larger subset of \s-1GNU\s0
readline.
.PP
Please see \s-1POE\s0 for more information about other authors and
contributors.