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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 68029 in the body.
You can then email your comments to 68029 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 29.1; (elisp) `pcase Macro': misleading mention of `cl-case'
Date: Mon, 25 Dec 2023 16:26:22 +0000

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.

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.

Even clearer is just this (same for the `pcase' example):

(message
 (let* ((val (get-return-code x))) 
   (if (stringp val) val
     (cl-case val
       (success       "Done!")
       (would-block   "Sorry, can't do it now")
       (read-only     "The shmliblick is read-only")
       (access-denied "You do not have the needed rights")
       (val           "You do not have the needed rights")))))

(And you've presumably misspelled schmilblick ;-):
https://en.wikipedia.org/wiki/Schmilblick)

In GNU Emacs 29.1 (build 2, x86_64-w64-mingw32) of 2023-08-02 built on
 AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19045
System Description: Microsoft Windows 10 Pro (v10.0.2009.19045.3803)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation=aot
 --without-compress-install --with-tree-sitter CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB

(NATIVE_COMP present but libgccjit not available)

Message #10 received at 68029-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>, 68029-done <at> debbugs.gnu.org
Subject: Re: bug#68029: 29.1;
 (elisp) `pcase Macro': misleading mention of `cl-case'
Date: Mon, 25 Dec 2023 08:53:52 -0800

Drew Adams <drew.adams <at> oracle.com> writes:

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

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

> Even clearer is just this (same for the `pcase' example):
>
> (message
>  (let* ((val (get-return-code x)))
>    (if (stringp val) val
>      (cl-case val
>        (success       "Done!")
>        (would-block   "Sorry, can't do it now")
>        (read-only     "The shmliblick is read-only")
>        (access-denied "You do not have the needed rights")
>        (val           "You do not have the needed rights")))))

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.

> (And you've presumably misspelled schmilblick ;-):
> https://en.wikipedia.org/wiki/Schmilblick)

I don't follow, sorry.

So I'm closing this bug report.

Message #13 received at 68029-done <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefankangas <at> gmail.com>, "68029-done <at> debbugs.gnu.org"
 <68029-done <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#68029: 29.1; (elisp) `pcase Macro':
 misleading mention of `cl-case'
Date: Tue, 26 Dec 2023 17:46:01 +0000

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.