feat: add support for custom keybindings and editor actions in the REPL

[Snehil-Shah]

Towards #2647.

Description

What is the purpose of this pull request?

This pull request:

• adds editor actions
• adds support for custom keybindings
• make existing actions configurable
• adds settings, APIs and update docs

Related Issues

Does this pull request have any related issues?

This pull request:

• partially resolves [RFC]: add support for custom key bindings in the REPL #2647

Questions

Any questions for reviewers of this pull request?

For the sake of user experience, I decided the key object can have 4 properties: name, ctrl, shift, and meta. In actuality, a readline key object also has properties like sequence and code, which mainly contain the escape sequence of the keypress.

In most keypresses, the name, ctrl, shift, and meta properties are correctly emitted and are enough to determine the action we have to trigger. But in some cases, for instance, CTRL+/, instead of emitting an event with { 'name': '/', 'ctrl': true }, it emits a sequence { 'sequence': '\x1f' }. So if a user has keybindings with CTRL+/ as the key, it won't work, as such a keypress is never emitted.

Now such cases might be limited, as readline only uses the sequence prop to identify two keypress actions, namely undo and redo.
Maybe we can handle these two special cases manually in code? Not sure if a robust solution exists.

Ofcourse, we can also punt the entire responsibility of giving the readline-ready key object, onto the user, but that's not user friendly IMO.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

---

@stdlib-js/reviewers

[Snehil-Shah]

Another solution to the problem in OP is, we can expect the user to give us the ASCII sequence of the keypress instead.

Every keypress will always have a sequence prop unlike name, ctrl, shift and meta.

Now this is not user-friendly as the user is expected to know the control sequence of the keypress they are wanting to assign.

So, another approach would be to maintain a table mapping all possible keybindings to their corresponding emitted control sequences. Something like:

const CONTROL_SEQUENCES = {
    '\x01': 'Ctrl+A',
    '\x02': 'Ctrl+B',
    '\x03': 'Ctrl+C',
    '\x04': 'Ctrl+D',
    '\x05': 'Ctrl+E',
    '\x06': 'Ctrl+F',
    '\x07': 'Ctrl+G',
    '\x08': 'Ctrl+H',
    '\x09': 'Ctrl+I',
    '\x0A': 'Ctrl+J',
    '\x0B': 'Ctrl+K',
    '\x0C': 'Ctrl+L',
    '\x0D': 'Ctrl+M',
    '\x0E': 'Ctrl+N',
    '\x0F': 'Ctrl+O',
    '\x10': 'Ctrl+P',
    '\x11': 'Ctrl+Q',
    '\x12': 'Ctrl+R',
    '\x13': 'Ctrl+S',
    '\x14': 'Ctrl+T',
    '\x15': 'Ctrl+U',
    '\x16': 'Ctrl+V',
    '\x17': 'Ctrl+W',
    '\x18': 'Ctrl+X',
    '\x19': 'Ctrl+Y',
    '\x1A': 'Ctrl+Z'
};

But not sure if control sequences and their corresponding keys are standardized across emulators..?
How should we proceed?

[Snehil-Shah]

https://github.com/nodejs/node/blob/main/lib/internal/readline/utils.js#L59

readline parses some keys based on xterm and gnome emulator behaviors (I guess). Maybe we can enforce xterm standards to parse keys? I suppose most combinations might emit standardized sequences..(?)

[Planeshifter]

@Snehil-Shah Not requiring providing a sequence was the right call, I think, given that asking users to know or look up the control sequences for keybindings they want is undesirable. The current approach of a key object with Boolean modifier properties seems good; we could consider renaming meta to alt, as that the latter be understood by more people maybe?

Enforcing xterm standards for key parsing could be feasible. xterm is widely used and AFAIK many terminal emulators aim for compatibility with xterm, so this sounds worth investigating.

I also do think that it would be a pragmatic choice to handle the undo and redo special cases separately.

[Snehil-Shah]

Now if we decide to go ahead and enforce xterm control sequences, we also have the flexibility to change the input format the user can give. So we can have something like the string "CTRL-E" as input, and map this to the corresponding xterm control sequence..

