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
This commit is contained in:
Kurtis Rader 2016-05-06 21:22:28 -07:00
parent fcbeddc3eb
commit 098f6d01c4
7 changed files with 319 additions and 128 deletions

1
.gitignore vendored
View File

@ -21,6 +21,7 @@ doc_src/commands.hdr
doc_src/index.hdr
po/*.gmo
fish
fish_key_reader
fish_indent
fish_tests
fish.pc

View File

@ -129,7 +129,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)
#
@ -189,8 +189,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
@ -836,9 +835,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 $@
@ -909,7 +910,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
@ -1025,11 +1026,11 @@ obj/input.o: src/event.h src/output.h
obj/intern.o: config.h src/fallback.h src/signal.h src/common.h src/intern.h
obj/io.o: config.h src/fallback.h src/signal.h src/wutil.h src/common.h
obj/io.o: src/exec.h src/io.h
obj/iothread.o: config.h src/iothread.h src/common.h src/fallback.h
obj/iothread.o: src/signal.h
obj/key_reader.o: config.h src/common.h src/fallback.h src/signal.h
obj/key_reader.o: src/input_common.h
obj/kill.o: config.h src/fallback.h src/signal.h src/kill.h src/common.h
obj/iothread.o: src/signal.h src/iothread.h src/common.h config.h
obj/iothread.o: src/fallback.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
obj/output.o: src/output.h src/color.h

View File

@ -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.
```

238
src/fish_key_reader.cpp Normal file
View File

@ -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;
}

View File

@ -5,7 +5,6 @@ Implementation file for the low level input library
*/
#include "config.h"
#include <string.h>
#include <errno.h>
#include <sys/time.h>
@ -18,19 +17,27 @@ Implementation file for the low level input library
#ifdef HAVE_SYS_SELECT_H
#include <sys/select.h>
#endif
#include "fallback.h" // IWYU pragma: keep
#include "util.h"
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/time.h>
#include <sys/types.h>
#include <wchar.h>
#include <wctype.h>
#include <cwctype>
#include <memory>
#include "common.h"
#include "fallback.h" // IWYU pragma: keep
#include "input_common.h"
#include "env_universal_common.h"
#include "env.h"
#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;
@ -212,10 +219,12 @@ static wint_t readb()
return arr[0];
}
// 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()
{
// 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() {
env_var_t escape_time_ms = env_get_string(L"fish_escape_delay_ms");
if (escape_time_ms.missing_or_empty())
{

View File

@ -94,15 +94,14 @@ void input_common_destroy();
// Adjust the escape timeout.
void update_wait_on_escape_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 true, readch2 will wait at most
WAIT_ON_ESCAPE milliseconds for a character to be available for
reading before returning with the value WEOF.
*/
/// 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
/// true, readch2 will wait at most WAIT_ON_ESCAPE milliseconds for a character to be available for
/// reading before returning with the value WEOF.
wchar_t input_common_readch(int timed);
/**

View File

@ -1,97 +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 "config.h"
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <termios.h>
#include <unistd.h>
#include <locale.h>
#include <termcap.h>
#include "common.h"
#include "fallback.h"
#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);
}
/* reset the terminal to the saved mode */
tcsetattr(0,TCSANOW,&savemodes);
input_common_destroy();
}
return 0;
}