all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#76055: 29.4; Doc of string-empty-p
@ 2025-02-04 20:28 Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2025-02-05 12:12 ` Eli Zaretskii
  2025-02-05 21:41 ` Stefan Kangas
  0 siblings, 2 replies; 11+ messages in thread
From: Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2025-02-04 20:28 UTC (permalink / raw)
  To: 76055

The doc string should tell you that it treats a symbol for arg STRING,
instead of a string, by checking its `symbol-name'.  E.g., like what is
done for `string=':

 Symbols are also allowed; their print names are used instead.

This should be done for _each_ function where a string is said to be the
expected arg but where we also allow a symbol.


In GNU Emacs 29.4 (build 2, x86_64-w64-mingw32) of 2024-07-05 built on
 AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19045
System Description: Microsoft Windows 10 Pro (v10.0.2009.19045.5371)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation=aot
 --without-compress-install --with-sqlite3 --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)

Important settings:
  value of $LANG: ENU
  locale-coding-system: cp1252





^ permalink raw reply	[flat|nested] 11+ messages in thread

* bug#76055: 29.4; Doc of string-empty-p
  2025-02-04 20:28 bug#76055: 29.4; Doc of string-empty-p Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2025-02-05 12:12 ` Eli Zaretskii
  2025-02-05 17:13   ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2025-02-05 21:41 ` Stefan Kangas
  1 sibling, 1 reply; 11+ messages in thread
From: Eli Zaretskii @ 2025-02-05 12:12 UTC (permalink / raw)
  To: Drew Adams; +Cc: 76055

> Date: Tue, 4 Feb 2025 20:28:00 +0000
> From:  Drew Adams via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> The doc string should tell you that it treats a symbol for arg STRING,
> instead of a string, by checking its `symbol-name'.  E.g., like what is
> done for `string=':
> 
>  Symbols are also allowed; their print names are used instead.
> 
> This should be done for _each_ function where a string is said to be the
> expected arg but where we also allow a symbol.

I'm not sure we want to advertise this, certainly not "for _each_
function".  Who says this is not a side effect of the particular
implementation, which can therefore be changed without notice?





^ permalink raw reply	[flat|nested] 11+ messages in thread

* bug#76055: 29.4; Doc of string-empty-p
  2025-02-05 12:12 ` Eli Zaretskii
@ 2025-02-05 17:13   ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2025-02-05 20:13     ` Eli Zaretskii
  0 siblings, 1 reply; 11+ messages in thread
From: Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2025-02-05 17:13 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 76055@debbugs.gnu.org

> >  Symbols are also allowed; their print names are used instead.
> >
> > This should be done for _each_ function where a string is said to be the
> > expected arg but where we also allow a symbol.
> 
> I'm not sure we want to advertise this, certainly not "for _each_
> function".  Who says this is not a side effect of the particular
> implementation, which can therefore be changed without notice?

Fair enough, wrt your last sentence.

I didn't say "for each function".   I said
each function where..." - something quite
different.

To be more precise: Please do it for each
such function where you can guess that this
behavior isn't just a side effect or that's
likely to be changed without notice.

My guess is that 90% or more of the cases
where we do this are intentional - we
explicitly _want_ to let users use a symbol
in place of a string.  That means it's in
the _design_, not just an implementation
side effect.

So for all _such_ functions (i.e., where you
can consider that this is something users
should be aware of), please make the change.
It's a judgment call, up to you.





^ permalink raw reply	[flat|nested] 11+ messages in thread

* bug#76055: 29.4; Doc of string-empty-p
  2025-02-05 17:13   ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2025-02-05 20:13     ` Eli Zaretskii
  2025-02-05 21:13       ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  0 siblings, 1 reply; 11+ messages in thread
From: Eli Zaretskii @ 2025-02-05 20:13 UTC (permalink / raw)
  To: Drew Adams; +Cc: 76055

> From: Drew Adams <drew.adams@oracle.com>
> CC: "76055@debbugs.gnu.org" <76055@debbugs.gnu.org>
> Date: Wed, 5 Feb 2025 17:13:17 +0000
> 
> To be more precise: Please do it for each
> such function where you can guess that this
> behavior isn't just a side effect or that's
> likely to be changed without notice.

How can anyone know that?

> My guess is that 90% or more of the cases
> where we do this are intentional - we
> explicitly _want_ to let users use a symbol
> in place of a string.  That means it's in
> the _design_, not just an implementation
> side effect.

That a function calls string= doesn't yet mean its author meant to
allow symbols.





^ permalink raw reply	[flat|nested] 11+ messages in thread

* bug#76055: 29.4; Doc of string-empty-p
  2025-02-05 20:13     ` Eli Zaretskii
@ 2025-02-05 21:13       ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2025-02-05 21:27         ` Alfred M. Szmidt
  2025-02-06  8:06         ` Eli Zaretskii
  0 siblings, 2 replies; 11+ messages in thread
From: Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2025-02-05 21:13 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 76055@debbugs.gnu.org

> > To be more precise: Please do it for each
> > such function where you can guess that this
> > behavior isn't just a side effect or that's
> > likely to be changed without notice.
> 
> How can anyone know that?

By looking at the name of the function and the
function definition, and thinking about how
the function is used and expected to be used?

A function such as `string-empty-p' is a prime
candidate for checking and adding such mention.

Its name (and its current doc string) provides
no clue that it handles a symbol argument as
if you were passing (symbol-name <the symbol>).

If a function name shouts that the function's
only about a string, its doc should mention it if
that's not the case.

> > My guess is that 90% or more of the cases
> > where we do this are intentional - we
> > explicitly _want_ to let users use a symbol
> > in place of a string.  That means it's in
> > the _design_, not just an implementation
> > side effect.
> 
> That a function calls string= doesn't yet mean its author meant to
> allow symbols.

Of course not.  It requires thinking about the
function's definition and how it's expected to
be used.

At least for _new_ functions that use primarily
strings as args, the _author_ should know why it
was decided to allow symbols instead of just
strings.





^ permalink raw reply	[flat|nested] 11+ messages in thread

* bug#76055: 29.4; Doc of string-empty-p
  2025-02-05 21:13       ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2025-02-05 21:27         ` Alfred M. Szmidt
  2025-02-05 23:28           ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2025-02-06  8:06         ` Eli Zaretskii
  1 sibling, 1 reply; 11+ messages in thread
From: Alfred M. Szmidt @ 2025-02-05 21:27 UTC (permalink / raw)
  To: Drew Adams; +Cc: 76055, eliz

   A function such as `string-empty-p' is a prime
   candidate for checking and adding such mention.

   Its name (and its current doc string) provides
   no clue that it handles a symbol argument as
   if you were passing (symbol-name <the symbol>).

Why should it?  Lisp is a dynamic language, and predicates generally
accept anything.  If anything, if the notion is that string-empty-p
should _reject_ anything but strings, it should be an assert!  (Not
saying that should be the case ...)

   If a function name shouts that the function's
   only about a string, its doc should mention it if
   that's not the case.





^ permalink raw reply	[flat|nested] 11+ messages in thread

* bug#76055: 29.4; Doc of string-empty-p
  2025-02-04 20:28 bug#76055: 29.4; Doc of string-empty-p Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2025-02-05 12:12 ` Eli Zaretskii
@ 2025-02-05 21:41 ` Stefan Kangas
  2025-02-05 23:30   ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2025-02-06  8:11   ` Eli Zaretskii
  1 sibling, 2 replies; 11+ messages in thread
From: Stefan Kangas @ 2025-02-05 21:41 UTC (permalink / raw)
  To: Drew Adams, 76055

Drew Adams via "Bug reports for GNU Emacs, the Swiss army knife of text
editors" <bug-gnu-emacs@gnu.org> writes:

> The doc string should tell you that it treats a symbol for arg STRING,
> instead of a string, by checking its `symbol-name'.  E.g., like what is
> done for `string=':
>
>  Symbols are also allowed; their print names are used instead.

FWIW, I'm not suggesting any changes, but I admit that I never really
understood this design decision.

