From bb4fd73c317cc88beb5e58c1abf52138abed107f Mon Sep 17 00:00:00 2001 From: Thijs Schreijer Date: Thu, 20 Jun 2024 23:16:29 +0200 Subject: Release v0.4.0 (#24) --- docs/modules/system.html | 1418 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1418 insertions(+) create mode 100644 docs/modules/system.html (limited to 'docs/modules/system.html') diff --git a/docs/modules/system.html b/docs/modules/system.html new file mode 100644 index 0000000..0423e37 --- /dev/null +++ b/docs/modules/system.html @@ -0,0 +1,1418 @@ + + + + + Lua-System docs + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module system

+

Platform independent system calls for Lua.

+

+ +

+ + +

Fields

+ + + + + +
windowsFlag to identify Windows.
+

Environment

+ + + + + + + + + + + + + +
getenv (name)Gets the value of an environment variable.
getenvs ()Returns a table with all environment variables.
setenv (name[, value])Sets an environment variable.
+

Random

+ + + + + +
random ([length=1])Generate random bytes.
+

Terminal

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CODEPAGE_UTF8UTF8 codepage.
_readkey ()Reads a key from the console non-blocking.
autotermrestore ()Backs up terminal settings and restores them on application exit.
getconsolecp ()Gets the current console code page (Windows).
getconsoleflags (file)Gets console flags (Windows).
getconsoleoutputcp ()Gets the current console output code page (Windows).
getnonblock (fd)Gets non-blocking mode status for a file (Posix).
isatty (file)Checks if a file-handle is a TTY.
listconsoleflags (fh)Debug function for console flags (Windows).
listtermflags (fh)Debug function for terminal flags (Posix).
readansi (timeout)Reads a single key, if it is the start of ansi escape sequence then it reads + the full sequence.
readkey (timeout)Reads a single byte from the console, with a timeout.
setconsolecp (cp)Sets the current console code page (Windows).
setconsoleflags (file, bitflags)Sets the console flags (Windows).
setconsoleoutputcp (cp)Sets the current console output code page (Windows).
setnonblock (fd, make_non_block)Enables or disables non-blocking mode for a file (Posix).
tcgetattr (fd)Get termios state (Posix).
tcsetattr (fd, actions, termios)Set termios state (Posix).
termbackup ()Returns a backup of terminal settings for stdin/out/err.
termrestore (backup)Restores terminal settings from a backup
termsize ()Get the size of the terminal in rows and columns.
termwrap (f)Wraps a function to automatically restore terminal settings upon returning.
utf8cwidth (utf8_char)Get the width of a utf8 character for terminal display.
utf8swidth (utf8_string)Get the width of a utf8 string for terminal display.
+

Time

+ + + + + + + + + + + + + +
gettime ()Get system time.
monotime ()Get monotonic time.
sleep (seconds[, precision=16])Sleep without a busy loop.
+ +
+
+ + +

Fields

+ +
+
+ + windows +
+
+ Flag to identify Windows. + + +
    +
  • windows + true if on Windows, false otherwise. +
    • +
+ + + + + +
+
+

Environment

+ +
+
+ + getenv (name) +
+
+ Gets the value of an environment variable.

+ +

NOTE: Windows has multiple copies of environment variables. For this reason, +the setenv function will not work with Lua's os.getenv on Windows. If you want +to use setenv then consider patching os.getenv with this implementation of getenv. + + +

Parameters:

+
    +
  • name + string + name of the environment variable +
    • +
+ +

Returns:

+
    + + string or nil + value of the environment variable, or nil if the variable is not set +
+ + + + +
+
+ + getenvs () +
+
+ Returns a table with all environment variables. + + + +

Returns:

+
    + + table + table with all environment variables and their values +
+ + + + +
+
+ + setenv (name[, value]) +
+
+ Sets an environment variable.

+ +

NOTE: Windows has multiple copies of environment variables. For this reason, the +setenv function will not work with Lua's os.getenv on Windows. If you want to use +it then consider patching os.getenv with the implementation of system.getenv. + + +

Parameters:

+
    +
  • name + string + name of the environment variable +
    • +
  • value + string + value of the environment variable, if nil the variable will be deleted (on +Windows, setting an empty string, will also delete the variable) + (optional) +
    • +
+ +

Returns:

+
    + + boolean + success +
+ + + + +
+
+

Random

+ +
+
+ + random ([length=1]) +
+
+ Generate random bytes. +This uses CryptGenRandom() on Windows, and /dev/urandom on other platforms. It will return the +requested number of bytes, or an error, never a partial result. + + +

Parameters:

+
    +
  • length + int + number of bytes to get + (default 1) +
    • +
+ +

Returns:

+
    + + string + string of random bytes +
+

Or

+
    +
  1. + nil + + +
    2. +
  2. + string + error message
    3. +
+ + + + +
+
+

Terminal

+ +
+ Unix: see https://blog.nelhage.com/2009/12/a-brief-introduction-to-termios-termios3-and-stty/

+ +

Windows: see https://learn.microsoft.com/en-us/windows/console/console-reference +

+
+
+ + CODEPAGE_UTF8 +
+
+ UTF8 codepage. + To be used with system.setconsoleoutputcp and system.setconsolecp. + + +
    +
  • CODEPAGE_UTF8 + The Windows CodePage for UTF8. +
    • +
+ + + + + +
+
+ + _readkey () +
+
+ Reads a key from the console non-blocking. This function should not be called +directly, but through the system.readkey or system.readansi functions. It +will return the next byte from the input stream, or nil if no key was pressed.

+ +

On Posix, io.stdin must be set to non-blocking mode using setnonblock +and canonical mode must be turned off using tcsetattr, +before calling this function. Otherwise it will block. No conversions are +done on Posix, so the byte read is returned as-is.

+ +

On Windows this reads a wide character and converts it to UTF-8. Multi-byte +sequences will be buffered internally and returned one byte at a time. + + + +

Returns:

+
    + + integer + the byte read from the input stream +
+

Or

+
    + + nil + if no key was pressed +
+

Or

+
    +
  1. + nil + on error
    2. +
  2. + string + error message
    3. +
  3. + int + errnum (on posix)
    4. +
+ + + + +
+
+ + autotermrestore () +
+
+ 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). + + + +

