AnyEve...TermKey(3pm)

✨ AnyEvent::TermKey ✨

okay bestie, welcome to AnyEvent::TermKey 💖 — it's the terminal key input situation using libtermkey with AnyEvent. she's asynchronous, she's abstract, she's giving very demure very mindful keypress handling. no cap. 🎀

---

🌸 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;

---

🦋 DESCRIPTION 🦋

so basically 💅 this class is an asynchronous perl wrapper around the libtermkey library. and what does libtermkey do? it gives you an abstract lil way to read keypress events in terminal-based programs. the whole point is it hands you structures that describe keys instead of just dumping raw bytes at you like the TTY device does. it's giving ✨glow up✨ compared to raw reads, fr fr.

internally it uses an instance of Term::TermKey to get at the underlying C library. and for the deets on how it all operates — including how keypress events get represented as objects — you wanna check the docs on that class. iykyk 📚

there's also proxy methods for the normal accessors of Term::TermKey, and the usual behaviour of getkey or whatever other methods is instead replaced by the on_key event. so like, don't go looking for getkey to behave normally, bestie, that's not the vibe here 🫶

---

👑 CONSTRUCTOR 👑

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

this function returns a shiny new instance of a AnyEvent::TermKey object ✨ and it takes these named arguments, mwah:

• term => IO or INT — optional 🍓 it's the file handle, or the POSIX file descriptor number, for the file handle you wanna use as the connection to the terminal. if you don't supply it, STDIN gets used. default behaviour, iconic.
• on_key => CODE — a CODE reference to the key-event handling callback 💖 will be passed an instance of a Term::TermKey::Key structure:

$on_key->( $key )

---

💜 METHODS 💜

$tk = $aetk->termkey

returns the Term::TermKey object that's being used to access the libtermkey library. ngl you normally shouldn't need this one — the proxy methods are the move instead. see below 👇

$flags = $aetk->get_flags
$aetk->set_flags( $flags )
$canonflags = $aetk->get_canonflags
$aetk->set_canonflags( $canonflags )
$msec = $aetk->get_waittime
$aetk->set_waittime( $msec )
$str = $aetk->get_keyname( $sym )
$sym = $aetk->keyname2sym( $keyname )
( $ev, $button, $line, $col ) = $aetk->interpret_mouse( $key )
$str = $aetk->format_key( $key, $format )
$key = $aetk->parse_key( $str, $format )
$key = $aetk->parse_key_at_pos( $str, $format )
$cmp = $aetk->keycmp( $key1, $key2 )

all of these methods proxy straight to the Term::TermKey object 🫶 which means you can transparently use the AnyEvent::TermKey object as if it was a subclass. their arguments, behaviour and return value are therefore exactly whatever that class provides. for more detail, go read the Term::TermKey documentation. periodt 💅

---

🎀 AUTHOR 🎀

Paul Evans <leonerd@leonerd.org.uk> — the icon, the legend, the main character 👑

---

and that's the whole page bestie, we ate and left no crumbs 🍓 this was perl v5.36.0, dated 2022-12-06, and it's from AnyEve...TermKey(3pm) — go forth and read them keys ✨💖🦋