GNU bug report logs - #20395
24.3; Documentation for `replace-regexp-in-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 20395 in the body.
You can then email your comments to 20395 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: Eli Barzilay <eli <at> barzilay.org>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3; Documentation for `replace-regexp-in-string'
Date: Tue, 21 Apr 2015 05:59:01 -0400

(In GNU Emacs 24.3.1, but same in git)

I tried to use `replace-regexp-in-string' like this:

    (let ((text "foo\nbar\nbaz\n") (r "*"))
      (replace-regexp-in-string
       "\n\\(.\\)"
       (lambda (_) (concat "\n" r (match-string 1 text)))
       text))

and it surprised me that this didn't work.  Looking at the docstring,
I found this

    When REP is called, the match data are the result of matching
    REGEXP against a substring of STRING.

and IMO that "a substring" is very subtle and easy to miss.  I then
looked at the code, and at least in its current form, I saw that I
could do this instead:

    (let ((text "foo\nbar\nbaz\n") (r "*"))
      (replace-regexp-in-string
       "\n\\(.\\)"
       (lambda (s) (concat "\n" r (match-string 1 s)))
       text))

So I think that it would be really good if this was made explicit in
the documentation, better with an example.  Something like

    When REP is called, the match data are the result of matching
    REGEXP against only the currently matched substring of STRING.
    For example, (lambda (s) (concat "<" (match-string 1 s) ">")) as
    REP is equivalent to "<\\1>".

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Eli Barzilay <eli <at> barzilay.org>
Cc: 20395 <at> debbugs.gnu.org
Subject: Re: bug#20395: 24.3; Documentation for `replace-regexp-in-string'
Date: Tue, 21 Apr 2015 18:00:01 +0300

> From: Eli Barzilay <eli <at> barzilay.org>
> Date: Tue, 21 Apr 2015 05:59:01 -0400
> 
>     When REP is called, the match data are the result of matching
>     REGEXP against a substring of STRING.
> 
> and IMO that "a substring" is very subtle and easy to miss.  I then
> looked at the code, and at least in its current form, I saw that I
> could do this instead:
> 
>     (let ((text "foo\nbar\nbaz\n") (r "*"))
>       (replace-regexp-in-string
>        "\n\\(.\\)"
>        (lambda (s) (concat "\n" r (match-string 1 s)))
>        text))
> 
> So I think that it would be really good if this was made explicit in
> the documentation, better with an example.  Something like
> 
>     When REP is called, the match data are the result of matching
>     REGEXP against only the currently matched substring of STRING.
>     For example, (lambda (s) (concat "<" (match-string 1 s) ">")) as
>     REP is equivalent to "<\\1>".

Thanks.

However, I wonder whether your suggested change is really enough of an
improvement.  AFAIU, the main problem with the existing doc string is
that it doesn't explain _which_ substring is being alluded to here, it
only hints on the answer.  And your suggested change also leaves that
part unexplained, leaving it to the reader to glean that from the fact
that 'concat' is being used.

So I think it would be good to come up with text that actually makes
that part clear.  WDYT?

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Eli Barzilay <eli <at> barzilay.org>
Cc: 20395-done <at> debbugs.gnu.org
Subject: Re: bug#20395: 24.3; Documentation for `replace-regexp-in-string'
Date: Sat, 25 Apr 2015 12:40:06 +0300

> From: Eli Barzilay <eli <at> barzilay.org>
> Date: Tue, 21 Apr 2015 05:59:01 -0400
> 
> (In GNU Emacs 24.3.1, but same in git)
> 
> I tried to use `replace-regexp-in-string' like this:
> 
>     (let ((text "foo\nbar\nbaz\n") (r "*"))
>       (replace-regexp-in-string
>        "\n\\(.\\)"
>        (lambda (_) (concat "\n" r (match-string 1 text)))
>        text))
> 
> and it surprised me that this didn't work.  Looking at the docstring,
> I found this
> 
>     When REP is called, the match data are the result of matching
>     REGEXP against a substring of STRING.
> 
> and IMO that "a substring" is very subtle and easy to miss.  I then
> looked at the code, and at least in its current form, I saw that I
> could do this instead:
> 
>     (let ((text "foo\nbar\nbaz\n") (r "*"))
>       (replace-regexp-in-string
>        "\n\\(.\\)"
>        (lambda (s) (concat "\n" r (match-string 1 s)))
>        text))
> 
> So I think that it would be really good if this was made explicit in
> the documentation, better with an example.  Something like
> 
>     When REP is called, the match data are the result of matching
>     REGEXP against only the currently matched substring of STRING.
>     For example, (lambda (s) (concat "<" (match-string 1 s) ">")) as
>     REP is equivalent to "<\\1>".

I tried to clarify this issue in a slightly different way.

Previous Next

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