view release on metacpan or  search on metacpan

lib/AnyEvent/TermKey.pm  view on Meta::CPAN

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2011 -- leonerd@leonerd.org.uk

package AnyEvent::TermKey;

use strict;
use warnings;

our $VERSION = '0.02';

use Carp;

use AnyEvent;
use Term::TermKey qw( RES_KEY RES_AGAIN );

=head1 NAME

C<AnyEvent::TermKey> - terminal key input using C<libtermkey> with C<AnyEvent>

=head1 SYNOPSIS

 use AnyEvent::TermKey qw( FORMAT_VIM KEYMOD_CTRL );
 use AnyEvent;
 
 my $cv = AnyEvent->condvar;
 
 my $aetk = AnyEvent::TermKey->new(
    term => \*STDIN,
 
    on_key => sub {
       my ( $key ) = @_;
 
       print "Got key: ".$key->termkey->format_key( $key, FORMAT_VIM )."\n";
 
       $cv->send if $key->type_is_unicode and
                    $key->utf8 eq "C" and
                    $key->modifiers & KEYMOD_CTRL;
    },
 );
 
 $cv->recv;

=head1 DESCRIPTION

This class implements an asynchronous perl wrapper around the C<libtermkey>
library, which provides an abstract way to read keypress events in
terminal-based programs. It yields structures that describe keys, rather than
simply returning raw bytes as read from the TTY device.

It internally uses an instance of L<Term::TermKey> to access the underlying C
library. For details on general operation, including the representation of
keypress events as objects, see the documentation on that class.

Proxy methods exist for normal accessors of C<Term::TermKey>, and the usual
behaviour of the C<getkey> or other methods is instead replaced by the
C<on_key> event.

=cut

# Forward any requests for symbol imports on to Term::TermKey
sub import
{
   shift; unshift @_, "Term::TermKey";
   my $import = $_[0]->can( "import" );
   goto &$import; # So as not to have to fiddle with Sub::UpLevel
}

=head1 CONSTRUCTOR

=cut

=head2 $aetk = AnyEvent::TermKey->new( %args )

This function returns a new instance of a C<AnyEvent::TermKey> object. It
takes the following named arguments:

=over 8

=item term => IO or INT

Optional. File handle or POSIX file descriptor number for the file handle to
use as the connection to the terminal. If not supplied C<STDIN> will be used.

=item on_key => CODE

CODE reference to the key-event handling callback. Will be passed an instance
of a C<Term::TermKey::Key> structure:

 $on_key->( $key )

=back

=cut

sub new