bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Daniel Nagy]

Hello,

The current signature of #'buffer-size is:

    (buffer-size &optional BUFFER)

It can only handle actual buffer objects as the argument. Could it be
made to accept the buffer name as a string as well? So that it's
signature would become:

    (buffer-size &optional BUFFER-OR-NAME)

Other functions, like #'get-buffer already do this.

Thanks,
--
Daniel Nagy

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Eli Zaretskii]

> From: Daniel Nagy <danielnagy@posteo.de>
> Date: Wed, 01 Nov 2023 16:31:01 +0000
> 
> The current signature of #'buffer-size is:
> 
>     (buffer-size &optional BUFFER)
> 
> It can only handle actual buffer objects as the argument. Could it be
> made to accept the buffer name as a string as well? So that it's
> signature would become:
> 
>     (buffer-size &optional BUFFER-OR-NAME)
> 
> Other functions, like #'get-buffer already do this.

It's very easy to get the buffer from its name.  You could do

  (buffer-size (get-buffer BUFFER-OR-NAME))

So I wonder whether it is worth our while to convert more functions to
accept both buffers and names of buffers.

Stefan, WDYT?

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Stefan Kangas]

tags 66890 + moreinfo
thanks

Eli Zaretskii <eliz@gnu.org> writes:

> It's very easy to get the buffer from its name.  You could do
>
>   (buffer-size (get-buffer BUFFER-OR-NAME))
>
> So I wonder whether it is worth our while to convert more functions to
> accept both buffers and names of buffers.
>
> Stefan, WDYT?

I'd lean towards not making the proposed change, as it stands.

Perhaps, for the sake of consistency, we should allow buffer names in
either none or all buffer-related functions.  But the only example given
so far is `get-buffer', and I don't really see how we could possibly
disallow using strings there.  Thus, it's not very convincing.

If anyone is interested in making a better case for this change, a
single example is not enough.  I'd suggest starting with a review of
what we have now, for example something like `M-x apropos-function RET
^buffer- RET'.

Without such a review, I don't really see that we have grounds for
making any changes here.  So I'm tagging this bug "moreinfo".

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Daniel Nagy]

(resending only to debbugs.gnu.org because my previous mail had delivery
problems)

These are the additional functions/macros, that I found using `M-x
apropos-function', that accept both types of arguments:

    `buffer-hash'
    `buffer-match-p'
    `buffer-text-pixel-size'
    `bury-buffer'
    `display-buffer'
    `get-buffer-create'
    `get-buffer-window'
    `get-buffer-window-list'
    `kill-buffer'
    `pop-to-buffer'
    `project-display-buffer'
    `project-display-buffer-other-frame'
    `project-switch-to-buffer'
    `replace-buffer-in-windows'
    `set-buffer'
    `set-window-buffer'
    `switch-to-buffer'
    `switch-to-buffer-other-frame'
    `switch-to-buffer-other-tab'
    `switch-to-buffer-other-window'
    `tab-bar-get-buffer-tab'
    `temp-buffer-window-setup'
    `window-normalize-buffer'
    `window-normalize-buffer-to-switch-to'
    `with-current-buffer'
    `with-current-buffer-window'
    `with-displayed-buffer-window'
    `with-temp-buffer-window'

The number of functions, that only accept a buffer is vast and probably
outnumbers that list above, so I am not going to list them here.

These are some disadvantages of such a change, that come to my mind:

    1. Could the acceptance of a string in that place of the argument
       prohibit possible future possibilites?

    2. Does the newly accepted argument type sacrifice function purity
       and/or side-effect-freeness?

    3. API inconsistency.

    4. Slightly increased code complexity, especially in the C part of
       the code base.

My commentary in this particular case would be, that I dont see how now
accepting strings in addition would shadow any future usage of that ( or
other ) functions. Neither do I see how it would break function purity
or side-effect-freeness, but that could just be my lack of imagination.

As for the advantage my main argument would be convenience. It does
reduce user's elisp code and and makes smaller evaluations in the
minibuffer easier to type.

I wanted to file some more of such polymorphism suggestions. Would those
be welcome?

--
Daniel Nagy

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Eli Zaretskii]

> From: Daniel Nagy <danielnagy@posteo.de>
> Cc: Eli Zaretskii <eliz@gnu.org>, 66890@debbugs.gnu.org
> Date: Thu, 02 Nov 2023 20:38:35 +0000
> 
> These are the additional functions/macros, that I found using `M-x
> apropos-function', that accept both types of arguments:
> 
>     `buffer-hash'
>     `buffer-match-p'
>     `buffer-text-pixel-size'
>     `bury-buffer'
>     `display-buffer'
>     `get-buffer-create'
>     `get-buffer-window'
>     `get-buffer-window-list'
>     `kill-buffer'
>     `pop-to-buffer'
>     `project-display-buffer'
>     `project-display-buffer-other-frame'
>     `project-switch-to-buffer'
>     `replace-buffer-in-windows'
>     `set-buffer'
>     `set-window-buffer'
>     `switch-to-buffer'
>     `switch-to-buffer-other-frame'
>     `switch-to-buffer-other-tab'
>     `switch-to-buffer-other-window'
>     `tab-bar-get-buffer-tab'
>     `temp-buffer-window-setup'
>     `window-normalize-buffer'
>     `window-normalize-buffer-to-switch-to'
>     `with-current-buffer'
>     `with-current-buffer-window'
>     `with-displayed-buffer-window'
>     `with-temp-buffer-window'
> 
> The number of functions, that only accept a buffer is vast and probably
> outnumbers that list above, so I am not going to list them here.
> 
> These are some disadvantages of such a change, that come to my mind:
> 
>     1. Could the acceptance of a string in that place of the argument
>        prohibit possible future possibilites?
> 
>     2. Does the newly accepted argument type sacrifice function purity
>        and/or side-effect-freeness?
> 
>     3. API inconsistency.
> 
>     4. Slightly increased code complexity, especially in the C part of
>        the code base.
> 
> My commentary in this particular case would be, that I dont see how now
> accepting strings in addition would shadow any future usage of that ( or
> other ) functions. Neither do I see how it would break function purity
> or side-effect-freeness, but that could just be my lack of imagination.
> 
> As for the advantage my main argument would be convenience. It does
> reduce user's elisp code and and makes smaller evaluations in the
> minibuffer easier to type.
> 
> I wanted to file some more of such polymorphism suggestions. Would those
> be welcome?

I added Stefan Monnier to this discussion, in case he has an opinion
on this issue, which seems now to be about a vast change in Emacs.

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Daniel wrote:
> My commentary in this particular case would be, that I dont see how now
> accepting strings in addition would shadow any future usage of that ( or
> other ) functions.

In most cases, the arg is meant to hold nothing but a buffer, and
allowing a string would probably not get in the way at all, indeed.

This said, there are functions out there that accept either buffers
or strings where the meaning of strings is not "buffer name" (e.g. where
a buffer is instead taken to mean "the `buffer-string` of that buffer"),
so we couldn't make it work "everywhere".

> Neither do I see how it would break function purity or
> side-effect-freeness, but that could just be my lack of imagination.

Agreed.  There is a slight cost to accepting strings, tho.
Not a very strong argument either, tho.

> As for the advantage my main argument would be convenience.  It does
> reduce user's elisp code

Does it?  Could you show some examples of the kind of reductions you're
thinking of?

> and and makes smaller evaluations in the minibuffer easier to type.

Indeed, it can be occasionally handy in `M-:`.

Eli wrote:
> I added Stefan Monnier to this discussion, in case he has an opinion
> on this issue, which seems now to be about a vast change in Emacs.

I do have an opinion on this: I wish I could go back in time and get rid
of this `buffer-or-string` business altogether.

The reason is that I've seen several ELisp packages which abused buffer
names as "handles" for buffers, leading to nasty bugs when those buffers
get renamed (e.g. by things like uniquify).

It's not important enough to motivate making backward
incompatible changes.

Maybe we should just "de-emphasize" the fact that those functions also
accept strings, and instead insist that you have to go through
`get-buffer` (or `get-buffer-create`).  If that sounds vague and you
don't know what that would mean concretely, well.. you're not alone :-)


        Stefan

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Stefan Kangas]

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

> I do have an opinion on this: I wish I could go back in time and get rid
> of this `buffer-or-string` business altogether.
>
> The reason is that I've seen several ELisp packages which abused buffer
> names as "handles" for buffers, leading to nasty bugs when those buffers
> get renamed (e.g. by things like uniquify).

I'm not sure which way to lean here: writing ELisp customizations is
easier for regular users if these functions accept either buffer or
string.  It's also less verbose.

OTOH, perhaps you're right that it's just too brittle.

Do you have some sense for how common that class of bugs are?
My guess is that we have a few of them in our tree, too.

