Provided by: libterm-termkey-perl_0.17-2build4_amd64 bug

NAME

       "Term::TermKey" - perl wrapper around "libtermkey"

SYNOPSIS

        use Term::TermKey;

        my $tk = Term::TermKey->new( \*STDIN );

        print "Press any key\n";

        $tk->waitkey( my $key );

        print "You pressed: " . $tk->format_key( $key, 0 );

DESCRIPTION

           Note that "libtermkey" itself is deprecated in favour of its eventual merge into "libtickit". As a
           result, uses of this module should also be considered deprecated. Consider rewriting code to use
           Tickit instead; either by creating a Tickit::Term to receive key input events, or perform a more
           wholescale rewrite into using "Tickit" generally for all screen interaction purposes.

       This module provides a light perl wrapper around the "libtermkey" library.  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 version of "Term::TermKey" requires "libtermkey" version at least 0.16.

   Multi-byte keys, ambiguous keys, and waittime
       Some keypresses generate multiple bytes from the terminal. There is also the ambiguity between multi-byte
       CSI or SS3 sequences, and the Escape key itself.  The waittime timer is used to distinguish them.

       When some bytes arrive that could be the start of possibly multiple different keypress events, the
       library will attempt to wait for more bytes to arrive that would finish it. If no more bytes arrive after
       this time, then the bytes will be reported as events as they stand, even if this results in interpreting
       a partially-complete Escape sequence as a literal Escape key followed by some normal letters or other
       symbols.

       Similarly, if the start of an incomplete UTF-8 sequence arrives when the library is in UTF-8 mode, this
       will be reported as the UTF-8 replacement character (U+FFFD) if it is incomplete after this time.

CONSTRUCTOR

   new
          $tk = Term::TermKey->new( $fh, $flags )

       Construct a new "Term::TermKey" object that wraps the given term handle.  $fh should be either an IO
       handle reference, an integer referring to a plain POSIX file descriptor, of "undef". $flags is optional,
       but if given should contain the flags to pass to "libtermkey"'s constructor. Assumes a default of 0 if
       not supplied. See the "FLAG_*" constants.

   new_abstract
          $tk = Term::TermKey->new_abstract( $termtype, $flags )

       Construct a new abstract "Term::TermKey" object not associated with a filehandle. Input may be fed to it
       using the push_bytes() method rather than waitkey() or advisereadable(). The name of the termtype should
       be given in the $termtype string.