This is what I get in Guile:

    scheme@(guile-user)> (string=? "foo" 'foo)
    ice-9/boot-9.scm:1676:22: In procedure raise-exception:
    In procedure string=: Wrong type argument in position 2 (expecting
string): foo

And in SBCL:

    * (string= "foo" 'foo)
    NIL

    * (string= "foo" 123)

    debugger invoked on a SIMPLE-TYPE-ERROR in thread
    #<THREAD tid=259 "main thread" RUNNING {7004FF0003}>:
      123 is not a string designator.





^ permalink raw reply	[flat|nested] 11+ messages in thread

* bug#76055: 29.4; Doc of string-empty-p
  2025-02-05 21:27         ` Alfred M. Szmidt
@ 2025-02-05 23:28           ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  0 siblings, 0 replies; 11+ messages in thread
From: Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2025-02-05 23:28 UTC (permalink / raw)
  To: Alfred M. Szmidt; +Cc: 76055@debbugs.gnu.org, eliz@gnu.org

>    A function such as `string-empty-p' is a prime
>    candidate for checking and adding such mention.
> 
>    Its name (and its current doc string) provides
>    no clue that it handles a symbol argument as
>    if you were passing (symbol-name <the symbol>).
> 
> Why should it?  Lisp is a dynamic language, and 
> predicates generally accept anything.  If anything,
> if the notion is that string-empty-p should _reject_ 
> anything but strings, it should be an assert!
> (Not saying that should be the case ...)

This is essentially a type predicate (per its
name, if nothing else): test whether the arg is
an empty string.

Of _course_ you can pass it a value of any type.
But what should its behavior be for a non-string
arg?

There was a choice made of whether to return nil
for an arbitrary non-string or to raise an error.
Emacs chose the latter, and I have _no problem_
with that.

(string-empty-p [1 2])       ; -> error
(string-empty-p 42)          ; -> error
(string-empty-p (cons 1 2))  ; -> error
(string-empty-p nil)         ; -> error

But if the non-string is a symbol then we have
a different story:

(string-empty-p "cat")       ; -> nil
(string-empty-p 'cat)        ; -> nil

(string-empty-p "")          ; -> t
(string-empty-p (intern "")) ; -> t

The handling of a symbol arg isn't something
someone would expect, just by looking at the
function name and reading the doc.

It raises an error for a non-string argument,
showing that it is, indeed, an empty-string
type predicate...

...EXCEPT for a non-string argument that's a
symbol.  If the `symbol-name' of the symbol
is "" then it returns t.  If the name is "x"
it returns nil.

That's what's missing.  It's not _at all_
obvious it would do this - neither from its
name nor from its doc.  It presents itself
as just an empty-string type predicate.

Just what is this function?  It's simply a
`string=' test for "".  And lo and behold,
the doc string of `string=' tells us loud
and clear:

  Symbols are also allowed; their print
  names are used instead.

Thank you very much, Emacs doc!  I have no
problem with this choice of behavior.  And
the doc is nice enough to make the behavior
clear.

The doc of `string-empty-p' should obviously
do the same - for the same reason: because
this exceptional non-string behavior is not
obvious, and the predicate's name and doc
suggests a different behavior (so far).





^ permalink raw reply	[flat|nested] 11+ messages in thread

* bug#76055: 29.4; Doc of string-empty-p
  2025-02-05 21:41 ` Stefan Kangas
@ 2025-02-05 23:30   ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2025-02-06  8:11   ` Eli Zaretskii
  1 sibling, 0 replies; 11+ messages in thread
From: Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2025-02-05 23:30 UTC (permalink / raw)
  To: Stefan Kangas, 76055@debbugs.gnu.org

> > The doc string should tell you that it treats a symbol for arg STRING,
> > instead of a string, by checking its `symbol-name'.  E.g., like what is
> > done for `string=':
> >
> >  Symbols are also allowed; their print names are used instead.
> 
> FWIW, I'm not suggesting any changes, but I admit that I never really
> understood this design decision.
> 
> This is what I get in Guile:
> 
>     scheme@(guile-user)> (string=? "foo" 'foo)
>     ice-9/boot-9.scm:1676:22: In procedure raise-exception:
>     In procedure string=: Wrong type argument in position 2 (expecting
> string): foo
> 
> And in SBCL:
> 
>     * (string= "foo" 'foo)
>     NIL
> 
>     * (string= "foo" 123)
> 
>     debugger invoked on a SIMPLE-TYPE-ERROR in thread
>     #<THREAD tid=259 "main thread" RUNNING {7004FF0003}>:
>       123 is not a string designator.

I'm not at all raising the question of it raising or
not raising an error if the arg isn't a string (i.e.,
"rejecting" the arg, as Alfred put it).

Elisp does the same as Scheme and SBCL for a non-symbol
non-string.  (But note SBCL's handling of a symbol, BTW.)

I _like_ Elisp's `string=' behavior and doc.  It says:
I'm a function that checks whether two strings are equal.
The args must be strings or I'll raise an error.
Oh wait, I do also accept symbols, and for them I use
their `symbol-name's, but that's the only non-string
exception.

[ I could also like a behavior that raised an error for
all non-string args, i.e., including symbols.  I could
also like a behavior that returned nil for a non-string
arg (any non-string arg).  That latter behavior would
just be a test whether the args are strings AND if so,
are equal. ]

`string-empty-p' should be just as polite and user
friendly as `string='.

^ permalink raw reply	[flat|nested] 11+ messages in thread

* bug#76055: 29.4; Doc of string-empty-p
  2025-02-05 21:13       ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2025-02-05 21:27         ` Alfred M. Szmidt
@ 2025-02-06  8:06         ` Eli Zaretskii
  1 sibling, 0 replies; 11+ messages in thread
From: Eli Zaretskii @ 2025-02-06  8:06 UTC (permalink / raw)
  To: Drew Adams; +Cc: 76055

> From: Drew Adams <drew.adams@oracle.com>
> CC: "76055@debbugs.gnu.org" <76055@debbugs.gnu.org>
> Date: Wed, 5 Feb 2025 21:13:05 +0000
> 
> > > To be more precise: Please do it for each
> > > such function where you can guess that this
> > > behavior isn't just a side effect or that's
> > > likely to be changed without notice.
> > 
> > How can anyone know that?
> 
> By looking at the name of the function and the
> function definition, and thinking about how
> the function is used and expected to be used?

Feel free to do this and suggest which functions you think should
document their support of symbols.  I personally think that you are
greatly underestimating how large and complex this job is, and
therefore I don't plan doing it myself, and would not encourage anyone
to do it.  I think the benefits are quite small compared with the
efforts.

> At least for _new_ functions that use primarily
> strings as args, the _author_ should know why it
> was decided to allow symbols instead of just
> strings.

You assume that it was a conscious decision, but that is not given at
all.  I dare to think that this assumption is simply false in most, if
not all, cases.





^ permalink raw reply	[flat|nested] 11+ messages in thread

* bug#76055: 29.4; Doc of string-empty-p
  2025-02-05 21:41 ` Stefan Kangas
  2025-02-05 23:30   ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2025-02-06  8:11   ` Eli Zaretskii
  1 sibling, 0 replies; 11+ messages in thread
From: Eli Zaretskii @ 2025-02-06  8:11 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 76055, drew.adams

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Wed, 5 Feb 2025 16:41:47 -0500
> 
> Drew Adams via "Bug reports for GNU Emacs, the Swiss army knife of text
> editors" <bug-gnu-emacs@gnu.org> writes:
> 
> > The doc string should tell you that it treats a symbol for arg STRING,
> > instead of a string, by checking its `symbol-name'.  E.g., like what is
> > done for `string=':
> >
> >  Symbols are also allowed; their print names are used instead.
> 
> FWIW, I'm not suggesting any changes, but I admit that I never really
> understood this design decision.

It's too late to change that: this function supported symbols since
the very beginning.  I'm guessing there were good practical reasons
for that behavior.

However, while extending to strings comparison to symbol names could
make sense, telling whether a string is empty (the subject of this
report) is NOT: what symbol could have an empty name?





^ permalink raw reply	[flat|nested] 11+ messages in thread

end of thread, other threads:[~2025-02-06  8:11 UTC | newest]

Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-02-04 20:28 bug#76055: 29.4; Doc of string-empty-p Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
2025-02-05 12:12 ` Eli Zaretskii
2025-02-05 17:13   ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
2025-02-05 20:13     ` Eli Zaretskii
2025-02-05 21:13       ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
2025-02-05 21:27         ` Alfred M. Szmidt
2025-02-05 23:28           ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
2025-02-06  8:06         ` Eli Zaretskii
2025-02-05 21:41 ` Stefan Kangas
2025-02-05 23:30   ` Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors
2025-02-06  8:11   ` Eli Zaretskii

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.