bug#68029: 29.1; (elisp) `pcase Macro': misleading mention of `cl-case'

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

> > I find this comment misleading/incorrect:
> >
> >   With 'cl-case', you would need to explicitly declare a
> >   local variable 'code' to hold the return value of
> >   'get-return-code'.  Also 'cl-case' is difficult to use
> >   with strings because it uses 'eql' for comparison.
> >
> > In fact, with `cl-case' the code is at least as simple:
> >
> > (let* ((val (get-return-code x)))
> >   (if (stringp val)  (message val)
> >     (cl-case val
> >       (success       (message "Done!"))
> >       (would-block   (message "Sorry, can't do it now"))
> >       (read-only     (message "The shmliblick is read-only"))
> >       (access-denied (message "You do not have the needed rights"))
> >       (val           (message "You do not have the needed rights")))))
> >
> > Yes, it's true that comparison is with `eql',
> > so for a string value you need to test that
> > separately (or intern and then test symbols
> > with `cl-case').  But there's no need to use
> > any `code' variable.
> 
> This shows that you do need to use a `code' variable (you named
> it `val' though), and that the pcase version is indeed better.

Are you missing the fact that with the `pcase'
version you use an `msg' variable, as well as
a `code' variable?  And with the `case' version
you have only the `val' variable?  1 var, not 2.

One traditional way of showing variables in Lisp
pattern matching is to use a syntax convention
(sometimes more than a convention - actually
parsed) of, say, a `?' prefix.

The `pcase version is, in effect this, if you
make explicit the symbols bound as vars:

(pcase (get-return-code x)
  ;; string
  ((and (pred stringp) ?MSG) ; <===
   (message "%s" ?MSG))      ; <===
  ;; symbol
  ('success       (message "Done!"))
  ('would-block   (message "Sorry, can't do it now"))
  ('read-only     (message "The shmliblick is read-only"))
  ('access-denied (message "You do not have the needed rights"))
  ;; default
  (?CODE                     ; <===
   (message "Unknown return code %S" ?CODE))) ; <===

`pcase' syntax has chosen to quote non-vars, so
instead of two variables indicated syntactically
with `?' as `?msg' and `?code' it uses the four
quoted non-vars `'success', `'would-block',
`'read-only', and `'access-denied'.  More noise
_in this case_, not less.

[You may note, BTW, that `pcase' doesn't quote
non-vars in all contexts: `(pred stringp)',
not `(pred 'stringp)'.]

Again, it's not to say that `pcase's choice of
quoting non-vars instead of using explicit var
syntax is worse.  It's to say that this example
_doesn't show off `pcase' as advantageous_ - it
does just the opposite.

I'm not saying the `pcase' syntax can't be a
workable/reasonable choice.  That _could be
shown_ with a different example.  This example
isn't a good one to show the advantages of
`pcase'.  It shows `pcase' as worse, not better.
Try again.

None of the examples given show the advantages
of `pcase'.  Such advantages should start with
DESTRUCTURING - the ONE thing you _don't_ have
built-in with the existing Elisp binding forms
or conditional forms.  Start with a simple
destructuring example: `case'-like, but with
destructuring.  That's my advice.

Destructuring is the easiest & most powerful
`pcase' feature to introduce, and it's not
really shown.  It's glossed over, at best.
Show beginners that, to start with.

In a nutshell, `pase-let' vs `let' is really
the place to start.  _Then_ add conditional
control into the mix.

It's as if someone only tried to explain away
some of what is particularly confusing about
`pcase', instead of teaching the strengths of
`pcase'.

Looks like doc written after a user complained
that some previous `pcase' doc didn't explain
some complicated aspects, so an attempt was
made to do only that, skipping the basics.

I don't claim that's really how we got the doc
we got.  I'm just saying it smells like that.

> > If you can't come up with a better example to
> > show advantages of `pcase' over `cl-case' (and
> > that should be easy to do), then don't say
> > anything about `cl-case'.  Or maybe just tell
> > the truth: `cl-case' handles _one simple
> > `pcase' use case_ in a simpler way.  IOW, if
> > you're just testing equality of the expression's
> > value against particular symbols then `cl-case'
> > is simpler and clearer.
> 
> No, the reality is that `pcase' has *many* advantages over `cl-case'.
> The example is just intended to showcase some of them.

Sure it has advantages over `case'!  No one would
argue otherwise.  You're missing the point: This
doc _doesn't show_ ANY of the advantages.

Don't show `pcase' trying to compete where `case'
or `if' is clearer & simpler.  No-brainer.

Show the strengths of `pcase'.  Don't just show
how to translate a trivial `if' form (with single
THEN and single ELSE sexps, no less!) to a more
verbose and complex `pcase' equivalent.

The only thing _shown_ is that `pcase' gives you
more complicated syntax to do what you can do
simpler with `if'!  Just the opposite from what,
I assume/hope, we intended to show.

If you don't yet get that this is poor doc, and
it does a big DISservice to `pcase', so be it.

> > >  (read-only "The shmliblick is read-only")
> >
> > (And you've presumably misspelled schmilblick ;-):
> >                                    ^  ^^
> >  https://en.wikipedia.org/wiki/Schmilblick)
> 
> I don't follow, sorry.

Did you try?  Is it hard to see those typos?

> I'm not sure that's indeed easier for a beginner
> ELisp developer to follow.  So I don't think it's
> worth making that change. So I'm closing this bug report.

Not surprised.  With luck, someone with a
different name than mine may help you see.