pybricks.tools.read_input_byte: Allow chr conversion of last byte.

The default behavior remains the same, but you can now optionally do:

read_input_byte(chr=True, last=True)

to apply the chr() function and discard all up to the last byte.

CHANGELOG.md

@@ -4,6 +4,17 @@
 
 ## [Unreleased]
 
+### Added
+- Added optional keyword arguments to `pybricks.tools.read_input_byte()` for
+  automatic conversion via `chr` and to skip to the last byte ([support#1574]).
+
+### Changed
+- Raise a descriptive error when the `Car` class can't find a steering mechanism
+  end stop within 10 seconds ([support#1564]).
+
+[support#1564]: https://github.com/pybricks/support/issues/1564
+[support#1574]: https://github.com/pybricks/support/issues/1574
+
 ## [3.5.0b1] - 2024-03-21
 
 ### Added
@@ -14,13 +25,10 @@
 
 ### Changed
 - Allow single floating point value for brightness array ([support#1547]).
-- Raise a descriptive error when the `Car` class can't find a steering mechanism
-  end stop within 10 seconds ([support#1564]).
 
 [support#1024]: https://github.com/pybricks/support/issues/1024
 [support#1537]: https://github.com/orgs/pybricks/discussions/1537
 [support#1547]: https://github.com/pybricks/support/issues/1547
-[support#1564]: https://github.com/pybricks/support/issues/1564
 
 ## [3.4.0] - 2024-03-11
 

pybricks/tools/pb_module_tools.c

@@ -152,22 +152,52 @@ mp_obj_t pb_module_tools_pbio_task_wait_or_await(pbio_task_t *task) {
 }
 
 /**
- * Reads one byte from stdin without blocking.
+ * Reads one byte or character from stdin without blocking.
  *
- * @returns The integer value of the byte read or @c None if no data is available.
+ * @param [in]  chr     Choose @c True to return a printable character or @c False to return an integer.
+ * @param [in]  last    Choose @c True to read until the last byte is read or @c False to return the first byte.
+ *
+ * @returns The value read or @c None if no valid data is available.
  */
-STATIC mp_obj_t pb_module_tools_read_input_byte(void) {
-    if (!(mp_hal_stdio_poll(MP_STREAM_POLL_RD) & MP_STREAM_POLL_RD)) {
-        // No bytes available.
+STATIC mp_obj_t pb_module_tools_read_input_byte(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    PB_PARSE_ARGS_FUNCTION(n_args, pos_args, kw_args,
+        PB_ARG_DEFAULT_FALSE(chr),
+        PB_ARG_DEFAULT_FALSE(last));
+
+    int chr = -1;
+
+    while ((mp_hal_stdio_poll(MP_STREAM_POLL_RD) & MP_STREAM_POLL_RD)) {
+        // REVISIT: In theory, this should not block if mp_hal_stdio_poll() and
+        // mp_hal_stdin_rx_chr() are implemented correctly and nothing happens
+        // in a thread/interrupt/kernel that changes the state.
+        chr = mp_hal_stdin_rx_chr();
+
+        // For last=True, read up to last, otherwise return first byte.
+        if (!mp_obj_is_true(last_in)) {
+            break;
+        }
+    }
+
+    // If no data is available, return None.
+    if (chr < 0) {
+        return mp_const_none;
+    }
+
+    // If chr=False, return the integer value of the byte.
+    if (!mp_obj_is_true(chr_in)) {
+        return MP_OBJ_NEW_SMALL_INT(chr);
+    }
+
+    // If char requested but not printable, return None.
+    if (chr < 32 || chr > 126) {
         return mp_const_none;
     }
 
-    // REVISIT: In theory, this should not block if mp_hal_stdio_poll() and
-    // mp_hal_stdin_rx_chr() are implemented correctly and nothing happens
-    // in a thread/interrupt/kernel that changes the state.
-    return MP_OBJ_NEW_SMALL_INT(mp_hal_stdin_rx_chr());
+    // Return the character as a string.
+    const char result[] = {chr};
+    return mp_obj_new_str(result, sizeof(result));
 }
-STATIC MP_DEFINE_CONST_FUN_OBJ_0(pb_module_tools_read_input_byte_obj, pb_module_tools_read_input_byte);
+STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pb_module_tools_read_input_byte_obj, 0, pb_module_tools_read_input_byte);
 
 STATIC mp_obj_t pb_module_tools_run_task(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     PB_PARSE_ARGS_FUNCTION(n_args, pos_args, kw_args,