METHODS

   start
   stop
          $success = $tk->start

          $success = $tk->stop

       Start or stop IO interactions from the instance. Starting will send the terminal initialisation sequence
       and set up termios(5) settings, stopping will send the terminal shutdown sequence and restore termios(5)
       back to the initial values. After construction, a "Term::TermKey" instance is already started, but these
       methods may be used to suspend and resume, for example, on receipt of a "SIGTSTP" signal requesting that
       the application background itself.

       Returns false if it fails; $! will contain an error code.

   is_started
          $started = $tk->is_started

       Returns true if the instance has been started, or false if it is stopped.

   get_flags
   set_flags
          $flags = $tk->get_flags

          $tk->set_flags( $newflags )

       Accessor and mutator for the flags. One of the "FLAG_UTF8" or "FLAG_RAW" flags will be set, even if
       neither was present in the constructor, as in this case the library will attempt to detect if the current
       locale is UTF-8 aware or not.

   get_canonflags
   set_canonflags
          $canonflags = $tk->get_canonflags

          $tk->set_canonflags( $newcanonflags )

       Accessor and mutator for the canonicalisation flags.

   get_waittime
   set_waittime
          $msec = $tk->get_waittime

          $tk->set_waittime( $msec )

       Accessor and mutator for the maximum wait time in miliseconds. The underlying "libtermkey" library will
       have specified a default value when the object was constructed.

   get_buffer_remaining
          $bytes = $tk->get_buffer_remaining

       Accessor returning the number of bytes of buffer space remaining in the buffer; the space in which
       "push_bytes" can write.

   get_buffer_size
   set_buffer_size
          $bytes = $tk->get_buffer_size

          $tk->set_buffer_size( $size )

       Accessor and mutator to for the total buffer size to store pending bytes. If the underlying
       termkey_set_buffer_size(3) call fails, the "set_buffer_size" method will throw an exception.

   getkey
          $res = $tk->getkey( $key )

       Attempt to retrieve a single keypress event from the buffer, and put it in $key. If successful, will
       return "RES_KEY" to indicate that the $key structure now contains a new keypress event. If $key is an
       undefined lvalue (such as a new scalar variable) it will be initialised to contain a new key structure.

       If nothing is in the buffer it will return "RES_NONE". If the buffer contains a partial keypress event
       which does not yet contain all the bytes required, it will return "RES_AGAIN" (see above section about
       multibyte events). If no events are ready and the input stream is now closed, will return "RES_EOF".

       This method will not block, nor will it perform any IO on the underlying file descriptor. For a normal
       blocking read, see waitkey().

   getkey_force
          $res = $tk->getkey_force( $key )

       Similar to getkey(), but will not return "RES_AGAIN" if a partial match was found. Instead, it will force
       an interpretation of the bytes, even if this means interpreting the start of an "<Esc>"-prefixed
       multibyte sequence as a literal "Escape" key followed by normal letters. If $key is an undefined lvalue
       (such as a new scalar variable) it will be initialised to contain a new key structure.

       This method will not block, nor will it perform any IO on the underlying file descriptor. For a normal
       blocking read, see waitkey().

   waitkey
          $res = $tk->waitkey( $key )

       Attempt to retrieve a single keypress event from the buffer, or block until one is available. If
       successful, will return "RES_KEY" to indicate that the $key structure now contains a new keypress event.
       If an IO error occurs it will return "RES_ERROR", and if the input stream is now closed it will return
       "RES_EOF".

       If $key is an undefined lvalue (such as a new scalar variable) it will be initialised to contain a new
       key structure.

   advisereadable
          $res = $tk->advisereadable

       Inform the underlying library that new input may be available on the underlying file descriptor and so it
       should call read() to obtain it.  Will return "RES_AGAIN" if it read at least one more byte, "RES_NONE"
       if no more input was found, or "RES_ERROR" if an IO error occurs.

       Normally this method would only be used in programs that want to use "Term::TermKey" asynchronously; see
       the EXAMPLES section. This method gracefully handles an "EAGAIN" error from the underlying read()
       syscall.

   push_bytes
          $len = $tk->push_bytes( $bytes )

       Feed more bytes into the input buffer. This is primarily useful for feeding input into filehandle-less
       instances, constructed by passing "undef" or -1 as the filehandle to the constructor. After calling this
       method, these bytes will be available to read as keypresses by the "getkey" method.

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

       Returns the name of a key sym, such as returned by "Term::TermKey::Key->sym()".

   keyname2sym
          $sym = $tk->keyname2sym( $keyname )

       Look up the sym for a named key. The result of this method call can be compared directly against the
       value returned by "Term::TermKey::Key->sym()". Because this method has to perform a linear search of key
       names, it is best called rarely, perhaps during program initialisation, and the result stored for easier
       comparisons during runtime.

   interpret_unknown_csi
          ( $cmd, @args ) = $tk->interpret_unknown_csi( $key )

       If $key contains an unknown CSI event then its command and arguments are returned in a list. $cmd will be
       a string of 1 to 3 characters long, containing the initial and intermediate characters if present,
       followed by the main command character. @args will contain the numerical arguments, where missing
       arguments are replaced by -1. If $key does not contain an unknown CSI event then an empty list is
       returned.

       Note that this method needs to be called immediately after "getkey" or "waitkey", or at least, before
       calling either of those methods again. The actual CSI sequence is retained in the libtermkey buffer, and
       only retrieved by this method call. Calling "getkey" or "waitkey" again may overwrite that buffer.

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

       Return a string representation of the keypress event in $key, following the flags given. See the
       descriptions of the flags, below, for more detail.

       This may be useful for matching keypress events against keybindings stored in a hash. See EXAMPLES
       section for more detail.

   parse_key
          $key = $tk->parse_key( $str, $format )

       Return a keypress event by parsing the string representation in $str, following the flags given. This
       method is an inverse of "format_key".

       This may be useful for parsing entries from a configuration file or similar.

   parse_key_at_pos
          $key = $tk->parse_key_at_pos( $str, $format )

       Return a keypress event by parsing the string representation in a region of $str, following the flags
       given.

       Where "parse_key" will start at the beginning of the string and requires the entire input to be consumed,
       this method will start at the current pos() position in $str (or at the beginning of the string if none
       is yet set), and after a successful parse, will update it to the end of the matched section. This
       position does not have to be at the end of the string. $str must therefore be a real scalar variable, and
       not a string literal.

       This may be useful for incremental parsing of configuration or other data, out of a larger string.

   keycmp
          $cmp = $tk->keycmp( $key1, $key2 )

       Compares the two given keypress events, returning a number less than, equal to, or greater than zero,
       depending on the ordering. Keys are ordered first by type (unicode, keysym, function, mouse), then by
       value within that type, then finally by modifier bits.

       This may be useful in "sort" expressions:

        my @sorted_keys = sort { $tk->keycmp( $a, $b ) } @keys;

