diff options
Diffstat (limited to 'Doc/zshzle.1')
| -rw-r--r-- | Doc/zshzle.1 | 2815 |
1 files changed, 2815 insertions, 0 deletions
diff --git a/Doc/zshzle.1 b/Doc/zshzle.1 new file mode 100644 index 000000000..23708d55d --- /dev/null +++ b/Doc/zshzle.1 @@ -0,0 +1,2815 @@ +.TH "ZSHZLE" "1" "February 14, 2020" "zsh 5\&.8" +.SH "NAME" +zshzle \- zsh command line editor +.\" Yodl file: Zsh/zle.yo +.SH "DESCRIPTION" +If the \fBZLE\fP option is set (which it is by default in interactive shells) +and the shell input is attached to the terminal, the user +is able to edit command lines\&. +.PP +There are two display modes\&. The first, multiline mode, is the +default\&. It only works if the \fBTERM\fP parameter is set to a valid +terminal type that can move the cursor up\&. The second, single line +mode, is used if \fBTERM\fP is invalid or incapable of moving the +cursor up, or if the \fBSINGLE_LINE_ZLE\fP option is set\&. +This mode +is similar to \fBksh\fP, and uses no termcap sequences\&. If \fBTERM\fP is +"emacs", the \fBZLE\fP option will be unset by default\&. +.PP +The parameters \fBBAUD\fP, \fBCOLUMNS\fP, and \fBLINES\fP are also used by the +line editor\&. See +\fIParameters Used By The Shell\fP in \fIzshparam\fP(1)\&. +.PP +The parameter \fBzle_highlight\fP is also used by the line editor; see +\fICharacter Highlighting\fP below\&. Highlighting +of special characters and the region between the cursor and the +mark (as set with \fBset\-mark\-command\fP in Emacs mode, or by \fBvisual\-mode\fP +in Vi mode) is enabled +by default; consult this reference for more information\&. Irascible +conservatives will wish to know that all highlighting may be disabled by +the following setting: +.PP +.RS +.nf +\fBzle_highlight=(none)\fP +.fi +.RE +.PP +In many places, references are made to the \fBnumeric argument\fP\&. This can +by default be entered in emacs mode by holding the alt key and typing +a number, or pressing escape before each digit, and in vi command mode +by typing the number before entering a command\&. Generally the numeric +argument causes the next command entered to be repeated the specified +number of times, unless otherwise noted below; this is implemented +by the \fBdigit\-argument\fP widget\&. See also +the \fIArguments\fP subsection of the \fIWidgets\fP section for some other ways the numeric argument can be modified\&. +.PP +.PP +.SH "KEYMAPS" +A keymap in ZLE contains a set of bindings between key sequences +and ZLE commands\&. The empty key sequence cannot be bound\&. +.PP +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\&. +\fBbindkey\fP can be used to manipulate keymap names\&. +.PP +Initially, there are eight keymaps: +.PP +.PD 0 +.TP +\fBemacs\fP +EMACS emulation +.TP +\fBviins\fP +vi emulation \- insert mode +.TP +\fBvicmd\fP +vi emulation \- command mode +.TP +\fBviopp\fP +vi emulation \- operator pending +.TP +\fBvisual\fP +vi emulation \- selection active +.TP +\fBisearch\fP +incremental search mode +.TP +\fBcommand\fP +read a command name +.TP +\fB\&.safe\fP +fallback keymap +.PD +.PP +The `\fB\&.safe\fP\&' 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 `\fB\&.\fP\&' for their own keymaps\&. +.PP +In addition to these names, either `\fBemacs\fP\&' or `\fBviins\fP' is +also linked to the name `\fBmain\fP\&'\&. If one of the \fBVISUAL\fP or +\fBEDITOR\fP environment variables contain the string `\fBvi\fP\&' when the shell +starts up then it will be `\fBviins\fP\&', otherwise it will be `\fBemacs\fP'\&. +\fBbindkey\fP\&'s \fB\-e\fP and \fB\-v\fP +options provide a convenient way to override this default choice\&. +.PP +When the editor starts up, it will select the `\fBmain\fP\&' keymap\&. +If that keymap doesn\&'t exist, it will use `\fB\&.safe\fP' instead\&. +.PP +In the `\fB\&.safe\fP\&' keymap, each single key is bound to \fBself\-insert\fP, +except for ^J (line feed) and ^M (return) which are bound to \fBaccept\-line\fP\&. +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\&. +.SS "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 \fBKEYTIMEOUT\fP parameter; +its default is 0\&.4 sec\&. There is no timeout if the prefix string is not +itself bound to a command\&. +.PP +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 \fB?\fP were typed and resets the input state\&. +.PP +As well as ZLE commands, key sequences can be bound to other strings, by using +`\fBbindkey \-s\fP\&'\&. +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\&. +.PP +A key sequence typed by the user can be turned into a command name for use +in user\-defined widgets with the \fBread\-command\fP widget, described in +the subsection `Miscellaneous\&' of the section `Standard Widgets' below\&. +.SS "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 \fBisearch\fP keymap will +override a binding in the \fBmain\fP keymap but all keys that are not +overridden can still be used\&. +.PP +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 \fBiw\fP in \fBviopp\fP as this +hides the binding of \fBi\fP in \fBvicmd\fP\&. However, a longer sequence in +the global keymap that shares the same prefix can still apply so for +example the binding of \fB^Xa\fP in the global keymap will be unaffected +by the binding of \fB^Xb\fP in the local keymap\&. +.PP +.SH "ZLE BUILTINS" +The ZLE module contains three related builtin commands\&. The \fBbindkey\fP +command manipulates keymaps and key bindings; the \fBvared\fP command invokes +ZLE on the value of a shell parameter; and the \fBzle\fP command manipulates +editing widgets and allows command line access to ZLE commands from within +shell functions\&. +.PP +.PD 0 +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-l\fP [ \fB\-L\fP ] [ \fIkeymap\fP \&.\&.\&. ] +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-d\fP +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-D\fP \fIkeymap\fP \&.\&.\&. +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-A\fP \fIold\-keymap new\-keymap\fP +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-N\fP \fInew\-keymap\fP [ \fIold\-keymap\fP ] +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-m\fP +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-r\fP \fIin\-string\fP \&.\&.\&. +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-s\fP \fIin\-string out\-string\fP \&.\&.\&. +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fIin\-string command\fP \&.\&.\&. +.TP +.PD +\fBbindkey\fP [ \fIoptions\fP ] [ \fIin\-string\fP ] +\fBbindkey\fP\&'s options can be divided into three categories: keymap +selection for the current command, operation selection, and others\&. The +keymap selection options are: +.RS +.PP +.PD 0 +.TP +.PD +\fB\-e\fP +Selects keymap `\fBemacs\fP\&' for any operations by the current command, +and also links `\fBemacs\fP\&' to `\fBmain\fP' so that it is selected by +default the next time the editor starts\&. +.TP +\fB\-v\fP +Selects keymap `\fBviins\fP\&' for any operations by the current command, +and also links `\fBviins\fP\&' to `\fBmain\fP' so that it is selected by default +the next time the editor starts\&. +.TP +\fB\-a\fP +Selects keymap `\fBvicmd\fP\&' for any operations by the current command\&. +.TP +\fB\-M\fP \fIkeymap\fP +The \fIkeymap\fP specifies a keymap name that is selected for any +operations by the current command\&. +.PP +If a keymap selection is required and none of the options above are used, the +`\fBmain\fP\&' keymap is used\&. Some operations do not permit a keymap to be +selected, namely: +.PP +.PD 0 +.TP +.PD +\fB\-l\fP +List all existing keymap names; if any arguments are given, list just +those keymaps\&. +.RS +.PP +If the \fB\-L\fP option is also used, list in the form of \fBbindkey\fP +commands to create or link the keymaps\&. `\fBbindkey \-lL +main\fP\&' shows which keymap is linked to `\fBmain\fP', if any, and hence if +the standard emacs or vi emulation is in effect\&. This option does +not show the \fB\&.safe\fP keymap because it cannot be created in that +fashion; however, neither is `\fBbindkey \-lL \&.safe\fP\&' reported as an +error, it simply outputs nothing\&. +.RE +.TP +\fB\-d\fP +Delete all existing keymaps and reset to the default state\&. +.TP +\fB\-D\fP \fIkeymap\fP \&.\&.\&. +Delete the named \fIkeymap\fPs\&. +.TP +\fB\-A\fP \fIold\-keymap new\-keymap\fP +Make the \fInew\-keymap\fP name an alias for \fIold\-keymap\fP, so that +both names refer to the same keymap\&. The names have equal standing; +if either is deleted, the other remains\&. If there is already a keymap +with the \fInew\-keymap\fP name, it is deleted\&. +.TP +\fB\-N\fP \fInew\-keymap\fP [ \fIold\-keymap\fP ] +Create a new keymap, named \fInew\-keymap\fP\&. If a keymap already has that +name, it is deleted\&. If an \fIold\-keymap\fP name is given, the new keymap +is initialized to be a duplicate of it, otherwise the new keymap will +be empty\&. +.PP +To use a newly created keymap, it should be linked to \fBmain\fP\&. Hence +the sequence of commands to create and use a new keymap `\fBmymap\fP\&' +initialized from the \fBemacs\fP keymap (which remains unchanged) is: +.PP +.RS +.nf +\fBbindkey \-N mymap emacs +bindkey \-A mymap main\fP +.fi +.RE +.PP +Note that while `\fBbindkey \-A\fP \fInewmap\fP \fBmain\fP\&' will work when +\fInewmap\fP is \fBemacs\fP or \fBviins\fP, it will not work for \fBvicmd\fP, as +switching from vi insert to command mode becomes impossible\&. +.PP +The following operations act on the `\fBmain\fP\&' keymap if no keymap +selection option was given: +.PP +.PD 0 +.TP +.PD +\fB\-m\fP +Add the built\-in set of meta\-key bindings to the selected keymap\&. +Only keys that are unbound or bound to \fBself\-insert\fP are affected\&. +.TP +\fB\-r\fP \fIin\-string\fP \&.\&.\&. +Unbind the specified \fIin\-string\fPs in the selected keymap\&. +This is exactly equivalent to binding the strings to \fBundefined\-key\fP\&. +.RS +.PP +When \fB\-R\fP is also used, interpret the \fIin\-string\fPs as ranges\&. +.PP +When \fB\-p\fP is also used, the \fIin\-string\fPs specify prefixes\&. Any +binding that has the given \fIin\-string\fP as a prefix, not including the +binding for the \fIin\-string\fP itself, if any, will be removed\&. For +example, +.PP +.RS +.nf +\fBbindkey \-rpM viins \&'^['\fP +.fi +.RE +.PP +will remove all bindings in the vi\-insert keymap beginning with an escape +character (probably cursor keys), but leave the binding for the escape +character itself (probably \fBvi\-cmd\-mode\fP)\&. This is incompatible with the +option \fB\-R\fP\&. +.RE +.TP +\fB\-s\fP \fIin\-string out\-string\fP \&.\&.\&. +Bind each \fIin\-string\fP to each \fIout\-string\fP\&. +When \fIin\-string\fP is typed, \fIout\-string\fP will be +pushed back and treated as input to the line editor\&. +When \fB\-R\fP is also used, interpret the \fIin\-string\fPs as ranges\&. +.RS +.PP +Note that both \fIin\-string\fP and \fIout\-string\fP are subject to the same +form of interpretation, as described below\&. +.RE +.TP +\fIin\-string command\fP \&.\&.\&. +Bind each \fIin\-string\fP to each \fIcommand\fP\&. +When \fB\-R\fP is used, interpret the \fIin\-string\fPs as ranges\&. +.TP +[ \fIin\-string\fP ] +List key bindings\&. If an \fIin\-string\fP is specified, the binding of +that string in the selected keymap is displayed\&. Otherwise, all key +bindings in the selected keymap are displayed\&. (As a special case, +if the \fB\-e\fP or \fB\-v\fP option is used alone, the keymap is \fInot\fP +displayed \- the implicit linking of keymaps is the only thing that +happens\&.) +.RS +.PP +When the option \fB\-p\fP is used, the \fIin\-string\fP must be present\&. +The listing shows all bindings which have the given key sequence as a +prefix, not including any bindings for the key sequence itself\&. +.PP +When the \fB\-L\fP option is used, the list is in the form of \fBbindkey\fP +commands to create the key bindings\&. +.RE +.PP +When the \fB\-R\fP option is used as noted above, a valid range consists of +two characters, with an optional `\fB\-\fP\&' between them\&. All characters +between the two specified, inclusive, are bound as specified\&. +.PP +For either \fIin\-string\fP or \fIout\-string\fP, the following +escape sequences are recognised: +.PP +.PD 0 +.TP +\fB\ea\fP +bell character +.TP +\fB\eb\fP +backspace +.TP +\fB\ee\fP, \fB\eE\fP +escape +.TP +\fB\ef\fP +form feed +.TP +\fB\en\fP +linefeed (newline) +.TP +\fB\er\fP +carriage return +.TP +\fB\et\fP +horizontal tab +.TP +\fB\ev\fP +vertical tab +.TP +\fB\e\fP\fINNN\fP +character code in octal +.TP +\fB\ex\fP\fINN\fP +character code in hexadecimal +.TP +\fB\eu\fP\fINNNN\fP +unicode character code in hexadecimal +.TP +\fB\eU\fP\fINNNNNNNN\fP +unicode character code in hexadecimal +.TP +\fB\eM\fP[\fB\-\fP]\fIX\fP +character with meta bit set +.TP +\fB\eC\fP[\fB\-\fP]\fIX\fP +control character +.TP +\fB^\fP\fIX\fP +control character +.PD +.PP +In all other cases, `\fB\e\fP\&' escapes the following character\&. Delete is +written as `\fB^?\fP\&'\&. Note that `\fB\eM^?\fP' and `\fB^\eM?\fP' are not the same, +and that (unlike emacs), the bindings `\fB\eM\-\fP\fIX\fP\&' and `\fB\ee\fP\fIX\fP' +are entirely distinct, although they are initialized to the same bindings +by `\fBbindkey \-m\fP\&'\&. +.RE + +.TP +.PD 0 +\fBvared \fP[ \fB\-Aacghe\fP ] [ \fB\-p\fP \fIprompt\fP ] [ \fB\-r\fP \fIrprompt\fP ] +.TP +.PD 0 +\fB \fP[ \fB\-M\fP \fImain\-keymap\fP ] [ \fB\-m\fP \fIvicmd\-keymap\fP ] +.TP +.PD 0 +\fB \fP[ \fB\-i\fP \fIinit\-widget\fP ] [ \fB\-f\fP \fIfinish\-widget\fP ] +.TP +.PD +\fB \fP[ \fB\-t\fP \fItty\fP ] \fIname\fP +The value of the parameter \fIname\fP is loaded into the edit +buffer, and the line editor is invoked\&. When the editor exits, +\fIname\fP is set to the string value returned by the editor\&. +When the \fB\-c\fP flag is given, the parameter is created if it doesn\&'t +already exist\&. The \fB\-a\fP flag may be given with \fB\-c\fP to create +an array parameter, or the \fB\-A\fP flag to create an associative array\&. +If the type of an existing parameter does not match the type to be +created, the parameter is unset and recreated\&. The \fB\-g\fP flag may +be given to suppress warnings from the \fBWARN_CREATE_GLOBAL\fP +and \fBWARN_NESTED_VAR\fP options\&. +.RS +.PP +If an array or array slice is being edited, separator characters as defined +in \fB$IFS\fP will be shown quoted with a backslash, as will backslashes +themselves\&. Conversely, when the edited text is split into an array, a +backslash quotes an immediately following separator character or backslash; +no other special handling of backslashes, or any handling of quotes, is +performed\&. +.PP +Individual elements of existing array or associative array parameters +may be edited by using subscript syntax on \fIname\fP\&. New elements are +created automatically, even without \fB\-c\fP\&. +.PP +If the \fB\-p\fP flag is given, the following string will be taken as +the prompt to display at the left\&. If the \fB\-r\fP flag is given, +the following string gives the prompt to display at the right\&. If the +\fB\-h\fP flag is specified, the history can be accessed from ZLE\&. If the +\fB\-e\fP flag is given, typing \fB^D\fP (Control\-D) on an empty line +causes \fBvared\fP to exit immediately with a non\-zero return value\&. +.PP +The \fB\-M\fP option gives a keymap to link to the \fBmain\fP keymap during +editing, and the \fB\-m\fP option gives a keymap to link to the \fBvicmd\fP +keymap during editing\&. For vi\-style editing, this allows a pair of keymaps +to override \fBviins\fP and \fBvicmd\fP\&. For emacs\-style editing, only \fB\-M\fP +is normally needed but the \fB\-m\fP option may still be used\&. On exit, the +previous keymaps will be restored\&. +.PP +\fBVared\fP calls the usual `\fBzle\-line\-init\fP\&' and `\fBzle\-line\-finish\fP' +hooks before and after it takes control\&. Using the \fB\-i\fP and \fB\-f\fP +options, it is possible to replace these with other custom widgets\&. +.PP +If `\fB\-t\fP \fItty\fP\&' is given, \fItty\fP is the name of a terminal device +to be used instead of the default \fB/dev/tty\fP\&. If \fItty\fP does not +refer to a terminal an error is reported\&. +.RE +.TP +.PD 0 +\fBzle\fP +.TP +.PD 0 +\fBzle\fP \fB\-l\fP [ \fB\-L\fP | \fB\-a\fP ] [ \fIstring\fP \&.\&.\&. ] +.TP +.PD 0 +\fBzle\fP \fB\-D\fP \fIwidget\fP \&.\&.\&. +.TP +.PD 0 +\fBzle\fP \fB\-A\fP \fIold\-widget\fP \fInew\-widget\fP +.TP +.PD 0 +\fBzle\fP \fB\-N\fP \fIwidget\fP [ \fIfunction\fP ] +.TP +.PD 0 +\fBzle\fP \fB\-f\fP \fIflag\fP [ \fIflag\fP\&.\&.\&. ] +.TP +.PD 0 +\fBzle\fP \fB\-C\fP \fIwidget\fP \fIcompletion\-widget\fP \fIfunction\fP +.TP +.PD 0 +\fBzle\fP \fB\-R\fP [ \fB\-c\fP ] [ \fIdisplay\-string\fP ] [ \fIstring\fP \&.\&.\&. ] +.TP +.PD 0 +\fBzle\fP \fB\-M\fP \fIstring\fP +.TP +.PD 0 +\fBzle\fP \fB\-U\fP \fIstring\fP +.TP +.PD 0 +\fBzle\fP \fB\-K\fP \fIkeymap\fP +.TP +.PD 0 +\fBzle\fP \fB\-F\fP [ \fB\-L\fP | \fB\-w\fP ] [ \fIfd\fP [ \fIhandler\fP ] ] +.TP +.PD 0 +\fBzle\fP \fB\-I\fP +.TP +.PD 0 +\fBzle\fP \fB\-T\fP [ \fBtc\fP \fIfunction\fP | \fB\-r\fP \fBtc\fP | \fB\-L\fP ] +.TP +.PD +\fBzle\fP \fIwidget\fP [ \fB\-n\fP \fInum\fP ] [ \fB\-Nw\fP ] [ \fB\-K\fP \fIkeymap\fP ] \fIargs\fP \&.\&.\&. +The \fBzle\fP builtin performs a number of different actions concerning +ZLE\&. +.RS +.PP +With no options and no arguments, only the return status will be +set\&. It is zero if ZLE is currently active and widgets could be +invoked using this builtin command and non\-zero otherwise\&. +Note that even if non\-zero status is returned, zle may still be active as +part of the completion system; this does not allow direct calls to ZLE +widgets\&. +.PP +Otherwise, which operation it performs depends on its options: +.PP +.PD 0 +.TP +.PD +\fB\-l\fP [ \fB\-L\fP | \fB\-a\fP ] [ \fIstring\fP ] +List all existing user\-defined widgets\&. If the \fB\-L\fP +option is used, list in the form of \fBzle\fP +commands to create the widgets\&. +.RS +.PP +When combined with the \fB\-a\fP option, all widget names are listed, +including the builtin ones\&. In this case the \fB\-L\fP option is ignored\&. +.PP +If at least one \fIstring\fP is given, and \fB\-a\fP is present or \fB\-L\fP is +not used, nothing will be printed\&. The return status will be zero if +all \fIstring\fPs are names of existing widgets and non\-zero if at least one +\fIstring\fP is not a name of a defined widget\&. If \fB\-a\fP is also +present, all widget names are used for the comparison including builtin +widgets, else only user\-defined widgets are used\&. +.PP +If at least one \fIstring\fP is present and the \fB\-L\fP option is used, +user\-defined widgets matching any \fIstring\fP are listed in the form of +\fBzle\fP commands to create the widgets\&. +.RE +.TP +\fB\-D\fP \fIwidget\fP \&.\&.\&. +Delete the named \fIwidget\fPs\&. +.TP +\fB\-A\fP \fIold\-widget\fP \fInew\-widget\fP +Make the \fInew\-widget\fP name an alias for \fIold\-widget\fP, so that +both names refer to the same widget\&. The names have equal standing; +if either is deleted, the other remains\&. If there is already a widget +with the \fInew\-widget\fP name, it is deleted\&. +.TP +\fB\-N\fP \fIwidget\fP [ \fIfunction\fP ] +Create a user\-defined widget\&. If there is already a widget with the +specified name, it is overwritten\&. When the new +widget is invoked from within the editor, the specified shell \fIfunction\fP +is called\&. If no function name is specified, it defaults to +the same name as the widget\&. For further information, see +the section `Widgets\&' below\&. +.TP +\fB\-f\fP \fIflag\fP [ \fIflag\fP\&.\&.\&. ] +Set various flags on the running widget\&. Possible values for \fIflag\fP are: +.RS +.PP +\fByank\fP for indicating that the widget has yanked text into the buffer\&. +If the widget is wrapping an existing internal widget, no further +action is necessary, but if it has inserted the text manually, then it +should also take care to set \fBYANK_START\fP and \fBYANK_END\fP correctly\&. +\fByankbefore\fP does the same but is used when the yanked text appears +after the cursor\&. +.PP +\fBkill\fP for indicating that text has been killed into the cutbuffer\&. +When repeatedly invoking a kill widget, text is appended to the cutbuffer +instead of replacing it, but when wrapping such widgets, it is necessary +to call `\fBzle \-f kill\fP\&' to retain this effect\&. +.PP +\fBvichange\fP for indicating that the widget represents a vi change that +can be repeated as a whole with `\fBvi\-repeat\-change\fP\&'\&. The flag should be set +early in the function before inspecting the value of \fBNUMERIC\fP or invoking +other widgets\&. This has no effect for a widget invoked from insert mode\&. If +insert mode is active when the widget finishes, the change extends until next +returning to command mode\&. +.RE +.TP +\fB\-C\fP \fIwidget\fP \fIcompletion\-widget\fP \fIfunction\fP +Create a user\-defined completion widget named \fIwidget\fP\&. The +completion widget will behave like the built\-in completion\-widget +whose name is given as \fIcompletion\-widget\fP\&. To generate the +completions, the shell function \fIfunction\fP will be called\&. +For further information, see +\fIzshcompwid\fP(1)\&. +.TP +\fB\-R\fP [ \fB\-c\fP ] [ \fIdisplay\-string\fP ] [ \fIstring\fP \&.\&.\&. ] +Redisplay the command line; this is to be called from within a user\-defined +widget to allow changes to become visible\&. If a \fIdisplay\-string\fP is +given and not empty, this is shown in the status line (immediately +below the line being edited)\&. +.RS +.PP +If the optional \fIstring\fPs are given they are listed below the +prompt in the same way as completion lists are printed\&. If no +\fIstring\fPs are given but the \fB\-c\fP option is used such a list is +cleared\&. +.PP +Note that this option is only useful for widgets that do not exit +immediately after using it because the strings displayed will be erased +immediately after return from the widget\&. +.PP +This command can safely be called outside user defined widgets; if zle is +active, the display will be refreshed, while if zle is not active, the +command has no effect\&. In this case there will usually be no other +arguments\&. +.PP +The status is zero if zle was active, else one\&. +.RE +.TP +\fB\-M\fP \fIstring\fP +As with the \fB\-R\fP option, the \fIstring\fP will be displayed below the +command line; unlike the \fB\-R\fP option, the string will not be put into +the status line but will instead be printed normally below the +prompt\&. This means that the \fIstring\fP will still be displayed after +the widget returns (until it is overwritten by subsequent commands)\&. +.TP +\fB\-U\fP \fIstring\fP +This pushes the characters in the \fIstring\fP onto the input stack of +ZLE\&. After the widget currently executed finishes ZLE will behave as +if the characters in the \fIstring\fP were typed by the user\&. +.RS +.PP +As ZLE uses a stack, if this option is used repeatedly +the last string pushed onto the stack will be processed first\&. However, +the characters in each \fIstring\fP will be processed in the order in which +they appear in the string\&. +.RE +.TP +\fB\-K\fP \fIkeymap\fP +Selects the keymap named \fIkeymap\fP\&. An error message will be displayed if +there is no such keymap\&. +.RS +.PP +This keymap selection affects the interpretation of following keystrokes +within this invocation of ZLE\&. Any following invocation (e\&.g\&., the next +command line) will start as usual with the `\fBmain\fP\&' keymap selected\&. +.RE +.TP +\fB\-F\fP [ \fB\-L\fP | \fB\-w\fP ] [ \fIfd\fP [ \fIhandler\fP ] ] +Only available if your system supports one of the `poll\&' or `select' system +calls; most modern systems do\&. +.RS +.PP +Installs \fIhandler\fP (the name of a shell function) to handle input from +file descriptor \fIfd\fP\&. Installing a handler for an \fIfd\fP which is +already handled causes the existing handler to be replaced\&. Any number of +handlers for any number of readable file descriptors may be installed\&. +Note that zle makes no attempt to check whether this \fIfd\fP is actually +readable when installing the handler\&. The user must make their own +arrangements for handling the file descriptor when zle is not active\&. +.PP +When zle is attempting to read data, it will examine both the terminal and +the list of handled \fIfd\fP\&'s\&. If data becomes available on a handled +\fIfd\fP, zle calls \fIhandler\fP with the fd which is ready for reading +as the first argument\&. Under normal circumstances this is the only +argument, but if an error was detected, a second argument provides +details: `\fBhup\fP\&' for a disconnect, `\fBnval\fP' for a closed or otherwise +invalid descriptor, or `\fBerr\fP\&' for any other condition\&. Systems that +support only the `select\&' system call always use `\fBerr\fP'\&. +.PP +If the option \fB\-w\fP is also given, the \fIhandler\fP is instead a line +editor widget, typically a shell function made into a widget using +`\fBzle \-N\fP\&'\&. In that case \fIhandler\fP can use all the facilities of zle +to update the current editing line\&. Note, however, that as handling \fIfd\fP +takes place at a low level changes to the display will not automatically +appear; the widget should call `\fBzle \-R\fP\&' to force redisplay\&. As of this +writing, widget handlers only support a single argument and thus are never +passed a string for error state, so widgets must be prepared to test the +descriptor themselves\&. +.PP +If either type of handler produces output to the terminal, it should call +`\fBzle \-I\fP\&' before doing so (see below)\&. Handlers should not attempt to +read from the terminal\&. +.PP +If no \fIhandler\fP is given, but an \fIfd\fP is present, any handler for +that \fIfd\fP is removed\&. If there is none, an error message is printed +and status 1 is returned\&. +.PP +If no arguments are given, or the \fB\-L\fP option is supplied, a list of +handlers is printed in a form which can be stored for later execution\&. +.PP +An \fIfd\fP (but not a \fIhandler\fP) may optionally be given with the \fB\-L\fP +option; in this case, the function will list the handler if any, else +silently return status 1\&. +.PP +Note that this feature should be used with care\&. Activity on one of the +\fIfd\fP\&'s which is not properly handled can cause the terminal to become +unusable\&. Removing an \fIfd\fP handler from within a signal trap may cause +unpredictable behavior\&. +.PP +Here is a simple example of using this feature\&. A connection to a remote +TCP port is created using the ztcp command; see +the description of the \fBzsh/net/tcp\fP module in \fIzshmodules\fP(1)\&. Then a handler is installed +which simply prints out any data which arrives on this connection\&. Note +that `select\&' will indicate that the file descriptor needs handling +if the remote side has closed the connection; we handle that by testing +for a failed read\&. +.PP +.RS +.nf +\fBif ztcp pwspc 2811; then + tcpfd=$REPLY + handler() { + zle \-I + local line + if ! read \-r line <&$1; then + # select marks this fd if we reach EOF, + # so handle this specially\&. + print "[Read on fd $1 failed, removing\&.]" >&2 + zle \-F $1 + return 1 + fi + print \-r \- $line + } + zle \-F $tcpfd handler +fi\fP +.fi +.RE +.RE +.TP +\fB\-I\fP +Unusually, this option is most useful outside ordinary widget functions, +though it may be used within if normal output to the terminal is required\&. +It invalidates the current zle display in preparation for output; typically +this will be from a trap function\&. It has no effect if zle is not +active\&. When a trap exits, the shell checks to see if the display needs +restoring, hence the following will print output in such a way as not to +disturb the line being edited: +.RS +.PP +.RS +.nf +\fBTRAPUSR1() { + # Invalidate zle display + [[ \-o zle ]] && zle \-I + # Show output + print Hello +}\fP +.fi +.RE +.PP +In general, the trap function may need to test whether zle is active before +using this method (as shown in the example), since the \fBzsh/zle\fP module +may not even be loaded; if it is not, the command can be skipped\&. +.PP +It is possible to call `\fBzle \-I\fP\&' several times before control is +returned to the editor; the display will only be invalidated the first time +to minimise disruption\&. +.PP +Note that there are normally better ways of manipulating the display from +within zle widgets; see, for example, `\fBzle \-R\fP\&' above\&. +.PP +The returned status is zero if zle was invalidated, even though +this may have been by a previous call to `\fBzle \-I\fP\&' or by a system +notification\&. To test if a zle widget may be called at this point, execute +\fBzle\fP with no arguments and examine the return status\&. +.RE +.TP +\fB\-T\fP +This is used to add, list or remove internal transformations on the +processing performed by the line editor\&. It is typically used only for +debugging or testing and is therefore of little interest to the general +user\&. +.RS +.PP +`\fBzle \-T\fP \fItransformation\fP \fIfunc\fP\&' specifies that the +given \fItransformation\fP (see below) is effected by shell function +\fIfunc\fP\&. +.PP +`\fBzle \-Tr\fP \fItransformation\fP\&' removes the given \fItransformation\fP +if it was present (it is not an error if none was)\&. +.PP +`\fBzle \-TL\fP\&' can be used to list all transformations currently in +operation\&. +.PP +Currently the only transformation is \fBtc\fP\&. This is used instead +of outputting termcap codes to the terminal\&. When the transformation is +in operation the shell function is passed the termcap code that would be +output as its first argument; if the operation required a numeric +argument, that is passed as a second argument\&. The function should set +the shell variable \fBREPLY\fP to the transformed termcap code\&. Typically +this is used to produce some simply formatted version of the code and +optional argument for debugging or testing\&. Note that this +transformation is not applied to other non\-printing characters such as +carriage returns and newlines\&. +.RE +.TP +\fIwidget\fP [ \fB\-n\fP \fInum\fP ] [ \fB\-Nw\fP ] [ \fB\-K\fP \fIkeymap\fP ] \fIargs\fP \&.\&.\&. +Invoke the specified \fIwidget\fP\&. This can only be done when ZLE is +active; normally this will be within a user\-defined widget\&. +.RS +.PP +With the options \fB\-n\fP and \fB\-N\fP, the current numeric argument will be +saved and then restored after the call to \fIwidget\fP; `\fB\-n\fP \fInum\fP\&' +sets the numeric argument temporarily to \fInum\fP, while `\fB\-N\fP\&' sets it +to the default, i\&.e\&. as if there were none\&. +.PP +With the option \fB\-K\fP, \fIkeymap\fP will be used as the current keymap +during the execution of the widget\&. The previous keymap will be +restored when the widget exits\&. +.PP +Normally, calling a widget in this way does not set the special +parameter \fBWIDGET\fP and related parameters, so that the environment +appears as if the top\-level widget called by the user were still +active\&. With the option \fB\-w\fP, \fBWIDGET\fP and related parameters are set +to reflect the widget being executed by the \fBzle\fP call\&. +.PP +Any further arguments will be passed to the widget; note that as +standard argument handling is performed, any general argument list +should be preceded by \fB\-\fP\fB\-\fP\&. If it is a shell +function, these are passed down as positional parameters; for builtin +widgets it is up to the widget in question what it does with them\&. +Currently arguments are only handled by the incremental\-search commands, +the \fBhistory\-search\-forward\fP and \fB\-backward\fP and the corresponding +functions prefixed by \fBvi\-\fP, and by \fBuniversal\-argument\fP\&. No error is +flagged if the command does not use the arguments, or only uses some of +them\&. +.PP +The return status reflects the success or failure of the operation carried +out by the widget, or if it is a user\-defined widget the return status of +the shell function\&. +.PP +A non\-zero return status causes the shell to beep when the widget exits, +unless the \fBBEEP\fP options was unset or the widget was called via the +\fBzle\fP command\&. Thus if a user defined widget requires an immediate beep, +it should call the \fBbeep\fP widget directly\&. +.RE +.RE +.PP +.SH "WIDGETS" +All actions in the editor are performed by `widgets\&'\&. A widget's job is +simply to perform some small action\&. The ZLE commands that key sequences +in keymaps are bound to are in fact widgets\&. Widgets can be user\-defined +or built in\&. +.PP +The standard widgets built into ZLE are listed in Standard Widgets below\&. +Other built\-in widgets can be defined by other modules (see +\fIzshmodules\fP(1))\&. Each built\-in widget has two names: its normal canonical name, and the +same name preceded by a `\fB\&.\fP\&'\&. The `\fB\&.\fP' name is special: it can't be +rebound to a different widget\&. This makes the widget available even when +its usual name has been redefined\&. +.PP +User\-defined widgets are defined using `\fBzle \-N\fP\&', and implemented +as shell functions\&. When the widget is executed, the corresponding +shell function is executed, and can perform editing (or other) actions\&. +It is recommended that user\-defined widgets should not have names +starting with `\fB\&.\fP\&'\&. +.SH "USER\-DEFINED WIDGETS" +User\-defined widgets, being implemented as shell functions, +can execute any normal shell command\&. They can also run other widgets +(whether built\-in or user\-defined) using the \fBzle\fP builtin command\&. The +standard input of the function is redirected from /dev/null to prevent +external commands from unintentionally blocking ZLE by reading from the +terminal, but \fBread \-k\fP or \fBread \-q\fP can be used to read characters\&. +Finally, they can examine and edit the ZLE buffer being edited by reading +and setting the special parameters described below\&. +.PP +These special parameters are always available in widget functions, but +are not in any way special outside ZLE\&. If they have some normal value +outside ZLE, that value is temporarily inaccessible, but will return +when the widget function exits\&. These special parameters in fact have +local scope, like parameters created in a function using \fBlocal\fP\&. +.PP +Inside completion widgets and traps called while ZLE is active, these +parameters are available read\-only\&. +.PP +Note that the parameters appear as local to any ZLE widget in +which they appear\&. Hence if it is desired to override them this needs +to be done within a nested function: +.PP +.RS +.nf +\fBwidget\-function() { + # $WIDGET here refers to the special variable + # that is local inside widget\-function + () { + # This anonymous nested function allows WIDGET + # to be used as a local variable\&. The \-h + # removes the special status of the variable\&. + local \-h WIDGET + } +}\fP +.fi +.RE +.PP +.PD 0 +.TP +.PD +\fBBUFFER\fP (scalar) +The entire contents of the edit buffer\&. If it is written to, the +cursor remains at the same offset, unless that would put it outside the +buffer\&. +.TP +\fBBUFFERLINES\fP (integer) +The number of screen lines needed for the edit buffer currently +displayed on screen (i\&.e\&. without any changes to the preceding +parameters done after the last redisplay); read\-only\&. +.TP +\fBCONTEXT\fP (scalar) +The context in which zle was called to read a line; read\-only\&. One of +the values: +.RS +.PP +.PD 0 +.TP +.PD +\fBstart\fP +The start of a command line (at prompt \fBPS1\fP)\&. +.TP +\fBcont\fP +A continuation to a command line (at prompt \fBPS2\fP)\&. +.TP +\fBselect\fP +In a \fBselect\fP loop (at prompt \fBPS3\fP)\&. +.TP +\fBvared\fP +Editing a variable in \fBvared\fP\&. +.RE +.TP +\fBCURSOR\fP (integer) +The offset of the cursor, within the edit buffer\&. This is in the range +0 to \fB$#BUFFER\fP, and is by definition equal to \fB$#LBUFFER\fP\&. +Attempts to move the cursor outside the buffer will result in the +cursor being moved to the appropriate end of the buffer\&. +.TP +\fBCUTBUFFER\fP (scalar) +The last item cut using one of the `\fBkill\-\fP\&' commands; the string +which the next yank would insert in the line\&. Later entries in +the kill ring are in the array \fBkillring\fP\&. Note that the +command `\fBzle copy\-region\-as\-kill\fP \fIstring\fP\&' can be used to +set the text of the cut buffer from a shell function and cycle the kill +ring in the same way as interactively killing text\&. +.TP +\fBHISTNO\fP (integer) +The current history number\&. Setting this has the same effect as +moving up or down in the history to the corresponding history line\&. +An attempt to set it is ignored if the line is not stored in the +history\&. Note this is not the same as the parameter \fBHISTCMD\fP, +which always gives the number of the history line being added to the main +shell\&'s history\&. \fBHISTNO\fP refers to the line being retrieved within +zle\&. +.TP +.PD 0 +\fBISEARCHMATCH_ACTIVE\fP (integer) +.TP +.PD 0 +\fBISEARCHMATCH_START\fP (integer) +.TP +.PD +\fBISEARCHMATCH_END\fP (integer) +\fBISEARCHMATCH_ACTIVE\fP indicates whether a part of the \fBBUFFER\fP is +currently matched by an incremental search pattern\&. \fBISEARCHMATCH_START\fP +and \fBISEARCHMATCH_END\fP give the location of the matched part and are +in the same units as \fBCURSOR\fP\&. They are only valid for reading +when \fBISEARCHMATCH_ACTIVE\fP is non\-zero\&. +.RS +.PP +All parameters are read\-only\&. +.RE +.TP +\fBKEYMAP\fP (scalar) +The name of the currently selected keymap; read\-only\&. +.TP +\fBKEYS\fP (scalar) +The keys typed to invoke this widget, as a literal string; read\-only\&. +.TP +\fBKEYS_QUEUED_COUNT\fP (integer) +The number of bytes pushed back to the input queue and therefore +available for reading immediately before any I/O is done; read\-only\&. +See also \fBPENDING\fP; the two values are distinct\&. +.TP +\fBkillring\fP (array) +The array of previously killed items, with the most recently killed first\&. +This gives the items that would be retrieved by a \fByank\-pop\fP in the +same order\&. Note, however, that the most recently killed item is in +\fB$CUTBUFFER\fP; \fB$killring\fP shows the array of previous entries\&. +.RS +.PP +The default size for the kill ring is eight, however the length may be +changed by normal array operations\&. Any empty string in the kill ring is +ignored by the \fByank\-pop\fP command, hence the size of the array +effectively sets the maximum length of the kill ring, while the number of +non\-zero strings gives the current length, both as seen by the user at the +command line\&. +.RE +.TP +\fBLASTABORTEDSEARCH\fP (scalar) +The last search string used by an interactive search that was +aborted by the user (status 3 returned by the search widget)\&. +.TP +\fBLASTSEARCH\fP (scalar) +The last search string used by an interactive search; read\-only\&. +This is set even if the search failed (status 0, 1 or 2 returned +by the search widget), but not if it was aborted by the user\&. +.TP +\fBLASTWIDGET\fP (scalar) +The name of the last widget that was executed; read\-only\&. +.TP +\fBLBUFFER\fP (scalar) +The part of the buffer that lies to the left of the cursor position\&. +If it is assigned to, only that part of the buffer is replaced, and the +cursor remains between the new \fB$LBUFFER\fP and the old \fB$RBUFFER\fP\&. +.TP +\fBMARK\fP (integer) +Like \fBCURSOR\fP, but for the mark\&. With vi\-mode operators that wait for +a movement command to select a region of text, setting \fBMARK\fP allows +the selection to extend in both directions from the initial cursor +position\&. +.TP +\fBNUMERIC\fP (integer) +The numeric argument\&. If no numeric argument was given, this parameter +is unset\&. When this is set inside a widget function, builtin widgets +called with the \fBzle\fP builtin command will use the value +assigned\&. If it is unset inside a widget function, builtin widgets +called behave as if no numeric argument was given\&. +.TP +\fBPENDING\fP (integer) +The number of bytes pending for input, i\&.e\&. the number of bytes which have +already been typed and can immediately be read\&. On systems where the shell +is not able to get this information, this parameter will always have a +value of zero\&. Read\-only\&. See also \fBKEYS_QUEUED_COUNT\fP; the two +values are distinct\&. +.TP +\fBPREBUFFER\fP (scalar) +In a multi\-line input at the secondary prompt, this read\-only parameter +contains the contents of the lines before the one the cursor is +currently in\&. +.TP +\fBPREDISPLAY\fP (scalar) +Text to be displayed before the start of the editable text buffer\&. This +does not have to be a complete line; to display a complete line, a newline +must be appended explicitly\&. The text is reset on each new invocation +(but not recursive invocation) of zle\&. +.TP +\fBPOSTDISPLAY\fP (scalar) +Text to be displayed after the end of the editable text buffer\&. This +does not have to be a complete line; to display a complete line, a newline +must be prepended explicitly\&. The text is reset on each new invocation +(but not recursive invocation) of zle\&. +.TP +\fBRBUFFER\fP (scalar) +The part of the buffer that lies to the right of the cursor position\&. +If it is assigned to, only that part of the buffer is replaced, and the +cursor remains between the old \fB$LBUFFER\fP and the new \fB$RBUFFER\fP\&. +.TP +\fBREGION_ACTIVE\fP (integer) +Indicates if the region is currently active\&. It can be assigned 0 or 1 +to deactivate and activate the region respectively\&. A value of 2 +activates the region in line\-wise mode with the highlighted text +extending for whole lines only; see +\fICharacter Highlighting\fP below\&. +.TP +\fBregion_highlight\fP (array) +Each element of this array may be set to a string that describes +highlighting for an arbitrary region of the command line that will +take effect the next time the command line is redisplayed\&. Highlighting +of the non\-editable parts of the command line in \fBPREDISPLAY\fP +and \fBPOSTDISPLAY\fP are possible, but note that the \fBP\fP flag +is needed for character indexing to include \fBPREDISPLAY\fP\&. +.RS +.PP +Each string consists of the following parts: +.PP +.PD 0 +.TP +.PD +\(bu +Optionally, a `\fBP\fP\&' to signify that the start and end offset that +follow include any string set by the \fBPREDISPLAY\fP special parameter; +this is needed if the predisplay string itself is to be highlighted\&. +Whitespace may follow the `\fBP\fP\&'\&. +.TP +\(bu +A start offset in the same units as \fBCURSOR\fP, terminated by +whitespace\&. +.TP +\(bu +An end offset in the same units as \fBCURSOR\fP, terminated by +whitespace\&. +.TP +\(bu +A highlight specification in the same format as +used for contexts in the parameter \fBzle_highlight\fP, see +the section `Character Highlighting\&' below; +for example, \fBstandout\fP or \fBfg=red,bold\fP +.PP +For example, +.PP +.RS +.nf +\fBregion_highlight=("P0 20 bold")\fP +.fi +.RE +.PP +specifies that the first twenty characters of the text including +any predisplay string should be highlighted in bold\&. +.PP +Note that the effect of \fBregion_highlight\fP is not saved and disappears +as soon as the line is accepted\&. +.PP +The final highlighting on the command line depends on both \fBregion_highlight\fP +and \fBzle_highlight\fP; see +the section CHARACTER HIGHLIGHTING below for details\&. +.RE +.TP +\fBregisters\fP (associative array) +The contents of each of the vi register buffers\&. These are +typically set using \fBvi\-set\-buffer\fP followed by a delete, change or +yank command\&. +.TP +.PD 0 +\fBSUFFIX_ACTIVE\fP (integer) +.TP +.PD 0 +\fBSUFFIX_START\fP (integer) +.TP +.PD +\fBSUFFIX_END\fP (integer) +\fBSUFFIX_ACTIVE\fP indicates whether an auto\-removable completion suffix +is currently active\&. \fBSUFFIX_START\fP and \fBSUFFIX_END\fP give the +location of the suffix and are in the same units as \fBCURSOR\fP\&. They are +only valid for reading when \fBSUFFIX_ACTIVE\fP is non\-zero\&. +.RS +.PP +All parameters are read\-only\&. +.RE +.TP +\fBUNDO_CHANGE_NO\fP (integer) +A number representing the state of the undo history\&. The only use +of this is passing as an argument to the \fBundo\fP widget in order to +undo back to the recorded point\&. Read\-only\&. +.TP +\fBUNDO_LIMIT_NO\fP (integer) +A number corresponding to an existing change in the undo history; +compare \fBUNDO_CHANGE_NO\fP\&. If this is set to a value greater +than zero, the \fBundo\fP command will not allow the line to +be undone beyond the given change number\&. It is still possible +to use `\fBzle undo\fP \fIchange\fP\&' in a widget to undo beyond +that point; in that case, it will not be possible to undo at +all until \fBUNDO_LIMIT_NO\fP is reduced\&. Set to 0 to disable the limit\&. +.RS +.PP +A typical use of this variable in a widget function is as follows (note +the additional function scope is required): +.PP +.RS +.nf +\fB() { + local UNDO_LIMIT_NO=$UNDO_CHANGE_NO + # Perform some form of recursive edit\&. +}\fP +.fi +.RE +.RE +.TP +\fBWIDGET\fP (scalar) +The name of the widget currently being executed; read\-only\&. +.TP +\fBWIDGETFUNC\fP (scalar) +The name of the shell function that implements a widget defined with +either \fBzle \-N\fP or \fBzle \-C\fP\&. In the former case, this is the second +argument to the \fBzle \-N\fP command that defined the widget, or +the first argument if there was no second argument\&. In the latter case +this is the third argument to the \fBzle \-C\fP command that defined the +widget\&. Read\-only\&. +.TP +\fBWIDGETSTYLE\fP (scalar) +Describes the implementation behind the completion widget currently being +executed; the second argument that followed \fBzle \-C\fP when the widget was +defined\&. This is the name of a builtin completion widget\&. For widgets +defined with \fBzle \-N\fP this is set to the empty string\&. Read\-only\&. +.TP +.PD 0 +\fBYANK_ACTIVE\fP (integer) +.TP +.PD 0 +\fBYANK_START\fP (integer) +.TP +.PD +\fBYANK_END\fP (integer) +\fBYANK_ACTIVE\fP indicates whether text has just been yanked (pasted) +into the buffer\&. \fBYANK_START\fP and \fBYANK_END\fP give the location of +the pasted text and are in the same units as \fBCURSOR\fP\&. They are only +valid for reading when \fBYANK_ACTIVE\fP is non\-zero\&. They can also be +assigned by widgets that insert text in a yank\-like fashion, for example +wrappers of \fBbracketed\-paste\fP\&. See also \fBzle \-f\fP\&. +.RS +.PP +\fBYANK_ACTIVE\fP is read\-only\&. +.RE +.TP +\fBZLE_RECURSIVE\fP (integer) +Usually zero, but incremented inside any instance of +\fBrecursive\-edit\fP\&. Hence indicates the current recursion level\&. +.RS +.PP +\fBZLE_RECURSIVE\fP is read\-only\&. +.RE +.TP +\fBZLE_STATE\fP (scalar) +Contains a set of space\-separated words that describe the current \fBzle\fP +state\&. +.RS +.PP +Currently, the states shown are the insert mode as set by the +\fBoverwrite\-mode\fP or \fBvi\-replace\fP widgets and whether history commands +will visit imported entries as controlled by the set\-local\-history widget\&. +The string contains `\fBinsert\fP\&' if characters to be inserted on the +command line move existing characters to the right or `\fBoverwrite\fP\&' +if characters to be inserted overwrite existing characters\&. It contains +`\fBlocalhistory\fP\&' if only local history commands will be visited or +`\fBglobalhistory\fP\&' if imported history commands will also be visited\&. +.PP +The substrings are sorted in alphabetical order so that if you want to +test for two specific substrings in a future\-proof way, you can do match +by doing: +.PP +.RS +.nf +\fBif [[ $ZLE_STATE == *globalhistory*insert* ]]; then \&.\&.\&.; fi\fP +.fi +.RE +.RE +.PP +.SS "Special Widgets" +.PP +There are a few user\-defined widgets which are special to the shell\&. +If they do not exist, no special action is taken\&. The environment +provided is identical to that for any other editing widget\&. +.PP +.PD 0 +.TP +.PD +\fBzle\-isearch\-exit\fP +Executed at the end of incremental search at the point where the isearch +prompt is removed from the display\&. See \fBzle\-isearch\-update\fP for +an example\&. +.TP +\fBzle\-isearch\-update\fP +Executed within incremental search when the display is about to be +redrawn\&. Additional output below the incremental search prompt can be +generated by using `\fBzle \-M\fP\&' within the widget\&. For example, +.RS +.PP +.RS +.nf +\fBzle\-isearch\-update() { zle \-M "Line $HISTNO"; } +zle \-N zle\-isearch\-update\fP +.fi +.RE +.PP +Note the line output by `\fBzle \-M\fP\&' is not deleted on exit from +incremental search\&. This can be done from a \fBzle\-isearch\-exit\fP +widget: +.PP +.RS +.nf +\fBzle\-isearch\-exit() { zle \-M ""; } +zle \-N zle\-isearch\-exit\fP +.fi +.RE +.RE +.TP +\fBzle\-line\-pre\-redraw\fP +Executed whenever the input line is about to be redrawn, providing an +opportunity to update the region_highlight array\&. +.TP +\fBzle\-line\-init\fP +Executed every time the line editor is started to read a new line +of input\&. The following example puts the line editor into vi command +mode when it starts up\&. +.RS +.PP +.RS +.nf +\fBzle\-line\-init() { zle \-K vicmd; } +zle \-N zle\-line\-init\fP +.fi +.RE +.PP +(The command inside the function sets the keymap directly; it is +equivalent to \fBzle vi\-cmd\-mode\fP\&.) +.RE +.TP +\fBzle\-line\-finish\fP +This is similar to \fBzle\-line\-init\fP but is executed every time the +line editor has finished reading a line of input\&. +.TP +\fBzle\-history\-line\-set\fP +Executed when the history line changes\&. +.TP +\fBzle\-keymap\-select\fP +Executed every time the keymap changes, i\&.e\&. the special parameter +\fBKEYMAP\fP is set to a different value, while the line editor is active\&. +Initialising the keymap when the line editor starts does not cause the +widget to be called\&. +.RS +.PP +The value \fB$KEYMAP\fP within the function reflects the new keymap\&. The +old keymap is passed as the sole argument\&. +.PP +This can be used for detecting switches between the vi command +(\fBvicmd\fP) and insert (usually \fBmain\fP) keymaps\&. +.RE +.PP +.SH "STANDARD WIDGETS" +The following is a list of all the standard widgets, +and their default bindings in emacs mode, +vi command mode and vi insert mode +(the `\fBemacs\fP\&', `\fBvicmd\fP' and `\fBviins\fP' keymaps, respectively)\&. +.PP +Note that cursor keys are bound to movement keys in all three keymaps; +the shell assumes that the cursor keys send the key sequences reported +by the terminal\-handling library (termcap or terminfo)\&. The key sequences +shown in the list are those based on the VT100, common on many modern +terminals, but in fact these are not necessarily bound\&. In the case of the +\fBviins\fP keymap, the initial escape character of the sequences serves also +to return to the \fBvicmd\fP keymap: whether this happens is determined by +the \fBKEYTIMEOUT\fP parameter, see \fIzshparam\fP(1)\&. +.SS "Movement" +.PD 0 +.TP +.PD +\fBvi\-backward\-blank\-word\fP (unbound) (\fBB\fP) (unbound) +Move backward one word, where a word is defined as a series of +non\-blank characters\&. +.TP +\fBvi\-backward\-blank\-word\-end\fP (unbound) (\fBgE\fP) (unbound) +Move to the end of the previous word, where a word is defined as a +series of non\-blank characters\&. +.TP +\fBbackward\-char\fP (\fB^B ESC\-[D\fP) (unbound) (unbound) +Move backward one character\&. +.TP +\fBvi\-backward\-char\fP (unbound) (\fB^H h ^?\fP) (\fBESC\-[D\fP) +Move backward one character, without changing lines\&. +.TP +\fBbackward\-word\fP (\fBESC\-B ESC\-b\fP) (unbound) (unbound) +Move to the beginning of the previous word\&. +.TP +\fBemacs\-backward\-word\fP +Move to the beginning of the previous word\&. +.TP +\fBvi\-backward\-word\fP (unbound) (\fBb\fP) (unbound) +Move to the beginning of the previous word, vi\-style\&. +.TP +\fBvi\-backward\-word\-end\fP (unbound) (\fBge\fP) (unbound) +Move to the end of the previous word, vi\-style\&. +.TP +\fBbeginning\-of\-line\fP (\fB^A\fP) (unbound) (unbound) +Move to the beginning of the line\&. If already at the beginning +of the line, move to the beginning of the previous line, if any\&. +.TP +\fBvi\-beginning\-of\-line\fP +Move to the beginning of the line, without changing lines\&. +.TP +\fBdown\-line\fP (unbound) (unbound) (unbound) +Move down a line in the buffer\&. +.TP +\fBend\-of\-line\fP (\fB^E\fP) (unbound) (unbound) +Move to the end of the line\&. If already at the end +of the line, move to the end of the next line, if any\&. +.TP +\fBvi\-end\-of\-line\fP (unbound) (\fB$\fP) (unbound) +Move to the end of the line\&. +If an argument is given to this command, the cursor will be moved to +the end of the line (argument \- 1) lines down\&. +.TP +\fBvi\-forward\-blank\-word\fP (unbound) (\fBW\fP) (unbound) +Move forward one word, where a word is defined as a series of +non\-blank characters\&. +.TP +\fBvi\-forward\-blank\-word\-end\fP (unbound) (\fBE\fP) (unbound) +Move to the end of the current word, or, if at the end of the current word, +to the end of the next word, +where a word is defined as a series of non\-blank characters\&. +.TP +\fBforward\-char\fP (\fB^F ESC\-[C\fP) (unbound) (unbound) +Move forward one character\&. +.TP +\fBvi\-forward\-char\fP (unbound) (\fBspace l\fP) (\fBESC\-[C\fP) +Move forward one character\&. +.TP +\fBvi\-find\-next\-char\fP (\fB^X^F\fP) (\fBf\fP) (unbound) +Read a character from the keyboard, and move to +the next occurrence of it in the line\&. +.TP +\fBvi\-find\-next\-char\-skip\fP (unbound) (\fBt\fP) (unbound) +Read a character from the keyboard, and move to +the position just before the next occurrence of it in the line\&. +.TP +\fBvi\-find\-prev\-char\fP (unbound) (\fBF\fP) (unbound) +Read a character from the keyboard, and move to +the previous occurrence of it in the line\&. +.TP +\fBvi\-find\-prev\-char\-skip\fP (unbound) (\fBT\fP) (unbound) +Read a character from the keyboard, and move to +the position just after the previous occurrence of it in the line\&. +.TP +\fBvi\-first\-non\-blank\fP (unbound) (\fB^\fP) (unbound) +Move to the first non\-blank character in the line\&. +.TP +\fBvi\-forward\-word\fP (unbound) (\fBw\fP) (unbound) +Move forward one word, vi\-style\&. +.TP +\fBforward\-word\fP (\fBESC\-F ESC\-f\fP) (unbound) (unbound) +Move to the beginning of the next word\&. +The editor\&'s idea of a word is specified with the \fBWORDCHARS\fP +parameter\&. +.TP +\fBemacs\-forward\-word\fP +Move to the end of the next word\&. +.TP +\fBvi\-forward\-word\-end\fP (unbound) (\fBe\fP) (unbound) +Move to the end of the next word\&. +.TP +\fBvi\-goto\-column\fP (\fBESC\-|\fP) (\fB|\fP) (unbound) +Move to the column specified by the numeric argument\&. +.TP +\fBvi\-goto\-mark\fP (unbound) (\fB`\fP) (unbound) +Move to the specified mark\&. +.TP +\fBvi\-goto\-mark\-line\fP (unbound) (\fB\&'\fP) (unbound) +Move to beginning of the line containing the specified mark\&. +.TP +\fBvi\-repeat\-find\fP (unbound) (\fB;\fP) (unbound) +Repeat the last \fBvi\-find\fP command\&. +.TP +\fBvi\-rev\-repeat\-find\fP (unbound) (\fB,\fP) (unbound) +Repeat the last \fBvi\-find\fP command in the opposite direction\&. +.TP +\fBup\-line\fP (unbound) (unbound) (unbound) +Move up a line in the buffer\&. +.SS "History Control" +.PD 0 +.TP +.PD +\fBbeginning\-of\-buffer\-or\-history\fP (\fBESC\-<\fP) (\fBgg\fP) (unbound) +Move to the beginning of the buffer, or if already there, +move to the first event in the history list\&. +.TP +\fBbeginning\-of\-line\-hist\fP +Move to the beginning of the line\&. If already at the +beginning of the buffer, move to the previous history line\&. +.TP +\fBbeginning\-of\-history\fP +Move to the first event in the history list\&. +.TP +\fBdown\-line\-or\-history\fP (\fB^N ESC\-[B\fP) (\fBj\fP) (\fBESC\-[B\fP) +Move down a line in the buffer, or if already at the bottom line, +move to the next event in the history list\&. +.TP +\fBvi\-down\-line\-or\-history\fP (unbound) (\fB+\fP) (unbound) +Move down a line in the buffer, or if already at the bottom line, +move to the next event in the history list\&. +Then move to the first non\-blank character on the line\&. +.TP +\fBdown\-line\-or\-search\fP +Move down a line in the buffer, or if already at the bottom line, +search forward in the history for a line beginning with the first +word in the buffer\&. +.RS +.PP +If called from a function by the \fBzle\fP command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer\&. +.RE +.TP +\fBdown\-history\fP (unbound) (\fB^N\fP) (unbound) +Move to the next event in the history list\&. +.TP +\fBhistory\-beginning\-search\-backward\fP +Search backward in the history for a line beginning with the current +line up to the cursor\&. +This leaves the cursor in its original position\&. +.TP +\fBend\-of\-buffer\-or\-history\fP (\fBESC\->\fP) (unbound) (unbound) +Move to the end of the buffer, or if already there, +move to the last event in the history list\&. +.TP +\fBend\-of\-line\-hist\fP +Move to the end of the line\&. If already at the end of +the buffer, move to the next history line\&. +.TP +\fBend\-of\-history\fP +Move to the last event in the history list\&. +.TP +\fBvi\-fetch\-history\fP (unbound) (\fBG\fP) (unbound) +Fetch the history line specified by the numeric argument\&. +This defaults to the current history line +(i\&.e\&. the one that isn\&'t history yet)\&. +.TP +\fBhistory\-incremental\-search\-backward\fP (\fB^R ^Xr\fP) (unbound) (unbound) +Search backward incrementally for a specified string\&. The search is +case\-insensitive if the search string does not have uppercase letters and no +numeric argument was given\&. The string may begin with `\fB^\fP\&' to anchor the +search to the beginning of the line\&. When called from a user\-defined +function returns the following statuses: 0, if the search succeeded; +1, if the search failed; 2, if the search term was a bad pattern; +3, if the search was aborted by the \fBsend\-break\fP command\&. +.RS +.PP +A restricted set of editing functions +is available in the mini\-buffer\&. Keys are looked up in the special +\fBisearch\fP keymap, and if not found there in the main keymap (note +that by default the \fBisearch\fP keymap is empty)\&. +An interrupt signal, as defined by the stty +setting, will stop the search and go back to the original line\&. An undefined +key will have the same effect\&. Note that the following always +perform the same task within incremental searches and cannot be +replaced by user defined widgets, nor can the set of functions +be extended\&. The supported functions are: +.PP +.PD 0 +.TP +.PD 0 +\fBaccept\-and\-hold\fP +.TP +.PD 0 +\fBaccept\-and\-infer\-next\-history\fP +.TP +.PD 0 +\fBaccept\-line\fP +.TP +.PD +\fBaccept\-line\-and\-down\-history\fP +Perform the usual function after exiting incremental search\&. +The command line displayed is executed\&. +.TP +.PD 0 +\fBbackward\-delete\-char\fP +.TP +.PD +\fBvi\-backward\-delete\-char\fP +Back up one place in the search history\&. If the search has been +repeated this does not immediately erase a character in the +minibuffer\&. +.TP +\fBaccept\-search\fP +Exit incremental search, retaining the command line but performing no +further action\&. Note that this function is not bound by default +and has no effect outside incremental search\&. +.TP +.PD 0 +\fBbackward\-delete\-word\fP +.TP +.PD 0 +\fBbackward\-kill\-word\fP +.TP +.PD +\fBvi\-backward\-kill\-word\fP +Back up one character in the minibuffer; if multiple searches +have been performed since the character was inserted the search +history is rewound to the point just before the character was +entered\&. Hence this has the effect of repeating +\fBbackward\-delete\-char\fP\&. +.TP +\fBclear\-screen\fP +Clear the screen, remaining in incremental search mode\&. +.TP +\fBhistory\-incremental\-search\-backward\fP +Find the next occurrence of the contents of the mini\-buffer\&. If the +mini\-buffer is empty, the most recent previously used search string is +reinstated\&. +.TP +\fBhistory\-incremental\-search\-forward\fP +Invert the sense of the search\&. +.TP +\fBmagic\-space\fP +Inserts a non\-magical space\&. +.TP +.PD 0 +\fBquoted\-insert\fP +.TP +.PD +\fBvi\-quoted\-insert\fP +Quote the character to insert into the minibuffer\&. +.TP +\fBredisplay\fP +Redisplay the command line, remaining in incremental search mode\&. +.TP +\fBvi\-cmd\-mode\fP +Select the `\fBvicmd\fP\&' keymap; +the `\fBmain\fP\&' keymap (insert mode) will be selected initially\&. +.RS +.PP +In addition, the modifications that were made while in vi insert mode are +merged to form a single undo event\&. +.RE +.TP +.PD 0 +\fBvi\-repeat\-search\fP +.TP +.PD +\fBvi\-rev\-repeat\-search\fP +Repeat the search\&. The direction of the search is indicated in the +mini\-buffer\&. +.PP +Any character that is not bound to one of the above functions, or +\fBself\-insert\fP or \fBself\-insert\-unmeta\fP, will cause the mode to be +exited\&. The character is then looked up and executed in the keymap in +effect at that point\&. +.PP +When called from a widget function by the \fBzle\fP command, the incremental +search commands can take a string argument\&. This will be treated as a +string of keys, as for arguments to the \fBbindkey\fP command, and used as +initial input for the command\&. Any characters in the string which are +unused by the incremental search will be silently ignored\&. For example, +.PP +.RS +.nf +\fBzle history\-incremental\-search\-backward forceps\fP +.fi +.RE +.PP +will search backwards for \fBforceps\fP, leaving the minibuffer containing +the string `\fBforceps\fP\&'\&. +.RE +.TP +\fBhistory\-incremental\-search\-forward\fP (\fB^S ^Xs\fP) (unbound) (unbound) +Search forward incrementally for a specified string\&. The search is +case\-insensitive if the search string does not have uppercase letters and no +numeric argument was given\&. The string may begin with `\fB^\fP\&' to anchor the +search to the beginning of the line\&. The functions available in the +mini\-buffer are the same as for \fBhistory\-incremental\-search\-backward\fP\&. +.TP +.PD 0 +\fBhistory\-incremental\-pattern\-search\-backward\fP +.TP +.PD +\fBhistory\-incremental\-pattern\-search\-forward\fP +These widgets behave similarly to the corresponding widgets with +no \fB\-pattern\fP, but the search string typed by the user is treated +as a pattern, respecting the current settings of the various options +affecting pattern matching\&. See +FILENAME GENERATION in \fIzshexpn\fP(1) for a description of patterns\&. +If no numeric argument was given lowercase letters in the search +string may match uppercase letters in the history\&. The string may begin +with `\fB^\fP\&' to anchor the search to the beginning of the line\&. +.RS +.PP +The prompt changes to indicate an invalid pattern; this may simply +indicate the pattern is not yet complete\&. +.PP +Note that only non\-overlapping matches are reported, so an expression +with wildcards may return fewer matches on a line than are visible +by inspection\&. +.RE +.TP +\fBhistory\-search\-backward\fP (\fBESC\-P ESC\-p\fP) (unbound) (unbound) +Search backward in the history for a line beginning with the first +word in the buffer\&. +.RS +.PP +If called from a function by the \fBzle\fP command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer\&. +.RE +.TP +\fBvi\-history\-search\-backward\fP (unbound) (\fB/\fP) (unbound) +Search backward in the history for a specified string\&. +The string may begin with `\fB^\fP\&' to anchor the search to the +beginning of the line\&. +.RS +.PP +A restricted set of editing functions is available in +the mini\-buffer\&. An interrupt signal, as defined by the stty setting, will +stop the search\&. +The functions available in the mini\-buffer are: +\fBaccept\-line\fP, +\fBbackward\-delete\-char\fP, +\fBvi\-backward\-delete\-char\fP, +\fBbackward\-kill\-word\fP, +\fBvi\-backward\-kill\-word\fP, +\fBclear\-screen\fP, +\fBredisplay\fP, +\fBquoted\-insert\fP +and +\fBvi\-quoted\-insert\fP\&. +.PP +\fBvi\-cmd\-mode\fP is treated the same as accept\-line, and +\fBmagic\-space\fP is treated as a space\&. +Any other character that is not bound to self\-insert or +self\-insert\-unmeta will beep and be ignored\&. If the function is called from vi +command mode, the bindings of the current insert mode will be used\&. +.PP +If called from a function by the \fBzle\fP command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer\&. +.RE +.TP +\fBhistory\-search\-forward\fP (\fBESC\-N ESC\-n\fP) (unbound) (unbound) +Search forward in the history for a line beginning with the first +word in the buffer\&. +.RS +.PP +If called from a function by the \fBzle\fP command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer\&. +.RE +.TP +\fBvi\-history\-search\-forward\fP (unbound) (\fB?\fP) (unbound) +Search forward in the history for a specified string\&. +The string may begin with `\fB^\fP\&' to anchor the search to the +beginning of the line\&. The functions available in the mini\-buffer are the same +as for \fBvi\-history\-search\-backward\fP\&. Argument handling is also the same +as for that command\&. +.TP +\fBinfer\-next\-history\fP (\fB^X^N\fP) (unbound) (unbound) +Search in the history list for a line matching the current one and +fetch the event following it\&. +.TP +\fBinsert\-last\-word\fP (\fBESC\-_ ESC\-\&.\fP) (unbound) (unbound) +Insert the last word from the previous history event at the +cursor position\&. If a positive numeric argument is given, +insert that word from the end of the previous history event\&. +If the argument is zero or negative insert that word from the +left (zero inserts the previous command word)\&. Repeating this command +replaces the word just inserted with the last word from the +history event prior to the one just used; numeric arguments can be used in +the same way to pick a word from that event\&. +.RS +.PP +When called from a shell function invoked from a user\-defined widget, the +command can take one to three arguments\&. The first argument specifies a +history offset which applies to successive calls to this widget: if it is \-1, +the default behaviour is used, while if it is 1, successive calls will move +forwards through the history\&. The value 0 can be used to indicate that the +history line examined by the previous execution of the command will be +reexamined\&. Note that negative numbers should be preceded by a +`\fB\-\fP\fB\-\fP\&' argument to avoid confusing them with options\&. +.PP +If two arguments are given, the second specifies the word on the command +line in normal array index notation (as a more natural alternative to the +numeric argument)\&. Hence 1 is the first word, and \-1 (the default) is the +last word\&. +.PP +If a third argument is given, its value is ignored, but it is used to +signify that the history offset is relative to the current history line, +rather than the one remembered after the previous invocations of +\fBinsert\-last\-word\fP\&. +.PP +For example, the default behaviour of the command corresponds to +.PP +.RS +.nf +\fBzle insert\-last\-word \-\- \-1 \-1\fP +.fi +.RE +.PP +while the command +.PP +.RS +.nf +\fBzle insert\-last\-word \-\- \-1 1 \-\fP +.fi +.RE +.PP +always copies the first word of the line in the history immediately before +the line being edited\&. This has the side effect that later invocations of +the widget will be relative to that line\&. +.RE +.TP +\fBvi\-repeat\-search\fP (unbound) (\fBn\fP) (unbound) +Repeat the last vi history search\&. +.TP +\fBvi\-rev\-repeat\-search\fP (unbound) (\fBN\fP) (unbound) +Repeat the last vi history search, but in reverse\&. +.TP +\fBup\-line\-or\-history\fP (\fB^P ESC\-[A\fP) (\fBk\fP) (\fBESC\-[A\fP) +Move up a line in the buffer, or if already at the top line, +move to the previous event in the history list\&. +.TP +\fBvi\-up\-line\-or\-history\fP (unbound) (\fB\-\fP) (unbound) +Move up a line in the buffer, or if already at the top line, +move to the previous event in the history list\&. +Then move to the first non\-blank character on the line\&. +.TP +\fBup\-line\-or\-search\fP +Move up a line in the buffer, or if already at the top line, +search backward in the history for a line beginning with the +first word in the buffer\&. +.RS +.PP +If called from a function by the \fBzle\fP command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer\&. +.RE +.TP +\fBup\-history\fP (unbound) (\fB^P\fP) (unbound) +Move to the previous event in the history list\&. +.TP +\fBhistory\-beginning\-search\-forward\fP +Search forward in the history for a line beginning with the current +line up to the cursor\&. +This leaves the cursor in its original position\&. +.TP +\fBset\-local\-history\fP +By default, history movement commands visit the imported lines as well as +the local lines\&. This widget lets you toggle this on and off, or set it with +the numeric argument\&. Zero for both local and imported lines and nonzero for +only local lines\&. +.SS "Modifying Text" +.PD 0 +.TP +.PD +\fBvi\-add\-eol\fP (unbound) (\fBA\fP) (unbound) +Move to the end of the line and enter insert mode\&. +.TP +\fBvi\-add\-next\fP (unbound) (\fBa\fP) (unbound) +Enter insert mode after the current cursor position, without changing lines\&. +.TP +\fBbackward\-delete\-char\fP (\fB^H ^?\fP) (unbound) (unbound) +Delete the character behind the cursor\&. +.TP +\fBvi\-backward\-delete\-char\fP (unbound) (\fBX\fP) (\fB^H\fP) +Delete the character behind the cursor, without changing lines\&. +If in insert mode, this won\&'t delete past the point where insert mode was +last entered\&. +.TP +\fBbackward\-delete\-word\fP +Delete the word behind the cursor\&. +.TP +\fBbackward\-kill\-line\fP +Kill from the beginning of the line to the cursor position\&. +.TP +\fBbackward\-kill\-word\fP (\fB^W ESC\-^H ESC\-^?\fP) (unbound) (unbound) +Kill the word behind the cursor\&. +.TP +\fBvi\-backward\-kill\-word\fP (unbound) (unbound) (\fB^W\fP) +Kill the word behind the cursor, without going past the point where insert +mode was last entered\&. +.TP +\fBcapitalize\-word\fP (\fBESC\-C ESC\-c\fP) (unbound) (unbound) +Capitalize the current word and move past it\&. +.TP +\fBvi\-change\fP (unbound) (\fBc\fP) (unbound) +Read a movement command from the keyboard, and kill +from the cursor position to the endpoint of the movement\&. +Then enter insert mode\&. +If the command is \fBvi\-change\fP, change the current line\&. +.RS +.PP +For compatibility with vi, if the command is \fBvi\-forward\-word\fP +or \fBvi\-forward\-blank\-word\fP, the whitespace after the word is not +included\&. If you prefer the more consistent behaviour with the +whitespace included use the following key binding: +.PP +.RS +.nf +\fBbindkey \-a \-s cw dwi\fP +.fi +.RE +.RE +.TP +\fBvi\-change\-eol\fP (unbound) (\fBC\fP) (unbound) +Kill to the end of the line and enter insert mode\&. +.TP +\fBvi\-change\-whole\-line\fP (unbound) (\fBS\fP) (unbound) +Kill the current line and enter insert mode\&. +.TP +\fBcopy\-region\-as\-kill\fP (\fBESC\-W ESC\-w\fP) (unbound) (unbound) +Copy the area from the cursor to the mark to the kill buffer\&. +.RS +.PP +If called from a ZLE widget function in the form `\fBzle +copy\-region\-as\-kill\fP \fIstring\fP\&' then \fIstring\fP will be taken as the +text to copy to the kill buffer\&. The cursor, the mark and the text on the +command line are not used in this case\&. +.RE +.TP +\fBcopy\-prev\-word\fP (\fBESC\-^_\fP) (unbound) (unbound) +Duplicate the word to the left of the cursor\&. +.TP +\fBcopy\-prev\-shell\-word\fP +Like \fBcopy\-prev\-word\fP, but the word is found by using shell parsing, +whereas \fBcopy\-prev\-word\fP looks for blanks\&. This makes a difference +when the word is quoted and contains spaces\&. +.TP +\fBvi\-delete\fP (unbound) (\fBd\fP) (unbound) +Read a movement command from the keyboard, and kill +from the cursor position to the endpoint of the movement\&. +If the command is \fBvi\-delete\fP, kill the current line\&. +.TP +\fBdelete\-char\fP +Delete the character under the cursor\&. +.TP +\fBvi\-delete\-char\fP (unbound) (\fBx\fP) (unbound) +Delete the character under the cursor, +without going past the end of the line\&. +.TP +\fBdelete\-word\fP +Delete the current word\&. +.TP +\fBdown\-case\-word\fP (\fBESC\-L ESC\-l\fP) (unbound) (unbound) +Convert the current word to all lowercase and move past it\&. +.TP +\fBvi\-down\-case\fP (unbound) (\fBgu\fP) (unbound) +Read a movement command from the keyboard, and convert all characters +from the cursor position to the endpoint of the movement to lowercase\&. +If the movement command is \fBvi\-down\-case\fP, swap the case of all +characters on the current line\&. +.TP +\fBkill\-word\fP (\fBESC\-D ESC\-d\fP) (unbound) (unbound) +Kill the current word\&. +.TP +\fBgosmacs\-transpose\-chars\fP +Exchange the two characters behind the cursor\&. +.TP +\fBvi\-indent\fP (unbound) (\fB>\fP) (unbound) +Indent a number of lines\&. +.TP +\fBvi\-insert\fP (unbound) (\fBi\fP) (unbound) +Enter insert mode\&. +.TP +\fBvi\-insert\-bol\fP (unbound) (\fBI\fP) (unbound) +Move to the first non\-blank character on the line and enter insert mode\&. +.TP +\fBvi\-join\fP (\fB^X^J\fP) (\fBJ\fP) (unbound) +Join the current line with the next one\&. +.TP +\fBkill\-line\fP (\fB^K\fP) (unbound) (unbound) +Kill from the cursor to the end of the line\&. +If already on the end of the line, kill the newline character\&. +.TP +\fBvi\-kill\-line\fP (unbound) (unbound) (\fB^U\fP) +Kill from the cursor back to wherever insert mode was last entered\&. +.TP +\fBvi\-kill\-eol\fP (unbound) (\fBD\fP) (unbound) +Kill from the cursor to the end of the line\&. +.TP +\fBkill\-region\fP +Kill from the cursor to the mark\&. +.TP +\fBkill\-buffer\fP (\fB^X^K\fP) (unbound) (unbound) +Kill the entire buffer\&. +.TP +\fBkill\-whole\-line\fP (\fB^U\fP) (unbound) (unbound) +Kill the current line\&. +.TP +\fBvi\-match\-bracket\fP (\fB^X^B\fP) (\fB%\fP) (unbound) +Move to the bracket character (one of \fB{}\fP, \fB()\fP or \fB[]\fP) that +matches the one under the cursor\&. +If the cursor is not on a bracket character, move forward without going +past the end of the line to find one, and then go to the matching bracket\&. +.TP +\fBvi\-open\-line\-above\fP (unbound) (\fBO\fP) (unbound) +Open a line above the cursor and enter insert mode\&. +.TP +\fBvi\-open\-line\-below\fP (unbound) (\fBo\fP) (unbound) +Open a line below the cursor and enter insert mode\&. +.TP +\fBvi\-oper\-swap\-case\fP (unbound) (\fBg~\fP) (unbound) +Read a movement command from the keyboard, and swap +the case of all characters +from the cursor position to the endpoint of the movement\&. +If the movement command is \fBvi\-oper\-swap\-case\fP, +swap the case of all characters on the current line\&. +.TP +\fBoverwrite\-mode\fP (\fB^X^O\fP) (unbound) (unbound) +Toggle between overwrite mode and insert mode\&. +.TP +\fBvi\-put\-before\fP (unbound) (\fBP\fP) (unbound) +Insert the contents of the kill buffer before the cursor\&. +If the kill buffer contains a sequence of lines (as opposed to characters), +paste it above the current line\&. +.TP +\fBvi\-put\-after\fP (unbound) (\fBp\fP) (unbound) +Insert the contents of the kill buffer after the cursor\&. +If the kill buffer contains a sequence of lines (as opposed to characters), +paste it below the current line\&. +.TP +\fBput\-replace\-selection\fP (unbound) (unbound) (unbound) +Replace the contents of the current region or selection with the +contents of the kill buffer\&. If the kill buffer contains a sequence of +lines (as opposed to characters), the current line will be split by the +pasted lines\&. +.TP +\fBquoted\-insert\fP (\fB^V\fP) (unbound) (unbound) +Insert the next character typed into the buffer literally\&. +An interrupt character will not be inserted\&. +.TP +\fBvi\-quoted\-insert\fP (unbound) (unbound) (\fB^Q ^V\fP) +Display a `\fB^\fP\&' at the cursor position, and +insert the next character typed into the buffer literally\&. +An interrupt character will not be inserted\&. +.TP +\fBquote\-line\fP (\fBESC\-\&'\fP) (unbound) (unbound) +Quote the current line; that is, put a `\fB\&'\fP' character at the +beginning and the end, and convert all `\fB\&'\fP' characters +to `\fB\&'\e''\fP'\&. +.TP +\fBquote\-region\fP (\fBESC\-"\fP) (unbound) (unbound) +Quote the region from the cursor to the mark\&. +.TP +\fBvi\-replace\fP (unbound) (\fBR\fP) (unbound) +Enter overwrite mode\&. +.TP +\fBvi\-repeat\-change\fP (unbound) (\fB\&.\fP) (unbound) +Repeat the last vi mode text modification\&. +If a count was used with the modification, it is remembered\&. +If a count is given to this command, it overrides the remembered count, +and is remembered for future uses of this command\&. +The cut buffer specification is similarly remembered\&. +.TP +\fBvi\-replace\-chars\fP (unbound) (\fBr\fP) (unbound) +Replace the character under the cursor with a character +read from the keyboard\&. +.TP +\fBself\-insert\fP (printable characters) (unbound) (printable characters and some control characters) +Insert a character into the buffer at the cursor position\&. +.TP +\fBself\-insert\-unmeta\fP (\fBESC\-^I ESC\-^J ESC\-^M\fP) (unbound) (unbound) +Insert a character into the buffer after stripping the meta bit +and converting ^M to ^J\&. +.TP +\fBvi\-substitute\fP (unbound) (\fBs\fP) (unbound) +Substitute the next character(s)\&. +.TP +\fBvi\-swap\-case\fP (unbound) (\fB~\fP) (unbound) +Swap the case of the character under the cursor and move past it\&. +.TP +\fBtranspose\-chars\fP (\fB^T\fP) (unbound) (unbound) +Exchange the two characters to the left of the +cursor if at end of line, else exchange the +character under the cursor with the character +to the left\&. +.TP +\fBtranspose\-words\fP (\fBESC\-T ESC\-t\fP) (unbound) (unbound) +Exchange the current word with the one before it\&. +.RS +.PP +With a positive numeric argument \fIN\fP, the word around the cursor, or +following it if the cursor is between words, is transposed with the +preceding \fIN\fP words\&. The cursor is put at the end of the resulting +group of words\&. +.PP +With a negative numeric argument \fI\-N\fP, the effect is the same as using +a positive argument \fIN\fP except that the original cursor position is +retained, regardless of how the words are rearranged\&. +.RE +.TP +\fBvi\-unindent\fP (unbound) (\fB<\fP) (unbound) +Unindent a number of lines\&. +.TP +\fBvi\-up\-case\fP (unbound) (\fBgU\fP) (unbound) +Read a movement command from the keyboard, and convert all characters +from the cursor position to the endpoint of the movement to lowercase\&. +If the movement command is \fBvi\-up\-case\fP, swap the case of all +characters on the current line\&. +.TP +\fBup\-case\-word\fP (\fBESC\-U ESC\-u\fP) (unbound) (unbound) +Convert the current word to all caps and move past it\&. +.TP +\fByank\fP (\fB^Y\fP) (unbound) (unbound) +Insert the contents of the kill buffer at the cursor position\&. +.TP +\fByank\-pop\fP (\fBESC\-y\fP) (unbound) (unbound) +Remove the text just yanked, rotate the kill\-ring (the history of +previously killed text) and yank the new top\&. Only works following +\fByank\fP, \fBvi\-put\-before\fP, \fBvi\-put\-after\fP or \fByank\-pop\fP\&. +.TP +\fBvi\-yank\fP (unbound) (\fBy\fP) (unbound) +Read a movement command from the keyboard, and copy the region +from the cursor position to the endpoint of the movement +into the kill buffer\&. +If the command is \fBvi\-yank\fP, copy the current line\&. +.TP +\fBvi\-yank\-whole\-line\fP (unbound) (\fBY\fP) (unbound) +Copy the current line into the kill buffer\&. +.TP +\fBvi\-yank\-eol\fP +Copy the region from the cursor position to the end of the line +into the kill buffer\&. +Arguably, this is what Y should do in vi, but it isn\&'t what it actually does\&. +.SS "Arguments" +.PD 0 +.TP +.PD +\fBdigit\-argument\fP (\fBESC\-0\fP\&.\&.\fBESC\-9\fP) (\fB1\fP\-\fB9\fP) (unbound) +Start a new numeric argument, or add to the current one\&. +See also \fBvi\-digit\-or\-beginning\-of\-line\fP\&. This only works if bound to a +key sequence ending in a decimal digit\&. +.RS +.PP +Inside a widget function, a call to this function treats the last key of +the key sequence which called the widget as the digit\&. +.RE +.TP +\fBneg\-argument\fP (\fBESC\-\fP\fB\-\fP) (unbound) (unbound) +Changes the sign of the following argument\&. +.TP +\fBuniversal\-argument\fP +Multiply the argument of the next command by 4\&. Alternatively, if +this command is followed by an integer (positive or negative), use +that as the argument for the next command\&. Thus digits cannot be +repeated using this command\&. For example, if this command occurs +twice, followed immediately by \fBforward\-char\fP, move forward sixteen +spaces; if instead it is followed by \fB\-2\fP, then \fBforward\-char\fP, +move backward two spaces\&. +.RS +.PP +Inside a widget function, if passed an argument, i\&.e\&. `\fBzle +universal\-argument\fP \fInum\fP\&', the numeric argument will be set to +\fInum\fP; this is equivalent to `\fBNUMERIC=\fP\fInum\fP\&'\&. +.RE +.TP +\fBargument\-base\fP +Use the existing numeric argument as a numeric base, which must be in the +range 2 to 36 inclusive\&. Subsequent use of \fBdigit\-argument\fP and +\fBuniversal\-argument\fP will input a new numeric argument in the given base\&. +The usual hexadecimal convention is used: the letter \fBa\fP or \fBA\fP +corresponds to 10, and so on\&. Arguments in bases requiring digits from 10 +upwards are more conveniently input with \fBuniversal\-argument\fP, since +\fBESC\-a\fP etc\&. are not usually bound to \fBdigit\-argument\fP\&. +.RS +.PP +The function can be used with a command argument inside a user\-defined +widget\&. The following code sets the base to 16 and lets the user input a +hexadecimal argument until a key out of the digit range is typed: +.PP +.RS +.nf +\fBzle argument\-base 16 +zle universal\-argument\fP +.fi +.RE +.RE +.SS "Completion" +.PD 0 +.TP +.PD +\fBaccept\-and\-menu\-complete\fP +In a menu completion, insert the current completion into the buffer, +and advance to the next possible completion\&. +.TP +\fBcomplete\-word\fP +Attempt completion on the current word\&. +.TP +\fBdelete\-char\-or\-list\fP (\fB^D\fP) (unbound) (unbound) +Delete the character under the cursor\&. If the cursor +is at the end of the line, list possible completions for the +current word\&. +.TP +\fBexpand\-cmd\-path\fP +Expand the current command to its full pathname\&. +.TP +\fBexpand\-or\-complete\fP (\fBTAB\fP) (unbound) (\fBTAB\fP) +Attempt shell expansion on the current word\&. +If that fails, +attempt completion\&. +.TP +\fBexpand\-or\-complete\-prefix\fP +Attempt shell expansion on the current word up to cursor\&. +.TP +\fBexpand\-history\fP (\fBESC\-space ESC\-!\fP) (unbound) (unbound) +Perform history expansion on the edit buffer\&. +.TP +\fBexpand\-word\fP (\fB^X*\fP) (unbound) (unbound) +Attempt shell expansion on the current word\&. +.TP +\fBlist\-choices\fP (\fBESC\-^D\fP) (\fB^D =\fP) (\fB^D\fP) +List possible completions for the current word\&. +.TP +\fBlist\-expand\fP (\fB^Xg ^XG\fP) (\fB^G\fP) (\fB^G\fP) +List the expansion of the current word\&. +.TP +\fBmagic\-space\fP +Perform history expansion and insert a space into the +buffer\&. This is intended to be bound to space\&. +.TP +\fBmenu\-complete\fP +Like \fBcomplete\-word\fP, except that menu completion is used\&. +See the \fBMENU_COMPLETE\fP option\&. +.TP +\fBmenu\-expand\-or\-complete\fP +Like \fBexpand\-or\-complete\fP, except that menu completion is used\&. +.TP +\fBreverse\-menu\-complete\fP +Perform menu completion, like \fBmenu\-complete\fP, except that if +a menu completion is already in progress, move to the \fIprevious\fP +completion rather than the next\&. +.TP +\fBend\-of\-list\fP +When a previous completion displayed a list below the prompt, this +widget can be used to move the prompt below the list\&. +.SS "Miscellaneous" +.PD 0 +.TP +.PD +\fBaccept\-and\-hold\fP (\fBESC\-A ESC\-a\fP) (unbound) (unbound) +Push the contents of the buffer on the buffer stack +and execute it\&. +.TP +\fBaccept\-and\-infer\-next\-history\fP +Execute the contents of the buffer\&. +Then search the history list for a line matching the current one +and push the event following onto the buffer stack\&. +.TP +\fBaccept\-line\fP (\fB^J ^M\fP) (\fB^J ^M\fP) (\fB^J ^M\fP) +Finish editing the buffer\&. Normally this causes the buffer to be +executed as a shell command\&. +.TP +\fBaccept\-line\-and\-down\-history\fP (\fB^O\fP) (unbound) (unbound) +Execute the current line, and push the next history +event on the buffer stack\&. +.TP +\fBauto\-suffix\-remove\fP +If the previous action added a suffix (space, slash, etc\&.) to the word on +the command line, remove it\&. Otherwise do nothing\&. Removing the suffix +ends any active menu completion or menu selection\&. +.RS +.PP +This widget is intended to be called from user\-defined widgets to enforce +a desired suffix\-removal behavior\&. +.RE +.TP +\fBauto\-suffix\-retain\fP +If the previous action added a suffix (space, slash, etc\&.) to the word on +the command line, force it to be preserved\&. Otherwise do nothing\&. +Retaining the suffix ends any active menu completion or menu selection\&. +.RS +.PP +This widget is intended to be called from user\-defined widgets to enforce +a desired suffix\-preservation behavior\&. +.RE +.TP +\fBbeep\fP +Beep, unless the \fBBEEP\fP option is unset\&. +.TP +\fBbracketed\-paste\fP +This widget is invoked when text is pasted to the terminal emulator\&. It +is not intended to be bound to actual keys but instead to the special +sequence generated by the terminal emulator when text is pasted\&. +.RS +.PP +When invoked interactively, the pasted text is inserted to the buffer +and placed in the cutbuffer\&. +If a numeric argument is given, shell quoting will be applied to the +pasted text before it is inserted\&. +.PP +When a named buffer is specified with \fBvi\-set\-buffer\fP (\fB"x\fP), +the pasted text is stored in that named buffer but not inserted\&. +.PP +When called from a widget function as `\fBbracketed\-paste\fP \fIname\fP`, the +pasted text is assigned to the variable \fIname\fP and no other processing is +done\&. +.PP +See also the \fBzle_bracketed_paste\fP parameter\&. +.RE +.TP +\fBvi\-cmd\-mode\fP (\fB^X^V\fP) (unbound) (\fB^[\fP) +Enter command mode; that is, select the `\fBvicmd\fP\&' keymap\&. +Yes, this is bound by default in emacs mode\&. +.TP +\fBvi\-caps\-lock\-panic\fP +Hang until any lowercase key is pressed\&. +This is for vi users without the mental capacity to keep +track of their caps lock key (like the author)\&. +.TP +\fBclear\-screen\fP (\fB^L ESC\-^L\fP) (\fB^L\fP) (\fB^L\fP) +Clear the screen and redraw the prompt\&. +.TP +\fBdeactivate\-region\fP +Make the current region inactive\&. This disables vim\-style visual +selection mode if it is active\&. +.TP +\fBdescribe\-key\-briefly\fP +Reads a key sequence, then prints the function bound to that sequence\&. +.TP +\fBexchange\-point\-and\-mark\fP (\fB^X^X\fP) (unbound) (unbound) +Exchange the cursor position (point) with the position of the mark\&. +Unless a negative numeric argument is given, the region between +point and mark is activated so that it can be highlighted\&. +If a zero numeric argument is given, the region is activated but +point and mark are not swapped\&. +.TP +\fBexecute\-named\-cmd\fP (\fBESC\-x\fP) (\fB:\fP) (unbound) +Read the name of an editor command and execute it\&. Aliasing this +widget with `\fBzle \-A\fP\&' or replacing it with `\fBzle \-N\fP' has no +effect when interpreting key bindings, but `\fBzle execute\-named\-cmd\fP\&' +will invoke such an alias or replacement\&. +.RS +.PP +A restricted set of editing functions is available in the +mini\-buffer\&. Keys are looked up in the special +\fBcommand\fP keymap, and if not found there in the main keymap\&. +An interrupt signal, as defined by the stty setting, will +abort the function\&. Note that the following always +perform the same task within the \fBexecuted\-named\-cmd\fP environment and +cannot be replaced by user defined widgets, nor can the set of functions +be extended\&. The allowed functions are: +\fBbackward\-delete\-char\fP, +\fBvi\-backward\-delete\-char\fP, +\fBclear\-screen\fP, +\fBredisplay\fP, +\fBquoted\-insert\fP, +\fBvi\-quoted\-insert\fP, +\fBbackward\-kill\-word\fP, +\fBvi\-backward\-kill\-word\fP, +\fBkill\-whole\-line\fP, +\fBvi\-kill\-line\fP, +\fBbackward\-kill\-line\fP, +\fBlist\-choices\fP, +\fBdelete\-char\-or\-list\fP, +\fBcomplete\-word\fP, +\fBaccept\-line\fP, +\fBexpand\-or\-complete\fP and +\fBexpand\-or\-complete\-prefix\fP\&. +.PP +\fBkill\-region\fP kills the last word, +and vi\-cmd\-mode is treated the same as accept\-line\&. +The space and tab characters, if not bound to one of +these functions, will complete the name and then list the +possibilities if the \fBAUTO_LIST\fP option is set\&. +Any other character that is not bound to \fBself\-insert\fP or +\fBself\-insert\-unmeta\fP will beep and be ignored\&. +The bindings of the current insert mode will be used\&. +.PP +Currently this command may not be redefined or called by name\&. +.RE +.TP +\fBexecute\-last\-named\-cmd\fP (\fBESC\-z\fP) (unbound) (unbound) +Redo the last function executed with \fBexecute\-named\-cmd\fP\&. +.RS +.PP +Like \fBexecute\-named\-cmd\fP, this command may not be redefined, +but it may be called by name\&. +.RE +.TP +\fBget\-line\fP (\fBESC\-G ESC\-g\fP) (unbound) (unbound) +Pop the top line off the buffer stack and insert it at the +cursor position\&. +.TP +\fBpound\-insert\fP (unbound) (\fB#\fP) (unbound) +If there is no # character at the beginning of the buffer, +add one to the beginning of each line\&. +If there is one, remove a # from each line that has one\&. +In either case, accept the current line\&. +The \fBINTERACTIVE_COMMENTS\fP option must be set +for this to have any usefulness\&. +.TP +\fBvi\-pound\-insert\fP +If there is no # character at the beginning of the current line, +add one\&. If there is one, remove it\&. +The \fBINTERACTIVE_COMMENTS\fP option must be set +for this to have any usefulness\&. +.TP +\fBpush\-input\fP +Push the entire current multiline construct onto the buffer stack and +return to the top\-level (\fBPS1\fP) prompt\&. +If the current parser construct is only a single line, this is exactly +like \fBpush\-line\fP\&. +Next time the editor starts up or is popped with \fBget\-line\fP, the +construct will be popped off the top of the buffer stack and loaded +into the editing buffer\&. +.TP +\fBpush\-line\fP (\fB^Q ESC\-Q ESC\-q\fP) (unbound) (unbound) +Push the current buffer onto the buffer stack and clear +the buffer\&. +Next time the editor starts up, the buffer will be popped +off the top of the buffer stack and loaded into the editing +buffer\&. +.TP +\fBpush\-line\-or\-edit\fP +At the top\-level (\fBPS1\fP) prompt, equivalent to \fBpush\-line\fP\&. +At a secondary (\fBPS2\fP) prompt, move the entire current multiline +construct into the editor buffer\&. +The latter is equivalent to \fBpush\-input\fP followed by \fBget\-line\fP\&. +.TP +\fBread\-command\fP +Only useful from a user\-defined widget\&. A keystroke is read just as in +normal operation, but instead of the command being executed the name +of the command that would be executed is stored in the shell parameter +\fBREPLY\fP\&. This can be used as the argument of a future \fBzle\fP +command\&. If the key sequence is not bound, status 1 is returned; +typically, however, \fBREPLY\fP is set to \fBundefined\-key\fP to indicate +a useless key sequence\&. +.TP +\fBrecursive\-edit\fP +Only useful from a user\-defined widget\&. At this point in the function, +the editor regains control until one of the standard widgets which would +normally cause zle to exit (typically an \fBaccept\-line\fP caused by +hitting the return key) is executed\&. Instead, control returns to the +user\-defined widget\&. The status returned is non\-zero if the return was +caused by an error, but the function still continues executing and hence +may tidy up\&. This makes it safe for the user\-defined widget to alter +the command line or key bindings temporarily\&. +.RS +.PP +The following widget, \fBcaps\-lock\fP, serves as an example\&. +.PP +.RS +.nf +\fBself\-insert\-ucase() { + LBUFFER+=${(U)KEYS[\-1]} +} + +integer stat + +zle \-N self\-insert self\-insert\-ucase +zle \-A caps\-lock save\-caps\-lock +zle \-A accept\-line caps\-lock + +zle recursive\-edit +stat=$? + +zle \-A \&.self\-insert self\-insert +zle \-A save\-caps\-lock caps\-lock +zle \-D save\-caps\-lock + +(( stat )) && zle send\-break + +return $stat\fP +.fi +.RE +.PP +This causes typed letters to be inserted capitalised until either +\fBaccept\-line\fP (i\&.e\&. typically the return key) is typed or the +\fBcaps\-lock\fP widget is invoked again; the later is handled by saving +the old definition of \fBcaps\-lock\fP as \fBsave\-caps\-lock\fP and then +rebinding it to invoke \fBaccept\-line\fP\&. Note that an error from the +recursive edit is detected as a non\-zero return status and propagated by +using the \fBsend\-break\fP widget\&. +.RE +.TP +\fBredisplay\fP (unbound) (\fB^R\fP) (\fB^R\fP) +Redisplays the edit buffer\&. +.TP +\fBreset\-prompt\fP (unbound) (unbound) (unbound) +Force the prompts on both the left and right of the screen to be +re\-expanded, then redisplay the edit buffer\&. This +reflects changes both to the prompt variables themselves and changes +in the expansion of the values (for example, changes in time or +directory, or changes to the value of variables referred to by the +prompt)\&. +.RS +.PP +Otherwise, the prompt is only expanded each time zle starts, and +when the display has been interrupted by output from another part of the +shell (such as a job notification) which causes the command line to be +reprinted\&. +.PP +\fBreset\-prompt\fP doesn\&'t alter the special parameter \fBLASTWIDGET\fP\&. +.PP +.RE +.TP +\fBsend\-break\fP (\fB^G ESC\-^G\fP) (unbound) (unbound) +Abort the current editor function, e\&.g\&. \fBexecute\-named\-command\fP, or the +editor itself, e\&.g\&. if you are in \fBvared\fP\&. Otherwise abort the parsing of +the current line; in this case the aborted line is available in the shell +variable \fBZLE_LINE_ABORTED\fP\&. If the editor is aborted from within +\fBvared\fP, the variable \fBZLE_VARED_ABORTED\fP is set\&. +.TP +\fBrun\-help\fP (\fBESC\-H ESC\-h\fP) (unbound) (unbound) +Push the buffer onto the buffer stack, and execute the +command `\fBrun\-help\fP \fIcmd\fP\&', where \fIcmd\fP is the current +command\&. \fBrun\-help\fP is normally aliased to \fBman\fP\&. +.TP +\fBvi\-set\-buffer\fP (unbound) (\fB"\fP) (unbound) +Specify a buffer to be used in the following command\&. +There are 37 buffers that can be specified: +the 26 `named\&' buffers \fB"a\fP to \fB"z\fP, the `yank' buffer \fB"0\fP, +the nine `queued\&' buffers \fB"1\fP to \fB"9\fP and the `black hole' buffer +\fB"_\fP\&. The named buffers can also be specified as \fB"A\fP to \fB"Z\fP\&. +.RS +.PP +When a buffer is specified for a cut, change or yank command, the text +concerned replaces the previous contents of the specified buffer\&. If +a named buffer is specified using a capital, the newly cut text is +appended to the buffer instead of overwriting it\&. When using the \fB"_\fP +buffer, nothing happens\&. This can be useful for deleting text without +affecting any buffers\&. +.PP +If no buffer is specified for a cut or change command, \fB"1\fP is used, and +the contents of \fB"1\fP to \fB"8\fP are each shifted along one buffer; +the contents of \fB"9\fP is lost\&. If no buffer is specified for a yank +command, \fB"0\fP is used\&. Finally, a paste command without a specified +buffer will paste the text from the most recent command regardless of any +buffer that might have been used with that command\&. +.PP +When called from a widget function by the \fBzle\fP command, the buffer +can optionally be specified with an argument\&. For example, +.PP +.RS +.nf +\fBzle vi\-set\-buffer A\fP +.fi +.RE +.RE +.TP +\fBvi\-set\-mark\fP (unbound) (\fBm\fP) (unbound) +Set the specified mark at the cursor position\&. +.TP +\fBset\-mark\-command\fP (\fB^@\fP) (unbound) (unbound) +Set the mark at the cursor position\&. If called with a negative +numeric argument, do not set the mark but deactivate the region so that +it is no longer highlighted (it is still usable for other purposes)\&. +Otherwise the region is marked as active\&. +.TP +\fBspell\-word\fP (\fBESC\-$ ESC\-S ESC\-s\fP) (unbound) (unbound) +Attempt spelling correction on the current word\&. +.TP +\fBsplit\-undo\fP +Breaks the undo sequence at the current change\&. This is useful in vi mode as +changes made in insert mode are coalesced on entering command mode\&. Similarly, +\fBundo\fP will normally revert as one all the changes made by a user\-defined +widget\&. +.TP +\fBundefined\-key\fP +This command is executed when a key sequence that is not bound to any +command is typed\&. By default it beeps\&. +.TP +\fBundo\fP (\fB^_ ^Xu ^X^U\fP) (\fBu\fP) (unbound) +Incrementally undo the last text modification\&. When called from a +user\-defined widget, takes an optional argument indicating a previous state +of the undo history as returned by the \fBUNDO_CHANGE_NO\fP variable; +modifications are undone until that state is reached, subject to +any limit imposed by the \fBUNDO_LIMIT_NO\fP variable\&. +.RS +.PP +Note that when invoked from vi command mode, the full prior change made in +insert mode is reverted, the changes having been merged when command mode was +selected\&. +.RE +.TP +\fBredo\fP (unbound) (\fB^R\fP) (unbound) +Incrementally redo undone text modifications\&. +.TP +\fBvi\-undo\-change\fP (unbound) (unbound) (unbound) +Undo the last text modification\&. +If repeated, redo the modification\&. +.TP +\fBvisual\-mode\fP (unbound) (\fBv\fP) (unbound) +Toggle vim\-style visual selection mode\&. If line\-wise visual mode is +currently enabled then it is changed to being character\-wise\&. If used +following an operator, it forces the subsequent movement command to be +treated as a character\-wise movement\&. +.TP +\fBvisual\-line\-mode\fP (unbound) (\fBV\fP) (unbound) +Toggle vim\-style line\-wise visual selection mode\&. If character\-wise +visual mode is currently enabled then it is changed to being line\-wise\&. If used +following an operator, it forces the subsequent movement command to be +treated as a line\-wise movement\&. +.TP +\fBwhat\-cursor\-position\fP (\fB^X=\fP) (\fBga\fP) (unbound) +Print the character under the cursor, its code as an octal, decimal and +hexadecimal number, the current cursor position within the buffer and the +column of the cursor in the current line\&. +.TP +\fBwhere\-is\fP +Read the name of an editor command and print the listing of key +sequences that invoke the specified command\&. +A restricted set of editing functions is available in the +mini\-buffer\&. Keys are looked up in the special +\fBcommand\fP keymap, and if not found there in the main keymap\&. +.TP +\fBwhich\-command\fP (\fBESC\-?\fP) (unbound) (unbound) +Push the buffer onto the buffer stack, and execute the +command `\fBwhich\-command\fP \fIcmd\fP\&'\&. where \fIcmd\fP is the current +command\&. \fBwhich\-command\fP is normally aliased to \fBwhence\fP\&. +.TP +\fBvi\-digit\-or\-beginning\-of\-line\fP (unbound) (\fB0\fP) (unbound) +If the last command executed was a digit as part of an argument, +continue the argument\&. Otherwise, execute vi\-beginning\-of\-line\&. +.SS "Text Objects" +Text objects are commands that can be used to select a block of text +according to some criteria\&. They are a feature of the vim text editor +and so are primarily intended for use with vi operators or from visual +selection mode\&. However, they can also be used from vi\-insert or emacs +mode\&. Key bindings listed below apply to the \fBviopp\fP and \fBvisual\fP +keymaps\&. +.PP +.PD 0 +.TP +.PD +\fBselect\-a\-blank\-word\fP (\fBaW\fP) +Select a word including adjacent blanks, where a word is defined as a +series of non\-blank characters\&. With a numeric argument, multiple words +will be selected\&. +.TP +\fBselect\-a\-shell\-word\fP (\fBaa\fP) +Select the current command argument applying the normal rules for +quoting\&. +.TP +\fBselect\-a\-word\fP (\fBaw\fP) +Select a word including adjacent blanks, using the normal vi\-style word +definition\&. With a numeric argument, multiple words will be selected\&. +.TP +\fBselect\-in\-blank\-word\fP (\fBiW\fP) +Select a word, where a word is defined as a series of non\-blank +characters\&. With a numeric argument, multiple words will be selected\&. +.TP +\fBselect\-in\-shell\-word\fP (\fBia\fP) +Select the current command argument applying the normal rules for +quoting\&. If the argument begins and ends with matching quote characters, +these are not included in the selection\&. +.TP +\fBselect\-in\-word\fP (\fBiw\fP) +Select a word, using the normal vi\-style word definition\&. With a numeric +argument, multiple words will be selected\&. +.PP +.SH "CHARACTER HIGHLIGHTING" +.PP +The line editor has the ability to highlight characters or regions +of the line that have a particular significance\&. This is controlled +by the array parameter \fBzle_highlight\fP, if it has been set by the user\&. +.PP +If the parameter contains the single entry \fBnone\fP all highlighting +is turned off\&. Note the parameter is still expected to be an array\&. +.PP +Otherwise each entry of the array should consist of a word indicating a +context for highlighting, then a colon, then a comma\-separated list of +the types of highlighting to apply in that context\&. +.PP +The contexts available for highlighting are the following: +.PP +.PD 0 +.TP +.PD +\fBdefault\fP +Any text within the command line not affected by any other highlighting\&. +Text outside the editable area of the command line is not affected\&. +.TP +\fBisearch\fP +When one of the incremental history search widgets is active, the +area of the command line matched by the search string or pattern\&. +.TP +\fBregion\fP +The currently selected text\&. In emacs terminology, this is referred to as +the region and is bounded by the cursor (point) and the mark\&. The region +is only highlighted if it is active, which is the case after the mark +is modified with \fBset\-mark\-command\fP or \fBexchange\-point\-and\-mark\fP\&. +Note that whether or not the region is active has no effect on its +use within emacs style widgets, it simply determines whether it is +highlighted\&. In vi mode, the region corresponds to selected text in +visual mode\&. +.TP +\fBspecial\fP +Individual characters that have no direct printable +representation but are shown in a special manner by the line editor\&. +These characters are described below\&. +.TP +\fBsuffix\fP +This context is used in completion for characters that are +marked as suffixes that will be removed if the completion ends +at that point, the most obvious example being a slash (\fB/\fP) after +a directory name\&. Note that suffix removal is configurable; the +circumstances under which the suffix will be removed may differ +for different completions\&. +.TP +\fBpaste\fP +Following a command to paste text, the characters that were inserted\&. +.PP +When \fBregion_highlight\fP is set, the contexts that describe a region \-\- +\fBisearch\fP, \fBregion\fP, \fBsuffix\fP, and \fBpaste\fP \-\- +are applied first, then \fBregion_highlight\fP is applied, then the remaining +\fBzle_highlight\fP contexts are applied\&. If a particular character is +affected by multiple specifications, the last specification wins\&. +.PP +\fBzle_highlight\fP may contain additional fields for controlling how +terminal sequences to change colours are output\&. Each of the following is +followed by a colon and a string in the same form as for key bindings\&. +This will not be necessary for the vast majority of terminals as the +defaults shown in parentheses are widely used\&. +.PP +.PD 0 +.TP +.PD +\fBfg_start_code\fP (\fB\ee[3\fP) +The start of the escape sequence for the foreground colour\&. +This is followed by one to three ASCII digits representing the colour\&. +Only used for palette colors, i\&.e\&. not 24\-bit colors specified via a +color triplet\&. +.TP +\fBfg_default_code\fP (\fB9\fP) +The number to use instead of the colour to reset the default foreground +colour\&. +.TP +\fBfg_end_code\fP (\fBm\fP) +The end of the escape sequence for the foreground colour\&. +.TP +\fBbg_start_code\fP (\fB\ee[4\fP) +The start of the escape sequence for the background colour\&. +See \fBfg_start_code\fP above\&. +.TP +\fBbg_default_code\fP (\fB9\fP) +The number to use instead of the colour to reset the default +background colour\&. +.TP +\fBbg_end_code\fP (\fBm\fP) +The end of the escape sequence for the background colour\&. +.PP +The available types of highlighting are the following\&. Note that +not all types of highlighting are available on all terminals: +.PP +.PD 0 +.TP +.PD +\fBnone\fP +No highlighting is applied to the given context\&. It is not useful for +this to appear with other types of highlighting; it is used to override +a default\&. +.TP +\fBfg=\fP\fIcolour\fP +The foreground colour should be set to \fIcolour\fP, a decimal integer, +the name of one of the eight most widely\-supported colours or as a +`\fB#\fP\&' followed by an RGB triplet in hexadecimal format\&. +.RS +.PP +Not all terminals support this and, of those that do, not all provide +facilities to test the support, hence the user should decide based on the +terminal type\&. Most terminals support the colours \fBblack\fP, \fBred\fP, +\fBgreen\fP, \fByellow\fP, \fBblue\fP, \fBmagenta\fP, \fBcyan\fP and \fBwhite\fP, +which can be set by name\&. In addition\&. \fBdefault\fP may be used to +set the terminal\&'s default foreground colour\&. Abbreviations are allowed; +\fBb\fP or \fBbl\fP selects black\&. Some terminals may generate additional +colours if the \fBbold\fP attribute is also present\&. +.PP +On recent terminals and on systems with an up\-to\-date terminal database the +number of colours supported may be tested by the command `\fBechotc +Co\fP\&'; if this succeeds, it indicates a limit on the number of colours which +will be enforced by the line editor\&. The number of colours is in any case +limited to 256 (i\&.e\&. the range 0 to 255)\&. +.PP +Some modern terminal emulators have support for 24\-bit true colour (16 +million colours)\&. In this case, the hex triplet format can be used\&. This +consists of a `\fB#\fP\&' followed by either a three or six digit hexadecimal +number describing the red, green and blue components of the colour\&. Hex +triplets can also be used with 88 and 256 colour terminals via the +\fBzsh/nearcolor\fP module (see \fIzshmodules\fP(1))\&. +.PP +Colour is also known as color\&. +.RE +.TP +\fBbg=\fP\fIcolour\fP +The background colour should be set to \fIcolour\fP\&. +This works similarly to the foreground colour, except the background is +not usually affected by the bold attribute\&. +.TP +\fBbold\fP +The characters in the given context are shown in a bold font\&. +Not all terminals distinguish bold fonts\&. +.TP +\fBstandout\fP +The characters in the given context are shown in the terminal\&'s standout +mode\&. The actual effect is specific to the terminal; on many terminals it +is inverse video\&. On some such terminals, where the cursor does not blink +it appears with standout mode negated, making it less than clear where +the cursor actually is\&. On such terminals one of the other effects +may be preferable for highlighting the region and matched search string\&. +.TP +\fBunderline\fP +The characters in the given context are shown underlined\&. Some +terminals show the foreground in a different colour instead; in this +case whitespace will not be highlighted\&. +.PP +The characters described above as `special\&' are as follows\&. The +formatting described here is used irrespective of whether the characters +are highlighted: +.PP +.PD 0 +.TP +.PD +ASCII control characters +Control characters in the ASCII range are shown as +`\fB^\fP\&' followed by the base character\&. +.TP +Unprintable multibyte characters +This item applies to control characters not in the ASCII range, +plus other characters as follows\&. If the \fBMULTIBYTE\fP option is in +effect, multibyte characters not in the ASCII character set that are +reported as having zero width are treated as combining characters when the +option \fBCOMBINING_CHARS\fP is on\&. If the option is off, or if a character +appears where a combining character is not valid, the character +is treated as unprintable\&. +.RS +.PP +Unprintable multibyte characters are shown as a hexadecimal number between +angle brackets\&. The number is the code point of the character in the wide +character set; this may or may not be Unicode, depending on the operating +system\&. +.RE +.TP +Invalid multibyte characters +If the \fBMULTIBYTE\fP option is in effect, any sequence of one or more +bytes that does not form a valid character in the current character +set is treated as a series of bytes each shown as a special character\&. +This case can be distinguished from other unprintable characters +as the bytes are represented as two hexadecimal digits between angle +brackets, as distinct from the four or eight digits that are used for +unprintable characters that are nonetheless valid in the current +character set\&. +.RS +.PP +Not all systems support this: for it to work, the system\&'s representation of +wide characters must be code values from the Universal Character Set, +as defined by IS0 10646 (also known as Unicode)\&. +.RE +.TP +Wrapped double\-width characters +When a double\-width character appears in the final column of a line, it +is instead shown on the next line\&. The empty space left in the original +position is highlighted as a special character\&. +.PP +If \fBzle_highlight\fP is not set or no value applies to a particular +context, the defaults applied are equivalent to +.PP +.RS +.nf +\fBzle_highlight=(region:standout special:standout +suffix:bold isearch:underline paste:standout)\fP +.fi +.RE +.PP +i\&.e\&. both the region and special characters are shown in standout mode\&. +.PP +Within widgets, arbitrary regions may be highlighted by setting the +special array parameter \fBregion_highlight\fP; see +above\&. +.PP |