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/topics/01-introduction.md.html | 27 ++++- docs/topics/02-development.md.html | 91 +++++++++++++++ docs/topics/03-terminal.md.html | 225 ++++++++++++++++++++++++++++++++++++ docs/topics/CHANGELOG.md.html | 55 +++++++-- docs/topics/LICENSE.md.html | 29 ++++- 5 files changed, 411 insertions(+), 16 deletions(-) create mode 100644 docs/topics/02-development.md.html create mode 100644 docs/topics/03-terminal.md.html (limited to 'docs/topics') diff --git a/docs/topics/01-introduction.md.html b/docs/topics/01-introduction.md.html index 319b9d5..019f7e4 100644 --- a/docs/topics/01-introduction.md.html +++ b/docs/topics/01-introduction.md.html @@ -27,17 +27,38 @@

Lua-System

+ +

Topics

Modules

+

Classes

+ +

Examples

+ @@ -62,8 +83,8 @@ independence.

-generated by LDoc 1.4.6 -Last updated 2023-12-15 13:15:09 +generated by LDoc 1.5.0 +Last updated 2024-06-20 23:11:37
diff --git a/docs/topics/02-development.md.html b/docs/topics/02-development.md.html new file mode 100644 index 0000000..e911eed --- /dev/null +++ b/docs/topics/02-development.md.html @@ -0,0 +1,91 @@ + + + + + Lua-System docs + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ + +

2. Development

+ +

Some tests cannot be run in CI becasue they test system specifics that +simply do not exist in a CI environment. An example is the isatty function +Which cannot be set to return a truthy value in CI.

+ +

The tests concerned are all labelled with #manual. And in CI they will +be skipped because --exclude-tags=manual is being passed to the +busted command line.

+ +

Hence if tests like this are being added, then please ensure the tests +pass locally, and do not rely on CI only.

+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-06-20 23:11:37 +
+
+ + diff --git a/docs/topics/03-terminal.md.html b/docs/topics/03-terminal.md.html new file mode 100644 index 0000000..3e7e548 --- /dev/null +++ b/docs/topics/03-terminal.md.html @@ -0,0 +1,225 @@ + + + + + Lua-System docs + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ + +

3. Terminal functionality

+ +

Terminals are fundamentally different on Windows and Posix. So even though +luasystem provides primitives to manipulate both the Windows and Posix terminals, +the user will still have to write platform specific code.

+ +

To mitigate this a little, all functions are available on all platforms. They just +will be a no-op if invoked on another platform. This means that no platform specific +branching is required (but still possible) in user code. The user must simply set +up both platforms to make it work.

+ +

+

3.1 Backup and Restore terminal settings

+ +

Since there are a myriad of settings available;

+ + + +

Some helper functions are available to backup and restore them all at once. +See termbackup, termrestore, autotermrestore and termwrap.

+ + +

+

3.1 Terminal ANSI sequences

+ +

Windows is catching up with this. In Windows 10 (since 2019), the Windows Terminal application (not to be +mistaken for the cmd console application) supports ANSI sequences. However this +might not be enabled by default.

+ +

ANSI processing can be set up both on the input (key sequences, reading cursor position) +as well as on the output (setting colors and cursor shapes).

+ +

To enable it use system.setconsoleflags like this:

+ + +
+-- setup Windows console to handle ANSI processing on output
+sys.setconsoleflags(io.stdout, sys.getconsoleflags(io.stdout) + sys.COF_VIRTUAL_TERMINAL_PROCESSING)
+sys.setconsoleflags(io.stderr, sys.getconsoleflags(io.stderr) + sys.COF_VIRTUAL_TERMINAL_PROCESSING)
+
+-- setup Windows console to handle ANSI processing on input
+sys.setconsoleflags(io.stdin, sys.getconsoleflags(io.stdin) + sys.CIF_VIRTUAL_TERMINAL_INPUT)
+
+ +

+

3.2 UTF-8 in/output and display width

+ +

3.2.1 UTF-8 in/output

+ +

Where (most) Posix systems use UTF-8 by default, Windows internally uses UTF-16. More +recent versions of Lua also have UTF-8 support. So luasystem also focusses on UTF-8.

+ +

On Windows UTF-8 output can be enabled by setting the output codepage like this:

+ + +
+-- setup Windows output codepage to UTF-8
+sys.setconsoleoutputcp(sys.CODEPAGE_UTF8)
+
+ +

Terminal input is handled by the _getwchar() function on Windows which returns +UTF-16 surrogate pairs. luasystem will automatically convert those to UTF-8. +So when using readkey or readansi to read keyboard input no additional changes +are required.

+ +

3.2.2 UTF-8 display width

+ +

Typical western characters and symbols are single width characters and will use only +a single column when displayed on a terminal. However many characters from other +languages/cultures or emojis require 2 columns for display.

+ +

Typically the wcwidth function is used on Posix to check the number of columns +required for display. However since Windows doesn't provide this functionality a +custom implementation is included based on the work by Markus Kuhn.

+ +

2 functions are provided, system.utf8cwidth for a single character, and system.utf8swidth for +a string. When writing terminal applications the display width is relevant to +positioning the cursor properly. For an example see the examples/readline.lua file.

+ + +

+

3.3 reading keyboard input

+ +

3.3.1 Non-blocking

+ +

There are 2 functions for keyboard input (actually 3, if taking system._readkey into +account): readkey and readansi.

+ +

readkey is a low level function and should preferably not be used, it returns +a byte at a time, and hence can leave stray/invalid byte sequences in the buffer if +only the start of a UTF-8 or ANSI sequence is consumed.

+ +

The preferred way is to use readansi which will parse and return entire characters in +single or multiple bytes, or a full ANSI sequence.

+ +

On Windows the input is read using _getwchar() which bypasses the terminal and reads +the input directly from the keyboard buffer. This means however that the character is +also not being echoed to the terminal (independent of the echo settings used with +system.setconsoleflags).

+ +

On Posix the traditional file approach is used, which:

+ +
    +
  • is blocking by default
    • +
  • echoes input to the terminal
    • +
  • requires enter to be pressed to pass the input (canonical mode)
    • +
+ +

To use non-blocking input here's how to set it up:

+ + +
+-- setup Windows console to disable echo and line input (not required since _getwchar is used, just for consistency)
+sys.setconsoleflags(io.stdin, sys.getconsoleflags(io.stdin) - sys.CIF_ECHO_INPUT - sys.CIF_LINE_INPUT)
+
+-- setup Posix by disabling echo, canonical mode, and making non-blocking
+local of_attr = sys.tcgetattr(io.stdin)
+sys.tcsetattr(io.stdin, sys.TCSANOW, {
+  lflag = of_attr.lflag - sys.L_ICANON - sys.L_ECHO,
+})
+sys.setnonblock(io.stdin, true)
+
+ +

Both functions require a timeout to be provided which allows for proper asynchronous +code to be written. Since the underlying sleep method used is system.sleep, just patching +that function with a coroutine based yielding one should be all that is needed to make +the result work with asynchroneous coroutine schedulers.

+ +

3.3.2 Blocking input

+ +

When using traditional input method like io.stdin:read() (which is blocking) the echo +and newline properties should be set on Windows similar to Posix. +For an example see examples/password_input.lua.

+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-06-20 23:11:37 +
+
+ + diff --git a/docs/topics/CHANGELOG.md.html b/docs/topics/CHANGELOG.md.html index 4e656c7..da8ddde 100644 --- a/docs/topics/CHANGELOG.md.html +++ b/docs/topics/CHANGELOG.md.html @@ -27,6 +27,10 @@

Lua-System

+ +

Contents