From b87e4a141da53cf903a0ab9fc9eb693c85a5c0b4 Mon Sep 17 00:00:00 2001
From: dam <dam@gudinoff>
Date: Sat, 4 May 2024 22:58:39 +0100
Subject: Documented get_key procedure and small cleanup.

---
 modules/TUI/module.jai | 38 ++++++++++++++++++++------------------
 1 file changed, 20 insertions(+), 18 deletions(-)

(limited to 'modules')

diff --git a/modules/TUI/module.jai b/modules/TUI/module.jai
index a6a3d11..772b30c 100644
--- a/modules/TUI/module.jai
+++ b/modules/TUI/module.jai
@@ -299,7 +299,7 @@ module_logger :: (message: string, data: *void, info: Log_Info) {
 }
 
 assert_is_active :: inline () {
-    assert(active, "Please call setup_terminal() before using the module procedures.");
+    assert(active, "Please call setup_terminal() to start using this module.");
 }
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -311,7 +311,6 @@ set_next_key :: inline (key: Key) {
     input_override = key;
 }
 
-// TODO Provide some documentation comments.
 get_key :: (timeout_milliseconds: s32 = -1) -> Key {
     assert_is_active();
     
@@ -319,25 +318,22 @@ get_key :: (timeout_milliseconds: s32 = -1) -> Key {
         defer input_override = xx Keys.None;
         return input_override;
     }
-
+    
     if OS_was_terminal_resized() return Keys.Resize;
 
-    should_read_input   := false;
-    is_input_available  := false;
+    // If there's nothing on the input_string buffer, await for input to be available,
+    // otherwise, if we have less than a complete Key, check if there's more to read.
+    should_read_input := false;
     
     if input_string.count == 0 {
-        should_read_input = true;
-        is_input_available = OS_wait_for_input(timeout_milliseconds);
+        should_read_input = OS_wait_for_input(timeout_milliseconds);
     }
     else if input_string.count < KEY_SIZE {
-        should_read_input = true;
-        is_input_available = OS_wait_for_input(0);
+        should_read_input = OS_wait_for_input(0);
     }
 
-    if OS_was_terminal_resized() return Keys.Resize;
-
-    if should_read_input && is_input_available {
-        // Copy buffered bytes to the start, and read the remaining ones from input.
+    if should_read_input {
+        // Copy data to the start of the input_string buffer.
         for 0..input_string.count-1 {
             input_buffer[it] = input_string[it];
         }
@@ -348,6 +344,9 @@ get_key :: (timeout_milliseconds: s32 = -1) -> Key {
         input_string.count += bytes_read;
     }
 
+    // The terminal may have been resized while waiting for or reading the input; check it again.
+    if OS_was_terminal_resized() return Keys.Resize;
+
     if input_string.count == 0 return Keys.None;
 
     // By default, parse a single UTF8 character (1 to 4 bytes).
@@ -368,12 +367,13 @@ get_key :: (timeout_milliseconds: s32 = -1) -> Key {
             key, success = table_find(*key_map, to_parse);
         }
 
-        
+
+        // If found, return the escape code, otherwise return a single escape character.
         if success {
-            return key; // Escape code found, return it.
+            return key;
         }
         else {
-            to_parse.count = 1; // No escape code found, return a single (escape) character.
+            to_parse.count = 1;
         }
     }
     
@@ -381,14 +381,15 @@ get_key :: (timeout_milliseconds: s32 = -1) -> Key {
 }
 
 // If count_limit has a non-negative value it will be used as the limit to the number of bytes on the returned string.
-// If any characters are provided in the terminators list, they will be used to scan and interrupt the input, including
+// If any ASCII characters are provided in the terminators list, they will be used to scan and interrupt the input, including
 // the terminator as the last character.
 // At least one of the arguments must be properly setup to avoid an infinite-loop reading the input.
 read_input :: (count_limit: int = -1, terminators: .. u8) -> string {
     assert_is_active();
     assert(count_limit >= 0 || terminators.count > 0, "Invalid arguments passed to read_input() will result in infinite-loop.");
 
-    // TODO Provide some documentation comments.
+    // Read until one of the terminator characters is found. 
+    // Since we don't know the resulting size of the returned string, we must keep the string builder growing.
     if count_limit < 0 {
         builder: String_Builder;
         init_string_builder(*builder);
@@ -411,6 +412,7 @@ read_input :: (count_limit: int = -1, terminators: .. u8) -> string {
         }
         return builder_to_string(*builder);
     }
+    // Do the same but limit the number of bytes in the returned string.
     else {
         buffer := alloc_string(count_limit);
         buffer.count = 0;
-- 
cgit v1.2.3