> It's not important enough to motivate making backward
> incompatible changes.
>
> Maybe we should just "de-emphasize" the fact that those functions also
> accept strings, and instead insist that you have to go through
> `get-buffer` (or `get-buffer-create`).  If that sounds vague and you
> don't know what that would mean concretely, well.. you're not alone :-)

Perhaps we could recommend against abusing it in `(elisp) Tips'.

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> I do have an opinion on this: I wish I could go back in time and get rid
>> of this `buffer-or-string` business altogether.
>>
>> The reason is that I've seen several ELisp packages which abused buffer
>> names as "handles" for buffers, leading to nasty bugs when those buffers
>> get renamed (e.g. by things like uniquify).
>
> I'm not sure which way to lean here: writing ELisp customizations is
> easier for regular users if these functions accept either buffer or
> string.  It's also less verbose.

What you write sounds obvious, but at the same time I'm hard pressed to
think of a customization where I'd pass a buffer name to a function that
usually takes a buffer.

The only use of `get-buffer` I could find in my own customizations is
one where accepting buffers-or-strings wouldn't help (I pass the
buffer to functions like `eq` rather than to functions that
specifically expect a buffer).

>> Maybe we should just "de-emphasize" the fact that those functions also
>> accept strings, and instead insist that you have to go through
>> `get-buffer` (or `get-buffer-create`).  If that sounds vague and you
>> don't know what that would mean concretely, well.. you're not alone :-)
> Perhaps we could recommend against abusing it in `(elisp) Tips'.

It's not as strong a "de-emphasize" as I was picturing, but yes,
that counts.


        Stefan

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Stefan Kangas]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> Maybe we should just "de-emphasize" the fact that those functions also
>>> accept strings, and instead insist that you have to go through
>>> `get-buffer` (or `get-buffer-create`).  If that sounds vague and you
>>> don't know what that would mean concretely, well.. you're not alone :-)
>> Perhaps we could recommend against abusing it in `(elisp) Tips'.
>
> It's not as strong a "de-emphasize" as I was picturing, but yes,
> that counts.

Feel free to propose other things we could do.  I just proposed the
first one that came to mind.  :-)

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Daniel Nagy]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> I do have an opinion on this: I wish I could go back in time and get
> rid of this `buffer-or-string` business altogether.

> The reason is that I've seen several ELisp packages which abused
> buffer names as "handles" for buffers, leading to nasty bugs when
> those buffers get renamed (e.g. by things like uniquify).

A reduced API surface will not prevent people from using buffer names as
handles. They will just wrap the string with `(get-buffer ...)' and call
it a day. That seems like a logic problem, that you cannot check for via
function arguments.

> Could you show some examples of the kind of reductions you're thinking
> of?

No, I cannot. This was mostly meant as a general statement. But maybe I
can argue in the other direction. What if things from that list above
were requiring to be more explicit. Such that you would need to write
`(with-current-buffer (get-buffer "mybuffer") ...)' instead of
`(with-current-buffer "mybuffer" ...)'. That would seem to me like an
(unnecessary) complication.

In general, I would say that, if the computer can unambigously decide
what is supposed to happen, it should help me and automatically correct
my "mistakes". Also I would argue, that is similar to what is already
present in Emacs with the dwim commands. Commands can behave differently
if, for example a region is active. So the "Do what I mean" notion
means, if I pass in a string, does the function unambigously know what I
mean with that? If yes, then it should do that.


--
Daniel Nagy

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Drew Adams]

My 2c, FWIW -

Things don't have to be all-or-nothing.  A general
principle or approach is one consideration.  But
there can be others.

Stefan mentioned, I think, some specific contexts
where it makes little/no sense to accept a buffer
name in place of a buffer, as an argument.  Fine.
The doc should anyway make clear whether an actual
buffer is required.

There are other (maybe most?) contexts where it
can make sense to accept either one.

Please take a look at vanilla library bookmark.el.
I'm not saying that things are equivalent.  And
bookmark functions constitute a more isolated
context than buffer contexts - the latter are more
numerous and more variable.

But FWIW, bookmark.el functions used to accept
only a bookmark as argument.  Over time they were
systematically changed to accept either a bookmark
name (a string) or a bookmark (a list structure).
___

(This wasn't influenced by Bookmark+, BTW; it has
nothing to do with me.  And in Bookmark+ I prefer
to use the less cumbersome arg name BOOKMARK
instead of the name BOOKMARK-NAME-OR-RECORD, even
when the arg can be either a name or a bookmark.)
___

