Re: prevent some lines directly coming from the history from being executed

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Vincent Lefevre wrote on Sat, May 28, 2022 at 02:07:20 +0200:
> On 2022-05-27 12:40:32 +0000, Daniel Shahaf wrote:
> > Peter Stephenson wrote on Thu, 26 May 2022 16:13 +00:00:
> > >> On 26 May 2022 at 16:53 Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx> wrote:
> > >> Vincent Lefevre wrote on Thu, May 26, 2022 at 16:36:02 +0200:
> > >> > When searching the man pages, I could find only one place where
> > >> > such a built-in is used: in the example for recursive-edit.
> > >>...
> > >> but, yes, it should be mentioned in the zle documentation too, not only
> > >> in the compsys documentation.
> > >> 
> > >> Anyone volunteering to write the patch?
> > >
> > > zle.yo contains the following.  We don't have the actual names for
> > > all the widgets, which makes them hard to search for, but the actual
> > > rule is very simple once you know it.  So while this isn't ideal I'm
> > > not sure what we'd want to change.
> 
> This is in Section "ZLE WIDGETS". But since this is specific to
> the standard widgets, shouldn't this be also at the beginning of
> Section "STANDARD WIDGETS"?
> 

The next paragraph recommends that user-defined widgets not be named
with leading dots.  That wouldn't belong under "Standard widgets".

> > > Should we put some examples here of the cases you're most likely
> > > to use, in particular .accept-line?
> 
> This would be interesting for users who wish to control the line
> before it is accepted.
> 
> > Thanks.
> > 
> > I expected there'd be an instance of «tt(.)var(widget)», and that's what
> > I initially grepped for.
> > 
> > Vincent, what did you search the man pages for?
> 
> I had searched for " \.[a-z]". I wasn't expecting quotes (it seems
> that most often, quotes are not used for single words).

There's no shortage of tt() instances surrounded by `TeX quotes',
though.

How about the following?  I think the new text has a lot of room for
improvement, so feedback's very welcome.

Cheers,

Daniel

diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 2d033a0a1..ce20513b8 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -746,17 +746,42 @@ ifnzman(noderef(Standard Widgets)).
 Other built-in widgets can be defined by other modules (see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(Zsh Modules))\
-).  Each built-in widget has two names: its normal canonical name, and the
-same name preceded by a `tt(.)'.  The `tt(.)' name is special: it can't be
-rebound to a different widget.  This makes the widget available even when
-its usual name has been redefined.
+).
 
 User-defined widgets are defined using `tt(zle -N)', and implemented
 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
+
+cindex(widgets, shadowing standard)
+User-defined widgets may shadow (replace) standard widgets: for instance,
+after `tt(zle -N self-insert myfunc)', any invocation of the standard
+tt(self-insert) widget (including every keypress that appends an alphanumeric
+or space character to the command line) would invoke the user-defined
+function tt(myfunc) rather than the standard implementation of that widget.
+However, each standard widget `var(foo)' is also available under the
+name `tt(.)var(foo)', and this name can't be rebound to a different widget.
+This makes the standard widget available to be called or bound even when
+its usual name has been redefined.
+Therefore, for forward compatibility with future versions of the shell,
+it is recommended that user-defined widgets should not have names
 starting with `tt(.)'.
 
+Continuing the example, tt(myfunc) would typically invoke the built-in widget
+it is replacing using the dot-prefix syntax:
+
+example(zle -N self-insert myfunc
+myfunc+LPAR()+RPAR() {
+  [[ $KEYS == [aeiou] ]] && zle .self-insert -- "$@"
+  zle .self-insert -- "$@" 
+})
+
+This example causes vowels to be inserted twice.
+
+Note the use of the dot-prefix syntax.  If the tt(self-insert) widget had been
+invoked without the dot DASH()- that is, as `tt(zle self-insert -- "$@")' DASH()-
+then tt(myfunc) would have been called again, effecting a bottomless
+recursion.
+
 texinode(User-Defined Widgets)(Standard Widgets)(Zle Widgets)(Zsh Line Editor)
 sect(User-Defined Widgets)
 cindex(widgets, user-defined)