Returns:

+
    + + boolean + true +
+

Or

+
    +
  1. + nil + if the backup was already created
    2. +
  2. + string + error message
    3. +
+ + + + +
+
+ + getconsolecp () +
+
+ Gets the current console code page (Windows). + + + +

Returns:

+
    + + int + the current code page (always 65001 on Posix systems) +
+ + + + +
+
+ + getconsoleflags (file) +
+
+ Gets console flags (Windows). +The CIF_ and COF_ constants are available on the module table. Where CIF are the +input flags (for use with io.stdin) and COF are the output flags (for use with +io.stdout/io.stderr).

+ +

Note: See setconsolemode documentation +for more information on the flags. + + +

Parameters:

+ + +

Returns:

+
    + + bitflags + the current console flags. +
+

Or

+
    +
  1. + nil + + +
    2. +
  2. + string + error message
    3. +
+ + + +

Usage:

+
    + 
    local system = require('system')
+
+local flags = system.getconsoleflags(io.stdout)
+print("Current stdout flags:", tostring(flags))
+
+if flags:has_all_of(system.COF_VIRTUAL_TERMINAL_PROCESSING + system.COF_PROCESSED_OUTPUT) then
+    print("Both flags are set")
+else
+    print("At least one flag is not set")
+end
    +
+ +
+
+ + getconsoleoutputcp () +
+
+ Gets the current console output code page (Windows). + + + +

Returns:

+
    + + int + the current code page (always 65001 on Posix systems) +
+ + + + +
+
+ + getnonblock (fd) +
+
+ Gets non-blocking mode status for a file (Posix). + + +

Parameters:

+ + +

Returns:

+
    + + bool + true if set to non-blocking, false if not. Always returns false on Windows. +
+

Or

+
    +
  1. + nil + + +
    2. +
  2. + string + error message
    3. +
  3. + int + errnum
    4. +
+ + + + +
+
+ + isatty (file) +
+
+ Checks if a file-handle is a TTY. + + +

Parameters:

+ + +

Returns:

+
    + + boolean + true if the file is a tty +
+ + + +

Usage:

+
    + 
    local system = require('system')
+if system.isatty(io.stdin) then
+    -- enable ANSI coloring etc on Windows, does nothing in Posix.
+    local flags = system.getconsoleflags(io.stdout)
+    system.setconsoleflags(io.stdout, flags + sys.COF_VIRTUAL_TERMINAL_PROCESSING)
+end
    +
+ +
+
+ + listconsoleflags (fh) +
+
+ Debug function for console flags (Windows). + Pretty prints the current flags set for the handle. + + +

Parameters:

+ + + + + +

Usage:

+
    + 
    -- Print the flags for stdin/out/err
+system.listconsoleflags(io.stdin)
+system.listconsoleflags(io.stdout)
+system.listconsoleflags(io.stderr)
    +
+ +
+
+ + listtermflags (fh) +
+
+ Debug function for terminal flags (Posix). + Pretty prints the current flags set for the handle. + + +

Parameters:

+ + + + + +

Usage:

+
    + 
    -- Print the flags for stdin/out/err
+system.listconsoleflags(io.stdin)
+system.listconsoleflags(io.stdout)
+system.listconsoleflags(io.stderr)
    +
+ +
+
+ + readansi (timeout) +
+
+ 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. + + +

Parameters:

+
    +
  • timeout + number + the timeout in seconds. +
    • +
+ +

Returns:

+
    +
  1. + string + the character that was received (can be multi-byte), or a complete ANSI sequence
    2. +
  2. + string + the type of input: "char" for a single key, "ansi" for an ANSI sequence
    3. +
+

Or

+
    +
  1. + nil + in case of an error
    2. +
  2. + string + error message; "timeout" if the timeout was reached.
    3. +
  3. + string + partial result in case of an error while reading a sequence, the sequence so far.
    4. +
+ + + + +
+
+ + readkey (timeout) +
+
+ 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. + + +

Parameters:

+
    +
  • timeout + number + the timeout in seconds. +
    • +
+ +

Returns:

+
    + + byte + the byte value that was read. +
+

Or

+
    +
  1. + nil + if no key was read
    2. +
  2. + string + error message; "timeout" if the timeout was reached.
    3. +
+ + + + +
+
+ + setconsolecp (cp) +
+
+ Sets the current console code page (Windows). + + +

Parameters:

+ + +

Returns:

+
    + + bool + true on success (always true on Posix systems) +
+ + + + +
+
+ + setconsoleflags (file, bitflags) +
+
+ Sets the console flags (Windows). +The CIF_ and COF_ constants are available on the module table. Where CIF are the +input flags (for use with io.stdin) and COF are the output flags (for use with +io.stdout/io.stderr).

+ +

To see flag status and constant names check listconsoleflags.

+ +

Note: not all combinations of flags are allowed, as some are mutually exclusive or mutually required. +See setconsolemode documentation + + +

Parameters:

+ + +

Returns:

+
    + + boolean + true on success +
+

Or

+
    +
  1. + nil + + +
    2. +
  2. + string + error message
    3. +
+ + + +

Usage:

+
    + 
    local system = require('system')
+system.listconsoleflags(io.stdout) -- List all the available flags and their current status
+
+local flags = system.getconsoleflags(io.stdout)
+assert(system.setconsoleflags(io.stdout,
+        flags + system.COF_VIRTUAL_TERMINAL_PROCESSING)
+
+system.listconsoleflags(io.stdout) -- List again to check the differences
    +
+ +
+
+ + setconsoleoutputcp (cp) +
+
+ Sets the current console output code page (Windows). + + +

Parameters:

+ + +

Returns:

+
    + + bool + true on success (always true on Posix systems) +
+ + + + +
+
+ + setnonblock (fd, make_non_block) +
+
+ Enables or disables non-blocking mode for a file (Posix). + + +

Parameters:

+
    +
  • fd + file + file handle to operate on, one of io.stdin, io.stdout, io.stderr +
    • +
  • make_non_block + boolean + a truthy value will enable non-blocking mode, a falsy value will disable it. +
    • +
+ +

Returns:

+
    + + bool + true, if successful +
+

Or

+
    +
  1. + nil + + +
    2. +
  2. + string + error message
    3. +
  3. + int + errnum
    4. +
+ + +

See also:

+ + +

Usage:

+
    + 
    local sys = require('system')
+
+-- set io.stdin to non-blocking mode
+local old_setting = sys.getnonblock(io.stdin)
+sys.setnonblock(io.stdin, true)
+
+-- do stuff
+
+-- restore old setting
+sys.setnonblock(io.stdin, old_setting)
    +
+ +
+
+ + tcgetattr (fd) +
+
+ +

Get termios state (Posix). +The terminal attributes is a table with the following fields:

+ +
    +
  • iflag input flags
    • +
  • oflag output flags
    • +
  • lflag local flags
    • +
  • cflag control flags
    • +
  • ispeed input speed
    • +
  • ospeed output speed
    • +
  • cc control characters
    • +
+ + + + +

Parameters:

+ + +

Returns:

+
    + + error message if failed +
+

Or

+
    + + termios + terminal attributes, if successful. On Windows the bitflags are all 0, and the cc table is empty. +
+

Or

+
    +
  1. + nil + + +
    2. +
  2. + string + error message
    3. +
  3. + int + errnum
    4. +
+ + + +

Usage:

+
    + 
    local system = require('system')
+
+local status = assert(tcgetattr(io.stdin))
+if status.iflag:has_all_of(system.I_IGNBRK) then
+    print("Ignoring break condition")
+end
    +
+ +
+
+ + tcsetattr (fd, actions, termios) +
+
+ Set termios state (Posix). +This function will set the flags as given.

+ +

The I_, O_, and L_ constants are available on the module table. They are the respective +flags for the iflags, oflags, and lflags bitmasks.

+ +

To see flag status and constant names check listtermflags. For their meaning check +the manpage.

+ +

Note: only iflag, oflag, and lflag are supported at the moment. The other fields are ignored. + + +

Parameters:

+
    +
  • fd + file + file handle to operate on, one of io.stdin, io.stdout, io.stderr +
    • +
  • actions + integer + one of TCSANOW, TCSADRAIN, TCSAFLUSH +
    • +
  • termios a table with bitflag fields: +
      +
    • iflag + bitflags + if given will set the input flags + (optional) +
      • +
    • oflag + bitflags + if given will set the output flags + (optional) +
      • +
    • lflag + bitflags + if given will set the local flags + (optional) +
      • +
    +
+ +

Returns:

+
    + + bool + true, if successful. Always returns true on Windows. +
+

Or

+
    +
  1. + nil
    2. +
  2. + string + error message
    3. +
  3. + int + errnum
    4. +
+ + + +

Usage:

+
    + 
    local system = require('system')
+
+local status = assert(tcgetattr(io.stdin))
+if not status.lflag:has_all_of(system.L_ECHO) then
+    -- if echo is off, turn echoing newlines on
+    tcsetattr(io.stdin, system.TCSANOW, { lflag = status.lflag + system.L_ECHONL }))
+end
    +