Similarly, vanilla Emacs used to use the arg name
BUFFER everywhere (whether or not a name was also
allowed), and in many places that was changed
over time to BUFFER-OR-NAME.  That there might be
more places where it makes sense for a function to
accept either seems reasonable.  That functions
should be considered individually also makes sense.

Should `buffer-size' allow a string argument -
that's the question raise here, no?  And Eli asked
the more general question of "whether it is worth
our while to convert more functions to accept both
buffers and names of buffers."  Whether you look
at one or several functions at a time, each should
be considered individually.
___

(Again, to me, the arg name BUFFER is preferable,
as long as the doc string makes clear (which it
really needs to do anyway) that either a string
or a buffer can be passed as arg.  But I'm not
suggesting that Emacs should change its naming
convention (again) in this regard.)

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Eli Zaretskii]

> Cc: 66890@debbugs.gnu.org
> From: Daniel Nagy <danielnagy@posteo.de>
> Date: Sat, 04 Nov 2023 20:57:41 +0000
> 
> In general, I would say that, if the computer can unambigously decide
> what is supposed to happen, it should help me and automatically correct
> my "mistakes".

IME, this is a somewhat dangerous tendency.  In practice, it is easy
for a program to mistakenly interpret invalid inputs as some
transformation of valid ones, and do something that is very far from
what the caller meant.  So whether to "correct mistakes" or fail the
call is largely a judgment call, and it is not an accident that most
APIs prefer to fail in those cases, reserving the "correction" path
only for documented polymorphic situations.

bug#66890: 29.1; buffer-size should also accept the buffer's name as string argument

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> The reason is that I've seen several ELisp packages which abused
>> buffer names as "handles" for buffers, leading to nasty bugs when
>> those buffers get renamed (e.g. by things like uniquify).
> A reduced API surface will not prevent people from using buffer names as
> handles.

Indeed.  But the extra annoyance of having to use `get-buffer`
everywhere may push them to try and store the result of that
`get-buffer` somewhere.  It wouldn't eliminate the problem, but it would
have made it less common, I believe.  Not like it matters, tho.

[ When I look at all the programming languages out there, and how they
  are fundamentally almost all identical except for "cosmetic details"
  here and there, and the sometimes wildly different coding styles that
  come out of them, I end up with the conviction that those "cosmetic
  details" are what drives the coding styles.  :-)  ]

>> Could you show some examples of the kind of reductions you're thinking
>> of?
> No, I cannot. This was mostly meant as a general statement. But maybe I
> can argue in the other direction. What if things from that list above
> were requiring to be more explicit. Such that you would need to write
> `(with-current-buffer (get-buffer "mybuffer") ...)' instead of
> `(with-current-buffer "mybuffer" ...)'.

Oh, thanks.  Yes, these are very much the kinds of examples of
reductions I asked.  And indeed `grep` suggests we have quite some
number of those; and by now, you can guess that I see those as latent
bugs (aka "code smells")  :-(
Maybe we should add a compiler warning for that :-)

> In general, I would say that, if the computer can unambigously decide
> what is supposed to happen, it should help me and automatically correct
> my "mistakes".

I'm a big fan of that, also.  But indeed, while using a string as
"buffer" for one-off code in `M-:` would be handy, refusing it in "real"
ELisp code would help the programmer avoid that mistake :-)

> Also I would argue, that is similar to what is already
> present in Emacs with the dwim commands.

Indeed, commands are like `M-:`, so we like to have them "guess the
right thing" for us.  But note that we have DWIM commands but not DWIM
functions, because code needs to work right in "all" cases rather just
in the current specific circumstance, so it's much easier to write code
using functions that do just one thing only than using DWIM functions
which can do all kinds of different operations depending on
the circumstances.

> Commands can behave differently if, for example a region is active. So
> the "Do what I mean" notion means, if I pass in a string, does the
> function unambigously know what I mean with that?  If yes, then it
> should do that.

That can be handy, but encourages bad coding practices, so when we do
accept it we usually like to emit a warning.  Especially since most
ELisp programmers are far from experts at ELisp.  So we need to try and
help them avoid pitfalls.

Most buffers never change name, so it's easy for the occasional ELisp
programmer to think of the name as being just as good as the buffer
itself.  But their code will break down when it gets run in someone
else's setup where some local customization dynamically renames all
buffers to use a particular naming scheme.


        Stefan