AnyEvent-ReadLine-Gnu/Gnu.pm

=head1 NAME

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

=head1 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> ", cb => 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;

=head1 DESCRIPTION

The L<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.

=over 4

=cut

package AnyEvent::ReadLine::Gnu;

use common::sense;
use AnyEvent;

BEGIN {
   # we try our best
   local $ENV{PERL_RL} = "Gnu";

   require Term::ReadLine;
   require Term::ReadLine::Gnu;
}

use base Term::ReadLine::;

our $VERSION = '0.1';

=item $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 L<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:

=over 4

=item on_line => $cb->($string)

The only mandatory parameter - passes the callback that will receive lines
that are completed by the user.

=item prompt => $string

The prompt string to use, defaults to C<< >  >>.

=item name => $string

The readline application name, defaults to C<$0>.

=item in => $glob

The input filehandle (should be a glob): defaults to C<*STDIN>.

=item out => $glob

The output filehandle (should be a glob): defaults to C<*STDOUT>.

=back

=cut

our $self;
our $prompt;
our $cb;
our $hidden;
our $rw;
our ($in, $out);

our $saved_point;
our $saved_line;

sub new {
   my ($class, %arg) = @_;

   $in     = $arg{in}  || *STDIN;
   $out    = $arg{out} || *STDOUT;
   $prompt = $arg{prompt} || "> ";
   $cb     = $arg{on_line};

   $self = $class->SUPER::new ($arg{name} || $0, $in, $out);

   $self->CallbackHandlerInstall ($prompt, $cb);
   # set the unadorned prompt
   $self->rl_set_prompt ($prompt);

   $hidden = 1;
   $self->show;

   $self
}

=item $rl->hide

=item AnyEvent::ReadLine::Gnu->hide

These methods I<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 C<hide>
readline, output your thing, then C<show> it again.

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

=cut

sub hide {
   return if !$self || $hidden++;

   undef $rw;

   $saved_point = $self->{point};
   $saved_line  = $self->{line_buffer};

   $self->rl_set_prompt ("");
   $self->{line_buffer} = "";
   $self->rl_redisplay;
}

=item $rl->show

=item AnyEvent::ReadLine::Gnu->show

Undos any hiding. Every call to C<hide> has to be followed to a call to
C<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.

=cut

sub show {
   return if !$self || --$hidden;

   if (defined $saved_point) {
      $self->rl_set_prompt ($prompt);
      $self->{line_buffer} = $saved_line;
      $self->{point}       = $saved_point;
      $self->redisplay;
   }

   $rw = AE::io $in, 0, sub {
      $self->rl_callback_read_char;
   };
}

=item $rl->print ($string, ...)

=item 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 cna be called even when readline has never been initialised.

The last string should end with a newline.

=cut

sub print {
   shift;

   hide;
   my $out = $out || *STDOUT;
   print $out @_;
   show;
}

END {
   return unless $self;

   $self->hide;
   $self->callback_handler_remove;
}

1;

=back

=head1 AUTHOR, CONTACT, SUPPORT

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

=cut

