From b6fdee98ed2e356d79a4646e09229b659183cb36 Mon Sep 17 00:00:00 2001
From: Thijs Schreijer <thijs@thijsschreijer.nl>
Date: Tue, 10 Feb 2026 11:51:00 +0100
Subject: [PATCH] docs(input): add example to readansi showing keymappings

---
 examples/keymap.lua           |  4 ++--
 src/terminal/input/init.lua   | 34 ++++++++++++++++++++++++++++++++++
 src/terminal/input/keymap.lua |  2 +-
 3 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/examples/keymap.lua b/examples/keymap.lua
index 88e39c02..26ed1aaf 100644
--- a/examples/keymap.lua
+++ b/examples/keymap.lua
@@ -53,8 +53,8 @@ local function main()
       print(to_hex_debug_format(key))
 
       local keyname = keymap[key]
-      print(yellow("\tit has the internal name: '") .. tostring(keyname) .. yellow("'"))
-      print(yellow("\tit maps to the names:"))
+      print(yellow("\tkey name: '") .. tostring(keyname) .. yellow("'"))
+      print(yellow("\taliases:"))
       for k, v in pairs(keys) do
         if v == keyname then
           print("\t\t" .. k)
diff --git a/src/terminal/input/init.lua b/src/terminal/input/init.lua
index ff1aca2b..4b01158d 100644
--- a/src/terminal/input/init.lua
+++ b/src/terminal/input/init.lua
@@ -50,6 +50,40 @@ M.sys_readansi = sys.readansi
 -- @tparam number timeout the timeout in seconds
 -- @tparam[opt] function fsleep the sleep function to use (default: the sleep function
 -- set by `initialize`)
+-- @see terminal.input.keymap
+-- @usage
+-- local t = require "terminal"
+-- local key_names = t.input.keymap.default_key_map
+-- local keys = t.input.keymap.default_keys
+--
+-- -- read a key, and look up its name
+-- local rawkey, keytype = t.input.readansi(math.huge)
+-- local keyname = key_names[rawkey] -- note: not every key has a name
+--
+-- -- use the 'keys' table to check for key-names to prevent
+-- -- having to use magic strings
+-- if keyname == keys.escape then
+--   t.output.print("Escape key pressed")
+-- elseif keyname == keys.up then
+--   t.output.print("Up key pressed")
+-- elseif keyname == keys.down then
+--   t.output.print("Down key pressed")
+-- elseif keyname == keys.left then
+--   t.output.print("Left key pressed")
+-- elseif keyname == keys.right then
+--   t.output.print("Right key pressed")
+-- else
+--   -- check on key-type; ctrl/ansi/char
+--   if keytype == "ctrl" then
+--     t.output.print("Control key pressed: " .. tostring(keyname))
+--   elseif keytype == "ansi" then
+--     t.output.print("ANSI key pressed: " .. tostring(keyname))
+--   elseif keytype == "char" then
+--     t.output.print("Character key pressed: " .. tostring(rawkey))  -- use rawkey here, not keyname
+--   else
+--     error("this cannot happen! keytype: " .. tostring(keytype))
+--   end
+-- end
 function M.readansi(timeout, fsleep)
   if kbend == 0 then
     -- buffer is empty, so read from the terminal
diff --git a/src/terminal/input/keymap.lua b/src/terminal/input/keymap.lua
index 9cbe4486..1d537dd9 100644
--- a/src/terminal/input/keymap.lua
+++ b/src/terminal/input/keymap.lua
@@ -31,7 +31,7 @@
 --     local key_map = terminal.input.keymap.default_key_map
 --     local keys = terminal.input.keymap.default_keys
 --
---     -- lookup the key-name from the raw inpout
+--     -- lookup the key-name from the raw input
 --     local keyname = key_map[rawkey] --> "ctrl_m"
 --
 --     -- the following if statements are equivalent: