From 86ac89fb616cea93c460f78f6997f6a5ff040e9c Mon Sep 17 00:00:00 2001 From: Thijs Schreijer Date: Sun, 20 Apr 2025 12:32:07 +0200 Subject: docs(terminal): reorganize terminal section into subsections (#66) --- docs/modules/system.html | 1002 ++++++++++++++++++++++++---------------------- 1 file changed, 521 insertions(+), 481 deletions(-) (limited to 'docs/modules/system.html') diff --git a/docs/modules/system.html b/docs/modules/system.html index 0934b35..6840b85 100644 --- a/docs/modules/system.html +++ b/docs/modules/system.html @@ -37,7 +37,12 @@
  • Environment
  • Random
  • Terminal
    • +
  • Terminal_Windows
    • +
  • Terminal_Posix
    • +
  • Terminal_Input
    • +
  • Terminal_UTF-8
  • Time
    • +
  • Terminal_Backup
    • @@ -112,97 +117,93 @@

    Terminal

    - - - - - - - - - - - - - - + + - - + + +
    CODEPAGE_UTF8UTF8 codepage.
    _readkey ()Reads a key from the console non-blocking.
    autotermrestore ()Backs up terminal settings and restores them on application exit.
    detachfds ()Creates new file descriptions for stdout and stderr.isatty (file)Checks if a file-handle is a TTY.
    getconsolecp ()Gets the current console code page (Windows).termsize ()Get the size of the terminal in rows and columns.
    +

    Terminal_Windows

    + - - + + - - + + +
    getconsoleflags (file) Gets console flags (Windows).
    getconsoleoutputcp ()Gets the current console output code page (Windows).listconsoleflags (fh)Debug function for console flags (Windows).
    getnonblock (fd)Gets non-blocking mode status for a file (Posix).setconsoleflags (file, bitflags)Sets the console flags (Windows).
    +

    Terminal_Posix

    + - - + + - - + + - - - - - - + + - - + + - - + + +
    isatty (file)Checks if a file-handle is a TTY.detachfds ()Creates new file descriptions for stdout and stderr.
    listconsoleflags (fh)Debug function for console flags (Windows).getnonblock (fd)Gets non-blocking mode status for a file (Posix).
    listtermflags (fh) Debug function for terminal flags (Posix).
    readansi (timeout[, fsleep=system.sleep])Reads a single key, if it is the start of ansi escape sequence then it reads - the full sequence.
    readkey (timeout[, fsleep=system.sleep])Reads a single byte from the console, with a timeout.setnonblock (fd, make_non_block)Enables or disables non-blocking mode for a file (Posix).
    setconsolecp (cp)Sets the current console code page (Windows).tcgetattr (fd)Get termios state (Posix).
    setconsoleflags (file, bitflags)Sets the console flags (Windows).tcsetattr (fd, actions, termios)Set termios state (Posix).
    +

    Terminal_Input

    + - - + + - - + + - - + + +
    setconsoleoutputcp (cp)Sets the current console output code page (Windows)._readkey ()Reads a key from the console non-blocking.
    setnonblock (fd, make_non_block)Enables or disables non-blocking mode for a file (Posix).readansi (timeout[, fsleep=system.sleep])Reads a single key, if it is the start of ansi escape sequence then it reads + the full sequence.
    tcgetattr (fd)Get termios state (Posix).readkey (timeout[, fsleep=system.sleep])Reads a single byte from the console, with a timeout.
    +

    Terminal_UTF-8

    + - - + + - - + + - - + + - - + + - - + + @@ -228,6 +229,25 @@
    tcsetattr (fd, actions, termios)Set termios state (Posix).CODEPAGE_UTF8UTF8 codepage.
    termbackup ()Returns a backup of terminal settings for stdin/out/err.getconsolecp ()Gets the current console code page (Windows).
    termrestore (backup)Restores terminal settings from a backupgetconsoleoutputcp ()Gets the current console output code page (Windows).
    termsize ()Get the size of the terminal in rows and columns.setconsolecp (cp)Sets the current console code page (Windows).
    termwrap (f)Wraps a function to automatically restore terminal settings upon returning.setconsoleoutputcp (cp)Sets the current console output code page (Windows).
    utf8cwidth (utf8_char)Sleep without a busy loop.
    +

    Terminal_Backup

    + + + + + + + + + + + + + + + + + +
    autotermrestore ()Backs up terminal settings and restores them on application exit.
    termbackup ()Returns a backup of terminal settings for stdin/out/err.
    termrestore (backup)Restores terminal settings from a backup
    termwrap (f)Wraps a function to automatically restore terminal settings upon returning.


    @@ -403,95 +423,66 @@ requested number of bytes, or an error, never a partial result.
    - - CODEPAGE_UTF8 + + isatty (file)
    - UTF8 codepage. - To be used with system.setconsoleoutputcp and system.setconsolecp. + Checks if a file-handle is a TTY. +

    Parameters:

      -
    • CODEPAGE_UTF8 - The Windows CodePage for UTF8. +
    • file + file + the file-handle to check, one of io.stdin, io.stdout, io.stderr.
    - - - - -
    -
    - - _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. + 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
      +
    - - autotermrestore () + + termsize ()
    - 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). + Get the size of the terminal in rows and columns.

    Returns:

      - - boolean - true +
    1. + int + the number of rows
      2. +
    2. + int + the number of columns

    Or

    1. nil - if the backup was already created
      2. + + +
    2. string error message
      3. @@ -501,60 +492,10 @@ sequences will be buffered internally and returned one byte at a time.
    -
    - - detachfds () -
    -
    - Creates new file descriptions for stdout and stderr. -Even if the file descriptors are unique, they still might point to the same -file description, and hence share settings like O_NONBLOCK. This means that -if one of them is set to non-blocking, the other will be as well. This can -lead to unexpected behavior.

    - -

    This function is used to detach stdout and stderr from the original -file descriptions, and create new file descriptions for them. This allows -independent control of flags (e.g., O_NONBLOCK) on stdout and stderr, -avoiding shared side effects.

    - -

    Does not modify stdin (fd 0), and does nothing on Windows. - - - -

    Returns:

    -
      - - boolean true on success, or throws an error on failure. -
    - - -

    See also:

    - - - -
    -
    - - getconsolecp () -
    -
    - Gets the current console code page (Windows). - - - -

    Returns:

    -
      - - int - the current code page (always 65001 on Posix systems) -
    - - - +
    +

    Terminal_Windows

    - +
    getconsoleflags (file) @@ -611,107 +552,6 @@ for more information on the flags. 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. -
    - - -

    See also:

    - - - -
    -
    - - 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
      -
    -
    @@ -742,194 +582,125 @@ system.listconsoleflags(
    - - listtermflags (fh) + + setconsoleflags (file, bitflags)
    - Debug function for terminal flags (Posix). - Pretty prints the current flags set for the handle. - - -

    Parameters:

    - - - - + 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).

    -

    Usage:

    -
      - 
      -- Print the flags for stdin/out/err
-system.listconsoleflags(io.stdin)
-system.listconsoleflags(io.stdout)
-system.listconsoleflags(io.stderr)
      -
    +

    To see flag status and constant names check listconsoleflags.

    -
    -
    - - readansi (timeout[, fsleep=system.sleep]) -
    -
    - 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 fsleep 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. +

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

    Parameters:

      -
    • timeout - number - the timeout in seconds. +
    • file + file + file handle to operate on, one of io.stdin, io.stdout, io.stderr
      • -
    • fsleep - function - the function to call for sleeping. - (default system.sleep) +
    • bitflags + bitflags + the flags to set/unset

    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. + + boolean + true on success

    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. - The function retains its own internal buffer, so on the next call the incomplete buffer is used to - complete the sequence.
      4. + error message
    +

    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
      +
    +
    +

    Terminal_Posix

    + +
    - - readkey (timeout[, fsleep=system.sleep]) + + detachfds ()
    - 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. - It returns immediately if a byte is available or if timeout is less than or equal to 0.

    + Creates new file descriptions for stdout and stderr. +Even if the file descriptors are unique, they still might point to the same +file description, and hence share settings like O_NONBLOCK. This means that +if one of them is set to non-blocking, the other will be as well. This can +lead to unexpected behavior.

    -

    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. +

    This function is used to detach stdout and stderr from the original +file descriptions, and create new file descriptions for them. This allows +independent control of flags (e.g., O_NONBLOCK) on stdout and stderr, +avoiding shared side effects.

    + +

    Does not modify stdin (fd 0), and does nothing on Windows. -

    Parameters:

    -
      -
    • timeout - number - the timeout in seconds. -
      • -
    • fsleep - function - the function to call for sleeping; ok, err = fsleep(secs) - (default system.sleep) -
      • -

    Returns:

      - byte - the byte value that was read. -
    -

    Or

    -
      -
    1. - nil - if no key was read
      2. -
    2. - string - error message when the timeout was reached ("timeout"), or if sleep failed.
      3. + boolean true on success, or throws an error on failure.
    - - -
    -
    - - setconsolecp (cp) -
    -
    - Sets the current console code page (Windows). - - -

    Parameters:

    +

    See also:

    -

    Returns:

    -
      - - bool - true on success (always true on Posix systems) -
    - - -
    - - setconsoleflags (file, bitflags) + + getnonblock (fd)
    - 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 + Gets non-blocking mode status for a file (Posix).

    Parameters:

    Returns:

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

    Or

      @@ -941,48 +712,45 @@ See s
    1. string error message
      2. +
    2. + int + errnum
    - -

    Usage:

    +

    See also:

      - 
      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
      + setnonblock
    +
    - - setconsoleoutputcp (cp) + + listtermflags (fh)
    - Sets the current console output code page (Windows). + Debug function for terminal flags (Posix). + Pretty prints the current flags set for the handle.

    Parameters:

    -

    Returns:

    -
      - - bool - true on success (always true on Posix systems) -
    +

    Usage:

    +
      + 
      -- Print the flags for stdin/out/err
