Non-patch: zle argument handling

[Peter Stephenson <pws@ibmth.df.unipi.it>]

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 <number>.
  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 <pws@ibmth.df.unipi.it>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy