GNU bug report logs - #35222
26.1; `read-command' documentation

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 35222 in the body.
You can then email your comments to 35222 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
Subject: 26.1; `read-command' documentation
Date: Wed, 10 Apr 2019 15:13:31 -0700 (PDT)

1. The doc string does not say what happens if DEFAULT is not provided
   (so `nil') and the user enters empty input.  And what happens is not
   obvious.  Please add that information to the doc string.

2. What does happen?  Well, it's documented in (elisp) `High-Level
   Completion'.  But please add information to that Info node that helps
   users understand a return value that is an empty-named interned
   symbol, which has the print and read syntax `##'.  It's pretty
   unusual for the default behavior of a read command to return such an
   odd beast.  (The default behavior is the case when arg DEFAULT is
   absent, hence `nil'.)  And please provide a cross-reference to node
   `Symbol Type', which explains this syntax.

   User code that tests the result of `read-command' typically needs to
   deal with the default DEFAULT case, hence with the possibility of the
   function returning an uninterned symbol.  Users need to be aware of
   this possibility - it's a gotcha.


In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 35222 <at> debbugs.gnu.org
Subject: Re: bug#35222: 26.1; `read-command' documentation
Date: Wed, 10 Apr 2019 18:24:14 -0400

On Wed, 10 Apr 2019 at 18:14, Drew Adams <drew.adams <at> oracle.com> wrote:
>
> 1. The doc string does not say what happens if DEFAULT is not provided
>    (so `nil') and the user enters empty input.  And what happens is not
>    obvious.  Please add that information to the doc string.

Um, can we declare the current behaviour a bug, and instead return nil
in this case? That matches the current doc string (i.e., return
DEFAULT-VALUE), and avoids the whole mess with the empty string symbol
which is weird and pretty useless as far as I can tell.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 35222 <at> debbugs.gnu.org
Subject: RE: bug#35222: 26.1; `read-command' documentation
Date: Wed, 10 Apr 2019 16:32:47 -0700 (PDT)

> > 1. The doc string does not say what happens if DEFAULT is not provided
> >    (so `nil') and the user enters empty input.  And what happens is not
> >    obvious.  Please add that information to the doc string.
> 
> Um, can we declare the current behaviour a bug, and instead return nil
> in this case? That matches the current doc string (i.e., return
> DEFAULT-VALUE), and avoids the whole mess with the empty string symbol
> which is weird and pretty useless as far as I can tell.

Good question.  That was in fact my first reaction.
I wrote the bug report that way, then reconsidered.

I agree that the behavior is weird, and I'm not sure
what users, in what use cases, it could help.  IOW,
why?

But the behavior has apparently always been thus.

(Prior to Emacs 24 there was no such read/print
syntax for uninterned symbols, so it was arguably
even weirder.  If you used the result as a variable
value and did `C-h v' it would show you nothing!)

I ended up figuring that someone wanted this for
some good reason that I couldn't think of, and that
since it is documented this way (always returns a
symbol) and it is of long date we should just leave
it and make sure the doc string also helps.

But it sure is a gotcha.  Why the default DEFAULT
behavior would be something so unexpected is a
good question.  Hysterical accident?  Intentional
design?  Anyone know or have an idea what good this
is?

All I could think of is that code using it can be
sure to get a symbol.  But it sure isn't sure to
get a command...  I don't have the C sources, but
a priori (e.g. if I were writing `read-command'
from scratch in Lisp) it seems like it should
_require_ a commandp symbol, i.e., use
`completing-read' with non-nil REQUIRE arg.

Someone is sure to enlighten us.  When that happens,
and if the decision is to continue the behavior,
hopefully people will agree even more strongly with
the need to provide clear doc about this odd default
case.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 35222-done <at> debbugs.gnu.org
Subject: Re: bug#35222: 26.1; `read-command' documentation
Date: Thu, 11 Apr 2019 17:02:20 +0300

> Date: Wed, 10 Apr 2019 15:13:31 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> 1. The doc string does not say what happens if DEFAULT is not provided
>    (so `nil') and the user enters empty input.  And what happens is not
>    obvious.  Please add that information to the doc string.

Thanks, fixed.

> 2. What does happen?  Well, it's documented in (elisp) `High-Level
>    Completion'.  But please add information to that Info node that helps
>    users understand a return value that is an empty-named interned
>    symbol, which has the print and read syntax `##'.  It's pretty
>    unusual for the default behavior of a read command to return such an
>    odd beast.  (The default behavior is the case when arg DEFAULT is
>    absent, hence `nil'.)  And please provide a cross-reference to node
>    `Symbol Type', which explains this syntax.

Done.

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

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 35222 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#35222: 26.1; `read-command' documentation
Date: Thu, 11 Apr 2019 14:55:47 -0400

>> 1. The doc string does not say what happens if DEFAULT is not provided
>>    (so `nil') and the user enters empty input.  And what happens is not
>>    obvious.  Please add that information to the doc string.
> Um, can we declare the current behaviour a bug, and instead return nil
> in this case? That matches the current doc string (i.e., return
> DEFAULT-VALUE), and avoids the whole mess with the empty string symbol
> which is weird and pretty useless as far as I can tell.

Yes, it would seem to be more in line with the usual expected behavior.
The caller can get the current behavior by passing ## as the DEFAULT
argument, so there doesn't seem to be any good reason to return ## when
DEFAULT was nil.


        Stefan

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
Cc: 35222 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#35222: 26.1; `read-command' documentation
Date: Thu, 11 Apr 2019 20:11:15 -0400

Stefan Monnier <monnier <at> IRO.UMontreal.CA> writes:

>>> 1. The doc string does not say what happens if DEFAULT is not provided
>>>    (so `nil') and the user enters empty input.  And what happens is not
>>>    obvious.  Please add that information to the doc string.
>> Um, can we declare the current behaviour a bug, and instead return nil
>> in this case? That matches the current doc string (i.e., return
>> DEFAULT-VALUE), and avoids the whole mess with the empty string symbol
>> which is weird and pretty useless as far as I can tell.
>
> Yes, it would seem to be more in line with the usual expected behavior.
> The caller can get the current behavior by passing ## as the DEFAULT
> argument, so there doesn't seem to be any good reason to return ## when
> DEFAULT was nil.

Since this bug is already closed, this should go Bug#35231.

Previous Next

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