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) is enabled by default; consult this reference for more
28 information. Irascible conservatives will wish to know that all high‐
29 lighting may be disabled by the following setting:
30 zle_highlight=(none)
32
34 A keymap in ZLE contains a set of bindings between key sequences and
35 ZLE commands. The empty key sequence cannot be bound.
36 There can be any number of keymaps at any time, and each keymap has one
38 or more names. If all of a keymap's names are deleted, it disappears.
39 bindkey can be used to manipulate keymap names.
40 Initially, there are six keymaps:
42 emacs EMACS emulation
44 viins vi emulation - insert mode
45 vicmd vi emulation - command mode
46 isearch
47 incremental search mode
48 command
49 read a command name
50 .safe fallback keymap
51 The `.safe' keymap is special. It can never be altered, and the name
53 can never be removed. However, it can be linked to other names, which
54 can be removed. In the future other special keymaps may be added;
55 users should avoid using names beginning with `.' for their own
56 keymaps.
57 In addition to these names, either `emacs' or `viins' is also linked to
59 the name `main'. If one of the VISUAL or EDITOR environment variables
60 contain the string `vi' when the shell starts up then it will be
61 `viins', otherwise it will be `emacs'. bindkey's -e and -v options
62 provide a convenient way to override this default choice.
63 When the editor starts up, it will select the `main' keymap. If that
65 keymap doesn't exist, it will use `.safe' instead.
66 In the `.safe' keymap, each single key is bound to self-insert, except
68 for ^J (line feed) and ^M (return) which are bound to accept-line.
69 This is deliberately not pleasant to use; if you are using it, it means
70 you deleted the main keymap, and you should put it back.
71 Reading Commands
73 When ZLE is reading a command from the terminal, it may read a sequence
74 that is bound to some command and is also a prefix of a longer bound
75 string. In this case ZLE will wait a certain time to see if more char‐
76 acters are typed, and if not (or they don't match any longer string) it
77 will execute the binding. This timeout is defined by the KEYTIMEOUT
78 parameter; its default is 0.4 sec. There is no timeout if the prefix
79 string is not itself bound to a command.
80 The key timeout is also applied when ZLE is reading the bytes from a
82 multibyte character string when it is in the appropriate mode. (This
83 requires that the shell was compiled with multibyte mode enabled; typi‐
84 cally also the locale has characters with the UTF-8 encoding, although
85 any multibyte encoding known to the operating system is supported.) If
86 the second or a subsequent byte is not read within the timeout period,
87 the shell acts as if ? were typed and resets the input state.
88 As well as ZLE commands, key sequences can be bound to other strings,
90 by using `bindkey -s'. When such a sequence is read, the replacement
91 string is pushed back as input, and the command reading process starts
92 again using these fake keystrokes. This input can itself invoke fur‐
93 ther replacement strings, but in order to detect loops the process will
94 be stopped if there are twenty such replacements without a real command
95 being read.
96 A key sequence typed by the user can be turned into a command name for
98 use in user-defined widgets with the read-command widget, described
99 below.
100
102 The ZLE module contains three related builtin commands. The bindkey
103 command manipulates keymaps and key bindings; the vared command invokes
104 ZLE on the value of a shell parameter; and the zle command manipulates
105 editing widgets and allows command line access to ZLE commands from
106 within shell functions.
107 bindkey [ options ] -l
109 bindkey [ options ] -d
110 bindkey [ options ] -D keymap ...
111 bindkey [ options ] -A old-keymap new-keymap
112 bindkey [ options ] -N new-keymap [ old-keymap ]
113 bindkey [ options ] -m
114 bindkey [ options ] -r in-string ...
115 bindkey [ options ] -s in-string out-string ...
116 bindkey [ options ] in-string command ...
117 bindkey [ options ] [ in-string ]
118 bindkey's options can be divided into three categories: keymap
119 selection, operation selection, and others. The keymap selec‐
120 tion options are:
121 -e Selects keymap `emacs', and also links it to `main'.
123 -v Selects keymap `viins', and also links it to `main'.
125 -a Selects keymap `vicmd'.
127 -M keymap
129 The keymap specifies a keymap name.
130 If a keymap selection is required and none of the options above
132 are used, the `main' keymap is used. Some operations do not
133 permit a keymap to be selected, namely:
134 -l List all existing keymap names. If the -L option is also
136 used, list in the form of bindkey commands to create the
137 keymaps.
138 -d Delete all existing keymaps and reset to the default
140 state.
141 -D keymap ...
143 Delete the named keymaps.
144 -A old-keymap new-keymap
146 Make the new-keymap name an alias for old-keymap, so that
147 both names refer to the same keymap. The names have
148 equal standing; if either is deleted, the other remains.
149 If there is already a keymap with the new-keymap name, it
150 is deleted.
151 -N new-keymap [ old-keymap ]
153 Create a new keymap, named new-keymap. If a keymap
154 already has that name, it is deleted. If an old-keymap
155 name is given, the new keymap is initialized to be a
156 duplicate of it, otherwise the new keymap will be empty.
157 To use a newly created keymap, it should be linked to main.
159 Hence the sequence of commands to create and use a new keymap
160 `mymap' initialized from the emacs keymap (which remains
161 unchanged) is:
162 bindkey -N mymap emacs
164 bindkey -A mymap main
165 Note that while `bindkey -A newmap main' will work when newmap
167 is emacs or viins, it will not work for vicmd, as switching from
168 vi insert to command mode becomes impossible.
169 The following operations act on the `main' keymap if no keymap
171 selection option was given:
172 -m Add the built-in set of meta-key bindings to the selected
174 keymap. Only keys that are unbound or bound to
175 self-insert are affected.
176 -r in-string ...
178 Unbind the specified in-strings in the selected keymap.
179 This is exactly equivalent to binding the strings to
180 undefined-key.
181 When -R is also used, interpret the in-strings as ranges.
183 When -p is also used, the in-strings specify prefixes.
185 Any binding that has the given in-string as a prefix, not
186 including the binding for the in-string itself, if any,
187 will be removed. For example,
188 bindkey -rpM viins '^['
190 will remove all bindings in the vi-insert keymap begin‐
192 ning with an escape character (probably cursor keys), but
193 leave the binding for the escape character itself (proba‐
194 bly vi-cmd-mode). This is incompatible with the option
195 -R.
196 -s in-string out-string ...
198 Bind each in-string to each out-string. When in-string
199 is typed, out-string will be pushed back and treated as
200 input to the line editor. When -R is also used, inter‐
201 pret the in-strings as ranges.
202 in-string command ...
204 Bind each in-string to each command. When -R is used,
205 interpret the in-strings as ranges.
206 [ in-string ]
208 List key bindings. If an in-string is specified, the
209 binding of that string in the selected keymap is dis‐
210 played. Otherwise, all key bindings in the selected
211 keymap are displayed. (As a special case, if the -e or
212 -v option is used alone, the keymap is not displayed -
213 the implicit linking of keymaps is the only thing that
214 happens.)
215 When the option -p is used, the in-string must be
217 present. The listing shows all bindings which have the
218 given key sequence as a prefix, not including any bind‐
219 ings for the key sequence itself.
220 When the -L option is used, the list is in the form of
222 bindkey commands to create the key bindings.
223 When the -R option is used as noted above, a valid range consists of
225 two characters, with an optional `-' between them. All characters
226 between the two specified, inclusive, are bound as specified.
227 For either in-string or out-string, the following escape sequences are
229 recognised:
230 \a bell character
232 \b backspace
233 \e, \E escape
234 \f form feed
235 \n linefeed (newline)
236 \r carriage return
237 \t horizontal tab
238 \v vertical tab
239 \NNN character code in octal
240 \xNN character code in hexadecimal
241 \M[-]X character with meta bit set
242 \C[-]X control character
243 ^X control character
244 In all other cases, `\' escapes the following character. Delete is
246 written as `^?'. Note that `\M^?' and `^\M?' are not the same, and
247 that (unlike emacs), the bindings `\M-X' and `\eX' are entirely dis‐
248 tinct, although they are initialized to the same bindings by `bindkey
249 -m'.
250 vared [ -Aache ] [ -p prompt ] [ -r rprompt ]
252 [ -M main-keymap ] [ -m vicmd-keymap ]
253 [ -t tty ] name
254 The value of the parameter name is loaded into the edit buffer,
255 and the line editor is invoked. When the editor exits, name is
256 set to the string value returned by the editor. When the -c
257 flag is given, the parameter is created if it doesn't already
258 exist. The -a flag may be given with -c to create an array
259 parameter, or the -A flag to create an associative array. If
260 the type of an existing parameter does not match the type to be
261 created, the parameter is unset and recreated.
262 If an array or array slice is being edited, separator characters
264 as defined in $IFS will be shown quoted with a backslash, as
265 will backslashes themselves. Conversely, when the edited text
266 is split into an array, a backslash quotes an immediately fol‐
267 lowing separator character or backslash; no other special han‐
268 dling of backslashes, or any handling of quotes, is performed.
269 Individual elements of existing array or associative array
271 parameters may be edited by using subscript syntax on name. New
272 elements are created automatically, even without -c.
273 If the -p flag is given, the following string will be taken as
275 the prompt to display at the left. If the -r flag is given, the
276 following string gives the prompt to display at the right. If
277 the -h flag is specified, the history can be accessed from ZLE.
278 If the -e flag is given, typing ^D (Control-D) on an empty line
279 causes vared to exit immediately with a non-zero return value.
280 The -M option gives a keymap to link to the main keymap during
282 editing, and the -m option gives a keymap to link to the vicmd
283 keymap during editing. For vi-style editing, this allows a pair
284 of keymaps to override viins and vicmd. For emacs-style edit‐
285 ing, only -M is normally needed but the -m option may still be
286 used. On exit, the previous keymaps will be restored.
287 If `-t tty' is given, tty is the name of a terminal device to be
289 used instead of the default /dev/tty. If tty does not refer to
290 a terminal an error is reported.
291 zle
293 zle -l [ -L | -a ] [ string ... ]
294 zle -D widget ...
295 zle -A old-widget new-widget
296 zle -N widget [ function ]
297 zle -C widget completion-widget function
298 zle -R [ -c ] [ display-string ] [ string ... ]
299 zle -M string
300 zle -U string
301 zle -K keymap
302 zle -F [ -L ] [ fd [ handler ] ]
303 zle -I
304 zle widget [ -n num ] [ -Nw ] [ -K keymap ] args ...
305 The zle builtin performs a number of different actions concern‐
306 ing ZLE.
307 With no options and no arguments, only the return status will be
309 set. It is zero if ZLE is currently active and widgets could be
310 invoked using this builtin command and non-zero otherwise. Note
311 that even if non-zero status is returned, zle may still be
312 active as part of the completion system; this does not allow
313 direct calls to ZLE widgets.
314 Otherwise, which operation it performs depends on its options:
316 -l [ -L | -a ]
318 List all existing user-defined widgets. If the -L option
319 is used, list in the form of zle commands to create the
320 widgets.
321 When combined with the -a option, all widget names are
323 listed, including the builtin ones. In this case the -L
324 option is ignored.
325 If at least one string is given, nothing will be printed
327 but the return status will be zero if all strings are
328 names of existing widgets (or of user-defined widgets if
329 the -a flag is not given) and non-zero if at least one
330 string is not a name of an defined widget.
331 -D widget ...
333 Delete the named widgets.
334 -A old-widget new-widget
336 Make the new-widget name an alias for old-widget, so that
337 both names refer to the same widget. The names have
338 equal standing; if either is deleted, the other remains.
339 If there is already a widget with the new-widget name, it
340 is deleted.
341 -N widget [ function ]
343 Create a user-defined widget. If there is already a wid‐
344 get with the specified name, it is overwritten. When the
345 new widget is invoked from within the editor, the speci‐
346 fied shell function is called. If no function name is
347 specified, it defaults to the same name as the widget.
348 For further information, see the section Widgets in zsh‐
349 zle(1).
350 -C widget completion-widget function
352 Create a user-defined completion widget named widget. The
353 completion widget will behave like the built-in comple‐
354 tion-widget whose name is given as completion-widget. To
355 generate the completions, the shell function function
356 will be called. For further information, see zshcomp‐
357 wid(1).
358 -R [ -c ] [ display-string ] [ string ... ]
360 Redisplay the command line; this is to be called from
361 within a user-defined widget to allow changes to become
362 visible. If a display-string is given and not empty,
363 this is shown in the status line (immediately below the
364 line being edited).
365 If the optional strings are given they are listed below
367 the prompt in the same way as completion lists are
368 printed. If no strings are given but the -c option is
369 used such a list is cleared.
370 Note that this option is only useful for widgets that do
372 not exit immediately after using it because the strings
373 displayed will be erased immediately after return from
374 the widget.
375 This command can safely be called outside user defined
377 widgets; if zle is active, the display will be refreshed,
378 while if zle is not active, the command has no effect.
379 In this case there will usually be no other arguments.
380 The status is zero if zle was active, else one.
382 -M string
384 As with the -R option, the string will be displayed below
385 the command line; unlike the -R option, the string will
386 not be put into the status line but will instead be
387 printed normally below the prompt. This means that the
388 string will still be displayed after the widget returns
389 (until it is overwritten by subsequent commands).
390 -U string
392 This pushes the characters in the string onto the input
393 stack of ZLE. After the widget currently executed fin‐
394 ishes ZLE will behave as if the characters in the string
395 were typed by the user.
396 As ZLE uses a stack, if this option is used repeatedly
398 the last string pushed onto the stack will be processed
399 first. However, the characters in each string will be
400 processed in the order in which they appear in the
401 string.
402 -K keymap
404 Selects the keymap named keymap. An error message will
405 be displayed if there is no such keymap.
406 This keymap selection affects the interpretation of fol‐
408 lowing keystrokes within this invocation of ZLE. Any
409 following invocation (e.g., the next command line) will
410 start as usual with the `main' keymap selected.
411 -F [ -L ] [ fd [ handler ] ]
413 Only available if your system supports one of the `poll'
414 or `select' system calls; most modern systems do.
415 Installs handler (the name of a shell function) to handle
417 input from file descriptor fd. When zle is attempting to
418 read data, it will examine both the terminal and the list
419 of handled fd's. If data becomes available on a handled
420 fd, zle will call handler with the fd which is ready for
421 reading as the only argument. If the handler produces
422 output to the terminal, it should call `zle -I' before
423 doing so (see below). The handler should not attempt to
424 read from the terminal. Note that zle makes no attempt
425 to check whether this fd is actually readable when
426 installing the handler. The user must make their own
427 arrangements for handling the file descriptor when zle is
428 not active.
429 Any number of handlers for any number of readable file
431 descriptors may be installed. Installing a handler for
432 an fd which is already handled causes the existing han‐
433 dler to be replaced.
434 If no handler is given, but an fd is present, any handler
436 for that fd is removed. If there is none, an error mes‐
437 sage is printed and status 1 is returned.
438 If no arguments are given, or the -L option is supplied,
440 a list of handlers is printed in a form which can be
441 stored for later execution.
442 An fd (but not a handler) may optionally be given with
444 the -L option; in this case, the function will list the
445 handler if any, else silently return status 1.
446 Note that this feature should be used with care. Activ‐
448 ity on one of the fd's which is not properly handled can
449 cause the terminal to become unusable.
450 Here is a simple example of using this feature. A con‐
452 nection to a remote TCP port is created using the ztcp
453 command; see the description of the zsh/net/tcp module in
454 zshmodules(1). Then a handler is installed which simply
455 prints out any data which arrives on this connection.
456 Note that `select' will indicate that the file descriptor
457 needs handling if the remote side has closed the connec‐
458 tion; we handle that by testing for a failed read.
459 if ztcp pwspc 2811; then
460 tcpfd=$REPLY
461 handler() {
462 zle -I
463 local line
464 if ! read -r line <&$1; then
465 # select marks this fd if we reach EOF,
466 # so handle this specially.
467 print "[Read on fd $1 failed, removing.]" >&2
468 zle -F $1
469 return 1
470 fi
471 print -r - $line
472 }
473 zle -F $tcpfd handler
474 fi
475 -I Unusually, this option is most useful outside ordinary
477 widget functions, though it may be used within if normal
478 output to the terminal is required. It invalidates the
479 current zle display in preparation for output; typically
480 this will be from a trap function. It has no effect if
481 zle is not active. When a trap exits, the shell checks
482 to see if the display needs restoring, hence the follow‐
483 ing will print output in such a way as not to disturb the
484 line being edited:
485 TRAPUSR1() {
487 # Invalidate zle display
488 [[ -o zle ]] && zle -I
489 # Show output
490 print Hello
491 }
492 In general, the trap function may need to test whether
494 zle is active before using this method (as shown in the
495 example), since the zsh/zle module may not even be
496 loaded; if it is not, the command can be skipped.
497 It is possible to call `zle -I' several times before con‐
499 trol is returned to the editor; the display will only be
500 invalidated the first time to minimise disruption.
501 Note that there are normally better ways of manipulating
503 the display from within zle widgets; see, for example,
504 `zle -R' above.
505 The returned status is zero if zle was invalidated, even
507 though this may have been by a previous call to `zle -I'
508 or by a system notification. To test if a zle widget may
509 be called at this point, execute zle with no arguments
510 and examine the return status.
511 widget [ -n num ] [ -Nw ] [ -K keymap ] args ...
513 Invoke the specified widget. This can only be done when
514 ZLE is active; normally this will be within a
515 user-defined widget.
516 With the options -n and -N, the current numerical argu‐
518 ment will be saved and then restored after the call to
519 widget; `-n num' sets the numerical argument temporarily
520 to num, while `-N' sets it to the default, i.e. as if
521 there were none.
522 With the option -K, keymap will be used as the current
524 keymap during the execution of the widget. The previous
525 keymap will be restored when the widget exits.
526 Normally, calling a widget in this way does not set the
528 special parameter WIDGET and related parameters, so that
529 the environment appears as if the top-level widget called
530 by the user were still active. With the option -w, WID‐
531 GET and related parameters are set to reflect the widget
532 being executed by the zle call.
533 Any further arguments will be passed to the widget; note
535 that as standard argument handling is performed, any gen‐
536 eral argument list should be preceded by --. If it is a
537 shell function, these are passed down as positional
538 parameters; for builtin widgets it is up to the widget in
539 question what it does with them. Currently arguments are
540 only handled by the incremental-search commands, the his‐
541 tory-search-forward and -backward and the corresponding
542 functions prefixed by vi-, and by universal-argument. No
543 error is flagged if the command does not use the argu‐
544 ments, or only uses some of them.
545 The return status reflects the success or failure of the
547 operation carried out by the widget, or if it is a
548 user-defined widget the return status of the shell func‐
549 tion.
550 A non-zero return status causes the shell to beep when
552 the widget exits, unless the BEEP options was unset or
553 the widget was called via the zle command. Thus if a
554 user defined widget requires an immediate beep, it should
555 call the beep widget directly.
556
558 All actions in the editor are performed by `widgets'. A widget's job
559 is simply to perform some small action. The ZLE commands that key
560 sequences in keymaps are bound to are in fact widgets. Widgets can be
561 user-defined or built in.
562 The standard widgets built in to ZLE are listed in Standard Widgets
564 below. Other built-in widgets can be defined by other modules (see
565 zshmodules(1)). Each built-in widget has two names: its normal canoni‐
566 cal name, and the same name preceded by a `.'. The `.' name is spe‐
567 cial: it can't be rebound to a different widget. This makes the widget
568 available even when its usual name has been redefined.
569 User-defined widgets are defined using `zle -N', and implemented as
571 shell functions. When the widget is executed, the corresponding shell
572 function is executed, and can perform editing (or other) actions. It
573 is recommended that user-defined widgets should not have names starting
574 with `.'.
575
577 User-defined widgets, being implemented as shell functions, can execute
578 any normal shell command. They can also run other widgets (whether
579 built-in or user-defined) using the zle builtin command. The standard
580 input of the function is closed to prevent external commands from unin‐
581 tentionally blocking ZLE by reading from the terminal, but read -k or
582 read -q can be used to read characters. Finally, they can examine and
583 edit the ZLE buffer being edited by reading and setting the special
584 parameters described below.
585 These special parameters are always available in widget functions, but
587 are not in any way special outside ZLE. If they have some normal value
588 outside ZLE, that value is temporarily inaccessible, but will return
589 when the widget function exits. These special parameters in fact have
590 local scope, like parameters created in a function using local.
591 Inside completion widgets and traps called while ZLE is active, these
593 parameters are available read-only.
594 BUFFER (scalar)
596 The entire contents of the edit buffer. If it is written to,
597 the cursor remains at the same offset, unless that would put it
598 outside the buffer.
599 BUFFERLINES (integer)
601 The number of screen lines needed for the edit buffer currently
602 displayed on screen (i.e. without any changes to the preceding
603 parameters done after the last redisplay); read-only.
604 CONTEXT (scalar)
606 The context in which zle was called to read a line; read-only.
607 One of the values:
608 start The start of a command line (at prompt PS1).
609 cont A continuation to a command line (at prompt PS2).
611 select In a select loop.
613 vared Editing a variable in vared.
615 CURSOR (integer)
617 The offset of the cursor, within the edit buffer. This is in
618 the range 0 to $#BUFFER, and is by definition equal to
619 $#LBUFFER. Attempts to move the cursor outside the buffer will
620 result in the cursor being moved to the appropriate end of the
621 buffer.
622 CUTBUFFER (scalar)
624 The last item to be cut using one of the `kill-' commands; the
625 string which the next yank would insert in the line. Later
626 entries in the kill ring are in the array killring. Note that
627 the command `zle copy-region-as-kill string' can be used to set
628 the text of the cut buffer from a shell function and cycle the
629 kill ring in the same way as interactively killing text.
630 HISTNO (integer)
632 The current history number. Setting this has the same effect as
633 moving up or down in the history to the corresponding history
634 line. An attempt to set it is ignored if the line is not stored
635 in the history. Note this is not the same as the parameter
636 HISTCMD, which always gives the number of the history line being
637 added to the main shell's history. HISTNO refers to the line
638 being retrieved within zle.
639 KEYMAP (scalar)
641 The name of the currently selected keymap; read-only.
642 KEYS (scalar)
644 The keys typed to invoke this widget, as a literal string;
645 read-only.
646 killring (array)
648 The array of previously killed items, with the most recently
649 killed first. This gives the items that would be retrieved by a
650 yank-pop in the same order. Note, however, that the most
651 recently killed item is in $CUTBUFFER; $killring shows the array
652 of previous entries.
653 The default size for the kill ring is eight, however the length
655 may be changed by normal array operations. Any empty string in
656 the kill ring is ignored by the yank-pop command, hence the size
657 of the array effectively sets the maximum length of the kill
658 ring, while the number of non-zero strings gives the current
659 length, both as seen by the user at the command line.
660 LASTABORTEDSEARCH (scalar)
662 The last search string used by an interactive search that was
663 aborted by the user (status 3 returned by the search widget).
664 LASTSEARCH (scalar)
666 The last search string used by an interactive search; read-only.
667 This is set even if the search failed (status 0, 1 or 2 returned
668 by the search widget), but not if it was aborted by the user.
669 LASTWIDGET (scalar)
671 The name of the last widget that was executed; read-only.
672 LBUFFER (scalar)
674 The part of the buffer that lies to the left of the cursor posi‐
675 tion. If it is assigned to, only that part of the buffer is
676 replaced, and the cursor remains between the new $LBUFFER and
677 the old $RBUFFER.
678 MARK (integer)
680 Like CURSOR, but for the mark.
681 NUMERIC (integer)
683 The numeric argument. If no numeric argument was given, this
684 parameter is unset. When this is set inside a widget function,
685 builtin widgets called with the zle builtin command will use the
686 value assigned. If it is unset inside a widget function, builtin
687 widgets called behave as if no numeric argument was given.
688 PENDING (integer)
690 The number of bytes pending for input, i.e. the number of bytes
691 which have already been typed and can immediately be read. On
692 systems where the shell is not able to get this information,
693 this parameter will always have a value of zero. Read-only.
694 PREBUFFER (scalar)
696 In a multi-line input at the secondary prompt, this read-only
697 parameter contains the contents of the lines before the one the
698 cursor is currently in.
699 PREDISPLAY (scalar)
701 Text to be displayed before the start of the editable text buf‐
702 fer. This does not have to be a complete line; to display a
703 complete line, a newline must be appended explicitly. The
704 text is reset on each new invocation (but not recursive invoca‐
705 tion) of zle.
706 POSTDISPLAY (scalar)
708 Text to be displayed after the end of the editable text buffer.
709 This does not have to be a complete line; to display a complete
710 line, a newline must be prepended explicitly. The text is reset
711 on each new invocation (but not recursive invocation) of zle.
712 RBUFFER (scalar)
714 The part of the buffer that lies to the right of the cursor
715 position. If it is assigned to, only that part of the buffer is
716 replaced, and the cursor remains between the old $LBUFFER and
717 the new $RBUFFER.
718 REGION_ACTIVE (integer)
720 Indicates if the region is currently active. It can be assigned
721 0 or 1 to deactivate and activate the region respectively; see
722 Character Highlighting below.
723 region_highlight (array)
725 Each element of this array may be set to a string that describes
726 highlighting for an arbitrary region of the command line that
727 will take effect the next time the command line is redisplayed.
728 Highlighting of the non-editable parts of the command line in
729 PREDISPLAY and POSTDISPLAY are possible, but note that the P
730 flag is needed for character indexing to include PREDISPLAY.
731 Each string consists of the following parts:
733 Optionally, a `P' to signify that the start and end offset that
735 follow include any string set by the PREDISPLAY special
736 parameter; this is needed if the predisplay string itself
737 is to be highlighted. Whitespace may follow the `P'.
738 A start offset in the same units as CURSOR, terminated by
739 whitespace.
740 An end offset in the same units as CURSOR, terminated by
741 whitespace.
742 A highlight specification in the same format as
743 used for contexts in the parameter zle_highlight, see
744 Character Highlighting below; for example, standout or
745 fg=red,bold.
746 For example,
748 region_highlight=("P0 20 bold")
750 specifies that the first twenty characters of the text including
752 any predisplay string should be highlighted in bold.
753 Note that the effect of region_highlight is not saved and disap‐
755 pears as soon as the line is accepted. The line editor makes no
756 attempt to keep the highlighting effect synchronised with the
757 line as it is edited; hence region highlighting is best limited
758 to static effects within user widgets.
759 WIDGET (scalar)
761 The name of the widget currently being executed; read-only.
762 WIDGETFUNC (scalar)
764 The name of the shell function that implements a widget defined
765 with either zle -N or zle -C. In the former case, this is the
766 second argument to the zle -N command that defined the widget,
767 or the first argument if there was no second argument. In the
768 latter case this is the the third argument to the zle -C command
769 that defined the widget. Read-only.
770 WIDGETSTYLE (scalar)
772 Describes the implementation behind the completion widget cur‐
773 rently being executed; the second argument that followed zle -C
774 when the widget was defined. This is the name of a builtin com‐
775 pletion widget. For widgets defined with zle -N this is set to
776 the empty string. Read-only.
777 Special Widgets
779 There are a few user-defined widgets which are special to the shell.
780 If they do not exist, no special action is taken. The environment pro‐
781 vided is identical to that for any other editing widget.
782 zle-line-init
784 Executed every time the line editor is started to read a new
785 line of input. The following example puts the line editor into
786 vi command mode when it starts up.
787 zle-line-init() { zle -K vicmd; }
789 zle -N zle-line-init
790 (The command inside the function sets the keymap directly; it is
792 equivalent to zle vi-cmd-mode.)
793 zle-line-finish
795 This is similar to zle-line-init but is executed every time the
796 line editor has finished reading a line of input.
797 zle-keymap-select
799 Executed every time the keymap changes, i.e. the special parame‐
800 ter KEYMAP is set to a different value, while the line editor is
801 active. Initialising the keymap when the line editor starts
802 does not cause the widget to be called.
803 The value $KEYMAP within the function reflects the new keymap.
805 The old keymap is passed as the sole argument.
806 This can been used for detecting switches between the vi command
808 (vicmd) and insert (usually main) keymaps.
809
811 The following is a list of all the standard widgets, and their default
812 bindings in emacs mode, vi command mode and vi insert mode (the
813 `emacs', `vicmd' and `viins' keymaps, respectively).
814 Note that cursor keys are bound to movement keys in all three keymaps;
816 the shell assumes that the cursor keys send the key sequences reported
817 by the terminal-handling library (termcap or terminfo). The key
818 sequences shown in the list are those based on the VT100, common on
819 many modern terminals, but in fact these are not necessarily bound. In
820 the case of the viins keymap, the initial escape character of the
821 sequences serves also to return to the vicmd keymap: whether this hap‐
822 pens is determined by the KEYTIMEOUT parameter, see zshparam(1).
823 Movement
825 vi-backward-blank-word (unbound) (B) (unbound)
826 Move backward one word, where a word is defined as a series of
827 non-blank characters.
828 backward-char (^B ESC-[D) (unbound) (unbound)
830 Move backward one character.
831 vi-backward-char (unbound) (^H h ^?) (ESC-[D)
833 Move backward one character, without changing lines.
834 backward-word (ESC-B ESC-b) (unbound) (unbound)
836 Move to the beginning of the previous word.
837 emacs-backward-word
839 Move to the beginning of the previous word.
840 vi-backward-word (unbound) (b) (unbound)
842 Move to the beginning of the previous word, vi-style.
843 beginning-of-line (^A) (unbound) (unbound)
845 Move to the beginning of the line. If already at the beginning
846 of the line, move to the beginning of the previous line, if any.
847 vi-beginning-of-line
849 Move to the beginning of the line, without changing lines.
850 end-of-line (^E) (unbound) (unbound)
852 Move to the end of the line. If already at the end of the line,
853 move to the end of the next line, if any.
854 vi-end-of-line (unbound) ($) (unbound)
856 Move to the end of the line. If an argument is given to this
857 command, the cursor will be moved to the end of the line (argu‐
858 ment - 1) lines down.
859 vi-forward-blank-word (unbound) (W) (unbound)
861 Move forward one word, where a word is defined as a series of
862 non-blank characters.
863 vi-forward-blank-word-end (unbound) (E) (unbound)
865 Move to the end of the current word, or, if at the end of the
866 current word, to the end of the next word, where a word is
867 defined as a series of non-blank characters.
868 forward-char (^F ESC-[C) (unbound) (unbound)
870 Move forward one character.
871 vi-forward-char (unbound) (space l) (ESC-[C)
873 Move forward one character.
874 vi-find-next-char (^X^F) (f) (unbound)
876 Read a character from the keyboard, and move to the next occur‐
877 rence of it in the line.
878 vi-find-next-char-skip (unbound) (t) (unbound)
880 Read a character from the keyboard, and move to the position
881 just before the next occurrence of it in the line.
882 vi-find-prev-char (unbound) (F) (unbound)
884 Read a character from the keyboard, and move to the previous
885 occurrence of it in the line.
886 vi-find-prev-char-skip (unbound) (T) (unbound)
888 Read a character from the keyboard, and move to the position
889 just after the previous occurrence of it in the line.
890 vi-first-non-blank (unbound) (^) (unbound)
892 Move to the first non-blank character in the line.
893 vi-forward-word (unbound) (w) (unbound)
895 Move forward one word, vi-style.
896 forward-word (ESC-F ESC-f) (unbound) (unbound)
898 Move to the beginning of the next word. The editor's idea of a
899 word is specified with the WORDCHARS parameter.
900 emacs-forward-word
902 Move to the end of the next word.
903 vi-forward-word-end (unbound) (e) (unbound)
905 Move to the end of the next word.
906 vi-goto-column (ESC-|) (|) (unbound)
908 Move to the column specified by the numeric argument.
909 vi-goto-mark (unbound) (`) (unbound)
911 Move to the specified mark.
912 vi-goto-mark-line (unbound) (') (unbound)
914 Move to beginning of the line containing the specified mark.
915 vi-repeat-find (unbound) (;) (unbound)
917 Repeat the last vi-find command.
918 vi-rev-repeat-find (unbound) (,) (unbound)
920 Repeat the last vi-find command in the opposite direction.
921 History Control
923 beginning-of-buffer-or-history (ESC-<) (unbound) (unbound)
924 Move to the beginning of the buffer, or if already there, move
925 to the first event in the history list.
926 beginning-of-line-hist
928 Move to the beginning of the line. If already at the beginning
929 of the buffer, move to the previous history line.
930 beginning-of-history
932 Move to the first event in the history list.
933 down-line-or-history (^N ESC-[B) (j) (ESC-[B)
935 Move down a line in the buffer, or if already at the bottom
936 line, move to the next event in the history list.
937 vi-down-line-or-history (unbound) (+) (unbound)
939 Move down a line in the buffer, or if already at the bottom
940 line, move to the next event in the history list. Then move to
941 the first non-blank character on the line.
942 down-line-or-search
944 Move down a line in the buffer, or if already at the bottom
945 line, search forward in the history for a line beginning with
946 the first word in the buffer.
947 If called from a function by the zle command with arguments, the
949 first argument is taken as the string for which to search,
950 rather than the first word in the buffer.
951 down-history (unbound) (^N) (unbound)
953 Move to the next event in the history list.
954 history-beginning-search-backward
956 Search backward in the history for a line beginning with the
957 current line up to the cursor. This leaves the cursor in its
958 original position.
959 end-of-buffer-or-history (ESC->) (unbound) (unbound)
961 Move to the end of the buffer, or if already there, move to the
962 last event in the history list.
963 end-of-line-hist
965 Move to the end of the line. If already at the end of the buf‐
966 fer, move to the next history line.
967 end-of-history
969 Move to the last event in the history list.
970 vi-fetch-history (unbound) (G) (unbound)
972 Fetch the history line specified by the numeric argument. This
973 defaults to the current history line (i.e. the one that isn't
974 history yet).
975 history-incremental-search-backward (^R ^Xr) (unbound) (unbound)
977 Search backward incrementally for a specified string. The
978 search is case-insensitive if the search string does not have
979 uppercase letters and no numeric argument was given. The string
980 may begin with `^' to anchor the search to the beginning of the
981 line. When called from a user-defined function returns the fol‐
982 lowing statuses: 0, if the search succeeded; 1, if the search
983 failed; 2, if the search term was a bad pattern; 3, if the
984 search was aborted by the send-break command.
985 A restricted set of editing functions is available in the
987 mini-buffer. Keys are looked up in the special isearch keymap,
988 and if not found there in the main keymap (note that by default
989 the isearch keymap is empty). An interrupt signal, as defined
990 by the stty setting, will stop the search and go back to the
991 original line. An undefined key will have the same effect.
992 Note that the following always perform the same task within
993 incremental searches and cannot be replaced by user defined wid‐
994 gets. The supported functions are:
995 accept-and-hold
997 accept-and-infer-next-history
998 accept-line
999 accept-line-and-down-history
1000 Perform the usual function after exiting incremental
1001 search. The command line displayed is executed.
1002 backward-delete-char
1004 vi-backward-delete-char
1005 Back up one place in the search history. If the search
1006 has been repeated this does not immediately erase a char‐
1007 acter in the minibuffer.
1008 accept-search
1010 Exit incremental search, retaining the command line but
1011 performing no further action. Note that this function is
1012 not bound by default and has no effect outside incremen‐
1013 tal search.
1014 backward-delete-word
1016 backward-kill-word
1017 vi-backward-kill-word
1018 Back up one character in the minibuffer; if multiple
1019 searches have been performed since the character was
1020 inserted the search history is rewound to the point just
1021 before the character was entered. Hence this has the
1022 effect of repeating backward-delete-char.
1023 clear-screen
1025 Clear the screen, remaining in incremental search mode.
1026 history-incremental-search-backward
1028 Find the next occurrence of the contents of the mini-buf‐
1029 fer.
1030 history-incremental-search-forward
1032 Invert the sense of the search.
1033 magic-space
1035 Inserts a non-magical space.
1036 quoted-insert
1038 vi-quoted-insert
1039 Quote the character to insert into the minibuffer.
1040 redisplay
1042 Redisplay the command line, remaining in incremental
1043 search mode.
1044 vi-cmd-mode
1046 Toggle between the `main' and `vicmd' keymaps; the `main'
1047 keymap (insert mode) will be selected initially.
1048 vi-repeat-search
1050 vi-rev-repeat-search
1051 Repeat the search. The direction of the search is indi‐
1052 cated in the mini-buffer.
1053 Any multi-character string that is not bound to one of the above
1055 functions will beep and interrupt the search, leaving the last
1056 found line in the buffer. Any single character that is not bound
1057 to one of the above functions, or self-insert or
1058 self-insert-unmeta, will have the same effect but the function
1059 will be executed.
1060 When called from a widget function by the zle command, the
1062 incremental search commands can take a string argument. This
1063 will be treated as a string of keys, as for arguments to the
1064 bindkey command, and used as initial input for the command. Any
1065 characters in the string which are unused by the incremental
1066 search will be silently ignored. For example,
1067 zle history-incremental-search-backward forceps
1069 will search backwards for forceps, leaving the minibuffer con‐
1071 taining the string `forceps'.
1072 history-incremental-search-forward (^S ^Xs) (unbound) (unbound)
1074 Search forward incrementally for a specified string. The search
1075 is case-insensitive if the search string does not have uppercase
1076 letters and no numeric argument was given. The string may begin
1077 with `^' to anchor the search to the beginning of the line. The
1078 functions available in the mini-buffer are the same as for his‐
1079 tory-incremental-search-backward.
1080 history-incremental-pattern-search-backward
1082 history-incremental-pattern-search-forward
1083 These widgets behave similarly to the corresponding widgets with
1084 no -pattern, but the search string typed by the user is treated
1085 as a pattern, respecting the current settings of the various
1086 options affecting pattern matching. See FILENAME GENERATION in
1087 zshexpn(1) for a description of patterns. If no numeric argu‐
1088 ment was given lowercase letters in the search string may match
1089 uppercase letters in the history. The string may begin with `^'
1090 to anchor the search to the beginning of the line.
1091 The prompt changes to indicate an invalid pattern; this may sim‐
1093 ply indicate the pattern is not yet complete.
1094 Note that only non-overlapping matches are reported, so an
1096 expression with wildcards may return fewer matches on a line
1097 than are visible by inspection.
1098 history-search-backward (ESC-P ESC-p) (unbound) (unbound)
1100 Search backward in the history for a line beginning with the
1101 first word in the buffer.
1102 If called from a function by the zle command with arguments, the
1104 first argument is taken as the string for which to search,
1105 rather than the first word in the buffer.
1106 vi-history-search-backward (unbound) (/) (unbound)
1108 Search backward in the history for a specified string. The
1109 string may begin with `^' to anchor the search to the beginning
1110 of the line.
1111 A restricted set of editing functions is available in the
1113 mini-buffer. An interrupt signal, as defined by the stty set‐
1114 ting, will stop the search. The functions available in the
1115 mini-buffer are: accept-line, backward-delete-char, vi-back‐
1116 ward-delete-char, backward-kill-word, vi-backward-kill-word,
1117 clear-screen, redisplay, quoted-insert and vi-quoted-insert.
1118 vi-cmd-mode is treated the same as accept-line, and magic-space
1120 is treated as a space. Any other character that is not bound to
1121 self-insert or self-insert-unmeta will beep and be ignored. If
1122 the function is called from vi command mode, the bindings of the
1123 current insert mode will be used.
1124 If called from a function by the zle command with arguments, the
1126 first argument is taken as the string for which to search,
1127 rather than the first word in the buffer.
1128 history-search-forward (ESC-N ESC-n) (unbound) (unbound)
1130 Search forward in the history for a line beginning with the
1131 first word in the buffer.
1132 If called from a function by the zle command with arguments, the
1134 first argument is taken as the string for which to search,
1135 rather than the first word in the buffer.
1136 vi-history-search-forward (unbound) (?) (unbound)
1138 Search forward in the history for a specified string. The
1139 string may begin with `^' to anchor the search to the beginning
1140 of the line. The functions available in the mini-buffer are the
1141 same as for vi-history-search-backward. Argument handling is
1142 also the same as for that command.
1143 infer-next-history (^X^N) (unbound) (unbound)
1145 Search in the history list for a line matching the current one
1146 and fetch the event following it.
1147 insert-last-word (ESC-_ ESC-.) (unbound) (unbound)
1149 Insert the last word from the previous history event at the cur‐
1150 sor position. If a positive numeric argument is given, insert
1151 that word from the end of the previous history event. If the
1152 argument is zero or negative insert that word from the left
1153 (zero inserts the previous command word). Repeating this com‐
1154 mand replaces the word just inserted with the last word from the
1155 history event prior to the one just used; numeric arguments can
1156 be used in the same way to pick a word from that event.
1157 When called from a shell function invoked from a user-defined
1159 widget, the command can take one to three arguments. The first
1160 argument specifies a history offset which applies to successive
1161 calls to this widget: if is -1, the default behaviour is used,
1162 while if it is 1, successive calls will move forwards through
1163 the history. The value 0 can be used to indicate that the his‐
1164 tory line examined by the previous execution of the command will
1165 be reexamined. Note that negative numbers should be preceded
1166 with a `--' argument to avoid confusing them with options.
1167 If two arguments are given, the second specifies the word on the
1169 command line in normal array index notation (as a more natural
1170 alternative to the prefix argument). Hence 1 is the first word,
1171 and -1 (the default) is the last word.
1172 If a third argument is given, its value is ignored, but it is
1174 used to signify that the history offset is relative to the cur‐
1175 rent history line, rather than the one remembered after the pre‐
1176 vious invocations of insert-last-word.
1177 For example, the default behaviour of the command corresponds to
1179 zle insert-last-word -- -1 -1
1181 while the command
1183 zle insert-last-word -- -1 1 -
1185 always copies the first word of the line in the history immedi‐
1187 ately before the line being edited. This has the side effect
1188 that later invocations of the widget will be relative to that
1189 line.
1190 vi-repeat-search (unbound) (n) (unbound)
1192 Repeat the last vi history search.
1193 vi-rev-repeat-search (unbound) (N) (unbound)
1195 Repeat the last vi history search, but in reverse.
1196 up-line-or-history (^P ESC-[A) (k) (ESC-[A)
1198 Move up a line in the buffer, or if already at the top line,
1199 move to the previous event in the history list.
1200 vi-up-line-or-history (unbound) (-) (unbound)
1202 Move up a line in the buffer, or if already at the top line,
1203 move to the previous event in the history list. Then move to
1204 the first non-blank character on the line.
1205 up-line-or-search
1207 Move up a line in the buffer, or if already at the top line,
1208 search backward in the history for a line beginning with the
1209 first word in the buffer.
1210 If called from a function by the zle command with arguments, the
1212 first argument is taken as the string for which to search,
1213 rather than the first word in the buffer.
1214 up-history (unbound) (^P) (unbound)
1216 Move to the previous event in the history list.
1217 history-beginning-search-forward
1219 Search forward in the history for a line beginning with the cur‐
1220 rent line up to the cursor. This leaves the cursor in its orig‐
1221 inal position.
1222 Modifying Text
1224 vi-add-eol (unbound) (A) (unbound)
1225 Move to the end of the line and enter insert mode.
1226 vi-add-next (unbound) (a) (unbound)
1228 Enter insert mode after the current cursor position, without
1229 changing lines.
1230 backward-delete-char (^H ^?) (unbound) (unbound)
1232 Delete the character behind the cursor.
1233 vi-backward-delete-char (unbound) (X) (^H)
1235 Delete the character behind the cursor, without changing lines.
1236 If in insert mode, this won't delete past the point where insert
1237 mode was last entered.
1238 backward-delete-word
1240 Delete the word behind the cursor.
1241 backward-kill-line
1243 Kill from the beginning of the line to the cursor position.
1244 backward-kill-word (^W ESC-^H ESC-^?) (unbound) (unbound)
1246 Kill the word behind the cursor.
1247 vi-backward-kill-word (unbound) (unbound) (^W)
1249 Kill the word behind the cursor, without going past the point
1250 where insert mode was last entered.
1251 capitalize-word (ESC-C ESC-c) (unbound) (unbound)
1253 Capitalize the current word and move past it.
1254 vi-change (unbound) (c) (unbound)
1256 Read a movement command from the keyboard, and kill from the
1257 cursor position to the endpoint of the movement. Then enter
1258 insert mode. If the command is vi-change, change the current
1259 line.
1260 vi-change-eol (unbound) (C) (unbound)
1262 Kill to the end of the line and enter insert mode.
1263 vi-change-whole-line (unbound) (S) (unbound)
1265 Kill the current line and enter insert mode.
1266 copy-region-as-kill (ESC-W ESC-w) (unbound) (unbound)
1268 Copy the area from the cursor to the mark to the kill buffer.
1269 If called from a ZLE widget function in the form `zle
1271 copy-region-as-kill string' then string will be taken as the
1272 text to copy to the kill buffer. The cursor, the mark and the
1273 text on the command line are not used in this case.
1274 copy-prev-word (ESC-^_) (unbound) (unbound)
1276 Duplicate the word to the left of the cursor.
1277 copy-prev-shell-word
1279 Like copy-prev-word, but the word is found by using shell pars‐
1280 ing, whereas copy-prev-word looks for blanks. This makes a dif‐
1281 ference when the word is quoted and contains spaces.
1282 vi-delete (unbound) (d) (unbound)
1284 Read a movement command from the keyboard, and kill from the
1285 cursor position to the endpoint of the movement. If the command
1286 is vi-delete, kill the current line.
1287 delete-char
1289 Delete the character under the cursor.
1290 vi-delete-char (unbound) (x) (unbound)
1292 Delete the character under the cursor, without going past the
1293 end of the line.
1294 delete-word
1296 Delete the current word.
1297 down-case-word (ESC-L ESC-l) (unbound) (unbound)
1299 Convert the current word to all lowercase and move past it.
1300 kill-word (ESC-D ESC-d) (unbound) (unbound)
1302 Kill the current word.
1303 gosmacs-transpose-chars
1305 Exchange the two characters behind the cursor.
1306 vi-indent (unbound) (>) (unbound)
1308 Indent a number of lines.
1309 vi-insert (unbound) (i) (unbound)
1311 Enter insert mode.
1312 vi-insert-bol (unbound) (I) (unbound)
1314 Move to the first non-blank character on the line and enter
1315 insert mode.
1316 vi-join (^X^J) (J) (unbound)
1318 Join the current line with the next one.
1319 kill-line (^K) (unbound) (unbound)
1321 Kill from the cursor to the end of the line. If already on the
1322 end of the line, kill the newline character.
1323 vi-kill-line (unbound) (unbound) (^U)
1325 Kill from the cursor back to wherever insert mode was last
1326 entered.
1327 vi-kill-eol (unbound) (D) (unbound)
1329 Kill from the cursor to the end of the line.
1330 kill-region
1332 Kill from the cursor to the mark.
1333 kill-buffer (^X^K) (unbound) (unbound)
1335 Kill the entire buffer.
1336 kill-whole-line (^U) (unbound) (unbound)
1338 Kill the current line.
1339 vi-match-bracket (^X^B) (%) (unbound)
1341 Move to the bracket character (one of {}, () or []) that matches
1342 the one under the cursor. If the cursor is not on a bracket
1343 character, move forward without going past the end of the line
1344 to find one, and then go to the matching bracket.
1345 vi-open-line-above (unbound) (O) (unbound)
1347 Open a line above the cursor and enter insert mode.
1348 vi-open-line-below (unbound) (o) (unbound)
1350 Open a line below the cursor and enter insert mode.
1351 vi-oper-swap-case
1353 Read a movement command from the keyboard, and swap the case of
1354 all characters from the cursor position to the endpoint of the
1355 movement. If the movement command is vi-oper-swap-case, swap
1356 the case of all characters on the current line.
1357 overwrite-mode (^X^O) (unbound) (unbound)
1359 Toggle between overwrite mode and insert mode.
1360 vi-put-before (unbound) (P) (unbound)
1362 Insert the contents of the kill buffer before the cursor. If
1363 the kill buffer contains a sequence of lines (as opposed to
1364 characters), paste it above the current line.
1365 vi-put-after (unbound) (p) (unbound)
1367 Insert the contents of the kill buffer after the cursor. If the
1368 kill buffer contains a sequence of lines (as opposed to charac‐
1369 ters), paste it below the current line.
1370 quoted-insert (^V) (unbound) (unbound)
1372 Insert the next character typed into the buffer literally. An
1373 interrupt character will not be inserted.
1374 vi-quoted-insert (unbound) (unbound) (^Q ^V)
1376 Display a `^' at the cursor position, and insert the next char‐
1377 acter typed into the buffer literally. An interrupt character
1378 will not be inserted.
1379 quote-line (ESC-') (unbound) (unbound)
1381 Quote the current line; that is, put a `'' character at the
1382 beginning and the end, and convert all `'' characters to `'\'''.
1383 quote-region (ESC-") (unbound) (unbound)
1385 Quote the region from the cursor to the mark.
1386 vi-replace (unbound) (R) (unbound)
1388 Enter overwrite mode.
1389 vi-repeat-change (unbound) (.) (unbound)
1391 Repeat the last vi mode text modification. If a count was used
1392 with the modification, it is remembered. If a count is given to
1393 this command, it overrides the remembered count, and is remem‐
1394 bered for future uses of this command. The cut buffer specifi‐
1395 cation is similarly remembered.
1396 vi-replace-chars (unbound) (r) (unbound)
1398 Replace the character under the cursor with a character read
1399 from the keyboard.
1400 self-insert (printable characters) (unbound) (printable characters and
1402 some control characters)
1403 Insert a character into the buffer at the cursor position.
1404 self-insert-unmeta (ESC-^I ESC-^J ESC-^M) (unbound) (unbound)
1406 Insert a character into the buffer after stripping the meta bit
1407 and converting ^M to ^J.
1408 vi-substitute (unbound) (s) (unbound)
1410 Substitute the next character(s).
1411 vi-swap-case (unbound) (~) (unbound)
1413 Swap the case of the character under the cursor and move past
1414 it.
1415 transpose-chars (^T) (unbound) (unbound)
1417 Exchange the two characters to the left of the cursor if at end
1418 of line, else exchange the character under the cursor with the
1419 character to the left.
1420 transpose-words (ESC-T ESC-t) (unbound) (unbound)
1422 Exchange the current word with the one before it.
1423 vi-unindent (unbound) (<) (unbound)
1425 Unindent a number of lines.
1426 up-case-word (ESC-U ESC-u) (unbound) (unbound)
1428 Convert the current word to all caps and move past it.
1429 yank (^Y) (unbound) (unbound)
1431 Insert the contents of the kill buffer at the cursor position.
1432 yank-pop (ESC-y) (unbound) (unbound)
1434 Remove the text just yanked, rotate the kill-ring (the history
1435 of previously killed text) and yank the new top. Only works
1436 following yank or yank-pop.
1437 vi-yank (unbound) (y) (unbound)
1439 Read a movement command from the keyboard, and copy the region
1440 from the cursor position to the endpoint of the movement into
1441 the kill buffer. If the command is vi-yank, copy the current
1442 line.
1443 vi-yank-whole-line (unbound) (Y) (unbound)
1445 Copy the current line into the kill buffer.
1446 vi-yank-eol
1448 Copy the region from the cursor position to the end of the line
1449 into the kill buffer. Arguably, this is what Y should do in vi,
1450 but it isn't what it actually does.
1451 Arguments
1453 digit-argument (ESC-0..ESC-9) (1-9) (unbound)
1454 Start a new numeric argument, or add to the current one. See
1455 also vi-digit-or-beginning-of-line. This only works if bound to
1456 a key sequence ending in a decimal digit.
1457 Inside a widget function, a call to this function treats the
1459 last key of the key sequence which called the widget as the
1460 digit.
1461 neg-argument (ESC--) (unbound) (unbound)
1463 Changes the sign of the following argument.
1464 universal-argument
1466 Multiply the argument of the next command by 4. Alternatively,
1467 if this command is followed by an integer (positive or nega‐
1468 tive), use that as the argument for the next command. Thus dig‐
1469 its cannot be repeated using this command. For example, if this
1470 command occurs twice, followed immediately by forward-char, move
1471 forward sixteen spaces; if instead it is followed by -2, then
1472 forward-char, move backward two spaces.
1473 Inside a widget function, if passed an argument, i.e. `zle uni‐
1475 versal-argument num', the numerical argument will be set to num;
1476 this is equivalent to `NUMERIC=num'.
1477 argument-base
1479 Use the existing numeric argument as a numeric base, which must
1480 be in the range 2 to 36 inclusive. Subsequent use of
1481 digit-argument and universal-argument will input a new prefix in
1482 the given base. The usual hexadecimal convention is used: the
1483 letter a or A corresponds to 10, and so on. Arguments in bases
1484 requiring digits from 10 upwards are more conveniently input
1485 with universal-argument, since ESC-a etc. are not usually bound
1486 to digit-argument.
1487 The function can be used with a command argument inside a
1489 user-defined widget. The following code sets the base to 16 and
1490 lets the user input a hexadecimal argument until a key out of
1491 the digit range is typed:
1492 zle argument-base 16
1494 zle universal-argument
1495 Completion
1497 accept-and-menu-complete
1498 In a menu completion, insert the current completion into the
1499 buffer, and advance to the next possible completion.
1500 complete-word
1502 Attempt completion on the current word.
1503 delete-char-or-list (^D) (unbound) (unbound)
1505 Delete the character under the cursor. If the cursor is at the
1506 end of the line, list possible completions for the current word.
1507 expand-cmd-path
1509 Expand the current command to its full pathname.
1510 expand-or-complete (TAB) (unbound) (TAB)
1512 Attempt shell expansion on the current word. If that fails,
1513 attempt completion.
1514 expand-or-complete-prefix
1516 Attempt shell expansion on the current word up to cursor.
1517 expand-history (ESC-space ESC-!) (unbound) (unbound)
1519 Perform history expansion on the edit buffer.
1520 expand-word (^X*) (unbound) (unbound)
1522 Attempt shell expansion on the current word.
1523 list-choices (ESC-^D) (^D =) (^D)
1525 List possible completions for the current word.
1526 list-expand (^Xg ^XG) (^G) (^G)
1528 List the expansion of the current word.
1529 magic-space
1531 Perform history expansion and insert a space into the buffer.
1532 This is intended to be bound to space.
1533 menu-complete
1535 Like complete-word, except that menu completion is used. See
1536 the MENU_COMPLETE option.
1537 menu-expand-or-complete
1539 Like expand-or-complete, except that menu completion is used.
1540 reverse-menu-complete
1542 Perform menu completion, like menu-complete, except that if a
1543 menu completion is already in progress, move to the previous
1544 completion rather than the next.
1545 end-of-list
1547 When a previous completion displayed a list below the prompt,
1548 this widget can be used to move the prompt below the list.
1549 Miscellaneous
1551 accept-and-hold (ESC-A ESC-a) (unbound) (unbound)
1552 Push the contents of the buffer on the buffer stack and execute
1553 it.
1554 accept-and-infer-next-history
1556 Execute the contents of the buffer. Then search the history
1557 list for a line matching the current one and push the event fol‐
1558 lowing onto the buffer stack.
1559 accept-line (^J ^M) (^J ^M) (^J ^M)
1561 Finish editing the buffer. Normally this causes the buffer to
1562 be executed as a shell command.
1563 accept-line-and-down-history (^O) (unbound) (unbound)
1565 Execute the current line, and push the next history event on the
1566 the buffer stack.
1567 auto-suffix-remove
1569 If the previous action added a suffix (space, slash, etc.) to
1570 the word on the command line, remove it. Otherwise do nothing.
1571 Removing the suffix ends any active menu completion or menu
1572 selection.
1573 This widget is intended to be called from user-defined widgets
1575 to enforce a desired suffix-removal behavior.
1576 auto-suffix-retain
1578 If the previous action added a suffix (space, slash, etc.) to
1579 the word on the command line, force it to be preserved. Other‐
1580 wise do nothing. Retaining the suffix ends any active menu com‐
1581 pletion or menu selection.
1582 This widget is intended to be called from user-defined widgets
1584 to enforce a desired suffix-preservation behavior.
1585 beep Beep, unless the BEEP option is unset.
1587 vi-cmd-mode (^X^V) (unbound) (^[)
1589 Enter command mode; that is, select the `vicmd' keymap. Yes,
1590 this is bound by default in emacs mode.
1591 vi-caps-lock-panic
1593 Hang until any lowercase key is pressed. This is for vi users
1594 without the mental capacity to keep track of their caps lock key
1595 (like the author).
1596 clear-screen (^L ESC-^L) (^L) (^L)
1598 Clear the screen and redraw the prompt.
1599 describe-key-briefly
1601 Reads a key sequence, then prints the function bound to that
1602 sequence.
1603 exchange-point-and-mark (^X^X) (unbound) (unbound)
1605 Exchange the cursor position (point) with the position of the
1606 mark. Unless a negative prefix argument is given, the region
1607 between point and mark is activated so that it can be high‐
1608 lighted. If a zero prefix argument is given, the region is
1609 activated but point and mark are not swapped.
1610 execute-named-cmd (ESC-x) (:) (unbound)
1612 Read the name of an editor command and execute it. A restricted
1613 set of editing functions is available in the mini-buffer. Keys
1614 are looked up in the special command keymap, and if not found
1615 there in the main keymap. An interrupt signal, as defined by
1616 the stty setting, will abort the function. The allowed functions
1617 are: backward-delete-char, vi-backward-delete-char,
1618 clear-screen, redisplay, quoted-insert, vi-quoted-insert, back‐
1619 ward-kill-word, vi-backward-kill-word, kill-whole-line,
1620 vi-kill-line, backward-kill-line, list-choices,
1621 delete-char-or-list, complete-word, accept-line, expand-or-com‐
1622 plete and expand-or-complete-prefix.
1623 kill-region kills the last word, and vi-cmd-mode is treated the
1625 same as accept-line. The space and tab characters, if not bound
1626 to one of these functions, will complete the name and then list
1627 the possibilities if the AUTO_LIST option is set. Any other
1628 character that is not bound to self-insert or self-insert-unmeta
1629 will beep and be ignored. The bindings of the current insert
1630 mode will be used.
1631 Currently this command may not be redefined or called by name.
1633 execute-last-named-cmd (ESC-z) (unbound) (unbound)
1635 Redo the last function executed with execute-named-cmd.
1636 Currently this command may not be redefined or called by name.
1638 get-line (ESC-G ESC-g) (unbound) (unbound)
1640 Pop the top line off the buffer stack and insert it at the cur‐
1641 sor position.
1642 pound-insert (unbound) (#) (unbound)
1644 If there is no # character at the beginning of the buffer, add
1645 one to the beginning of each line. If there is one, remove a #
1646 from each line that has one. In either case, accept the current
1647 line. The INTERACTIVE_COMMENTS option must be set for this to
1648 have any usefulness.
1649 vi-pound-insert
1651 If there is no # character at the beginning of the current line,
1652 add one. If there is one, remove it. The INTERACTIVE_COMMENTS
1653 option must be set for this to have any usefulness.
1654 push-input
1656 Push the entire current multiline construct onto the buffer
1657 stack and return to the top-level (PS1) prompt. If the current
1658 parser construct is only a single line, this is exactly like
1659 push-line. Next time the editor starts up or is popped with
1660 get-line, the construct will be popped off the top of the buffer
1661 stack and loaded into the editing buffer.
1662 push-line (^Q ESC-Q ESC-q) (unbound) (unbound)
1664 Push the current buffer onto the buffer stack and clear the buf‐
1665 fer. Next time the editor starts up, the buffer will be popped
1666 off the top of the buffer stack and loaded into the editing buf‐
1667 fer.
1668 push-line-or-edit
1670 At the top-level (PS1) prompt, equivalent to push-line. At a
1671 secondary (PS2) prompt, move the entire current multiline con‐
1672 struct into the editor buffer. The latter is equivalent to
1673 push-input followed by get-line.
1674 read-command
1676 Only useful from a user-defined widget. A keystroke is read
1677 just as in normal operation, but instead of the command being
1678 executed the name of the command that would be executed is
1679 stored in the shell parameter REPLY. This can be used as the
1680 argument of a future zle command. If the key sequence is not
1681 bound, status 1 is returned; typically, however, REPLY is set to
1682 undefined-key to indicate a useless key sequence.
1683 recursive-edit
1685 Only useful from a user-defined widget. At this point in the
1686 function, the editor regains control until one of the standard
1687 widgets which would normally cause zle to exit (typically an
1688 accept-line caused by hitting the return key) is executed.
1689 Instead, control returns to the user-defined widget. The status
1690 returned is non-zero if the return was caused by an error, but
1691 the function still continues executing and hence may tidy up.
1692 This makes it safe for the user-defined widget to alter the com‐
1693 mand line or key bindings temporarily.
1694 The following widget, caps-lock, serves as an example.
1696 self-insert-ucase() {
1697 LBUFFER+=${(U)KEYS[-1]}
1698 }
1699 integer stat
1701 zle -N self-insert self-insert-ucase
1703 zle -A caps-lock save-caps-lock
1704 zle -A accept-line caps-lock
1705 zle recursive-edit
1707 stat=$?
1708 zle -A .self-insert self-insert
1710 zle -A save-caps-lock caps-lock
1711 zle -D save-caps-lock
1712 (( stat )) && zle send-break
1714 return $stat
1716 This causes typed letters to be inserted capitalised until
1717 either accept-line (i.e. typically the return key) is typed or
1718 the caps-lock widget is invoked again; the later is handled by
1719 saving the old definition of caps-lock as save-caps-lock and
1720 then rebinding it to invoke accept-line. Note that an error
1721 from the recursive edit is detected as a non-zero return status
1722 and propagated by using the send-break widget.
1723 redisplay (unbound) (^R) (^R)
1725 Redisplays the edit buffer.
1726 reset-prompt (unbound) (unbound) (unbound)
1728 Force the prompts on both the left and right of the screen to be
1729 re-expanded, then redisplay the edit buffer. This reflects
1730 changes both to the prompt variables themselves and changes in
1731 the expansion of the values (for example, changes in time or
1732 directory, or changes to the value of variables referred to by
1733 the prompt).
1734 Otherwise, the prompt is only expanded each time zle starts, and
1736 when the display as been interrupted by output from another part
1737 of the shell (such as a job notification) which causes the com‐
1738 mand line to be reprinted.
1739 send-break (^G ESC-^G) (unbound) (unbound)
1741 Abort the current editor function, e.g. execute-named-command,
1742 or the editor itself, e.g. if you are in vared. Otherwise abort
1743 the parsing of the current line.
1744 run-help (ESC-H ESC-h) (unbound) (unbound)
1746 Push the buffer onto the buffer stack, and execute the command
1747 `run-help cmd', where cmd is the current command. run-help is
1748 normally aliased to man.
1749 vi-set-buffer (unbound) (") (unbound)
1751 Specify a buffer to be used in the following command. There are
1752 35 buffers that can be specified: the 26 `named' buffers "a to
1753 "z and the nine `queued' buffers "1 to "9. The named buffers
1754 can also be specified as "A to "Z.
1755 When a buffer is specified for a cut command, the text being cut
1757 replaces the previous contents of the specified buffer. If a
1758 named buffer is specified using a capital, the newly cut text is
1759 appended to the buffer instead of overwriting it.
1760 If no buffer is specified for a cut command, "1 is used, and the
1762 contents of "1 to "8 are each shifted along one buffer; the con‐
1763 tents of "9 is lost.
1764 vi-set-mark (unbound) (m) (unbound)
1766 Set the specified mark at the cursor position.
1767 set-mark-command (^@) (unbound) (unbound)
1769 Set the mark at the cursor position. If called with a negative
1770 prefix argument, do not set the mark but deactivate the region
1771 so that it is no longer highlighted (it is still usable for
1772 other purposes). Otherwise the region is marked as active.
1773 spell-word (ESC-$ ESC-S ESC-s) (unbound) (unbound)
1775 Attempt spelling correction on the current word.
1776 undefined-key
1778 This command is executed when a key sequence that is not bound
1779 to any command is typed. By default it beeps.
1780 undo (^_ ^Xu ^X^U) (unbound) (unbound)
1782 Incrementally undo the last text modification.
1783 redo Incrementally redo undone text modifications.
1785 vi-undo-change (unbound) (u) (unbound)
1787 Undo the last text modification. If repeated, redo the modifi‐
1788 cation.
1789 what-cursor-position (^X=) (unbound) (unbound)
1791 Print the character under the cursor, its code as an octal, dec‐
1792 imal and hexadecimal number, the current cursor position within
1793 the buffer and the column of the cursor in the current line.
1794 where-is
1796 Read the name of an editor command and and print the listing of
1797 key sequences that invoke the specified command. A restricted
1798 set of editing functions is available in the mini-buffer. Keys
1799 are looked up in the special command keymap, and if not found
1800 there in the main keymap.
1801 which-command (ESC-?) (unbound) (unbound)
1803 Push the buffer onto the buffer stack, and execute the command
1804 `which-command cmd'. where cmd is the current command.
1805 which-command is normally aliased to whence.
1806 vi-digit-or-beginning-of-line (unbound) (0) (unbound)
1808 If the last command executed was a digit as part of an argument,
1809 continue the argument. Otherwise, execute vi-beginning-of-line.
1810
1812 The line editor has the ability to highlight characters or regions of
1813 the line that have a particular significance. This is controlled by
1814 the array parameter zle_highlight, if it has been set by the user.
1815 If the parameter contains the single entry none all highlighting is
1817 turned off. Note the parameter is still expected to be an array.
1818 Otherwise each entry of the array should consist of a word indicating a
1820 context for highlighting, then a colon, then a comma-separated list of
1821 the types of highlighting to apply in that context.
1822 The contexts available for highlighting are the following:
1824 default
1826 Any text within the command line not affected by any other high‐
1827 lighting. Text outside the editable area of the command line is
1828 not affected.
1829 isearch
1831 When one of the incremental history search widgets is active,
1832 the area of the command line matched by the search string or
1833 pattern.
1834 region The region between the cursor (point) and the mark as set with
1836 set-mark-command. The region is only highlighted if it is
1837 active, which is the case if set-mark-command or
1838 exchange-point-and-mark has been called and the line has not
1839 been subsequently modified. The region can be deactivated by
1840 calling set-mark-command with a negative prefix argument, or
1841 reactivated by calling exchange-point-and-mark with a zero pre‐
1842 fix argument. Note that whether or not the region is active has
1843 no effect on its use within widgets, it simply determines
1844 whether it is highlighted.
1845 special
1847 Individual characters that have no direct printable representa‐
1848 tion but are shown in a special manner by the line editor.
1849 These characters are described below.
1850 zle_highlight may contain additional fields for controlling how termi‐
1852 nal sequences to change colours are output. Each of the following is
1853 followed by a colon and a string in the same form as for key bindings.
1854 This will not be necessary for the vast majority of terminals as the
1855 defaults shown in parentheses are widely used.
1856 fg_start_code (\e[3)
1858 The start of the escape sequence for the foreground colour.
1859 This is followed by an ASCII digit representing the colour.
1860 fg_default_code (9)
1862 The number to use instead of the colour to reset the default
1863 foreground colour.
1864 fg_end_code (m)
1866 The end of the escape sequence for the foreground colour.
1867 bg_start_code (\e[4)
1869 The start of the escape sequence for the background colour.
1870 This is followed by an ASCII digit representing the colour.
1871 bg_default_code (9)
1873 The number to use instead of the colour to reset the default
1874 background colour.
1875 bg_end_code (m)
1877 The end of the escape sequence for the background colour.
1878 The available types of highlighting are the following. Note that not
1880 all types of highlighting are available on all terminals:
1881 none No highlighting is applied to the given context. It is not use‐
1883 ful for this to appear with other types of highlighting; it is
1884 used to override a default.
1885 fg=colour
1887 The foreground colour should be set to colour, a decimal integer
1888 or the name of one of the eight most widely-supported colours.
1889 Not all terminals support this and, of those that do, not all
1891 provide facilities to test the support, hence the user should
1892 decide based on the terminal type. Most terminals support the
1893 colours black, red, green, yellow, blue, magenta, cyan and
1894 white, which can be set by name. In addition. default may be
1895 used to set the terminal's default foreground colour. Abbrevia‐
1896 tions are allowed; b or bl selects black. Some terminals may
1897 generate additional colours if the bold attribute is also
1898 present.
1899 On recent terminals and on systems with an up-to-date terminal
1901 database the number of colours supported may be tested by the
1902 command `echotc Co'; if this succeeds, it indicates a limit on
1903 the number of colours which will be enforced by the line editor.
1904 The number of colours is in any case limited to 256 (i.e. the
1905 range 0 to 255).
1906 Colour is also known as color.
1908 bg=colour
1910 The background colour should be set to colour. This works simi‐
1911 larly to the foreground colour, except the background is not
1912 usually affected by the bold attribute.
1913 bold The characters in the given context are shown in a bold font.
1915 standout
1917 The characters in the given context are shown in the terminal's
1918 standout mode. The actual effect is specific to the terminal;
1919 on many terminals it is inverse video. On some such terminals,
1920 where the cursor does not blink it appears with standout mode
1921 negated, making it less than clear where the cursor actually is.
1922 On such terminals one of the other effects may be preferable for
1923 highlighting the region and matched search string.
1924 underline
1926 The characters in the given context are shown underlined. Some
1927 terminals show the foreground in a different colour instead; in
1928 this case whitespace will not be highlighted.
1929 The characters described above as `special' are as follows. The for‐
1931 matting described here is used irrespective of whether the characters
1932 are highlighted:
1933 ASCII control characters
1935 Control characters in the ASCII range are shown as `^' followed
1936 by the base character.
1937 Unprintable multibyte characters
1939 This item applies to control characters not in the ASCII range,
1940 plus other characters as follows. If the MULTIBYTE option is in
1941 effect, multibyte characters not in the ASCII character set that
1942 are reported as having zero width are treated as combining char‐
1943 acters when the option COMBINING_CHARS is on. If the option is
1944 off, or if a character appears where a combining character is
1945 not valid, the character is treated as unprintable.
1946 Unprintable multibyte characters are shown as a hexadecimal num‐
1948 ber between angle brackets. The number is the code point of the
1949 character in the wide character set; this may or may not be Uni‐
1950 code, depending on the operating system.
1951 If zle_highlight is not set or no value applies to a particular con‐
1953 text, the defaults applied are equivalent to
1954 zle_highlight=(region:standout special:standout
1956 isearch:underline)
1957 i.e. both the region and special characters are shown in standout mode.
1959 Within widgets, arbitrary regions may be highlighted by setting the
1961 special array parameter region_highlight; see above.
1962zsh 4.3.10 June 1, 2009 ZSHZLE(1)