|
|
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 | |