[ViewVC] Annotation of: cvs/AnyEvent-ReadLine-Gnu/README

NAME
    AnyEvent::ReadLine::Gnu - event-based interface to Term::ReadLine::Gnu

SYNOPSIS
     use AnyEvent::ReadLine::Gnu;

     # works always, prints message to stdout
     AnyEvent::ReadLine::Gnu->print ("message\n");

     # now initialise readline
     my $rl = new AnyEvent::ReadLine::Gnu prompt => "hi> ", on_line => sub {
        # called for each line entered by the user
        AnyEvent::ReadLine::Gnu->print ("you entered: $_[0]\n");
     };

     # asynchronously print something
     my $t = AE::timer 1, 1, sub {
        $rl->hide;
        print "async message 1\n"; # mind the \n
        $rl->show;

        # the same, but shorter:
        $rl->print ("async message 2\n");
     };

     # do other eventy stuff...
     AE::cv->recv;

DESCRIPTION
    The Term::ReadLine module family is bizarre (and you are encouraged not
    to look at its sources unless you want to go blind). It does support
    event-based operations, somehow, but it's hard to figure out.

    It also has some utility functions for printing messages asynchronously,
    something that, again, isn't obvious how to do.

    This module has figured it all out for you, once and for all.

    $rl = new AnyEvent::ReadLine::Gnu key => value...
        Creates a new AnyEvent::ReadLine object.

        Actually, it only configures readline and provides a convenient way
        to call the show and hide methods, as well as readline methods -
        this is a singleton.

        The returned object is the standard Term::ReadLine::Gnu object, all
        methods that are documented (or working) for that module should work
        on this object.

        Once initialised, this module will also restore the terminal
        settings on a normal program exit.

        The callback will be installed with the "CallbackHandlerInstall",
        which means it handles history expansion and history, among other
        things.

        The following key-value pairs are supported:

        on_line => $cb->($string)
            The only mandatory parameter - passes the callback that will
            receive lines that are completed by the user.

            The string will be in locale-encoding (a multibyte character
            string). For example, in an utf-8 using locale it will be utf-8.
            There is no portable way known to the author to convert this
            into e.g. a unicode string.

        prompt => $string
            The prompt string to use, defaults to ">".

        name => $string
            The readline application name, defaults to $0.

        in => $glob
            The input filehandle (should be a glob): defaults to *STDIN.

        out => $glob
            The output filehandle (should be a glob): defaults to *STDOUT.

    $rl->hide
    AnyEvent::ReadLine::Gnu->hide
        These methods *hide* the readline prompt and text. Basically, it
        removes the readline feedback from your terminal.

        It is safe to call even when AnyEvent::ReadLine::Gnu has not yet
        been initialised.

        This is immensely useful in an event-based program when you want to
        output some stuff to the terminal without disturbing the prompt -
        just "hide" readline, output your thing, then "show" it again.

        Since user input will not be processed while readline is hidden, you
        should call "show" as soon as possible.

    $rl->show
    AnyEvent::ReadLine::Gnu->show
        Undos any hiding. Every call to "hide" has to be followed to a call
        to "show". The last call will redisplay the readline prompt, current
        input line and cursor position. Keys entered while the prompt was
        hidden will be processed again.

    $rl->print ($string, ...)
    AnyEvent::ReadLine::Gnu->print ($string, ...)
        Prints the given strings to the terminal, by first hiding the
        readline, printing the message, and showing it again.

        This function can be called even when readline has never been
        initialised.

        The last string should end with a newline.

CAVEATS
    There are some issues with readline that can be problematic in
    event-based programs:

    blocking I/O
        Readline uses blocking terminal I/O. Under most circumstances, this
        does not cause big delays, but ttys have the potential to block
        programs indefinitely (e.g. on XOFF).

    unexpected disk I/O
        By default, readline does filename completion on TAB, and reads its
        config files.

        Tab completion can be disabled by calling "$rl->unbind_key (9)".

    tty settings
        After readline has been initialised, it will mangle the termios tty
        settings. This does not normally affect output very much, but should
        be taken into consideration.

    output intermixing
        Your program might wish to print messages (for example, log
        messages) to STDOUT or STDERR. This will usually cause confusion,
        unless readline is hidden with the hide method.

    Oh, and the above list is probably not complete.

AUTHOR, CONTACT, SUPPORT
     Marc Lehmann <schmorp@schmorp.de>
     http://software.schmorp.de/pkg/AnyEvent-ReadLine-Gnu.html

SEE ALSO
    rltelnet - a simple tcp_connect-with-readline program using this module.

Revision:	1.3
Committed:	Fri May 11 15:38:02 2012 UTC (12 years 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
#	User	Rev	Content
1	root	1.2	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	root	1.3	The callback will be installed with the "CallbackHandlerInstall",
54			which means it handles history expansion and history, among other
55			things.
56
57	root	1.2	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	root	1.3	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	root	1.2	AUTHOR, CONTACT, SUPPORT
140			Marc Lehmann <schmorp@schmorp.de>
141	root	1.3	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	root	1.2