Re: query-replace-interactive not documented

[Richard Stallman]

    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.

    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?


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.

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


*** replace.el  17 Jun 2004 19:28:37 -0400      1.173
--- replace.el  19 Jun 2004 21:26:16 -0400      
***************
*** 165,181 ****
  whatever what matched the Nth `\\(...\\)' in REGEXP.
  
  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.
  
  When you use `\\,' or `\\#' in the replacement, TO-STRING actually
  becomes a list with expanded shorthands.
--- 165,178 ----
  whatever what matched the Nth `\\(...\\)' in REGEXP.
  
  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.
  
  When you use `\\,' or `\\#' in the replacement, TO-STRING actually
  becomes a list with expanded shorthands.
***************
*** 200,206 ****
                    ((eq char ?\,)
                     (setq pos (read-from-string to-string))
                     (push `(replace-quote ,(car pos)) to-expr)
!                    (setq to-string (substring to-string (cdr pos))))))
            (setq to-expr (nreverse (delete "" (cons to-string to-expr))))
            (replace-match-string-symbols to-expr)
            (cons 'replace-eval-replacement 
--- 197,211 ----
                    ((eq char ?\,)
                     (setq pos (read-from-string to-string))
                     (push `(replace-quote ,(car pos)) to-expr)
!                    (let ((end
!                           ;; Swallow a space after a symbol
!                           ;; if there is a space.
!                           (if (and (symbolp (car pos))
!                                    (equal " " (substring to-string (cdr pos)
!                                                          (1+ (cdr pos)))))
!                               (1+ (cdr pos))
!                             (cdr pos))))
!                      (setq to-string (substring to-string end))))))
            (setq to-expr (nreverse (delete "" (cons to-string to-expr))))
            (replace-match-string-symbols to-expr)
            (cons 'replace-eval-replacement