ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-ReadLine-Gnu/README
(Generate patch)

Comparing AnyEvent-ReadLine-Gnu/README (file contents):
Revision 1.1 by root, Thu May 10 02:21:49 2012 UTC vs.
Revision 1.2 by root, Thu May 10 21:53:03 2012 UTC

1NAME
2 AnyEvent::ReadLine::Gnu - event-based interface to Term::ReadLine::Gnu
3
4SYNOPSIS
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
29DESCRIPTION
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 following key-value pairs are supported:
54
55 on_line => $cb->($string)
56 The only mandatory parameter - passes the callback that will
57 receive lines that are completed by the user.
58
59 The string will be in locale-encoding (a multibyte character
60 string). For example, in an utf-8 using locale it will be utf-8.
61 There is no portable way known to the author to convert this
62 into e.g. a unicode string.
63
64 prompt => $string
65 The prompt string to use, defaults to ">".
66
67 name => $string
68 The readline application name, defaults to $0.
69
70 in => $glob
71 The input filehandle (should be a glob): defaults to *STDIN.
72
73 out => $glob
74 The output filehandle (should be a glob): defaults to *STDOUT.
75
76 $rl->hide
77 AnyEvent::ReadLine::Gnu->hide
78 These methods *hide* the readline prompt and text. Basically, it
79 removes the readline feedback from your terminal.
80
81 It is safe to call even when AnyEvent::ReadLine::Gnu has not yet
82 been initialised.
83
84 This is immensely useful in an event-based program when you want to
85 output some stuff to the terminal without disturbing the prompt -
86 just "hide" readline, output your thing, then "show" it again.
87
88 Since user input will not be processed while readline is hidden, you
89 should call "show" as soon as possible.
90
91 $rl->show
92 AnyEvent::ReadLine::Gnu->show
93 Undos any hiding. Every call to "hide" has to be followed to a call
94 to "show". The last call will redisplay the readline prompt, current
95 input line and cursor position. Keys entered while the prompt was
96 hidden will be processed again.
97
98 $rl->print ($string, ...)
99 AnyEvent::ReadLine::Gnu->print ($string, ...)
100 Prints the given strings to the terminal, by first hiding the
101 readline, printing the message, and showing it again.
102
103 This function can be called even when readline has never been
104 initialised.
105
106 The last string should end with a newline.
107
108AUTHOR, CONTACT, SUPPORT
109 Marc Lehmann <schmorp@schmorp.de>
110 http://software.schmorp.de/pkg/AnyEvent-Readline-Gnu.html
111

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines