Re: Replace trivial pcase occurrences in the Emacs sources

[Eli Zaretskii]

> From: Michael Heerdegen <address@hidden>
> Cc: address@hidden,  address@hidden
> Date: Sat, 03 Nov 2018 18:12:43 +0100
> 
> > Sorry, you lost me here.  How can these not be pcase patterns, when
> > they are used with 'pcase', and "pcase patterns" are _defined_ as
> > those used with 'pcase'?
> 
> We called these UPATS in the past btw.
> 
> Not every part of a pattern is also a pattern.
> 
> ,a is not an expression since it's only valid as sexp inside a backquote
> expression.  For a similar reason, ,a is not a pcase pattern because
> it's only valid in a ` pattern.
> 
> (< 1) is also not a pcase pattern, although it's valid inside a pred:
> (pred (< 1)).
> 
> A pcase pattern should only be called what is valid as PATTERN in a
> pcase clause (PATTERN BODY).

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.

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

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.

> >   (defun test (arg)
> >     (let ((s (cond ((stringp arg) arg)
> >                    ((numberp arg) (number-to-string arg)))))
> >       s))
> >
> > (which is both simpler and shorter)?
> 
> It was just an example.

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.

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

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

> > > 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?  Stefan's original text talked about extracting values (or
subfields), so it was clear to me that Stefan, too, alluded to
destructuring.  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.

In any case, feel free to suggest modifications of the doc strings
that are more general without losing clarity, and let's take this from
there.

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

We write our documentation to be useful in the main use cases, not to
be 110% accurate.  Favoring the latter at the price of obfuscating the
former is IME a serious mistake that produces inferior programming
docs.