[Snehil-Shah]

Went ahead and added parsing of unrecognized keypresses. Fortunately, there were not many cases to cover, the above problems were mainly around keys involving symbols.

@Planeshifter I think it would be better to stick to meta as the internal readline key object, also uses it. This makes it easier to map keybindings. And julia also uses meta instead of alt in their naming so we're not alone.

[Planeshifter]

Looks good to me!

One small comment: I believe we can safely assume that _rli.line is a string, correct? Hence, we could use the base package equivalents, so e.g. @stdlib/string/base/uppercase instead of @stdlib/string/uppercase, to bypass runtime argument validation of these functions.

[Snehil-Shah]

@Planeshifter Makes sense..

[kgryte]

we could use the base package equivalents

We should go ahead and make those changes. Too easy to forget to do them later.

[kgryte]

Deep equality could be an expensive check. Is there a potential lighter weight means?

[kgryte]

Given that we know the keys, can we not write a small custom function which explicitly compares known keys?

[Snehil-Shah]

For two keys to be equal, their four properties should be equal (name, ctrl, meta, shift). Wouldn't deep equality do just that?

[kgryte]

Yes, but it is the difference between comparing values having an unknown schema and those having a known schema. For the former, you need to dynamically resolve the list of keys and then iterate. For the latter, you can skip resolution and directly compare without iteration. It is something of a micro-optimization, but my main concern is preventing lag, especially as we continue to add various keystroke listeners.

[Snehil-Shah]

Makes sense. I'll make a helper function, or better, a module like containsKeys which will take an array of possible keybindings (as one action has multiple keybindings set) and the user input key.

[kgryte]

Seems reasonable.

[kgryte]

These types seem off. Is key an object or a string? And it is not obvious that the function can return a boolean.

[kgryte]

Okay. parseMetaSymbolSequence can return a boolean. Would it make more sense to make the types consistent? For example, return an empty array? Alternatively, rather than a boolean, it is more common for us to return null.

[Snehil-Shah]

I forgot to update the jsdoc, sorry for the confusion. Yes, the main parse_key function doesn't return a boolean.

I updated parseMetaSymbolSequence to return null instead. If it returns null means it's not a meta symbol sequence. So we just return the original key object.

Should parseMetaSymbolSequence return an empty array? The only problem would be, we won't be able to check directly if it returned a sequence or not (using if ( out )) but would have to check if the array is empty. null should be fine(?).

[kgryte]

Is there an issue with checking out.length > 0? I suppose I am not sure why null would be preferred over checking the length of the returned array.

[kgryte]

@Planeshifter and I were not able to get indentation to work.

[Snehil-Shah]

Just tried and it's highly likely it's clashing with your terminal's internal keybindings (that's the case with me, ALT+RIGHT is vscode terminal's internal binding). Just change the keybinding to something unoccupied and it should work.

[kgryte]

I wonder how we should publicly document these keybindings. As @Planeshifter and I experienced, not all the default keybindings work (e.g., due to a terminal's internal keybindings). I can already imagine getting bug reports for when keybindings don't work, but this is because a user is unaware that some other application has already laid claim to a particular keybinding.

[kgryte]

Should all of these keybindings work or just one of them?

[Snehil-Shah]

All of them should work. The user can set multiple keybindings to trigger a single action.

[kgryte]

It was often the case that only one of the keybindings worked. I suppose it is possible that there are conflicts happening somewhere so that not able to see intended changes.

[kgryte]

This also doesn't work for me.

[Snehil-Shah]

Is this comment also for the indentation?

[kgryte]

Yes, meaning same as indentLineLeft for me, as neither worked.

[kgryte]

Thanks, @Snehil-Shah, for working this. I think this PR is pretty close to merge. Just left a few small questions, and @Planeshifter and I were not able to get indentation to work.

[kgryte]

Maybe we can handle these two special cases manually in code? Not sure if a robust solution exists

@Snehil-Shah I'll defer to your judgement on that.