diff options
Diffstat (limited to 'Doc/Zsh/zle.yo')
| -rw-r--r-- | Doc/Zsh/zle.yo | 87 |
1 files changed, 58 insertions, 29 deletions
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index 2d7756859..2a907c52c 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -252,6 +252,9 @@ Bind each var(in-string) to each var(out-string). When var(in-string) is typed, var(out-string) will be pushed back and treated as input to the line editor. When tt(-R) is also used, interpret the var(in-string)s as ranges. + +Note that both var(in-string) and var(out-string) are subject to the same +form of interpretation, as described below. ) item(var(in-string command) ...)( Bind each var(in-string) to each var(command). @@ -492,26 +495,35 @@ Only available if your system supports one of the `poll' or `select' system calls; most modern systems do. Installs var(handler) (the name of a shell function) to handle input from -file descriptor var(fd). When zle is attempting to read data, it will -examine both the terminal and the list of handled var(fd)'s. If data -becomes available on a handled var(fd), zle will call var(handler) with -the fd which is ready for reading as the only argument. If the handler -produces output to the terminal, it should call `tt(zle -I)' before doing -so (see below). The handler should not attempt to read from the terminal. -Note that zle makes no attempt to check whether this fd is actually +file descriptor var(fd). Installing a handler for an var(fd) which is +already handled causes the existing handler to be replaced. Any number of +handlers for any number of readable file descriptors may be installed. +Note that zle makes no attempt to check whether this var(fd) is actually readable when installing the handler. The user must make their own arrangements for handling the file descriptor when zle is not active. -If the option tt(-w) is also given, the var(handler) is instead a -line editor widget, typically a shell function made into a widget using -tt(zle -N). In that case var(handler) can use all the facilities of -zle to update the current editing line. Note, however, that as handling -var(fd) takes place at a low level changes to the display will not -automatically appear; the widget should call tt(zle -R) to force redisplay. - -Any number of handlers for any number of readable file descriptors may be -installed. Installing a handler for an var(fd) which is already handled -causes the existing handler to be replaced. +When zle is attempting to read data, it will examine both the terminal and +the list of handled var(fd)'s. If data becomes available on a handled +var(fd), zle calls var(handler) with the fd which is ready for reading +as the first argument. Under normal circumstances this is the only +argument, but if an error was detected, a second argument provides +details: `tt(hup)' for a disconnect, `tt(nval)' for a closed or otherwise +invalid descriptor, or `tt(err)' for any other condition. Systems that +support only the `select' system call always use `tt(err)'. + +If the option tt(-w) is also given, the var(handler) is instead a line +editor widget, typically a shell function made into a widget using +`tt(zle -N)'. In that case var(handler) can use all the facilities of zle +to update the current editing line. Note, however, that as handling var(fd) +takes place at a low level changes to the display will not automatically +appear; the widget should call `tt(zle -R)' to force redisplay. As of this +writing, widget handlers only support a single argument and thus are never +passed a string for error state, so widgets must be prepared to test the +descriptor themselves. + +If either type of handler produces output to the terminal, it should call +`tt(zle -I)' before doing so (see below). Handlers should not attempt to +read from the terminal. If no var(handler) is given, but an var(fd) is present, any handler for that var(fd) is removed. If there is none, an error message is printed @@ -526,7 +538,8 @@ silently return status 1. Note that this feature should be used with care. Activity on one of the var(fd)'s which is not properly handled can cause the terminal to become -unusable. +unusable. Removing an var(fd) handler from within a signal trap may cause +unpredictable behavior. Here is a simple example of using this feature. A connection to a remote TCP port is created using the ztcp command; see @@ -536,6 +549,7 @@ which simply prints out any data which arrives on this connection. Note that `select' will indicate that the file descriptor needs handling if the remote side has closed the connection; we handle that by testing for a failed read. + example(if ztcp pwspc 2811; then tcpfd=$REPLY handler+LPAR()RPAR() { @@ -716,17 +730,18 @@ vindex(CONTEXT) item(tt(CONTEXT) (scalar))( The context in which zle was called to read a line; read-only. One of the values: + startitem() -item(start)( +item(tt(start))( The start of a command line (at prompt tt(PS1)). ) -item(cont)( +item(tt(cont))( A continuation to a command line (at prompt tt(PS2)). ) -item(select)( +item(tt(select))( In a tt(select) loop. ) -item(vared)( +item(tt(vared))( Editing a variable in tt(vared). ) enditem() @@ -863,21 +878,21 @@ is needed for character indexing to include tt(PREDISPLAY). Each string consists of the following parts: -startlist() -list(Optionally, a `tt(P)' to signify that the start and end offset that +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)'.) -list(A start offset in the same units as tt(CURSOR), terminated by +itemiz(A start offset in the same units as tt(CURSOR), terminated by whitespace.) -list(An end offset in the same units as tt(CURSOR), terminated by +itemiz(An end offset in the same units as tt(CURSOR), terminated by whitespace.) -list(A highlight specification in the same format as +itemiz(A highlight specification in the same format as used for contexts in the parameter tt(zle_highlight), ifnzman(noderef(Character Highlighting))\ ifzman(see Character Highlighting below); for example, tt(standout) or tt(fg=red,bold)). -endlist() +enditemize() For example, @@ -1293,8 +1308,11 @@ item(tt(redisplay))( Redisplay the command line, remaining in incremental search mode. ) item(tt(vi-cmd-mode))( -Toggle between the `tt(main)' and `tt(vicmd)' keymaps; +Select the `tt(vicmd)' keymap; the `tt(main)' keymap (insert mode) will be selected initially. + +In addition, the modifications that were made while in vi insert mode are +merged to form a single undo event. ) xitem(tt(vi-repeat-search)) item(tt(vi-rev-repeat-search))( @@ -2191,6 +2209,13 @@ tindex(spell-word) item(tt(spell-word) (ESC-$ ESC-S ESC-s) (unbound) (unbound))( Attempt spelling correction on the current word. ) +tindex(split-undo) +item(tt(split-undo))( +Breaks the undo sequence at the current change. This is useful in vi mode as +changes made in insert mode are coalesced on entering command mode. Similarly, +tt(undo) will normally revert as one all the changes made by a user-defined +widget. +) tindex(undefined-key) item(tt(undefined-key))( This command is executed when a key sequence that is not bound to any @@ -2202,6 +2227,10 @@ Incrementally undo the last text modification. When called from a user-defined widget, takes an optional argument indicating a previous state of the undo history as returned by the tt(UNDO_CHANGE_NO) variable; modifications are undone until that state is reached. + +Note that when invoked from vi command mode, the full prior change made in +insert mode is reverted, the changes having been merged when command mode was +selected. ) tindex(redo) item(tt(redo))( |