1ZSHZLE(1) General Commands Manual ZSHZLE(1)
2
6 zshzle - zsh command line editor
7
9 If the ZLE option is set (which it is by default in interactive shells)
10 and the shell input is attached to the terminal, the user is able to
11 edit command lines.
12 There are two display modes. The first, multiline mode, is the de‐
14 fault. It only works if the TERM parameter is set to a valid terminal
15 type that can move the cursor up. The second, single line mode, is
16 used if TERM is invalid or incapable of moving the cursor up, or if the
17 SINGLE_LINE_ZLE option is set. This mode is similar to ksh, and uses
18 no termcap sequences. If TERM is "emacs", the ZLE option will be unset
19 by default.
20 The parameters BAUD, COLUMNS, and LINES are also used by the line edi‐
22 tor. See Parameters Used By The Shell in zshparam(1).
23 The parameter zle_highlight is also used by the line editor; see Char‐
25 acter Highlighting below. Highlighting of special characters and the
26 region between the cursor and the mark (as set with set-mark-command in
27 Emacs mode, or by visual-mode in Vi mode) is enabled by default; con‐
28 sult this reference for more information. Irascible conservatives will
29 wish to know that all highlighting may be disabled by the following
30 setting:
31 zle_highlight=(none)
33 In many places, references are made to the numeric argument. This can
35 by default be entered in emacs mode by holding the alt key and typing a
36 number, or pressing escape before each digit, and in vi command mode by
37 typing the number before entering a command. Generally the numeric ar‐
38 gument causes the next command entered to be repeated the specified
39 number of times, unless otherwise noted below; this is implemented by
40 the digit-argument widget. See also the Arguments subsection of the
41 Widgets section for some other ways the numeric argument can be modi‐
42 fied.
43
45 A keymap in ZLE contains a set of bindings between key sequences and
46 ZLE commands. The empty key sequence cannot be bound.
47 There can be any number of keymaps at any time, and each keymap has one
49 or more names. If all of a keymap's names are deleted, it disappears.
50 bindkey can be used to manipulate keymap names.
51 Initially, there are eight keymaps:
53 emacs EMACS emulation
55 viins vi emulation - insert mode
56 vicmd vi emulation - command mode
57 viopp vi emulation - operator pending
58 visual vi emulation - selection active
59 isearch
60 incremental search mode
61 command
62 read a command name
63 .safe fallback keymap
64 The `.safe' keymap is special. It can never be altered, and the name
66 can never be removed. However, it can be linked to other names, which
67 can be removed. In the future other special keymaps may be added;
68 users should avoid using names beginning with `.' for their own
69 keymaps.
70 In addition to these names, either `emacs' or `viins' is also linked to
72 the name `main'. If one of the VISUAL or EDITOR environment variables
73 contain the string `vi' when the shell starts up then it will be `vi‐
74 ins', otherwise it will be `emacs'. bindkey's -e and -v options pro‐
75 vide a convenient way to override this default choice.
76 When the editor starts up, it will select the `main' keymap. If that
78 keymap doesn't exist, it will use `.safe' instead.
79 In the `.safe' keymap, each single key is bound to self-insert, except
81 for ^J (line feed) and ^M (return) which are bound to accept-line.
82 This is deliberately not pleasant to use; if you are using it, it means
83 you deleted the main keymap, and you should put it back.
84 Reading Commands
86 When ZLE is reading a command from the terminal, it may read a sequence
87 that is bound to some command and is also a prefix of a longer bound
88 string. In this case ZLE will wait a certain time to see if more char‐
89 acters are typed, and if not (or they don't match any longer string) it
90 will execute the binding. This timeout is defined by the KEYTIMEOUT
91 parameter; its default is 0.4 sec. There is no timeout if the prefix
92 string is not itself bound to a command.
93 The key timeout is also applied when ZLE is reading the bytes from a
95 multibyte character string when it is in the appropriate mode. (This
96 requires that the shell was compiled with multibyte mode enabled; typi‐
97 cally also the locale has characters with the UTF-8 encoding, although
98 any multibyte encoding known to the operating system is supported.) If
99 the second or a subsequent byte is not read within the timeout period,
100 the shell acts as if ? were typed and resets the input state.
101 As well as ZLE commands, key sequences can be bound to other strings,
103 by using `bindkey -s'. When such a sequence is read, the replacement
104 string is pushed back as input, and the command reading process starts
105 again using these fake keystrokes. This input can itself invoke fur‐
106 ther replacement strings, but in order to detect loops the process will
107 be stopped if there are twenty such replacements without a real command
108 being read.
109 A key sequence typed by the user can be turned into a command name for
111 use in user-defined widgets with the read-command widget, described in
112 the subsection `Miscellaneous' of the section `Standard Widgets' below.
113 Local Keymaps
115 While for normal editing a single keymap is used exclusively, in many
116 modes a local keymap allows for some keys to be customised. For exam‐
117 ple, in an incremental search mode, a binding in the isearch keymap
118 will override a binding in the main keymap but all keys that are not
119 overridden can still be used.
120 If a key sequence is defined in a local keymap, it will hide a key se‐
122 quence in the global keymap that is a prefix of that sequence. An exam‐
123 ple of this occurs with the binding of iw in viopp as this hides the
124 binding of i in vicmd. However, a longer sequence in the global keymap
125 that shares the same prefix can still apply so for example the binding
126 of ^Xa in the global keymap will be unaffected by the binding of ^Xb in
127 the local keymap.
128
130 The ZLE module contains three related builtin commands. The bindkey
131 command manipulates keymaps and key bindings; the vared command invokes
132 ZLE on the value of a shell parameter; and the zle command manipulates
133 editing widgets and allows command line access to ZLE commands from
134 within shell functions.
135 bindkey [ options ] -l [ -L ] [ keymap ... ]
137 bindkey [ options ] -d
138 bindkey [ options ] -D keymap ...
139 bindkey [ options ] -A old-keymap new-keymap
140 bindkey [ options ] -N new-keymap [ old-keymap ]
141 bindkey [ options ] -m
142 bindkey [ options ] -r in-string ...
143 bindkey [ options ] -s in-string out-string ...
144 bindkey [ options ] in-string command ...
145 bindkey [ options ] [ in-string ]
146 bindkey's options can be divided into three categories: keymap
147 selection for the current command, operation selection, and oth‐
148 ers. The keymap selection options are:
149 -e Selects keymap `emacs' for any operations by the current
151 command, and also links `emacs' to `main' so that it is
152 selected by default the next time the editor starts.
153 -v Selects keymap `viins' for any operations by the current
155 command, and also links `viins' to `main' so that it is
156 selected by default the next time the editor starts.
157 -a Selects keymap `vicmd' for any operations by the current
159 command.
160 -M keymap
162 The keymap specifies a keymap name that is selected for
163 any operations by the current command.
164 If a keymap selection is required and none of the options above
166 are used, the `main' keymap is used. Some operations do not
167 permit a keymap to be selected, namely:
168 -l List all existing keymap names; if any arguments are
170 given, list just those keymaps.
171 If the -L option is also used, list in the form of bind‐
173 key commands to create or link the keymaps. `bindkey -lL
174 main' shows which keymap is linked to `main', if any, and
175 hence if the standard emacs or vi emulation is in effect.
176 This option does not show the .safe keymap because it
177 cannot be created in that fashion; however, neither is
178 `bindkey -lL .safe' reported as an error, it simply out‐
179 puts nothing.
180 -d Delete all existing keymaps and reset to the default
182 state.
183 -D keymap ...
185 Delete the named keymaps.
186 -A old-keymap new-keymap
188 Make the new-keymap name an alias for old-keymap, so that
189 both names refer to the same keymap. The names have
190 equal standing; if either is deleted, the other remains.
191 If there is already a keymap with the new-keymap name, it
192 is deleted.
193 -N new-keymap [ old-keymap ]
195 Create a new keymap, named new-keymap. If a keymap al‐
196 ready has that name, it is deleted. If an old-keymap
197 name is given, the new keymap is initialized to be a du‐
198 plicate of it, otherwise the new keymap will be empty.
199 To use a newly created keymap, it should be linked to main.
201 Hence the sequence of commands to create and use a new keymap
202 `mymap' initialized from the emacs keymap (which remains un‐
203 changed) is:
204 bindkey -N mymap emacs
206 bindkey -A mymap main
207 Note that while `bindkey -A newmap main' will work when newmap
209 is emacs or viins, it will not work for vicmd, as switching from
210 vi insert to command mode becomes impossible.
211 The following operations act on the `main' keymap if no keymap
213 selection option was given:
214 -m Add the built-in set of meta-key bindings to the selected
216 keymap. Only keys that are unbound or bound to self-in‐
217 sert are affected.
218 -r in-string ...
220 Unbind the specified in-strings in the selected keymap.
221 This is exactly equivalent to binding the strings to un‐
222 defined-key.
223 When -R is also used, interpret the in-strings as ranges.
225 When -p is also used, the in-strings specify prefixes.
227 Any binding that has the given in-string as a prefix, not
228 including the binding for the in-string itself, if any,
229 will be removed. For example,
230 bindkey -rpM viins '^['
232 will remove all bindings in the vi-insert keymap begin‐
234 ning with an escape character (probably cursor keys), but
235 leave the binding for the escape character itself (proba‐
236 bly vi-cmd-mode). This is incompatible with the option
237 -R.
238 -s in-string out-string ...
240 Bind each in-string to each out-string. When in-string
241 is typed, out-string will be pushed back and treated as
242 input to the line editor. When -R is also used, inter‐
243 pret the in-strings as ranges.
244 Note that both in-string and out-string are subject to
246 the same form of interpretation, as described below.
247 in-string command ...
249 Bind each in-string to each command. When -R is used,
250 interpret the in-strings as ranges.
251 [ in-string ]
253 List key bindings. If an in-string is specified, the
254 binding of that string in the selected keymap is dis‐
255 played. Otherwise, all key bindings in the selected
256 keymap are displayed. (As a special case, if the -e or
257 -v option is used alone, the keymap is not displayed -
258 the implicit linking of keymaps is the only thing that
259 happens.)
260 When the option -p is used, the in-string must be
262 present. The listing shows all bindings which have the
263 given key sequence as a prefix, not including any bind‐
264 ings for the key sequence itself.
265 When the -L option is used, the list is in the form of
267 bindkey commands to create the key bindings.
268 When the -R option is used as noted above, a valid range con‐
270 sists of two characters, with an optional `-' between them. All
271 characters between the two specified, inclusive, are bound as
272 specified.
273 For either in-string or out-string, the following escape se‐
275 quences are recognised:
276 \a bell character
278 \b backspace
279 \e, \E escape
280 \f form feed
281 \n linefeed (newline)
282 \r carriage return
283 \t horizontal tab
284 \v vertical tab
285 \NNN character code in octal
286 \xNN character code in hexadecimal
287 \uNNNN unicode character code in hexadecimal
288 \UNNNNNNNN
289 unicode character code in hexadecimal
290 \M[-]X character with meta bit set
291 \C[-]X control character
292 ^X control character
293 In all other cases, `\' escapes the following character. Delete
295 is written as `^?'. Note that `\M^?' and `^\M?' are not the
296 same, and that (unlike emacs), the bindings `\M-X' and `\eX' are
297 entirely distinct, although they are initialized to the same
298 bindings by `bindkey -m'.
299 vared [ -Aacghe ] [ -p prompt ] [ -r rprompt ]
302 [ -M main-keymap ] [ -m vicmd-keymap ]
303 [ -i init-widget ] [ -f finish-widget ]
304 [ -t tty ] name
305 The value of the parameter name is loaded into the edit buffer,
306 and the line editor is invoked. When the editor exits, name is
307 set to the string value returned by the editor. When the -c
308 flag is given, the parameter is created if it doesn't already
309 exist. The -a flag may be given with -c to create an array pa‐
310 rameter, or the -A flag to create an associative array. If the
311 type of an existing parameter does not match the type to be cre‐
312 ated, the parameter is unset and recreated. The -g flag may be
313 given to suppress warnings from the WARN_CREATE_GLOBAL and
314 WARN_NESTED_VAR options.
315 If an array or array slice is being edited, separator characters
317 as defined in $IFS will be shown quoted with a backslash, as
318 will backslashes themselves. Conversely, when the edited text
319 is split into an array, a backslash quotes an immediately fol‐
320 lowing separator character or backslash; no other special han‐
321 dling of backslashes, or any handling of quotes, is performed.
322 Individual elements of existing array or associative array pa‐
324 rameters may be edited by using subscript syntax on name. New
325 elements are created automatically, even without -c.
326 If the -p flag is given, the following string will be taken as
328 the prompt to display at the left. If the -r flag is given, the
329 following string gives the prompt to display at the right. If
330 the -h flag is specified, the history can be accessed from ZLE.
331 If the -e flag is given, typing ^D (Control-D) on an empty line
332 causes vared to exit immediately with a non-zero return value.
333 The -M option gives a keymap to link to the main keymap during
335 editing, and the -m option gives a keymap to link to the vicmd
336 keymap during editing. For vi-style editing, this allows a pair
337 of keymaps to override viins and vicmd. For emacs-style edit‐
338 ing, only -M is normally needed but the -m option may still be
339 used. On exit, the previous keymaps will be restored.
340 Vared calls the usual `zle-line-init' and `zle-line-finish'
342 hooks before and after it takes control. Using the -i and -f op‐
343 tions, it is possible to replace these with other custom wid‐
344 gets.
345 If `-t tty' is given, tty is the name of a terminal device to be
347 used instead of the default /dev/tty. If tty does not refer to
348 a terminal an error is reported.
349 zle
351 zle -l [ -L | -a ] [ string ... ]
352 zle -D widget ...
353 zle -A old-widget new-widget
354 zle -N widget [ function ]
355 zle -f flag [ flag... ]
356 zle -C widget completion-widget function
357 zle -R [ -c ] [ display-string ] [ string ... ]
358 zle -M string
359 zle -U string
360 zle -K keymap
361 zle -F [ -L | -w ] [ fd [ handler ] ]
362 zle -I
363 zle -T [ tc function | -r tc | -L ]
364 zle widget [ -n num ] [ -f flag ] [ -Nw ] [ -K keymap ] args ...
365 The zle builtin performs a number of different actions concern‐
366 ing ZLE.
367 With no options and no arguments, only the return status will be
369 set. It is zero if ZLE is currently active and widgets could be
370 invoked using this builtin command and non-zero otherwise. Note
371 that even if non-zero status is returned, zle may still be ac‐
372 tive as part of the completion system; this does not allow di‐
373 rect calls to ZLE widgets.
374 Otherwise, which operation it performs depends on its options:
376 -l [ -L | -a ] [ string ]
378 List all existing user-defined widgets. If the -L option
379 is used, list in the form of zle commands to create the
380 widgets.
381 When combined with the -a option, all widget names are
383 listed, including the builtin ones. In this case the -L
384 option is ignored.
385 If at least one string is given, and -a is present or -L
387 is not used, nothing will be printed. The return status
388 will be zero if all strings are names of existing widgets
389 and non-zero if at least one string is not a name of a
390 defined widget. If -a is also present, all widget names
391 are used for the comparison including builtin widgets,
392 else only user-defined widgets are used.
393 If at least one string is present and the -L option is
395 used, user-defined widgets matching any string are listed
396 in the form of zle commands to create the widgets.
397 -D widget ...
399 Delete the named widgets.
400 -A old-widget new-widget
402 Make the new-widget name an alias for old-widget, so that
403 both names refer to the same widget. The names have
404 equal standing; if either is deleted, the other remains.
405 If there is already a widget with the new-widget name, it
406 is deleted.
407 -N widget [ function ]
409 Create a user-defined widget. If there is already a wid‐
410 get with the specified name, it is overwritten. When the
411 new widget is invoked from within the editor, the speci‐
412 fied shell function is called. If no function name is
413 specified, it defaults to the same name as the widget.
414 For further information, see the section `Widgets' below.
415 -f flag [ flag... ]
417 Set various flags on the running widget. Possible values
418 for flag are:
419 yank for indicating that the widget has yanked text into
421 the buffer. If the widget is wrapping an existing inter‐
422 nal widget, no further action is necessary, but if it has
423 inserted the text manually, then it should also take care
424 to set YANK_START and YANK_END correctly. yankbefore
425 does the same but is used when the yanked text appears
426 after the cursor.
427 kill for indicating that text has been killed into the
429 cutbuffer. When repeatedly invoking a kill widget, text
430 is appended to the cutbuffer instead of replacing it, but
431 when wrapping such widgets, it is necessary to call `zle
432 -f kill' to retain this effect.
433 vichange for indicating that the widget represents a vi
435 change that can be repeated as a whole with `vi-re‐
436 peat-change'. The flag should be set early in the func‐
437 tion before inspecting the value of NUMERIC or invoking
438 other widgets. This has no effect for a widget invoked
439 from insert mode. If insert mode is active when the wid‐
440 get finishes, the change extends until next returning to
441 command mode.
442 -C widget completion-widget function
444 Create a user-defined completion widget named widget. The
445 completion widget will behave like the built-in comple‐
446 tion-widget whose name is given as completion-widget. To
447 generate the completions, the shell function function
448 will be called. For further information, see zshcomp‐
449 wid(1).
450 -R [ -c ] [ display-string ] [ string ... ]
452 Redisplay the command line. If a display-string is given
453 and not empty, this is shown in the status line (immedi‐
454 ately below the line being edited).
455 If the optional strings are given they are listed below
457 the prompt in the same way as completion lists are
458 printed. If no strings are given but the -c option is
459 used such a list is cleared.
460 Note that immediately after returning from running wid‐
462 gets, the command line will be redisplayed and the
463 strings displayed will be erased. Therefore, this option
464 is only useful for widgets that do not exit immediately
465 after using it.
466 This command can safely be called outside user defined
468 widgets; if zle is active, the display will be refreshed,
469 while if zle is not active, the command has no effect.
470 In this case there will usually be no other arguments.
471 The status is zero if zle was active, else one.
473 -M string
475 As with the -R option, the string will be displayed below
476 the command line; unlike the -R option, the string will
477 not be put into the status line but will instead be
478 printed normally below the prompt. This means that the
479 string will still be displayed after the widget returns
480 (until it is overwritten by subsequent commands).
481 -U string
483 This pushes the characters in the string onto the input
484 stack of ZLE. After the widget currently executed fin‐
485 ishes ZLE will behave as if the characters in the string
486 were typed by the user.
487 As ZLE uses a stack, if this option is used repeatedly
489 the last string pushed onto the stack will be processed
490 first. However, the characters in each string will be
491 processed in the order in which they appear in the
492 string.
493 -K keymap
495 Selects the keymap named keymap. An error message will
496 be displayed if there is no such keymap.
497 This keymap selection affects the interpretation of fol‐
499 lowing keystrokes within this invocation of ZLE. Any
500 following invocation (e.g., the next command line) will
501 start as usual with the `main' keymap selected.
502 -F [ -L | -w ] [ fd [ handler ] ]
504 Only available if your system supports one of the `poll'
505 or `select' system calls; most modern systems do.
506 Installs handler (the name of a shell function) to handle
508 input from file descriptor fd. Installing a handler for
509 an fd which is already handled causes the existing han‐
510 dler to be replaced. Any number of handlers for any num‐
511 ber of readable file descriptors may be installed. Note
512 that zle makes no attempt to check whether this fd is ac‐
513 tually readable when installing the handler. The user
514 must make their own arrangements for handling the file
515 descriptor when zle is not active.
516 When zle is attempting to read data, it will examine both
518 the terminal and the list of handled fd's. If data be‐
519 comes available on a handled fd, zle calls handler with
520 the fd which is ready for reading as the first argument.
521 Under normal circumstances this is the only argument, but
522 if an error was detected, a second argument provides de‐
523 tails: `hup' for a disconnect, `nval' for a closed or
524 otherwise invalid descriptor, or `err' for any other con‐
525 dition. Systems that support only the `select' system
526 call always use `err'.
527 If the option -w is also given, the handler is instead a
529 line editor widget, typically a shell function made into
530 a widget using `zle -N'. In that case handler can use
531 all the facilities of zle to update the current editing
532 line. Note, however, that as handling fd takes place at
533 a low level changes to the display will not automatically
534 appear; the widget should call `zle -R' to force redis‐
535 play. As of this writing, widget handlers only support a
536 single argument and thus are never passed a string for
537 error state, so widgets must be prepared to test the de‐
538 scriptor themselves.
539 If either type of handler produces output to the termi‐
541 nal, it should call `zle -I' before doing so (see below).
542 Handlers should not attempt to read from the terminal.
543 If no handler is given, but an fd is present, any handler
545 for that fd is removed. If there is none, an error mes‐
546 sage is printed and status 1 is returned.
547 If no arguments are given, or the -L option is supplied,
549 a list of handlers is printed in a form which can be
550 stored for later execution.
551 An fd (but not a handler) may optionally be given with
553 the -L option; in this case, the function will list the
554 handler if any, else silently return status 1.
555 Note that this feature should be used with care. Activ‐
557 ity on one of the fd's which is not properly handled can
558 cause the terminal to become unusable. Removing an fd
559 handler from within a signal trap may cause unpredictable
560 behavior.
561 Here is a simple example of using this feature. A con‐
563 nection to a remote TCP port is created using the ztcp
564 command; see the description of the zsh/net/tcp module in
565 zshmodules(1). Then a handler is installed which simply
566 prints out any data which arrives on this connection.
567 Note that `select' will indicate that the file descriptor
568 needs handling if the remote side has closed the connec‐
569 tion; we handle that by testing for a failed read.
570 if ztcp pwspc 2811; then
572 tcpfd=$REPLY
573 handler() {
574 zle -I
575 local line
576 if ! read -r line <&$1; then
577 # select marks this fd if we reach EOF,
578 # so handle this specially.
579 print "[Read on fd $1 failed, removing.]" >&2
580 zle -F $1
581 return 1
582 fi
583 print -r - $line
584 }
585 zle -F $tcpfd handler
586 fi
587 -I Unusually, this option is most useful outside ordinary
589 widget functions, though it may be used within if normal
590 output to the terminal is required. It invalidates the
591 current zle display in preparation for output; typically
592 this will be from a trap function. It has no effect if
593 zle is not active. When a trap exits, the shell checks
594 to see if the display needs restoring, hence the follow‐
595 ing will print output in such a way as not to disturb the
596 line being edited:
597 TRAPUSR1() {
599 # Invalidate zle display
600 [[ -o zle ]] && zle -I
601 # Show output
602 print Hello
603 }
604 In general, the trap function may need to test whether
606 zle is active before using this method (as shown in the
607 example), since the zsh/zle module may not even be
608 loaded; if it is not, the command can be skipped.
609 It is possible to call `zle -I' several times before con‐
611 trol is returned to the editor; the display will only be
612 invalidated the first time to minimise disruption.
613 Note that there are normally better ways of manipulating
615 the display from within zle widgets; see, for example,
616 `zle -R' above.
617 The returned status is zero if zle was invalidated, even
619 though this may have been by a previous call to `zle -I'
620 or by a system notification. To test if a zle widget may
621 be called at this point, execute zle with no arguments
622 and examine the return status.
623 -T This is used to add, list or remove internal transforma‐
625 tions on the processing performed by the line editor. It
626 is typically used only for debugging or testing and is
627 therefore of little interest to the general user.
628 `zle -T transformation func' specifies that the given
630 transformation (see below) is effected by shell function
631 func.
632 `zle -Tr transformation' removes the given transformation
634 if it was present (it is not an error if none was).
635 `zle -TL' can be used to list all transformations cur‐
637 rently in operation.
638 Currently the only transformation is tc. This is used
640 instead of outputting termcap codes to the terminal.
641 When the transformation is in operation the shell func‐
642 tion is passed the termcap code that would be output as
643 its first argument; if the operation required a numeric
644 argument, that is passed as a second argument. The func‐
645 tion should set the shell variable REPLY to the trans‐
646 formed termcap code. Typically this is used to produce
647 some simply formatted version of the code and optional
648 argument for debugging or testing. Note that this trans‐
649 formation is not applied to other non-printing characters
650 such as carriage returns and newlines.
651 widget [ -n num ] [ -f flag ] [ -Nw ] [ -K keymap ] args ...
653 Invoke the specified widget. This can only be done when
654 ZLE is active; normally this will be within a user-de‐
655 fined widget.
656 With the options -n and -N, the current numeric argument
658 will be saved and then restored after the call to widget;
659 `-n num' sets the numeric argument temporarily to num,
660 while `-N' sets it to the default, i.e. as if there were
661 none.
662 With the option -K, keymap will be used as the current
664 keymap during the execution of the widget. The previous
665 keymap will be restored when the widget exits.
666 Normally, calling a widget in this way does not set the
668 special parameter WIDGET and related parameters, so that
669 the environment appears as if the top-level widget called
670 by the user were still active. With the option -w, WID‐
671 GET and related parameters are set to reflect the widget
672 being executed by the zle call.
673 Normally, when widget returns the special parameter LAST‐
675 WIDGET will point to it. This can be inhibited by pass‐
676 ing the option -f nolast.
677 Any further arguments will be passed to the widget; note
679 that as standard argument handling is performed, any gen‐
680 eral argument list should be preceded by --. If it is a
681 shell function, these are passed down as positional pa‐
682 rameters; for builtin widgets it is up to the widget in
683 question what it does with them. Currently arguments are
684 only handled by the incremental-search commands, the his‐
685 tory-search-forward and -backward and the corresponding
686 functions prefixed by vi-, and by universal-argument. No
687 error is flagged if the command does not use the argu‐
688 ments, or only uses some of them.
689 The return status reflects the success or failure of the
691 operation carried out by the widget, or if it is a
692 user-defined widget the return status of the shell func‐
693 tion.
694 A non-zero return status causes the shell to beep when
696 the widget exits, unless the BEEP options was unset or
697 the widget was called via the zle command. Thus if a
698 user defined widget requires an immediate beep, it should
699 call the beep widget directly.
700
702 All actions in the editor are performed by `widgets'. A widget's job
703 is simply to perform some small action. The ZLE commands that key se‐
704 quences in keymaps are bound to are in fact widgets. Widgets can be
705 user-defined or built in.
706 The standard widgets built into ZLE are listed in the section `Standard
708 Widgets' below. Other built-in widgets can be defined by other modules
709 (see zshmodules(1)). Each built-in widget has two names: its normal
710 canonical name, and the same name preceded by a `.'. The `.' name is
711 special: it can't be rebound to a different widget. This makes the
712 widget available even when its usual name has been redefined.
713 User-defined widgets are defined using `zle -N', and implemented as
715 shell functions. When the widget is executed, the corresponding shell
716 function is executed, and can perform editing (or other) actions. It
717 is recommended that user-defined widgets should not have names starting
718 with `.'.
719
721 User-defined widgets, being implemented as shell functions, can execute
722 any normal shell command. They can also run other widgets (whether
723 built-in or user-defined) using the zle builtin command. The standard
724 input of the function is redirected from /dev/null to prevent external
725 commands from unintentionally blocking ZLE by reading from the termi‐
726 nal, but read -k or read -q can be used to read characters. Finally,
727 they can examine and edit the ZLE buffer being edited by reading and
728 setting the special parameters described below.
729 These special parameters are always available in widget functions, but
731 are not in any way special outside ZLE. If they have some normal value
732 outside ZLE, that value is temporarily inaccessible, but will return
733 when the widget function exits. These special parameters in fact have
734 local scope, like parameters created in a function using local.
735 Inside completion widgets and traps called while ZLE is active, these
737 parameters are available read-only.
738 Note that the parameters appear as local to any ZLE widget in which
740 they appear. Hence if it is desired to override them this needs to be
741 done within a nested function:
742 widget-function() {
744 # $WIDGET here refers to the special variable
745 # that is local inside widget-function
746 () {
747 # This anonymous nested function allows WIDGET
748 # to be used as a local variable. The -h
749 # removes the special status of the variable.
750 local -h WIDGET
751 }
752 }
753 BUFFER (scalar)
755 The entire contents of the edit buffer. If it is written to,
756 the cursor remains at the same offset, unless that would put it
757 outside the buffer.
758 BUFFERLINES (integer)
760 The number of screen lines needed for the edit buffer currently
761 displayed on screen (i.e. without any changes to the preceding
762 parameters done after the last redisplay); read-only.
763 CONTEXT (scalar)
765 The context in which zle was called to read a line; read-only.
766 One of the values:
767 start The start of a command line (at prompt PS1).
769 cont A continuation to a command line (at prompt PS2).
771 select In a select loop (at prompt PS3).
773 vared Editing a variable in vared.
775 CURSOR (integer)
777 The offset of the cursor, within the edit buffer. This is in
778 the range 0 to $#BUFFER, and is by definition equal to
779 $#LBUFFER. Attempts to move the cursor outside the buffer will
780 result in the cursor being moved to the appropriate end of the
781 buffer.
782 CUTBUFFER (scalar)
784 The last item cut using one of the `kill-' commands; the string
785 which the next yank would insert in the line. Later entries in
786 the kill ring are in the array killring. Note that the command
787 `zle copy-region-as-kill string' can be used to set the text of
788 the cut buffer from a shell function and cycle the kill ring in
789 the same way as interactively killing text.
790 HISTNO (integer)
792 The current history number. Setting this has the same effect as
793 moving up or down in the history to the corresponding history
794 line. An attempt to set it is ignored if the line is not stored
795 in the history. Note this is not the same as the parameter
796 HISTCMD, which always gives the number of the history line being
797 added to the main shell's history. HISTNO refers to the line
798 being retrieved within zle.
799 ISEARCHMATCH_ACTIVE (integer)
801 ISEARCHMATCH_START (integer)
802 ISEARCHMATCH_END (integer)
803 ISEARCHMATCH_ACTIVE indicates whether a part of the BUFFER is
804 currently matched by an incremental search pattern. ISEARCH‐
805 MATCH_START and ISEARCHMATCH_END give the location of the
806 matched part and are in the same units as CURSOR. They are only
807 valid for reading when ISEARCHMATCH_ACTIVE is non-zero.
808 All parameters are read-only.
810 KEYMAP (scalar)
812 The name of the currently selected keymap; read-only.
813 KEYS (scalar)
815 The keys typed to invoke this widget, as a literal string;
816 read-only.
817 KEYS_QUEUED_COUNT (integer)
819 The number of bytes pushed back to the input queue and therefore
820 available for reading immediately before any I/O is done;
821 read-only. See also PENDING; the two values are distinct.
822 killring (array)
824 The array of previously killed items, with the most recently
825 killed first. This gives the items that would be retrieved by a
826 yank-pop in the same order. Note, however, that the most re‐
827 cently killed item is in $CUTBUFFER; $killring shows the array
828 of previous entries.
829 The default size for the kill ring is eight, however the length
831 may be changed by normal array operations. Any empty string in
832 the kill ring is ignored by the yank-pop command, hence the size
833 of the array effectively sets the maximum length of the kill
834 ring, while the number of non-zero strings gives the current
835 length, both as seen by the user at the command line.
836 LASTABORTEDSEARCH (scalar)
838 The last search string used by an interactive search that was
839 aborted by the user (status 3 returned by the search widget).
840 LASTSEARCH (scalar)
842 The last search string used by an interactive search; read-only.
843 This is set even if the search failed (status 0, 1 or 2 returned
844 by the search widget), but not if it was aborted by the user.
845 LASTWIDGET (scalar)
847 The name of the last widget that was executed; read-only.
848 LBUFFER (scalar)
850 The part of the buffer that lies to the left of the cursor posi‐
851 tion. If it is assigned to, only that part of the buffer is re‐
852 placed, and the cursor remains between the new $LBUFFER and the
853 old $RBUFFER.
854 MARK (integer)
856 Like CURSOR, but for the mark. With vi-mode operators that wait
857 for a movement command to select a region of text, setting MARK
858 allows the selection to extend in both directions from the ini‐
859 tial cursor position.
860 NUMERIC (integer)
862 The numeric argument. If no numeric argument was given, this pa‐
863 rameter is unset. When this is set inside a widget function,
864 builtin widgets called with the zle builtin command will use the
865 value assigned. If it is unset inside a widget function, builtin
866 widgets called behave as if no numeric argument was given.
867 PENDING (integer)
869 The number of bytes pending for input, i.e. the number of bytes
870 which have already been typed and can immediately be read. On
871 systems where the shell is not able to get this information,
872 this parameter will always have a value of zero. Read-only.
873 See also KEYS_QUEUED_COUNT; the two values are distinct.
874 PREBUFFER (scalar)
876 In a multi-line input at the secondary prompt, this read-only
877 parameter contains the contents of the lines before the one the
878 cursor is currently in.
879 PREDISPLAY (scalar)
881 Text to be displayed before the start of the editable text buf‐
882 fer. This does not have to be a complete line; to display a
883 complete line, a newline must be appended explicitly. The text
884 is reset on each new invocation (but not recursive invocation)
885 of zle.
886 POSTDISPLAY (scalar)
888 Text to be displayed after the end of the editable text buffer.
889 This does not have to be a complete line; to display a complete
890 line, a newline must be prepended explicitly. The text is reset
891 on each new invocation (but not recursive invocation) of zle.
892 RBUFFER (scalar)
894 The part of the buffer that lies to the right of the cursor po‐
895 sition. If it is assigned to, only that part of the buffer is
896 replaced, and the cursor remains between the old $LBUFFER and
897 the new $RBUFFER.
898 REGION_ACTIVE (integer)
900 Indicates if the region is currently active. It can be assigned
901 0 or 1 to deactivate and activate the region respectively. A
902 value of 2 activates the region in line-wise mode with the high‐
903 lighted text extending for whole lines only; see Character High‐
904 lighting below.
905 region_highlight (array)
907 Each element of this array may be set to a string that describes
908 highlighting for an arbitrary region of the command line that
909 will take effect the next time the command line is redisplayed.
910 Highlighting of the non-editable parts of the command line in
911 PREDISPLAY and POSTDISPLAY are possible, but note that the P
912 flag is needed for character indexing to include PREDISPLAY.
913 Each string consists of the following whitespace-separated
915 parts:
916 • Optionally, a `P' to signify that the start and end off‐
918 set that follow include any string set by the PREDISPLAY
919 special parameter; this is needed if the predisplay
920 string itself is to be highlighted. Whitespace between
921 the `P' and the start offset is optional.
922 • A start offset in the same units as CURSOR.
924 • An end offset in the same units as CURSOR.
926 • A highlight specification in the same format as used for
928 contexts in the parameter zle_highlight, see the section
929 `Character Highlighting' below; for example, standout or
930 fg=red,bold.
931 • Optionally, a string of the form `memo=token'. The token
933 consists of everything between the `=' and the next
934 whitespace, comma, NUL, or the end of the string. The
935 token is preserved verbatim but not parsed in any way.
936 Plugins may use this to identify array elements they have
938 added: for example, a plugin might set token to its (the
939 plugin's) name and then use `region_highlight=( ${re‐
940 gion_highlight:#*memo=token} )' in order to remove array
941 elements it have added.
942 (This example uses the `${name:#pattern}' array-grepping
944 syntax described in the section `Parameter Expansion' in
945 zshexpn(1).)
946 For example,
948 region_highlight=("P0 20 bold memo=foobar")
950 specifies that the first twenty characters of the text including
952 any predisplay string should be highlighted in bold.
953 Note that the effect of region_highlight is not saved and disap‐
955 pears as soon as the line is accepted.
956 Note that zsh 5.8 and older do not support the `memo=token'
958 field and may misparse the third (highlight specification) field
959 when a memo is given.
960 The final highlighting on the command line depends on both re‐
963 gion_highlight and zle_highlight; see the section CHARACTER
964 HIGHLIGHTING below for details.
965 registers (associative array)
967 The contents of each of the vi register buffers. These are typi‐
968 cally set using vi-set-buffer followed by a delete, change or
969 yank command.
970 SUFFIX_ACTIVE (integer)
972 SUFFIX_START (integer)
973 SUFFIX_END (integer)
974 SUFFIX_ACTIVE indicates whether an auto-removable completion
975 suffix is currently active. SUFFIX_START and SUFFIX_END give the
976 location of the suffix and are in the same units as CURSOR. They
977 are only valid for reading when SUFFIX_ACTIVE is non-zero.
978 All parameters are read-only.
980 UNDO_CHANGE_NO (integer)
982 A number representing the state of the undo history. The only
983 use of this is passing as an argument to the undo widget in or‐
984 der to undo back to the recorded point. Read-only.
985 UNDO_LIMIT_NO (integer)
987 A number corresponding to an existing change in the undo his‐
988 tory; compare UNDO_CHANGE_NO. If this is set to a value greater
989 than zero, the undo command will not allow the line to be undone
990 beyond the given change number. It is still possible to use
991 `zle undo change' in a widget to undo beyond that point; in that
992 case, it will not be possible to undo at all until UNDO_LIMIT_NO
993 is reduced. Set to 0 to disable the limit.
994 A typical use of this variable in a widget function is as fol‐
996 lows (note the additional function scope is required):
997 () {
999 local UNDO_LIMIT_NO=$UNDO_CHANGE_NO
1000 # Perform some form of recursive edit.
1001 }
1002 WIDGET (scalar)
1004 The name of the widget currently being executed; read-only.
1005 WIDGETFUNC (scalar)
1007 The name of the shell function that implements a widget defined
1008 with either zle -N or zle -C. In the former case, this is the
1009 second argument to the zle -N command that defined the widget,
1010 or the first argument if there was no second argument. In the
1011 latter case this is the third argument to the zle -C command
1012 that defined the widget. Read-only.
1013 WIDGETSTYLE (scalar)
1015 Describes the implementation behind the completion widget cur‐
1016 rently being executed; the second argument that followed zle -C
1017 when the widget was defined. This is the name of a builtin com‐
1018 pletion widget. For widgets defined with zle -N this is set to
1019 the empty string. Read-only.
1020 YANK_ACTIVE (integer)
1022 YANK_START (integer)
1023 YANK_END (integer)
1024 YANK_ACTIVE indicates whether text has just been yanked (pasted)
1025 into the buffer. YANK_START and YANK_END give the location of
1026 the pasted text and are in the same units as CURSOR. They are
1027 only valid for reading when YANK_ACTIVE is non-zero. They can
1028 also be assigned by widgets that insert text in a yank-like
1029 fashion, for example wrappers of bracketed-paste. See also zle
1030 -f.
1031 YANK_ACTIVE is read-only.
1033 ZLE_RECURSIVE (integer)
1035 Usually zero, but incremented inside any instance of recur‐
1036 sive-edit. Hence indicates the current recursion level.
1037 ZLE_RECURSIVE is read-only.
1039 ZLE_STATE (scalar)
1041 Contains a set of space-separated words that describe the cur‐
1042 rent zle state.
1043 Currently, the states shown are the insert mode as set by the
1045 overwrite-mode or vi-replace widgets and whether history com‐
1046 mands will visit imported entries as controlled by the set-lo‐
1047 cal-history widget. The string contains `insert' if characters
1048 to be inserted on the command line move existing characters to
1049 the right or `overwrite' if characters to be inserted overwrite
1050 existing characters. It contains `localhistory' if only local
1051 history commands will be visited or `globalhistory' if imported
1052 history commands will also be visited.
1053 The substrings are sorted in alphabetical order so that if you
1055 want to test for two specific substrings in a future-proof way,
1056 you can do match by doing:
1057 if [[ $ZLE_STATE == *globalhistory*insert* ]]; then ...; fi
1059 Special Widgets
1061 There are a few user-defined widgets which are special to the shell.
1062 If they do not exist, no special action is taken. The environment pro‐
1063 vided is identical to that for any other editing widget.
1064 zle-isearch-exit
1066 Executed at the end of incremental search at the point where the
1067 isearch prompt is removed from the display. See zle-isearch-up‐
1068 date for an example.
1069 zle-isearch-update
1071 Executed within incremental search when the display is about to
1072 be redrawn. Additional output below the incremental search
1073 prompt can be generated by using `zle -M' within the widget.
1074 For example,
1075 zle-isearch-update() { zle -M "Line $HISTNO"; }
1077 zle -N zle-isearch-update
1078 Note the line output by `zle -M' is not deleted on exit from in‐
1080 cremental search. This can be done from a zle-isearch-exit wid‐
1081 get:
1082 zle-isearch-exit() { zle -M ""; }
1084 zle -N zle-isearch-exit
1085 zle-line-pre-redraw
1087 Executed whenever the input line is about to be redrawn, provid‐
1088 ing an opportunity to update the region_highlight array.
1089 zle-line-init
1091 Executed every time the line editor is started to read a new
1092 line of input. The following example puts the line editor into
1093 vi command mode when it starts up.
1094 zle-line-init() { zle -K vicmd; }
1096 zle -N zle-line-init
1097 (The command inside the function sets the keymap directly; it is
1099 equivalent to zle vi-cmd-mode.)
1100 zle-line-finish
1102 This is similar to zle-line-init but is executed every time the
1103 line editor has finished reading a line of input.
1104 zle-history-line-set
1106 Executed when the history line changes.
1107 zle-keymap-select
1109 Executed every time the keymap changes, i.e. the special parame‐
1110 ter KEYMAP is set to a different value, while the line editor is
1111 active. Initialising the keymap when the line editor starts
1112 does not cause the widget to be called.
1113 The value $KEYMAP within the function reflects the new keymap.
1115 The old keymap is passed as the sole argument.
1116 This can be used for detecting switches between the vi command
1118 (vicmd) and insert (usually main) keymaps.
1119
1121 The following is a list of all the standard widgets, and their default
1122 bindings in emacs mode, vi command mode and vi insert mode (the
1123 `emacs', `vicmd' and `viins' keymaps, respectively).
1124 Note that cursor keys are bound to movement keys in all three keymaps;
1126 the shell assumes that the cursor keys send the key sequences reported
1127 by the terminal-handling library (termcap or terminfo). The key se‐
1128 quences shown in the list are those based on the VT100, common on many
1129 modern terminals, but in fact these are not necessarily bound. In the
1130 case of the viins keymap, the initial escape character of the sequences
1131 serves also to return to the vicmd keymap: whether this happens is de‐
1132 termined by the KEYTIMEOUT parameter, see zshparam(1).
1133 Movement
1135 vi-backward-blank-word (unbound) (B) (unbound)
1136 Move backward one word, where a word is defined as a series of
1137 non-blank characters.
1138 vi-backward-blank-word-end (unbound) (gE) (unbound)
1140 Move to the end of the previous word, where a word is defined as
1141 a series of non-blank characters.
1142 backward-char (^B ESC-[D) (unbound) (unbound)
1144 Move backward one character.
1145 vi-backward-char (unbound) (^H h ^?) (ESC-[D)
1147 Move backward one character, without changing lines.
1148 backward-word (ESC-B ESC-b) (unbound) (unbound)
1150 Move to the beginning of the previous word.
1151 emacs-backward-word
1153 Move to the beginning of the previous word.
1154 vi-backward-word (unbound) (b) (unbound)
1156 Move to the beginning of the previous word, vi-style.
1157 vi-backward-word-end (unbound) (ge) (unbound)
1159 Move to the end of the previous word, vi-style.
1160 beginning-of-line (^A) (unbound) (unbound)
1162 Move to the beginning of the line. If already at the beginning
1163 of the line, move to the beginning of the previous line, if any.
1164 vi-beginning-of-line
1166 Move to the beginning of the line, without changing lines.
1167 down-line (unbound) (unbound) (unbound)
1169 Move down a line in the buffer.
1170 end-of-line (^E) (unbound) (unbound)
1172 Move to the end of the line. If already at the end of the line,
1173 move to the end of the next line, if any.
1174 vi-end-of-line (unbound) ($) (unbound)
1176 Move to the end of the line. If an argument is given to this
1177 command, the cursor will be moved to the end of the line (argu‐
1178 ment - 1) lines down.
1179 vi-forward-blank-word (unbound) (W) (unbound)
1181 Move forward one word, where a word is defined as a series of
1182 non-blank characters.
1183 vi-forward-blank-word-end (unbound) (E) (unbound)
1185 Move to the end of the current word, or, if at the end of the
1186 current word, to the end of the next word, where a word is de‐
1187 fined as a series of non-blank characters.
1188 forward-char (^F ESC-[C) (unbound) (unbound)
1190 Move forward one character.
1191 vi-forward-char (unbound) (space l) (ESC-[C)
1193 Move forward one character.
1194 vi-find-next-char (^X^F) (f) (unbound)
1196 Read a character from the keyboard, and move to the next occur‐
1197 rence of it in the line.
1198 vi-find-next-char-skip (unbound) (t) (unbound)
1200 Read a character from the keyboard, and move to the position
1201 just before the next occurrence of it in the line.
1202 vi-find-prev-char (unbound) (F) (unbound)
1204 Read a character from the keyboard, and move to the previous oc‐
1205 currence of it in the line.
1206 vi-find-prev-char-skip (unbound) (T) (unbound)
1208 Read a character from the keyboard, and move to the position
1209 just after the previous occurrence of it in the line.
1210 vi-first-non-blank (unbound) (^) (unbound)
1212 Move to the first non-blank character in the line.
1213 vi-forward-word (unbound) (w) (unbound)
1215 Move forward one word, vi-style.
1216 forward-word (ESC-F ESC-f) (unbound) (unbound)
1218 Move to the beginning of the next word. The editor's idea of a
1219 word is specified with the WORDCHARS parameter.
1220 emacs-forward-word
1222 Move to the end of the next word.
1223 vi-forward-word-end (unbound) (e) (unbound)
1225 Move to the end of the next word.
1226 vi-goto-column (ESC-|) (|) (unbound)
1228 Move to the column specified by the numeric argument.
1229 vi-goto-mark (unbound) (`) (unbound)
1231 Move to the specified mark.
1232 vi-goto-mark-line (unbound) (') (unbound)
1234 Move to beginning of the line containing the specified mark.
1235 vi-repeat-find (unbound) (;) (unbound)
1237 Repeat the last vi-find command.
1238 vi-rev-repeat-find (unbound) (,) (unbound)
1240 Repeat the last vi-find command in the opposite direction.
1241 up-line (unbound) (unbound) (unbound)
1243 Move up a line in the buffer.
1244 History Control
1246 beginning-of-buffer-or-history (ESC-<) (gg) (unbound)
1247 Move to the beginning of the buffer, or if already there, move
1248 to the first event in the history list.
1249 beginning-of-line-hist
1251 Move to the beginning of the line. If already at the beginning
1252 of the buffer, move to the previous history line.
1253 beginning-of-history
1255 Move to the first event in the history list.
1256 down-line-or-history (^N ESC-[B) (j) (ESC-[B)
1258 Move down a line in the buffer, or if already at the bottom
1259 line, move to the next event in the history list.
1260 vi-down-line-or-history (unbound) (+) (unbound)
1262 Move down a line in the buffer, or if already at the bottom
1263 line, move to the next event in the history list. Then move to
1264 the first non-blank character on the line.
1265 down-line-or-search
1267 Move down a line in the buffer, or if already at the bottom
1268 line, search forward in the history for a line beginning with
1269 the first word in the buffer.
1270 If called from a function by the zle command with arguments, the
1272 first argument is taken as the string for which to search,
1273 rather than the first word in the buffer.
1274 down-history (unbound) (^N) (unbound)
1276 Move to the next event in the history list.
1277 history-beginning-search-backward
1279 Search backward in the history for a line beginning with the
1280 current line up to the cursor. This leaves the cursor in its
1281 original position.
1282 end-of-buffer-or-history (ESC->) (unbound) (unbound)
1284 Move to the end of the buffer, or if already there, move to the
1285 last event in the history list.
1286 end-of-line-hist
1288 Move to the end of the line. If already at the end of the buf‐
1289 fer, move to the next history line.
1290 end-of-history
1292 Move to the last event in the history list.
1293 vi-fetch-history (unbound) (G) (unbound)
1295 Fetch the history line specified by the numeric argument. This
1296 defaults to the current history line (i.e. the one that isn't
1297 history yet).
1298 history-incremental-search-backward (^R ^Xr) (unbound) (unbound)
1300 Search backward incrementally for a specified string. The
1301 search is case-insensitive if the search string does not have
1302 uppercase letters and no numeric argument was given. The string
1303 may begin with `^' to anchor the search to the beginning of the
1304 line. When called from a user-defined function returns the fol‐
1305 lowing statuses: 0, if the search succeeded; 1, if the search
1306 failed; 2, if the search term was a bad pattern; 3, if the
1307 search was aborted by the send-break command.
1308 A restricted set of editing functions is available in the
1310 mini-buffer. Keys are looked up in the special isearch keymap,
1311 and if not found there in the main keymap (note that by default
1312 the isearch keymap is empty). An interrupt signal, as defined
1313 by the stty setting, will stop the search and go back to the
1314 original line. An undefined key will have the same effect.
1315 Note that the following always perform the same task within in‐
1316 cremental searches and cannot be replaced by user defined wid‐
1317 gets, nor can the set of functions be extended. The supported
1318 functions are:
1319 accept-and-hold
1321 accept-and-infer-next-history
1322 accept-line
1323 accept-line-and-down-history
1324 Perform the usual function after exiting incremental
1325 search. The command line displayed is executed.
1326 backward-delete-char
1328 vi-backward-delete-char
1329 Back up one place in the search history. If the search
1330 has been repeated this does not immediately erase a char‐
1331 acter in the minibuffer.
1332 accept-search
1334 Exit incremental search, retaining the command line but
1335 performing no further action. Note that this function is
1336 not bound by default and has no effect outside incremen‐
1337 tal search.
1338 backward-delete-word
1340 backward-kill-word
1341 vi-backward-kill-word
1342 Back up one character in the minibuffer; if multiple
1343 searches have been performed since the character was in‐
1344 serted the search history is rewound to the point just
1345 before the character was entered. Hence this has the ef‐
1346 fect of repeating backward-delete-char.
1347 clear-screen
1349 Clear the screen, remaining in incremental search mode.
1350 history-incremental-search-backward
1352 Find the next occurrence of the contents of the mini-buf‐
1353 fer. If the mini-buffer is empty, the most recent previ‐
1354 ously used search string is reinstated.
1355 history-incremental-search-forward
1357 Invert the sense of the search.
1358 magic-space
1360 Inserts a non-magical space.
1361 quoted-insert
1363 vi-quoted-insert
1364 Quote the character to insert into the minibuffer.
1365 redisplay
1367 Redisplay the command line, remaining in incremental
1368 search mode.
1369 vi-cmd-mode
1371 Select the `vicmd' keymap; the `main' keymap (insert
1372 mode) will be selected initially.
1373 In addition, the modifications that were made while in vi
1375 insert mode are merged to form a single undo event.
1376 vi-repeat-search
1378 vi-rev-repeat-search
1379 Repeat the search. The direction of the search is indi‐
1380 cated in the mini-buffer.
1381 Any character that is not bound to one of the above functions,
1383 or self-insert or self-insert-unmeta, will cause the mode to be
1384 exited. The character is then looked up and executed in the
1385 keymap in effect at that point.
1386 When called from a widget function by the zle command, the in‐
1388 cremental search commands can take a string argument. This will
1389 be treated as a string of keys, as for arguments to the bindkey
1390 command, and used as initial input for the command. Any charac‐
1391 ters in the string which are unused by the incremental search
1392 will be silently ignored. For example,
1393 zle history-incremental-search-backward forceps
1395 will search backwards for forceps, leaving the minibuffer con‐
1397 taining the string `forceps'.
1398 history-incremental-search-forward (^S ^Xs) (unbound) (unbound)
1400 Search forward incrementally for a specified string. The search
1401 is case-insensitive if the search string does not have uppercase
1402 letters and no numeric argument was given. The string may begin
1403 with `^' to anchor the search to the beginning of the line. The
1404 functions available in the mini-buffer are the same as for his‐
1405 tory-incremental-search-backward.
1406 history-incremental-pattern-search-backward
1408 history-incremental-pattern-search-forward
1409 These widgets behave similarly to the corresponding widgets with
1410 no -pattern, but the search string typed by the user is treated
1411 as a pattern, respecting the current settings of the various op‐
1412 tions affecting pattern matching. See FILENAME GENERATION in
1413 zshexpn(1) for a description of patterns. If no numeric argu‐
1414 ment was given lowercase letters in the search string may match
1415 uppercase letters in the history. The string may begin with `^'
1416 to anchor the search to the beginning of the line.
1417 The prompt changes to indicate an invalid pattern; this may sim‐
1419 ply indicate the pattern is not yet complete.
1420 Note that only non-overlapping matches are reported, so an ex‐
1422 pression with wildcards may return fewer matches on a line than
1423 are visible by inspection.
1424 history-search-backward (ESC-P ESC-p) (unbound) (unbound)
1426 Search backward in the history for a line beginning with the
1427 first word in the buffer.
1428 If called from a function by the zle command with arguments, the
1430 first argument is taken as the string for which to search,
1431 rather than the first word in the buffer.
1432 vi-history-search-backward (unbound) (/) (unbound)
1434 Search backward in the history for a specified string. The
1435 string may begin with `^' to anchor the search to the beginning
1436 of the line.
1437 A restricted set of editing functions is available in the
1439 mini-buffer. An interrupt signal, as defined by the stty set‐
1440 ting, will stop the search. The functions available in the
1441 mini-buffer are: accept-line, backward-delete-char, vi-back‐
1442 ward-delete-char, backward-kill-word, vi-backward-kill-word,
1443 clear-screen, redisplay, quoted-insert and vi-quoted-insert.
1444 vi-cmd-mode is treated the same as accept-line, and magic-space
1446 is treated as a space. Any other character that is not bound to
1447 self-insert or self-insert-unmeta will beep and be ignored. If
1448 the function is called from vi command mode, the bindings of the
1449 current insert mode will be used.
1450 If called from a function by the zle command with arguments, the
1452 first argument is taken as the string for which to search,
1453 rather than the first word in the buffer.
1454 history-search-forward (ESC-N ESC-n) (unbound) (unbound)
1456 Search forward in the history for a line beginning with the
1457 first word in the buffer.
1458 If called from a function by the zle command with arguments, the
1460 first argument is taken as the string for which to search,
1461 rather than the first word in the buffer.
1462 vi-history-search-forward (unbound) (?) (unbound)
1464 Search forward in the history for a specified string. The
1465 string may begin with `^' to anchor the search to the beginning
1466 of the line. The functions available in the mini-buffer are the
1467 same as for vi-history-search-backward. Argument handling is
1468 also the same as for that command.
1469 infer-next-history (^X^N) (unbound) (unbound)
1471 Search in the history list for a line matching the current one
1472 and fetch the event following it.
1473 insert-last-word (ESC-_ ESC-.) (unbound) (unbound)
1475 Insert the last word from the previous history event at the cur‐
1476 sor position. If a positive numeric argument is given, insert
1477 that word from the end of the previous history event. If the
1478 argument is zero or negative insert that word from the left
1479 (zero inserts the previous command word). Repeating this com‐
1480 mand replaces the word just inserted with the last word from the
1481 history event prior to the one just used; numeric arguments can
1482 be used in the same way to pick a word from that event.
1483 When called from a shell function invoked from a user-defined
1485 widget, the command can take one to three arguments. The first
1486 argument specifies a history offset which applies to successive
1487 calls to this widget: if it is -1, the default behaviour is
1488 used, while if it is 1, successive calls will move forwards
1489 through the history. The value 0 can be used to indicate that
1490 the history line examined by the previous execution of the com‐
1491 mand will be reexamined. Note that negative numbers should be
1492 preceded by a `--' argument to avoid confusing them with op‐
1493 tions.
1494 If two arguments are given, the second specifies the word on the
1496 command line in normal array index notation (as a more natural
1497 alternative to the numeric argument). Hence 1 is the first
1498 word, and -1 (the default) is the last word.
1499 If a third argument is given, its value is ignored, but it is
1501 used to signify that the history offset is relative to the cur‐
1502 rent history line, rather than the one remembered after the pre‐
1503 vious invocations of insert-last-word.
1504 For example, the default behaviour of the command corresponds to
1506 zle insert-last-word -- -1 -1
1508 while the command
1510 zle insert-last-word -- -1 1 -
1512 always copies the first word of the line in the history immedi‐
1514 ately before the line being edited. This has the side effect
1515 that later invocations of the widget will be relative to that
1516 line.
1517 vi-repeat-search (unbound) (n) (unbound)
1519 Repeat the last vi history search.
1520 vi-rev-repeat-search (unbound) (N) (unbound)
1522 Repeat the last vi history search, but in reverse.
1523 up-line-or-history (^P ESC-[A) (k) (ESC-[A)
1525 Move up a line in the buffer, or if already at the top line,
1526 move to the previous event in the history list.
1527 vi-up-line-or-history (unbound) (-) (unbound)
1529 Move up a line in the buffer, or if already at the top line,
1530 move to the previous event in the history list. Then move to
1531 the first non-blank character on the line.
1532 up-line-or-search
1534 Move up a line in the buffer, or if already at the top line,
1535 search backward in the history for a line beginning with the
1536 first word in the buffer.
1537 If called from a function by the zle command with arguments, the
1539 first argument is taken as the string for which to search,
1540 rather than the first word in the buffer.
1541 up-history (unbound) (^P) (unbound)
1543 Move to the previous event in the history list.
1544 history-beginning-search-forward
1546 Search forward in the history for a line beginning with the cur‐
1547 rent line up to the cursor. This leaves the cursor in its orig‐
1548 inal position.
1549 set-local-history
1551 By default, history movement commands visit the imported lines
1552 as well as the local lines. This widget lets you toggle this on
1553 and off, or set it with the numeric argument. Zero for both lo‐
1554 cal and imported lines and nonzero for only local lines.
1555 Modifying Text
1557 vi-add-eol (unbound) (A) (unbound)
1558 Move to the end of the line and enter insert mode.
1559 vi-add-next (unbound) (a) (unbound)
1561 Enter insert mode after the current cursor position, without
1562 changing lines.
1563 backward-delete-char (^H ^?) (unbound) (unbound)
1565 Delete the character behind the cursor.
1566 vi-backward-delete-char (unbound) (X) (^H)
1568 Delete the character behind the cursor, without changing lines.
1569 If in insert mode, this won't delete past the point where insert
1570 mode was last entered.
1571 backward-delete-word
1573 Delete the word behind the cursor.
1574 backward-kill-line
1576 Kill from the beginning of the line to the cursor position.
1577 backward-kill-word (^W ESC-^H ESC-^?) (unbound) (unbound)
1579 Kill the word behind the cursor.
1580 vi-backward-kill-word (unbound) (unbound) (^W)
1582 Kill the word behind the cursor, without going past the point
1583 where insert mode was last entered.
1584 capitalize-word (ESC-C ESC-c) (unbound) (unbound)
1586 Capitalize the current word and move past it.
1587 vi-change (unbound) (c) (unbound)
1589 Read a movement command from the keyboard, and kill from the
1590 cursor position to the endpoint of the movement. Then enter in‐
1591 sert mode. If the command is vi-change, change the current
1592 line.
1593 For compatibility with vi, if the command is vi-forward-word or
1595 vi-forward-blank-word, the whitespace after the word is not in‐
1596 cluded. If you prefer the more consistent behaviour with the
1597 whitespace included use the following key binding:
1598 bindkey -a -s cw dwi
1600 vi-change-eol (unbound) (C) (unbound)
1602 Kill to the end of the line and enter insert mode.
1603 vi-change-whole-line (unbound) (S) (unbound)
1605 Kill the current line and enter insert mode.
1606 copy-region-as-kill (ESC-W ESC-w) (unbound) (unbound)
1608 Copy the area from the cursor to the mark to the kill buffer.
1609 If called from a ZLE widget function in the form `zle copy-re‐
1611 gion-as-kill string' then string will be taken as the text to
1612 copy to the kill buffer. The cursor, the mark and the text on
1613 the command line are not used in this case.
1614 copy-prev-word (ESC-^_) (unbound) (unbound)
1616 Duplicate the word to the left of the cursor.
1617 copy-prev-shell-word
1619 Like copy-prev-word, but the word is found by using shell pars‐
1620 ing, whereas copy-prev-word looks for blanks. This makes a dif‐
1621 ference when the word is quoted and contains spaces.
1622 vi-delete (unbound) (d) (unbound)
1624 Read a movement command from the keyboard, and kill from the
1625 cursor position to the endpoint of the movement. If the command
1626 is vi-delete, kill the current line.
1627 delete-char
1629 Delete the character under the cursor.
1630 vi-delete-char (unbound) (x) (unbound)
1632 Delete the character under the cursor, without going past the
1633 end of the line.
1634 delete-word
1636 Delete the current word.
1637 down-case-word (ESC-L ESC-l) (unbound) (unbound)
1639 Convert the current word to all lowercase and move past it.
1640 vi-down-case (unbound) (gu) (unbound)
1642 Read a movement command from the keyboard, and convert all char‐
1643 acters from the cursor position to the endpoint of the movement
1644 to lowercase. If the movement command is vi-down-case, swap the
1645 case of all characters on the current line.
1646 kill-word (ESC-D ESC-d) (unbound) (unbound)
1648 Kill the current word.
1649 gosmacs-transpose-chars
1651 Exchange the two characters behind the cursor.
1652 vi-indent (unbound) (>) (unbound)
1654 Indent a number of lines.
1655 vi-insert (unbound) (i) (unbound)
1657 Enter insert mode.
1658 vi-insert-bol (unbound) (I) (unbound)
1660 Move to the first non-blank character on the line and enter in‐
1661 sert mode.
1662 vi-join (^X^J) (J) (unbound)
1664 Join the current line with the next one.
1665 kill-line (^K) (unbound) (unbound)
1667 Kill from the cursor to the end of the line. If already on the
1668 end of the line, kill the newline character.
1669 vi-kill-line (unbound) (unbound) (^U)
1671 Kill from the cursor back to wherever insert mode was last en‐
1672 tered.
1673 vi-kill-eol (unbound) (D) (unbound)
1675 Kill from the cursor to the end of the line.
1676 kill-region
1678 Kill from the cursor to the mark.
1679 kill-buffer (^X^K) (unbound) (unbound)
1681 Kill the entire buffer.
1682 kill-whole-line (^U) (unbound) (unbound)
1684 Kill the current line.
1685 vi-match-bracket (^X^B) (%) (unbound)
1687 Move to the bracket character (one of {}, () or []) that matches
1688 the one under the cursor. If the cursor is not on a bracket
1689 character, move forward without going past the end of the line
1690 to find one, and then go to the matching bracket.
1691 vi-open-line-above (unbound) (O) (unbound)
1693 Open a line above the cursor and enter insert mode.
1694 vi-open-line-below (unbound) (o) (unbound)
1696 Open a line below the cursor and enter insert mode.
1697 vi-oper-swap-case (unbound) (g~) (unbound)
1699 Read a movement command from the keyboard, and swap the case of
1700 all characters from the cursor position to the endpoint of the
1701 movement. If the movement command is vi-oper-swap-case, swap
1702 the case of all characters on the current line.
1703 overwrite-mode (^X^O) (unbound) (unbound)
1705 Toggle between overwrite mode and insert mode.
1706 vi-put-before (unbound) (P) (unbound)
1708 Insert the contents of the kill buffer before the cursor. If
1709 the kill buffer contains a sequence of lines (as opposed to
1710 characters), paste it above the current line.
1711 vi-put-after (unbound) (p) (unbound)
1713 Insert the contents of the kill buffer after the cursor. If the
1714 kill buffer contains a sequence of lines (as opposed to charac‐
1715 ters), paste it below the current line.
1716 put-replace-selection (unbound) (unbound) (unbound)
1718 Replace the contents of the current region or selection with the
1719 contents of the kill buffer. If the kill buffer contains a se‐
1720 quence of lines (as opposed to characters), the current line
1721 will be split by the pasted lines.
1722 quoted-insert (^V) (unbound) (unbound)
1724 Insert the next character typed into the buffer literally. An
1725 interrupt character will not be inserted.
1726 vi-quoted-insert (unbound) (unbound) (^Q ^V)
1728 Display a `^' at the cursor position, and insert the next char‐
1729 acter typed into the buffer literally. An interrupt character
1730 will not be inserted.
1731 quote-line (ESC-') (unbound) (unbound)
1733 Quote the current line; that is, put a `'' character at the be‐
1734 ginning and the end, and convert all `'' characters to `'\'''.
1735 quote-region (ESC-") (unbound) (unbound)
1737 Quote the region from the cursor to the mark.
1738 vi-replace (unbound) (R) (unbound)
1740 Enter overwrite mode.
1741 vi-repeat-change (unbound) (.) (unbound)
1743 Repeat the last vi mode text modification. If a count was used
1744 with the modification, it is remembered. If a count is given to
1745 this command, it overrides the remembered count, and is remem‐
1746 bered for future uses of this command. The cut buffer specifi‐
1747 cation is similarly remembered.
1748 vi-replace-chars (unbound) (r) (unbound)
1750 Replace the character under the cursor with a character read
1751 from the keyboard.
1752 self-insert (printable characters) (unbound) (printable characters and
1754 some control characters)
1755 Insert a character into the buffer at the cursor position.
1756 self-insert-unmeta (ESC-^I ESC-^J ESC-^M) (unbound) (unbound)
1758 Insert a character into the buffer after stripping the meta bit
1759 and converting ^M to ^J.
1760 vi-substitute (unbound) (s) (unbound)
1762 Substitute the next character(s).
1763 vi-swap-case (unbound) (~) (unbound)
1765 Swap the case of the character under the cursor and move past
1766 it.
1767 transpose-chars (^T) (unbound) (unbound)
1769 Exchange the two characters to the left of the cursor if at end
1770 of line, else exchange the character under the cursor with the
1771 character to the left.
1772 transpose-words (ESC-T ESC-t) (unbound) (unbound)
1774 Exchange the current word with the one before it.
1775 With a positive numeric argument N, the word around the cursor,
1777 or following it if the cursor is between words, is transposed
1778 with the preceding N words. The cursor is put at the end of the
1779 resulting group of words.
1780 With a negative numeric argument -N, the effect is the same as
1782 using a positive argument N except that the original cursor po‐
1783 sition is retained, regardless of how the words are rearranged.
1784 vi-unindent (unbound) (<) (unbound)
1786 Unindent a number of lines.
1787 vi-up-case (unbound) (gU) (unbound)
1789 Read a movement command from the keyboard, and convert all char‐
1790 acters from the cursor position to the endpoint of the movement
1791 to lowercase. If the movement command is vi-up-case, swap the
1792 case of all characters on the current line.
1793 up-case-word (ESC-U ESC-u) (unbound) (unbound)
1795 Convert the current word to all caps and move past it.
1796 yank (^Y) (unbound) (unbound)
1798 Insert the contents of the kill buffer at the cursor position.
1799 yank-pop (ESC-y) (unbound) (unbound)
1801 Remove the text just yanked, rotate the kill-ring (the history
1802 of previously killed text) and yank the new top. Only works
1803 following yank, vi-put-before, vi-put-after or yank-pop.
1804 vi-yank (unbound) (y) (unbound)
1806 Read a movement command from the keyboard, and copy the region
1807 from the cursor position to the endpoint of the movement into
1808 the kill buffer. If the command is vi-yank, copy the current
1809 line.
1810 vi-yank-whole-line (unbound) (Y) (unbound)
1812 Copy the current line into the kill buffer.
1813 vi-yank-eol
1815 Copy the region from the cursor position to the end of the line
1816 into the kill buffer. Arguably, this is what Y should do in vi,
1817 but it isn't what it actually does.
1818 Arguments
1820 digit-argument (ESC-0..ESC-9) (1-9) (unbound)
1821 Start a new numeric argument, or add to the current one. See
1822 also vi-digit-or-beginning-of-line. This only works if bound to
1823 a key sequence ending in a decimal digit.
1824 Inside a widget function, a call to this function treats the
1826 last key of the key sequence which called the widget as the
1827 digit.
1828 neg-argument (ESC--) (unbound) (unbound)
1830 Changes the sign of the following argument.
1831 universal-argument
1833 Multiply the argument of the next command by 4. Alternatively,
1834 if this command is followed by an integer (positive or nega‐
1835 tive), use that as the argument for the next command. Thus dig‐
1836 its cannot be repeated using this command. For example, if this
1837 command occurs twice, followed immediately by forward-char, move
1838 forward sixteen spaces; if instead it is followed by -2, then
1839 forward-char, move backward two spaces.
1840 Inside a widget function, if passed an argument, i.e. `zle uni‐
1842 versal-argument num', the numeric argument will be set to num;
1843 this is equivalent to `NUMERIC=num'.
1844 argument-base
1846 Use the existing numeric argument as a numeric base, which must
1847 be in the range 2 to 36 inclusive. Subsequent use of digit-ar‐
1848 gument and universal-argument will input a new numeric argument
1849 in the given base. The usual hexadecimal convention is used:
1850 the letter a or A corresponds to 10, and so on. Arguments in
1851 bases requiring digits from 10 upwards are more conveniently in‐
1852 put with universal-argument, since ESC-a etc. are not usually
1853 bound to digit-argument.
1854 The function can be used with a command argument inside a
1856 user-defined widget. The following code sets the base to 16 and
1857 lets the user input a hexadecimal argument until a key out of
1858 the digit range is typed:
1859 zle argument-base 16
1861 zle universal-argument
1862 Completion
1864 accept-and-menu-complete
1865 In a menu completion, insert the current completion into the
1866 buffer, and advance to the next possible completion.
1867 complete-word
1869 Attempt completion on the current word.
1870 delete-char-or-list (^D) (unbound) (unbound)
1872 Delete the character under the cursor. If the cursor is at the
1873 end of the line, list possible completions for the current word.
1874 expand-cmd-path
1876 Expand the current command to its full pathname.
1877 expand-or-complete (TAB) (unbound) (TAB)
1879 Attempt shell expansion on the current word. If that fails, at‐
1880 tempt completion.
1881 expand-or-complete-prefix
1883 Attempt shell expansion on the current word up to cursor.
1884 expand-history (ESC-space ESC-!) (unbound) (unbound)
1886 Perform history expansion on the edit buffer.
1887 expand-word (^X*) (unbound) (unbound)
1889 Attempt shell expansion on the current word.
1890 list-choices (ESC-^D) (^D =) (^D)
1892 List possible completions for the current word.
1893 list-expand (^Xg ^XG) (^G) (^G)
1895 List the expansion of the current word.
1896 magic-space
1898 Perform history expansion and insert a space into the buffer.
1899 This is intended to be bound to space.
1900 menu-complete
1902 Like complete-word, except that menu completion is used. See
1903 the MENU_COMPLETE option.
1904 menu-expand-or-complete
1906 Like expand-or-complete, except that menu completion is used.
1907 reverse-menu-complete
1909 Perform menu completion, like menu-complete, except that if a
1910 menu completion is already in progress, move to the previous
1911 completion rather than the next.
1912 end-of-list
1914 When a previous completion displayed a list below the prompt,
1915 this widget can be used to move the prompt below the list.
1916 Miscellaneous
1918 accept-and-hold (ESC-A ESC-a) (unbound) (unbound)
1919 Push the contents of the buffer on the buffer stack and execute
1920 it.
1921 accept-and-infer-next-history
1923 Execute the contents of the buffer. Then search the history
1924 list for a line matching the current one and push the event fol‐
1925 lowing onto the buffer stack.
1926 accept-line (^J ^M) (^J ^M) (^J ^M)
1928 Finish editing the buffer. Normally this causes the buffer to
1929 be executed as a shell command.
1930 accept-line-and-down-history (^O) (unbound) (unbound)
1932 Execute the current line, and push the next history event on the
1933 buffer stack.
1934 auto-suffix-remove
1936 If the previous action added a suffix (space, slash, etc.) to
1937 the word on the command line, remove it. Otherwise do nothing.
1938 Removing the suffix ends any active menu completion or menu se‐
1939 lection.
1940 This widget is intended to be called from user-defined widgets
1942 to enforce a desired suffix-removal behavior.
1943 auto-suffix-retain
1945 If the previous action added a suffix (space, slash, etc.) to
1946 the word on the command line, force it to be preserved. Other‐
1947 wise do nothing. Retaining the suffix ends any active menu com‐
1948 pletion or menu selection.
1949 This widget is intended to be called from user-defined widgets
1951 to enforce a desired suffix-preservation behavior.
1952 beep Beep, unless the BEEP option is unset.
1954 bracketed-paste (^[[200~) (^[[200~) (^[[200~)
1956 This widget is invoked when text is pasted to the terminal emu‐
1957 lator. It is not intended to be bound to actual keys but instead
1958 to the special sequence generated by the terminal emulator when
1959 text is pasted.
1960 When invoked interactively, the pasted text is inserted to the
1962 buffer and placed in the cutbuffer. If a numeric argument is
1963 given, shell quoting will be applied to the pasted text before
1964 it is inserted.
1965 When a named buffer is specified with vi-set-buffer ("x), the
1967 pasted text is stored in that named buffer but not inserted.
1968 When called from a widget function as `bracketed-paste name`,
1970 the pasted text is assigned to the variable name and no other
1971 processing is done.
1972 See also the zle_bracketed_paste parameter.
1974 vi-cmd-mode (^X^V) (unbound) (^[)
1976 Enter command mode; that is, select the `vicmd' keymap. Yes,
1977 this is bound by default in emacs mode.
1978 vi-caps-lock-panic
1980 Hang until any lowercase key is pressed. This is for vi users
1981 without the mental capacity to keep track of their caps lock key
1982 (like the author).
1983 clear-screen (^L ESC-^L) (^L) (^L)
1985 Clear the screen and redraw the prompt.
1986 deactivate-region
1988 Make the current region inactive. This disables vim-style visual
1989 selection mode if it is active.
1990 describe-key-briefly
1992 Reads a key sequence, then prints the function bound to that se‐
1993 quence.
1994 exchange-point-and-mark (^X^X) (unbound) (unbound)
1996 Exchange the cursor position (point) with the position of the
1997 mark. Unless a negative numeric argument is given, the region
1998 between point and mark is activated so that it can be high‐
1999 lighted. If a zero numeric argument is given, the region is ac‐
2000 tivated but point and mark are not swapped.
2001 execute-named-cmd (ESC-x) (:) (unbound)
2003 Read the name of an editor command and execute it. Aliasing
2004 this widget with `zle -A' or replacing it with `zle -N' has no
2005 effect when interpreting key bindings, but `zle exe‐
2006 cute-named-cmd' will invoke such an alias or replacement.
2007 A restricted set of editing functions is available in the
2009 mini-buffer. Keys are looked up in the special command keymap,
2010 and if not found there in the main keymap. An interrupt signal,
2011 as defined by the stty setting, will abort the function. Note
2012 that the following always perform the same task within the exe‐
2013 cuted-named-cmd environment and cannot be replaced by user de‐
2014 fined widgets, nor can the set of functions be extended. The
2015 allowed functions are: backward-delete-char, vi-back‐
2016 ward-delete-char, clear-screen, redisplay, quoted-insert,
2017 vi-quoted-insert, backward-kill-word, vi-backward-kill-word,
2018 kill-whole-line, vi-kill-line, backward-kill-line, list-choices,
2019 delete-char-or-list, complete-word, accept-line, expand-or-com‐
2020 plete and expand-or-complete-prefix.
2021 kill-region kills the last word, and vi-cmd-mode is treated the
2023 same as accept-line. The space and tab characters, if not bound
2024 to one of these functions, will complete the name and then list
2025 the possibilities if the AUTO_LIST option is set. Any other
2026 character that is not bound to self-insert or self-insert-unmeta
2027 will beep and be ignored. The bindings of the current insert
2028 mode will be used.
2029 Currently this command may not be redefined or called by name.
2031 execute-last-named-cmd (ESC-z) (unbound) (unbound)
2033 Redo the last function executed with execute-named-cmd.
2034 Like execute-named-cmd, this command may not be redefined, but
2036 it may be called by name.
2037 get-line (ESC-G ESC-g) (unbound) (unbound)
2039 Pop the top line off the buffer stack and insert it at the cur‐
2040 sor position.
2041 pound-insert (unbound) (#) (unbound)
2043 If there is no # character at the beginning of the buffer, add
2044 one to the beginning of each line. If there is one, remove a #
2045 from each line that has one. In either case, accept the current
2046 line. The INTERACTIVE_COMMENTS option must be set for this to
2047 have any usefulness.
2048 vi-pound-insert
2050 If there is no # character at the beginning of the current line,
2051 add one. If there is one, remove it. The INTERACTIVE_COMMENTS
2052 option must be set for this to have any usefulness.
2053 push-input
2055 Push the entire current multiline construct onto the buffer
2056 stack and return to the top-level (PS1) prompt. If the current
2057 parser construct is only a single line, this is exactly like
2058 push-line. Next time the editor starts up or is popped with
2059 get-line, the construct will be popped off the top of the buffer
2060 stack and loaded into the editing buffer.
2061 push-line (^Q ESC-Q ESC-q) (unbound) (unbound)
2063 Push the current buffer onto the buffer stack and clear the buf‐
2064 fer. Next time the editor starts up, the buffer will be popped
2065 off the top of the buffer stack and loaded into the editing buf‐
2066 fer.
2067 push-line-or-edit
2069 At the top-level (PS1) prompt, equivalent to push-line. At a
2070 secondary (PS2) prompt, move the entire current multiline con‐
2071 struct into the editor buffer. The latter is equivalent to
2072 push-input followed by get-line.
2073 read-command
2075 Only useful from a user-defined widget. A keystroke is read
2076 just as in normal operation, but instead of the command being
2077 executed the name of the command that would be executed is
2078 stored in the shell parameter REPLY. This can be used as the
2079 argument of a future zle command. If the key sequence is not
2080 bound, status 1 is returned; typically, however, REPLY is set to
2081 undefined-key to indicate a useless key sequence.
2082 recursive-edit
2084 Only useful from a user-defined widget. At this point in the
2085 function, the editor regains control until one of the standard
2086 widgets which would normally cause zle to exit (typically an ac‐
2087 cept-line caused by hitting the return key) is executed. In‐
2088 stead, control returns to the user-defined widget. The status
2089 returned is non-zero if the return was caused by an error, but
2090 the function still continues executing and hence may tidy up.
2091 This makes it safe for the user-defined widget to alter the com‐
2092 mand line or key bindings temporarily.
2093 The following widget, caps-lock, serves as an example.
2095 self-insert-ucase() {
2097 LBUFFER+=${(U)KEYS[-1]}
2098 }
2099 integer stat
2101 zle -N self-insert self-insert-ucase
2103 zle -A caps-lock save-caps-lock
2104 zle -A accept-line caps-lock
2105 zle recursive-edit
2107 stat=$?
2108 zle -A .self-insert self-insert
2110 zle -A save-caps-lock caps-lock
2111 zle -D save-caps-lock
2112 (( stat )) && zle send-break
2114 return $stat
2116 This causes typed letters to be inserted capitalised until ei‐
2118 ther accept-line (i.e. typically the return key) is typed or the
2119 caps-lock widget is invoked again; the later is handled by sav‐
2120 ing the old definition of caps-lock as save-caps-lock and then
2121 rebinding it to invoke accept-line. Note that an error from the
2122 recursive edit is detected as a non-zero return status and prop‐
2123 agated by using the send-break widget.
2124 redisplay (unbound) (^R) (^R)
2126 Redisplays the edit buffer.
2127 reset-prompt (unbound) (unbound) (unbound)
2129 Force the prompts on both the left and right of the screen to be
2130 re-expanded, then redisplay the edit buffer. This reflects
2131 changes both to the prompt variables themselves and changes in
2132 the expansion of the values (for example, changes in time or di‐
2133 rectory, or changes to the value of variables referred to by the
2134 prompt).
2135 Otherwise, the prompt is only expanded each time zle starts, and
2137 when the display has been interrupted by output from another
2138 part of the shell (such as a job notification) which causes the
2139 command line to be reprinted.
2140 reset-prompt doesn't alter the special parameter LASTWIDGET.
2142 send-break (^G ESC-^G) (unbound) (unbound)
2144 Abort the current editor function, e.g. execute-named-command,
2145 or the editor itself, e.g. if you are in vared. Otherwise abort
2146 the parsing of the current line; in this case the aborted line
2147 is available in the shell variable ZLE_LINE_ABORTED. If the ed‐
2148 itor is aborted from within vared, the variable
2149 ZLE_VARED_ABORTED is set.
2150 run-help (ESC-H ESC-h) (unbound) (unbound)
2152 Push the buffer onto the buffer stack, and execute the command
2153 `run-help cmd', where cmd is the current command. run-help is
2154 normally aliased to man.
2155 vi-set-buffer (unbound) (") (unbound)
2157 Specify a buffer to be used in the following command. There are
2158 37 buffers that can be specified: the 26 `named' buffers "a to
2159 "z, the `yank' buffer "0, the nine `queued' buffers "1 to "9 and
2160 the `black hole' buffer "_. The named buffers can also be spec‐
2161 ified as "A to "Z.
2162 When a buffer is specified for a cut, change or yank command,
2164 the text concerned replaces the previous contents of the speci‐
2165 fied buffer. If a named buffer is specified using a capital, the
2166 newly cut text is appended to the buffer instead of overwriting
2167 it. When using the "_ buffer, nothing happens. This can be use‐
2168 ful for deleting text without affecting any buffers.
2169 If no buffer is specified for a cut or change command, "1 is
2171 used, and the contents of "1 to "8 are each shifted along one
2172 buffer; the contents of "9 is lost. If no buffer is specified
2173 for a yank command, "0 is used. Finally, a paste command without
2174 a specified buffer will paste the text from the most recent com‐
2175 mand regardless of any buffer that might have been used with
2176 that command.
2177 When called from a widget function by the zle command, the buf‐
2179 fer can optionally be specified with an argument. For example,
2180 zle vi-set-buffer A
2182 vi-set-mark (unbound) (m) (unbound)
2184 Set the specified mark at the cursor position.
2185 set-mark-command (^@) (unbound) (unbound)
2187 Set the mark at the cursor position. If called with a negative
2188 numeric argument, do not set the mark but deactivate the region
2189 so that it is no longer highlighted (it is still usable for
2190 other purposes). Otherwise the region is marked as active.
2191 spell-word (ESC-$ ESC-S ESC-s) (unbound) (unbound)
2193 Attempt spelling correction on the current word.
2194 split-undo
2196 Breaks the undo sequence at the current change. This is useful
2197 in vi mode as changes made in insert mode are coalesced on en‐
2198 tering command mode. Similarly, undo will normally revert as
2199 one all the changes made by a user-defined widget.
2200 undefined-key
2202 This command is executed when a key sequence that is not bound
2203 to any command is typed. By default it beeps.
2204 undo (^_ ^Xu ^X^U) (u) (unbound)
2206 Incrementally undo the last text modification. When called from
2207 a user-defined widget, takes an optional argument indicating a
2208 previous state of the undo history as returned by the
2209 UNDO_CHANGE_NO variable; modifications are undone until that
2210 state is reached, subject to any limit imposed by the
2211 UNDO_LIMIT_NO variable.
2212 Note that when invoked from vi command mode, the full prior
2214 change made in insert mode is reverted, the changes having been
2215 merged when command mode was selected.
2216 redo (unbound) (^R) (unbound)
2218 Incrementally redo undone text modifications.
2219 vi-undo-change (unbound) (unbound) (unbound)
2221 Undo the last text modification. If repeated, redo the modifi‐
2222 cation.
2223 visual-mode (unbound) (v) (unbound)
2225 Toggle vim-style visual selection mode. If line-wise visual mode
2226 is currently enabled then it is changed to being character-wise.
2227 If used following an operator, it forces the subsequent movement
2228 command to be treated as a character-wise movement.
2229 visual-line-mode (unbound) (V) (unbound)
2231 Toggle vim-style line-wise visual selection mode. If charac‐
2232 ter-wise visual mode is currently enabled then it is changed to
2233 being line-wise. If used following an operator, it forces the
2234 subsequent movement command to be treated as a line-wise move‐
2235 ment.
2236 what-cursor-position (^X=) (ga) (unbound)
2238 Print the character under the cursor, its code as an octal, dec‐
2239 imal and hexadecimal number, the current cursor position within
2240 the buffer and the column of the cursor in the current line.
2241 where-is
2243 Read the name of an editor command and print the listing of key
2244 sequences that invoke the specified command. A restricted set
2245 of editing functions is available in the mini-buffer. Keys are
2246 looked up in the special command keymap, and if not found there
2247 in the main keymap.
2248 which-command (ESC-?) (unbound) (unbound)
2250 Push the buffer onto the buffer stack, and execute the command
2251 `which-command cmd'. where cmd is the current command.
2252 which-command is normally aliased to whence.
2253 vi-digit-or-beginning-of-line (unbound) (0) (unbound)
2255 If the last command executed was a digit as part of an argument,
2256 continue the argument. Otherwise, execute vi-beginning-of-line.
2257 Text Objects
2259 Text objects are commands that can be used to select a block of text
2260 according to some criteria. They are a feature of the vim text editor
2261 and so are primarily intended for use with vi operators or from visual
2262 selection mode. However, they can also be used from vi-insert or emacs
2263 mode. Key bindings listed below apply to the viopp and visual keymaps.
2264 select-a-blank-word (aW)
2266 Select a word including adjacent blanks, where a word is defined
2267 as a series of non-blank characters. With a numeric argument,
2268 multiple words will be selected.
2269 select-a-shell-word (aa)
2271 Select the current command argument applying the normal rules
2272 for quoting.
2273 select-a-word (aw)
2275 Select a word including adjacent blanks, using the normal
2276 vi-style word definition. With a numeric argument, multiple
2277 words will be selected.
2278 select-in-blank-word (iW)
2280 Select a word, where a word is defined as a series of non-blank
2281 characters. With a numeric argument, multiple words will be se‐
2282 lected.
2283 select-in-shell-word (ia)
2285 Select the current command argument applying the normal rules
2286 for quoting. If the argument begins and ends with matching quote
2287 characters, these are not included in the selection.
2288 select-in-word (iw)
2290 Select a word, using the normal vi-style word definition. With a
2291 numeric argument, multiple words will be selected.
2292
2294 The line editor has the ability to highlight characters or regions of
2295 the line that have a particular significance. This is controlled by
2296 the array parameter zle_highlight, if it has been set by the user.
2297 If the parameter contains the single entry none all highlighting is
2299 turned off. Note the parameter is still expected to be an array.
2300 Otherwise each entry of the array should consist of a word indicating a
2302 context for highlighting, then a colon, then a comma-separated list of
2303 the types of highlighting to apply in that context.
2304 The contexts available for highlighting are the following:
2306 default
2308 Any text within the command line not affected by any other high‐
2309 lighting. Text outside the editable area of the command line is
2310 not affected.
2311 isearch
2313 When one of the incremental history search widgets is active,
2314 the area of the command line matched by the search string or
2315 pattern.
2316 region The currently selected text. In emacs terminology, this is re‐
2318 ferred to as the region and is bounded by the cursor (point) and
2319 the mark. The region is only highlighted if it is active, which
2320 is the case after the mark is modified with set-mark-command or
2321 exchange-point-and-mark. Note that whether or not the region is
2322 active has no effect on its use within emacs style widgets, it
2323 simply determines whether it is highlighted. In vi mode, the re‐
2324 gion corresponds to selected text in visual mode.
2325 special
2327 Individual characters that have no direct printable representa‐
2328 tion but are shown in a special manner by the line editor.
2329 These characters are described below.
2330 suffix This context is used in completion for characters that are
2332 marked as suffixes that will be removed if the completion ends
2333 at that point, the most obvious example being a slash (/) after
2334 a directory name. Note that suffix removal is configurable; the
2335 circumstances under which the suffix will be removed may differ
2336 for different completions.
2337 paste Following a command to paste text, the characters that were in‐
2339 serted.
2340 When region_highlight is set, the contexts that describe a region --
2342 isearch, region, suffix, and paste -- are applied first, then re‐
2343 gion_highlight is applied, then the remaining zle_highlight contexts
2344 are applied. If a particular character is affected by multiple speci‐
2345 fications, the last specification wins.
2346 zle_highlight may contain additional fields for controlling how termi‐
2348 nal sequences to change colours are output. Each of the following is
2349 followed by a colon and a string in the same form as for key bindings.
2350 This will not be necessary for the vast majority of terminals as the
2351 defaults shown in parentheses are widely used.
2352 fg_start_code (\e[3)
2354 The start of the escape sequence for the foreground colour.
2355 This is followed by one to three ASCII digits representing the
2356 colour. Only used for palette colors, i.e. not 24-bit colors
2357 specified via a color triplet.
2358 fg_default_code (9)
2360 The number to use instead of the colour to reset the default
2361 foreground colour.
2362 fg_end_code (m)
2364 The end of the escape sequence for the foreground colour.
2365 bg_start_code (\e[4)
2367 The start of the escape sequence for the background colour. See
2368 fg_start_code above.
2369 bg_default_code (9)
2371 The number to use instead of the colour to reset the default
2372 background colour.
2373 bg_end_code (m)
2375 The end of the escape sequence for the background colour.
2376 The available types of highlighting are the following. Note that not
2378 all types of highlighting are available on all terminals:
2379 none No highlighting is applied to the given context. It is not use‐
2381 ful for this to appear with other types of highlighting; it is
2382 used to override a default.
2383 fg=colour
2385 The foreground colour should be set to colour, a decimal inte‐
2386 ger, the name of one of the eight most widely-supported colours
2387 or as a `#' followed by an RGB triplet in hexadecimal format.
2388 Not all terminals support this and, of those that do, not all
2390 provide facilities to test the support, hence the user should
2391 decide based on the terminal type. Most terminals support the
2392 colours black, red, green, yellow, blue, magenta, cyan and
2393 white, which can be set by name. In addition. default may be
2394 used to set the terminal's default foreground colour. Abbrevia‐
2395 tions are allowed; b or bl selects black. Some terminals may
2396 generate additional colours if the bold attribute is also
2397 present.
2398 On recent terminals and on systems with an up-to-date terminal
2400 database the number of colours supported may be tested by the
2401 command `echotc Co'; if this succeeds, it indicates a limit on
2402 the number of colours which will be enforced by the line editor.
2403 The number of colours is in any case limited to 256 (i.e. the
2404 range 0 to 255).
2405 Some modern terminal emulators have support for 24-bit true
2407 colour (16 million colours). In this case, the hex triplet for‐
2408 mat can be used. This consists of a `#' followed by either a
2409 three or six digit hexadecimal number describing the red, green
2410 and blue components of the colour. Hex triplets can also be used
2411 with 88 and 256 colour terminals via the zsh/nearcolor module
2412 (see zshmodules(1)).
2413 Colour is also known as color.
2415 bg=colour
2417 The background colour should be set to colour. This works simi‐
2418 larly to the foreground colour, except the background is not
2419 usually affected by the bold attribute.
2420 bold The characters in the given context are shown in a bold font.
2422 Not all terminals distinguish bold fonts.
2423 standout
2425 The characters in the given context are shown in the terminal's
2426 standout mode. The actual effect is specific to the terminal;
2427 on many terminals it is inverse video. On some such terminals,
2428 where the cursor does not blink it appears with standout mode
2429 negated, making it less than clear where the cursor actually is.
2430 On such terminals one of the other effects may be preferable for
2431 highlighting the region and matched search string.
2432 underline
2434 The characters in the given context are shown underlined. Some
2435 terminals show the foreground in a different colour instead; in
2436 this case whitespace will not be highlighted.
2437 The characters described above as `special' are as follows. The for‐
2439 matting described here is used irrespective of whether the characters
2440 are highlighted:
2441 ASCII control characters
2443 Control characters in the ASCII range are shown as `^' followed
2444 by the base character.
2445 Unprintable multibyte characters
2447 This item applies to control characters not in the ASCII range,
2448 plus other characters as follows. If the MULTIBYTE option is in
2449 effect, multibyte characters not in the ASCII character set that
2450 are reported as having zero width are treated as combining char‐
2451 acters when the option COMBINING_CHARS is on. If the option is
2452 off, or if a character appears where a combining character is
2453 not valid, the character is treated as unprintable.
2454 Unprintable multibyte characters are shown as a hexadecimal num‐
2456 ber between angle brackets. The number is the code point of the
2457 character in the wide character set; this may or may not be Uni‐
2458 code, depending on the operating system.
2459 Invalid multibyte characters
2461 If the MULTIBYTE option is in effect, any sequence of one or
2462 more bytes that does not form a valid character in the current
2463 character set is treated as a series of bytes each shown as a
2464 special character. This case can be distinguished from other
2465 unprintable characters as the bytes are represented as two hexa‐
2466 decimal digits between angle brackets, as distinct from the four
2467 or eight digits that are used for unprintable characters that
2468 are nonetheless valid in the current character set.
2469 Not all systems support this: for it to work, the system's rep‐
2471 resentation of wide characters must be code values from the Uni‐
2472 versal Character Set, as defined by IS0 10646 (also known as
2473 Unicode).
2474 Wrapped double-width characters
2476 When a double-width character appears in the final column of a
2477 line, it is instead shown on the next line. The empty space left
2478 in the original position is highlighted as a special character.
2479 If zle_highlight is not set or no value applies to a particular con‐
2481 text, the defaults applied are equivalent to
2482 zle_highlight=(region:standout special:standout
2484 suffix:bold isearch:underline paste:standout)
2485 i.e. both the region and special characters are shown in standout mode.
2487 Within widgets, arbitrary regions may be highlighted by setting the
2489 special array parameter region_highlight; see above.
2490zsh 5.9 May 14, 2022 ZSHZLE(1)