Ideas for Customizing Keybinds

[tiymat]

Hi all,
I'd like to kick some ideas around and solicit feedback on the topic of supporting the ability to configure custom keybinds in Murex. I started looking into writing a PR to do this, but it quickly became clear that there are a lot of high-level questions that don't necessarily have clear answers.

---

Background

Currently, Murex supports a number of keybinds. These can do everything from modifying the text and cursor in the command prompt to navigating and controlling Murex's features and utilities. Unless I've missed it, there's currently no mechanism by which these keybinds can be customized by the user.

The existing keybinds do seem to do a good job of making users accustomed to Bash/Readline comfortable. But no configuration will work for all users. Subjectively, having to learn new keybinds when you switch software rather than being able to reuse the ones you're already comfortable with can be a big source of friction. Speaking personally, the first ever issue I opened in this repo was a request to add keybinds I was used to in other shells.

---

Survey of Other Shells

While Bash/Readline might be familiar, I was curious how others handle keybinds, so I took a look at some more recent shells. Of course, these shells may have communities, use cases, and design philosophies that differ from Murex's, but they can still provide us with some ideas. I don't claim to be an expert on any of these shells, I just gathered this information from a quick look at their docs.

Fish

Fish provides a bind command that supports mode-aware keybindings.
The key that triggers a binding is defined by a fish escape sequence.
Additionally, fish provides a neat builtin called fish_key_reader that captures a key sequence and tells you how it's represented as a fish escape sequence, and what bindings (if any) are currently mapped to that sequence.
Key sequences can be mapped to normal shell commands/functions, but also to a special set of functions mostly relating to manipulating the cursor/text in the prompt, analogous to Murex's hotkey_functions.go.
Reference

Elvish

Elvish comes with a readline-binding module providing readline keybinds which is not turned on by default but can be enabled with the command use readline-binding.
Keys may be mapped to code blocks.
Keys are expressed as a character (e.g. k) or function key (e.g. F1, Right, PageUp), optionally prefixed by a modifier (e.g. A-, Alt-, S-, Shift-).
Keybindings can be edited with a command of the following form (where "insert" is the mode in which the keybinding should apply) set edit:insert:binding[Alt-x] = { exit }
Keybinds can be made across all modes as well in $edit:global-binding.
Reference

Nushell

Keybindings in Nushell can be set in a config file, also with per-mode specificity. Each keybinding contains the following elements

• Name: A distinct name for the binding
• Keycode: The pressed key
• Modifier: e.g. control, alt_shift, none, etc.
• Mode: Any combination of emacs, vi_insert, and vi_normal
• Event: Defines the behaviour when the keybinding is invoked. Supports executing commands and manipulating prompt text, among other options.

Reference

Oil

Oil appears to use Readline.

Zsh