Revision:	1.1
Committed:	Thu May 10 02:21:49 2012 UTC (12 years ago) by root
Branch:	MAIN
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			AnyEvent::ReadLine::Gnu - event-based interface to Term::ReadLine::Gnu
4
5			=head1 SYNOPSIS
6
7			use AnyEvent::ReadLine::Gnu;
8
9			# works always, prints message to stdout
10			AnyEvent::ReadLine::Gnu->print ("message\n");
11
12			# now initialise readline
13			my $rl = new AnyEvent::ReadLine::Gnu prompt => "hi> ", cb => sub {
14			# called for each line entered by the user
15			AnyEvent::ReadLine::Gnu->print ("you entered: $_[0]\n");
16			};
17
18			# asynchronously print something
19			my $t = AE::timer 1, 1, sub {
20			$rl->hide;
21			print "async message 1\n"; # mind the \n
22			$rl->show;
23
24			# the same, but shorter:
25			$rl->print ("async message 2\n");
26			};
27
28			# do other eventy stuff...
29			AE::cv->recv;
30
31			=head1 DESCRIPTION
32
33			The L<Term::ReadLine> module family is bizarre (and you are encouraged not
34			to look at its sources unless you want to go blind). It does support
35			event-based operations, somehow, but it's hard to figure out.
36
37			It also has some utility functions for printing messages asynchronously,
38			something that, again, isn't obvious how to do.
39
40			This module has figured it all out for you, once and for all.
41
42			=over 4
43
44			=cut
45
46			package AnyEvent::ReadLine::Gnu;
47
48			use common::sense;
49			use AnyEvent;
50
51			BEGIN {
52			# we try our best
53			local $ENV{PERL_RL} = "Gnu";
54
55			require Term::ReadLine;
56			require Term::ReadLine::Gnu;
57			}
58
59			use base Term::ReadLine::;
60
61			our $VERSION = '0.1';
62
63			=item $rl = new AnyEvent::ReadLine::Gnu key => value...
64
65			Creates a new AnyEvent::ReadLine object.
66
67			Actually, it only configures readline and provides a convenient way to
68			call the show and hide methods, as well as readline methods - this is a
69			singleton.
70
71			The returned object is the standard L<Term::ReadLine::Gnu> object, all
72			methods that are documented (or working) for that module should work on
73			this object.
74
75			Once initialised, this module will also restore the terminal settings on a
76			normal program exit.
77
78			The following key-value pairs are supported:
79
80			=over 4
81
82			=item on_line => $cb->($string)
83
84			The only mandatory parameter - passes the callback that will receive lines
85			that are completed by the user.
86
87			=item prompt => $string
88
89			The prompt string to use, defaults to C<< > >>.
90
91			=item name => $string
92
93			The readline application name, defaults to C<$0>.
94
95			=item in => $glob
96
97			The input filehandle (should be a glob): defaults to C<*STDIN>.
98
99			=item out => $glob
100
101			The output filehandle (should be a glob): defaults to C<*STDOUT>.
102
103			=back
104
105			=cut
106
107			our $self;
108			our $prompt;
109			our $cb;
110			our $hidden;
111			our $rw;
112			our ($in, $out);
113
114			our $saved_point;
115			our $saved_line;
116
117			sub new {
118			my ($class, %arg) = @_;
119
120			$in = $arg{in} \|\| *STDIN;
121			$out = $arg{out} \|\| *STDOUT;
122			$prompt = $arg{prompt} \|\| "> ";
123			$cb = $arg{on_line};
124
125			$self = $class->SUPER::new ($arg{name} \|\| $0, $in, $out);
126
127			$self->CallbackHandlerInstall ($prompt, $cb);
128			# set the unadorned prompt
129			$self->rl_set_prompt ($prompt);
130
131			$hidden = 1;
132			$self->show;
133
134			$self
135			}
136
137			=item $rl->hide
138
139			=item AnyEvent::ReadLine::Gnu->hide
140
141			These methods I<hide> the readline prompt and text. Basically, it removes
142			the readline feedback from your terminal.
143
144			It is safe to call even when AnyEvent::ReadLine::Gnu has not yet been
145			initialised.
146
147			This is immensely useful in an event-based program when you want to output
148			some stuff to the terminal without disturbing the prompt - just C<hide>
149			readline, output your thing, then C<show> it again.
150
151			Since user input will not be processed while readline is hidden, you
152			should call C<show> as soon as possible.
153
154			=cut
155
156			sub hide {
157			return if !$self \|\| $hidden++;
158
159			undef $rw;
160
161			$saved_point = $self->{point};
162			$saved_line = $self->{line_buffer};
163
164			$self->rl_set_prompt ("");
165			$self->{line_buffer} = "";
166			$self->rl_redisplay;
167			}
168
169			=item $rl->show
170
171			=item AnyEvent::ReadLine::Gnu->show
172
173			Undos any hiding. Every call to C<hide> has to be followed to a call to
174			C<show>. The last call will redisplay the readline prompt, current input
175			line and cursor position. Keys entered while the prompt was hidden will be
176			processed again.
177
178			=cut
179
180			sub show {
181			return if !$self \|\| --$hidden;
182
183			if (defined $saved_point) {
184			$self->rl_set_prompt ($prompt);
185			$self->{line_buffer} = $saved_line;
186			$self->{point} = $saved_point;
187			$self->redisplay;
188			}
189
190			$rw = AE::io $in, 0, sub {
191			$self->rl_callback_read_char;
192			};
193			}
194
195			=item $rl->print ($string, ...)
196
197			=item AnyEvent::ReadLine::Gnu->print ($string, ...)
198
199			Prints the given strings to the terminal, by first hiding the readline,
200			printing the message, and showing it again.
201
202			This function cna be called even when readline has never been initialised.
203
204			The last string should end with a newline.
205
206			=cut
207
208			sub print {
209			shift;
210
211			hide;
212			my $out = $out \|\| *STDOUT;
213			print $out @_;
214			show;
215			}
216
217			END {
218			return unless $self;
219
220			$self->hide;
221			$self->callback_handler_remove;
222			}
223
224			1;
225
226			=back
227
228			=head1 AUTHOR, CONTACT, SUPPORT
229
230			Marc Lehmann <schmorp@schmorp.de>
231			http://software.schmorp.de/pkg/AnyEvent-Readline-Gnu.html
232
233			=cut
234