Re: Does add-zle-hook-widget violate the contract of ZLE hook widgets?

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Marlon Richert wrote on Fri, Jun 25, 2021 at 00:48:16 +0300:
> On Thu, Jun 24, 2021 at 9:30 PM Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx> wrote:
> >
> > Marlon Richert wrote on Thu, Jun 24, 2021 at 13:34:00 +0300:
> > > On Thu, Jun 24, 2021 at 1:06 PM Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx> wrote:
> > > >
> > > > Marlon Richert wrote on Wed, 23 Jun 2021 20:30 +00:00:
> > > > > foo implements a perfectly fine zle-line-init widget. It obeys the
> > > > > contract laid out at
> > > > > https://zsh.sourceforge.io/Doc/Release/Zsh-Line-Editor.html#Special-Widgets,
> > > > > which says nothing about return values.
> > > >
> > > > That has two possible interpretations:
> > > >
> > > > - Hook functions may set $? however they want
> > > >
> > > > - Hook functions should set $? to zero on success and to non-zero
> > > >   otherwise
> > > >
> > > > In favour of the first interpretation is that the manual's language
> > > > doesn't explicitly rule it out and compatibility with hook functions
> > > > that predate add-zle-hook-widget and don't set $? as
> > > > add-zle-hook-widget expects.
> > > >
> > > > In favour of the second interpretation is that those semantics are the
> > > > default, ubiquitous, baked into the language's syntax, and extensible
> > > > (same thing as "This bit must be zero" in wire protocol specifications).
> > > >
> > > > I'm voting for the second interpretation.
> > > >
> > > > I suppose we could've added something to NEWS/README when add-zle-hook-widget
> > > > was introduced, if only because this is an interoperability issue (foo
> > > > and bar may be have separate maintainers).
> > >
> > > I think this should be mentioned permanently in the manual, exactly
> > > because we see foo and bar from separate maintainers in the wild.
> >
> > I'm ambivalent about this.
> >
> > On the one hand, as mentioned, "set $? correctly" is a ground rule that
> > shouldn't need to be made explicit everywhere it matters.  I don't want
> > to create an expectation that where the manual _doesn't_ explicitly
> > specify that $? should be set correctly, $?'s value doesn't matter.
> >
> > On the one hand, someone who uses «zle -N zle-line-init foo» may not be
> > aware of a-z-h-w and of the fact that the return value does have an
> > effect.
> >
> > In balance, I think I would rather see it documented globally that $?
> > should always be set to zero/non-zero unless explicitly specified
> > otherwise.  Makes sense?
> 
> That makes sense, but then, it should also be documented what that
> actually means. If your function returns zero/non-zero, what is
> expected to happen? Does this always happen? Or are there different
> classes of functions with different results for zero/non-zero?
> 
> I can already think of two examples that contradict each other:
> * In hook functions, callee returning NON-zero causes the caller to
> refrain from calling more functions.
> * In completion functions, callee returning ZERO causes the caller to
> refrain from calling more functions.
> 
> Those two behave exactly opposite of each other.
> 
> My point being, I think this is best spelled out everywhere.
> Zero/non-zero don't always appear to mean the same thing between
> caller and callee. Clearly it matters, but it doesn't appear to always
> matter in the same way.
> 

I think it's misleading to look at the "caller and callee" system.  They
aren't coupled.  The caller is written to work with any callee that
follows the standard return value semantics, and the callee is written
to work with any caller that expects the standard return value
semantics.

Some callers have a list of callees; some don't.  Some callers who have
a list of callees will call them all; some will call them until the
first success; some will call them until the first failure.  The callee
neither knows nor cares.  The callee simply takes care to return
non-zero whenever it fails, and zero whenever it succeeds.  That's
implied.

What isn't implied is which semantics the caller follows.  The caller
(e.g., add-zsh-hook, add-zle-hook-widget) should document that.

> > > > > Should that `|| return` be removed?
> > > > No, because that would break the case of _deliberately_ returning non-zero
> > > > from one a-z-h-w hook to prevent further a-z-h-w hooks from running.
> > > > Granted, that's not a documented promise, but there's no reason to break
> > > > it, either.
> > >
> > > For hooks added through azhw, yes. But hooks added through zle -N
> > > zle-<hook> have no reason to expect that their return value has any
> > > effect.
> > >
> >
> > I did give some reasons in my previous reply; and compare how drivers
> > should use their turn indicators even when they don't see anyone on the
> > road.
> 
> That's because it's convention everywhere that you signal in the
> direction to which you turn. However, what convention we're supposed
> to follow for return values in Zsh is not quite as clear. See my
> contradictory examples above.
> 

My point was that drivers signal even when there's no one else on the
road.  The analogy to that is that functions should return zero for
success and non-zero otherwise even when they don't know what their
caller would do with that.

> > > How about if azhw would ignore the return value _only_ of any
> > > pre-existing zle -N zle-X widget? For example, this part of the azhw
> > > code could be modified to wrap the original widget function in a
> > > function that always returns zero:
> >
> > At this point, given that the current behaviour has appeared in stable
> > releases for 4.5 years now and is _a priori_ preferable, I think it's
> > better to document the current behaviour and move on.  So, basically, an
> > addition to the incompatible changes section in README (for 5.9) that
> > describes the change in 5.3.  WDYT?
> 
> I'm fine with that. That documentation needs to be findable, though,
> from the docs for both zle -N zle-X and azhw.

Perhaps.  The manual and NEWS/README have different purposes.