zsh: Keymaps

Next: Zle Builtins, Up: Zsh Line Editor [Contents][Index]

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

Next: Zle Builtins, Up: Zsh Line Editor [Contents][Index]