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. See also the Arguments
40 subsection of the Widgets section for some other ways the numeric argu‐
41 ment can be modified. The default bindings mentioned here use the
42 digit-argument widget.
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 [ -Aache ] [ -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.
313 If an array or array slice is being edited, separator characters
315 as defined in $IFS will be shown quoted with a backslash, as
316 will backslashes themselves. Conversely, when the edited text
317 is split into an array, a backslash quotes an immediately fol‐
318 lowing separator character or backslash; no other special han‐
319 dling of backslashes, or any handling of quotes, is performed.
320 Individual elements of existing array or associative array
322 parameters may be edited by using subscript syntax on name. New
323 elements are created automatically, even without -c.
324 If the -p flag is given, the following string will be taken as
326 the prompt to display at the left. If the -r flag is given, the
327 following string gives the prompt to display at the right. If
328 the -h flag is specified, the history can be accessed from ZLE.
329 If the -e flag is given, typing ^D (Control-D) on an empty line
330 causes vared to exit immediately with a non-zero return value.
331 The -M option gives a keymap to link to the main keymap during
333 editing, and the -m option gives a keymap to link to the vicmd
334 keymap during editing. For vi-style editing, this allows a pair
335 of keymaps to override viins and vicmd. For emacs-style edit‐
336 ing, only -M is normally needed but the -m option may still be
337 used. On exit, the previous keymaps will be restored.
338 Vared calls the usual `zle-line-init' and `zle-line-finish'
340 hooks before and after it takes control. Using the -i and -f
341 options, it is possible to replace these with other custom wid‐
342 gets.
343 If `-t tty' is given, tty is the name of a terminal device to be
345 used instead of the default /dev/tty. If tty does not refer to
346 a terminal an error is reported.
347 zle
349 zle -l [ -L | -a ] [ string ... ]
350 zle -D widget ...
351 zle -A old-widget new-widget
352 zle -N widget [ function ]
353 zle -f flag [ flag... ]
354 zle -C widget completion-widget function
355 zle -R [ -c ] [ display-string ] [ string ... ]
356 zle -M string
357 zle -U string
358 zle -K keymap
359 zle -F [ -L | -w ] [ fd [ handler ] ]
360 zle -I
361 zle -T [ tc function | -r tc | -L ]
362 zle widget [ -n num ] [ -Nw ] [ -K keymap ] args ...
363 The zle builtin performs a number of different actions concern‐
364 ing ZLE.
365 With no options and no arguments, only the return status will be
367 set. It is zero if ZLE is currently active and widgets could be
368 invoked using this builtin command and non-zero otherwise. Note
369 that even if non-zero status is returned, zle may still be
370 active as part of the completion system; this does not allow
371 direct calls to ZLE widgets.
372 Otherwise, which operation it performs depends on its options:
374 -l [ -L | -a ] [ string ]
376 List all existing user-defined widgets. If the -L option
377 is used, list in the form of zle commands to create the
378 widgets.
379 When combined with the -a option, all widget names are
381 listed, including the builtin ones. In this case the -L
382 option is ignored.
383 If at least one string is given, and -a is present or -L
385 is not used, nothing will be printed. The return status
386 will be zero if all strings are names of existing widgets
387 and non-zero if at least one string is not a name of a
388 defined widget. If -a is also present, all widget names
389 are used for the comparison including builtin widgets,
390 else only user-defined widgets are used.
391 If at least one string is present and the -L option is
393 used, user-defined widgets matching any string are listed
394 in the form of zle commands to create the widgets.
395 -D widget ...
397 Delete the named widgets.
398 -A old-widget new-widget
400 Make the new-widget name an alias for old-widget, so that
401 both names refer to the same widget. The names have
402 equal standing; if either is deleted, the other remains.
403 If there is already a widget with the new-widget name, it
404 is deleted.
405 -N widget [ function ]
407 Create a user-defined widget. If there is already a wid‐
408 get with the specified name, it is overwritten. When the
409 new widget is invoked from within the editor, the speci‐
410 fied shell function is called. If no function name is
411 specified, it defaults to the same name as the widget.
412 For further information, see the section `Widgets' below.
413 -f flag [ flag... ]
415 Set various flags on the running widget. Possible values
416 for flag are:
417 yank for indicating that the widget has yanked text into
419 the buffer. If the widget is wrapping an existing inter‐
420 nal widget, no further action is necessary, but if it has
421 inserted the text manually, then it should also take care
422 to set YANK_START and YANK_END correctly. yankbefore
423 does the same but is used when the yanked text appears
424 after the cursor.
425 kill for indicating that text has been killed into the
427 cutbuffer. When repeatedly invoking a kill widget, text
428 is appended to the cutbuffer instead of replacing it, but
429 when wrapping such widgets, it is necessary to call `zle
430 -f kill' to retain this effect.
431 vichange for indicating that the widget represents a vi
433 change that can be repeated as a whole with
434 `vi-repeat-change'. The flag should be set early in the
435 function before inspecting the value of NUMERIC or invok‐
436 ing other widgets. This has no effect for a widget
437 invoked from insert mode. If insert mode is active when
438 the widget finishes, the change extends until next
439 returning to command mode.
440 -C widget completion-widget function
442 Create a user-defined completion widget named widget. The
443 completion widget will behave like the built-in comple‐
444 tion-widget whose name is given as completion-widget. To
445 generate the completions, the shell function function
446 will be called. For further information, see zshcomp‐
447 wid(1).
448 -R [ -c ] [ display-string ] [ string ... ]
450 Redisplay the command line; this is to be called from
451 within a user-defined widget to allow changes to become
452 visible. If a display-string is given and not empty,
453 this is shown in the status line (immediately below the
454 line being edited).
455 If the optional strings are given they are listed below
457 the prompt in the same way as completion lists are
458 printed. If no strings are given but the -c option is
459 used such a list is cleared.
460 Note that this option is only useful for widgets that do
462 not exit immediately after using it because the strings
463 displayed will be erased immediately after return from
464 the widget.
465 This command can safely be called outside user defined
467 widgets; if zle is active, the display will be refreshed,
468 while if zle is not active, the command has no effect.
469 In this case there will usually be no other arguments.
470 The status is zero if zle was active, else one.
472 -M string
474 As with the -R option, the string will be displayed below
475 the command line; unlike the -R option, the string will
476 not be put into the status line but will instead be
477 printed normally below the prompt. This means that the
478 string will still be displayed after the widget returns
479 (until it is overwritten by subsequent commands).
480 -U string
482 This pushes the characters in the string onto the input
483 stack of ZLE. After the widget currently executed fin‐
484 ishes ZLE will behave as if the characters in the string
485 were typed by the user.
486 As ZLE uses a stack, if this option is used repeatedly
488 the last string pushed onto the stack will be processed
489 first. However, the characters in each string will be
490 processed in the order in which they appear in the
491 string.
492 -K keymap
494 Selects the keymap named keymap. An error message will
495 be displayed if there is no such keymap.
496 This keymap selection affects the interpretation of fol‐
498 lowing keystrokes within this invocation of ZLE. Any
499 following invocation (e.g., the next command line) will
500 start as usual with the `main' keymap selected.
501 -F [ -L | -w ] [ fd [ handler ] ]
503 Only available if your system supports one of the `poll'
504 or `select' system calls; most modern systems do.
505 Installs handler (the name of a shell function) to handle
507 input from file descriptor fd. Installing a handler for
508 an fd which is already handled causes the existing han‐
509 dler to be replaced. Any number of handlers for any num‐
510 ber of readable file descriptors may be installed. Note
511 that zle makes no attempt to check whether this fd is
512 actually readable when installing the handler. The user
513 must make their own arrangements for handling the file
514 descriptor when zle is not active.
515 When zle is attempting to read data, it will examine both
517 the terminal and the list of handled fd's. If data
518 becomes available on a handled fd, zle calls handler with
519 the fd which is ready for reading as the first argument.
520 Under normal circumstances this is the only argument, but
521 if an error was detected, a second argument provides
522 details: `hup' for a disconnect, `nval' for a closed or
523 otherwise invalid descriptor, or `err' for any other con‐
524 dition. Systems that support only the `select' system
525 call always use `err'.
526 If the option -w is also given, the handler is instead a
528 line editor widget, typically a shell function made into
529 a widget using `zle -N'. In that case handler can use
530 all the facilities of zle to update the current editing
531 line. Note, however, that as handling fd takes place at
532 a low level changes to the display will not automatically
533 appear; the widget should call `zle -R' to force redis‐
534 play. As of this writing, widget handlers only support a
535 single argument and thus are never passed a string for
536 error state, so widgets must be prepared to test the
537 descriptor themselves.
538 If either type of handler produces output to the termi‐
540 nal, it should call `zle -I' before doing so (see below).
541 Handlers should not attempt to read from the terminal.
542 If no handler is given, but an fd is present, any handler
544 for that fd is removed. If there is none, an error mes‐
545 sage is printed and status 1 is returned.
546 If no arguments are given, or the -L option is supplied,
548 a list of handlers is printed in a form which can be
549 stored for later execution.
550 An fd (but not a handler) may optionally be given with
552 the -L option; in this case, the function will list the
553 handler if any, else silently return status 1.
554 Note that this feature should be used with care. Activ‐
556 ity on one of the fd's which is not properly handled can
557 cause the terminal to become unusable. Removing an fd
558 handler from within a signal trap may cause unpredictable
559 behavior.
560 Here is a simple example of using this feature. A con‐
562 nection to a remote TCP port is created using the ztcp
563 command; see the description of the zsh/net/tcp module in
564 zshmodules(1). Then a handler is installed which simply
565 prints out any data which arrives on this connection.
566 Note that `select' will indicate that the file descriptor
567 needs handling if the remote side has closed the connec‐
568 tion; we handle that by testing for a failed read.
569 if ztcp pwspc 2811; then
571 tcpfd=$REPLY
572 handler() {
573 zle -I
574 local line
575 if ! read -r line <&$1; then
576 # select marks this fd if we reach EOF,
577 # so handle this specially.
578 print "[Read on fd $1 failed, removing.]" >&2
579 zle -F $1
580 return 1
581 fi
582 print -r - $line
583 }
584 zle -F $tcpfd handler
585 fi
586 -I Unusually, this option is most useful outside ordinary
588 widget functions, though it may be used within if normal
589 output to the terminal is required. It invalidates the
590 current zle display in preparation for output; typically
591 this will be from a trap function. It has no effect if
592 zle is not active. When a trap exits, the shell checks
593 to see if the display needs restoring, hence the follow‐
594 ing will print output in such a way as not to disturb the
595 line being edited:
596 TRAPUSR1() {
598 # Invalidate zle display
599 [[ -o zle ]] && zle -I
600 # Show output
601 print Hello
602 }
603 In general, the trap function may need to test whether
605 zle is active before using this method (as shown in the
606 example), since the zsh/zle module may not even be
607 loaded; if it is not, the command can be skipped.
608 It is possible to call `zle -I' several times before con‐
610 trol is returned to the editor; the display will only be
611 invalidated the first time to minimise disruption.
612 Note that there are normally better ways of manipulating
614 the display from within zle widgets; see, for example,
615 `zle -R' above.
616 The returned status is zero if zle was invalidated, even
618 though this may have been by a previous call to `zle -I'
619 or by a system notification. To test if a zle widget may
620 be called at this point, execute zle with no arguments
621 and examine the return status.
622 -T This is used to add, list or remove internal transforma‐
624 tions on the processing performed by the line editor. It
625 is typically used only for debugging or testing and is
626 therefore of little interest to the general user.
627 `zle -T transformation func' specifies that the given
629 transformation (see below) is effected by shell function
630 func.
631 `zle -Tr transformation' removes the given transformation
633 if it was present (it is not an error if none was).
634 `zle -TL' can be used to list all transformations cur‐
636 rently in operation.
637 Currently the only transformation is tc. This is used
639 instead of outputting termcap codes to the terminal.
640 When the transformation is in operation the shell func‐
641 tion is passed the termcap code that would be output as
642 its first argument; if the operation required a numeric
643 argument, that is passed as a second argument. The func‐
644 tion should set the shell variable REPLY to the trans‐
645 formed termcap code. Typically this is used to produce
646 some simply formatted version of the code and optional
647 argument for debugging or testing. Note that this trans‐
648 formation is not applied to other non-printing characters
649 such as carriage returns and newlines.
650 widget [ -n num ] [ -Nw ] [ -K keymap ] args ...
652 Invoke the specified widget. This can only be done when
653 ZLE is active; normally this will be within a
654 user-defined widget.
655 With the options -n and -N, the current numeric argument
657 will be saved and then restored after the call to widget;
658 `-n num' sets the numeric argument temporarily to num,
659 while `-N' sets it to the default, i.e. as if there were
660 none.
661 With the option -K, keymap will be used as the current
663 keymap during the execution of the widget. The previous
664 keymap will be restored when the widget exits.
665 Normally, calling a widget in this way does not set the
667 special parameter WIDGET and related parameters, so that
668 the environment appears as if the top-level widget called
669 by the user were still active. With the option -w, WID‐
670 GET and related parameters are set to reflect the widget
671 being executed by the zle call.
672 Any further arguments will be passed to the widget; note
674 that as standard argument handling is performed, any gen‐
675 eral argument list should be preceded by --. If it is a
676 shell function, these are passed down as positional
677 parameters; for builtin widgets it is up to the widget in
678 question what it does with them. Currently arguments are
679 only handled by the incremental-search commands, the his‐
680 tory-search-forward and -backward and the corresponding
681 functions prefixed by vi-, and by universal-argument. No
682 error is flagged if the command does not use the argu‐
683 ments, or only uses some of them.
684 The return status reflects the success or failure of the
686 operation carried out by the widget, or if it is a
687 user-defined widget the return status of the shell func‐
688 tion.
689 A non-zero return status causes the shell to beep when
691 the widget exits, unless the BEEP options was unset or
692 the widget was called via the zle command. Thus if a
693 user defined widget requires an immediate beep, it should
694 call the beep widget directly.
695
697 All actions in the editor are performed by `widgets'. A widget's job
698 is simply to perform some small action. The ZLE commands that key
699 sequences in keymaps are bound to are in fact widgets. Widgets can be
700 user-defined or built in.
701 The standard widgets built into ZLE are listed in Standard Widgets
703 below. Other built-in widgets can be defined by other modules (see
704 zshmodules(1)). Each built-in widget has two names: its normal canoni‐
705 cal name, and the same name preceded by a `.'. The `.' name is spe‐
706 cial: it can't be rebound to a different widget. This makes the widget
707 available even when its usual name has been redefined.
708 User-defined widgets are defined using `zle -N', and implemented as
710 shell functions. When the widget is executed, the corresponding shell
711 function is executed, and can perform editing (or other) actions. It
712 is recommended that user-defined widgets should not have names starting
713 with `.'.
714
716 User-defined widgets, being implemented as shell functions, can execute
717 any normal shell command. They can also run other widgets (whether
718 built-in or user-defined) using the zle builtin command. The standard
719 input of the function is redirected from /dev/null to prevent external
720 commands from unintentionally blocking ZLE by reading from the termi‐
721 nal, but read -k or read -q can be used to read characters. Finally,
722 they can examine and edit the ZLE buffer being edited by reading and
723 setting the special parameters described below.
724 These special parameters are always available in widget functions, but
726 are not in any way special outside ZLE. If they have some normal value
727 outside ZLE, that value is temporarily inaccessible, but will return
728 when the widget function exits. These special parameters in fact have
729 local scope, like parameters created in a function using local.
730 Inside completion widgets and traps called while ZLE is active, these
732 parameters are available read-only.
733 Note that the parameters appear as local to any ZLE widget in which
735 they appear. Hence if it is desired to override them this needs to be
736 done within a nested function:
737 widget-function() {
739 # $WIDGET here refers to the special variable
740 # that is local inside widget-function
741 () {
742 # This anonymous nested function allows WIDGET
743 # to be used as a local variable. The -h
744 # removes the special status of the variable.
745 local -h WIDGET
746 }
747 }
748 BUFFER (scalar)
750 The entire contents of the edit buffer. If it is written to,
751 the cursor remains at the same offset, unless that would put it
752 outside the buffer.
753 BUFFERLINES (integer)
755 The number of screen lines needed for the edit buffer currently
756 displayed on screen (i.e. without any changes to the preceding
757 parameters done after the last redisplay); read-only.
758 CONTEXT (scalar)
760 The context in which zle was called to read a line; read-only.
761 One of the values:
762 start The start of a command line (at prompt PS1).
764 cont A continuation to a command line (at prompt PS2).
766 select In a select loop (at prompt PS3).
768 vared Editing a variable in vared.
770 CURSOR (integer)
772 The offset of the cursor, within the edit buffer. This is in
773 the range 0 to $#BUFFER, and is by definition equal to
774 $#LBUFFER. Attempts to move the cursor outside the buffer will
775 result in the cursor being moved to the appropriate end of the
776 buffer.
777 CUTBUFFER (scalar)
779 The last item cut using one of the `kill-' commands; the string
780 which the next yank would insert in the line. Later entries in
781 the kill ring are in the array killring. Note that the command
782 `zle copy-region-as-kill string' can be used to set the text of
783 the cut buffer from a shell function and cycle the kill ring in
784 the same way as interactively killing text.
785 HISTNO (integer)
787 The current history number. Setting this has the same effect as
788 moving up or down in the history to the corresponding history
789 line. An attempt to set it is ignored if the line is not stored
790 in the history. Note this is not the same as the parameter
791 HISTCMD, which always gives the number of the history line being
792 added to the main shell's history. HISTNO refers to the line
793 being retrieved within zle.
794 ISEARCHMATCH_ACTIVE (integer)
796 ISEARCHMATCH_START (integer)
797 ISEARCHMATCH_END (integer)
798 ISEARCHMATCH_ACTIVE indicates whether a part of the BUFFER is
799 currently matched by an incremental search pattern. ISEARCH‐
800 MATCH_START and ISEARCHMATCH_END give the location of the
801 matched part and are in the same units as CURSOR. They are only
802 valid for reading when ISEARCHMATCH_ACTIVE is non-zero.
803 All parameters are read-only.
805 KEYMAP (scalar)
807 The name of the currently selected keymap; read-only.
808 KEYS (scalar)
810 The keys typed to invoke this widget, as a literal string;
811 read-only.
812 KEYS_QUEUED_COUNT (integer)
814 The number of bytes pushed back to the input queue and therefore
815 available for reading immediately before any I/O is done;
816 read-only. See also PENDING; the two values are distinct.
817 killring (array)
819 The array of previously killed items, with the most recently
820 killed first. This gives the items that would be retrieved by a
821 yank-pop in the same order. Note, however, that the most
822 recently killed item is in $CUTBUFFER; $killring shows the array
823 of previous entries.
824 The default size for the kill ring is eight, however the length
826 may be changed by normal array operations. Any empty string in
827 the kill ring is ignored by the yank-pop command, hence the size
828 of the array effectively sets the maximum length of the kill
829 ring, while the number of non-zero strings gives the current
830 length, both as seen by the user at the command line.
831 LASTABORTEDSEARCH (scalar)
833 The last search string used by an interactive search that was
834 aborted by the user (status 3 returned by the search widget).
835 LASTSEARCH (scalar)
837 The last search string used by an interactive search; read-only.
838 This is set even if the search failed (status 0, 1 or 2 returned
839 by the search widget), but not if it was aborted by the user.
840 LASTWIDGET (scalar)
842 The name of the last widget that was executed; read-only.
843 LBUFFER (scalar)
845 The part of the buffer that lies to the left of the cursor posi‐
846 tion. If it is assigned to, only that part of the buffer is
847 replaced, and the cursor remains between the new $LBUFFER and
848 the old $RBUFFER.
849 MARK (integer)
851 Like CURSOR, but for the mark. With vi-mode operators that wait
852 for a movement command to select a region of text, setting MARK
853 allows the selection to extend in both directions from the ini‐
854 tial cursor position.
855 NUMERIC (integer)
857 The numeric argument. If no numeric argument was given, this
858 parameter is unset. When this is set inside a widget function,
859 builtin widgets called with the zle builtin command will use the
860 value assigned. If it is unset inside a widget function, builtin
861 widgets called behave as if no numeric argument was given.
862 PENDING (integer)
864 The number of bytes pending for input, i.e. the number of bytes
865 which have already been typed and can immediately be read. On
866 systems where the shell is not able to get this information,
867 this parameter will always have a value of zero. Read-only.
868 See also KEYS_QUEUED_COUNT; the two values are distinct.
869 PREBUFFER (scalar)
871 In a multi-line input at the secondary prompt, this read-only
872 parameter contains the contents of the lines before the one the
873 cursor is currently in.
874 PREDISPLAY (scalar)
876 Text to be displayed before the start of the editable text buf‐
877 fer. This does not have to be a complete line; to display a
878 complete line, a newline must be appended explicitly. The text
879 is reset on each new invocation (but not recursive invocation)
880 of zle.
881 POSTDISPLAY (scalar)
883 Text to be displayed after the end of the editable text buffer.
884 This does not have to be a complete line; to display a complete
885 line, a newline must be prepended explicitly. The text is reset
886 on each new invocation (but not recursive invocation) of zle.
887 RBUFFER (scalar)
889 The part of the buffer that lies to the right of the cursor
890 position. If it is assigned to, only that part of the buffer is
891 replaced, and the cursor remains between the old $LBUFFER and
892 the new $RBUFFER.
893 REGION_ACTIVE (integer)
895 Indicates if the region is currently active. It can be assigned
896 0 or 1 to deactivate and activate the region respectively. A
897 value of 2 activates the region in line-wise mode with the high‐
898 lighted text extending for whole lines only; see Character High‐
899 lighting below.
900 region_highlight (array)
902 Each element of this array may be set to a string that describes
903 highlighting for an arbitrary region of the command line that
904 will take effect the next time the command line is redisplayed.
905 Highlighting of the non-editable parts of the command line in
906 PREDISPLAY and POSTDISPLAY are possible, but note that the P
907 flag is needed for character indexing to include PREDISPLAY.
908 Each string consists of the following parts:
910 · Optionally, a `P' to signify that the start and end off‐
912 set that follow include any string set by the PREDISPLAY
913 special parameter; this is needed if the predisplay
914 string itself is to be highlighted. Whitespace may fol‐
915 low the `P'.
916 · A start offset in the same units as CURSOR, terminated by
918 whitespace.
919 · An end offset in the same units as CURSOR, terminated by
921 whitespace.
922 · A highlight specification in the same format as used for
924 contexts in the parameter zle_highlight, see the section
925 `Character Highlighting' below; for example, standout or
926 fg=red,bold
927 For example,
929 region_highlight=("P0 20 bold")
931 specifies that the first twenty characters of the text including
933 any predisplay string should be highlighted in bold.
934 Note that the effect of region_highlight is not saved and disap‐
936 pears as soon as the line is accepted.
937 The final highlighting on the command line depends on both
939 region_highlight and zle_highlight; see the section CHARACTER
940 HIGHLIGHTING below for details.
941 registers (associative array)
943 The contents of each of the vi register buffers. These are typi‐
944 cally set using vi-set-buffer followed by a delete, change or
945 yank command.
946 SUFFIX_ACTIVE (integer)
948 SUFFIX_START (integer)
949 SUFFIX_END (integer)
950 SUFFIX_ACTIVE indicates whether an auto-removable completion
951 suffix is currently active. SUFFIX_START and SUFFIX_END give the
952 location of the suffix and are in the same units as CURSOR. They
953 are only valid for reading when SUFFIX_ACTIVE is non-zero.
954 All parameters are read-only.
956 UNDO_CHANGE_NO (integer)
958 A number representing the state of the undo history. The only
959 use of this is passing as an argument to the undo widget in
960 order to undo back to the recorded point. Read-only.
961 UNDO_LIMIT_NO (integer)
963 A number corresponding to an existing change in the undo his‐
964 tory; compare UNDO_CHANGE_NO. If this is set to a value greater
965 than zero, the undo command will not allow the line to be undone
966 beyond the given change number. It is still possible to use
967 `zle undo change' in a widget to undo beyond that point; in that
968 case, it will not be possible to undo at all until UNDO_LIMIT_NO
969 is reduced. Set to 0 to disable the limit.
970 A typical use of this variable in a widget function is as fol‐
972 lows (note the additional function scope is required):
973 () {
975 local UNDO_LIMIT_NO=$UNDO_CHANGE_NO
976 # Perform some form of recursive edit.
977 }
978 WIDGET (scalar)
980 The name of the widget currently being executed; read-only.
981 WIDGETFUNC (scalar)
983 The name of the shell function that implements a widget defined
984 with either zle -N or zle -C. In the former case, this is the
985 second argument to the zle -N command that defined the widget,
986 or the first argument if there was no second argument. In the
987 latter case this is the third argument to the zle -C command
988 that defined the widget. Read-only.
989 WIDGETSTYLE (scalar)
991 Describes the implementation behind the completion widget cur‐
992 rently being executed; the second argument that followed zle -C
993 when the widget was defined. This is the name of a builtin com‐
994 pletion widget. For widgets defined with zle -N this is set to
995 the empty string. Read-only.
996 YANK_ACTIVE (integer)
998 YANK_START (integer)
999 YANK_END (integer)
1000 YANK_ACTIVE indicates whether text has just been yanked (pasted)
1001 into the buffer. YANK_START and YANK_END give the location of
1002 the pasted text and are in the same units as CURSOR. They are
1003 only valid for reading when YANK_ACTIVE is non-zero. They can
1004 also be assigned by widgets that insert text in a yank-like
1005 fashion, for example wrappers of bracketed-paste. See also zle
1006 -f.
1007 YANK_ACTIVE is read-only.
1009 ZLE_STATE (scalar)
1011 Contains a set of space-separated words that describe the cur‐
1012 rent zle state.
1013 Currently, the states shown are the insert mode as set by the
1015 overwrite-mode or vi-replace widgets and whether history com‐
1016 mands will visit imported entries as controlled by the
1017 set-local-history widget. The string contains `insert' if char‐
1018 acters to be inserted on the command line move existing charac‐
1019 ters to the right or `overwrite' if characters to be inserted
1020 overwrite existing characters. It contains `localhistory' if
1021 only local history commands will be visited or `globalhistory'
1022 if imported history commands will also be visited.
1023 The substrings are sorted in alphabetical order so that if you
1025 want to test for two specific substrings in a future-proof way,
1026 you can do match by doing:
1027 if [[ $ZLE_STATE == *globalhistory*insert* ]]; then ...; fi
1029 Special Widgets
1031 There are a few user-defined widgets which are special to the shell.
1032 If they do not exist, no special action is taken. The environment pro‐
1033 vided is identical to that for any other editing widget.
1034 zle-isearch-exit
1036 Executed at the end of incremental search at the point where the
1037 isearch prompt is removed from the display. See
1038 zle-isearch-update for an example.
1039 zle-isearch-update
1041 Executed within incremental search when the display is about to
1042 be redrawn. Additional output below the incremental search
1043 prompt can be generated by using `zle -M' within the widget.
1044 For example,
1045 zle-isearch-update() { zle -M "Line $HISTNO"; }
1047 zle -N zle-isearch-update
1048 Note the line output by `zle -M' is not deleted on exit from
1050 incremental search. This can be done from a zle-isearch-exit
1051 widget:
1052 zle-isearch-exit() { zle -M ""; }
1054 zle -N zle-isearch-exit
1055 zle-line-pre-redraw
1057 Executed whenever the input line is about to be redrawn, provid‐
1058 ing an opportunity to update the region_highlight array.
1059 zle-line-init
1061 Executed every time the line editor is started to read a new
1062 line of input. The following example puts the line editor into
1063 vi command mode when it starts up.
1064 zle-line-init() { zle -K vicmd; }
1066 zle -N zle-line-init
1067 (The command inside the function sets the keymap directly; it is
1069 equivalent to zle vi-cmd-mode.)
1070 zle-line-finish
1072 This is similar to zle-line-init but is executed every time the
1073 line editor has finished reading a line of input.
1074 zle-history-line-set
1076 Executed when the history line changes.
1077 zle-keymap-select
1079 Executed every time the keymap changes, i.e. the special parame‐
1080 ter KEYMAP is set to a different value, while the line editor is
1081 active. Initialising the keymap when the line editor starts
1082 does not cause the widget to be called.
1083 The value $KEYMAP within the function reflects the new keymap.
1085 The old keymap is passed as the sole argument.
1086 This can be used for detecting switches between the vi command
1088 (vicmd) and insert (usually main) keymaps.
1089
1091 The following is a list of all the standard widgets, and their default
1092 bindings in emacs mode, vi command mode and vi insert mode (the
1093 `emacs', `vicmd' and `viins' keymaps, respectively).
1094 Note that cursor keys are bound to movement keys in all three keymaps;
1096 the shell assumes that the cursor keys send the key sequences reported
1097 by the terminal-handling library (termcap or terminfo). The key
1098 sequences shown in the list are those based on the VT100, common on
1099 many modern terminals, but in fact these are not necessarily bound. In
1100 the case of the viins keymap, the initial escape character of the
1101 sequences serves also to return to the vicmd keymap: whether this hap‐
1102 pens is determined by the KEYTIMEOUT parameter, see zshparam(1).
1103 Movement
1105 vi-backward-blank-word (unbound) (B) (unbound)
1106 Move backward one word, where a word is defined as a series of
1107 non-blank characters.
1108 vi-backward-blank-word-end (unbound) (gE) (unbound)
1110 Move to the end of the previous word, where a word is defined as
1111 a series of non-blank characters.
1112 backward-char (^B ESC-[D) (unbound) (unbound)
1114 Move backward one character.
1115 vi-backward-char (unbound) (^H h ^?) (ESC-[D)
1117 Move backward one character, without changing lines.
1118 backward-word (ESC-B ESC-b) (unbound) (unbound)
1120 Move to the beginning of the previous word.
1121 emacs-backward-word
1123 Move to the beginning of the previous word.
1124 vi-backward-word (unbound) (b) (unbound)
1126 Move to the beginning of the previous word, vi-style.
1127 vi-backward-word-end (unbound) (ge) (unbound)
1129 Move to the end of the previous word, vi-style.
1130 beginning-of-line (^A) (unbound) (unbound)
1132 Move to the beginning of the line. If already at the beginning
1133 of the line, move to the beginning of the previous line, if any.
1134 vi-beginning-of-line
1136 Move to the beginning of the line, without changing lines.
1137 down-line (unbound) (unbound) (unbound)
1139 Move down a line in the buffer.
1140 end-of-line (^E) (unbound) (unbound)
1142 Move to the end of the line. If already at the end of the line,
1143 move to the end of the next line, if any.
1144 vi-end-of-line (unbound) ($) (unbound)
1146 Move to the end of the line. If an argument is given to this
1147 command, the cursor will be moved to the end of the line (argu‐
1148 ment - 1) lines down.
1149 vi-forward-blank-word (unbound) (W) (unbound)
1151 Move forward one word, where a word is defined as a series of
1152 non-blank characters.
1153 vi-forward-blank-word-end (unbound) (E) (unbound)
1155 Move to the end of the current word, or, if at the end of the
1156 current word, to the end of the next word, where a word is
1157 defined as a series of non-blank characters.
1158 forward-char (^F ESC-[C) (unbound) (unbound)
1160 Move forward one character.
1161 vi-forward-char (unbound) (space l) (ESC-[C)
1163 Move forward one character.
1164 vi-find-next-char (^X^F) (f) (unbound)
1166 Read a character from the keyboard, and move to the next occur‐
1167 rence of it in the line.
1168 vi-find-next-char-skip (unbound) (t) (unbound)
1170 Read a character from the keyboard, and move to the position
1171 just before the next occurrence of it in the line.
1172 vi-find-prev-char (unbound) (F) (unbound)
1174 Read a character from the keyboard, and move to the previous
1175 occurrence of it in the line.
1176 vi-find-prev-char-skip (unbound) (T) (unbound)
1178 Read a character from the keyboard, and move to the position
1179 just after the previous occurrence of it in the line.
1180 vi-first-non-blank (unbound) (^) (unbound)
1182 Move to the first non-blank character in the line.
1183 vi-forward-word (unbound) (w) (unbound)
1185 Move forward one word, vi-style.
1186 forward-word (ESC-F ESC-f) (unbound) (unbound)
1188 Move to the beginning of the next word. The editor's idea of a
1189 word is specified with the WORDCHARS parameter.
1190 emacs-forward-word
1192 Move to the end of the next word.
1193 vi-forward-word-end (unbound) (e) (unbound)
1195 Move to the end of the next word.
1196 vi-goto-column (ESC-|) (|) (unbound)
1198 Move to the column specified by the numeric argument.
1199 vi-goto-mark (unbound) (`) (unbound)
1201 Move to the specified mark.
1202 vi-goto-mark-line (unbound) (') (unbound)
1204 Move to beginning of the line containing the specified mark.
1205 vi-repeat-find (unbound) (;) (unbound)
1207 Repeat the last vi-find command.
1208 vi-rev-repeat-find (unbound) (,) (unbound)
1210 Repeat the last vi-find command in the opposite direction.
1211 up-line (unbound) (unbound) (unbound)
1213 Move up a line in the buffer.
1214 History Control
1216 beginning-of-buffer-or-history (ESC-<) (gg) (unbound)
1217 Move to the beginning of the buffer, or if already there, move
1218 to the first event in the history list.
1219 beginning-of-line-hist
1221 Move to the beginning of the line. If already at the beginning
1222 of the buffer, move to the previous history line.
1223 beginning-of-history
1225 Move to the first event in the history list.
1226 down-line-or-history (^N ESC-[B) (j) (ESC-[B)
1228 Move down a line in the buffer, or if already at the bottom
1229 line, move to the next event in the history list.
1230 vi-down-line-or-history (unbound) (+) (unbound)
1232 Move down a line in the buffer, or if already at the bottom
1233 line, move to the next event in the history list. Then move to
1234 the first non-blank character on the line.
1235 down-line-or-search
1237 Move down a line in the buffer, or if already at the bottom
1238 line, search forward in the history for a line beginning with
1239 the first word in the buffer.
1240 If called from a function by the zle command with arguments, the
1242 first argument is taken as the string for which to search,
1243 rather than the first word in the buffer.
1244 down-history (unbound) (^N) (unbound)
1246 Move to the next event in the history list.
1247 history-beginning-search-backward
1249 Search backward in the history for a line beginning with the
1250 current line up to the cursor. This leaves the cursor in its
1251 original position.
1252 end-of-buffer-or-history (ESC->) (unbound) (unbound)
1254 Move to the end of the buffer, or if already there, move to the
1255 last event in the history list.
1256 end-of-line-hist
1258 Move to the end of the line. If already at the end of the buf‐
1259 fer, move to the next history line.
1260 end-of-history
1262 Move to the last event in the history list.
1263 vi-fetch-history (unbound) (G) (unbound)
1265 Fetch the history line specified by the numeric argument. This
1266 defaults to the current history line (i.e. the one that isn't
1267 history yet).
1268 history-incremental-search-backward (^R ^Xr) (unbound) (unbound)
1270 Search backward incrementally for a specified string. The
1271 search is case-insensitive if the search string does not have
1272 uppercase letters and no numeric argument was given. The string
1273 may begin with `^' to anchor the search to the beginning of the
1274 line. When called from a user-defined function returns the fol‐
1275 lowing statuses: 0, if the search succeeded; 1, if the search
1276 failed; 2, if the search term was a bad pattern; 3, if the
1277 search was aborted by the send-break command.
1278 A restricted set of editing functions is available in the
1280 mini-buffer. Keys are looked up in the special isearch keymap,
1281 and if not found there in the main keymap (note that by default
1282 the isearch keymap is empty). An interrupt signal, as defined
1283 by the stty setting, will stop the search and go back to the
1284 original line. An undefined key will have the same effect.
1285 Note that the following always perform the same task within
1286 incremental searches and cannot be replaced by user defined wid‐
1287 gets, nor can the set of functions be extended. The supported
1288 functions are:
1289 accept-and-hold
1291 accept-and-infer-next-history
1292 accept-line
1293 accept-line-and-down-history
1294 Perform the usual function after exiting incremental
1295 search. The command line displayed is executed.
1296 backward-delete-char
1298 vi-backward-delete-char
1299 Back up one place in the search history. If the search
1300 has been repeated this does not immediately erase a char‐
1301 acter in the minibuffer.
1302 accept-search
1304 Exit incremental search, retaining the command line but
1305 performing no further action. Note that this function is
1306 not bound by default and has no effect outside incremen‐
1307 tal search.
1308 backward-delete-word
1310 backward-kill-word
1311 vi-backward-kill-word
1312 Back up one character in the minibuffer; if multiple
1313 searches have been performed since the character was
1314 inserted the search history is rewound to the point just
1315 before the character was entered. Hence this has the
1316 effect of repeating backward-delete-char.
1317 clear-screen
1319 Clear the screen, remaining in incremental search mode.
1320 history-incremental-search-backward
1322 Find the next occurrence of the contents of the mini-buf‐
1323 fer. If the mini-buffer is empty, the most recent previ‐
1324 ously used search string is reinstated.
1325 history-incremental-search-forward
1327 Invert the sense of the search.
1328 magic-space
1330 Inserts a non-magical space.
1331 quoted-insert
1333 vi-quoted-insert
1334 Quote the character to insert into the minibuffer.
1335 redisplay
1337 Redisplay the command line, remaining in incremental
1338 search mode.
1339 vi-cmd-mode
1341 Select the `vicmd' keymap; the `main' keymap (insert
1342 mode) will be selected initially.
1343 In addition, the modifications that were made while in vi
1345 insert mode are merged to form a single undo event.
1346 vi-repeat-search
1348 vi-rev-repeat-search
1349 Repeat the search. The direction of the search is indi‐
1350 cated in the mini-buffer.
1351 Any character that is not bound to one of the above functions,
1353 or self-insert or self-insert-unmeta, will cause the mode to be
1354 exited. The character is then looked up and executed in the
1355 keymap in effect at that point.
1356 When called from a widget function by the zle command, the
1358 incremental search commands can take a string argument. This
1359 will be treated as a string of keys, as for arguments to the
1360 bindkey command, and used as initial input for the command. Any
1361 characters in the string which are unused by the incremental
1362 search will be silently ignored. For example,
1363 zle history-incremental-search-backward forceps
1365 will search backwards for forceps, leaving the minibuffer con‐
1367 taining the string `forceps'.
1368 history-incremental-search-forward (^S ^Xs) (unbound) (unbound)
1370 Search forward incrementally for a specified string. The search
1371 is case-insensitive if the search string does not have uppercase
1372 letters and no numeric argument was given. The string may begin
1373 with `^' to anchor the search to the beginning of the line. The
1374 functions available in the mini-buffer are the same as for his‐
1375 tory-incremental-search-backward.
1376 history-incremental-pattern-search-backward
1378 history-incremental-pattern-search-forward
1379 These widgets behave similarly to the corresponding widgets with
1380 no -pattern, but the search string typed by the user is treated
1381 as a pattern, respecting the current settings of the various
1382 options affecting pattern matching. See FILENAME GENERATION in
1383 zshexpn(1) for a description of patterns. If no numeric argu‐
1384 ment was given lowercase letters in the search string may match
1385 uppercase letters in the history. The string may begin with `^'
1386 to anchor the search to the beginning of the line.
1387 The prompt changes to indicate an invalid pattern; this may sim‐
1389 ply indicate the pattern is not yet complete.
1390 Note that only non-overlapping matches are reported, so an
1392 expression with wildcards may return fewer matches on a line
1393 than are visible by inspection.
1394 history-search-backward (ESC-P ESC-p) (unbound) (unbound)
1396 Search backward in the history for a line beginning with the
1397 first word in the buffer.
1398 If called from a function by the zle command with arguments, the
1400 first argument is taken as the string for which to search,
1401 rather than the first word in the buffer.
1402 vi-history-search-backward (unbound) (/) (unbound)
1404 Search backward in the history for a specified string. The
1405 string may begin with `^' to anchor the search to the beginning
1406 of the line.
1407 A restricted set of editing functions is available in the
1409 mini-buffer. An interrupt signal, as defined by the stty set‐
1410 ting, will stop the search. The functions available in the
1411 mini-buffer are: accept-line, backward-delete-char, vi-back‐
1412 ward-delete-char, backward-kill-word, vi-backward-kill-word,
1413 clear-screen, redisplay, quoted-insert and vi-quoted-insert.
1414 vi-cmd-mode is treated the same as accept-line, and magic-space
1416 is treated as a space. Any other character that is not bound to
1417 self-insert or self-insert-unmeta will beep and be ignored. If
1418 the function is called from vi command mode, the bindings of the
1419 current insert mode will be used.
1420 If called from a function by the zle command with arguments, the
1422 first argument is taken as the string for which to search,
1423 rather than the first word in the buffer.
1424 history-search-forward (ESC-N ESC-n) (unbound) (unbound)
1426 Search forward in the history for a line beginning with the
1427 first word in the buffer.
1428 If called from a function by the zle command with arguments, the
1430 first argument is taken as the string for which to search,
1431 rather than the first word in the buffer.
1432 vi-history-search-forward (unbound) (?) (unbound)
1434 Search forward in the history for a specified string. The
1435 string may begin with `^' to anchor the search to the beginning
1436 of the line. The functions available in the mini-buffer are the
1437 same as for vi-history-search-backward. Argument handling is
1438 also the same as for that command.
1439 infer-next-history (^X^N) (unbound) (unbound)
1441 Search in the history list for a line matching the current one
1442 and fetch the event following it.
1443 insert-last-word (ESC-_ ESC-.) (unbound) (unbound)
1445 Insert the last word from the previous history event at the cur‐
1446 sor position. If a positive numeric argument is given, insert
1447 that word from the end of the previous history event. If the
1448 argument is zero or negative insert that word from the left
1449 (zero inserts the previous command word). Repeating this com‐
1450 mand replaces the word just inserted with the last word from the
1451 history event prior to the one just used; numeric arguments can
1452 be used in the same way to pick a word from that event.
1453 When called from a shell function invoked from a user-defined
1455 widget, the command can take one to three arguments. The first
1456 argument specifies a history offset which applies to successive
1457 calls to this widget: if it is -1, the default behaviour is
1458 used, while if it is 1, successive calls will move forwards
1459 through the history. The value 0 can be used to indicate that
1460 the history line examined by the previous execution of the com‐
1461 mand will be reexamined. Note that negative numbers should be
1462 preceded by a `--' argument to avoid confusing them with
1463 options.
1464 If two arguments are given, the second specifies the word on the
1466 command line in normal array index notation (as a more natural
1467 alternative to the numeric argument). Hence 1 is the first
1468 word, and -1 (the default) is the last word.
1469 If a third argument is given, its value is ignored, but it is
1471 used to signify that the history offset is relative to the cur‐
1472 rent history line, rather than the one remembered after the pre‐
1473 vious invocations of insert-last-word.
1474 For example, the default behaviour of the command corresponds to
1476 zle insert-last-word -- -1 -1
1478 while the command
1480 zle insert-last-word -- -1 1 -
1482 always copies the first word of the line in the history immedi‐
1484 ately before the line being edited. This has the side effect
1485 that later invocations of the widget will be relative to that
1486 line.
1487 vi-repeat-search (unbound) (n) (unbound)
1489 Repeat the last vi history search.
1490 vi-rev-repeat-search (unbound) (N) (unbound)
1492 Repeat the last vi history search, but in reverse.
1493 up-line-or-history (^P ESC-[A) (k) (ESC-[A)
1495 Move up a line in the buffer, or if already at the top line,
1496 move to the previous event in the history list.
1497 vi-up-line-or-history (unbound) (-) (unbound)
1499 Move up a line in the buffer, or if already at the top line,
1500 move to the previous event in the history list. Then move to
1501 the first non-blank character on the line.
1502 up-line-or-search
1504 Move up a line in the buffer, or if already at the top line,
1505 search backward in the history for a line beginning with the
1506 first word in the buffer.
1507 If called from a function by the zle command with arguments, the
1509 first argument is taken as the string for which to search,
1510 rather than the first word in the buffer.
1511 up-history (unbound) (^P) (unbound)
1513 Move to the previous event in the history list.
1514 history-beginning-search-forward
1516 Search forward in the history for a line beginning with the cur‐
1517 rent line up to the cursor. This leaves the cursor in its orig‐
1518 inal position.
1519 set-local-history
1521 By default, history movement commands visit the imported lines
1522 as well as the local lines. This widget lets you toggle this on
1523 and off, or set it with the numeric argument. Zero for both
1524 local and imported lines and nonzero for only local lines.
1525 Modifying Text
1527 vi-add-eol (unbound) (A) (unbound)
1528 Move to the end of the line and enter insert mode.
1529 vi-add-next (unbound) (a) (unbound)
1531 Enter insert mode after the current cursor position, without
1532 changing lines.
1533 backward-delete-char (^H ^?) (unbound) (unbound)
1535 Delete the character behind the cursor.
1536 vi-backward-delete-char (unbound) (X) (^H)
1538 Delete the character behind the cursor, without changing lines.
1539 If in insert mode, this won't delete past the point where insert
1540 mode was last entered.
1541 backward-delete-word
1543 Delete the word behind the cursor.
1544 backward-kill-line
1546 Kill from the beginning of the line to the cursor position.
1547 backward-kill-word (^W ESC-^H ESC-^?) (unbound) (unbound)
1549 Kill the word behind the cursor.
1550 vi-backward-kill-word (unbound) (unbound) (^W)
1552 Kill the word behind the cursor, without going past the point
1553 where insert mode was last entered.
1554 capitalize-word (ESC-C ESC-c) (unbound) (unbound)
1556 Capitalize the current word and move past it.
1557 vi-change (unbound) (c) (unbound)
1559 Read a movement command from the keyboard, and kill from the
1560 cursor position to the endpoint of the movement. Then enter
1561 insert mode. If the command is vi-change, change the current
1562 line.
1563 For compatibility with vi, if the command is vi-forward-word or
1565 vi-forward-blank-word, the whitespace after the word is not
1566 included. If you prefer the more consistent behaviour with the
1567 whitespace included use the following key binding:
1568 bindkey -a -s cw dwi
1570 vi-change-eol (unbound) (C) (unbound)
1572 Kill to the end of the line and enter insert mode.
1573 vi-change-whole-line (unbound) (S) (unbound)
1575 Kill the current line and enter insert mode.
1576 copy-region-as-kill (ESC-W ESC-w) (unbound) (unbound)
1578 Copy the area from the cursor to the mark to the kill buffer.
1579 If called from a ZLE widget function in the form `zle
1581 copy-region-as-kill string' then string will be taken as the
1582 text to copy to the kill buffer. The cursor, the mark and the
1583 text on the command line are not used in this case.
1584 copy-prev-word (ESC-^_) (unbound) (unbound)
1586 Duplicate the word to the left of the cursor.
1587 copy-prev-shell-word
1589 Like copy-prev-word, but the word is found by using shell pars‐
1590 ing, whereas copy-prev-word looks for blanks. This makes a dif‐
1591 ference when the word is quoted and contains spaces.
1592 vi-delete (unbound) (d) (unbound)
1594 Read a movement command from the keyboard, and kill from the
1595 cursor position to the endpoint of the movement. If the command
1596 is vi-delete, kill the current line.
1597 delete-char
1599 Delete the character under the cursor.
1600 vi-delete-char (unbound) (x) (unbound)
1602 Delete the character under the cursor, without going past the
1603 end of the line.
1604 delete-word
1606 Delete the current word.
1607 down-case-word (ESC-L ESC-l) (unbound) (unbound)
1609 Convert the current word to all lowercase and move past it.
1610 vi-down-case (unbound) (gu) (unbound)
1612 Read a movement command from the keyboard, and convert all char‐
1613 acters from the cursor position to the endpoint of the movement
1614 to lowercase. If the movement command is vi-down-case, swap the
1615 case of all characters on the current line.
1616 kill-word (ESC-D ESC-d) (unbound) (unbound)
1618 Kill the current word.
1619 gosmacs-transpose-chars
1621 Exchange the two characters behind the cursor.
1622 vi-indent (unbound) (>) (unbound)
1624 Indent a number of lines.
1625 vi-insert (unbound) (i) (unbound)
1627 Enter insert mode.
1628 vi-insert-bol (unbound) (I) (unbound)
1630 Move to the first non-blank character on the line and enter
1631 insert mode.
1632 vi-join (^X^J) (J) (unbound)
1634 Join the current line with the next one.
1635 kill-line (^K) (unbound) (unbound)
1637 Kill from the cursor to the end of the line. If already on the
1638 end of the line, kill the newline character.
1639 vi-kill-line (unbound) (unbound) (^U)
1641 Kill from the cursor back to wherever insert mode was last
1642 entered.
1643 vi-kill-eol (unbound) (D) (unbound)
1645 Kill from the cursor to the end of the line.
1646 kill-region
1648 Kill from the cursor to the mark.
1649 kill-buffer (^X^K) (unbound) (unbound)
1651 Kill the entire buffer.
1652 kill-whole-line (^U) (unbound) (unbound)
1654 Kill the current line.
1655 vi-match-bracket (^X^B) (%) (unbound)
1657 Move to the bracket character (one of {}, () or []) that matches
1658 the one under the cursor. If the cursor is not on a bracket
1659 character, move forward without going past the end of the line
1660 to find one, and then go to the matching bracket.
1661 vi-open-line-above (unbound) (O) (unbound)
1663 Open a line above the cursor and enter insert mode.
1664 vi-open-line-below (unbound) (o) (unbound)
1666 Open a line below the cursor and enter insert mode.
1667 vi-oper-swap-case (unbound) (g~) (unbound)
1669 Read a movement command from the keyboard, and swap the case of
1670 all characters from the cursor position to the endpoint of the
1671 movement. If the movement command is vi-oper-swap-case, swap
1672 the case of all characters on the current line.
1673 overwrite-mode (^X^O) (unbound) (unbound)
1675 Toggle between overwrite mode and insert mode.
1676 vi-put-before (unbound) (P) (unbound)
1678 Insert the contents of the kill buffer before the cursor. If
1679 the kill buffer contains a sequence of lines (as opposed to
1680 characters), paste it above the current line.
1681 vi-put-after (unbound) (p) (unbound)
1683 Insert the contents of the kill buffer after the cursor. If the
1684 kill buffer contains a sequence of lines (as opposed to charac‐
1685 ters), paste it below the current line.
1686 put-replace-selection (unbound) (unbound) (unbound)
1688 Replace the contents of the current region or selection with the
1689 contents of the kill buffer. If the kill buffer contains a
1690 sequence of lines (as opposed to characters), the current line
1691 will be split by the pasted lines.
1692 quoted-insert (^V) (unbound) (unbound)
1694 Insert the next character typed into the buffer literally. An
1695 interrupt character will not be inserted.
1696 vi-quoted-insert (unbound) (unbound) (^Q ^V)
1698 Display a `^' at the cursor position, and insert the next char‐
1699 acter typed into the buffer literally. An interrupt character
1700 will not be inserted.
1701 quote-line (ESC-') (unbound) (unbound)
1703 Quote the current line; that is, put a `'' character at the
1704 beginning and the end, and convert all `'' characters to `'\'''.
1705 quote-region (ESC-") (unbound) (unbound)
1707 Quote the region from the cursor to the mark.
1708 vi-replace (unbound) (R) (unbound)
1710 Enter overwrite mode.
1711 vi-repeat-change (unbound) (.) (unbound)
1713 Repeat the last vi mode text modification. If a count was used
1714 with the modification, it is remembered. If a count is given to
1715 this command, it overrides the remembered count, and is remem‐
1716 bered for future uses of this command. The cut buffer specifi‐
1717 cation is similarly remembered.
1718 vi-replace-chars (unbound) (r) (unbound)
1720 Replace the character under the cursor with a character read
1721 from the keyboard.
1722 self-insert (printable characters) (unbound) (printable characters and
1724 some control characters)
1725 Insert a character into the buffer at the cursor position.
1726 self-insert-unmeta (ESC-^I ESC-^J ESC-^M) (unbound) (unbound)
1728 Insert a character into the buffer after stripping the meta bit
1729 and converting ^M to ^J.
1730 vi-substitute (unbound) (s) (unbound)
1732 Substitute the next character(s).
1733 vi-swap-case (unbound) (~) (unbound)
1735 Swap the case of the character under the cursor and move past
1736 it.
1737 transpose-chars (^T) (unbound) (unbound)
1739 Exchange the two characters to the left of the cursor if at end
1740 of line, else exchange the character under the cursor with the
1741 character to the left.
1742 transpose-words (ESC-T ESC-t) (unbound) (unbound)
1744 Exchange the current word with the one before it.
1745 With a positive numeric argument N, the word around the cursor,
1747 or following it if the cursor is between words, is transposed
1748 with the preceding N words. The cursor is put at the end of the
1749 resulting group of words.
1750 With a negative numeric argument -N, the effect is the same as
1752 using a positive argument N except that the original cursor
1753 position is retained, regardless of how the words are rear‐
1754 ranged.
1755 vi-unindent (unbound) (<) (unbound)
1757 Unindent a number of lines.
1758 vi-up-case (unbound) (gU) (unbound)
1760 Read a movement command from the keyboard, and convert all char‐
1761 acters from the cursor position to the endpoint of the movement
1762 to lowercase. If the movement command is vi-up-case, swap the
1763 case of all characters on the current line.
1764 up-case-word (ESC-U ESC-u) (unbound) (unbound)
1766 Convert the current word to all caps and move past it.
1767 yank (^Y) (unbound) (unbound)
1769 Insert the contents of the kill buffer at the cursor position.
1770 yank-pop (ESC-y) (unbound) (unbound)
1772 Remove the text just yanked, rotate the kill-ring (the history
1773 of previously killed text) and yank the new top. Only works
1774 following yank, vi-put-before, vi-put-after or yank-pop.
1775 vi-yank (unbound) (y) (unbound)
1777 Read a movement command from the keyboard, and copy the region
1778 from the cursor position to the endpoint of the movement into
1779 the kill buffer. If the command is vi-yank, copy the current
1780 line.
1781 vi-yank-whole-line (unbound) (Y) (unbound)
1783 Copy the current line into the kill buffer.
1784 vi-yank-eol
1786 Copy the region from the cursor position to the end of the line
1787 into the kill buffer. Arguably, this is what Y should do in vi,
1788 but it isn't what it actually does.
1789 Arguments
1791 digit-argument (ESC-0..ESC-9) (1-9) (unbound)
1792 Start a new numeric argument, or add to the current one. See
1793 also vi-digit-or-beginning-of-line. This only works if bound to
1794 a key sequence ending in a decimal digit.
1795 Inside a widget function, a call to this function treats the
1797 last key of the key sequence which called the widget as the
1798 digit.
1799 neg-argument (ESC--) (unbound) (unbound)
1801 Changes the sign of the following argument.
1802 universal-argument
1804 Multiply the argument of the next command by 4. Alternatively,
1805 if this command is followed by an integer (positive or nega‐
1806 tive), use that as the argument for the next command. Thus dig‐
1807 its cannot be repeated using this command. For example, if this
1808 command occurs twice, followed immediately by forward-char, move
1809 forward sixteen spaces; if instead it is followed by -2, then
1810 forward-char, move backward two spaces.
1811 Inside a widget function, if passed an argument, i.e. `zle uni‐
1813 versal-argument num', the numeric argument will be set to num;
1814 this is equivalent to `NUMERIC=num'.
1815 argument-base
1817 Use the existing numeric argument as a numeric base, which must
1818 be in the range 2 to 36 inclusive. Subsequent use of
1819 digit-argument and universal-argument will input a new numeric
1820 argument in the given base. The usual hexadecimal convention is
1821 used: the letter a or A corresponds to 10, and so on. Arguments
1822 in bases requiring digits from 10 upwards are more conveniently
1823 input with universal-argument, since ESC-a etc. are not usually
1824 bound to digit-argument.
1825 The function can be used with a command argument inside a
1827 user-defined widget. The following code sets the base to 16 and
1828 lets the user input a hexadecimal argument until a key out of
1829 the digit range is typed:
1830 zle argument-base 16
1832 zle universal-argument
1833 Completion
1835 accept-and-menu-complete
1836 In a menu completion, insert the current completion into the
1837 buffer, and advance to the next possible completion.
1838 complete-word
1840 Attempt completion on the current word.
1841 delete-char-or-list (^D) (unbound) (unbound)
1843 Delete the character under the cursor. If the cursor is at the
1844 end of the line, list possible completions for the current word.
1845 expand-cmd-path
1847 Expand the current command to its full pathname.
1848 expand-or-complete (TAB) (unbound) (TAB)
1850 Attempt shell expansion on the current word. If that fails,
1851 attempt completion.
1852 expand-or-complete-prefix
1854 Attempt shell expansion on the current word up to cursor.
1855 expand-history (ESC-space ESC-!) (unbound) (unbound)
1857 Perform history expansion on the edit buffer.
1858 expand-word (^X*) (unbound) (unbound)
1860 Attempt shell expansion on the current word.
1861 list-choices (ESC-^D) (^D =) (^D)
1863 List possible completions for the current word.
1864 list-expand (^Xg ^XG) (^G) (^G)
1866 List the expansion of the current word.
1867 magic-space
1869 Perform history expansion and insert a space into the buffer.
1870 This is intended to be bound to space.
1871 menu-complete
1873 Like complete-word, except that menu completion is used. See
1874 the MENU_COMPLETE option.
1875 menu-expand-or-complete
1877 Like expand-or-complete, except that menu completion is used.
1878 reverse-menu-complete
1880 Perform menu completion, like menu-complete, except that if a
1881 menu completion is already in progress, move to the previous
1882 completion rather than the next.
1883 end-of-list
1885 When a previous completion displayed a list below the prompt,
1886 this widget can be used to move the prompt below the list.
1887 Miscellaneous
1889 accept-and-hold (ESC-A ESC-a) (unbound) (unbound)
1890 Push the contents of the buffer on the buffer stack and execute
1891 it.
1892 accept-and-infer-next-history
1894 Execute the contents of the buffer. Then search the history
1895 list for a line matching the current one and push the event fol‐
1896 lowing onto the buffer stack.
1897 accept-line (^J ^M) (^J ^M) (^J ^M)
1899 Finish editing the buffer. Normally this causes the buffer to
1900 be executed as a shell command.
1901 accept-line-and-down-history (^O) (unbound) (unbound)
1903 Execute the current line, and push the next history event on the
1904 buffer stack.
1905 auto-suffix-remove
1907 If the previous action added a suffix (space, slash, etc.) to
1908 the word on the command line, remove it. Otherwise do nothing.
1909 Removing the suffix ends any active menu completion or menu
1910 selection.
1911 This widget is intended to be called from user-defined widgets
1913 to enforce a desired suffix-removal behavior.
1914 auto-suffix-retain
1916 If the previous action added a suffix (space, slash, etc.) to
1917 the word on the command line, force it to be preserved. Other‐
1918 wise do nothing. Retaining the suffix ends any active menu com‐
1919 pletion or menu selection.
1920 This widget is intended to be called from user-defined widgets
1922 to enforce a desired suffix-preservation behavior.
1923 beep Beep, unless the BEEP option is unset.
1925 bracketed-paste
1927 This widget is invoked when text is pasted to the terminal emu‐
1928 lator. It is not intended to be bound to actual keys but instead
1929 to the special sequence generated by the terminal emulator when
1930 text is pasted.
1931 When invoked interactively, the pasted text is inserted to the
1933 buffer and placed in the cutbuffer. If a numeric argument is
1934 given, shell quoting will be applied to the pasted text before
1935 it is inserted.
1936 When a named buffer is specified with vi-set-buffer ("x), the
1938 pasted text is stored in that named buffer but not inserted.
1939 When called from a widget function as `bracketed-paste name`,
1941 the pasted text is assigned to the variable name and no other
1942 processing is done.
1943 See also the zle_bracketed_paste parameter.
1945 vi-cmd-mode (^X^V) (unbound) (^[)
1947 Enter command mode; that is, select the `vicmd' keymap. Yes,
1948 this is bound by default in emacs mode.
1949 vi-caps-lock-panic
1951 Hang until any lowercase key is pressed. This is for vi users
1952 without the mental capacity to keep track of their caps lock key
1953 (like the author).
1954 clear-screen (^L ESC-^L) (^L) (^L)
1956 Clear the screen and redraw the prompt.
1957 deactivate-region
1959 Make the current region inactive. This disables vim-style visual
1960 selection mode if it is active.
1961 describe-key-briefly
1963 Reads a key sequence, then prints the function bound to that
1964 sequence.
1965 exchange-point-and-mark (^X^X) (unbound) (unbound)
1967 Exchange the cursor position (point) with the position of the
1968 mark. Unless a negative numeric argument is given, the region
1969 between point and mark is activated so that it can be high‐
1970 lighted. If a zero numeric argument is given, the region is
1971 activated but point and mark are not swapped.
1972 execute-named-cmd (ESC-x) (:) (unbound)
1974 Read the name of an editor command and execute it. Aliasing
1975 this widget with `zle -A' or replacing it with `zle -N' has no
1976 effect when interpreting key bindings, but `zle exe‐
1977 cute-named-cmd' will invoke such an alias or replacement.
1978 A restricted set of editing functions is available in the
1980 mini-buffer. Keys are looked up in the special command keymap,
1981 and if not found there in the main keymap. An interrupt signal,
1982 as defined by the stty setting, will abort the function. Note
1983 that the following always perform the same task within the exe‐
1984 cuted-named-cmd environment and cannot be replaced by user
1985 defined widgets, nor can the set of functions be extended. The
1986 allowed functions are: backward-delete-char, vi-back‐
1987 ward-delete-char, clear-screen, redisplay, quoted-insert,
1988 vi-quoted-insert, backward-kill-word, vi-backward-kill-word,
1989 kill-whole-line, vi-kill-line, backward-kill-line, list-choices,
1990 delete-char-or-list, complete-word, accept-line, expand-or-com‐
1991 plete and expand-or-complete-prefix.
1992 kill-region kills the last word, and vi-cmd-mode is treated the
1994 same as accept-line. The space and tab characters, if not bound
1995 to one of these functions, will complete the name and then list
1996 the possibilities if the AUTO_LIST option is set. Any other
1997 character that is not bound to self-insert or self-insert-unmeta
1998 will beep and be ignored. The bindings of the current insert
1999 mode will be used.
2000 Currently this command may not be redefined or called by name.
2002 execute-last-named-cmd (ESC-z) (unbound) (unbound)
2004 Redo the last function executed with execute-named-cmd.
2005 Like execute-named-cmd, this command may not be redefined, but
2007 it may be called by name.
2008 get-line (ESC-G ESC-g) (unbound) (unbound)
2010 Pop the top line off the buffer stack and insert it at the cur‐
2011 sor position.
2012 pound-insert (unbound) (#) (unbound)
2014 If there is no # character at the beginning of the buffer, add
2015 one to the beginning of each line. If there is one, remove a #
2016 from each line that has one. In either case, accept the current
2017 line. The INTERACTIVE_COMMENTS option must be set for this to
2018 have any usefulness.
2019 vi-pound-insert
2021 If there is no # character at the beginning of the current line,
2022 add one. If there is one, remove it. The INTERACTIVE_COMMENTS
2023 option must be set for this to have any usefulness.
2024 push-input
2026 Push the entire current multiline construct onto the buffer
2027 stack and return to the top-level (PS1) prompt. If the current
2028 parser construct is only a single line, this is exactly like
2029 push-line. Next time the editor starts up or is popped with
2030 get-line, the construct will be popped off the top of the buffer
2031 stack and loaded into the editing buffer.
2032 push-line (^Q ESC-Q ESC-q) (unbound) (unbound)
2034 Push the current buffer onto the buffer stack and clear the buf‐
2035 fer. Next time the editor starts up, the buffer will be popped
2036 off the top of the buffer stack and loaded into the editing buf‐
2037 fer.
2038 push-line-or-edit
2040 At the top-level (PS1) prompt, equivalent to push-line. At a
2041 secondary (PS2) prompt, move the entire current multiline con‐
2042 struct into the editor buffer. The latter is equivalent to
2043 push-input followed by get-line.
2044 read-command
2046 Only useful from a user-defined widget. A keystroke is read
2047 just as in normal operation, but instead of the command being
2048 executed the name of the command that would be executed is
2049 stored in the shell parameter REPLY. This can be used as the
2050 argument of a future zle command. If the key sequence is not
2051 bound, status 1 is returned; typically, however, REPLY is set to
2052 undefined-key to indicate a useless key sequence.
2053 recursive-edit
2055 Only useful from a user-defined widget. At this point in the
2056 function, the editor regains control until one of the standard
2057 widgets which would normally cause zle to exit (typically an
2058 accept-line caused by hitting the return key) is executed.
2059 Instead, control returns to the user-defined widget. The status
2060 returned is non-zero if the return was caused by an error, but
2061 the function still continues executing and hence may tidy up.
2062 This makes it safe for the user-defined widget to alter the com‐
2063 mand line or key bindings temporarily.
2064 The following widget, caps-lock, serves as an example.
2066 self-insert-ucase() {
2068 LBUFFER+=${(U)KEYS[-1]}
2069 }
2070 integer stat
2072 zle -N self-insert self-insert-ucase
2074 zle -A caps-lock save-caps-lock
2075 zle -A accept-line caps-lock
2076 zle recursive-edit
2078 stat=$?
2079 zle -A .self-insert self-insert
2081 zle -A save-caps-lock caps-lock
2082 zle -D save-caps-lock
2083 (( stat )) && zle send-break
2085 return $stat
2087 This causes typed letters to be inserted capitalised until
2089 either accept-line (i.e. typically the return key) is typed or
2090 the caps-lock widget is invoked again; the later is handled by
2091 saving the old definition of caps-lock as save-caps-lock and
2092 then rebinding it to invoke accept-line. Note that an error
2093 from the recursive edit is detected as a non-zero return status
2094 and propagated by using the send-break widget.
2095 redisplay (unbound) (^R) (^R)
2097 Redisplays the edit buffer.
2098 reset-prompt (unbound) (unbound) (unbound)
2100 Force the prompts on both the left and right of the screen to be
2101 re-expanded, then redisplay the edit buffer. This reflects
2102 changes both to the prompt variables themselves and changes in
2103 the expansion of the values (for example, changes in time or
2104 directory, or changes to the value of variables referred to by
2105 the prompt).
2106 Otherwise, the prompt is only expanded each time zle starts, and
2108 when the display as been interrupted by output from another part
2109 of the shell (such as a job notification) which causes the com‐
2110 mand line to be reprinted.
2111 send-break (^G ESC-^G) (unbound) (unbound)
2113 Abort the current editor function, e.g. execute-named-command,
2114 or the editor itself, e.g. if you are in vared. Otherwise abort
2115 the parsing of the current line; in this case the aborted line
2116 is available in the shell variable ZLE_LINE_ABORTED. If the
2117 editor is aborted from within vared, the variable
2118 ZLE_VARED_ABORTED is set.
2119 run-help (ESC-H ESC-h) (unbound) (unbound)
2121 Push the buffer onto the buffer stack, and execute the command
2122 `run-help cmd', where cmd is the current command. run-help is
2123 normally aliased to man.
2124 vi-set-buffer (unbound) (") (unbound)
2126 Specify a buffer to be used in the following command. There are
2127 37 buffers that can be specified: the 26 `named' buffers "a to
2128 "z, the `yank' buffer "0, the nine `queued' buffers "1 to "9 and
2129 the `black hole' buffer "_. The named buffers can also be spec‐
2130 ified as "A to "Z.
2131 When a buffer is specified for a cut, change or yank command,
2133 the text concerned replaces the previous contents of the speci‐
2134 fied buffer. If a named buffer is specified using a capital, the
2135 newly cut text is appended to the buffer instead of overwriting
2136 it. When using the "_ buffer, nothing happens. This can be use‐
2137 ful for deleting text without affecting any buffers.
2138 If no buffer is specified for a cut or change command, "1 is
2140 used, and the contents of "1 to "8 are each shifted along one
2141 buffer; the contents of "9 is lost. If no buffer is specified
2142 for a yank command, "0 is used. Finally, a paste command without
2143 a specified buffer will paste the text from the most recent com‐
2144 mand regardless of any buffer that might have been used with
2145 that command.
2146 When called from a widget function by the zle command, the buf‐
2148 fer can optionally be specified with an argument. For example,
2149 zle vi-set-buffer A
2151 vi-set-mark (unbound) (m) (unbound)
2153 Set the specified mark at the cursor position.
2154 set-mark-command (^@) (unbound) (unbound)
2156 Set the mark at the cursor position. If called with a negative
2157 numeric argument, do not set the mark but deactivate the region
2158 so that it is no longer highlighted (it is still usable for
2159 other purposes). Otherwise the region is marked as active.
2160 spell-word (ESC-$ ESC-S ESC-s) (unbound) (unbound)
2162 Attempt spelling correction on the current word.
2163 split-undo
2165 Breaks the undo sequence at the current change. This is useful
2166 in vi mode as changes made in insert mode are coalesced on
2167 entering command mode. Similarly, undo will normally revert as
2168 one all the changes made by a user-defined widget.
2169 undefined-key
2171 This command is executed when a key sequence that is not bound
2172 to any command is typed. By default it beeps.
2173 undo (^_ ^Xu ^X^U) (u) (unbound)
2175 Incrementally undo the last text modification. When called from
2176 a user-defined widget, takes an optional argument indicating a
2177 previous state of the undo history as returned by the
2178 UNDO_CHANGE_NO variable; modifications are undone until that
2179 state is reached, subject to any limit imposed by the
2180 UNDO_LIMIT_NO variable.
2181 Note that when invoked from vi command mode, the full prior
2183 change made in insert mode is reverted, the changes having been
2184 merged when command mode was selected.
2185 redo (unbound) (^R) (unbound)
2187 Incrementally redo undone text modifications.
2188 vi-undo-change (unbound) (unbound) (unbound)
2190 Undo the last text modification. If repeated, redo the modifi‐
2191 cation.
2192 visual-mode (unbound) (v) (unbound)
2194 Toggle vim-style visual selection mode. If line-wise visual mode
2195 is currently enabled then it is changed to being character-wise.
2196 If used following an operator, it forces the subsequent movement
2197 command to be treated as a character-wise movement.
2198 visual-line-mode (unbound) (V) (unbound)
2200 Toggle vim-style line-wise visual selection mode. If charac‐
2201 ter-wise visual mode is currently enabled then it is changed to
2202 being line-wise. If used following an operator, it forces the
2203 subsequent movement command to be treated as a line-wise move‐
2204 ment.
2205 what-cursor-position (^X=) (ga) (unbound)
2207 Print the character under the cursor, its code as an octal, dec‐
2208 imal and hexadecimal number, the current cursor position within
2209 the buffer and the column of the cursor in the current line.
2210 where-is
2212 Read the name of an editor command and print the listing of key
2213 sequences that invoke the specified command. A restricted set
2214 of editing functions is available in the mini-buffer. Keys are
2215 looked up in the special command keymap, and if not found there
2216 in the main keymap.
2217 which-command (ESC-?) (unbound) (unbound)
2219 Push the buffer onto the buffer stack, and execute the command
2220 `which-command cmd'. where cmd is the current command.
2221 which-command is normally aliased to whence.
2222 vi-digit-or-beginning-of-line (unbound) (0) (unbound)
2224 If the last command executed was a digit as part of an argument,
2225 continue the argument. Otherwise, execute vi-beginning-of-line.
2226 Text Objects
2228 Text objects are commands that can be used to select a block of text
2229 according to some criteria. They are a feature of the vim text editor
2230 and so are primarily intended for use with vi operators or from visual
2231 selection mode. However, they can also be used from vi-insert or emacs
2232 mode. Key bindings listed below apply to the viopp and visual keymaps.
2233 select-a-blank-word (aW)
2235 Select a word including adjacent blanks, where a word is defined
2236 as a series of non-blank characters. With a numeric argument,
2237 multiple words will be selected.
2238 select-a-shell-word (aa)
2240 Select the current command argument applying the normal rules
2241 for quoting.
2242 select-a-word (aw)
2244 Select a word including adjacent blanks, using the normal
2245 vi-style word definition. With a numeric argument, multiple
2246 words will be selected.
2247 select-in-blank-word (iW)
2249 Select a word, where a word is defined as a series of non-blank
2250 characters. With a numeric argument, multiple words will be
2251 selected.
2252 select-in-shell-word (ia)
2254 Select the current command argument applying the normal rules
2255 for quoting. If the argument begins and ends with matching quote
2256 characters, these are not included in the selection.
2257 select-in-word (iw)
2259 Select a word, using the normal vi-style word definition. With a
2260 numeric argument, multiple words will be selected.
2261
2263 The line editor has the ability to highlight characters or regions of
2264 the line that have a particular significance. This is controlled by
2265 the array parameter zle_highlight, if it has been set by the user.
2266 If the parameter contains the single entry none all highlighting is
2268 turned off. Note the parameter is still expected to be an array.
2269 Otherwise each entry of the array should consist of a word indicating a
2271 context for highlighting, then a colon, then a comma-separated list of
2272 the types of highlighting to apply in that context.
2273 The contexts available for highlighting are the following:
2275 default
2277 Any text within the command line not affected by any other high‐
2278 lighting. Text outside the editable area of the command line is
2279 not affected.
2280 isearch
2282 When one of the incremental history search widgets is active,
2283 the area of the command line matched by the search string or
2284 pattern.
2285 region The currently selected text. In emacs terminology, this is
2287 referred to as the region and is bounded by the cursor (point)
2288 and the mark. The region is only highlighted if it is active,
2289 which is the case after the mark is modified with set-mark-com‐
2290 mand or exchange-point-and-mark. Note that whether or not the
2291 region is active has no effect on its use within emacs style
2292 widgets, it simply determines whether it is highlighted. In vi
2293 mode, the region corresponds to selected text in visual mode.
2294 special
2296 Individual characters that have no direct printable representa‐
2297 tion but are shown in a special manner by the line editor.
2298 These characters are described below.
2299 suffix This context is used in completion for characters that are
2301 marked as suffixes that will be removed if the completion ends
2302 at that point, the most obvious example being a slash (/) after
2303 a directory name. Note that suffix removal is configurable; the
2304 circumstances under which the suffix will be removed may differ
2305 for different completions.
2306 paste Following a command to paste text, the characters that were
2308 inserted.
2309 When region_highlight is set, the contexts that describe a region --
2311 isearch, region, suffix, and paste -- are applied first, then
2312 region_highlight is applied, then the remaining zle_highlight contexts
2313 are applied. If a particular character is affected by multiple speci‐
2314 fications, the last specification wins.
2315 zle_highlight may contain additional fields for controlling how termi‐
2317 nal sequences to change colours are output. Each of the following is
2318 followed by a colon and a string in the same form as for key bindings.
2319 This will not be necessary for the vast majority of terminals as the
2320 defaults shown in parentheses are widely used.
2321 fg_start_code (\e[3)
2323 The start of the escape sequence for the foreground colour.
2324 This is followed by an ASCII digit representing the colour.
2325 fg_default_code (9)
2327 The number to use instead of the colour to reset the default
2328 foreground colour.
2329 fg_end_code (m)
2331 The end of the escape sequence for the foreground colour.
2332 bg_start_code (\e[4)
2334 The start of the escape sequence for the background colour.
2335 This is followed by an ASCII digit representing the colour.
2336 bg_default_code (9)
2338 The number to use instead of the colour to reset the default
2339 background colour.
2340 bg_end_code (m)
2342 The end of the escape sequence for the background colour.
2343 The available types of highlighting are the following. Note that not
2345 all types of highlighting are available on all terminals:
2346 none No highlighting is applied to the given context. It is not use‐
2348 ful for this to appear with other types of highlighting; it is
2349 used to override a default.
2350 fg=colour
2352 The foreground colour should be set to colour, a decimal integer
2353 or the name of one of the eight most widely-supported colours.
2354 Not all terminals support this and, of those that do, not all
2356 provide facilities to test the support, hence the user should
2357 decide based on the terminal type. Most terminals support the
2358 colours black, red, green, yellow, blue, magenta, cyan and
2359 white, which can be set by name. In addition. default may be
2360 used to set the terminal's default foreground colour. Abbrevia‐
2361 tions are allowed; b or bl selects black. Some terminals may
2362 generate additional colours if the bold attribute is also
2363 present.
2364 On recent terminals and on systems with an up-to-date terminal
2366 database the number of colours supported may be tested by the
2367 command `echotc Co'; if this succeeds, it indicates a limit on
2368 the number of colours which will be enforced by the line editor.
2369 The number of colours is in any case limited to 256 (i.e. the
2370 range 0 to 255).
2371 Colour is also known as color.
2373 bg=colour
2375 The background colour should be set to colour. This works simi‐
2376 larly to the foreground colour, except the background is not
2377 usually affected by the bold attribute.
2378 bold The characters in the given context are shown in a bold font.
2380 Not all terminals distinguish bold fonts.
2381 standout
2383 The characters in the given context are shown in the terminal's
2384 standout mode. The actual effect is specific to the terminal;
2385 on many terminals it is inverse video. On some such terminals,
2386 where the cursor does not blink it appears with standout mode
2387 negated, making it less than clear where the cursor actually is.
2388 On such terminals one of the other effects may be preferable for
2389 highlighting the region and matched search string.
2390 underline
2392 The characters in the given context are shown underlined. Some
2393 terminals show the foreground in a different colour instead; in
2394 this case whitespace will not be highlighted.
2395 The characters described above as `special' are as follows. The for‐
2397 matting described here is used irrespective of whether the characters
2398 are highlighted:
2399 ASCII control characters
2401 Control characters in the ASCII range are shown as `^' followed
2402 by the base character.
2403 Unprintable multibyte characters
2405 This item applies to control characters not in the ASCII range,
2406 plus other characters as follows. If the MULTIBYTE option is in
2407 effect, multibyte characters not in the ASCII character set that
2408 are reported as having zero width are treated as combining char‐
2409 acters when the option COMBINING_CHARS is on. If the option is
2410 off, or if a character appears where a combining character is
2411 not valid, the character is treated as unprintable.
2412 Unprintable multibyte characters are shown as a hexadecimal num‐
2414 ber between angle brackets. The number is the code point of the
2415 character in the wide character set; this may or may not be Uni‐
2416 code, depending on the operating system.
2417 Invalid multibyte characters
2419 If the MULTIBYTE option is in effect, any sequence of one or
2420 more bytes that does not form a valid character in the current
2421 character set is treated as a series of bytes each shown as a
2422 special character. This case can be distinguished from other
2423 unprintable characters as the bytes are represented as two hexa‐
2424 decimal digits between angle brackets, as distinct from the four
2425 or eight digits that are used for unprintable characters that
2426 are nonetheless valid in the current character set.
2427 Not all systems support this: for it to work, the system's rep‐
2429 resentation of wide characters must be code values from the Uni‐
2430 versal Character Set, as defined by IS0 10646 (also known as
2431 Unicode).
2432 Wrapped double-width characters
2434 When a double-width character appears in the final column of a
2435 line, it is instead shown on the next line. The empty space left
2436 in the original position is highlighted as a special character.
2437 If zle_highlight is not set or no value applies to a particular con‐
2439 text, the defaults applied are equivalent to
2440 zle_highlight=(region:standout special:standout
2442 suffix:bold isearch:underline paste:standout)
2443 i.e. both the region and special characters are shown in standout mode.
2445 Within widgets, arbitrary regions may be highlighted by setting the
2447 special array parameter region_highlight; see above.
2448zsh 5.5.1 April 16, 2018 ZSHZLE(1)