From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 2878 invoked from network); 20 Jun 1999 15:00:30 -0000 Received: from sunsite.auc.dk (130.225.51.30) by ns1.primenet.com.au with SMTP; 20 Jun 1999 15:00:30 -0000 Received: (qmail 9108 invoked by alias); 20 Jun 1999 15:00:06 -0000 Mailing-List: contact zsh-workers-help@sunsite.auc.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 6726 Received: (qmail 9083 invoked from network); 20 Jun 1999 15:00:04 -0000 Message-Id: <9906201431.AA13678@ibmth.df.unipi.it> To: zsh-workers@sunsite.auc.dk (Zsh hackers list) Subject: Non-patch: zle argument handling Date: Sun, 20 Jun 1999 16:31:28 +0200 From: Peter Stephenson I've merged Sven's (6616) and my (6609) work on zle widget arguments. The nuts and bolts are more or less Sven's, which got the return status of the functions correct. It's a big change because of that, but I think it's necessary if we're going to allow serious zle programming. I haven't bothered sending a patch for the merged changes, which will appear in pws-23, if I haven't lost count, but below are the documentation changes only (Sven, please look and see if I've missed any of your changes which I claim to have included) --- don't apply this, except to read, since there aren't any code changes to go with it. Here is what I think I've done: - All Sven's basic argument and return value handling. - Sven's changes for {vi-},history-search-{for,back}ward, which do a complete search without I/O, and my changes for the isearch commands which prime the input buffer then give the user control --- these complement each other nicely. - Sven's read builtin changes - Sven's zle -R change - My change to specify a numeric argument to zle with -N or -n . I didn't like "zle widget '' args" to call a widget with argument args using the current numeric argument, since it's unclear and error-prone. (This means the zle calls in Sven's example isearch function need changing.) - My bug fix to feep() if digit-argument finds that the last key pressed wasn't a digit. - My (somewhat superfluous) universal-argument change I have not included: - Any way of aliasing widgets. You need to defined a function to do anything like this. We can add something like this if and when we decide it's necessary. Another possible suggestion: We could remove all the feep()'s from the code and feep() if and only if the widget returned 1. For user-defined widgets, we could have a special function to allow them to feep and a special option to zle that will suppress the feep for any other widget, so that simple zle -N's work without extra error handling. If there are times we need to return 1 internally but not feep, we could return 2 instead; that would also allow a widget to know if a function had failed but not feeped. (By the way, what does feep mean?) --- Doc/Zsh/builtins.yo.argdoc Thu Jun 17 16:53:03 1999 +++ Doc/Zsh/builtins.yo Sun Jun 20 16:09:55 1999 @@ -682,12 +682,15 @@ With this flag set the return value is zero only if the character was `tt(y)' or `tt(Y)'. Note that this always reads from the terminal, even if used with the tt(-p) or tt(-u) or tt(-z) flags or with redirected input. +May be called from a zle widget, in which case it will use zle to retrieve +a key. ) item(tt(-k) [ var(num) ])( Read only one (or var(num)) characters. All are assigned to the first var(name), without word splitting. This flag is ignored when tt(-q) is present. Input is read from the terminal unless one of tt(-u) or tt(-p) -is present. +is present. May be called from a zle widget with no tt(-u) +or tt(-p) argument, in which case it will use zle to retrieve a key. ) item(tt(-z))( Read one entry from the editor buffer stack and assign it to the first --- Doc/Zsh/mod_zle.yo.argdoc Thu Jun 17 14:01:38 1999 +++ Doc/Zsh/mod_zle.yo Sun Jun 20 16:13:07 1999 @@ -166,7 +166,8 @@ xitem(tt(zle) tt(-A) var(old-widget) var(new-widget)) xitem(tt(zle) tt(-N) var(widget) [ var(function) ]) xitem(tt(zle) tt(-C) var(widget) var(completion-widget) var(function)) -item(tt(zle) var(widget))( +xitem(tt(zle) tt(-R) [ var(display-string) ]) +item(tt(zle) var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)( The tt(zle) builtin performs a number of different actions concerning ZLE. Which operation it performs depends on its options: @@ -191,7 +192,11 @@ specified name, it is overwritten. When the new widget is invoked from within the editor, the specified shell var(function) is called. If no function name is specified, it defaults to -the same name as the widget. +the same name as the widget. For further information, see the section +em(Widgets) in +ifzman(zmanref(zshzle))\ +ifnzman(noderef(Zsh Line Editor))\ +. ) item(tt(-C) var(widget) var(completion-widget) var(function))( Create a user-defined completion widget names var(widget). The @@ -203,9 +208,33 @@ ifnzman(noderef(Completion Widgets))\ . ) -item(var(widget))( +item(tt(-R) [ var(display-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 +given, this is shown in the status line (immediately below the line being +edited). +) +item(var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)( Invoke the specified widget. This can only be done when ZLE is active; normally this will be within a user-defined widget. + +With the options tt(-n) and tt(-N), the current numerical argument will be +saved and then restored after the call to tt(widget); `tt(-n) var(num)' +sets the numerical argument temporarily to var(num), while `tt(-N)' sets it +to the default, i.e. as if there were none. + +Any further arguments will be passed to the widget. If it is a shell +function, these are passed down as postional parameters; for builtin +widgets it is up to the widget in question what it does with them. +Currently arguments are only handled by the incremental-search commands, +the tt(history-search-forward) and tt(-backward) and the corresponding +functions prefixed by tt(vi-), and by tt(universal-argument). No error is +flagged if the command does not use the arguments, or only uses some of +them. + +The return status reflects the success or failure of the operation carried +out by the widget, or if it is a user-defined widget the return status of +the shell function. ) enditem() ) --- Doc/Zsh/zle.yo.argdoc Thu Jun 17 13:52:55 1999 +++ Doc/Zsh/zle.yo Sun Jun 20 16:27:38 1999 @@ -102,6 +102,8 @@ User-defined widgets, being implemented as shell functions, can execute any normal shell command. They can also run other widgets (whether built-in or user-defined) using the tt(zle) builtin command. +They can use tt(read -k) or tt(read -q) to read characters from standard +input, which will use the appropriate tt(zle) key input mechanism. Finally, they can examine and edit the ZLE buffer being edited by reading and setting the special parameters described below. @@ -350,6 +352,10 @@ Move down a line in the buffer, or if already at the bottom line, search forward in the history for a line beginning with the first word in the buffer. + +If called from a function by the tt(zle) command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. ) tindex(down-history) item(tt(down-history) (unbound) (^N) (unbound))( @@ -418,6 +424,17 @@ is not bound to one of the above functions, or tt(self-insert) or tt(self-insert-unmeta), will have the same effect but the function will be executed. + +When called from a widget function by the tt(zle) command, the incremental +search commands can take a string argument. This will be treated as a +string of keys, as for arguments to the tt(bindkey) command, and used as +initial input for the command. Any characters in the string which are +unused by the incremental search will be silently ignored. For example, + +example(zle history-incremental-search-backward forceps) + +will search backwards for tt(forceps), leaving the minibuffer containing +the string `tt(forceps)'. ) tindex(history-incremental-search-forward) item(tt(history-incremental-search-forward) (^S ^Xs) (unbound) (unbound))( @@ -431,6 +448,10 @@ item(tt(history-search-backward) (ESC-P ESC-p) (unbound) (unbound))( Search backward in the history for a line beginning with the first word in the buffer. + +If called from a function by the tt(zle) command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. ) tindex(vi-history-search-backward) item(tt(vi-history-search-backward) (unbound) (/) (unbound))( @@ -458,18 +479,27 @@ Any other character that is not bound to self-insert or self-insert-unmeta will beep and be ignored. If the function is called from vi command mode, the bindings of the current insert mode will be used. + +If called from a function by the tt(zle) command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. ) tindex(history-search-forward) item(tt(history-search-forward) (ESC-N ESC-n) (unbound) (unbound))( Search forward in the history for a line beginning with the first word in the buffer. + +If called from a function by the tt(zle) command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. ) tindex(vi-history-search-forward) item(tt(vi-history-search-forward) (unbound) (?) (unbound))( Search forward in the history for a specified string. The string may begin with `tt(^)' to anchor the search to the beginning of the line. The functions available in the mini-buffer are the same -as for tt(vi-history-search-backward). +as for tt(vi-history-search-backward). Argument handling is also the same +as for that command. ) tindex(infer-next-history) item(tt(infer-next-history) (^X^N) (unbound) (unbound))( @@ -508,6 +538,10 @@ Move up a line in the buffer, or if already at the top line, search backward in the history for a line beginning with the first word in the buffer. + +If called from a function by the tt(zle) command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. ) tindex(up-history) item(tt(up-history) (unbound) (^P) (unbound))( @@ -804,7 +838,11 @@ tindex(digit-argument) item(tt(digit-argument) (ESC-0..ESC-9) (1-9) (unbound))( Start a new numeric argument, or add to the current one. -See also tt(vi-digit-or-beginning-of-line). +See also tt(vi-digit-or-beginning-of-line). This only works if bound to a +key sequence ending in a decimal digit. + +Inside a widget function, a call to this function treats the last key of +the key sequence which called the widget as the digit. ) tindex(neg-argument) item(tt(neg-argument) (ESC--) (unbound) (unbound))( @@ -819,6 +857,10 @@ twice, followed immediately by tt(forward-char), move forward sixteen spaces; if instead it is followed by tt(-2), then tt(forward-char), move backward two spaces. + +Inside a widget function, if passed an argument, i.e. `tt(zle +universal-argument) var(num)', the numerical argument will be set to +var(num); this is equivalent to `tt(NUMERIC=)var(num)'. ) enditem() texinode(Completion)(Miscellaneous)(Arguments)(Zsh Line Editor) -- Peter Stephenson Tel: +39 050 844536 WWW: http://www.ifh.de/~pws/ Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy