libtermkey

This library allows easy processing of keyboard entry from terminal-based programs. It handles all the necessary logic to recognise special keys, UTF-8 combining, and so on, with a simple interface.

DEPRECATED

Note: Use of this library for new programs is discouraged. It is being maintained for legacy purposes only. For writing new programs, please use libtickit instead.

All of the code in this library will be migrated into libtickit in due course; currently it is used via an internal dependency.

It provides the following features:

Follows terminfo for every sequence listed there, only falling back on other methods to deal with unrecognised input.
Recognises special keys (such as arrow and function keys), including "modified" keys like Ctrl-Left.
Recognises XTerm-style mouse position/button reporting.
MIT licenced to allow almost all projects to use it; both Open Source and Commercial.
Implemented in a small handfull of .c files which allows direct embedding in a larger application, if a shared library is not desired.
Small API - just three functions are needed in simple common cases.
Both synchronous (blocking) and asynchronous (non-blocking) APIs are supported.
Fully conformant with my suggested terminal key representation scheme

Comparision with Terminfo

This library uses the terminfo database for the terminal type given by $TERM as a first attempt to convert raw incoming bytes into symbolic keypress events. If this translation fails, and the terminal type is known to be one that uses xterm's generic CSI scheme for representing modified keypresses (e.g. xterm), then the sequence is interpreted according to xterm's rules. Finally, if all of these fail, the raw bytes will be presented as they are.

Special handling for screen is made, because of the way screen will translate some keypresses that it recognises, but passes on everything else verbatim. The xterm rules will also apply in this case, to cope with the case where screen is being driven by an xterm-like terminal, ensuring all the modified keypresses can still be interpreted.

Source

Download source in tarball from:

libtermkey-0.22.tar.gz - changes: bugfixes for unit tests on BSD platforms
libtermkey-0.21.1.tar.gz - changes: internal bugfixes, valgrind neatness
libtermkey-0.20.tar.gz - changes: added parsing of DCS and OSC control strings
libtermkey-0.19.tar.gz - changes: fixed handling of Ctrl-Space, bugfix for keypad mode switching, endian fix for unicode keys (thanks jamessan)
libtermkey-0.18.tar.gz - changes: look for .utf8 in locale variables, C++-compatible header, don't treat Ctrl-H as Backspace, disable IEXTEN where applicable
libtermkey-0.17.tar.gz - changes: added TERMKEY_FORMAT_SPACEMOD, TERMKEY_FORMAT_LOWERMOD, TERMKEY_FORMAT_LOWERSPACE and TERMKEY_FORMAT_URWID shortcut; better detection of UTF-8 locales; abstract C compiler from Makefile by using $(CC).
libtermkey-0.16.tar.gz - changes: recognise ANSI and DEC mode reports, extract and yield real key events for unrecognised CSI sequences; added termkey_interpret_{modereport,csi}; bugfix handling of CPR vs F3.
libtermkey-0.15b.tar.gz - changes: recognise SGR and rxvt mouse encodings, recognise cursor position report - (0.15a includes position report bugfix; 0.15b includes 'make install' portability fix)
libtermkey-0.14.tar.gz - changes: added termkey_{start,stop}, termkey_is_started, ship unit tests in distribution tarball for downstream to use
libtermkey-0.13.tar.gz - changes: added termkey_new_abstract, termkey_{get,set}_buffer_size, use errno rather than fprintf() to stderr, optionally use libncursesw if unibilium fails
libtermkey-0.12.tar.gz - changes: added termkey_push_bytes, support filehandle-less (abstract) instances, many manpage improvements
libtermkey-0.11.tar.gz - changes: optionally use unibilium instead of curses
libtermkey-0.10.tar.gz - changes: added termkey_canonicalise, canonicalisation flags, fixed some compile bugs on Solaris/OS X
libtermkey-0.9.tar.gz - changes: added FLAG_EINTR and RES_ERROR for better control of signal handling
libtermkey-0.8.tar.gz - bugfixes: handle Ctrl-Space on non-Linux, gracefully ignore EINTR, handle CSI u encodings
libtermkey-0.7.tar.gz - changes: added termkey_strpkey and termkey_keycmp, renamed termkey_snprint_key to termkey_strfkey
libtermkey-0.6.tar.gz - changes: control over SIGINT behaviour, Space as Unicode
libtermkey-0.5.tar.gz - changes: improved libtool integration; better mouse API
libtermkey-0.4.tar.gz - changes: use libtool for building; preliminary mouse support
libtermkey-0.3.tar.gz
libtermkey-0.2.tar.gz
libtermkey-0.1.tar.gz

The primary revision control repository is a Bazaar branch at http://bazaar.leonerd.org.uk/c/libtermkey/.

For an overview of the API, see here.

Online versions of the manpages are available in HTML form.

Language Bindings

This is a C library, but the following bindings exist for other languages.

Perl: Term::TermKey
Python: ctypes_libtermkey