Continue reading in 'read-event' etc. at the end of a keyboard macro

This fixes a bug that could make 'read-event', 'read-char', and
'read-char-exclusive' erroneously return -1, an internal magic return
value of 'read_char' leaked from C to lisp. Instead of returning -1, the
aforementioned lisp functions now transparently continue reading
available input (e.g., from the keyboard) when reaching the end of a
keyboard macro.

* src/keyboard.c (read_char, read_key_sequence): Move handling
of the end of a keyboard macro from 'read_char' to its caller
'read_key_sequence', which is the only caller that can
meaningfully deal with this case.
* src/macros.c (Fexecute_kbd_macro): Document how the end of keyboard
macro is processed.
* etc/NEWS: Announce this change.

1 files changed, 12 insertions, 0 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 2e51c0490fe..19cd170e5c7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2141,6 +2141,18 @@ Like the variable with the same name, it adds menus from the list that
 is the value of the property to context menus shown when clicking on the
 text which as this property.
 
+---
+** Detecting the end of an iteration of a keyboard macro
+'read-event', 'read-char', and 'read-char-exclusive' no longer return -1
+when called at the end of an iteration of a the execution of a keyboard
+macro.  Instead, they will transparently continue reading available input
+(e.g., from the keyboard).  If you need to detect the end of a macro
+iteration, check the following condition before calling one of the
+aforementioned functions:
+
+    (and (arrayp executing-kbd-macro)
+         (>= executing-kbd-macro-index (length executing-kbd-macro))))
+
 
 * Changes in Emacs 30.1 on Non-Free Operating Systems