[ViewVC] Contents 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 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.

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

Revision:	1.2
Committed:	Thu May 10 21:53:03 2012 UTC (12 years ago) by root
Branch:	MAIN
CVS Tags:	rel-0_2
Changes since 1.1:	+111 -0 lines
Log Message:	0.2
#	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 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
108	AUTHOR, CONTACT, SUPPORT
109	Marc Lehmann <schmorp@schmorp.de>
110	http://software.schmorp.de/pkg/AnyEvent-Readline-Gnu.html
111