KEY OBJECTS

       The "Term::TermKey::Key" subclass is used to store a single keypress event.  Objects in this class cannot
       be changed by perl code. getkey(), getkey_force() or waitkey() will overwrite the contents of the
       structure with a new value.

       Keys cannot be constructed, but getkey(), getkey_force() or waitkey() will place a new key structure in
       the $key variable if it is undefined when they are called. parse_key() and parse_key_at_pos() will return
       new keys.

   type
          $key->type

       The type of event. One of "TYPE_UNICODE", "TYPE_FUNCTION", "TYPE_KEYSYM", "TYPE_MOUSE", "TYPE_POSITION",
       "TYPE_MODEREPORT", "TYPE_UNKNOWN_CSI".

   type_is_...
          $key->type_is_unicode

          $key->type_is_function

          $key->type_is_keysym

          $key->type_is_mouse

          $key->type_is_position

          $key->type_is_modereport

          $key->type_is_unknown_csi

       Shortcuts which return a boolean.

   codepoint
          $key->codepoint

       The Unicode codepoint number for "TYPE_UNICODE", or 0 otherwise.

   number
          $key->number

       The function key number for "TYPE_FUNCTION", or 0 otherwise.

   sym
          $key->sym

       The key symbol number for "TYPE_KEYSYM", or 0 otherwise. This can be passed to
       "Term::TermKey->get_keyname()", or compared to a result earlier obtained from
       "Term::TermKey->keyname2sym()".

   modifiers
          $key->modifiers

       The modifier bitmask. Can be compared against the "KEYMOD_*" constants.

   modifier_...
          $key->modifier_shift

          $key->modifier_alt

          $key->modifier_ctrl

       Shortcuts which return a boolean if the appropriate modifier is present.

   utf8
          $key->utf8

       A string representation of the given Unicode codepoint. If the underlying "termkey" library is in UTF-8
       mode then this will be a UTF-8 string. If it is in raw mode, then this will be a single raw byte.

   mouseev
   button
          $key->mouseev

          $key->button

       The details of a mouse event for "TYPE_MOUSE", or "undef" for other types of event.

   line
   col
          $key->line

          $key->col

       The details of a mouse or position event, or "undef" for other types of event.

   termkey
          $key->termkey

       Return the underlying "Term::TermKey" object this key was retrieved from.

   format
          $str = $key->format( $format )

       Returns a string representation of the keypress event, identically to calling "format_key" on the
       underlying "Term::TermKey" object.

