| 1 |
NAME |
| 2 |
AnyEvent::ReadLine::Gnu - event-based interface to Term::ReadLine::Gnu |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use AnyEvent::ReadLine::Gnu; |
| 6 |
|
| 7 |
# works always, prints message to stdout |
| 8 |
AnyEvent::ReadLine::Gnu->print ("message\n"); |
| 9 |
|
| 10 |
# now initialise readline |
| 11 |
my $rl = new AnyEvent::ReadLine::Gnu prompt => "hi> ", on_line => sub { |
| 12 |
# called for each line entered by the user |
| 13 |
AnyEvent::ReadLine::Gnu->print ("you entered: $_[0]\n"); |
| 14 |
}; |
| 15 |
|
| 16 |
# asynchronously print something |
| 17 |
my $t = AE::timer 1, 1, sub { |
| 18 |
$rl->hide; |
| 19 |
print "async message 1\n"; # mind the \n |
| 20 |
$rl->show; |
| 21 |
|
| 22 |
# the same, but shorter: |
| 23 |
$rl->print ("async message 2\n"); |
| 24 |
}; |
| 25 |
|
| 26 |
# do other eventy stuff... |
| 27 |
AE::cv->recv; |
| 28 |
|
| 29 |
DESCRIPTION |
| 30 |
The Term::ReadLine module family is bizarre (and you are encouraged not |
| 31 |
to look at its sources unless you want to go blind). It does support |
| 32 |
event-based operations, somehow, but it's hard to figure out. |
| 33 |
|
| 34 |
It also has some utility functions for printing messages asynchronously, |
| 35 |
something that, again, isn't obvious how to do. |
| 36 |
|
| 37 |
This module has figured it all out for you, once and for all. |
| 38 |
|
| 39 |
$rl = new AnyEvent::ReadLine::Gnu key => value... |
| 40 |
Creates a new AnyEvent::ReadLine object. |
| 41 |
|
| 42 |
Actually, it only configures readline and provides a convenient way |
| 43 |
to call the show and hide methods, as well as readline methods - |
| 44 |
this is a singleton. |
| 45 |
|
| 46 |
The returned object is the standard Term::ReadLine::Gnu object, all |
| 47 |
methods that are documented (or working) for that module should work |
| 48 |
on this object. |
| 49 |
|
| 50 |
Once initialised, this module will also restore the terminal |
| 51 |
settings on a normal program exit. |
| 52 |
|
| 53 |
The callback will be installed with the "CallbackHandlerInstall", |
| 54 |
which means it handles history expansion and history, among other |
| 55 |
things. |
| 56 |
|
| 57 |
The following key-value pairs are supported: |
| 58 |
|
| 59 |
on_line => $cb->($string) |
| 60 |
The only mandatory parameter - passes the callback that will |
| 61 |
receive lines that are completed by the user. |
| 62 |
|
| 63 |
The string will be in locale-encoding (a multibyte character |
| 64 |
string). For example, in an utf-8 using locale it will be utf-8. |
| 65 |
There is no portable way known to the author to convert this |
| 66 |
into e.g. a unicode string. |
| 67 |
|
| 68 |
prompt => $string |
| 69 |
The prompt string to use, defaults to ">". |
| 70 |
|
| 71 |
name => $string |
| 72 |
The readline application name, defaults to $0. |
| 73 |
|
| 74 |
in => $glob |
| 75 |
The input filehandle (should be a glob): defaults to *STDIN. |
| 76 |
|
| 77 |
out => $glob |
| 78 |
The output filehandle (should be a glob): defaults to *STDOUT. |
| 79 |
|
| 80 |
$rl->hide |
| 81 |
AnyEvent::ReadLine::Gnu->hide |
| 82 |
These methods *hide* the readline prompt and text. Basically, it |
| 83 |
removes the readline feedback from your terminal. |
| 84 |
|
| 85 |
It is safe to call even when AnyEvent::ReadLine::Gnu has not yet |
| 86 |
been initialised. |
| 87 |
|
| 88 |
This is immensely useful in an event-based program when you want to |
| 89 |
output some stuff to the terminal without disturbing the prompt - |
| 90 |
just "hide" readline, output your thing, then "show" it again. |
| 91 |
|
| 92 |
Since user input will not be processed while readline is hidden, you |
| 93 |
should call "show" as soon as possible. |
| 94 |
|
| 95 |
$rl->show |
| 96 |
AnyEvent::ReadLine::Gnu->show |
| 97 |
Undos any hiding. Every call to "hide" has to be followed to a call |
| 98 |
to "show". The last call will redisplay the readline prompt, current |
| 99 |
input line and cursor position. Keys entered while the prompt was |
| 100 |
hidden will be processed again. |
| 101 |
|
| 102 |
$rl->print ($string, ...) |
| 103 |
AnyEvent::ReadLine::Gnu->print ($string, ...) |
| 104 |
Prints the given strings to the terminal, by first hiding the |
| 105 |
readline, printing the message, and showing it again. |
| 106 |
|
| 107 |
This function can be called even when readline has never been |
| 108 |
initialised. |
| 109 |
|
| 110 |
The last string should end with a newline. |
| 111 |
|
| 112 |
CAVEATS |
| 113 |
There are some issues with readline that can be problematic in |
| 114 |
event-based programs: |
| 115 |
|
| 116 |
blocking I/O |
| 117 |
Readline uses blocking terminal I/O. Under most circumstances, this |
| 118 |
does not cause big delays, but ttys have the potential to block |
| 119 |
programs indefinitely (e.g. on XOFF). |
| 120 |
|
| 121 |
unexpected disk I/O |
| 122 |
By default, readline does filename completion on TAB, and reads its |
| 123 |
config files. |
| 124 |
|
| 125 |
Tab completion can be disabled by calling "$rl->unbind_key (9)". |
| 126 |
|
| 127 |
tty settings |
| 128 |
After readline has been initialised, it will mangle the termios tty |
| 129 |
settings. This does not normally affect output very much, but should |
| 130 |
be taken into consideration. |
| 131 |
|
| 132 |
output intermixing |
| 133 |
Your program might wish to print messages (for example, log |
| 134 |
messages) to STDOUT or STDERR. This will usually cause confusion, |
| 135 |
unless readline is hidden with the hide method. |
| 136 |
|
| 137 |
Oh, and the above list is probably not complete. |
| 138 |
|
| 139 |
AUTHOR, CONTACT, SUPPORT |
| 140 |
Marc Lehmann <schmorp@schmorp.de> |
| 141 |
http://software.schmorp.de/pkg/AnyEvent-ReadLine-Gnu.html |
| 142 |
|
| 143 |
SEE ALSO |
| 144 |
rltelnet - a simple tcp_connect-with-readline program using this module. |
| 145 |
|