Okay, although I said I was looking at shells newer than Bash, this still technically counts, having been released one year later! 😆
Zsh key bindings can be managed with the bindkey builtin.
Keys can be described in multiple notations (e.g. caret notation, escape sequences, Unicode).
Keys can be bound to ZLE (ZSH's Readline equivalent) widgets or strings. ZLE provides widgets to manipulate the cursor/text in the prompt (e.g. backward-kill-word, up-line-or-history), and supports user-defined widgets to run shell commands. Binding a key to a string can also be used to run commands, e.g. by making the string the name of a command followed by a newline character.
Reference 1
Reference 2

---

Questions About Murex Keybinds

With these other implementations in mind, we can now turn to how some of these features might be implemented in Murex.

In my opinion, the config builtin seems to be a natural way to implement custom keybinds in Murex. Maybe a new app in config called keys could be added. If we were to take this approach, though, I'm not entirely sure how the JSON would be structured.
One approach would be to have an object with some kind of representation of the key+modifier as its keys, and code blocks to execute as its values.

{
"Ctrl-x": "{ exit }",
"Ctrl-Alt-v": "{ version --no-app-name }",
}

Another would be some kind of list, e.g.

[ {
"key": "Ctrl-x",
"command": "{ exit }"
},
{
"key": "Ctrl-Alt-v",
"command": "{ version --no-app-name }"
} ]

but this seems like it would have the disadvantage of being more difficult to query. If you're looking for a specific keybind using the first format, it's just a lookup for the key. But using the second format, you'd have to iterate over the list checking each object to see if the key matches.

Another wrinkle is modes, or the ability for a keybind to do different things in different contexts. Using the first format, you'd have to bake the mode into the key somehow, whereas with the second format you could just add a "mode" key to each object to specify the mode(s) for which the keybind is active. While Murex doesn't seem to use the term mode in the same was as most of the other shells we looked at, it does have different contexts where we might want keybinds to do different things. For example, we might want Tab to do one thing while autocompleting a command, and another when the F9 command line preview is open.

Still another question is what do we want to allow users to do when a keybind is pressed. Presumably they could bind a key to a code block or function, but it also seems desirable for them to have some ability to access the functions in hotkey_functions.go. Is there any other functionality we want to expose to them?

---

Conclusion

This turned out much longer than expected but I hope it might provoke some thought and discussion about keybinds. Thanks for reading!

[lmorg]

Coincidentally, just this week I pushed an update to develop which adds support for events to return data back to the caller function. This was the missing link Murex needed to properly support redefining keys.

I'll share more on what that might look like when I get time later today.

[lmorg]

Sorry for going quiet. It's been a busy week at work and home. Anyhow, the topic at hand.

The solution I'm proposing is this one, instead of having a flat and rigid config file, instead having it a native part of Murex's event system. For example:

event onKeyPress example={F1} {
    $.Actions = %[ CursorStartOfLine ]
}

yeah that's verbose, but it doesn't create yet another different way of configuring the shell. Plus it means you can get a little more clever, for example, if you want this hotkey to also apply a message to the hint text:

event onKeyPress example={F1} {
    # return a 2001 Space Odyssey reference if today is Monday
    # otherwise move the cursor to the start of the line

    if { datetime( --in {now} --out "{py}%A" ) == "Monday" } then {
        $.HintText = "I'm sorry $USER, I'm afraid I can't do that"

    } else {
        $.Actions  = %[ CursorStartOfLine ]
    }
}

You can also chain actions, eg

event onKeyPress example={F1} {
    $.Actions  = %[
        CursorStartOfLine
        ClearHelpters
    ]
}

---

config is another option, but personally I think event would be easier to wrangle this.

[lmorg]

I've been thinking about your "modes" comment quite a bit this week. Murex does have a concept of modes, but several different modes can be true in parallel:

Line editing mode

• Regular input
• VIM keys

Autocompletion mode

• no autocompletion menu
• regular autocompletion (can be a list or grid)
• fuzzy search autocompletion

Preview mode

• no preview mode
• item preview (like command tips or file preview)
• command line preview

There are some limitations, like fuzzy search doesn't support VIM keys, but by and large any of those 3 modes could be in any of their respective states at any one time. So I'm not sure the best way to surface to complexity to the event in a way that doesn't create burden on the individual writing their event.

The initial thought was I can surface a JSON structure that's easy to inspect, looking something like:

"Modes": {
    "LineEditing":    "Regular"  | "VimKeys",
    "Autocompletion": "Disabled" | "Enabled" | "Fuzzy",
    "Preview":        "Disabled" | "Item"    | "CommandLine"
}

So you could inspect it like:

if { $.Modes.Preview } then {
    # only bind key if in preview mode
}

[tiymat]

Thanks for the detailed response! So if I'm understanding right, in this example you gave with a list of actions,

event onKeyPress example={F1} {
    $.Actions = %[ CursorStartOfLine ]
}

the content of $.Actions is a list that can contain functions from onKeyPress/actions_autogenerated.go. Could it also contain code blocks like this?

event onKeyPress example={F1} {
    $.Actions = %[ CursorStartOfLine, ${ out "F1 pressed!" } ]
}

Would the readline/cursor actions only be available in the context of the keypress event?

Also, when I was playing around with what's on develop at the moment, I noticed that defining a keypress event when one already existed for the same key would silently overwrite the existing one (or at least, the old one would not appear in runtime --events -> ["onKeyPress"] after adding the new one.) How would this work if e.g. a user defines a keyPress event for a specific key in their .murex_profile, and then a module they have redefines the onKeyPress for that key?

IMO in that case it might be a good idea to print some kind of warning to stderr about redefining an existing key?

[lmorg]

The whole event block is a code block. eg

event onKeyPress example={F1} {
    $.Actions = %[ CursorStartOfLine ]
    out "F1 pressed!"
}

The gotchya here is that $.Actions happens after the event has finished rather than at the point it is defined. So in the above code, out happens before CursorStartOfLine.

In hindsight that's going to be a surprise to people. so perhaps instead of calling actions_autogenerated.go via $.Actions, it should be a builtin command, eg event state %{ Actions: [ CursorStartOfLine ] }

eg

event onKeyPress example={F1} {
    event state %{
        Actions: [ CursorStartOfLine ]
    }
    out "F1 pressed!"
}

[lmorg]

Regarding support for multiple events to be binded to a single key, that's something very easy to fix. There code was actually purposely written to prevent that because, basically, there wasn't any need for that originally. But I can easily change that code to now support multiple events per key binding. Just like most other events support multiple events per interrupt.

[tiymat]

That's a potential gotcha for sure! Maybe another approach could be requiring modifications to $.Actions to occur at the end of the event's code block if they occur at all, which would reinforce the idea that they happen after the event?

As to multiple events per binding, I guess then my question would be whether there would be some guarantee that the order different events for the same binding are invoked in will be consistent. But the more I think about it the more I guess it doesn't matter, since if you have commands that you want to ensure are run sequentially, you could just move them to the same event.

[lmorg]

That's a potential gotcha for sure! Maybe another approach could be requiring modifications to $.Actions to occur at the end of the event's code block if they occur at all, which would reinforce the idea that they happen after the event?

That's not really possible to enforce with the current parser and to be honest I'd prefer it wasn't enforced too because there might be different values for $.Actions depending on branching on conditionals.

As to multiple events per binding, I guess then my question would be whether there would be some guarantee that the order different events for the same binding are invoked in will be consistent. But the more I think about it the more I guess it doesn't matter, since if you have commands that you want to ensure are run sequentially, you could just move them to the same event.

This isn't an issue because we already have precedence in Murex of handling multiple functions per an event: https://murex.rocks/events/onprompt.html#order-of-execution

[tiymat]

I like your approach to adding modes as a meta variable -- it adds a lot of configuration power to the event without being overly complex. My only question would be are onKeyPress events able to change the mode themselves, and if so would that be done by manipulating the meta variable? e.g. set $.Modes.Preview="Disabled"?

[lmorg]

Sorry for spamming but I've been giving this a little more thought, and the more I think about it the harder it is for me to think of a scenario where it would matter if $.Actions[] wasn't processed at the end of the function.

eg

$.Actions[ PreviewClose ]
$.SetHintText "F1 pressed"

does it really matter here which order things are run? Is there any scenario where it might matter? I can't think of any.

So I'm very tempted to continue with the existing code where $. values are processed at the end of the function:

1. because that code has already been written
2. because creating custom code to process it on change is proving more bothersome than I hoped

And at least following this paradigm, I can pivot the code to apply actions upon change (rather than at the end of the function) in a later release if any use cases do arise.

Do you think that's a fair approach? Or can you think of some scenarios where the current behaviour could produce unexpected results?

[tiymat]

Sorry I haven't been following this discussion lately -- it's been a busy week.

You're right that it's difficult to think of a realistic situation where the fact that $Actions occurs at the end matters. I'm looking at actions_autogenerated trying to contrive such an example. Perhaps something like this?

event onKeyPress example={F3} {
    $.Actions = %[ ClearScreen ]
    ls
}

The user might expect the screen to be cleared and ls's output to be visible on an otherwise empty screen, but instead ClearScreen would occur after ls so there would just be a blank screen, if I'm understanding correctly.

That said, one could take the position that as long as that behaviour is well documented (and presumably the user would be looking at the documentation in the first place if they know about $.Actions) it's not the worst thing in the world, especially if the other approaches would be difficult to implement/maintain.

[lmorg]

Interesting example. Normally I'd have associated that as being a function, eg

function example {
    clear
    ls
}

...but what if they want a hotkey to perform that role? There's no support for that in Murex at the moment.

So I guess it does come back to needing those actions to be immediate

[tiymat]

Hmm, well now I'm wondering, is there a reason

event onKeyPress example={F3} {
    clear
    ls
}

wouldn't work? All the examples I could think of where it could be surprising that actions were evaluated after everything else involved the ClearScreen action, which I guess generally will have commands that can be used to accomplish it (clear on most Linux systems and apparently cls on Windows.) Is your concern that that behaviour would be reliant on external packages and so there wouldn't technically be a built-in pure Murex way of accomplishing it?

[lmorg]

Good point that clear / cls really should be a command action rather than $.Action[], if just because $.Action[]s should only affect the operation of the readline interface rather than the wider terminal.

Your point about whether clear should be a builtin is also an interesting one. At one time clear was aliased to cls on Windows builds but that was removed when I decided to drop the idea reinventing coreutils for Windows users because that would clearly have been a massive undertaking. However it might still be worth making an exception for clear given how basic a tool it is.

Coming back to the original question, it might be worth me just getting the working event into develop with $.Actions[] running at the end of the function and we can try a few experiments with it to see how well it works in practice.

[lmorg]

First working prototype has been pushed to develop.

No documentation yet

[tiymat]

Awesome! I'll play around with it tomorrow and see how it goes

[tiymat]

Hmm, not sure if I'm doing something wrong, I have

event onKeyPress f2test={F2} {
    out "f2"
}

but can't seem to get the event working with the latest on develop. version --no-app-name gives 6.1.7210. I've tried with a few other keys and no luck. Using the show_key kitten I get \x1bOQ when I press F2, which I believe is correct, so the signal should at least be reaching my terminal.

[lmorg]

F1 to F4 are a little bit weird because there are a few different escape sequences for those same keys depending on what terminal you emulate. These days most terminal emulators are basically emulating xterm rather than a hardware terminal, and xterm used to have F1->F4 based on the VT220 because F5->F20 were all VT220 functions too. But xterm later switched to VT100. I don't know why they changed but I'm sure there was a logical reason for it.

Anyway, long story short, Murex currently uses VT220 codes for F1->F4 like xterm used to. However this doesn't seem to work with most terminal emulators I tested on. Whereas {F2-VT100} will. I am planning on remapping {F2} to be the same as `{F2-VT100} though.

---

There's a new builtin that helps here too, key-code:
https://dev.murex.rocks/commands/key-code.html

[lmorg]

Actually, I'll just make the VT100/220 f-key change now... dfd2370

[lmorg]

@tiymat

I'm having second thoughts about using $. for return. I'd forgotten that the meta variable gets overwritten by some builtins such as foreach.

This could lead to some unexpected edge cases like in the following contrived example:

event onKeyPress contrived_example={F1} {
    -> set event
    $.SetHintText = "This is a contrived example"

    $event.Interrupt.CmdLine -> jsplit " " -> foreach word {
        # $. has been overwritten by `foreach`
    }

    # event now fails because $. isn't in the correct format
}

An easy solution to this is to use a different variable name, eg $EVENT_RETURN / $RETURN or something of that ilk. But something about this approach makes be feel a little uneasy -- it feels like these magic variables violates what little functional design the language has left.

You can workaround the above problem with something like

event onKeyPress contrived_example={F1} {
    -> set event

    $EVENT_RETURN = $.
    $EVENT_RETURN.SetHintText = "This is a contrived example"

    $event.Interrupt.CmdLine -> jsplit " " -> foreach word {
        # $. has been overwritten by `foreach`
    }

    $. = $EVENT_RETURN
}

...basically assigning $. to a placeholder variable and then assigning that back to $. at the end of the event. But this is a nasty hack that is non-obvious.

Plus if I'm expecting users to do that then I might as well just make that variable special to begin with. eg $RETURN.SetHintText = "example"

---

The other option is to scrap using variables entirely and write to a named pipe. But I think that just creates new problems too.

[tiymat]

I understand your qualms with creating a special $EVENT_RETURN variable, but at the end of the day maybe that's the approach with the fewest side-effects/special logic.

I'm not too familiar with how meta variables are used elsewhere in the codebase, but my understanding was that in the case of foreach the only key that is used is $.i? Would one option be to merge that onto the existing meta variable if it exists?

e.g.

event onKeyPress contrived_example={F1} {
    -> set event
    # $ has SetHintext, Actions, etc., but not i
    $.SetHintText = "This is a contrived example"

    $event.Interrupt.CmdLine -> jsplit " " -> foreach word {
        # $ has SetHintText, Actions, etc., and i
    }

    # $ has SetHintText, Actions, etc., and i
}

I definitely agree that having some kind of special <event> pipe feels out of place.

[lmorg]

@tiymat I've gone with $EVENT_RETURN. Latest code is in develop. I'm hoping to release in the next couple of days. Just tarting up the documentation first.

https://dev.murex.rocks/events/onkeypress.html