+system.listconsoleflags(io.stdin)
+system.listconsoleflags(io.stdout)
+system.listconsoleflags(io.stderr)
      +
    @@ -1158,61 +926,237 @@ flags for the iflags, oflags, and lflags if given will set the output flags (optional) -
  • lflag - bitflags - if given will set the local 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
      +
    + + +
    +

    Terminal_Input

    + +
    +
    + + _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. +
    + + + + +
    +
    + + readansi (timeout[, fsleep=system.sleep]) +
    +
    + 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 fsleep 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. +
      • +
    • fsleep + function + the function to call for sleeping. + (default system.sleep) +
      • +
    + +

    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. + The function retains its own internal buffer, so on the next call the incomplete buffer is used to + complete the sequence.
      4. +
    + + + + +
    +
    + + readkey (timeout[, fsleep=system.sleep]) +
    +
    + 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. + 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. +
      • +
    • fsleep + function + the function to call for sleeping; ok, err = fsleep(secs) + (default system.sleep)
      • -

    Returns:

      - bool - true, if successful. Always returns true on Windows. + byte + the byte value that was read.

    Or

    1. - nil
      2. + nil + if no key was read
    2. string - error message
      3. -
    3. - int - errnum
      4. + error message when the timeout was reached ("timeout"), or if sleep failed.
    -

    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
      +
    +
    +

    Terminal_UTF-8

    + +
    +
    + + CODEPAGE_UTF8 +
    +
    + UTF8 codepage. + To be used with system.setconsoleoutputcp and system.setconsolecp. + + +
      +
    • CODEPAGE_UTF8 + The Windows CodePage for UTF8. +
    + + + +
    - - termbackup () + + getconsolecp ()
    - 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. + Gets the current console code page (Windows).

    Returns:

      - table with backup of terminal settings + int + the current code page (always 65001 on Posix systems)
    @@ -1220,26 +1164,19 @@ flags for the iflags, oflags, and lflags
    - - termrestore (backup) + + getconsoleoutputcp ()
    - Restores terminal settings from a backup + Gets the current console output code page (Windows). -

    Parameters:

    -

    Returns:

      - boolean - true + int + the current code page (always 65001 on Posix systems)
    @@ -1247,33 +1184,26 @@ flags for the iflags, oflags, and lflags
    - - termsize () + + setconsolecp (cp)
    - Get the size of the terminal in rows and columns. + Sets the current console code page (Windows). +

    Parameters:

    +

    Returns:

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

    Or

    -
      -
    1. - nil - -
      2. -
    2. - string - error message
      3. + bool + true on success (always true on Posix systems)
    @@ -1281,27 +1211,26 @@ flags for the iflags, oflags, and lflags
    - - termwrap (f) + + setconsoleoutputcp (cp)
    - Wraps a function to automatically restore terminal settings upon returning. - Calls termbackup before calling the function and termrestore after. + Sets the current console output code page (Windows).

    Parameters:

      -
    • f - function - function to wrap +
    • cp + int + the code page to set, use system.CODEPAGE_UTF8 (65001) for UTF-8

    Returns:

      - function - wrapped function + bool + true on success (always true on Posix systems)
    @@ -1461,6 +1390,117 @@ This function will sleep, without doing a busy-loop and wasting CPU cycles. +
    +
    +

    Terminal_Backup

    + +
    +
    + + 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. +
    + + + + +
    +
    + + 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 +
    + + + + +
    +
    + + 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 +
    + + + +
    @@ -1469,7 +1509,7 @@ This function will sleep, without doing a busy-loop and wasting CPU cycles.
    generated by LDoc 1.5.0 -Last updated 2025-04-15 13:14:45 +Last updated 2025-04-17 09:50:39
    -- cgit v1.2.3-55-g6feb