andyk / ht

headless terminal - wrap any binary with a terminal interface for easy programmatic access.
Apache License 2.0
746 stars 12 forks source link

Better keyboard input API #10

Closed ku1ik closed 1 week ago

ku1ik commented 1 week ago

This PR brings greatly improved keyboard input support, with the new sendKeys command (inspired by tmux).

From the updated README:


sendKeys command allows sending keys to a process running in the virtual terminal as if the keys were pressed on a keyboard.

{ "type": "sendKeys", "keys": ["nano", "Enter"] }
{ "type": "sendKeys", "keys": ["hello", "Enter", "world"] }
{ "type": "sendKeys", "keys": ["^x", "n"] }

Each element of the keys array can be either a key name or an arbitrary text. If a key is not matched by any supported key name then the text is sent to the process as is, i.e. like when using the input command.

This command doesn't produce any output on stdout.

The following key specifications are currently supported:

Modifier keys are supported by prepending a key with one of the prefixes:

Modifiers can be combined (for arrow keys only at the moment), so combinations such as S-A-Up or C-S-Left are possible.

C- control modifier notation can be used with ASCII letters (both lower and upper case are supported) and most special key names. The caret control notation (^) may only be used with ASCII letters, not with special keys.

Shift modifier can be used with special key names only, such as Left, PageUp etc. For text characters, instead of specifying e.g. S-a just use upper case A.

Alt modifier can be used with any Unicode character and most special key names.


I also updated the description of the existing input command, stating it's a more lower level, raw input mode.

Thing to consider: use angle brackets for special keys, e.g. <Enter> instead of Enter. Key names are matched unambiguously already, thanks to the sendKeys arg being an array, so technically using angle brackets wouldn't make it work any better. This would just look nicer (?) for us humans I guess. But not sure :)

andyk commented 1 week ago

LGTM. This is awesome - and I'm excited to use it. Since folks approaching the project might wonder how you chose the notation, can you add a sentence (and maybe a link) saying where we copied the notation from (tmux right)?