bug#58177: Return value of perform-replace and its documentation string

bug#58177: Return value of perform-replace and its documentation string

[Ruy Exel]

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

bug#58177: Return value of perform-replace and its documentation string

[Lars Ingebrigtsen]

Ruy Exel <ruyexel@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?

bug#58177: Return value of perform-replace and its documentation string

[Juri Linkov]

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

bug#58177: Return value of perform-replace and its documentation string

[Lars Ingebrigtsen]

Juri Linkov <juri@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.