GNU bug report logs - #58177
Return value of perform-replace and its documentation string

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 58177 in the body.
You can then email your comments to 58177 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: Ruy Exel <ruyexel <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Return value of perform-replace and its documentation string
Date: Thu, 29 Sep 2022 15:02:17 -0300

This bug report was suggested to me by Emacs Stack Exchange user
"db48x" in a reply to my question "How to count number of replacements
made by "query-replace?"
(https://emacs.stackexchange.com/questions/73860/how-to-count-number-of-replacements-made-by-query-replace)
and corroborated by user "dalanicolai".

Primarily this is related to the documentation string of the emacs
function "perform-replace" which says:

"This function returns nil if and only if there were no matches to
make, or the user didn’t cancel the call."

Since the return value IS NIL when the user DID cancel the call, the
documentation string appears to be incorrect.

On the other hand, it seems to me that the actual behavior, namely
returning nil upon cancellation, is not the ideal behavior.

Recall that the return value of perform-replace, when not interrupted
by the user, is a list giving information regarding the replacements
tried, including those actually made.

In case the user decides to reply "yes" to the first few queries, and
then decides to reply with "q", canceling the command, the return
value of nil cannot be used to determine which replacements were made,
which in turn might be of interest in certain circumstances, as in the
one described in my Emacs Stack Exchange question mentioned above.

Thus, I would like to add a feature request to this bug report, namely
that the return value of perform-replace, in case it is canceled by
the user, be changed from nil to some other value reflecting the
replacements considered before the cancel request.

Yours,
Ruy Exel

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Ruy Exel <ruyexel <at> gmail.com>
Cc: 58177 <at> debbugs.gnu.org
Subject: Re: bug#58177: Return value of perform-replace and its
 documentation string
Date: Fri, 30 Sep 2022 15:25:45 +0200

Ruy Exel <ruyexel <at> gmail.com> writes:

> Thus, I would like to add a feature request to this bug report, namely
> that the return value of perform-replace, in case it is canceled by
> the user, be changed from nil to some other value reflecting the
> replacements considered before the cancel request.

Yes, I think that makes sense.  An alternate value would be to return a
list of all considered replacements, but marking all the ones after the
`q' the same way as the `n's are marked.  I.e., `q' as a way of saying
"skip all the rest", which it is, in a way.

Anybody have any opinions here?

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

From: Juri Linkov <juri <at> linkov.net>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 58177 <at> debbugs.gnu.org, Ruy Exel <ruyexel <at> gmail.com>
Subject: Re: bug#58177: Return value of perform-replace and its
 documentation string
Date: Sat, 01 Oct 2022 22:13:31 +0300

>> Thus, I would like to add a feature request to this bug report, namely
>> that the return value of perform-replace, in case it is canceled by
>> the user, be changed from nil to some other value reflecting the
>> replacements considered before the cancel request.
>
> Yes, I think that makes sense.  An alternate value would be to return a
> list of all considered replacements, but marking all the ones after the
> `q' the same way as the `n's are marked.  I.e., `q' as a way of saying
> "skip all the rest", which it is, in a way.
>
> Anybody have any opinions here?

Unfortunately, nil value is used to decide whether to continue
to the next file in multi-buffer replacements.  Examples of such code
including but not limited to: xref--query-replace-1 that contains

(defun xref--query-replace-1 (from to iter)
  (let* ((continue t)
    ...
    (while (and continue ...
      ...
      (setq continue
            (perform-replace from to t t nil nil multi-query-replace-map)))
      ...

and

(defun fileloop-continue ()
    ...
    (while
      ...
      (save-restriction
        (widen)
        (funcall fileloop--operate-function)))
      (setq file-finished t))))

etc.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Juri Linkov <juri <at> linkov.net>
Cc: 58177 <at> debbugs.gnu.org, Ruy Exel <ruyexel <at> gmail.com>
Subject: Re: bug#58177: Return value of perform-replace and its
 documentation string
Date: Sun, 02 Oct 2022 14:09:58 +0200

Juri Linkov <juri <at> linkov.net> writes:

> Unfortunately, nil value is used to decide whether to continue
> to the next file in multi-buffer replacements.

Hm, right.  We could add Yet Another Parameter to change the return
value, but I'm not sure whether that would be valuable (especially since
there's already 11 parameter).

So I guess the only thing to do here is to fix the doc string, and I've
now done that in Emacs 29.

Previous Next

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