diff options
Diffstat (limited to 'Doc/Zsh/zle.yo')
| -rw-r--r-- | Doc/Zsh/zle.yo | 87 |
1 files changed, 59 insertions, 28 deletions
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index c928b8ca2..2d033a0a1 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -50,13 +50,15 @@ argument causes the next command entered to be repeated the specified number of times, unless otherwise noted below; this is implemented by the tt(digit-argument) widget. See also ifzman(the em(Arguments) subsection of the em(Widgets) section )\ -ifnzman(noderef(Arguments) )\ +ifnzman(noderef(Arguments))\ for some other ways the numeric argument can be modified. startmenu() menu(Keymaps) menu(Zle Builtins) menu(Zle Widgets) +menu(User-Defined Widgets) +menu(Standard Widgets) menu(Character Highlighting) endmenu() @@ -107,6 +109,7 @@ In the `tt(.safe)' keymap, each single key is bound to tt(self-insert), except for ^J (line feed) and ^M (return) which are bound to tt(accept-line). This is deliberately not pleasant to use; if you are using it, it means you deleted the main keymap, and you should put it back. + subsect(Reading Commands) When ZLE is reading a command from the terminal, it may read a sequence that is bound to some command and is also a prefix of a longer bound string. @@ -137,6 +140,7 @@ in user-defined widgets with the tt(read-command) widget, described in ifzman(the subsection `Miscellaneous' of the section `Standard Widgets' below)\ ifnzman(noderef(Miscellaneous) below)\ . + subsect(Local Keymaps) cindex(local keymaps) While for normal editing a single keymap is used exclusively, in many @@ -415,7 +419,7 @@ xitem(tt(zle) tt(-K) var(keymap)) xitem(tt(zle) tt(-F) [ tt(-L) | tt(-w) ] [ var(fd) [ var(handler) ] ]) xitem(tt(zle) tt(-I)) xitem(tt(zle) tt(-T) [ tt(tc) var(function) | tt(-r) tt(tc) | tt(-L) ] ) -item(tt(zle) var(widget) [ tt(-n) var(num) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)( +item(tt(zle) var(widget) [ tt(-n) var(num) ] [ tt(-f) var(flag) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)( The tt(zle) builtin performs a number of different actions concerning ZLE. @@ -501,8 +505,7 @@ ifnzman(noderef(Completion Widgets))\ . ) item(tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ])( -Redisplay the command line; this is to be called from within a user-defined -widget to allow changes to become visible. If a var(display-string) is +Redisplay the command line. If a var(display-string) is given and not empty, this is shown in the status line (immediately below the line being edited). @@ -511,9 +514,9 @@ prompt in the same way as completion lists are printed. If no var(string)s are given but the tt(-c) option is used such a list is cleared. -Note that this option is only useful for widgets that do not exit -immediately after using it because the strings displayed will be erased -immediately after return from the widget. +Note that immediately after returning from running widgets, the command line +will be redisplayed and the strings displayed will be erased. Therefore, this +option is only useful for widgets that do not exit immediately after using it. This command can safely be called outside user defined widgets; if zle is active, the display will be refreshed, while if zle is not active, the @@ -683,7 +686,7 @@ optional argument for debugging or testing. Note that this transformation is not applied to other non-printing characters such as carriage returns and newlines. ) -item(var(widget) [ tt(-n) var(num) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)( +item(var(widget) [ tt(-n) var(num) ] [ tt(-f) var(flag) ] [ tt(-Nw) ] [ tt(-K) var(keymap) ] var(args) ...)( Invoke the specified var(widget). This can only be done when ZLE is active; normally this will be within a user-defined widget. @@ -702,6 +705,9 @@ appears as if the top-level widget called by the user were still active. With the option tt(-w), tt(WIDGET) and related parameters are set to reflect the widget being executed by the tt(zle) call. +Normally, when var(widget) returns the special parameter tt(LASTWIDGET) will +point to it. This can be inhibited by passing the option tt(-f nolast). + Any further arguments will be passed to the widget; note that as standard argument handling is performed, any general argument list should be preceded by tt(-)tt(-). If it is a shell @@ -726,15 +732,17 @@ enditem() ) enditem() -texinode(Zle Widgets)(Character Highlighting)(Zle Builtins)(Zsh Line Editor) -sect(Widgets) +texinode(Zle Widgets)(User-Defined Widgets)(Zle Builtins)(Zsh Line Editor) +sect(Zle Widgets) cindex(widgets) All actions in the editor are performed by `widgets'. A widget's job is simply to perform some small action. The ZLE commands that key sequences in keymaps are bound to are in fact widgets. Widgets can be user-defined or built in. -The standard widgets built into ZLE are listed in Standard Widgets below. +The standard widgets built into ZLE are listed in +ifzman(the section `Standard Widgets' below)\ +ifnzman(noderef(Standard Widgets)). Other built-in widgets can be defined by other modules (see ifzman(zmanref(zshmodules))\ ifnzman(noderef(Zsh Modules))\ @@ -748,6 +756,8 @@ as shell functions. When the widget is executed, the corresponding shell function is executed, and can perform editing (or other) actions. It is recommended that user-defined widgets should not have names starting with `tt(.)'. + +texinode(User-Defined Widgets)(Standard Widgets)(Zle Widgets)(Zsh Line Editor) sect(User-Defined Widgets) cindex(widgets, user-defined) User-defined widgets, being implemented as shell functions, @@ -974,27 +984,39 @@ of the non-editable parts of the command line in tt(PREDISPLAY) and tt(POSTDISPLAY) are possible, but note that the tt(P) flag is needed for character indexing to include tt(PREDISPLAY). -Each string consists of the following parts: +Each string consists of the following whitespace-separated parts: startitemize() itemiz(Optionally, a `tt(P)' to signify that the start and end offset that follow include any string set by the tt(PREDISPLAY) special parameter; this is needed if the predisplay string itself is to be highlighted. -Whitespace may follow the `tt(P)'.) -itemiz(A start offset in the same units as tt(CURSOR), terminated by -whitespace.) -itemiz(An end offset in the same units as tt(CURSOR), terminated by -whitespace.) +Whitespace between the `tt(P)' and the start offset is optional.) +itemiz(A start offset in the same units as tt(CURSOR).) +itemiz(An end offset in the same units as tt(CURSOR).) itemiz(A highlight specification in the same format as used for contexts in the parameter tt(zle_highlight), see ifnzman(noderef(Character Highlighting))\ ifzman(the section `Character Highlighting' below); -for example, tt(standout) or tt(fg=red,bold)). +for example, tt(standout) or tt(fg=red,bold).) +itemiz(Optionally, a string of the form `tt(memo=)var(token)'. +The var(token) consists of everything between the `tt(=)' and the next +whitespace, comma, NUL, or the end of the string. +The var(token) is preserved verbatim but not parsed in any way. + +Plugins may use this to identify array elements they have added: for example, +a plugin might set var(token) to its (the plugin's) name and then use +`tt(region_highlight=+LPAR() ${region_highlight:#*memo=)var(token)tt(} +RPAR())' +in order to remove array elements it have added. + +(This example uses the `tt(${)var(name)tt(:#)var(pattern)tt(})' array-grepping +syntax described in +ifzman(the section `Parameter Expansion' in zmanref(zshexpn))\ +ifnzman(noderef(Parameter Expansion)).)) enditemize() For example, -example(region_highlight=("P0 20 bold")) +example(region_highlight=("P0 20 bold memo=foobar")) specifies that the first twenty characters of the text including any predisplay string should be highlighted in bold. @@ -1002,6 +1024,14 @@ any predisplay string should be highlighted in bold. Note that the effect of tt(region_highlight) is not saved and disappears as soon as the line is accepted. +Note that zsh 5.8 and older do not support the `tt(memo=)var(token)' field +and may misparse the third (highlight specification) field when a memo +is given. +COMMENT(The syntax `tt(0 20 bold, memo=foobar)' (with an auxiliary comma) +happens to work on both zsh <=5.8 and zsh 5.9-to-be, but that seems to be more of +an accident of implementation than something we should make a first-class-citizen +API promise. It's mentioned in the "Incompatibilities" section of README.) + The final highlighting on the command line depends on both tt(region_highlight) and tt(zle_highlight); see ifzman(the section CHARACTER HIGHLIGHTING below)\ @@ -1184,6 +1214,7 @@ This can be used for detecting switches between the vi command ) enditem() +texinode(Standard Widgets)(Character Highlighting)(User-Defined Widgets)(Zsh Line Editor) sect(Standard Widgets) cindex(widgets, standard) The following is a list of all the standard widgets, @@ -1209,7 +1240,7 @@ menu(Completion) menu(Miscellaneous) menu(Text Objects) endmenu() -texinode(Movement)(History Control)()(Zle Widgets) +texinode(Movement)(History Control)()(Standard Widgets) subsect(Movement) startitem() tindex(vi-backward-blank-word) @@ -1356,7 +1387,7 @@ item(tt(up-line) (unbound) (unbound) (unbound))( Move up a line in the buffer. ) enditem() -texinode(History Control)(Modifying Text)(Movement)(Zle Widgets) +texinode(History Control)(Modifying Text)(Movement)(Standard Widgets) subsect(History Control) startitem() tindex(beginning-of-buffer-or-history) @@ -1704,7 +1735,7 @@ the numeric argument. Zero for both local and imported lines and nonzero for only local lines. ) enditem() -texinode(Modifying Text)(Arguments)(History Control)(Zle Widgets) +texinode(Modifying Text)(Arguments)(History Control)(Standard Widgets) subsect(Modifying Text) startitem() tindex(vi-add-eol) @@ -2030,7 +2061,7 @@ into the kill buffer. Arguably, this is what Y should do in vi, but it isn't what it actually does. ) enditem() -texinode(Arguments)(Completion)(Modifying Text)(Zle Widgets) +texinode(Arguments)(Completion)(Modifying Text)(Standard Widgets) subsect(Arguments) startitem() tindex(digit-argument) @@ -2078,7 +2109,7 @@ example(zle argument-base 16 zle universal-argument) ) enditem() -texinode(Completion)(Miscellaneous)(Arguments)(Zle Widgets) +texinode(Completion)(Miscellaneous)(Arguments)(Standard Widgets) subsect(Completion) startitem() tindex(accept-and-menu-complete) @@ -2153,7 +2184,7 @@ When a previous completion displayed a list below the prompt, this widget can be used to move the prompt below the list. ) enditem() -texinode(Miscellaneous)(Text Objects)(Completion)(Zle Widgets) +texinode(Miscellaneous)(Text Objects)(Completion)(Standard Widgets) subsect(Miscellaneous) startitem() tindex(accept-and-hold) @@ -2200,7 +2231,7 @@ item(tt(beep))( Beep, unless the tt(BEEP) option is unset. ) tindex(bracketed-paste) -item(tt(bracketed-paste))( +item(tt(bracketed-paste) (tt(^[[200~)) (tt(^[[200~)) (tt(^[[200~)))( This widget is invoked when text is pasted to the terminal emulator. It is not intended to be bound to actual keys but instead to the special sequence generated by the terminal emulator when text is pasted. @@ -2551,7 +2582,7 @@ If the last command executed was a digit as part of an argument, continue the argument. Otherwise, execute vi-beginning-of-line. ) enditem() -texinode(Text Objects)()(Miscellaneous)(Zle Widgets) +texinode(Text Objects)()(Miscellaneous)(Standard Widgets) subsect(Text Objects) cindex(text objects) Text objects are commands that can be used to select a block of text @@ -2596,7 +2627,7 @@ argument, multiple words will be selected. ) enditem() -texinode(Character Highlighting)()(Zle Widgets)(Zsh Line Editor) +texinode(Character Highlighting)()(Standard Widgets)(Zsh Line Editor) sect(Character Highlighting) vindex(zle_highlight, setting) |