EXPORTED CONSTANTS

       The following constant names are all derived from the underlying "libtermkey" library. For more detail
       see the documentation on the library.

       These constants are possible values of "$key->type"

       "TYPE_UNICODE"
           a Unicode codepoint

       "TYPE_FUNCTION"
           a numbered function key

       "TYPE_KEYSYM"
           a symbolic key

       "TYPE_MOUSE"
           a mouse movement or button press or release

       "TYPE_POSITION"
           a cursor position report

       "TYPE_MODEREPORT"
           an ANSI or DEC mode report

       "TYPE_UNKNOWN_CSI"
           an unrecognised CSI sequence

       These constants are result values from getkey(), getkey_force(), waitkey() or advisereadable()

       "RES_NONE"
           No key event is ready.

       "RES_KEY"
           A key event has been provided.

       "RES_EOF"
           No key events are ready and the terminal has been closed, so no more will arrive.

       "RES_AGAIN"
           No key event is ready yet, but a partial one has been found. This is only returned by getkey(). To
           obtain the partial result even if it never completes, call getkey_force().

       "RES_ERROR"
           Returned by "waitkey" or "advisereadable" if an IO error occurs while trying to read another key
           event.

       These constants are key modifier masks for "$key->modifiers"

       "KEYMOD_SHIFT"
       "KEYMOD_ALT"
       "KEYMOD_CTRL"
           Should be obvious ;)

       These constants are types of mouse event which may be returned by "$key->mouseev" or "interpret_mouse":

       "MOUSE_UNKNOWN"
           The type of mouse event was not recognised

       "MOUSE_PRESS"
           The event reports a mouse button being pressed

       "MOUSE_DRAG"
           The event reports the mouse being moved while a button is held down

       "MOUSE_RELEASE"
           The event reports the mouse buttons being released, or the mouse moved without a button held.

       These constants are flags for the constructor, "Term::TermKey->new"

       "FLAG_NOINTERPRET"
           Do not attempt to interpret C0 codes into keysyms (ie. "Backspace", "Tab", "Enter", "Escape").
           Instead report them as plain "Ctrl-letter" events.

       "FLAG_CONVERTKP"
           Convert xterm's alternate keypad symbols into the plain ASCII codes they would represent.

       "FLAG_RAW"
           Ignore locale settings; do not attempt to recombine UTF-8 sequences. Instead report only raw values.

       "FLAG_UTF8"
           Ignore locale settings; force UTF-8 recombining on.

       "FLAG_NOTERMIOS"
           Even if the terminal file descriptor represents a TTY device, do not call the tcsetattr() "termios"
           function on it to set in canonical input mode.

       "FLAG_SPACESYMBOL"
           Sets the "CANON_SPACESYMBOL" canonicalisation flag. See below.

       "FLAG_CTRLC"
           Disable the "SIGINT" behaviour of the "Ctrl-C" key, allowing it to be read as a modified Unicode
           keypress.

       "FLAG_EINTR"
           Disable retry on signal interrupt; instead report it as an error with "RES_ERROR" and $! set to
           "EINTR". Without this flag, IO operations will be retried if interrupted.

       These constants are canonicalisation flags for "set_canonflags" and "get_canonflags"

       "CANON_SPACESYMBOL"
           With this flag set, the Space key will appear as a "TYPE_KEYSYM" key event whose symname is "Space".
           Without this flag, it appears as a normal "TYPE_UNICODE" character.

       "CANON_DELBS"
           With this flag set, the ASCII "DEL" byte is interpreted as the "Backspace" keysym, rather than "DEL".
           This flag does not affect the interpretation of ASCII "BS", which is always represented as
           "Backspace".

       These constants are flags to "format_key"

       "FORMAT_LONGMOD"
           Print full modifier names e.g. "Shift-" instead of abbreviating to "S-".

       "FORMAT_CARETCTRL"
           If the only modifier is "Ctrl" on a plain character, render it as "^X".

       "FORMAT_ALTISMETA"
           Use the name "Meta" or the letter "M" instead of "Alt" or "A".

       "FORMAT_WRAPBRACKET"
           If the key event is a special key instead of unmodified Unicode, wrap it in "<brackets>".

       "FORMAT_MOUSE_POS"
           If the event is a mouse event, also include the cursor position; rendered as "@ ($col,$line)"

       "FORMAT_VIM"
           Shortcut to "FORMAT_ALTISMETA|FORMAT_WRAPBRACKET"; which gives an output close to the format the vim
           editor uses.

