ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-ReadLine-Gnu/README
Revision: 1.3
Committed: Fri May 11 15:38:02 2012 UTC (12 years, 2 months ago) by root
Branch: MAIN
CVS Tags: rel-1_1, rel-1_0, HEAD
Changes since 1.2: +35 -1 lines
Log Message:
1.0

File Contents

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