view release on metacpan or  search on metacpan

Gnu.pm  view on Meta::CPAN

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

=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 = '1.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 callback will be installed with the C<CallbackHandlerInstall>, which
means it handles history expansion and history, among other things.

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.

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.

=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