NAME

Term::TermKey::Async - perl wrapper around libtermkey for IO::Async

SYNOPSIS

use Term::TermKey::Async qw( FORMAT_VIM KEYMOD_CTRL );
use IO::Async::Loop;

my $loop = IO::Async::Loop->new();

my $tka = Term::TermKey::Async->new(
   term => \*STDIN,

   on_key => sub {
      my ( $self, $key ) = @_;

      print "Got key: ".$self->format_key( $key, FORMAT_VIM )."\n";

      $loop->loop_stop if $key->type_is_unicode and
                          $key->utf8 eq "C" and
                          $key->modifiers & KEYMOD_CTRL;
   },
);

$loop->add( $tka );

$loop->loop_forever;

DESCRIPTION

This object class implements an asynchronous perl wrapper around the libtermkey library for handling terminal keypress events. This library attempts to provide an abstract way to read keypress events in terminal-based programs by providing structures that describe keys, rather than simply returning raw bytes as read from the TTY device.

This class is a subclass of IO::Async::Notifier, allowing it to be put in an IO::Async::Loop object and used alongside other objects in an IO::Async program.

This object internally uses an instance of 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.

For implementation reasons, this class is not actually a subclass of Term::TermKey. Instead, an object of that class is stored and accessed by this object, which is a subclass of IO::Async::Notifier. This distinction should not normally be noticable. Proxy methods exist for the normal accessors of Term::TermKey, and the usual behaviour of the getkey() or other methods is instead replaced by the on_key callback or method.

This object may be used in one of two ways; with a callback function, or as a base class.

Callbacks

This object may take a CODE reference to a callback function in its constructor:

$on_key->( $self, $key )

The $key parameter will contain an instance of Term::TermKey::Key representing the keypress event.

Base Class

Alternatively, a subclass of this class may be built which handles the following method:

$self->on_key( $key )

The $key parameter will contain an instance of Term::TermKey::Key representing the keypress event.

CONSTRUCTOR

$tka = Term::TermKey::Async->new( %args )

This function returns a new instance of a Term::TermKey::Async object. It takes the following named arguments:

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 STDIN will be used.

on_key => CODE

Callback to invoke when a key is pressed.

METHODS

$tk = $tka->termkey

Returns the Term::TermKey object being used to access the libtermkey library. Normally should not be required; the proxy methods should be used instead. See below.

$flags = $tka->get_flags

$tka->set_flags( $flags )

$msec = $tka->get_waittime

$tka->set_waittime( $msec )

$str = $tka->get_keyname( $sym )

$str = $tka->format_key( $key, $format )

These methods all proxy to the Term::TermKey object, and allow transparent use of the Term::TermKey::Async object as if it was a subclass. Their arguments, behaviour and return value are therefore those provided by that class. For more detail, see the Term::TermKey documentation.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Term::TermKey::Async

perl -MCPAN -e shell
install Term::TermKey::Async