Re: query-replace-interactive not documented

[David Kastrup <dak@gnu.org>]

Richard Stallman <rms@gnu.org> writes:

>     Wel, optional spaces in the middle of regexp are something that
>     needs extra explaining....Actually, I can't think about much
>     except symbols here, and maybe forms like 'symbol which end up as
>     a list.
> 
> I think that is simple enough to explain.
> 
>     It does feel somewhat strange that the replacement expression
>     x + \,(1+ \#) + y;
>     would swallow a space,
> 
> It would not swallow a space; the reader would stop after the
> close paren.

So what is the rule?  The problem is that currently I just use
read-from-string, and that can't distinguish between
'symbol
and
(quote symbol)
even though it sounds as though both should be treated differently.

>     Have you taken a look at the DOC-string of the currently checked-in
>     version of query-replace-regexp?
> 
> No.  Did you check something in that doesn't agree with what
> I've said?

You are quoting it.

> These two paragraphs of doc string
> 
>     When this function is called interactively, the replacement text
>     can also contain `\\,' followed by a Lisp expression.  The escaped
>     shorthands for `query-replace-regexp-eval' are also valid
>     here: within the Lisp expression, you can use `\\&' for the whole
>     match string, `\\N' for partial matches, `\\#&' and `\\#N' for
>     the respective numeric values, and `\\#' for `replace-count'.
> 
>     If your Lisp expression is an identifier and the next
>     letter in the replacement string would be interpreted as part of it,
>     you can wrap it with an expression like `\\,(or \\#)'.  Incidentally,
>     for this particular case you may also enter `\\#' in the replacement
>     text directly.
> 
> would be clearer as follows:
> 
>     When this function is called interactively, the replacement text
>     can also contain `\\,' followed by a Lisp expression.  Each
>     replacement evaluates that expression to compute the replacement
>     string.  In the expression, you can use `\\&' for the whole
>     match string, `\\N' for partial matches, and `\\#' for the
>     sequence number (origin-zero) of this replacement.
> 
>     If the replacement expression is a symbol, write a space after it
>     to terminate it.

That's cheating.  It does not tell that this space will actually get
gobbled and won't appear in the replacement.  It does not tell just
_when_ such spaces will get gobbled.  It does not tell how many of
them might get gobbled.  So it is too easy.

I don't think you can do this much shorter than:

    If the replacement expression is a symbol, then it may be followed
    by one optional space that won't appear in the actual replacement.

> I left out the part about `\\#&' and `\\#N' because I don't
> understand what they do.  I am not sure what "respective numeric
> values" means.  When I tried \#&, it seemed to insert the
> replacement count followed by an &.

Not _within_ a Lisp expression, namely something like
\,(format "%d %d" \#& \#2).  And if you had a match like
\([0-9]+\), then you can do arithmetic on it with something like
\,(1+ \#1).

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum