diff --git a/.gitignore b/.gitignore index 2420bb4e5..4f123aeeb 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 6172721e8..4bb0998c1 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 cad467cdc..ee9353021 100644 --- a/build_tools/iwyu.osx.imp +++ b/build_tools/iwyu.osx.imp @@ -83,6 +83,7 @@ { symbol: ["pid_t", "private", "", "public"] }, { symbol: ["uid_t", "private", "", "public"] }, { symbol: ["gid_t", "private", "", "public"] }, + { symbol: ["timeval", "private", "", "public"] }, { symbol: ["uint32_t", "private", "", "public"] }, { symbol: ["uint32_t", "private", "", "public"] }, { symbol: ["intptr_t", "private", "", "public"] }, diff --git a/doc_src/fish_key_reader.txt b/doc_src/fish_key_reader.txt new file mode 100644 index 000000000..9e5afca64 --- /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 000000000..ef587d3c3 --- /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 +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#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: \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 93e94fd3f..405e0d6e4 100644 --- a/src/input_common.cpp +++ b/src/input_common.cpp @@ -14,6 +14,7 @@ #include #include #include +#include #include #include #include @@ -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 d7bafe3fa..e5778b70f 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 0d0b997f4..000000000 --- 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 -#include -#include -#include -#include -#include - -#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; -}