Re: Replace trivial pcase occurrences in the Emacs sources

[Michael Heerdegen]

Eli Zaretskii <address@hidden> writes:

> > We called these UPATS in the past btw.

That should have been QPATs, sorry.

> Sorry, I'm still in the dark here.  The node I pointed to describes
> "backquote-style patterns", and explains that these "ease structural
> matching".  The same patterns are useful for destructuring binding,
> precisely because destructuring binding needs a structural match.
> That is all that I'm trying to convey.  Making that point will help
> the reader to understand what subset of pcase patterns will be most
> useful for destructuring.

So, I should read it as "the set of patterns that are of the form
`SOMETHING"?  I had read it as the set of what we call "QPATs".  So we
have probably talked about different things.

I find the wording used in (info "(elisp) Backquote Patterns")
confusing, especially the first sentence "This subsection describes
“backquote-style patterns”, a set of builtin patterns that eases
structural matching." which seems to introduce a whole set of builtin
patterns though it talks only about one macro, `.

You only refer to that in your change, using the same wording, so what
you changed is consistent with what we have, although I don't like it
that much.


> > > > (2) We already have a lot other patterns for destructuring
> > > > (eieio, seq, map, cl-struct), and we probably will get even more
> > > > in the future.
> > >
> > > OK, but why is that a reason not to use what I wrote?  Note that it
> > > talks about "destructuring binding", not just about destructuring.
> > 
> > Well, for binding there is only one pattern, SYMBOL.  But you also
> > write
> > 
> > | since they express a specification of the structure of objects that
> > | will match.
> > 
> > so this seems to speak about destructuring and not about binding.
>
> Destructuring binding requires destructuring, that's all.

"Destructuring binding" - pcase has nothing like that.  We have a
pattern type for binding, SYMBOL, and diverse for performing
destructuring, ``' being the main and most general one.  You can combine
these, but both are different things.

We talk about this paragraph:

| +The pcase patterns that are useful for destructuring bindings are
| +generally those described in @ref{Backquote Patterns}, since they
| +express a specification of the structure of objects that will match.

I would already be happy if you would leave out the word "bindings".
Establishing bindings is not the only use of `.

> Again, I don't understand the nature of your objections to the text.
>
> > | The pcase patterns that are useful for destructuring bindings are
> > | generally those described in @ref{Backquote Patterns}
> > 
> > makes it sounds if ` is the only method to get destructuring bindings
> > with pcase.
>
> No, it says those are _useful_ for destructuring bindings, that's all.
> I'm sure you realize that saying A doesn't say that there's nothing
> but A.

Sorry, I'm not an native English speaker.  But "are generally those"
sounds quite, well, generalizing to me ;-)

> I submit that any other example, except the ones that follow my
> description, will have the same property: they can be rewritten
> cleaner, and in many cases also shorter, than using pcase-let etc.

But that's personal preference.  I found at least one example of such a
`pcase-let' that doesn't use destructuring in the Emacs sources.  It
isn't wrong just because you would personally write it in a different
way, and it should be understandable after reading the docs.  All
occurrences should be understandable after reading the docs, not only
those that are main use cases or cases that the inventor had in mind
when the thing was created.

> > And docstrings shouldn't tell restrictions that don't exist just
> > because you would prefer `cond' in such cases anyway.
>
> So you seem to object to the doc string describing only part of the
> possible uses?  If so, this argument was already voiced in the
> discussion, and I already said that I think it's a mistake to make our
> documentation more vague and therefore more confusing, for the benefit
> of being 100% accurate.

I don't suggest to make it vague.  In my option, what you did in your
change makes it more vague, actually.  What we write in the docs should
be correct, at least.

> IOW, it is quite clear that, knowing the way a macro is implemented,
> one can tweak the macro into doing stuff it never was designed to do.

These are still valid use cases.

> But we introduced pcase-let for a reason, and AFAIU that reason is to
> allow destructuring binding.  It can also do other things, but nothing
> important will be lost by making the documentation general enough, and
> thus vague/abstract enough, to cover those other use cases.

I don't understand what this means in concrete.

> > > > Also the docstrings give the impression that these are limited to
> > > > destructuring, which is not true.
> > >
> > > Can you tell where did you get that impression?  The doc strings talk
> > > about destructuring bindings, when BINDINGS have the form specified,
> > > and I believe that is true.
> > 
> > You say
> > 
> > | Perform desctructuring binding of variables according to
> > | @var{bindings}, and then evaluate @var{body}.
> > 
> > Any pcase PATTERN can be used in BINDINGS, whether it performs
> > destructuring or not, the only assumption is that it should match.
>
> But these macros were invented to support destructuring, don't you
> agree?

To 100%.

> Stefan's original text talked about extracting values (or subfields),
> so it was clear to me that Stefan, too, alluded to destructuring.

It talked about "extracting data".  It didn't restrict to what data and
from where.  Destructuring comes to my mind when I read that, but
"extracting data" doesn't explicitly limit it to that case.  I wouldn't
have chosen that wording, however.  It was not the original docstring,
btw, but one Stefan had rewritten after he had been urged to by people
(like you) who were not happy with the original docstring.  The original
docstring was clearer in that regard, indeed.

> I think we should describe the intended usage of these macros first
> and foremost.  If the other uses can be described without losing
> clarity, fine; but that's not the case here, as the long discussions
> seem to show -- people were unhappy with the original abstract and
> general descriptions because they didn't tell them enough about the
> main use case.

I'm not against telling the main use cases.  But a thing isn't described
completely or even in a good way only by telling the main use cases.

> > You can say that pcase-let is mostly useful for destructuring the
> > bound values, but as a summary of what `pcase-let' and the like is
> > about it's misleading.  It's misleading because I then wonder where
> > the restriction to destructuring comes from, and what's different to
> > just matching the patterns against the values as in `pcase'.
>
> I disagree that it's misleading.  If you care so much about the
> restrictions, or lack thereof, you are welcome to study the code.  But
> the doc string should explain how to use the macro to the rest of us.

Say the "rest of us" is 50% of the people.  The other 50% don't matter?
The docs get more confusing for them.

What would you say if I would change the docstring of `cond' to say it's
limited to the cases where I would use it, just because I, and lots of
other people ("the rest of us") would prefer something more suited in
our eyes in these cases, like pcase?

Also, not only people write pcase/pcase-let expressions, but also code
can do that.  The documentation should make clear what is allowed and
what not also for that case.  After saying that you can write how the
main use cases look like.  FWIW, I always thought that the docstrings
tell how something works and what it does, and the manual is for
learning and telling use cases.

It's also a difference between "... is typically used for" (which I
would find ok) and "... does this and that" and it's not accurate.


Michael.