beamtea_key (beamtea v0.1.2)

View Source

Decode a stream of raw terminal bytes into high-level key events.

The terminal delivers key presses as raw bytes: a single ASCII byte for ordinary keys, a multi-byte UTF-8 sequence for non-ASCII characters, and ANSI escape sequences (CSI / SS3) for the arrows, function and navigation keys. parse/1 turns a binary chunk into a list of key() events plus any trailing bytes that form an incomplete sequence — those must be prepended to the next chunk.

Key events are represented as:

  • a named atom for special keys: up, down, left, right, enter, esc, tab, back_tab, backspace, delete, insert, home, `end'', page_up, page_down
  • {ctrl, Letter} for Ctrl-combinations, e.g. Ctrl-C is {ctrl, $c}
  • {char, CodePoint} for a printable character (including space); the code point is a full Unicode code point, so UTF-8 text "just works"

Summary

Types

key/0

Functions

parse(Bin)

Parse a raw byte chunk into {Keys, Rest}. Rest is the tail of an incomplete escape sequence or UTF-8 code point and should be prepended to the next chunk before parsing.

to_binary(Cp)

Render a single {char, Cp} (or a bare code point) as a UTF-8 binary. Handy for building text buffers in an update/2.

Types

key/0

-type key() ::
          up | down | left | right | home | 'end' | page_up | page_down | insert | delete | enter |
          tab | back_tab | backspace | esc |
          {ctrl, char()} |
          {char, char()}.

Functions

parse(Bin)

-spec parse(binary()) -> {[key()], binary()}.

Parse a raw byte chunk into {Keys, Rest}. Rest is the tail of an incomplete escape sequence or UTF-8 code point and should be prepended to the next chunk before parsing.

to_binary(Cp)

-spec to_binary({char, char()} | char()) -> binary().

Render a single {char, Cp} (or a bare code point) as a UTF-8 binary. Handy for building text buffers in an update/2.