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

[Drew Adams]

> >> Well, I'd say that pcase is kinda awkward because you can't tell by
> >> skimming whether it's complex or not
> >
> > 100% agreement.  That's really the point, for me.
> >
> > * `pcase' shouts: "This might be complicated.  Better look closely."
> >
> > * `cond' and `cl-case' and `if' ... shout: "Nothing fancy here.
> >   We're only testing literals"
> 
> I don't see how `cond' and `if' shout that at all, they can test
> anything, no restrictions. I would prefer `pcase` over `cond` (if
> there were some reason to exclude `cl-case') because the code is
> shorter and simpler so I can skim it faster than the equivalent
> `cond'.

I tried to consistently contrast what they do with the
"_decomposition pattern-matching_" that `pcase' can do (in
addition to only matching literal "patterns" - `eql').

Sorry if that wasn't clear.  Of course the ordinary control
structures can perform any kind of test.  That's not in
question.  But when it comes to _pattern matching_ (e.g.,
for `cl-case'), only literal matches are done.

`pcase' is unique among control structures in being able to
decompose what a pattern matches, i.e., to bind local variables.
This is really what it has to offer (IMHO).  The rest is nothing
new.  And I would (personally) typically use it only when it
was doing that.

You could get `pcase' behavior with just a decomposing
let combined with the classic control structures.  You
might even argue that that might be clearer.

(I used to use a Lisp, many moon ago, that had such a let,
but I've forgotten what it was.  Maybe it was something I
wrote, instead of being part of the language - I don't recall.)