enhance the key_reader program

The original `key_reader` program was useful but didn't do much that `xxd`
or `od -tx1z` didn't do. Furthermore, it wasn't built and installed by
default. This change adds features that make it superior to those programs
for decoding interactive key presses and makes it a first-class citizen
like the `fish_indent` program that is always available.

Fixes #2991

8 files changed, 299 insertions, 84 deletions

diff --git a/.gitignore b/.gitignore
index 2420bb4e..4f123aee 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,6 +21,7 @@ doc_src/commands.hdr
 doc_src/index.hdr
 po/*.gmo
 fish
+fish_key_reader
 fish_indent
 fish_tests
 fish.pc
diff --git a/Makefile.in b/Makefile.in
index 6172721e..4bb0998c 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -119,7 +119,7 @@ FISH_TESTS_OBJS := $(FISH_OBJS) obj/fish_tests.o
 # (that is, are not themselves #included in other source files)
 #
 FISH_ALL_OBJS := $(sort $(FISH_OBJS) $(FISH_INDENT_OBJS) $(FISH_TESTS_OBJS) \
-                   obj/fish.o obj/key_reader.o)
+                   obj/fish.o obj/fish_key_reader.o)
 
 #
 # Files containing user documentation
@@ -170,7 +170,7 @@ FUNCTIONS_DIR_FILES := $(wildcard share/functions/*.fish)
 #
 # Programs to install
 #
-PROGRAMS := fish fish_indent
+PROGRAMS := fish fish_indent fish_key_reader
 
 #
 # Manual pages to install
@@ -795,9 +795,11 @@ fish_indent: $(FISH_INDENT_OBJS) $(EXTRA_PCRE2)
 	$(CXX) $(CXXFLAGS) $(LDFLAGS) $(FISH_INDENT_OBJS) $(LIBS) -o $@
 
 #
-# Neat little program to show output from terminal
+# Build the fish_key_reader program to show input from the terminal. Note that
+# fish_key_reader doesn't need all of the object files that fish does but it
+# does need a significant number so it's easier to just use the same list.
 #
-key_reader: $(FISH_OBJS) $(EXTRA_PCRE2) obj/key_reader.o
+fish_key_reader: $(FISH_OBJS) $(EXTRA_PCRE2) obj/fish_key_reader.o
 	$(CXX) $(CXXFLAGS) $(LDFLAGS_FISH) $^ $(LIBS) -o $@
 
 #
@@ -866,7 +868,7 @@ clean:
 	rm -f obj/*.o *.o doc.h doc.tmp
 	rm -f doc_src/*.doxygen doc_src/*.cpp doc_src/*.o doc_src/commands.hdr
 	rm -f tests/tmp.err tests/tmp.out tests/tmp.status tests/foo.txt
-	rm -f $(PROGRAMS) fish_tests key_reader
+	rm -f $(PROGRAMS) fish_tests fish_key_reader
 	rm -f command_list.txt command_list_toc.txt toc.txt
 	rm -f doc_src/index.hdr doc_src/commands.hdr
 	rm -f lexicon_filter lexicon.txt lexicon.log
@@ -1019,8 +1021,8 @@ obj/io.o: src/fallback.h config.h src/signal.h src/wutil.h src/common.h
 obj/io.o: src/exec.h src/io.h
 obj/iothread.o: src/signal.h src/iothread.h src/common.h config.h
 obj/iothread.o: src/fallback.h
-obj/key_reader.o: src/common.h config.h src/fallback.h src/signal.h
-obj/key_reader.o: src/input_common.h
+obj/fish_key_reader.o: src/common.h config.h src/fallback.h src/signal.h
+obj/fish_key_reader.o: src/input_common.h
 obj/kill.o: src/fallback.h config.h src/signal.h src/kill.h src/common.h
 obj/kill.o: src/env.h src/exec.h src/path.h
 obj/output.o: config.h src/fallback.h src/signal.h src/wutil.h src/common.h
diff --git a/build_tools/iwyu.osx.imp b/build_tools/iwyu.osx.imp
index cad467cd..ee935302 100644
--- a/build_tools/iwyu.osx.imp
+++ b/build_tools/iwyu.osx.imp
@@ -83,6 +83,7 @@
     { symbol: ["pid_t", "private", "<sys/types.h>", "public"] },
     { symbol: ["uid_t", "private", "<sys/types.h>", "public"] },
     { symbol: ["gid_t", "private", "<sys/types.h>", "public"] },
+    { symbol: ["timeval", "private", "<sys/time.h>", "public"] },
     { symbol: ["uint32_t", "private", "<sys/types.h>", "public"] },
     { symbol: ["uint32_t", "private", "<stdint.h>", "public"] },
     { symbol: ["intptr_t", "private", "<stdint.h>", "public"] },
diff --git a/doc_src/fish_key_reader.txt b/doc_src/fish_key_reader.txt
new file mode 100644
index 00000000..9e5afca6
--- /dev/null
+++ b/doc_src/fish_key_reader.txt
@@ -0,0 +1,40 @@
+\section fish_key_reader fish_key_reader - explore what characters keyboard keys send
+
+\subsection fish_key_reader-synopsis Synopsis
+\fish{synopsis}
+fish_key_reader [-c | --continuous]
+\endfish
+
+\subsection fish_key_reader-description Description
+
+`fish_key_reader` is used to show in a human friendly manner the sequence of characters each key on a keyboard sends. If the sequence of characters matches a key name recognized by the `bind` command that is also displayed. It shows each characters decimal, hexadecimal and symbolic values. It also shows the delay in microseconds since the previous character was received. The timing data is useful for detecting when an intermediary such as ssh or tmux has altered the timing of the characters sent by the keyboard. If at least 0.2 seconds has passed since the previous character the program will insert a blank line in the output. This makes it visually easier to distinguish the sequence of chars sent by a single key press.
+
+By default the program exits after displaying a single key sequence. Specifially, it exits after 0.5 seconds has elapsed without seeing another character after the first character is seen. You can force it to run in a continuous mode by passing the `--continuous` or `-c` flag.
+
+Here is an example of the program in action that also shows how to exit from continuous mode:
+
+```
+$ ./fish_key_reader --continuous
+
+Type 'exit' or 'quit' to terminate this program.
+
+Characters such as [ctrl-D] (EOF) and [ctrl-C] (interrupt)
+have no special meaning and will not terminate this program.
+
+Type 'exit' or 'quit' to terminate this program.
+
+999999 usec  dec:  27  hex: 1b  char: \e (aka \c[)
+   450 usec  dec:  91  hex: 5b  char: [
+   409 usec  dec:  49  hex: 31  char: 1
+   424 usec  dec: 126  hex: 7e  char: ~
+FYI: Found sequence for bind key name "home"
+
+Type 'exit' or 'quit' to terminate this program.
+
+999999 usec  dec: 113  hex: 71  char: q
+111562 usec  dec: 117  hex: 75  char: u
+ 55820 usec  dec: 105  hex: 69  char: i
+128021 usec  dec: 116  hex: 74  char: t
+
+Exiting at your request.
+```
diff --git a/src/fish_key_reader.cpp b/src/fish_key_reader.cpp
new file mode 100644
index 00000000..ef587d3c
--- /dev/null
+++ b/src/fish_key_reader.cpp
@@ -0,0 +1,238 @@
+// A small utility to print information related to pressing keys. This is similar to using tools
+// like `xxd` and `od -tx1z` but provides more information such as the time delay between each
+// character. It also allows pressing and interpreting keys that are normally special such as
+// [ctrl-C] (interrupt the program) or [ctrl-D] (EOF to signal the program should exit).
+// And unlike those other tools this one disables ICRNL mode so it can distinguish between
+// carriage-return (\cM) and newline (\cJ).
+//
+// Type "exit" or "quit" to terminate the program.
+#include <getopt.h>
+#include <locale.h>
+#include <signal.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/time.h>
+#include <termios.h>
+#include <wctype.h>
+#include <string>
+
+#include "common.h"
+#include "env.h"
+#include "fallback.h"  // IWYU pragma: keep
+#include "input.h"
+#include "input_common.h"
+
+struct config_paths_t determine_config_directory_paths(const char *argv0);
+
+static struct termios saved_modes;  // so we can reset the modes when we're done
+static long long int prev_tstamp = 0;
+static const char *ctrl_equivalents[] = {NULL,  NULL,  NULL,  NULL,  NULL,  NULL,  NULL, "\\a",
+    "\\b", "\\t", "\\n", "\\v", "\\f", "\\r", NULL, NULL,
+    NULL,  NULL,  NULL,  NULL,  NULL,  NULL,  NULL, NULL,
+    NULL,  NULL,  NULL,  "\\e", NULL,  NULL,  NULL, NULL};
+
+/// Return true if the recent sequence of characters indicates the user wants to exit the program.
+bool should_exit(unsigned char c) {
+    static unsigned char recent_chars[4] = {0};
+
+    recent_chars[0] = recent_chars[1];
+    recent_chars[1] = recent_chars[2];
+    recent_chars[2] = recent_chars[3];
+    recent_chars[3] = c;
+    return memcmp(recent_chars, "exit", 4) == 0 || memcmp(recent_chars, "quit", 4) == 0;
+}
+
+/// Return the key name if the recent sequence of characters matches a known terminfo sequence.
+char * const key_name(unsigned char c) {
+    static char recent_chars[8] = {0};
+
+    recent_chars[0] = recent_chars[1];
+    recent_chars[1] = recent_chars[2];
+    recent_chars[2] = recent_chars[3];
+    recent_chars[3] = recent_chars[4];
+    recent_chars[4] = recent_chars[5];
+    recent_chars[5] = recent_chars[6];
+    recent_chars[6] = recent_chars[7];
+    recent_chars[7] = c;
+
+    for (int idx = 7; idx >= 0; idx--) {
+        wcstring out_name;
+        wcstring seq = str2wcstring(recent_chars + idx, 8 - idx);
+        bool found = input_terminfo_get_name(seq, &out_name);
+        if (found) {
+            return strdup(wcs2string(out_name).c_str());
+        }
+    }
+
+    return NULL;
+}
+
+/// Process the characters we receive as the user presses keys.
+void process_input(bool continuous_mode) {
+    bool first_char_seen = false;
+    while (true) {
+        wchar_t wc = input_common_readch(first_char_seen && !continuous_mode);
+        if (wc == WEOF) {
+            return;
+        }
+        if (wc > 255) {
+            printf("\nUnexpected wide character from input_common_readch(): %lld / 0x%llx\n",
+                   (long long)wc, (long long)wc);
+            return;
+        }
+
+        long long int curr_tstamp, delta_tstamp;
+        timeval char_tstamp;
+        gettimeofday(&char_tstamp, NULL);
+        curr_tstamp = char_tstamp.tv_sec * 1000000 + char_tstamp.tv_usec;
+        delta_tstamp = curr_tstamp - prev_tstamp;
+        if (delta_tstamp >= 1000000) delta_tstamp = 999999;
+        if (delta_tstamp >= 200000 && continuous_mode) {
+            printf("\n");
+            printf("Type 'exit' or 'quit' to terminate this program.\n");
+            printf("\n");
+        }
+        prev_tstamp = curr_tstamp;
+
+        unsigned char c = wc;
+        if (c < 32) {
+            // Control characters.
+            if (ctrl_equivalents[c]) {
+                printf("%6lld usec  dec: %3u  hex: %2x  char: %s (aka \\c%c)\n", delta_tstamp, c, c,
+                       ctrl_equivalents[c], c + 64);
+            } else {
+                printf("%6lld usec  dec: %3u  hex: %2x  char: \\c%c\n", delta_tstamp, c, c, c + 64);
+            }
+        } else if (c == 32) {
+            // The space character.
+            printf("%6lld usec  dec: %3u  hex: %2x  char: <space>\n", delta_tstamp, c, c);
+        } else if (c == 127) {
+            // The "del" character.
+            printf("%6lld usec  dec: %3u  hex: %2x  char: \\x7f (aka del)\n", delta_tstamp, c, c);
+        } else if (c >= 128) {
+            // Non-ASCII characters (i.e., those with bit 7 set).
+            printf("%6lld usec  dec: %3u  hex: %2x  char: non-ASCII\n", delta_tstamp, c, c);
+        } else {
+            // ASCII characters that are not control characters.
+            printf("%6lld usec  dec: %3u  hex: %2x  char: %c\n", delta_tstamp, c, c, c);
+        }
+
+        char * const name = key_name(c);
+        if (name) {
+            printf("FYI: Saw sequence for bind key name \"%s\"\n", name);
+            free(name);
+        }
+
+        if (should_exit(c)) {
+            printf("\nExiting at your request.\n");
+            break;
+        }
+
+        first_char_seen = true;
+    }
+}
+
+/// Set the tty modes to not interpret any characters. We want every character to be passed thru to
+/// this program. Including characters such as [ctrl-C] and [ctrl-D] that might normally have
+/// special significance (e.g., terminate the program).
+bool set_tty_modes(void) {
+    struct termios modes;
+
+    tcgetattr(0, &modes);  // get the current tty modes
+    saved_modes = modes;   // save a copy so we can reset them on exit
+
+    modes.c_lflag &= ~ICANON;  // turn off canonical mode
+    modes.c_lflag &= ~ECHO;    // turn off echo mode
+    modes.c_lflag &= ~ISIG;    // turn off recognizing signal generating characters
+    modes.c_iflag &= ~ICRNL;   // turn off mapping CR to NL
+    modes.c_iflag &= ~INLCR;   // turn off mapping NL to CR
+    modes.c_cc[VMIN] = 1;      // return each character as they arrive
+    modes.c_cc[VTIME] = 0;     // wait forever for the next character
+
+    if (tcsetattr(0, TCSANOW, &modes) != 0) {  // set the new modes
+        return false;
+    }
+    return true;
+}
+
+/// Restore the tty modes to what they were before this program was run. This shouldn't be required
+/// but we do it just in case the program that ran us doesn't handle tty modes for external programs
+/// in a sensible manner.
+void reset_tty_modes() { tcsetattr(0, TCSANOW, &saved_modes); }
+
+/// Make sure we cleanup before exiting if we're signaled.
+void signal_handler(int signo) {
+    printf("\nExiting on receipt of signal #%d\n", signo);
+    reset_tty_modes();
+    exit(1);
+}
+
+/// Setup our environment (e.g., tty modes), process key strokes, then reset the environment.
+void setup_and_process_keys(bool continuous_mode) {
+    set_main_thread();
+    setup_fork_guards();
+    wsetlocale(LC_ALL, L"POSIX");
+    program_name = L"fish_key_reader";
+    env_init();
+    input_init();
+
+    // Installing our handler for every signal (e.g., SIGSEGV) is dubious because it means that
+    // signals that might generate a core dump will not do so. On the other hand this allows us
+    // to restore the tty modes so the terminal is still usable when we die.
+    for (int signo = 1; signo < 32; signo++) {
+        signal(signo, signal_handler);
+    }
+
+    if (continuous_mode) {
+        printf("\n");
+        printf("Type 'exit' or 'quit' to terminate this program.\n");
+        printf("\n");
+        printf("Characters such as [ctrl-D] (EOF) and [ctrl-C] (interrupt)\n");
+        printf("have no special meaning and will not terminate this program.\n");
+        printf("\n");
+    } else {
+        set_wait_on_escape_ms(500);
+    }
+
+    if (!set_tty_modes()) {
+        printf("Could not set the tty modes. Refusing to continue running.\n");
+        exit(1);
+    }
+    // TODO: We really should enable keypad mode but see issue #838.
+    process_input(continuous_mode);
+    reset_tty_modes();
+}
+
+int main(int argc, char **argv) {
+    bool continuous_mode = false;
+    const char *short_opts = "+c";
+    const struct option long_opts[] = {{"continuous", no_argument, NULL, 'd'}, {NULL, 0, NULL, 0}};
+    int opt;
+    while ((opt = getopt_long(argc, argv, short_opts, long_opts, NULL)) != -1) {
+        switch (opt) {
+            case 0: {
+                fprintf(stderr, "getopt_long() unexpectedly returned zero\n");
+                exit(1);
+            }
+            case 'c': {
+                continuous_mode = true;
+                break;
+            }
+            default: {
+                // We assume getopt_long() has already emitted a diagnostic msg.
+                exit(1);
+            }
+        }
+    }
+
+    argc -= optind;
+    if (argc != 0) {
+        fprintf(stderr, "Expected no CLI arguments, got %d\n", argc);
+        return 1;
+    }
+
+    setup_and_process_keys(continuous_mode);
+    return 0;
+}
diff --git a/src/input_common.cpp b/src/input_common.cpp
index 93e94fd3..405e0d6e 100644
--- a/src/input_common.cpp
+++ b/src/input_common.cpp
@@ -14,6 +14,7 @@
 #include <stdbool.h>
 #include <stdio.h>
 #include <stdlib.h>
+#include <sys/time.h>
 #include <sys/types.h>
 #include <wchar.h>
 #include <wctype.h>
@@ -28,9 +29,9 @@
 #include "iothread.h"
 #include "util.h"
 
-// Time in milliseconds to wait for another byte to be available for reading
-// after \x1b is read before assuming that escape key was pressed, and not an
-// escape sequence.
+/// Time in milliseconds to wait for another byte to be available for reading
+/// after \x1b is read before assuming that escape key was pressed, and not an
+/// escape sequence.
 #define WAIT_ON_ESCAPE_DEFAULT 300
 static int wait_on_escape_ms = WAIT_ON_ESCAPE_DEFAULT;
 
@@ -169,6 +170,9 @@ static wint_t readb() {
     return arr[0];
 }
 
+// Directly set the input timeout.
+void set_wait_on_escape_ms(int ms) { wait_on_escape_ms = ms; }
+
 // Update the wait_on_escape_ms value in response to the fish_escape_delay_ms user variable being
 // set.
 void update_wait_on_escape_ms() {
diff --git a/src/input_common.h b/src/input_common.h
index d7bafe3f..e5778b70 100644
--- a/src/input_common.h
+++ b/src/input_common.h
@@ -85,6 +85,9 @@ void input_common_destroy();
 /// Adjust the escape timeout.
 void update_wait_on_escape_ms();
 
+/// Set the escape timeout directly.
+void set_wait_on_escape_ms(int ms);
+
 /// Function used by input_readch to read bytes from stdin until enough bytes have been read to
 /// convert them to a wchar_t. Conversion is done using mbrtowc. If a character has previously been
 /// read and then 'unread' using \c input_common_unreadch, that character is returned. If timed is
diff --git a/src/key_reader.cpp b/src/key_reader.cpp
deleted file mode 100644
index 0d0b997f..00000000
--- a/src/key_reader.cpp
+++ /dev/null
@@ -1,74 +0,0 @@
-// A small utility to print the resulting key codes from pressing a key. Servers the same function
-// as hitting ^V in bash, but I prefer the way key_reader works.
-//
-// Type ^C to exit the program.
-#include <locale.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include <termcap.h>
-#include <termios.h>
-
-#include "common.h"
-#include "fallback.h"  // IWYU pragma: keep
-#include "input_common.h"
-
-int writestr(char *str) {
-    write_ignore(1, str, strlen(str));
-    return 0;
-}
-
-int main(int argc, char **argv) {
-    set_main_thread();
-    setup_fork_guards();
-    setlocale(LC_ALL, "");
-
-    if (argc == 2) {
-        static char term_buffer[2048];
-        char *termtype = getenv("TERM");
-        char *tbuff = new char[9999];
-        char *res;
-
-        tgetent(term_buffer, termtype);
-        res = tgetstr(argv[1], &tbuff);
-        if (res != 0) {
-            while (*res != 0) {
-                printf("%d ", *res);
-
-                res++;
-            }
-            printf("\n");
-        } else {
-            printf("Undefined sequence\n");
-        }
-    } else {
-        char scratch[1024];
-        unsigned int c;
-
-        struct termios modes,  // so we can change the modes
-            savemodes;         // so we can reset the modes when we're done
-
-        input_common_init(0);
-
-        tcgetattr(0, &modes);  // get the current terminal modes
-        savemodes = modes;     // save a copy so we can reset them
-
-        modes.c_lflag &= ~ICANON;  // turn off canonical mode
-        modes.c_lflag &= ~ECHO;    // turn off echo mode
-        modes.c_cc[VMIN] = 1;
-        modes.c_cc[VTIME] = 0;
-        tcsetattr(0, TCSANOW, &modes);  // set the new modes
-        while (1) {
-            if ((c = input_common_readch(0)) == EOF) break;
-            if ((c > 31) && (c != 127))
-                sprintf(scratch, "dec: %u hex: %x char: %c\n", c, c, c);
-            else
-                sprintf(scratch, "dec: %u hex: %x\n", c, c);
-            writestr(scratch);
-        }
-        tcsetattr(0, TCSANOW, &savemodes);  // reset the terminal to the saved mode
-        input_common_destroy();
-    }
-
-    return 0;
-}