RE: The poor state of documentation of pcase like things.

[Drew Adams <drew.adams@oracle.com>]

> I don't see how a pcase used like a cl-case - as in the quoted example -
> is any harder to read or understand.
> 
> And of course it has also advantages to use pcase in such cases.  If you
> want to change the code or try things and you suddenly want a feature
> from pcase, you don't have to rewrite the whole thing.
> 
> It just...arguable what you prefer.

Yes.  So let me argue ;-) in favor of using `pcase' only, or
mainly, when decomposition pattern-matching is used, and not
just for literal tests.

Your point is that `pcase' is more general, so if you want to
later add a clause that does make use of decomposition
pattern-matching then it's easy to do so.  That is a good
argument.

It's not the argument that persuades me, however.  I generally
come down on the side of trying to have the most readable code,
even at the cost of more maintenance work, in terms of typing.

Why?  Because I think that code readability is primary, and
the biggest maintenance burden is not typing but understanding.

Why do I think that a control structure that tests only
literals is clearer for literal-testing than one that also
uses decomposition patterns?

Because the former necessarily shouts that there are ONLY literal
tests here.  `pcase' is harder to parse not just because some of
us might not be as used to it, but also precisely because of its
generality.  You have to look closely, to see whether there might
be some decomposition pattern-matching going on.

(Occam's razor.  Einstein's as-simple-as-possible-but-no-simpler.)

Because `pcase' is so general that it can handle also fancy
patterns, its syntax is more involved - overkill.  Not overkill
for the cases where it makes sense and takes advantage of pattern
matching.  But overkill for the mundane, literal-matching cases.

I prefer to use the simpler `cl-case' or whatever when possible,
because it says, loud-and-clear, to a reader: "Nothing fancy here."
The reader is the one who counts, for me, not the writer.

And I don't mind having to later rewrite the code if a feature
change or bug fix makes it possible to really take advantage of
what `pcase' has to offer.  Yes, that's an added burden, but one
that I, personally, don't mind.  (I'm talking about me and my
code.  I can understand, if Emacs maintainers feel differently
about the distributed Emacs code.)

IOW, I echo the hammer=>nail reflection that David made.  There
is no need to think that `pcase' _needs_ to be used everywhere,
just because it _can_ be used everywhere.  (And I feel the same
about `loop', FWIW.)

Just one opinion, of course.