Non-patch: zle argument handling

Non-patch: zle argument handling

[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 <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

Re: Non-patch: zle argument handling

[Bart Schaefer]

On Jun 20,  4:31pm, Peter Stephenson wrote:
} Subject: Non-patch: zle argument handling
}
} Here is what I think I've done:

Sounds good to me.

} Another possible suggestion: We could remove all the feep()'s from the code
} and feep() if and only if the widget returned 1.

I like this idea.

} 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.

I presume that in this scheme an un-suppressed feep() would abort the
widget, as I believe currently happens?

} (By the way, what does feep mean?)

It means "failure beep."  (Actually, it probably just means "beep", but
I think some curses packages already have a beep() function so PF had to
pick a different name.)

} --- 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.
}  )

How about:

   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.
  +When called from a zle widget, zle is used to read from the terminal.

However, I don't see what possible difference this makes, as only one key
is read in any case, and it's still going to be interpreted as either `y'
for `yes' or anything else for `no'.

}  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.
}  )

Does this imply when called from that var(num) is ignored and exactly one
key is read regardless?  That seems broken to me.  If that's not what it
means, then what difference does it make that zle is involved?  Things
should only get documented if they are visible behavior changes; and then
what you need to document is the behavior, not the implementation.

} +++ 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.

Again, what does it *mean* to "use the appropriate key input mechanism"?

Otherwise this stuff all looks great.

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Re: Non-patch: zle argument handling

[Peter Stephenson]

"Bart Schaefer" wrote:
> } 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.
> 
> I presume that in this scheme an un-suppressed feep() would abort the
> widget, as I believe currently happens?

Actually, it doesn't seem to at the moment.  I haven't been keeping track
of this, so I don't know if it's changed, but
  testwidget() { zle transpose-words; LBUFFER="${LBUFFER}Ha."; }
both beeps and inserts "Ha." when there's only one word on the line.
On the other hand, with an `&&' between the two it now works as expected
--- this is certainly new and is now the favo[u]red mechanism for returning
early.

> }  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.
> }  )
> 
> Does this imply when called from that var(num) is ignored and exactly one
> key is read regardless?  That seems broken to me.  If that's not what it
> means, then what difference does it make that zle is involved?  Things
> should only get documented if they are visible behavior changes; and then
> what you need to document is the behavior, not the implementation.

No, var(num) is still used.  The difference is that it now works with zle.
The version below is simplified.

--- /temp/pws/zsh-3.1.5/Doc/Zsh/builtins.yo.a2	Mon Jun 21 09:16:32 1999
+++ /temp/pws/zsh-3.1.5/Doc/Zsh/builtins.yo	Mon Jun 21 09:28:19 1999
@@ -682,15 +682,13 @@
 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.
+This option may also be used within zle widgets.
 )
 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.  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.
+is present.  This option may also be used within zle widgets.
 )
 item(tt(-z))(
 Read one entry from the editor buffer stack and assign it to the first
--- /temp/pws/zsh-3.1.5/Doc/Zsh/zle.yo.a2	Mon Jun 21 09:20:35 1999
+++ /temp/pws/zsh-3.1.5/Doc/Zsh/zle.yo	Mon Jun 21 09:21:04 1999
@@ -103,8 +103,7 @@
 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
+input.  Finally, they can examine and edit the ZLE buffer being edited by
 reading and setting the special parameters described below.
 
 cindex(parameters, 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

RE: Non-patch: zle argument handling

[Andrej Borsenkow]

>
> Andrej Borsenkow wrote:
>
> > Related question - is it possible to use minibuffer from
> user-defined widgets?
> > Is it useful? Or it can be implemented with current changes to read?
>
> My little isearch example did that: with a combination of `read -k'
> and `zle -R "search: $str"' (the argument of `-R' is displayed in the
> statusline).
>
>

You cannot edit input with read -k.

bor@itsrm2:~%> foo() {
function> read -k 4 test
function> print $#test
function> }
bor@itsrm2:~%> foo
12^H^H4

So, either widget should make all edtiting itself, or we need some way to
dispatch on input key sequences (to call normal editing widget) or (better yet)
to use minibuffer with builtin editing.

/andrej

RE: Non-patch: zle argument handling

[Sven Wischnowsky]

Andrej Borsenkow wrote:

> Related question - is it possible to use minibuffer from user-defined widgets?
> Is it useful? Or it can be implemented with current changes to read?

My little isearch example did that: with a combination of `read -k'
and `zle -R "search: $str"' (the argument of `-R' is displayed in the
statusline).


Bye
 Sven


--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de

RE: Non-patch: zle argument handling

[Andrej Borsenkow]

>
> Of course it reads multiple keys (and without `-[kq]' it reads anything
> up to the next `\n').
> Maybe we should just say that `read' also works inside zle widgets? Or
> would every user expect this? Does everyone know about `read'? We had
> some questions about accessing the command line inside completion
> functions after all. Maybe we should just say that keys can be read
> inside zle widgets in the zle docs?
>
> Btw.: do we want to have a way to read a key sequence (relative to a
> keymap)? A way to look up a key (-sequence) in a keymap?
>


Related question - is it possible to use minibuffer from user-defined widgets?
Is it useful? Or it can be implemented with current changes to read?

/andrej

Re: Non-patch: zle argument handling

[Sven Wischnowsky]

Peter Stephenson wrote:

> 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.

As far as I can see now, it looks good.

> - Sven's read builtin changes

I was thinking about this some more. Maybe we should make this return
key in the same way as they are reported by the `keys' special
parameter? I.e. `C-a' instead of ASCII-1.
Maybe I'll produce a patch for this sometime this week so we can play
with it...

> - Sven's zle -R change

There are other things along this line we might want to think
of. E.g.: a way to put the cursor under the command line (a la
trashzle()). Probably even a way to redisplay the prompt after that
and saying that we have just printed n lines (I'm talking about
user-programmable alwayslastprompt-behavior).

> - 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.)

I didn't like that either, I was just too lazy to implement more
sophisticated argument handling.

> 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.

That's ok for me.

> 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?)

No opinion here -- I always switch off all [bf]eeps.

Bart Schaefer wrote:

> Does this imply when called from that var(num) is ignored and exactly one
> key is read regardless?  That seems broken to me.  If that's not what it
> means, then what difference does it make that zle is involved?  Things
> should only get documented if they are visible behavior changes; and then
> what you need to document is the behavior, not the implementation.

Of course it reads multiple keys (and without `-[kq]' it reads anything
up to the next `\n').
Maybe we should just say that `read' also works inside zle widgets? Or 
would every user expect this? Does everyone know about `read'? We had
some questions about accessing the command line inside completion
functions after all. Maybe we should just say that keys can be read
inside zle widgets in the zle docs?

Btw.: do we want to have a way to read a key sequence (relative to a
keymap)? A way to look up a key (-sequence) in a keymap?

Bye
 Sven


--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de