1 files changed, 75 insertions, 35 deletions

diff --git a/system/init.lua b/system/init.lua
index a81978e..9b71d4d 100644
--- a/system/init.lua
+++ b/system/init.lua
@@ -10,17 +10,21 @@ local system = require 'system.core'
 --- UTF8 codepage.
 -- To be used with `system.setconsoleoutputcp` and `system.setconsolecp`.
 -- @field CODEPAGE_UTF8 The Windows CodePage for UTF8.
+-- @within Terminal_UTF-8
 system.CODEPAGE_UTF8 = 65001
 
 do
-  local backup_mt = {}
+  local backup_indicator = {}
 
   --- Returns a backup of terminal settings for stdin/out/err.
   -- Handles terminal/console flags, Windows codepage, and non-block flags on the streams.
   -- Backs up terminal/console flags only if a stream is a tty.
   -- @return table with backup of terminal settings
+  -- @within Terminal_Backup
   function system.termbackup()
-    local backup = setmetatable({}, backup_mt)
+    local backup = {
+      __type = backup_indicator, -- cannot set a metatable, since autotermrestore uses it for GC
+    }
 
     if system.isatty(io.stdin) then
       backup.console_in = system.getconsoleflags(io.stdin)
@@ -50,8 +54,9 @@ do
   --- Restores terminal settings from a backup
   -- @tparam table backup the backup of terminal settings, see `termbackup`.
   -- @treturn boolean true
+  -- @within Terminal_Backup
   function system.termrestore(backup)
-    if getmetatable(backup) ~= backup_mt then
+    if type(backup) ~= "table" or backup.__type ~= backup_indicator then
       error("arg #1 to termrestore, expected backup table, got " .. type(backup), 2)
     end
 
@@ -106,6 +111,7 @@ do -- autotermrestore
   -- @treturn[1] boolean true
   -- @treturn[2] nil if the backup was already created
   -- @treturn[2] string error message
+  -- @within Terminal_Backup
   function system.autotermrestore()
     if global_backup then
       return nil, "global terminal backup was already set up"
@@ -134,6 +140,7 @@ do
   -- Calls `termbackup` before calling the function and `termrestore` after.
   -- @tparam function f function to wrap
   -- @treturn function wrapped function
+  -- @within Terminal_Backup
   function system.termwrap(f)
     if type(f) ~= "function" then
       error("arg #1 to wrap, expected function, got " .. type(f), 2)
@@ -153,6 +160,7 @@ end
 --- Debug function for console flags (Windows).
 -- Pretty prints the current flags set for the handle.
 -- @param fh file handle (`io.stdin`, `io.stdout`, `io.stderr`)
+-- @within Terminal_Windows
 -- @usage -- Print the flags for stdin/out/err
 -- system.listconsoleflags(io.stdin)
 -- system.listconsoleflags(io.stdout)
@@ -192,6 +200,7 @@ end
 --- Debug function for terminal flags (Posix).
 -- Pretty prints the current flags set for the handle.
 -- @param fh file handle (`io.stdin`, `io.stdout`, `io.stderr`)
+-- @within Terminal_Posix
 -- @usage -- Print the flags for stdin/out/err
 -- system.listconsoleflags(io.stdin)
 -- system.listconsoleflags(io.stdout)
@@ -230,32 +239,40 @@ end
 do
   --- Reads a single byte from the console, with a timeout.
   -- This function uses `fsleep` to wait until either a byte is available or the timeout is reached.
-  -- The sleep period is exponentially backing off, starting at 0.0125 seconds, with a maximum of 0.2 seconds.
+  -- The sleep period is exponentially backing off, starting at 0.0125 seconds, with a maximum of 0.1 seconds.
   -- It returns immediately if a byte is available or if `timeout` is less than or equal to `0`.
   --
   -- Using `system.readansi` is preferred over this function. Since this function can leave stray/invalid
   -- byte-sequences in the input buffer, while `system.readansi` reads full ANSI and UTF8 sequences.
   -- @tparam number timeout the timeout in seconds.
-  -- @tparam[opt=system.sleep] function fsleep the function to call for sleeping.
+  -- @tparam[opt=system.sleep] function fsleep the function to call for sleeping; `ok, err = fsleep(secs)`
   -- @treturn[1] byte the byte value that was read.
   -- @treturn[2] nil if no key was read
-  -- @treturn[2] string error message; `"timeout"` if the timeout was reached.
+  -- @treturn[2] string error message when the timeout was reached (`"timeout"`), or if `sleep` failed.
+  -- @within Terminal_Input
   function system.readkey(timeout, fsleep)
     if type(timeout) ~= "number" then
       error("arg #1 to readkey, expected timeout in seconds, got " .. type(timeout), 2)
     end
 
     local interval = 0.0125
-    local key = system._readkey()
+    local ok
+    local key, err = system._readkey()
     while key == nil and timeout > 0 do
-      (fsleep or system.sleep)(math.min(interval, timeout))
+      if err then
+        return nil, err
+      end
+      ok, err = (fsleep or system.sleep)(math.min(interval, timeout))
+      if not ok then
+        return nil, err
+      end
       timeout = timeout - interval
-      interval = math.min(0.2, interval * 2)
-      key = system._readkey()
+      interval = math.min(0.1, interval * 2)
+      key, err = system._readkey()
     end
 
-    if key then
-      return key
+    if key or err then
+      return key, err
     end
     return nil, "timeout"
   end
@@ -264,7 +281,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
@@ -278,10 +294,20 @@ do
   -- @tparam number timeout the timeout in seconds.
   -- @tparam[opt=system.sleep] function fsleep the function to call for sleeping.
   -- @treturn[1] string the character that was received (can be multi-byte), or a complete ANSI sequence
-  -- @treturn[1] string the type of input: `"char"` for a single key, `"ansi"` for an ANSI sequence
+  -- @treturn[1] string the type of input: `"ctrl"` for 0-31 and 127 bytes, `"char"` for other UTF-8 characters, `"ansi"` for an ANSI sequence
   -- @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.
+  -- @within Terminal_Input
+  -- @usage
+  -- local key, keytype = system.readansi(5)
+  -- if keytype == "char" then ... end -- printable character
+  -- if keytype ~= "char" then ... end -- non-printable character or sequence
+  -- if keytype == "ansi" then ... end -- a multi-byte sequence, but not a UTF8 character
+  -- if keytype ~= "ansi" then ... end -- a valid UTF8 character (which includes control characters)
+  -- if keytype == "ctrl" then ... end -- a single-byte ctrl character (0-31, 127)
   function system.readansi(timeout, fsleep)
     if type(timeout) ~= "number" then
       error("arg #1 to readansi, expected timeout in seconds, got " .. type(timeout), 2)
@@ -292,40 +318,54 @@ 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
-          return string.char(key), "char"
+        if key2 == nil then
+          -- no key available, return the escape key, on its own
+          sequence = nil
+          return string.char(key), "ctrl"
+
+        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
-        if utf8_length  == 1 then
+        if utf8_length == 1 then
           -- single byte character
           utf8_length = nil
-          return string.char(key), "char"
+          return string.char(key), ((key <= 31 or key == 127) and "ctrl" or "char")
         else
           -- UTF8 sequence detected
           sequence = { key }