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
14 default. It only works if the TERM parameter is set to a valid termi‐
15 nal 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
38 argument 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
74 `viins', otherwise it will be `emacs'. bindkey's -e and -v options
75 provide 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
122 sequence in the global keymap that is a prefix of that sequence. An
123 example of this occurs with the binding of iw in viopp as this hides
124 the binding of i in vicmd. However, a longer sequence in the global
125 keymap that shares the same prefix can still apply so for example the
126 binding of ^Xa in the global keymap will be unaffected by the binding
127 of ^Xb in 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
196 already has that name, it is deleted. If an old-keymap
197 name is given, the new keymap is initialized to be a
198 duplicate 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
203 unchanged) 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
217 self-insert 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
222 undefined-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
275 sequences 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
310 parameter, or the -A flag to create an associative array. If
311 the type of an existing parameter does not match the type to be
312 created, the parameter is unset and recreated. The -g flag may
313 be 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
324 parameters 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
343 options, 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
372 active as part of the completion system; this does not allow
373 direct 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
436 `vi-repeat-change'. The flag should be set early in the
437 function before inspecting the value of NUMERIC or invok‐
438 ing other widgets. This has no effect for a widget
439 invoked from insert mode. If insert mode is active when
440 the widget finishes, the change extends until next
441 returning to 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
514 actually 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
520 becomes 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
524 details: `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
539 descriptor 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
656 user-defined 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
679 parameters; 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
701 sequences 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
705 below. Other built-in widgets can be defined by other modules (see
706 zshmodules(1)). Each built-in widget has two names: its normal canoni‐
707 cal name, and the same name preceded by a `.'. The `.' name is spe‐
708 cial: it can't be rebound to a different widget. This makes the widget
709 available 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
824 recently 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
849 replaced, and the cursor remains between the new $LBUFFER and
850 the 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
860 parameter 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
892 position. 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
941 region_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
962 order 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
1025 set-local-history widget. The string contains `insert' if char‐
1026 acters to be inserted on the command line move existing charac‐
1027 ters to the right or `overwrite' if characters to be inserted
1028 overwrite existing characters. It contains `localhistory' if
1029 only local history commands will be visited or `globalhistory'
1030 if imported 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
1046 zle-isearch-update 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
1058 incremental search. This can be done from a zle-isearch-exit
1059 widget:
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
1106 sequences shown in the list are those based on the VT100, common on
1107 many modern terminals, but in fact these are not necessarily bound. In
1108 the case of the viins keymap, the initial escape character of the
1109 sequences serves also to return to the vicmd keymap: whether this hap‐
1110 pens is determined 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
1165 defined 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
1183 occurrence 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
1294 incremental 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
1322 inserted the search history is rewound to the point just
1323 before the character was entered. Hence this has the
1324 effect 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
1366 incremental search commands can take a string argument. This
1367 will be treated as a string of keys, as for arguments to the
1368 bindkey command, and used as initial input for the command. Any
1369 characters in the string which are unused by the incremental
1370 search 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
1390 options 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
1400 expression with wildcards may return fewer matches on a line
1401 than 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
1471 options.
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
1532 local 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
1569 insert 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
1574 included. 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
1589 copy-region-as-kill string' then string will be taken as the
1590 text to copy to the kill buffer. The cursor, the mark and the
1591 text on 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
1639 insert 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
1650 entered.
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
1698 sequence 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
1712 beginning 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
1761 position is retained, regardless of how the words are rear‐
1762 ranged.
1763 vi-unindent (unbound) (<) (unbound)
1765 Unindent a number of lines.
1766 vi-up-case (unbound) (gU) (unbound)
1768 Read a movement command from the keyboard, and convert all char‐
1769 acters from the cursor position to the endpoint of the movement
1770 to lowercase. If the movement command is vi-up-case, swap the
1771 case of all characters on the current line.
1772 up-case-word (ESC-U ESC-u) (unbound) (unbound)
1774 Convert the current word to all caps and move past it.
1775 yank (^Y) (unbound) (unbound)
1777 Insert the contents of the kill buffer at the cursor position.
1778 yank-pop (ESC-y) (unbound) (unbound)
1780 Remove the text just yanked, rotate the kill-ring (the history
1781 of previously killed text) and yank the new top. Only works
1782 following yank, vi-put-before, vi-put-after or yank-pop.
1783 vi-yank (unbound) (y) (unbound)
1785 Read a movement command from the keyboard, and copy the region
1786 from the cursor position to the endpoint of the movement into
1787 the kill buffer. If the command is vi-yank, copy the current
1788 line.
1789 vi-yank-whole-line (unbound) (Y) (unbound)
1791 Copy the current line into the kill buffer.
1792 vi-yank-eol
1794 Copy the region from the cursor position to the end of the line
1795 into the kill buffer. Arguably, this is what Y should do in vi,
1796 but it isn't what it actually does.
1797 Arguments
1799 digit-argument (ESC-0..ESC-9) (1-9) (unbound)
1800 Start a new numeric argument, or add to the current one. See
1801 also vi-digit-or-beginning-of-line. This only works if bound to
1802 a key sequence ending in a decimal digit.
1803 Inside a widget function, a call to this function treats the
1805 last key of the key sequence which called the widget as the
1806 digit.
1807 neg-argument (ESC--) (unbound) (unbound)
1809 Changes the sign of the following argument.
1810 universal-argument
1812 Multiply the argument of the next command by 4. Alternatively,
1813 if this command is followed by an integer (positive or nega‐
1814 tive), use that as the argument for the next command. Thus dig‐
1815 its cannot be repeated using this command. For example, if this
1816 command occurs twice, followed immediately by forward-char, move
1817 forward sixteen spaces; if instead it is followed by -2, then
1818 forward-char, move backward two spaces.
1819 Inside a widget function, if passed an argument, i.e. `zle uni‐
1821 versal-argument num', the numeric argument will be set to num;
1822 this is equivalent to `NUMERIC=num'.
1823 argument-base
1825 Use the existing numeric argument as a numeric base, which must
1826 be in the range 2 to 36 inclusive. Subsequent use of
1827 digit-argument and universal-argument will input a new numeric
1828 argument in the given base. The usual hexadecimal convention is
1829 used: the letter a or A corresponds to 10, and so on. Arguments
1830 in bases requiring digits from 10 upwards are more conveniently
1831 input with universal-argument, since ESC-a etc. are not usually
1832 bound to digit-argument.
1833 The function can be used with a command argument inside a
1835 user-defined widget. The following code sets the base to 16 and
1836 lets the user input a hexadecimal argument until a key out of
1837 the digit range is typed:
1838 zle argument-base 16
1840 zle universal-argument
1841 Completion
1843 accept-and-menu-complete
1844 In a menu completion, insert the current completion into the
1845 buffer, and advance to the next possible completion.
1846 complete-word
1848 Attempt completion on the current word.
1849 delete-char-or-list (^D) (unbound) (unbound)
1851 Delete the character under the cursor. If the cursor is at the
1852 end of the line, list possible completions for the current word.
1853 expand-cmd-path
1855 Expand the current command to its full pathname.
1856 expand-or-complete (TAB) (unbound) (TAB)
1858 Attempt shell expansion on the current word. If that fails,
1859 attempt completion.
1860 expand-or-complete-prefix
1862 Attempt shell expansion on the current word up to cursor.
1863 expand-history (ESC-space ESC-!) (unbound) (unbound)
1865 Perform history expansion on the edit buffer.
1866 expand-word (^X*) (unbound) (unbound)
1868 Attempt shell expansion on the current word.
1869 list-choices (ESC-^D) (^D =) (^D)
1871 List possible completions for the current word.
1872 list-expand (^Xg ^XG) (^G) (^G)
1874 List the expansion of the current word.
1875 magic-space
1877 Perform history expansion and insert a space into the buffer.
1878 This is intended to be bound to space.
1879 menu-complete
1881 Like complete-word, except that menu completion is used. See
1882 the MENU_COMPLETE option.
1883 menu-expand-or-complete
1885 Like expand-or-complete, except that menu completion is used.
1886 reverse-menu-complete
1888 Perform menu completion, like menu-complete, except that if a
1889 menu completion is already in progress, move to the previous
1890 completion rather than the next.
1891 end-of-list
1893 When a previous completion displayed a list below the prompt,
1894 this widget can be used to move the prompt below the list.
1895 Miscellaneous
1897 accept-and-hold (ESC-A ESC-a) (unbound) (unbound)
1898 Push the contents of the buffer on the buffer stack and execute
1899 it.
1900 accept-and-infer-next-history
1902 Execute the contents of the buffer. Then search the history
1903 list for a line matching the current one and push the event fol‐
1904 lowing onto the buffer stack.
1905 accept-line (^J ^M) (^J ^M) (^J ^M)
1907 Finish editing the buffer. Normally this causes the buffer to
1908 be executed as a shell command.
1909 accept-line-and-down-history (^O) (unbound) (unbound)
1911 Execute the current line, and push the next history event on the
1912 buffer stack.
1913 auto-suffix-remove
1915 If the previous action added a suffix (space, slash, etc.) to
1916 the word on the command line, remove it. Otherwise do nothing.
1917 Removing the suffix ends any active menu completion or menu
1918 selection.
1919 This widget is intended to be called from user-defined widgets
1921 to enforce a desired suffix-removal behavior.
1922 auto-suffix-retain
1924 If the previous action added a suffix (space, slash, etc.) to
1925 the word on the command line, force it to be preserved. Other‐
1926 wise do nothing. Retaining the suffix ends any active menu com‐
1927 pletion or menu selection.
1928 This widget is intended to be called from user-defined widgets
1930 to enforce a desired suffix-preservation behavior.
1931 beep Beep, unless the BEEP option is unset.
1933 bracketed-paste
1935 This widget is invoked when text is pasted to the terminal emu‐
1936 lator. It is not intended to be bound to actual keys but instead
1937 to the special sequence generated by the terminal emulator when
1938 text is pasted.
1939 When invoked interactively, the pasted text is inserted to the
1941 buffer and placed in the cutbuffer. If a numeric argument is
1942 given, shell quoting will be applied to the pasted text before
1943 it is inserted.
1944 When a named buffer is specified with vi-set-buffer ("x), the
1946 pasted text is stored in that named buffer but not inserted.
1947 When called from a widget function as `bracketed-paste name`,
1949 the pasted text is assigned to the variable name and no other
1950 processing is done.
1951 See also the zle_bracketed_paste parameter.
1953 vi-cmd-mode (^X^V) (unbound) (^[)
1955 Enter command mode; that is, select the `vicmd' keymap. Yes,
1956 this is bound by default in emacs mode.
1957 vi-caps-lock-panic
1959 Hang until any lowercase key is pressed. This is for vi users
1960 without the mental capacity to keep track of their caps lock key
1961 (like the author).
1962 clear-screen (^L ESC-^L) (^L) (^L)
1964 Clear the screen and redraw the prompt.
1965 deactivate-region
1967 Make the current region inactive. This disables vim-style visual
1968 selection mode if it is active.
1969 describe-key-briefly
1971 Reads a key sequence, then prints the function bound to that
1972 sequence.
1973 exchange-point-and-mark (^X^X) (unbound) (unbound)
1975 Exchange the cursor position (point) with the position of the
1976 mark. Unless a negative numeric argument is given, the region
1977 between point and mark is activated so that it can be high‐
1978 lighted. If a zero numeric argument is given, the region is
1979 activated but point and mark are not swapped.
1980 execute-named-cmd (ESC-x) (:) (unbound)
1982 Read the name of an editor command and execute it. Aliasing
1983 this widget with `zle -A' or replacing it with `zle -N' has no
1984 effect when interpreting key bindings, but `zle exe‐
1985 cute-named-cmd' will invoke such an alias or replacement.
1986 A restricted set of editing functions is available in the
1988 mini-buffer. Keys are looked up in the special command keymap,
1989 and if not found there in the main keymap. An interrupt signal,
1990 as defined by the stty setting, will abort the function. Note
1991 that the following always perform the same task within the exe‐
1992 cuted-named-cmd environment and cannot be replaced by user
1993 defined widgets, nor can the set of functions be extended. The
1994 allowed functions are: backward-delete-char, vi-back‐
1995 ward-delete-char, clear-screen, redisplay, quoted-insert,
1996 vi-quoted-insert, backward-kill-word, vi-backward-kill-word,
1997 kill-whole-line, vi-kill-line, backward-kill-line, list-choices,
1998 delete-char-or-list, complete-word, accept-line, expand-or-com‐
1999 plete and expand-or-complete-prefix.
2000 kill-region kills the last word, and vi-cmd-mode is treated the
2002 same as accept-line. The space and tab characters, if not bound
2003 to one of these functions, will complete the name and then list
2004 the possibilities if the AUTO_LIST option is set. Any other
2005 character that is not bound to self-insert or self-insert-unmeta
2006 will beep and be ignored. The bindings of the current insert
2007 mode will be used.
2008 Currently this command may not be redefined or called by name.
2010 execute-last-named-cmd (ESC-z) (unbound) (unbound)
2012 Redo the last function executed with execute-named-cmd.
2013 Like execute-named-cmd, this command may not be redefined, but
2015 it may be called by name.
2016 get-line (ESC-G ESC-g) (unbound) (unbound)
2018 Pop the top line off the buffer stack and insert it at the cur‐
2019 sor position.
2020 pound-insert (unbound) (#) (unbound)
2022 If there is no # character at the beginning of the buffer, add
2023 one to the beginning of each line. If there is one, remove a #
2024 from each line that has one. In either case, accept the current
2025 line. The INTERACTIVE_COMMENTS option must be set for this to
2026 have any usefulness.
2027 vi-pound-insert
2029 If there is no # character at the beginning of the current line,
2030 add one. If there is one, remove it. The INTERACTIVE_COMMENTS
2031 option must be set for this to have any usefulness.
2032 push-input
2034 Push the entire current multiline construct onto the buffer
2035 stack and return to the top-level (PS1) prompt. If the current
2036 parser construct is only a single line, this is exactly like
2037 push-line. Next time the editor starts up or is popped with
2038 get-line, the construct will be popped off the top of the buffer
2039 stack and loaded into the editing buffer.
2040 push-line (^Q ESC-Q ESC-q) (unbound) (unbound)
2042 Push the current buffer onto the buffer stack and clear the buf‐
2043 fer. Next time the editor starts up, the buffer will be popped
2044 off the top of the buffer stack and loaded into the editing buf‐
2045 fer.
2046 push-line-or-edit
2048 At the top-level (PS1) prompt, equivalent to push-line. At a
2049 secondary (PS2) prompt, move the entire current multiline con‐
2050 struct into the editor buffer. The latter is equivalent to
2051 push-input followed by get-line.
2052 read-command
2054 Only useful from a user-defined widget. A keystroke is read
2055 just as in normal operation, but instead of the command being
2056 executed the name of the command that would be executed is
2057 stored in the shell parameter REPLY. This can be used as the
2058 argument of a future zle command. If the key sequence is not
2059 bound, status 1 is returned; typically, however, REPLY is set to
2060 undefined-key to indicate a useless key sequence.
2061 recursive-edit
2063 Only useful from a user-defined widget. At this point in the
2064 function, the editor regains control until one of the standard
2065 widgets which would normally cause zle to exit (typically an
2066 accept-line caused by hitting the return key) is executed.
2067 Instead, control returns to the user-defined widget. The status
2068 returned is non-zero if the return was caused by an error, but
2069 the function still continues executing and hence may tidy up.
2070 This makes it safe for the user-defined widget to alter the com‐
2071 mand line or key bindings temporarily.
2072 The following widget, caps-lock, serves as an example.
2074 self-insert-ucase() {
2076 LBUFFER+=${(U)KEYS[-1]}
2077 }
2078 integer stat
2080 zle -N self-insert self-insert-ucase
2082 zle -A caps-lock save-caps-lock
2083 zle -A accept-line caps-lock
2084 zle recursive-edit
2086 stat=$?
2087 zle -A .self-insert self-insert
2089 zle -A save-caps-lock caps-lock
2090 zle -D save-caps-lock
2091 (( stat )) && zle send-break
2093 return $stat
2095 This causes typed letters to be inserted capitalised until
2097 either accept-line (i.e. typically the return key) is typed or
2098 the caps-lock widget is invoked again; the later is handled by
2099 saving the old definition of caps-lock as save-caps-lock and
2100 then rebinding it to invoke accept-line. Note that an error
2101 from the recursive edit is detected as a non-zero return status
2102 and propagated by using the send-break widget.
2103 redisplay (unbound) (^R) (^R)
2105 Redisplays the edit buffer.
2106 reset-prompt (unbound) (unbound) (unbound)
2108 Force the prompts on both the left and right of the screen to be
2109 re-expanded, then redisplay the edit buffer. This reflects
2110 changes both to the prompt variables themselves and changes in
2111 the expansion of the values (for example, changes in time or
2112 directory, or changes to the value of variables referred to by
2113 the prompt).
2114 Otherwise, the prompt is only expanded each time zle starts, and
2116 when the display has been interrupted by output from another
2117 part of the shell (such as a job notification) which causes the
2118 command line to be reprinted.
2119 reset-prompt doesn't alter the special parameter LASTWIDGET.
2121 send-break (^G ESC-^G) (unbound) (unbound)
2123 Abort the current editor function, e.g. execute-named-command,
2124 or the editor itself, e.g. if you are in vared. Otherwise abort
2125 the parsing of the current line; in this case the aborted line
2126 is available in the shell variable ZLE_LINE_ABORTED. If the
2127 editor is aborted from within vared, the variable
2128 ZLE_VARED_ABORTED is set.
2129 run-help (ESC-H ESC-h) (unbound) (unbound)
2131 Push the buffer onto the buffer stack, and execute the command
2132 `run-help cmd', where cmd is the current command. run-help is
2133 normally aliased to man.
2134 vi-set-buffer (unbound) (") (unbound)
2136 Specify a buffer to be used in the following command. There are
2137 37 buffers that can be specified: the 26 `named' buffers "a to
2138 "z, the `yank' buffer "0, the nine `queued' buffers "1 to "9 and
2139 the `black hole' buffer "_. The named buffers can also be spec‐
2140 ified as "A to "Z.
2141 When a buffer is specified for a cut, change or yank command,
2143 the text concerned replaces the previous contents of the speci‐
2144 fied buffer. If a named buffer is specified using a capital, the
2145 newly cut text is appended to the buffer instead of overwriting
2146 it. When using the "_ buffer, nothing happens. This can be use‐
2147 ful for deleting text without affecting any buffers.
2148 If no buffer is specified for a cut or change command, "1 is
2150 used, and the contents of "1 to "8 are each shifted along one
2151 buffer; the contents of "9 is lost. If no buffer is specified
2152 for a yank command, "0 is used. Finally, a paste command without
2153 a specified buffer will paste the text from the most recent com‐
2154 mand regardless of any buffer that might have been used with
2155 that command.
2156 When called from a widget function by the zle command, the buf‐
2158 fer can optionally be specified with an argument. For example,
2159 zle vi-set-buffer A
2161 vi-set-mark (unbound) (m) (unbound)
2163 Set the specified mark at the cursor position.
2164 set-mark-command (^@) (unbound) (unbound)
2166 Set the mark at the cursor position. If called with a negative
2167 numeric argument, do not set the mark but deactivate the region
2168 so that it is no longer highlighted (it is still usable for
2169 other purposes). Otherwise the region is marked as active.
2170 spell-word (ESC-$ ESC-S ESC-s) (unbound) (unbound)
2172 Attempt spelling correction on the current word.
2173 split-undo
2175 Breaks the undo sequence at the current change. This is useful
2176 in vi mode as changes made in insert mode are coalesced on
2177 entering command mode. Similarly, undo will normally revert as
2178 one all the changes made by a user-defined widget.
2179 undefined-key
2181 This command is executed when a key sequence that is not bound
2182 to any command is typed. By default it beeps.
2183 undo (^_ ^Xu ^X^U) (u) (unbound)
2185 Incrementally undo the last text modification. When called from
2186 a user-defined widget, takes an optional argument indicating a
2187 previous state of the undo history as returned by the
2188 UNDO_CHANGE_NO variable; modifications are undone until that
2189 state is reached, subject to any limit imposed by the
2190 UNDO_LIMIT_NO variable.
2191 Note that when invoked from vi command mode, the full prior
2193 change made in insert mode is reverted, the changes having been
2194 merged when command mode was selected.
2195 redo (unbound) (^R) (unbound)
2197 Incrementally redo undone text modifications.
2198 vi-undo-change (unbound) (unbound) (unbound)
2200 Undo the last text modification. If repeated, redo the modifi‐
2201 cation.
2202 visual-mode (unbound) (v) (unbound)
2204 Toggle vim-style visual selection mode. If line-wise visual mode
2205 is currently enabled then it is changed to being character-wise.
2206 If used following an operator, it forces the subsequent movement
2207 command to be treated as a character-wise movement.
2208 visual-line-mode (unbound) (V) (unbound)
2210 Toggle vim-style line-wise visual selection mode. If charac‐
2211 ter-wise visual mode is currently enabled then it is changed to
2212 being line-wise. If used following an operator, it forces the
2213 subsequent movement command to be treated as a line-wise move‐
2214 ment.
2215 what-cursor-position (^X=) (ga) (unbound)
2217 Print the character under the cursor, its code as an octal, dec‐
2218 imal and hexadecimal number, the current cursor position within
2219 the buffer and the column of the cursor in the current line.
2220 where-is
2222 Read the name of an editor command and print the listing of key
2223 sequences that invoke the specified command. A restricted set
2224 of editing functions is available in the mini-buffer. Keys are
2225 looked up in the special command keymap, and if not found there
2226 in the main keymap.
2227 which-command (ESC-?) (unbound) (unbound)
2229 Push the buffer onto the buffer stack, and execute the command
2230 `which-command cmd'. where cmd is the current command.
2231 which-command is normally aliased to whence.
2232 vi-digit-or-beginning-of-line (unbound) (0) (unbound)
2234 If the last command executed was a digit as part of an argument,
2235 continue the argument. Otherwise, execute vi-beginning-of-line.
2236 Text Objects
2238 Text objects are commands that can be used to select a block of text
2239 according to some criteria. They are a feature of the vim text editor
2240 and so are primarily intended for use with vi operators or from visual
2241 selection mode. However, they can also be used from vi-insert or emacs
2242 mode. Key bindings listed below apply to the viopp and visual keymaps.
2243 select-a-blank-word (aW)
2245 Select a word including adjacent blanks, where a word is defined
2246 as a series of non-blank characters. With a numeric argument,
2247 multiple words will be selected.
2248 select-a-shell-word (aa)
2250 Select the current command argument applying the normal rules
2251 for quoting.
2252 select-a-word (aw)
2254 Select a word including adjacent blanks, using the normal
2255 vi-style word definition. With a numeric argument, multiple
2256 words will be selected.
2257 select-in-blank-word (iW)
2259 Select a word, where a word is defined as a series of non-blank
2260 characters. With a numeric argument, multiple words will be
2261 selected.
2262 select-in-shell-word (ia)
2264 Select the current command argument applying the normal rules
2265 for quoting. If the argument begins and ends with matching quote
2266 characters, these are not included in the selection.
2267 select-in-word (iw)
2269 Select a word, using the normal vi-style word definition. With a
2270 numeric argument, multiple words will be selected.
2271
2273 The line editor has the ability to highlight characters or regions of
2274 the line that have a particular significance. This is controlled by
2275 the array parameter zle_highlight, if it has been set by the user.
2276 If the parameter contains the single entry none all highlighting is
2278 turned off. Note the parameter is still expected to be an array.
2279 Otherwise each entry of the array should consist of a word indicating a
2281 context for highlighting, then a colon, then a comma-separated list of
2282 the types of highlighting to apply in that context.
2283 The contexts available for highlighting are the following:
2285 default
2287 Any text within the command line not affected by any other high‐
2288 lighting. Text outside the editable area of the command line is
2289 not affected.
2290 isearch
2292 When one of the incremental history search widgets is active,
2293 the area of the command line matched by the search string or
2294 pattern.
2295 region The currently selected text. In emacs terminology, this is
2297 referred to as the region and is bounded by the cursor (point)
2298 and the mark. The region is only highlighted if it is active,
2299 which is the case after the mark is modified with set-mark-com‐
2300 mand or exchange-point-and-mark. Note that whether or not the
2301 region is active has no effect on its use within emacs style
2302 widgets, it simply determines whether it is highlighted. In vi
2303 mode, the region corresponds to selected text in visual mode.
2304 special
2306 Individual characters that have no direct printable representa‐
2307 tion but are shown in a special manner by the line editor.
2308 These characters are described below.
2309 suffix This context is used in completion for characters that are
2311 marked as suffixes that will be removed if the completion ends
2312 at that point, the most obvious example being a slash (/) after
2313 a directory name. Note that suffix removal is configurable; the
2314 circumstances under which the suffix will be removed may differ
2315 for different completions.
2316 paste Following a command to paste text, the characters that were
2318 inserted.
2319 When region_highlight is set, the contexts that describe a region --
2321 isearch, region, suffix, and paste -- are applied first, then
2322 region_highlight is applied, then the remaining zle_highlight contexts
2323 are applied. If a particular character is affected by multiple speci‐
2324 fications, the last specification wins.
2325 zle_highlight may contain additional fields for controlling how termi‐
2327 nal sequences to change colours are output. Each of the following is
2328 followed by a colon and a string in the same form as for key bindings.
2329 This will not be necessary for the vast majority of terminals as the
2330 defaults shown in parentheses are widely used.
2331 fg_start_code (\e[3)
2333 The start of the escape sequence for the foreground colour.
2334 This is followed by one to three ASCII digits representing the
2335 colour. Only used for palette colors, i.e. not 24-bit colors
2336 specified via a color triplet.
2337 fg_default_code (9)
2339 The number to use instead of the colour to reset the default
2340 foreground colour.
2341 fg_end_code (m)
2343 The end of the escape sequence for the foreground colour.
2344 bg_start_code (\e[4)
2346 The start of the escape sequence for the background colour. See
2347 fg_start_code above.
2348 bg_default_code (9)
2350 The number to use instead of the colour to reset the default
2351 background colour.
2352 bg_end_code (m)
2354 The end of the escape sequence for the background colour.
2355 The available types of highlighting are the following. Note that not
2357 all types of highlighting are available on all terminals:
2358 none No highlighting is applied to the given context. It is not use‐
2360 ful for this to appear with other types of highlighting; it is
2361 used to override a default.
2362 fg=colour
2364 The foreground colour should be set to colour, a decimal inte‐
2365 ger, the name of one of the eight most widely-supported colours
2366 or as a `#' followed by an RGB triplet in hexadecimal format.
2367 Not all terminals support this and, of those that do, not all
2369 provide facilities to test the support, hence the user should
2370 decide based on the terminal type. Most terminals support the
2371 colours black, red, green, yellow, blue, magenta, cyan and
2372 white, which can be set by name. In addition. default may be
2373 used to set the terminal's default foreground colour. Abbrevia‐
2374 tions are allowed; b or bl selects black. Some terminals may
2375 generate additional colours if the bold attribute is also
2376 present.
2377 On recent terminals and on systems with an up-to-date terminal
2379 database the number of colours supported may be tested by the
2380 command `echotc Co'; if this succeeds, it indicates a limit on
2381 the number of colours which will be enforced by the line editor.
2382 The number of colours is in any case limited to 256 (i.e. the
2383 range 0 to 255).
2384 Some modern terminal emulators have support for 24-bit true
2386 colour (16 million colours). In this case, the hex triplet for‐
2387 mat can be used. This consists of a `#' followed by either a
2388 three or six digit hexadecimal number describing the red, green
2389 and blue components of the colour. Hex triplets can also be used
2390 with 88 and 256 colour terminals via the zsh/nearcolor module
2391 (see zshmodules(1)).
2392 Colour is also known as color.
2394 bg=colour
2396 The background colour should be set to colour. This works simi‐
2397 larly to the foreground colour, except the background is not
2398 usually affected by the bold attribute.
2399 bold The characters in the given context are shown in a bold font.
2401 Not all terminals distinguish bold fonts.
2402 standout
2404 The characters in the given context are shown in the terminal's
2405 standout mode. The actual effect is specific to the terminal;
2406 on many terminals it is inverse video. On some such terminals,
2407 where the cursor does not blink it appears with standout mode
2408 negated, making it less than clear where the cursor actually is.
2409 On such terminals one of the other effects may be preferable for
2410 highlighting the region and matched search string.
2411 underline
2413 The characters in the given context are shown underlined. Some
2414 terminals show the foreground in a different colour instead; in
2415 this case whitespace will not be highlighted.
2416 The characters described above as `special' are as follows. The for‐
2418 matting described here is used irrespective of whether the characters
2419 are highlighted:
2420 ASCII control characters
2422 Control characters in the ASCII range are shown as `^' followed
2423 by the base character.
2424 Unprintable multibyte characters
2426 This item applies to control characters not in the ASCII range,
2427 plus other characters as follows. If the MULTIBYTE option is in
2428 effect, multibyte characters not in the ASCII character set that
2429 are reported as having zero width are treated as combining char‐
2430 acters when the option COMBINING_CHARS is on. If the option is
2431 off, or if a character appears where a combining character is
2432 not valid, the character is treated as unprintable.
2433 Unprintable multibyte characters are shown as a hexadecimal num‐
2435 ber between angle brackets. The number is the code point of the
2436 character in the wide character set; this may or may not be Uni‐
2437 code, depending on the operating system.
2438 Invalid multibyte characters
2440 If the MULTIBYTE option is in effect, any sequence of one or
2441 more bytes that does not form a valid character in the current
2442 character set is treated as a series of bytes each shown as a
2443 special character. This case can be distinguished from other
2444 unprintable characters as the bytes are represented as two hexa‐
2445 decimal digits between angle brackets, as distinct from the four
2446 or eight digits that are used for unprintable characters that
2447 are nonetheless valid in the current character set.
2448 Not all systems support this: for it to work, the system's rep‐
2450 resentation of wide characters must be code values from the Uni‐
2451 versal Character Set, as defined by IS0 10646 (also known as
2452 Unicode).
2453 Wrapped double-width characters
2455 When a double-width character appears in the final column of a
2456 line, it is instead shown on the next line. The empty space left
2457 in the original position is highlighted as a special character.
2458 If zle_highlight is not set or no value applies to a particular con‐
2460 text, the defaults applied are equivalent to
2461 zle_highlight=(region:standout special:standout
2463 suffix:bold isearch:underline paste:standout)
2464 i.e. both the region and special characters are shown in standout mode.
2466 Within widgets, arbitrary regions may be highlighted by setting the
2468 special array parameter region_highlight; see above.
2469zsh 5.8 February 14, 2020 ZSHZLE(1)