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 ] [ -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; this is to be called from
453 within a user-defined widget to allow changes to become
454 visible. If a display-string is given and not empty,
455 this is shown in the status line (immediately below the
456 line being edited).
457 If the optional strings are given they are listed below
459 the prompt in the same way as completion lists are
460 printed. If no strings are given but the -c option is
461 used such a list is cleared.
462 Note that this option is only useful for widgets that do
464 not exit immediately after using it because the strings
465 displayed will be erased immediately after return from
466 the widget.
467 This command can safely be called outside user defined
469 widgets; if zle is active, the display will be refreshed,
470 while if zle is not active, the command has no effect.
471 In this case there will usually be no other arguments.
472 The status is zero if zle was active, else one.
474 -M string
476 As with the -R option, the string will be displayed below
477 the command line; unlike the -R option, the string will
478 not be put into the status line but will instead be
479 printed normally below the prompt. This means that the
480 string will still be displayed after the widget returns
481 (until it is overwritten by subsequent commands).
482 -U string
484 This pushes the characters in the string onto the input
485 stack of ZLE. After the widget currently executed fin‐
486 ishes ZLE will behave as if the characters in the string
487 were typed by the user.
488 As ZLE uses a stack, if this option is used repeatedly
490 the last string pushed onto the stack will be processed
491 first. However, the characters in each string will be
492 processed in the order in which they appear in the
493 string.
494 -K keymap
496 Selects the keymap named keymap. An error message will
497 be displayed if there is no such keymap.
498 This keymap selection affects the interpretation of fol‐
500 lowing keystrokes within this invocation of ZLE. Any
501 following invocation (e.g., the next command line) will
502 start as usual with the `main' keymap selected.
503 -F [ -L | -w ] [ fd [ handler ] ]
505 Only available if your system supports one of the `poll'
506 or `select' system calls; most modern systems do.
507 Installs handler (the name of a shell function) to handle
509 input from file descriptor fd. Installing a handler for
510 an fd which is already handled causes the existing han‐
511 dler to be replaced. Any number of handlers for any num‐
512 ber of readable file descriptors may be installed. Note
513 that zle makes no attempt to check whether this fd is ac‐
514 tually readable when installing the handler. The user
515 must make their own arrangements for handling the file
516 descriptor when zle is not active.
517 When zle is attempting to read data, it will examine both
519 the terminal and the list of handled fd's. If data be‐
520 comes available on a handled fd, zle calls handler with
521 the fd which is ready for reading as the first argument.
522 Under normal circumstances this is the only argument, but
523 if an error was detected, a second argument provides de‐
524 tails: `hup' for a disconnect, `nval' for a closed or
525 otherwise invalid descriptor, or `err' for any other con‐
526 dition. Systems that support only the `select' system
527 call always use `err'.
528 If the option -w is also given, the handler is instead a
530 line editor widget, typically a shell function made into
531 a widget using `zle -N'. In that case handler can use
532 all the facilities of zle to update the current editing
533 line. Note, however, that as handling fd takes place at
534 a low level changes to the display will not automatically
535 appear; the widget should call `zle -R' to force redis‐
536 play. As of this writing, widget handlers only support a
537 single argument and thus are never passed a string for
538 error state, so widgets must be prepared to test the de‐
539 scriptor themselves.
540 If either type of handler produces output to the termi‐
542 nal, it should call `zle -I' before doing so (see below).
543 Handlers should not attempt to read from the terminal.
544 If no handler is given, but an fd is present, any handler
546 for that fd is removed. If there is none, an error mes‐
547 sage is printed and status 1 is returned.
548 If no arguments are given, or the -L option is supplied,
550 a list of handlers is printed in a form which can be
551 stored for later execution.
552 An fd (but not a handler) may optionally be given with
554 the -L option; in this case, the function will list the
555 handler if any, else silently return status 1.
556 Note that this feature should be used with care. Activ‐
558 ity on one of the fd's which is not properly handled can
559 cause the terminal to become unusable. Removing an fd
560 handler from within a signal trap may cause unpredictable
561 behavior.
562 Here is a simple example of using this feature. A con‐
564 nection to a remote TCP port is created using the ztcp
565 command; see the description of the zsh/net/tcp module in
566 zshmodules(1). Then a handler is installed which simply
567 prints out any data which arrives on this connection.
568 Note that `select' will indicate that the file descriptor
569 needs handling if the remote side has closed the connec‐
570 tion; we handle that by testing for a failed read.
571 if ztcp pwspc 2811; then
573 tcpfd=$REPLY
574 handler() {
575 zle -I
576 local line
577 if ! read -r line <&$1; then
578 # select marks this fd if we reach EOF,
579 # so handle this specially.
580 print "[Read on fd $1 failed, removing.]" >&2
581 zle -F $1
582 return 1
583 fi
584 print -r - $line
585 }
586 zle -F $tcpfd handler
587 fi
588 -I Unusually, this option is most useful outside ordinary
590 widget functions, though it may be used within if normal
591 output to the terminal is required. It invalidates the
592 current zle display in preparation for output; typically
593 this will be from a trap function. It has no effect if
594 zle is not active. When a trap exits, the shell checks
595 to see if the display needs restoring, hence the follow‐
596 ing will print output in such a way as not to disturb the
597 line being edited:
598 TRAPUSR1() {
600 # Invalidate zle display
601 [[ -o zle ]] && zle -I
602 # Show output
603 print Hello
604 }
605 In general, the trap function may need to test whether
607 zle is active before using this method (as shown in the
608 example), since the zsh/zle module may not even be
609 loaded; if it is not, the command can be skipped.
610 It is possible to call `zle -I' several times before con‐
612 trol is returned to the editor; the display will only be
613 invalidated the first time to minimise disruption.
614 Note that there are normally better ways of manipulating
616 the display from within zle widgets; see, for example,
617 `zle -R' above.
618 The returned status is zero if zle was invalidated, even
620 though this may have been by a previous call to `zle -I'
621 or by a system notification. To test if a zle widget may
622 be called at this point, execute zle with no arguments
623 and examine the return status.
624 -T This is used to add, list or remove internal transforma‐
626 tions on the processing performed by the line editor. It
627 is typically used only for debugging or testing and is
628 therefore of little interest to the general user.
629 `zle -T transformation func' specifies that the given
631 transformation (see below) is effected by shell function
632 func.
633 `zle -Tr transformation' removes the given transformation
635 if it was present (it is not an error if none was).
636 `zle -TL' can be used to list all transformations cur‐
638 rently in operation.
639 Currently the only transformation is tc. This is used
641 instead of outputting termcap codes to the terminal.
642 When the transformation is in operation the shell func‐
643 tion is passed the termcap code that would be output as
644 its first argument; if the operation required a numeric
645 argument, that is passed as a second argument. The func‐
646 tion should set the shell variable REPLY to the trans‐
647 formed termcap code. Typically this is used to produce
648 some simply formatted version of the code and optional
649 argument for debugging or testing. Note that this trans‐
650 formation is not applied to other non-printing characters
651 such as carriage returns and newlines.
652 widget [ -n num ] [ -Nw ] [ -K keymap ] args ...
654 Invoke the specified widget. This can only be done when
655 ZLE is active; normally this will be within a user-de‐
656 fined widget.
657 With the options -n and -N, the current numeric argument
659 will be saved and then restored after the call to widget;
660 `-n num' sets the numeric argument temporarily to num,
661 while `-N' sets it to the default, i.e. as if there were
662 none.
663 With the option -K, keymap will be used as the current
665 keymap during the execution of the widget. The previous
666 keymap will be restored when the widget exits.
667 Normally, calling a widget in this way does not set the
669 special parameter WIDGET and related parameters, so that
670 the environment appears as if the top-level widget called
671 by the user were still active. With the option -w, WID‐
672 GET and related parameters are set to reflect the widget
673 being executed by the zle call.
674 Any further arguments will be passed to the widget; note
676 that as standard argument handling is performed, any gen‐
677 eral argument list should be preceded by --. If it is a
678 shell function, these are passed down as positional pa‐
679 rameters; for builtin widgets it is up to the widget in
680 question what it does with them. Currently arguments are
681 only handled by the incremental-search commands, the his‐
682 tory-search-forward and -backward and the corresponding
683 functions prefixed by vi-, and by universal-argument. No
684 error is flagged if the command does not use the argu‐
685 ments, or only uses some of them.
686 The return status reflects the success or failure of the
688 operation carried out by the widget, or if it is a
689 user-defined widget the return status of the shell func‐
690 tion.
691 A non-zero return status causes the shell to beep when
693 the widget exits, unless the BEEP options was unset or
694 the widget was called via the zle command. Thus if a
695 user defined widget requires an immediate beep, it should
696 call the beep widget directly.
697
699 All actions in the editor are performed by `widgets'. A widget's job
700 is simply to perform some small action. The ZLE commands that key se‐
701 quences in keymaps are bound to are in fact widgets. Widgets can be
702 user-defined or built in.
703 The standard widgets built into ZLE are listed in Standard Widgets be‐
705 low. Other built-in widgets can be defined by other modules (see zsh‐
706 modules(1)). Each built-in widget has two names: its normal canonical
707 name, and the same name preceded by a `.'. The `.' name is special: it
708 can't be rebound to a different widget. This makes the widget avail‐
709 able even when its usual name has been redefined.
710 User-defined widgets are defined using `zle -N', and implemented as
712 shell functions. When the widget is executed, the corresponding shell
713 function is executed, and can perform editing (or other) actions. It
714 is recommended that user-defined widgets should not have names starting
715 with `.'.
716
718 User-defined widgets, being implemented as shell functions, can execute
719 any normal shell command. They can also run other widgets (whether
720 built-in or user-defined) using the zle builtin command. The standard
721 input of the function is redirected from /dev/null to prevent external
722 commands from unintentionally blocking ZLE by reading from the termi‐
723 nal, but read -k or read -q can be used to read characters. Finally,
724 they can examine and edit the ZLE buffer being edited by reading and
725 setting the special parameters described below.
726 These special parameters are always available in widget functions, but
728 are not in any way special outside ZLE. If they have some normal value
729 outside ZLE, that value is temporarily inaccessible, but will return
730 when the widget function exits. These special parameters in fact have
731 local scope, like parameters created in a function using local.
732 Inside completion widgets and traps called while ZLE is active, these
734 parameters are available read-only.
735 Note that the parameters appear as local to any ZLE widget in which
737 they appear. Hence if it is desired to override them this needs to be
738 done within a nested function:
739 widget-function() {
741 # $WIDGET here refers to the special variable
742 # that is local inside widget-function
743 () {
744 # This anonymous nested function allows WIDGET
745 # to be used as a local variable. The -h
746 # removes the special status of the variable.
747 local -h WIDGET
748 }
749 }
750 BUFFER (scalar)
752 The entire contents of the edit buffer. If it is written to,
753 the cursor remains at the same offset, unless that would put it
754 outside the buffer.
755 BUFFERLINES (integer)
757 The number of screen lines needed for the edit buffer currently
758 displayed on screen (i.e. without any changes to the preceding
759 parameters done after the last redisplay); read-only.
760 CONTEXT (scalar)
762 The context in which zle was called to read a line; read-only.
763 One of the values:
764 start The start of a command line (at prompt PS1).
766 cont A continuation to a command line (at prompt PS2).
768 select In a select loop (at prompt PS3).
770 vared Editing a variable in vared.
772 CURSOR (integer)
774 The offset of the cursor, within the edit buffer. This is in
775 the range 0 to $#BUFFER, and is by definition equal to
776 $#LBUFFER. Attempts to move the cursor outside the buffer will
777 result in the cursor being moved to the appropriate end of the
778 buffer.
779 CUTBUFFER (scalar)
781 The last item cut using one of the `kill-' commands; the string
782 which the next yank would insert in the line. Later entries in
783 the kill ring are in the array killring. Note that the command
784 `zle copy-region-as-kill string' can be used to set the text of
785 the cut buffer from a shell function and cycle the kill ring in
786 the same way as interactively killing text.
787 HISTNO (integer)
789 The current history number. Setting this has the same effect as
790 moving up or down in the history to the corresponding history
791 line. An attempt to set it is ignored if the line is not stored
792 in the history. Note this is not the same as the parameter
793 HISTCMD, which always gives the number of the history line being
794 added to the main shell's history. HISTNO refers to the line
795 being retrieved within zle.
796 ISEARCHMATCH_ACTIVE (integer)
798 ISEARCHMATCH_START (integer)
799 ISEARCHMATCH_END (integer)
800 ISEARCHMATCH_ACTIVE indicates whether a part of the BUFFER is
801 currently matched by an incremental search pattern. ISEARCH‐
802 MATCH_START and ISEARCHMATCH_END give the location of the
803 matched part and are in the same units as CURSOR. They are only
804 valid for reading when ISEARCHMATCH_ACTIVE is non-zero.
805 All parameters are read-only.
807 KEYMAP (scalar)
809 The name of the currently selected keymap; read-only.
810 KEYS (scalar)
812 The keys typed to invoke this widget, as a literal string;
813 read-only.
814 KEYS_QUEUED_COUNT (integer)
816 The number of bytes pushed back to the input queue and therefore
817 available for reading immediately before any I/O is done;
818 read-only. See also PENDING; the two values are distinct.
819 killring (array)
821 The array of previously killed items, with the most recently
822 killed first. This gives the items that would be retrieved by a
823 yank-pop in the same order. Note, however, that the most re‐
824 cently killed item is in $CUTBUFFER; $killring shows the array
825 of previous entries.
826 The default size for the kill ring is eight, however the length
828 may be changed by normal array operations. Any empty string in
829 the kill ring is ignored by the yank-pop command, hence the size
830 of the array effectively sets the maximum length of the kill
831 ring, while the number of non-zero strings gives the current
832 length, both as seen by the user at the command line.
833 LASTABORTEDSEARCH (scalar)
835 The last search string used by an interactive search that was
836 aborted by the user (status 3 returned by the search widget).
837 LASTSEARCH (scalar)
839 The last search string used by an interactive search; read-only.
840 This is set even if the search failed (status 0, 1 or 2 returned
841 by the search widget), but not if it was aborted by the user.
842 LASTWIDGET (scalar)
844 The name of the last widget that was executed; read-only.
845 LBUFFER (scalar)
847 The part of the buffer that lies to the left of the cursor posi‐
848 tion. If it is assigned to, only that part of the buffer is re‐
849 placed, and the cursor remains between the new $LBUFFER and the
850 old $RBUFFER.
851 MARK (integer)
853 Like CURSOR, but for the mark. With vi-mode operators that wait
854 for a movement command to select a region of text, setting MARK
855 allows the selection to extend in both directions from the ini‐
856 tial cursor position.
857 NUMERIC (integer)
859 The numeric argument. If no numeric argument was given, this pa‐
860 rameter is unset. When this is set inside a widget function,
861 builtin widgets called with the zle builtin command will use the
862 value assigned. If it is unset inside a widget function, builtin
863 widgets called behave as if no numeric argument was given.
864 PENDING (integer)
866 The number of bytes pending for input, i.e. the number of bytes
867 which have already been typed and can immediately be read. On
868 systems where the shell is not able to get this information,
869 this parameter will always have a value of zero. Read-only.
870 See also KEYS_QUEUED_COUNT; the two values are distinct.
871 PREBUFFER (scalar)
873 In a multi-line input at the secondary prompt, this read-only
874 parameter contains the contents of the lines before the one the
875 cursor is currently in.
876 PREDISPLAY (scalar)
878 Text to be displayed before the start of the editable text buf‐
879 fer. This does not have to be a complete line; to display a
880 complete line, a newline must be appended explicitly. The text
881 is reset on each new invocation (but not recursive invocation)
882 of zle.
883 POSTDISPLAY (scalar)
885 Text to be displayed after the end of the editable text buffer.
886 This does not have to be a complete line; to display a complete
887 line, a newline must be prepended explicitly. The text is reset
888 on each new invocation (but not recursive invocation) of zle.
889 RBUFFER (scalar)
891 The part of the buffer that lies to the right of the cursor po‐
892 sition. If it is assigned to, only that part of the buffer is
893 replaced, and the cursor remains between the old $LBUFFER and
894 the new $RBUFFER.
895 REGION_ACTIVE (integer)
897 Indicates if the region is currently active. It can be assigned
898 0 or 1 to deactivate and activate the region respectively. A
899 value of 2 activates the region in line-wise mode with the high‐
900 lighted text extending for whole lines only; see Character High‐
901 lighting below.
902 region_highlight (array)
904 Each element of this array may be set to a string that describes
905 highlighting for an arbitrary region of the command line that
906 will take effect the next time the command line is redisplayed.
907 Highlighting of the non-editable parts of the command line in
908 PREDISPLAY and POSTDISPLAY are possible, but note that the P
909 flag is needed for character indexing to include PREDISPLAY.
910 Each string consists of the following parts:
912 • Optionally, a `P' to signify that the start and end off‐
914 set that follow include any string set by the PREDISPLAY
915 special parameter; this is needed if the predisplay
916 string itself is to be highlighted. Whitespace may fol‐
917 low the `P'.
918 • A start offset in the same units as CURSOR, terminated by
920 whitespace.
921 • An end offset in the same units as CURSOR, terminated by
923 whitespace.
924 • A highlight specification in the same format as used for
926 contexts in the parameter zle_highlight, see the section
927 `Character Highlighting' below; for example, standout or
928 fg=red,bold
929 For example,
931 region_highlight=("P0 20 bold")
933 specifies that the first twenty characters of the text including
935 any predisplay string should be highlighted in bold.
936 Note that the effect of region_highlight is not saved and disap‐
938 pears as soon as the line is accepted.
939 The final highlighting on the command line depends on both re‐
941 gion_highlight and zle_highlight; see the section CHARACTER
942 HIGHLIGHTING below for details.
943 registers (associative array)
945 The contents of each of the vi register buffers. These are typi‐
946 cally set using vi-set-buffer followed by a delete, change or
947 yank command.
948 SUFFIX_ACTIVE (integer)
950 SUFFIX_START (integer)
951 SUFFIX_END (integer)
952 SUFFIX_ACTIVE indicates whether an auto-removable completion
953 suffix is currently active. SUFFIX_START and SUFFIX_END give the
954 location of the suffix and are in the same units as CURSOR. They
955 are only valid for reading when SUFFIX_ACTIVE is non-zero.
956 All parameters are read-only.
958 UNDO_CHANGE_NO (integer)
960 A number representing the state of the undo history. The only
961 use of this is passing as an argument to the undo widget in or‐
962 der to undo back to the recorded point. Read-only.
963 UNDO_LIMIT_NO (integer)
965 A number corresponding to an existing change in the undo his‐
966 tory; compare UNDO_CHANGE_NO. If this is set to a value greater
967 than zero, the undo command will not allow the line to be undone
968 beyond the given change number. It is still possible to use
969 `zle undo change' in a widget to undo beyond that point; in that
970 case, it will not be possible to undo at all until UNDO_LIMIT_NO
971 is reduced. Set to 0 to disable the limit.
972 A typical use of this variable in a widget function is as fol‐
974 lows (note the additional function scope is required):
975 () {
977 local UNDO_LIMIT_NO=$UNDO_CHANGE_NO
978 # Perform some form of recursive edit.
979 }
980 WIDGET (scalar)
982 The name of the widget currently being executed; read-only.
983 WIDGETFUNC (scalar)
985 The name of the shell function that implements a widget defined
986 with either zle -N or zle -C. In the former case, this is the
987 second argument to the zle -N command that defined the widget,
988 or the first argument if there was no second argument. In the
989 latter case this is the third argument to the zle -C command
990 that defined the widget. Read-only.
991 WIDGETSTYLE (scalar)
993 Describes the implementation behind the completion widget cur‐
994 rently being executed; the second argument that followed zle -C
995 when the widget was defined. This is the name of a builtin com‐
996 pletion widget. For widgets defined with zle -N this is set to
997 the empty string. Read-only.
998 YANK_ACTIVE (integer)
1000 YANK_START (integer)
1001 YANK_END (integer)
1002 YANK_ACTIVE indicates whether text has just been yanked (pasted)
1003 into the buffer. YANK_START and YANK_END give the location of
1004 the pasted text and are in the same units as CURSOR. They are
1005 only valid for reading when YANK_ACTIVE is non-zero. They can
1006 also be assigned by widgets that insert text in a yank-like
1007 fashion, for example wrappers of bracketed-paste. See also zle
1008 -f.
1009 YANK_ACTIVE is read-only.
1011 ZLE_RECURSIVE (integer)
1013 Usually zero, but incremented inside any instance of recur‐
1014 sive-edit. Hence indicates the current recursion level.
1015 ZLE_RECURSIVE is read-only.
1017 ZLE_STATE (scalar)
1019 Contains a set of space-separated words that describe the cur‐
1020 rent zle state.
1021 Currently, the states shown are the insert mode as set by the
1023 overwrite-mode or vi-replace widgets and whether history com‐
1024 mands will visit imported entries as controlled by the set-lo‐
1025 cal-history widget. The string contains `insert' if characters
1026 to be inserted on the command line move existing characters to
1027 the right or `overwrite' if characters to be inserted overwrite
1028 existing characters. It contains `localhistory' if only local
1029 history commands will be visited or `globalhistory' if imported
1030 history commands will also be visited.
1031 The substrings are sorted in alphabetical order so that if you
1033 want to test for two specific substrings in a future-proof way,
1034 you can do match by doing:
1035 if [[ $ZLE_STATE == *globalhistory*insert* ]]; then ...; fi
1037 Special Widgets
1039 There are a few user-defined widgets which are special to the shell.
1040 If they do not exist, no special action is taken. The environment pro‐
1041 vided is identical to that for any other editing widget.
1042 zle-isearch-exit
1044 Executed at the end of incremental search at the point where the
1045 isearch prompt is removed from the display. See zle-isearch-up‐
1046 date for an example.
1047 zle-isearch-update
1049 Executed within incremental search when the display is about to
1050 be redrawn. Additional output below the incremental search
1051 prompt can be generated by using `zle -M' within the widget.
1052 For example,
1053 zle-isearch-update() { zle -M "Line $HISTNO"; }
1055 zle -N zle-isearch-update
1056 Note the line output by `zle -M' is not deleted on exit from in‐
1058 cremental search. This can be done from a zle-isearch-exit wid‐
1059 get:
1060 zle-isearch-exit() { zle -M ""; }
1062 zle -N zle-isearch-exit
1063 zle-line-pre-redraw
1065 Executed whenever the input line is about to be redrawn, provid‐
1066 ing an opportunity to update the region_highlight array.
1067 zle-line-init
1069 Executed every time the line editor is started to read a new
1070 line of input. The following example puts the line editor into
1071 vi command mode when it starts up.
1072 zle-line-init() { zle -K vicmd; }
1074 zle -N zle-line-init
1075 (The command inside the function sets the keymap directly; it is
1077 equivalent to zle vi-cmd-mode.)
1078 zle-line-finish
1080 This is similar to zle-line-init but is executed every time the
1081 line editor has finished reading a line of input.
1082 zle-history-line-set
1084 Executed when the history line changes.
1085 zle-keymap-select
1087 Executed every time the keymap changes, i.e. the special parame‐
1088 ter KEYMAP is set to a different value, while the line editor is
1089 active. Initialising the keymap when the line editor starts
1090 does not cause the widget to be called.
1091 The value $KEYMAP within the function reflects the new keymap.
1093 The old keymap is passed as the sole argument.
1094 This can be used for detecting switches between the vi command
1096 (vicmd) and insert (usually main) keymaps.
1097
1099 The following is a list of all the standard widgets, and their default
1100 bindings in emacs mode, vi command mode and vi insert mode (the
1101 `emacs', `vicmd' and `viins' keymaps, respectively).
1102 Note that cursor keys are bound to movement keys in all three keymaps;
1104 the shell assumes that the cursor keys send the key sequences reported
1105 by the terminal-handling library (termcap or terminfo). The key se‐
1106 quences shown in the list are those based on the VT100, common on many
1107 modern terminals, but in fact these are not necessarily bound. In the
1108 case of the viins keymap, the initial escape character of the sequences
1109 serves also to return to the vicmd keymap: whether this happens is de‐
1110 termined by the KEYTIMEOUT parameter, see zshparam(1).
1111 Movement
1113 vi-backward-blank-word (unbound) (B) (unbound)
1114 Move backward one word, where a word is defined as a series of
1115 non-blank characters.
1116 vi-backward-blank-word-end (unbound) (gE) (unbound)
1118 Move to the end of the previous word, where a word is defined as
1119 a series of non-blank characters.
1120 backward-char (^B ESC-[D) (unbound) (unbound)
1122 Move backward one character.
1123 vi-backward-char (unbound) (^H h ^?) (ESC-[D)
1125 Move backward one character, without changing lines.
1126 backward-word (ESC-B ESC-b) (unbound) (unbound)
1128 Move to the beginning of the previous word.
1129 emacs-backward-word
1131 Move to the beginning of the previous word.
1132 vi-backward-word (unbound) (b) (unbound)
1134 Move to the beginning of the previous word, vi-style.
1135 vi-backward-word-end (unbound) (ge) (unbound)
1137 Move to the end of the previous word, vi-style.
1138 beginning-of-line (^A) (unbound) (unbound)
1140 Move to the beginning of the line. If already at the beginning
1141 of the line, move to the beginning of the previous line, if any.
1142 vi-beginning-of-line
1144 Move to the beginning of the line, without changing lines.
1145 down-line (unbound) (unbound) (unbound)
1147 Move down a line in the buffer.
1148 end-of-line (^E) (unbound) (unbound)
1150 Move to the end of the line. If already at the end of the line,
1151 move to the end of the next line, if any.
1152 vi-end-of-line (unbound) ($) (unbound)
1154 Move to the end of the line. If an argument is given to this
1155 command, the cursor will be moved to the end of the line (argu‐
1156 ment - 1) lines down.
1157 vi-forward-blank-word (unbound) (W) (unbound)
1159 Move forward one word, where a word is defined as a series of
1160 non-blank characters.
1161 vi-forward-blank-word-end (unbound) (E) (unbound)
1163 Move to the end of the current word, or, if at the end of the
1164 current word, to the end of the next word, where a word is de‐
1165 fined as a series of non-blank characters.
1166 forward-char (^F ESC-[C) (unbound) (unbound)
1168 Move forward one character.
1169 vi-forward-char (unbound) (space l) (ESC-[C)
1171 Move forward one character.
1172 vi-find-next-char (^X^F) (f) (unbound)
1174 Read a character from the keyboard, and move to the next occur‐
1175 rence of it in the line.
1176 vi-find-next-char-skip (unbound) (t) (unbound)
1178 Read a character from the keyboard, and move to the position
1179 just before the next occurrence of it in the line.
1180 vi-find-prev-char (unbound) (F) (unbound)
1182 Read a character from the keyboard, and move to the previous oc‐
1183 currence of it in the line.
1184 vi-find-prev-char-skip (unbound) (T) (unbound)
1186 Read a character from the keyboard, and move to the position
1187 just after the previous occurrence of it in the line.
1188 vi-first-non-blank (unbound) (^) (unbound)
1190 Move to the first non-blank character in the line.
1191 vi-forward-word (unbound) (w) (unbound)
1193 Move forward one word, vi-style.
1194 forward-word (ESC-F ESC-f) (unbound) (unbound)
1196 Move to the beginning of the next word. The editor's idea of a
1197 word is specified with the WORDCHARS parameter.
1198 emacs-forward-word
1200 Move to the end of the next word.
1201 vi-forward-word-end (unbound) (e) (unbound)
1203 Move to the end of the next word.
1204 vi-goto-column (ESC-|) (|) (unbound)
1206 Move to the column specified by the numeric argument.
1207 vi-goto-mark (unbound) (`) (unbound)
1209 Move to the specified mark.
1210 vi-goto-mark-line (unbound) (') (unbound)
1212 Move to beginning of the line containing the specified mark.
1213 vi-repeat-find (unbound) (;) (unbound)
1215 Repeat the last vi-find command.
1216 vi-rev-repeat-find (unbound) (,) (unbound)
1218 Repeat the last vi-find command in the opposite direction.
1219 up-line (unbound) (unbound) (unbound)
1221 Move up a line in the buffer.
1222 History Control
1224 beginning-of-buffer-or-history (ESC-<) (gg) (unbound)
1225 Move to the beginning of the buffer, or if already there, move
1226 to the first event in the history list.
1227 beginning-of-line-hist
1229 Move to the beginning of the line. If already at the beginning
1230 of the buffer, move to the previous history line.
1231 beginning-of-history
1233 Move to the first event in the history list.
1234 down-line-or-history (^N ESC-[B) (j) (ESC-[B)
1236 Move down a line in the buffer, or if already at the bottom
1237 line, move to the next event in the history list.
1238 vi-down-line-or-history (unbound) (+) (unbound)
1240 Move down a line in the buffer, or if already at the bottom
1241 line, move to the next event in the history list. Then move to
1242 the first non-blank character on the line.
1243 down-line-or-search
1245 Move down a line in the buffer, or if already at the bottom
1246 line, search forward in the history for a line beginning with
1247 the first word in the buffer.
1248 If called from a function by the zle command with arguments, the
1250 first argument is taken as the string for which to search,
1251 rather than the first word in the buffer.
1252 down-history (unbound) (^N) (unbound)
1254 Move to the next event in the history list.
1255 history-beginning-search-backward
1257 Search backward in the history for a line beginning with the
1258 current line up to the cursor. This leaves the cursor in its
1259 original position.
1260 end-of-buffer-or-history (ESC->) (unbound) (unbound)
1262 Move to the end of the buffer, or if already there, move to the
1263 last event in the history list.
1264 end-of-line-hist
1266 Move to the end of the line. If already at the end of the buf‐
1267 fer, move to the next history line.
1268 end-of-history
1270 Move to the last event in the history list.
1271 vi-fetch-history (unbound) (G) (unbound)
1273 Fetch the history line specified by the numeric argument. This
1274 defaults to the current history line (i.e. the one that isn't
1275 history yet).
1276 history-incremental-search-backward (^R ^Xr) (unbound) (unbound)
1278 Search backward incrementally for a specified string. The
1279 search is case-insensitive if the search string does not have
1280 uppercase letters and no numeric argument was given. The string
1281 may begin with `^' to anchor the search to the beginning of the
1282 line. When called from a user-defined function returns the fol‐
1283 lowing statuses: 0, if the search succeeded; 1, if the search
1284 failed; 2, if the search term was a bad pattern; 3, if the
1285 search was aborted by the send-break command.
1286 A restricted set of editing functions is available in the
1288 mini-buffer. Keys are looked up in the special isearch keymap,
1289 and if not found there in the main keymap (note that by default
1290 the isearch keymap is empty). An interrupt signal, as defined
1291 by the stty setting, will stop the search and go back to the
1292 original line. An undefined key will have the same effect.
1293 Note that the following always perform the same task within in‐
1294 cremental searches and cannot be replaced by user defined wid‐
1295 gets, nor can the set of functions be extended. The supported
1296 functions are:
1297 accept-and-hold
1299 accept-and-infer-next-history
1300 accept-line
1301 accept-line-and-down-history
1302 Perform the usual function after exiting incremental
1303 search. The command line displayed is executed.
1304 backward-delete-char
1306 vi-backward-delete-char
1307 Back up one place in the search history. If the search
1308 has been repeated this does not immediately erase a char‐
1309 acter in the minibuffer.
1310 accept-search
1312 Exit incremental search, retaining the command line but
1313 performing no further action. Note that this function is
1314 not bound by default and has no effect outside incremen‐
1315 tal search.
1316 backward-delete-word
1318 backward-kill-word
1319 vi-backward-kill-word
1320 Back up one character in the minibuffer; if multiple
1321 searches have been performed since the character was in‐
1322 serted the search history is rewound to the point just
1323 before the character was entered. Hence this has the ef‐
1324 fect of repeating backward-delete-char.
1325 clear-screen
1327 Clear the screen, remaining in incremental search mode.
1328 history-incremental-search-backward
1330 Find the next occurrence of the contents of the mini-buf‐
1331 fer. If the mini-buffer is empty, the most recent previ‐
1332 ously used search string is reinstated.
1333 history-incremental-search-forward
1335 Invert the sense of the search.
1336 magic-space
1338 Inserts a non-magical space.
1339 quoted-insert
1341 vi-quoted-insert
1342 Quote the character to insert into the minibuffer.
1343 redisplay
1345 Redisplay the command line, remaining in incremental
1346 search mode.
1347 vi-cmd-mode
1349 Select the `vicmd' keymap; the `main' keymap (insert
1350 mode) will be selected initially.
1351 In addition, the modifications that were made while in vi
1353 insert mode are merged to form a single undo event.
1354 vi-repeat-search
1356 vi-rev-repeat-search
1357 Repeat the search. The direction of the search is indi‐
1358 cated in the mini-buffer.
1359 Any character that is not bound to one of the above functions,
1361 or self-insert or self-insert-unmeta, will cause the mode to be
1362 exited. The character is then looked up and executed in the
1363 keymap in effect at that point.
1364 When called from a widget function by the zle command, the in‐
1366 cremental search commands can take a string argument. This will
1367 be treated as a string of keys, as for arguments to the bindkey
1368 command, and used as initial input for the command. Any charac‐
1369 ters in the string which are unused by the incremental search
1370 will be silently ignored. For example,
1371 zle history-incremental-search-backward forceps
1373 will search backwards for forceps, leaving the minibuffer con‐
1375 taining the string `forceps'.
1376 history-incremental-search-forward (^S ^Xs) (unbound) (unbound)
1378 Search forward incrementally for a specified string. The search
1379 is case-insensitive if the search string does not have uppercase
1380 letters and no numeric argument was given. The string may begin
1381 with `^' to anchor the search to the beginning of the line. The
1382 functions available in the mini-buffer are the same as for his‐
1383 tory-incremental-search-backward.
1384 history-incremental-pattern-search-backward
1386 history-incremental-pattern-search-forward
1387 These widgets behave similarly to the corresponding widgets with
1388 no -pattern, but the search string typed by the user is treated
1389 as a pattern, respecting the current settings of the various op‐
1390 tions affecting pattern matching. See FILENAME GENERATION in
1391 zshexpn(1) for a description of patterns. If no numeric argu‐
1392 ment was given lowercase letters in the search string may match
1393 uppercase letters in the history. The string may begin with `^'
1394 to anchor the search to the beginning of the line.
1395 The prompt changes to indicate an invalid pattern; this may sim‐
1397 ply indicate the pattern is not yet complete.
1398 Note that only non-overlapping matches are reported, so an ex‐
1400 pression with wildcards may return fewer matches on a line than
1401 are visible by inspection.
1402 history-search-backward (ESC-P ESC-p) (unbound) (unbound)
1404 Search backward in the history for a line beginning with the
1405 first word in the buffer.
1406 If called from a function by the zle command with arguments, the
1408 first argument is taken as the string for which to search,
1409 rather than the first word in the buffer.
1410 vi-history-search-backward (unbound) (/) (unbound)
1412 Search backward in the history for a specified string. The
1413 string may begin with `^' to anchor the search to the beginning
1414 of the line.
1415 A restricted set of editing functions is available in the
1417 mini-buffer. An interrupt signal, as defined by the stty set‐
1418 ting, will stop the search. The functions available in the
1419 mini-buffer are: accept-line, backward-delete-char, vi-back‐
1420 ward-delete-char, backward-kill-word, vi-backward-kill-word,
1421 clear-screen, redisplay, quoted-insert and vi-quoted-insert.
1422 vi-cmd-mode is treated the same as accept-line, and magic-space
1424 is treated as a space. Any other character that is not bound to
1425 self-insert or self-insert-unmeta will beep and be ignored. If
1426 the function is called from vi command mode, the bindings of the
1427 current insert mode will be used.
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 history-search-forward (ESC-N ESC-n) (unbound) (unbound)
1434 Search forward in the history for a line beginning with the
1435 first word in the buffer.
1436 If called from a function by the zle command with arguments, the
1438 first argument is taken as the string for which to search,
1439 rather than the first word in the buffer.
1440 vi-history-search-forward (unbound) (?) (unbound)
1442 Search forward in the history for a specified string. The
1443 string may begin with `^' to anchor the search to the beginning
1444 of the line. The functions available in the mini-buffer are the
1445 same as for vi-history-search-backward. Argument handling is
1446 also the same as for that command.
1447 infer-next-history (^X^N) (unbound) (unbound)
1449 Search in the history list for a line matching the current one
1450 and fetch the event following it.
1451 insert-last-word (ESC-_ ESC-.) (unbound) (unbound)
1453 Insert the last word from the previous history event at the cur‐
1454 sor position. If a positive numeric argument is given, insert
1455 that word from the end of the previous history event. If the
1456 argument is zero or negative insert that word from the left
1457 (zero inserts the previous command word). Repeating this com‐
1458 mand replaces the word just inserted with the last word from the
1459 history event prior to the one just used; numeric arguments can
1460 be used in the same way to pick a word from that event.
1461 When called from a shell function invoked from a user-defined
1463 widget, the command can take one to three arguments. The first
1464 argument specifies a history offset which applies to successive
1465 calls to this widget: if it is -1, the default behaviour is
1466 used, while if it is 1, successive calls will move forwards
1467 through the history. The value 0 can be used to indicate that
1468 the history line examined by the previous execution of the com‐
1469 mand will be reexamined. Note that negative numbers should be
1470 preceded by a `--' argument to avoid confusing them with op‐
1471 tions.
1472 If two arguments are given, the second specifies the word on the
1474 command line in normal array index notation (as a more natural
1475 alternative to the numeric argument). Hence 1 is the first
1476 word, and -1 (the default) is the last word.
1477 If a third argument is given, its value is ignored, but it is
1479 used to signify that the history offset is relative to the cur‐
1480 rent history line, rather than the one remembered after the pre‐
1481 vious invocations of insert-last-word.
1482 For example, the default behaviour of the command corresponds to
1484 zle insert-last-word -- -1 -1
1486 while the command
1488 zle insert-last-word -- -1 1 -
1490 always copies the first word of the line in the history immedi‐
1492 ately before the line being edited. This has the side effect
1493 that later invocations of the widget will be relative to that
1494 line.
1495 vi-repeat-search (unbound) (n) (unbound)
1497 Repeat the last vi history search.
1498 vi-rev-repeat-search (unbound) (N) (unbound)
1500 Repeat the last vi history search, but in reverse.
1501 up-line-or-history (^P ESC-[A) (k) (ESC-[A)
1503 Move up a line in the buffer, or if already at the top line,
1504 move to the previous event in the history list.
1505 vi-up-line-or-history (unbound) (-) (unbound)
1507 Move up a line in the buffer, or if already at the top line,
1508 move to the previous event in the history list. Then move to
1509 the first non-blank character on the line.
1510 up-line-or-search
1512 Move up a line in the buffer, or if already at the top line,
1513 search backward in the history for a line beginning with the
1514 first word in the buffer.
1515 If called from a function by the zle command with arguments, the
1517 first argument is taken as the string for which to search,
1518 rather than the first word in the buffer.
1519 up-history (unbound) (^P) (unbound)
1521 Move to the previous event in the history list.
1522 history-beginning-search-forward
1524 Search forward in the history for a line beginning with the cur‐
1525 rent line up to the cursor. This leaves the cursor in its orig‐
1526 inal position.
1527 set-local-history
1529 By default, history movement commands visit the imported lines
1530 as well as the local lines. This widget lets you toggle this on
1531 and off, or set it with the numeric argument. Zero for both lo‐
1532 cal and imported lines and nonzero for only local lines.
1533 Modifying Text
1535 vi-add-eol (unbound) (A) (unbound)
1536 Move to the end of the line and enter insert mode.
1537 vi-add-next (unbound) (a) (unbound)
1539 Enter insert mode after the current cursor position, without
1540 changing lines.
1541 backward-delete-char (^H ^?) (unbound) (unbound)
1543 Delete the character behind the cursor.
1544 vi-backward-delete-char (unbound) (X) (^H)
1546 Delete the character behind the cursor, without changing lines.
1547 If in insert mode, this won't delete past the point where insert
1548 mode was last entered.
1549 backward-delete-word
1551 Delete the word behind the cursor.
1552 backward-kill-line
1554 Kill from the beginning of the line to the cursor position.
1555 backward-kill-word (^W ESC-^H ESC-^?) (unbound) (unbound)
1557 Kill the word behind the cursor.
1558 vi-backward-kill-word (unbound) (unbound) (^W)
1560 Kill the word behind the cursor, without going past the point
1561 where insert mode was last entered.
1562 capitalize-word (ESC-C ESC-c) (unbound) (unbound)
1564 Capitalize the current word and move past it.
1565 vi-change (unbound) (c) (unbound)
1567 Read a movement command from the keyboard, and kill from the
1568 cursor position to the endpoint of the movement. Then enter in‐
1569 sert mode. If the command is vi-change, change the current
1570 line.
1571 For compatibility with vi, if the command is vi-forward-word or
1573 vi-forward-blank-word, the whitespace after the word is not in‐
1574 cluded. If you prefer the more consistent behaviour with the
1575 whitespace included use the following key binding:
1576 bindkey -a -s cw dwi
1578 vi-change-eol (unbound) (C) (unbound)
1580 Kill to the end of the line and enter insert mode.
1581 vi-change-whole-line (unbound) (S) (unbound)
1583 Kill the current line and enter insert mode.
1584 copy-region-as-kill (ESC-W ESC-w) (unbound) (unbound)
1586 Copy the area from the cursor to the mark to the kill buffer.
1587 If called from a ZLE widget function in the form `zle copy-re‐
1589 gion-as-kill string' then string will be taken as the text to
1590 copy to the kill buffer. The cursor, the mark and the text on
1591 the command line are not used in this case.
1592 copy-prev-word (ESC-^_) (unbound) (unbound)
1594 Duplicate the word to the left of the cursor.
1595 copy-prev-shell-word
1597 Like copy-prev-word, but the word is found by using shell pars‐
1598 ing, whereas copy-prev-word looks for blanks. This makes a dif‐
1599 ference when the word is quoted and contains spaces.
1600 vi-delete (unbound) (d) (unbound)
1602 Read a movement command from the keyboard, and kill from the
1603 cursor position to the endpoint of the movement. If the command
1604 is vi-delete, kill the current line.
1605 delete-char
1607 Delete the character under the cursor.
1608 vi-delete-char (unbound) (x) (unbound)
1610 Delete the character under the cursor, without going past the
1611 end of the line.
1612 delete-word
1614 Delete the current word.
1615 down-case-word (ESC-L ESC-l) (unbound) (unbound)
1617 Convert the current word to all lowercase and move past it.
1618 vi-down-case (unbound) (gu) (unbound)
1620 Read a movement command from the keyboard, and convert all char‐
1621 acters from the cursor position to the endpoint of the movement
1622 to lowercase. If the movement command is vi-down-case, swap the
1623 case of all characters on the current line.
1624 kill-word (ESC-D ESC-d) (unbound) (unbound)
1626 Kill the current word.
1627 gosmacs-transpose-chars
1629 Exchange the two characters behind the cursor.
1630 vi-indent (unbound) (>) (unbound)
1632 Indent a number of lines.
1633 vi-insert (unbound) (i) (unbound)
1635 Enter insert mode.
1636 vi-insert-bol (unbound) (I) (unbound)
1638 Move to the first non-blank character on the line and enter in‐
1639 sert mode.
1640 vi-join (^X^J) (J) (unbound)
1642 Join the current line with the next one.
1643 kill-line (^K) (unbound) (unbound)
1645 Kill from the cursor to the end of the line. If already on the
1646 end of the line, kill the newline character.
1647 vi-kill-line (unbound) (unbound) (^U)
1649 Kill from the cursor back to wherever insert mode was last en‐
1650 tered.
1651 vi-kill-eol (unbound) (D) (unbound)
1653 Kill from the cursor to the end of the line.
1654 kill-region
1656 Kill from the cursor to the mark.
1657 kill-buffer (^X^K) (unbound) (unbound)
1659 Kill the entire buffer.
1660 kill-whole-line (^U) (unbound) (unbound)
1662 Kill the current line.
1663 vi-match-bracket (^X^B) (%) (unbound)
1665 Move to the bracket character (one of {}, () or []) that matches
1666 the one under the cursor. If the cursor is not on a bracket
1667 character, move forward without going past the end of the line
1668 to find one, and then go to the matching bracket.
1669 vi-open-line-above (unbound) (O) (unbound)
1671 Open a line above the cursor and enter insert mode.
1672 vi-open-line-below (unbound) (o) (unbound)
1674 Open a line below the cursor and enter insert mode.
1675 vi-oper-swap-case (unbound) (g~) (unbound)
1677 Read a movement command from the keyboard, and swap the case of
1678 all characters from the cursor position to the endpoint of the
1679 movement. If the movement command is vi-oper-swap-case, swap
1680 the case of all characters on the current line.
1681 overwrite-mode (^X^O) (unbound) (unbound)
1683 Toggle between overwrite mode and insert mode.
1684 vi-put-before (unbound) (P) (unbound)
1686 Insert the contents of the kill buffer before the cursor. If
1687 the kill buffer contains a sequence of lines (as opposed to
1688 characters), paste it above the current line.
1689 vi-put-after (unbound) (p) (unbound)
1691 Insert the contents of the kill buffer after the cursor. If the
1692 kill buffer contains a sequence of lines (as opposed to charac‐
1693 ters), paste it below the current line.
1694 put-replace-selection (unbound) (unbound) (unbound)
1696 Replace the contents of the current region or selection with the
1697 contents of the kill buffer. If the kill buffer contains a se‐
1698 quence of lines (as opposed to characters), the current line
1699 will be split by the pasted lines.
1700 quoted-insert (^V) (unbound) (unbound)
1702 Insert the next character typed into the buffer literally. An
1703 interrupt character will not be inserted.
1704 vi-quoted-insert (unbound) (unbound) (^Q ^V)
1706 Display a `^' at the cursor position, and insert the next char‐
1707 acter typed into the buffer literally. An interrupt character
1708 will not be inserted.
1709 quote-line (ESC-') (unbound) (unbound)
1711 Quote the current line; that is, put a `'' character at the be‐
1712 ginning and the end, and convert all `'' characters to `'\'''.
1713 quote-region (ESC-") (unbound) (unbound)
1715 Quote the region from the cursor to the mark.
1716 vi-replace (unbound) (R) (unbound)
1718 Enter overwrite mode.
1719 vi-repeat-change (unbound) (.) (unbound)
1721 Repeat the last vi mode text modification. If a count was used
1722 with the modification, it is remembered. If a count is given to
1723 this command, it overrides the remembered count, and is remem‐
1724 bered for future uses of this command. The cut buffer specifi‐
1725 cation is similarly remembered.
1726 vi-replace-chars (unbound) (r) (unbound)
1728 Replace the character under the cursor with a character read
1729 from the keyboard.
1730 self-insert (printable characters) (unbound) (printable characters and
1732 some control characters)
1733 Insert a character into the buffer at the cursor position.
1734 self-insert-unmeta (ESC-^I ESC-^J ESC-^M) (unbound) (unbound)
1736 Insert a character into the buffer after stripping the meta bit
1737 and converting ^M to ^J.
1738 vi-substitute (unbound) (s) (unbound)
1740 Substitute the next character(s).
1741 vi-swap-case (unbound) (~) (unbound)
1743 Swap the case of the character under the cursor and move past
1744 it.
1745 transpose-chars (^T) (unbound) (unbound)
1747 Exchange the two characters to the left of the cursor if at end
1748 of line, else exchange the character under the cursor with the
1749 character to the left.
1750 transpose-words (ESC-T ESC-t) (unbound) (unbound)
1752 Exchange the current word with the one before it.
1753 With a positive numeric argument N, the word around the cursor,
1755 or following it if the cursor is between words, is transposed
1756 with the preceding N words. The cursor is put at the end of the
1757 resulting group of words.
1758 With a negative numeric argument -N, the effect is the same as
1760 using a positive argument N except that the original cursor po‐
1761 sition is retained, regardless of how the words are rearranged.
1762 vi-unindent (unbound) (<) (unbound)
1764 Unindent a number of lines.
1765 vi-up-case (unbound) (gU) (unbound)
1767 Read a movement command from the keyboard, and convert all char‐
1768 acters from the cursor position to the endpoint of the movement
1769 to lowercase. If the movement command is vi-up-case, swap the
1770 case of all characters on the current line.
1771 up-case-word (ESC-U ESC-u) (unbound) (unbound)
1773 Convert the current word to all caps and move past it.
1774 yank (^Y) (unbound) (unbound)
1776 Insert the contents of the kill buffer at the cursor position.
1777 yank-pop (ESC-y) (unbound) (unbound)
1779 Remove the text just yanked, rotate the kill-ring (the history
1780 of previously killed text) and yank the new top. Only works
1781 following yank, vi-put-before, vi-put-after or yank-pop.
1782 vi-yank (unbound) (y) (unbound)
1784 Read a movement command from the keyboard, and copy the region
1785 from the cursor position to the endpoint of the movement into
1786 the kill buffer. If the command is vi-yank, copy the current
1787 line.
1788 vi-yank-whole-line (unbound) (Y) (unbound)
1790 Copy the current line into the kill buffer.
1791 vi-yank-eol
1793 Copy the region from the cursor position to the end of the line
1794 into the kill buffer. Arguably, this is what Y should do in vi,
1795 but it isn't what it actually does.
1796 Arguments
1798 digit-argument (ESC-0..ESC-9) (1-9) (unbound)
1799 Start a new numeric argument, or add to the current one. See
1800 also vi-digit-or-beginning-of-line. This only works if bound to
1801 a key sequence ending in a decimal digit.
1802 Inside a widget function, a call to this function treats the
1804 last key of the key sequence which called the widget as the
1805 digit.
1806 neg-argument (ESC--) (unbound) (unbound)
1808 Changes the sign of the following argument.
1809 universal-argument
1811 Multiply the argument of the next command by 4. Alternatively,
1812 if this command is followed by an integer (positive or nega‐
1813 tive), use that as the argument for the next command. Thus dig‐
1814 its cannot be repeated using this command. For example, if this
1815 command occurs twice, followed immediately by forward-char, move
1816 forward sixteen spaces; if instead it is followed by -2, then
1817 forward-char, move backward two spaces.
1818 Inside a widget function, if passed an argument, i.e. `zle uni‐
1820 versal-argument num', the numeric argument will be set to num;
1821 this is equivalent to `NUMERIC=num'.
1822 argument-base
1824 Use the existing numeric argument as a numeric base, which must
1825 be in the range 2 to 36 inclusive. Subsequent use of digit-ar‐
1826 gument and universal-argument will input a new numeric argument
1827 in the given base. The usual hexadecimal convention is used:
1828 the letter a or A corresponds to 10, and so on. Arguments in
1829 bases requiring digits from 10 upwards are more conveniently in‐
1830 put with universal-argument, since ESC-a etc. are not usually
1831 bound to digit-argument.
1832 The function can be used with a command argument inside a
1834 user-defined widget. The following code sets the base to 16 and
1835 lets the user input a hexadecimal argument until a key out of
1836 the digit range is typed:
1837 zle argument-base 16
1839 zle universal-argument
1840 Completion
1842 accept-and-menu-complete
1843 In a menu completion, insert the current completion into the
1844 buffer, and advance to the next possible completion.
1845 complete-word
1847 Attempt completion on the current word.
1848 delete-char-or-list (^D) (unbound) (unbound)
1850 Delete the character under the cursor. If the cursor is at the
1851 end of the line, list possible completions for the current word.
1852 expand-cmd-path
1854 Expand the current command to its full pathname.
1855 expand-or-complete (TAB) (unbound) (TAB)
1857 Attempt shell expansion on the current word. If that fails, at‐
1858 tempt completion.
1859 expand-or-complete-prefix
1861 Attempt shell expansion on the current word up to cursor.
1862 expand-history (ESC-space ESC-!) (unbound) (unbound)
1864 Perform history expansion on the edit buffer.
1865 expand-word (^X*) (unbound) (unbound)
1867 Attempt shell expansion on the current word.
1868 list-choices (ESC-^D) (^D =) (^D)
1870 List possible completions for the current word.
1871 list-expand (^Xg ^XG) (^G) (^G)
1873 List the expansion of the current word.
1874 magic-space
1876 Perform history expansion and insert a space into the buffer.
1877 This is intended to be bound to space.
1878 menu-complete
1880 Like complete-word, except that menu completion is used. See
1881 the MENU_COMPLETE option.
1882 menu-expand-or-complete
1884 Like expand-or-complete, except that menu completion is used.
1885 reverse-menu-complete
1887 Perform menu completion, like menu-complete, except that if a
1888 menu completion is already in progress, move to the previous
1889 completion rather than the next.
1890 end-of-list
1892 When a previous completion displayed a list below the prompt,
1893 this widget can be used to move the prompt below the list.
1894 Miscellaneous
1896 accept-and-hold (ESC-A ESC-a) (unbound) (unbound)
1897 Push the contents of the buffer on the buffer stack and execute
1898 it.
1899 accept-and-infer-next-history
1901 Execute the contents of the buffer. Then search the history
1902 list for a line matching the current one and push the event fol‐
1903 lowing onto the buffer stack.
1904 accept-line (^J ^M) (^J ^M) (^J ^M)
1906 Finish editing the buffer. Normally this causes the buffer to
1907 be executed as a shell command.
1908 accept-line-and-down-history (^O) (unbound) (unbound)
1910 Execute the current line, and push the next history event on the
1911 buffer stack.
1912 auto-suffix-remove
1914 If the previous action added a suffix (space, slash, etc.) to
1915 the word on the command line, remove it. Otherwise do nothing.
1916 Removing the suffix ends any active menu completion or menu se‐
1917 lection.
1918 This widget is intended to be called from user-defined widgets
1920 to enforce a desired suffix-removal behavior.
1921 auto-suffix-retain
1923 If the previous action added a suffix (space, slash, etc.) to
1924 the word on the command line, force it to be preserved. Other‐
1925 wise do nothing. Retaining the suffix ends any active menu com‐
1926 pletion or menu selection.
1927 This widget is intended to be called from user-defined widgets
1929 to enforce a desired suffix-preservation behavior.
1930 beep Beep, unless the BEEP option is unset.
1932 bracketed-paste
1934 This widget is invoked when text is pasted to the terminal emu‐
1935 lator. It is not intended to be bound to actual keys but instead
1936 to the special sequence generated by the terminal emulator when
1937 text is pasted.
1938 When invoked interactively, the pasted text is inserted to the
1940 buffer and placed in the cutbuffer. If a numeric argument is
1941 given, shell quoting will be applied to the pasted text before
1942 it is inserted.
1943 When a named buffer is specified with vi-set-buffer ("x), the
1945 pasted text is stored in that named buffer but not inserted.
1946 When called from a widget function as `bracketed-paste name`,
1948 the pasted text is assigned to the variable name and no other
1949 processing is done.
1950 See also the zle_bracketed_paste parameter.
1952 vi-cmd-mode (^X^V) (unbound) (^[)
1954 Enter command mode; that is, select the `vicmd' keymap. Yes,
1955 this is bound by default in emacs mode.
1956 vi-caps-lock-panic
1958 Hang until any lowercase key is pressed. This is for vi users
1959 without the mental capacity to keep track of their caps lock key
1960 (like the author).
1961 clear-screen (^L ESC-^L) (^L) (^L)
1963 Clear the screen and redraw the prompt.
1964 deactivate-region
1966 Make the current region inactive. This disables vim-style visual
1967 selection mode if it is active.
1968 describe-key-briefly
1970 Reads a key sequence, then prints the function bound to that se‐
1971 quence.
1972 exchange-point-and-mark (^X^X) (unbound) (unbound)
1974 Exchange the cursor position (point) with the position of the
1975 mark. Unless a negative numeric argument is given, the region
1976 between point and mark is activated so that it can be high‐
1977 lighted. If a zero numeric argument is given, the region is ac‐
1978 tivated but point and mark are not swapped.
1979 execute-named-cmd (ESC-x) (:) (unbound)
1981 Read the name of an editor command and execute it. Aliasing
1982 this widget with `zle -A' or replacing it with `zle -N' has no
1983 effect when interpreting key bindings, but `zle exe‐
1984 cute-named-cmd' will invoke such an alias or replacement.
1985 A restricted set of editing functions is available in the
1987 mini-buffer. Keys are looked up in the special command keymap,
1988 and if not found there in the main keymap. An interrupt signal,
1989 as defined by the stty setting, will abort the function. Note
1990 that the following always perform the same task within the exe‐
1991 cuted-named-cmd environment and cannot be replaced by user de‐
1992 fined widgets, nor can the set of functions be extended. The
1993 allowed functions are: backward-delete-char, vi-back‐
1994 ward-delete-char, clear-screen, redisplay, quoted-insert,
1995 vi-quoted-insert, backward-kill-word, vi-backward-kill-word,
1996 kill-whole-line, vi-kill-line, backward-kill-line, list-choices,
1997 delete-char-or-list, complete-word, accept-line, expand-or-com‐
1998 plete and expand-or-complete-prefix.
1999 kill-region kills the last word, and vi-cmd-mode is treated the
2001 same as accept-line. The space and tab characters, if not bound
2002 to one of these functions, will complete the name and then list
2003 the possibilities if the AUTO_LIST option is set. Any other
2004 character that is not bound to self-insert or self-insert-unmeta
2005 will beep and be ignored. The bindings of the current insert
2006 mode will be used.
2007 Currently this command may not be redefined or called by name.
2009 execute-last-named-cmd (ESC-z) (unbound) (unbound)
2011 Redo the last function executed with execute-named-cmd.
2012 Like execute-named-cmd, this command may not be redefined, but
2014 it may be called by name.
2015 get-line (ESC-G ESC-g) (unbound) (unbound)
2017 Pop the top line off the buffer stack and insert it at the cur‐
2018 sor position.
2019 pound-insert (unbound) (#) (unbound)
2021 If there is no # character at the beginning of the buffer, add
2022 one to the beginning of each line. If there is one, remove a #
2023 from each line that has one. In either case, accept the current
2024 line. The INTERACTIVE_COMMENTS option must be set for this to
2025 have any usefulness.
2026 vi-pound-insert
2028 If there is no # character at the beginning of the current line,
2029 add one. If there is one, remove it. The INTERACTIVE_COMMENTS
2030 option must be set for this to have any usefulness.
2031 push-input
2033 Push the entire current multiline construct onto the buffer
2034 stack and return to the top-level (PS1) prompt. If the current
2035 parser construct is only a single line, this is exactly like
2036 push-line. Next time the editor starts up or is popped with
2037 get-line, the construct will be popped off the top of the buffer
2038 stack and loaded into the editing buffer.
2039 push-line (^Q ESC-Q ESC-q) (unbound) (unbound)
2041 Push the current buffer onto the buffer stack and clear the buf‐
2042 fer. Next time the editor starts up, the buffer will be popped
2043 off the top of the buffer stack and loaded into the editing buf‐
2044 fer.
2045 push-line-or-edit
2047 At the top-level (PS1) prompt, equivalent to push-line. At a
2048 secondary (PS2) prompt, move the entire current multiline con‐
2049 struct into the editor buffer. The latter is equivalent to
2050 push-input followed by get-line.
2051 read-command
2053 Only useful from a user-defined widget. A keystroke is read
2054 just as in normal operation, but instead of the command being
2055 executed the name of the command that would be executed is
2056 stored in the shell parameter REPLY. This can be used as the
2057 argument of a future zle command. If the key sequence is not
2058 bound, status 1 is returned; typically, however, REPLY is set to
2059 undefined-key to indicate a useless key sequence.
2060 recursive-edit
2062 Only useful from a user-defined widget. At this point in the
2063 function, the editor regains control until one of the standard
2064 widgets which would normally cause zle to exit (typically an ac‐
2065 cept-line caused by hitting the return key) is executed. In‐
2066 stead, control returns to the user-defined widget. The status
2067 returned is non-zero if the return was caused by an error, but
2068 the function still continues executing and hence may tidy up.
2069 This makes it safe for the user-defined widget to alter the com‐
2070 mand line or key bindings temporarily.
2071 The following widget, caps-lock, serves as an example.
2073 self-insert-ucase() {
2075 LBUFFER+=${(U)KEYS[-1]}
2076 }
2077 integer stat
2079 zle -N self-insert self-insert-ucase
2081 zle -A caps-lock save-caps-lock
2082 zle -A accept-line caps-lock
2083 zle recursive-edit
2085 stat=$?
2086 zle -A .self-insert self-insert
2088 zle -A save-caps-lock caps-lock
2089 zle -D save-caps-lock
2090 (( stat )) && zle send-break
2092 return $stat
2094 This causes typed letters to be inserted capitalised until ei‐
2096 ther accept-line (i.e. typically the return key) is typed or the
2097 caps-lock widget is invoked again; the later is handled by sav‐
2098 ing the old definition of caps-lock as save-caps-lock and then
2099 rebinding it to invoke accept-line. Note that an error from the
2100 recursive edit is detected as a non-zero return status and prop‐
2101 agated by using the send-break widget.
2102 redisplay (unbound) (^R) (^R)
2104 Redisplays the edit buffer.
2105 reset-prompt (unbound) (unbound) (unbound)
2107 Force the prompts on both the left and right of the screen to be
2108 re-expanded, then redisplay the edit buffer. This reflects
2109 changes both to the prompt variables themselves and changes in
2110 the expansion of the values (for example, changes in time or di‐
2111 rectory, or changes to the value of variables referred to by the
2112 prompt).
2113 Otherwise, the prompt is only expanded each time zle starts, and
2115 when the display has been interrupted by output from another
2116 part of the shell (such as a job notification) which causes the
2117 command line to be reprinted.
2118 reset-prompt doesn't alter the special parameter LASTWIDGET.
2120 send-break (^G ESC-^G) (unbound) (unbound)
2122 Abort the current editor function, e.g. execute-named-command,
2123 or the editor itself, e.g. if you are in vared. Otherwise abort
2124 the parsing of the current line; in this case the aborted line
2125 is available in the shell variable ZLE_LINE_ABORTED. If the ed‐
2126 itor is aborted from within vared, the variable
2127 ZLE_VARED_ABORTED is set.
2128 run-help (ESC-H ESC-h) (unbound) (unbound)
2130 Push the buffer onto the buffer stack, and execute the command
2131 `run-help cmd', where cmd is the current command. run-help is
2132 normally aliased to man.
2133 vi-set-buffer (unbound) (") (unbound)
2135 Specify a buffer to be used in the following command. There are
2136 37 buffers that can be specified: the 26 `named' buffers "a to
2137 "z, the `yank' buffer "0, the nine `queued' buffers "1 to "9 and
2138 the `black hole' buffer "_. The named buffers can also be spec‐
2139 ified as "A to "Z.
2140 When a buffer is specified for a cut, change or yank command,
2142 the text concerned replaces the previous contents of the speci‐
2143 fied buffer. If a named buffer is specified using a capital, the
2144 newly cut text is appended to the buffer instead of overwriting
2145 it. When using the "_ buffer, nothing happens. This can be use‐
2146 ful for deleting text without affecting any buffers.
2147 If no buffer is specified for a cut or change command, "1 is
2149 used, and the contents of "1 to "8 are each shifted along one
2150 buffer; the contents of "9 is lost. If no buffer is specified
2151 for a yank command, "0 is used. Finally, a paste command without
2152 a specified buffer will paste the text from the most recent com‐
2153 mand regardless of any buffer that might have been used with
2154 that command.
2155 When called from a widget function by the zle command, the buf‐
2157 fer can optionally be specified with an argument. For example,
2158 zle vi-set-buffer A
2160 vi-set-mark (unbound) (m) (unbound)
2162 Set the specified mark at the cursor position.
2163 set-mark-command (^@) (unbound) (unbound)
2165 Set the mark at the cursor position. If called with a negative
2166 numeric argument, do not set the mark but deactivate the region
2167 so that it is no longer highlighted (it is still usable for
2168 other purposes). Otherwise the region is marked as active.
2169 spell-word (ESC-$ ESC-S ESC-s) (unbound) (unbound)
2171 Attempt spelling correction on the current word.
2172 split-undo
2174 Breaks the undo sequence at the current change. This is useful
2175 in vi mode as changes made in insert mode are coalesced on en‐
2176 tering command mode. Similarly, undo will normally revert as
2177 one all the changes made by a user-defined widget.
2178 undefined-key
2180 This command is executed when a key sequence that is not bound
2181 to any command is typed. By default it beeps.
2182 undo (^_ ^Xu ^X^U) (u) (unbound)
2184 Incrementally undo the last text modification. When called from
2185 a user-defined widget, takes an optional argument indicating a
2186 previous state of the undo history as returned by the
2187 UNDO_CHANGE_NO variable; modifications are undone until that
2188 state is reached, subject to any limit imposed by the
2189 UNDO_LIMIT_NO variable.
2190 Note that when invoked from vi command mode, the full prior
2192 change made in insert mode is reverted, the changes having been
2193 merged when command mode was selected.
2194 redo (unbound) (^R) (unbound)
2196 Incrementally redo undone text modifications.
2197 vi-undo-change (unbound) (unbound) (unbound)
2199 Undo the last text modification. If repeated, redo the modifi‐
2200 cation.
2201 visual-mode (unbound) (v) (unbound)
2203 Toggle vim-style visual selection mode. If line-wise visual mode
2204 is currently enabled then it is changed to being character-wise.
2205 If used following an operator, it forces the subsequent movement
2206 command to be treated as a character-wise movement.
2207 visual-line-mode (unbound) (V) (unbound)
2209 Toggle vim-style line-wise visual selection mode. If charac‐
2210 ter-wise visual mode is currently enabled then it is changed to
2211 being line-wise. If used following an operator, it forces the
2212 subsequent movement command to be treated as a line-wise move‐
2213 ment.
2214 what-cursor-position (^X=) (ga) (unbound)
2216 Print the character under the cursor, its code as an octal, dec‐
2217 imal and hexadecimal number, the current cursor position within
2218 the buffer and the column of the cursor in the current line.
2219 where-is
2221 Read the name of an editor command and print the listing of key
2222 sequences that invoke the specified command. A restricted set
2223 of editing functions is available in the mini-buffer. Keys are
2224 looked up in the special command keymap, and if not found there
2225 in the main keymap.
2226 which-command (ESC-?) (unbound) (unbound)
2228 Push the buffer onto the buffer stack, and execute the command
2229 `which-command cmd'. where cmd is the current command.
2230 which-command is normally aliased to whence.
2231 vi-digit-or-beginning-of-line (unbound) (0) (unbound)
2233 If the last command executed was a digit as part of an argument,
2234 continue the argument. Otherwise, execute vi-beginning-of-line.
2235 Text Objects
2237 Text objects are commands that can be used to select a block of text
2238 according to some criteria. They are a feature of the vim text editor
2239 and so are primarily intended for use with vi operators or from visual
2240 selection mode. However, they can also be used from vi-insert or emacs
2241 mode. Key bindings listed below apply to the viopp and visual keymaps.
2242 select-a-blank-word (aW)
2244 Select a word including adjacent blanks, where a word is defined
2245 as a series of non-blank characters. With a numeric argument,
2246 multiple words will be selected.
2247 select-a-shell-word (aa)
2249 Select the current command argument applying the normal rules
2250 for quoting.
2251 select-a-word (aw)
2253 Select a word including adjacent blanks, using the normal
2254 vi-style word definition. With a numeric argument, multiple
2255 words will be selected.
2256 select-in-blank-word (iW)
2258 Select a word, where a word is defined as a series of non-blank
2259 characters. With a numeric argument, multiple words will be se‐
2260 lected.
2261 select-in-shell-word (ia)
2263 Select the current command argument applying the normal rules
2264 for quoting. If the argument begins and ends with matching quote
2265 characters, these are not included in the selection.
2266 select-in-word (iw)
2268 Select a word, using the normal vi-style word definition. With a
2269 numeric argument, multiple words will be selected.
2270
2272 The line editor has the ability to highlight characters or regions of
2273 the line that have a particular significance. This is controlled by
2274 the array parameter zle_highlight, if it has been set by the user.
2275 If the parameter contains the single entry none all highlighting is
2277 turned off. Note the parameter is still expected to be an array.
2278 Otherwise each entry of the array should consist of a word indicating a
2280 context for highlighting, then a colon, then a comma-separated list of
2281 the types of highlighting to apply in that context.
2282 The contexts available for highlighting are the following:
2284 default
2286 Any text within the command line not affected by any other high‐
2287 lighting. Text outside the editable area of the command line is
2288 not affected.
2289 isearch
2291 When one of the incremental history search widgets is active,
2292 the area of the command line matched by the search string or
2293 pattern.
2294 region The currently selected text. In emacs terminology, this is re‐
2296 ferred to as the region and is bounded by the cursor (point) and
2297 the mark. The region is only highlighted if it is active, which
2298 is the case after the mark is modified with set-mark-command or
2299 exchange-point-and-mark. Note that whether or not the region is
2300 active has no effect on its use within emacs style widgets, it
2301 simply determines whether it is highlighted. In vi mode, the re‐
2302 gion corresponds to selected text in visual mode.
2303 special
2305 Individual characters that have no direct printable representa‐
2306 tion but are shown in a special manner by the line editor.
2307 These characters are described below.
2308 suffix This context is used in completion for characters that are
2310 marked as suffixes that will be removed if the completion ends
2311 at that point, the most obvious example being a slash (/) after
2312 a directory name. Note that suffix removal is configurable; the
2313 circumstances under which the suffix will be removed may differ
2314 for different completions.
2315 paste Following a command to paste text, the characters that were in‐
2317 serted.
2318 When region_highlight is set, the contexts that describe a region --
2320 isearch, region, suffix, and paste -- are applied first, then re‐
2321 gion_highlight is applied, then the remaining zle_highlight contexts
2322 are applied. If a particular character is affected by multiple speci‐
2323 fications, the last specification wins.
2324 zle_highlight may contain additional fields for controlling how termi‐
2326 nal sequences to change colours are output. Each of the following is
2327 followed by a colon and a string in the same form as for key bindings.
2328 This will not be necessary for the vast majority of terminals as the
2329 defaults shown in parentheses are widely used.
2330 fg_start_code (\e[3)
2332 The start of the escape sequence for the foreground colour.
2333 This is followed by one to three ASCII digits representing the
2334 colour. Only used for palette colors, i.e. not 24-bit colors
2335 specified via a color triplet.
2336 fg_default_code (9)
2338 The number to use instead of the colour to reset the default
2339 foreground colour.
2340 fg_end_code (m)
2342 The end of the escape sequence for the foreground colour.
2343 bg_start_code (\e[4)
2345 The start of the escape sequence for the background colour. See
2346 fg_start_code above.
2347 bg_default_code (9)
2349 The number to use instead of the colour to reset the default
2350 background colour.
2351 bg_end_code (m)
2353 The end of the escape sequence for the background colour.
2354 The available types of highlighting are the following. Note that not
2356 all types of highlighting are available on all terminals:
2357 none No highlighting is applied to the given context. It is not use‐
2359 ful for this to appear with other types of highlighting; it is
2360 used to override a default.
2361 fg=colour
2363 The foreground colour should be set to colour, a decimal inte‐
2364 ger, the name of one of the eight most widely-supported colours
2365 or as a `#' followed by an RGB triplet in hexadecimal format.
2366 Not all terminals support this and, of those that do, not all
2368 provide facilities to test the support, hence the user should
2369 decide based on the terminal type. Most terminals support the
2370 colours black, red, green, yellow, blue, magenta, cyan and
2371 white, which can be set by name. In addition. default may be
2372 used to set the terminal's default foreground colour. Abbrevia‐
2373 tions are allowed; b or bl selects black. Some terminals may
2374 generate additional colours if the bold attribute is also
2375 present.
2376 On recent terminals and on systems with an up-to-date terminal
2378 database the number of colours supported may be tested by the
2379 command `echotc Co'; if this succeeds, it indicates a limit on
2380 the number of colours which will be enforced by the line editor.
2381 The number of colours is in any case limited to 256 (i.e. the
2382 range 0 to 255).
2383 Some modern terminal emulators have support for 24-bit true
2385 colour (16 million colours). In this case, the hex triplet for‐
2386 mat can be used. This consists of a `#' followed by either a
2387 three or six digit hexadecimal number describing the red, green
2388 and blue components of the colour. Hex triplets can also be used
2389 with 88 and 256 colour terminals via the zsh/nearcolor module
2390 (see zshmodules(1)).
2391 Colour is also known as color.
2393 bg=colour
2395 The background colour should be set to colour. This works simi‐
2396 larly to the foreground colour, except the background is not
2397 usually affected by the bold attribute.
2398 bold The characters in the given context are shown in a bold font.
2400 Not all terminals distinguish bold fonts.
2401 standout
2403 The characters in the given context are shown in the terminal's
2404 standout mode. The actual effect is specific to the terminal;
2405 on many terminals it is inverse video. On some such terminals,
2406 where the cursor does not blink it appears with standout mode
2407 negated, making it less than clear where the cursor actually is.
2408 On such terminals one of the other effects may be preferable for
2409 highlighting the region and matched search string.
2410 underline
2412 The characters in the given context are shown underlined. Some
2413 terminals show the foreground in a different colour instead; in
2414 this case whitespace will not be highlighted.
2415 The characters described above as `special' are as follows. The for‐
2417 matting described here is used irrespective of whether the characters
2418 are highlighted:
2419 ASCII control characters
2421 Control characters in the ASCII range are shown as `^' followed
2422 by the base character.
2423 Unprintable multibyte characters
2425 This item applies to control characters not in the ASCII range,
2426 plus other characters as follows. If the MULTIBYTE option is in
2427 effect, multibyte characters not in the ASCII character set that
2428 are reported as having zero width are treated as combining char‐
2429 acters when the option COMBINING_CHARS is on. If the option is
2430 off, or if a character appears where a combining character is
2431 not valid, the character is treated as unprintable.
2432 Unprintable multibyte characters are shown as a hexadecimal num‐
2434 ber between angle brackets. The number is the code point of the
2435 character in the wide character set; this may or may not be Uni‐
2436 code, depending on the operating system.
2437 Invalid multibyte characters
2439 If the MULTIBYTE option is in effect, any sequence of one or
2440 more bytes that does not form a valid character in the current
2441 character set is treated as a series of bytes each shown as a
2442 special character. This case can be distinguished from other
2443 unprintable characters as the bytes are represented as two hexa‐
2444 decimal digits between angle brackets, as distinct from the four
2445 or eight digits that are used for unprintable characters that
2446 are nonetheless valid in the current character set.
2447 Not all systems support this: for it to work, the system's rep‐
2449 resentation of wide characters must be code values from the Uni‐
2450 versal Character Set, as defined by IS0 10646 (also known as
2451 Unicode).
2452 Wrapped double-width characters
2454 When a double-width character appears in the final column of a
2455 line, it is instead shown on the next line. The empty space left
2456 in the original position is highlighted as a special character.
2457 If zle_highlight is not set or no value applies to a particular con‐
2459 text, the defaults applied are equivalent to
2460 zle_highlight=(region:standout special:standout
2462 suffix:bold isearch:underline paste:standout)
2463 i.e. both the region and special characters are shown in standout mode.
2465 Within widgets, arbitrary regions may be highlighted by setting the
2467 special array parameter region_highlight; see above.
2468zsh 5.8.1 February 12, 2022 ZSHZLE(1)