fix(terminal): readansi now properly handles <alt>+key key-presses (#62)

Also; documents the internal buffer and retry behaviour of readansi

3 files changed, 78 insertions, 21 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 28e7272..2048c92 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,11 @@ The scope of what is covered by the version number excludes:
 
 ## Version history
 
+### version xxx, unreleased
+
+- Docs: document readansi internal buffer for incomplete sequences.
+- Fix: ensure to properly parse `<alt>+key` key presses
+
 ### version 0.6.0, released 10-Apr-2025
 
 - Fix: when sleep returns an error, pass that on in `readkey`.
diff --git a/spec/04-term_spec.lua b/spec/04-term_spec.lua
index b3de461..0ce0033 100644
--- a/spec/04-term_spec.lua
+++ b/spec/04-term_spec.lua
@@ -928,10 +928,31 @@ describe("Terminal:", function()
       end)
 
 
+      it("reads ANSI escape sequences, just an '<esc>O' (<alt><O> key press)", function()
+        setbuffer("\27O")
+        assert.are.same({"\27O", "ansi"}, {system.readansi(0)})
+      end)
+
+
+      it("reads <alt>+key key presses; <esc>+<key>", function()
+        setbuffer("\27a\27b\27c\27d")
+        assert.are.same({"\27a", "ansi"}, {system.readansi(0)})
+        assert.are.same({"\27b", "ansi"}, {system.readansi(0)})
+        assert.are.same({"\27c", "ansi"}, {system.readansi(0)})
+        assert.are.same({"\27d", "ansi"}, {system.readansi(0)})
+      end)
+
+
+      it("reads <ctrl><alt>[ key press; <esc>+<esc>", function()
+        setbuffer("\27\27\27\27")
+        assert.are.same({"\27\27", "ansi"}, {system.readansi(0)})
+        assert.are.same({"\27\27", "ansi"}, {system.readansi(0)})
+      end)
+
+
       it("returns a single <esc> character if no sequence is found", function()
-        setbuffer("\27\27[A")
+        setbuffer("\27")
         assert.are.same({"\27", "char"}, {system.readansi(0)})
-        assert.are.same({"\27[A", "ansi"}, {system.readansi(0)})
       end)
 
 
@@ -945,6 +966,22 @@ describe("Terminal:", function()
         assert.is.near(1, timing, 0.5)       -- this also works for MacOS in CI
       end)
 
+
+      it("incomplete ANSI sequences will be completed on next call", function()
+        setbuffer("\27[")
+        assert.are.same({nil, "timeout", "\27["}, {system.readansi(0)})
+        setbuffer("A")
+        assert.are.same({"\27[A", "ansi"}, {system.readansi(0)})
+      end)
+
+
+      it("incomplete UTF8 sequences will be completed on next call", function()
+        setbuffer(string.char(240, 159))
+        assert.are.same({nil, "timeout", string.char(240, 159)}, {system.readansi(0)})
+        setbuffer(string.char(154, 128))
+        assert.are.same({"🚀", "char"}, {system.readansi(0)})
+      end)
+
     end)
 
   end)
diff --git a/system/init.lua b/system/init.lua
index 28fe65c..e0e5f21 100644
--- a/system/init.lua
+++ b/system/init.lua
@@ -267,7 +267,6 @@ end
 
 
 do
-  local left_over_key
   local sequence -- table to store the sequence in progress
   local utf8_length -- length of utf8 sequence currently being processed
   local unpack = unpack or table.unpack
@@ -285,6 +284,8 @@ do
   -- @treturn[2] nil in case of an error
   -- @treturn[2] string error message; `"timeout"` if the timeout was reached.
   -- @treturn[2] string partial result in case of an error while reading a sequence, the sequence so far.
+  -- The function retains its own internal buffer, so on the next call the incomplete buffer is used to
+  -- complete the sequence.
   function system.readansi(timeout, fsleep)
     if type(timeout) ~= "number" then
       error("arg #1 to readansi, expected timeout in seconds, got " .. type(timeout), 2)
@@ -295,33 +296,47 @@ do
 
     if not sequence then
       -- no sequence in progress, read a key
-
-      if left_over_key then
-        -- we still have a cached key from the last call
-        key = left_over_key
-        left_over_key = nil
-      else
-        -- read a new key
-        local err
-        key, err = system.readkey(timeout, fsleep)
-        if key == nil then -- timeout or error
-          return nil, err
-        end
+      local err
+      key, err = system.readkey(timeout, fsleep)
+      if key == nil then -- timeout or error
+        return nil, err
       end
 
       if key == 27 then
         -- looks like an ansi escape sequence, immediately read next char
         -- as an heuristic against manually typing escape sequences
         local key2 = system.readkey(0, fsleep)
-        if key2 ~= 91 and key2 ~= 79 then -- we expect either "[" or "O" for an ANSI sequence
-          -- not the expected [ or O character, so we return the key as is
-          -- and store the extra key read for the next call
-          left_over_key = key2
+        if key2 == nil then
+          -- no key available, return the escape key, on its own
+          sequence = nil
           return string.char(key), "char"
+
+        elseif key2 == 91 then
+          -- "[" means it is for sure an ANSI sequence
+          sequence = { key, key2 }
+
+        elseif key2 == 79 then
+          -- "O" means it is either an ANSI sequence or just an <alt>+O key stroke
+          -- check if there is yet another byte available
+          local key3 = system.readkey(0, fsleep)
+          if key3 == nil then
+            -- no key available, return the <alt>O key stroke, report as ANSI
+            sequence = nil
+            return string.char(key, key2), "ansi"
+          end
+          -- it's an ANSI sequence, marked with <ESC>O
+          if (key3 >= 65 and key3 <= 90) or (key3 >= 97 and key3 <= 126) then
+            -- end of sequence, return the full sequence
+            return string.char(key, key2, key3), "ansi"
+          end
+          sequence = { key, key2, key3 }
+
+        else
+          -- not an ANSI sequence, but an <alt>+<key2> key stroke, so report as ANSI
+          sequence = nil
+          return string.char(key, key2), "ansi"
         end
 
-        -- escape sequence detected
-        sequence = { key, key2 }
       else
         -- check UTF8 length
         utf8_length = key < 128 and 1 or key < 224 and 2 or key < 240 and 3 or key < 248 and 4