18.2 Keymaps

A keymap in ZLE contains a set of bindings between key sequences and ZLE commands. The empty key sequence cannot be bound.

There can be any number of keymaps at any time, and each keymap has one or more names. If all of a keymap’s names are deleted, it disappears. bindkey can be used to manipulate keymap names.

Initially, there are eight keymaps:

emacs

EMACS emulation

viins

vi emulation - insert mode

vicmd

vi emulation - command mode

viopp

vi emulation - operator pending

visual

vi emulation - selection active

isearch

incremental search mode

command

read a command name

.safe

fallback keymap

The ‘.safe’ keymap is special. It can never be altered, and the name can never be removed. However, it can be linked to other names, which can be removed. In the future other special keymaps may be added; users should avoid using names beginning with ‘.’ for their own keymaps.

In addition to these names, either ‘emacs’ or ‘viins’ is also linked to the name ‘main’. If one of the VISUAL or EDITOR environment variables contain the string ‘vi’ when the shell starts up then it will be ‘viins’, otherwise it will be ‘emacs’. bindkey’s -e and -v options provide a convenient way to override this default choice.

When the editor starts up, it will select the ‘main’ keymap. If that keymap doesn’t exist, it will use ‘.safe’ instead.

In the ‘.safe’ keymap, each single key is bound to self-insert, except for ^J (line feed) and ^M (return) which are bound to accept-line. This is deliberately not pleasant to use; if you are using it, it means you deleted the main keymap, and you should put it back.

18.2.1 Reading Commands

When ZLE is reading a command from the terminal, it may read a sequence that is bound to some command and is also a prefix of a longer bound string. In this case ZLE will wait a certain time to see if more characters are typed, and if not (or they don’t match any longer string) it will execute the binding. This timeout is defined by the KEYTIMEOUT parameter; its default is 0.4 sec. There is no timeout if the prefix string is not itself bound to a command.

The key timeout is also applied when ZLE is reading the bytes from a multibyte character string when it is in the appropriate mode. (This requires that the shell was compiled with multibyte mode enabled; typically also the locale has characters with the UTF-8 encoding, although any multibyte encoding known to the operating system is supported.) If the second or a subsequent byte is not read within the timeout period, the shell acts as if ? were typed and resets the input state.

As well as ZLE commands, key sequences can be bound to other strings, by using ‘bindkey -s’. When such a sequence is read, the replacement string is pushed back as input, and the command reading process starts again using these fake keystrokes. This input can itself invoke further replacement strings, but in order to detect loops the process will be stopped if there are twenty such replacements without a real command being read.

A key sequence typed by the user can be turned into a command name for use in user-defined widgets with the read-command widget, described in Miscellaneous below.

18.2.2 Local Keymaps

While for normal editing a single keymap is used exclusively, in many modes a local keymap allows for some keys to be customised. For example, in an incremental search mode, a binding in the isearch keymap will override a binding in the main keymap but all keys that are not overridden can still be used.

If a key sequence is defined in a local keymap, it will hide a key sequence in the global keymap that is a prefix of that sequence. An example of this occurs with the binding of iw in viopp as this hides the binding of i in vicmd. However, a longer sequence in the global keymap that shares the same prefix can still apply so for example the binding of ^Xa in the global keymap will be unaffected by the binding of ^Xb in the local keymap.