+ +
+
+ + termbackup () +
+
+ 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. + + + +

Returns:

+
    + + table with backup of terminal settings +
+ + + + +
+
+ + termrestore (backup) +
+
+ Restores terminal settings from a backup + + +

Parameters:

+ + +

Returns:

+
    + + boolean + true +
+ + + + +
+
+ + termsize () +
+
+ Get the size of the terminal in rows and columns. + + + +

Returns:

+
    +
  1. + int + the number of rows
    2. +
  2. + int + the number of columns
    3. +
+

Or

+
    +
  1. + nil + + +
    2. +
  2. + string + error message
    3. +
+ + + + +
+
+ + termwrap (f) +
+
+ Wraps a function to automatically restore terminal settings upon returning. + Calls termbackup before calling the function and termrestore after. + + +

Parameters:

+
    +
  • f + function + function to wrap +
    • +
+ +

Returns:

+
    + + function + wrapped function +
+ + + + +
+
+ + utf8cwidth (utf8_char) +
+
+ Get the width of a utf8 character for terminal display. + + +

Parameters:

+
    +
  • utf8_char + string + the utf8 character to check, only the width of the first character will be returned +
    • +
+ +

Returns:

+
    + + int + the display width in columns of the first character in the string (0 for an empty string) +
+

Or

+
    +
  1. + nil + + +
    2. +
  2. + string + error message
    3. +
+ + + + +
+
+ + utf8swidth (utf8_string) +
+
+ Get the width of a utf8 string for terminal display. + + +

Parameters:

+
    +
  • utf8_string + string + the utf8 string to check +
    • +
+ +

Returns:

+
    + + int + the display width of the string in columns (0 for an empty string) +
+

Or

+
    +
  1. + nil + + +
    2. +
  2. + string + error message
    3. +
+ + + + +
+
+

Time

+ +
+
+ + gettime () +
+
+ Get system time. +The time is returned as the seconds since the epoch (1 January 1970 00:00:00). + + + +

Returns:

+
    + + number + seconds (fractional) +
+ + + + +
+
+ + monotime () +
+
+ Get monotonic time. +The time is returned as the seconds since system start. + + + +

Returns:

+
    + + number + seconds (fractional) +
+ + + + +
+
+ + sleep (seconds[, precision=16]) +
+
+ Sleep without a busy loop. +This function will sleep, without doing a busy-loop and wasting CPU cycles. + + +

Parameters:

+
    +
  • seconds + number + seconds to sleep (fractional). +
    • +
  • precision + integer + minimum stepsize in milliseconds (Windows only, ignored elsewhere) + (default 16) +
    • +
+ +

Returns:

+
    + + true on success, or nil+err on failure +
+ + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-06-20 23:11:37 +
+
+ + -- cgit v1.2.3-55-g6feb