Skip to main content


Laurence MorganAbout 3 min


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 input
  • VimKeys: where input behaves like vim
  • VimReplaceOnce: vim mode, but next keystroke might normally overwrite current character
  • VimReplaceMany: vim mode, but where every keystroke overwrites characters rather than inserts
  • VimDelete: vim mode, but where characters are deleted
  • Autocomplete: the autocomplete menu is shown
  • FuzzyFind: the autocomplete menu is shown with the Fuzzy Find input enabled

More details about these modes can be found in the Terminal Hotkeys document.


Preview mode is independent to input mode.

  • Disabled: preview is not running
  • Autocomplete: regular preview mode
  • CmdLine: command line preview

More details about these modes can be found in the Interactive Shell document.

Event Return

$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 ""

   This file was automatically generated by ./

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.


Arbitrary code execution

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 = %[

Readline Modes

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"


Standard out and error

Stdout and stderr are both written to the terminal.

Order of execution

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).

See Also

  • Interactive Shell: What's different about Murex's interactive shell?
  • Terminal Hotkeys: A list of all the terminal hotkeys and their uses
  • config: Query or define Murex runtime settings
  • event: Event driven programming for shell scripts
  • onCommandCompletion: Trigger an event upon a command's completion
  • onPreview: Full screen previews for files and command documentation
  • onPrompt: Events triggered by changes in state of the interactive shell

This document was generated from builtins/events/onKeyPress/onkeypress_doc.yamlopen in new window.

Last update:
Contributors: Laurence Morgan