diff options
Diffstat (limited to 'system/init.lua')
| -rw-r--r-- | system/init.lua | 378 |
1 files changed, 378 insertions, 0 deletions
diff --git a/system/init.lua b/system/init.lua index 77e0c3b..e99d0d4 100644 --- a/system/init.lua +++ b/system/init.lua @@ -1,2 +1,380 @@ +--- Lua System Library. +-- @module system + +--- Terminal +-- @section terminal + local system = require 'system.core' + + +--- UTF8 codepage. +-- To be used with `system.setconsoleoutputcp` and `system.setconsolecp`. +-- @field CODEPAGE_UTF8 The Windows CodePage for UTF8. +system.CODEPAGE_UTF8 = 65001 + +do + local backup_mt = {} + + --- 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 + function system.termbackup() + local backup = setmetatable({}, backup_mt) + + if system.isatty(io.stdin) then + backup.console_in = system.getconsoleflags(io.stdin) + backup.term_in = system.tcgetattr(io.stdin) + end + if system.isatty(io.stdout) then + backup.console_out = system.getconsoleflags(io.stdout) + backup.term_out = system.tcgetattr(io.stdout) + end + if system.isatty(io.stderr) then + backup.console_err = system.getconsoleflags(io.stderr) + backup.term_err = system.tcgetattr(io.stderr) + end + + backup.block_in = system.getnonblock(io.stdin) + backup.block_out = system.getnonblock(io.stdout) + backup.block_err = system.getnonblock(io.stderr) + + backup.consoleoutcodepage = system.getconsoleoutputcp() + backup.consolecp = system.getconsolecp() + + return backup + end + + + + --- Restores terminal settings from a backup + -- @tparam table backup the backup of terminal settings, see `termbackup`. + -- @treturn boolean true + function system.termrestore(backup) + if getmetatable(backup) ~= backup_mt then + error("arg #1 to termrestore, expected backup table, got " .. type(backup), 2) + end + + if backup.console_in then system.setconsoleflags(io.stdin, backup.console_in) end + if backup.term_in then system.tcsetattr(io.stdin, system.TCSANOW, backup.term_in) end + if backup.console_out then system.setconsoleflags(io.stdout, backup.console_out) end + if backup.term_out then system.tcsetattr(io.stdout, system.TCSANOW, backup.term_out) end + if backup.console_err then system.setconsoleflags(io.stderr, backup.console_err) end + if backup.term_err then system.tcsetattr(io.stderr, system.TCSANOW, backup.term_err) end + + if backup.block_in ~= nil then system.setnonblock(io.stdin, backup.block_in) end + if backup.block_out ~= nil then system.setnonblock(io.stdout, backup.block_out) end + if backup.block_err ~= nil then system.setnonblock(io.stderr, backup.block_err) end + + if backup.consoleoutcodepage then system.setconsoleoutputcp(backup.consoleoutcodepage) end + if backup.consolecp then system.setconsolecp(backup.consolecp) end + return true + end +end + + +do -- autotermrestore + local global_backup -- global backup for terminal settings + + + local add_gc_method do + -- __gc meta-method is not available in all Lua versions + local has_gc = not newproxy or false -- `__gc` was added when `newproxy` was removed + + if has_gc then + -- use default GC mechanism since it is available + function add_gc_method(t, f) + setmetatable(t, { __gc = f }) + end + else + -- create workaround using a proxy userdata, typical for Lua 5.1 + function add_gc_method(t, f) + local proxy = newproxy(true) + getmetatable(proxy).__gc = function() + t["__gc_proxy"] = nil + f(t) + end + t["__gc_proxy"] = proxy + end + end + end + + + --- Backs up terminal settings and restores them on application exit. + -- Calls `termbackup` to back up terminal settings and sets up a GC method to + -- automatically restore them on application exit (also works on Lua 5.1). + -- @treturn[1] boolean true + -- @treturn[2] nil if the backup was already created + -- @treturn[2] string error message + function system.autotermrestore() + if global_backup then + return nil, "global terminal backup was already set up" + end + global_backup = system.termbackup() + add_gc_method(global_backup, function(self) pcall(system.termrestore, self) end) + return true + end + + -- export a reset function only upon testing + if _G._TEST then + function system._reset_global_backup() + global_backup = nil + end + end +end + + + +do + local oldunpack = unpack or table.unpack + local pack = function(...) return { n = select("#", ...), ... } end + local unpack = function(t) return oldunpack(t, 1, t.n) end + + --- Wraps a function to automatically restore terminal settings upon returning. + -- Calls `termbackup` before calling the function and `termrestore` after. + -- @tparam function f function to wrap + -- @treturn function wrapped function + function system.termwrap(f) + if type(f) ~= "function" then + error("arg #1 to wrap, expected function, got " .. type(f), 2) + end + + return function(...) + local bu = system.termbackup() + local results = pack(f(...)) + system.termrestore(bu) + return unpack(results) + end + end +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`) +-- @usage -- Print the flags for stdin/out/err +-- system.listconsoleflags(io.stdin) +-- system.listconsoleflags(io.stdout) +-- system.listconsoleflags(io.stderr) +function system.listconsoleflags(fh) + local flagtype + if fh == io.stdin then + print "------ STDIN FLAGS WINDOWS ------" + flagtype = "CIF_" + elseif fh == io.stdout then + print "------ STDOUT FLAGS WINDOWS ------" + flagtype = "COF_" + elseif fh == io.stderr then + print "------ STDERR FLAGS WINDOWS ------" + flagtype = "COF_" + end + + local flags = assert(system.getconsoleflags(fh)) + local out = {} + for k,v in pairs(system) do + if type(k) == "string" and k:sub(1,4) == flagtype then + if flags:has_all_of(v) then + out[#out+1] = string.format("%10d [x] %s",v:value(),k) + else + out[#out+1] = string.format("%10d [ ] %s",v:value(),k) + end + end + end + table.sort(out) + for k,v in pairs(out) do + print(v) + end +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`) +-- @usage -- Print the flags for stdin/out/err +-- system.listconsoleflags(io.stdin) +-- system.listconsoleflags(io.stdout) +-- system.listconsoleflags(io.stderr) +function system.listtermflags(fh) + if fh == io.stdin then + print "------ STDIN FLAGS POSIX ------" + elseif fh == io.stdout then + print "------ STDOUT FLAGS POSIX ------" + elseif fh == io.stderr then + print "------ STDERR FLAGS POSIX ------" + end + + local flags = assert(system.tcgetattr(fh)) + for _, flagtype in ipairs { "iflag", "oflag", "lflag" } do + local prefix = flagtype:sub(1,1):upper() .. "_" -- I_, O_, or L_, the constant prefixes + local out = {} + for k,v in pairs(system) do + if type(k) == "string" and k:sub(1,2) == prefix then + if flags[flagtype]:has_all_of(v) then + out[#out+1] = string.format("%10d [x] %s",v:value(),k) + else + out[#out+1] = string.format("%10d [ ] %s",v:value(),k) + end + end + end + table.sort(out) + for k,v in pairs(out) do + print(v) + end + end +end + + + +do + --- Reads a single byte from the console, with a timeout. + -- This function uses `system.sleep` 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. + -- 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. + -- @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. + function system.readkey(timeout) + 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() + while key == nil and timeout > 0 do + system.sleep(math.min(interval, timeout)) + timeout = timeout - interval + interval = math.min(0.2, interval * 2) + key = system._readkey() + end + + if key then + return key + end + return nil, "timeout" + end +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 + + --- Reads a single key, if it is the start of ansi escape sequence then it reads + -- the full sequence. The key can be a multi-byte string in case of multibyte UTF-8 character. + -- This function uses `system.readkey`, and hence `system.sleep` to wait until either a key is + -- available or the timeout is reached. + -- It returns immediately if a key is available or if `timeout` is less than or equal to `0`. + -- In case of an ANSI sequence, it will return the full sequence as a string. + -- @tparam number timeout the timeout in seconds. + -- @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[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. + function system.readansi(timeout) + if type(timeout) ~= "number" then + error("arg #1 to readansi, expected timeout in seconds, got " .. type(timeout), 2) + end + + local key + + 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) + if key == nil then -- timeout or error + return nil, err + end + 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) + 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" + 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 + -- single byte character + utf8_length = nil + return string.char(key), "char" + else + -- UTF8 sequence detected + sequence = { key } + end + end + end + + local err + if utf8_length then + -- read remainder of UTF8 sequence + local timeout_end = system.gettime() + timeout + while true do + key, err = system.readkey(timeout_end - system.gettime()) + if err then + break + end + table.insert(sequence, key) + + if #sequence == utf8_length then + -- end of sequence, return the full sequence + local result = string.char(unpack(sequence)) + sequence = nil + utf8_length = nil + return result, "char" + end + end + + else + -- read remainder of ANSI sequence + local timeout_end = system.gettime() + timeout + while true do + key, err = system.readkey(timeout_end - system.gettime()) + if err then + break + end + table.insert(sequence, key) + + if (key >= 65 and key <= 90) or (key >= 97 and key <= 126) then + -- end of sequence, return the full sequence + local result = string.char(unpack(sequence)) + sequence = nil + return result, "ansi" + end + end + end + + -- error, or timeout reached, return the sequence so far + local partial = string.char(unpack(sequence)) + return nil, err, partial + end +end + + + return system |