Module terminal.input.keymap

Module to map received input to key-names.

Check the examples below for usage.

key-map: a key-map is a table that maps raw key-stroke input (from readansi) to key-names. The raw input can be a control-character (bytes 0-31 + 127), or an ANSI escape sequence.

note: a raw-key only maps to 1 name, even if the sequence is known under multiple names. For example, the raw key "\013" (carriage return) maps to the name "ctrl_m". Though on Windows it is also know as keyname "enter" or "return", it will not map to these names.

That's why there is keys: a map of aliases for key-names to official key-names. This allows to use user-friendly names for keys. For example, the key-name "ctrl_m" can be aliased to "enter" or "return", so that you can use these names in your code, instead of the raw key-name. For unknown keys, an error will be thrown, so you can catch typos in your code early.

So in key-map; raw-key "\013" maps to "ctrl_m"

In keys; the keys "ctrl_m", "enter", and "return", all map to the same key-name; "ctrl_m".

Check the source code for default keys and aliases. Custom maps can be created with get_keymap and get_keys.

Usage:

    local rawkey = "\013" -- carriage return
local keymap = terminal.input.keymap.default_key_map
local keys = terminal.input.keymap.default_keys

local keyname = key_map[rawkey] --> "ctrl_m"

-- the following if statements are equivalent:
if keyname == "ctrl_m" then     -- uses magic strings, typos are lurking bugs!
if keyname == keys.ctrl_m then  -- uses the official name, prevents typos, hard to read
if keyname == keys.enter then   -- uses alias, easily readable, prevents typos
if keyname == keys.return then  -- uses alias, easily readable, prevents typos

-- This will throw an error when running due to the typo:
if keyname == keys.retunr then  -- typo, will throw an error

Functions

get_keymap ([overrides]) Returns a new key-map to map incoming raw key-strokes to a key-name.
get_keys ([keymap=default-key-map[, aliasses]]) Returns a constant lookup table with key-names.
is_printable (keystroke) Checks if a raw-key is printable.

Tables

control_characters Key-map of only control characters.
default_key_map The default list of key-mapping from raw-input to key names.
default_keys The default lookup table with key-names.


Functions

get_keymap ([overrides])
Returns a new key-map to map incoming raw key-strokes to a key-name. Generates a new key-map, containing the default_key_map, and the provided overrides.

Parameters:

  • overrides table a table with key-value pairs to override the default key map. The key should be the raw-key (character or sequence) as returned by readansi, the value should be the name of the key. (optional)

Returns:

    table new key_map

Usage:

    -- use overrides to re-map vim-oriented keys to arrow-keys
local keys = terminal.input.keymap.default_keys
local vi_keymap = terminal.input.keymap.get_keymap({
  ["j"] = keys.down,   -- use lookup table, not magic strings
  ["k"] = keys.up,     -- use lookup table, not magic strings
})

local keystroke, keytype = terminal.input.readansi(math.huge)
local keyname = vi_keymap[keystroke]

if keyname == nil then
  print("this key is unnamed: " .. keystroke:gsub("\027", "\\027"))
elseif keyname == keys.up then      -- matches "k" and arrow-up press
  print("Up key pressed")
elseif keyname == keys.down then    -- matches "j" and arrow-down press
  print("Down key pressed")
else
  ...
end
get_keys ([keymap=default-key-map[, aliasses]])
Returns a constant lookup table with key-names. It will contain everything from the keymap table, the default key-aliases, and the provided aliasses. Looking up an unknown name will throw an error. Use this instead of magic-strings when checking for specific keys.

Parameters:

  • keymap table , either default_key_map, or the result from get_keymap. (default default-key-map)
  • aliasses table a table with key-value pairs to override the default key map. The key is the alias, the value is the official name of the key. (optional)

Returns:

    table constant table where the aliases/keys map to the official key names.

Usage:

    local keys = terminal.input.keymap.default_keys
local rawkey = terminal.input.readansi(math.huge)
local keyname = terminal.input.keymap.default_key_map[key]

if     keyname == "up" then     -- will work
elseif keyname == "upx" then    -- will not work, but will silently be ignored
elseif keyname == keys.up then  -- will work
elseif keyname == keys.upx then -- will throw an error, due to typo
end
is_printable (keystroke)
Checks if a raw-key is printable. A printable key is a key that is not an ANSI escape sequence and not a control character (bytes 0-31 and 127).

Note: Tab, Cr, and Lf, which are control characters, are considered non-printable by this function.

Parameters:

  • keystroke string the raw key-stroke as returned by readansi.

Returns:

    boolean true if the key is printable, false otherwise.

Tables

control_characters
Key-map of only control characters. The control characters are single byte strings, with byte values 0-31 and 127. The map maps the raw control character to a key-name. The key-names are the names of the control characters, e.g. "ctrl_a" for byte 1, or "ctrl_[" for byte 27 (ESC).
default_key_map
The default list of key-mapping from raw-input to key names.
default_keys
The default lookup table with key-names.
generated by LDoc 1.5.0