EXAMPLES

   A simple print-until-"Ctrl-C" loop
       This program just prints every keypress until the user presses "Ctrl-C".

        use Term::TermKey qw( FLAG_UTF8 RES_EOF FORMAT_VIM );

        my $tk = Term::TermKey->new(\*STDIN);

        # ensure perl and libtermkey agree on Unicode handling
        binmode( STDOUT, ":encoding(UTF-8)" ) if $tk->get_flags & FLAG_UTF8;

        while( ( my $ret = $tk->waitkey( my $key ) ) != RES_EOF ) {
           print "Got key: ".$tk->format_key( $key, FORMAT_VIM )."\n";
        }

   Configuration of custom keypresses
       Because format_key() yields a plain string representation of a keypress it can be used as a hash key to
       look up a "handler" routine for the key.

       The following implements a simple line input program, though obviously lacking many features in a true
       line editor like readline.

        use Term::TermKey qw( FLAG_UTF8 RES_EOF FORMAT_LONGMOD );

        my $tk = Term::TermKey->new(\*STDIN);

        # ensure perl and libtermkey agree on Unicode handling
        binmode( STDOUT, ":encoding(UTF-8)" ) if $tk->get_flags & FLAG_UTF8;

        my $line = "";

        $| = 1;

        my %key_handlers = (
           "Enter"  => sub {
              print "\nThe line is: $line\n";
              $line = "";
           },

           "Backspace" => sub {
              return unless length $line;
              substr( $line, -1, 1 ) = "";
              print "\cH \cH"; # erase it
           },

           # other handlers ...
        );

        while( ( my $ret = $tk->waitkey( my $key ) ) != RES_EOF ) {
           my $handler = $key_handlers{ $tk->format_key( $key, FORMAT_LONGMOD ) };
           if( $handler ) {
              $handler->( $key );
           }
           elsif( $key->type_is_unicode and !$key->modifiers ) {
              my $char = $key->utf8;

              $line .= $char;
              print $char;
           }
        }

   Asynchronous operation
       Because the getkey() method performs no IO itself, it can be combined with the advisereadable() method in
       an asynchronous program.

        use IO::Select;
        use Term::TermKey qw(
           FLAG_UTF8 RES_KEY RES_AGAIN RES_EOF FORMAT_VIM
        );

        my $select = IO::Select->new();

        my $tk = Term::TermKey->new(\*STDIN);
        $select->add(\*STDIN);

        # ensure perl and libtermkey agree on Unicode handling
        binmode( STDOUT, ":encoding(UTF-8)" ) if $tk->get_flags & FLAG_UTF8;

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

           print "You pressed " . $tk->format_key( $key, FORMAT_VIM ) . "\n";
        }

        my $again = 0;

        while(1) {
           my $timeout = $again ? $tk->get_waittime/1000 : undef;
           my @ready = $select->can_read($timeout);

           if( !@ready ) {
              my $ret;
              while( ( $ret = $tk->getkey_force( my $key ) ) == RES_KEY ) {
                 on_key( $tk, $key );
              }
           }

           while( my $fh = shift @ready ) {
              if( $fh == \*STDIN ) {
                 $tk->advisereadable;
                 my $ret;
                 while( ( $ret = $tk->getkey( my $key ) ) == RES_KEY ) {
                    on_key( $tk, $key );
                 }

                 $again = ( $ret == RES_AGAIN );
                 exit if $ret == RES_EOF;
              }
              # Deal with other filehandles here
           }
        }

       There may also be more appropriate modules on CPAN for particular event frameworks; see the "SEE ALSO"
       section below.

SEE ALSO

       •   <http://www.leonerd.org.uk/code/libtermkey/> - "libtermkey" home page

       •   Term::TermKey::Async - terminal key input using "libtermkey" with IO::Async

       •   POE::Wheel::TermKey - terminal key input using "libtermkey" with POE

       •   AnyEvent::TermKey - terminal key input using "libtermkey" with AnyEvent

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>