onKeyPress
Custom definable key bindings and macros
While Murex aims to have compatibility with common keyboard shortcuts favoured in other shells, there is still a need for to define your own preferences.
onKeyPress
enables you to write custom key bindings and macros in Murex using Murex’s scripting language.
event onKeyPress name=keystroke { code block }
!event onKeyPress name[.keystroke]
The following payload is passed to the function via stdin:
{
"Name": "",
"Interrupt": {
"Line": "",
"CursorPos": 0,
"KeyPress": "",
"IsMasked": false,
"InputMode": "",
"PreviewMode": ""
}
}
This is the namespaced name – ie the name and operation.
This is the name you specified when defining the event.
The current line as it appears in readline.
Where the text input cursor is sat on the line
The key which was pressed.
If the key stroke is represented by an ANSI escape sequence, then this field will be multiple multiple characters long.
This will be true
if you have a password / input mask (eg *
). Otherwise it will be false
.
This is the input mode of readline. Different input modes will utilise keystrokes differently.
This field is a string and the following constants are supported:
Normal
: regular inputVimKeys
: where input behaves like vim
VimReplaceOnce
: vim
mode, but next keystroke might normally overwrite current characterVimReplaceMany
: vim
mode, but where every keystroke overwrites characters rather than insertsVimDelete
: vim
mode, but where characters are deletedAutocomplete
: the autocomplete menu is shownFuzzyFind
: the autocomplete menu is shown with the Fuzzy Find input enabledMore details about these modes can be found in the Terminal Hotkeys document.
Preview mode is independent to input mode.
Disabled
: preview is not runningAutocomplete
: regular preview modeCmdLine
: command line previewMore details about these modes can be found in the Interactive Shell document.
$EVENT_RETURN
, is a special variable that stores a writable structure to return back to the event caller.
The $EVENT_RETURN
values available for this event are:
{
"Actions": [],
"Continue": false,
"SetCursorPos": 0,
"SetHintText": "",
"SetLine": ""
}
This is an array of strings, each defining a hotkey function to execute after the event function has completed.
You can supply multiple functions in the array.
Supported values are:
package onkeypress
import "github.com/lmorg/murex/utils/readline"
/*
This file was automatically generated by ./actions.mx
DO NOT EDIT THIS FILE DIRECTLY!!
*/
var fnLookup = map[string]func(*readline.Instance){
"CancelAction": readline.HkFnCancelAction,
"ClearAfterCursor": readline.HkFnClearAfterCursor,
"ClearLine": readline.HkFnClearLine,
"ClearScreen": readline.HkFnClearScreen,
"CursorJumpBackwards": readline.HkFnCursorJumpBackwards,
"CursorJumpForwards": readline.HkFnCursorJumpForwards,
"CursorMoveToEndOfLine": readline.HkFnCursorMoveToEndOfLine,
"CursorMoveToStartOfLine": readline.HkFnCursorMoveToStartOfLine,
"ModeAutocomplete": readline.HkFnModeAutocomplete,
"ModeFuzzyFind": readline.HkFnModeFuzzyFind,
"ModePreviewLine": readline.HkFnModePreviewLine,
"ModePreviewToggle": readline.HkFnModePreviewToggle,
"ModeSearchHistory": readline.HkFnModeSearchHistory,
"RecallWord1": readline.HkFnRecallWord1,
"RecallWord10": readline.HkFnRecallWord10,
"RecallWord11": readline.HkFnRecallWord11,
"RecallWord12": readline.HkFnRecallWord12,
"RecallWord2": readline.HkFnRecallWord2,
"RecallWord3": readline.HkFnRecallWord3,
"RecallWord4": readline.HkFnRecallWord4,
"RecallWord5": readline.HkFnRecallWord5,
"RecallWord6": readline.HkFnRecallWord6,
"RecallWord7": readline.HkFnRecallWord7,
"RecallWord8": readline.HkFnRecallWord8,
"RecallWord9": readline.HkFnRecallWord9,
"RecallWordLast": readline.HkFnRecallWordLast,
"Undo": readline.HkFnUndo,
}
This boolean value defines whether to execute other events for the same keypress after this one.
On the surface of it, you might question why you’d wouldn’t want multiple actions bound to the same keypress. However since readline supports different operational modes, you might want different events bound to different states of readline. In which case you’d need to set $EVENT_RETURN.Continue
to true
.
This allows you to shift the text input cursor to an absolute location.
Forces a different message in the hint text.
Change your input line in readline.
The following example will output “Ouch!” when you press {f3}
:
event onKeyPress poke={F3} {
out "Ouch!"
}
The following code will perform two undo’s:
event onKeyPress double-undo={F4} {
$EVENT_RETURN.Actions = %[
Undo
Undo
]
}
The following code will output the operations modes of readline to the hint text:
event onKeyPress status={F5} {
-> set event
$EVENT_RETURN.SetHintText = "Readline input mode is $event.Interrupt.InputMode and preview mode is $event.Interrupt.PreviewMode"
}
Stdout and stderr are both written to the terminal.
Interrupts are run in alphabetical order. So an event named “alfa” would run before an event named “zulu”. If you are writing multiple events and the order of execution matters, then you can prefix the names with a number, eg 10_jump
This event is namespaced as $(NAME).$(OPERATION)
.
For example, if an event in onPrompt
was defined as example=eof
then its namespace would be example.eof
and thus a subsequent event with the same name but different operation, eg example=abort
, would not overwrite the former event defined against the interrupt eof
.
The reason for this namespacing is because you might legitimately want the same name for different operations (eg a smart prompt that has elements triggered from different interrupts).
event
): Event driven programming for shell scriptsconfig
): Query or define Murex runtime settingsonCommandCompletion
: Trigger an event upon a command’s completiononPreview
: Full screen previews for files and command documentationonPrompt
: Events triggered by changes in state of the interactive shellThis document was generated from builtins/events/onKeyPress/onkeypress_doc.yaml.
This site's content is rebuilt automatically from murex's source code after each merge to the master
branch. Downloadable murex binaries are also built with the website.
Last built on Wed Sep 18 21:18:57 UTC 2024 against commit c037883c03788357164e9846c84d9f777251495d9452a8e.
Current version is 6.3.4225 (develop) which has been verified against tests cases.