Possible Regexp documentation bug

Hi all,

I think I found a small bug in the description of the
Regexp.escape method 
(http://www.ruby-doc.org/core/classes/Regexp.html#M001216
).

It says:

"(Regexp.escape) Escapes any characters that would have
special meaning in 
a regular expression. Returns a new escaped string, or self
if no 
characters are escaped. For any string,
Regexp.escape(str)=~str will be 
true."

I think the last part is incorrect. The left-hand side of
the =~ operator 
should be a string, the right-hand side should be a regexp.
So if the 
escape method does change anything, the condition will not
hold.

I think it would be more accurate to say:

   "str =~ Regexp.escape(str) will be true."

Is that right? And how should one go about changing the
documentation?

Cheers, Chris.
-- 
_____ __     _
  __/ / ,__(_)_  | Chris Wilson <0000 at qwirx.com> -
Cambs UK |
/ (_/ ,/ _/ /_  | Security/C/C++/Java/Perl/SQL/HTML
Developer |
 _/_/_/_//_/___/ | We are GNU-free your mind-and your
software |

On Jul 15, 2007, at 10:39 , Chris Wilson wrote:

> Hi all,
>
> I think I found a small bug in the description of the
Regexp.escape  
> method (http://www.ruby-doc.org/core/classes/Regexp.html#M001216
).
>
> It says:
>
> "(Regexp.escape) Escapes any characters that would
have special  
> meaning in a regular expression. Returns a new escaped
string, or  
> self if no characters are escaped. For any string,
Regexp.escape 
> (str)=~str will be true."
>
> I think the last part is incorrect. The left-hand side
of the =~  
> operator should be a string, the right-hand side should
be a  
> regexp. So if the escape method does change anything,
the condition  
> will not hold.
>
> I think it would be more accurate to say:
>
>   "str =~ Regexp.escape(str) will be true."

502 % ri Regexp.=~
No, it works either way:

------------------------------------------------------------
-- Regexp#=~
      rxp.match(str)   => matchdata or nil
------------------------------------------------------------
------------
      Returns a +MatchData+ object describing the match, or
+nil+ if
      there was no match. This is equivalent to retrieving
the value of
      the special variable +$~+ following a normal match.

         /(.)(.)(.)/.match("abc")[2]   #=>
"b"

> Is that right? And how should one go about changing the
documentation?

You'd check out the source for ruby via subversion, make and
test the  
change, and thes submit the patch on the ruby project on  
rubyforge.org assigning the documentation category to it.

On 15/07/07, Chris Wilson <chrisqwirx.com> wrote:
> Hi all,
>
> I think I found a small bug in the description of the
Regexp.escape method
> (http://www.ruby-doc.org/core/classes/Regexp.html#M001216
).
>
> It says:
>
> "(Regexp.escape) Escapes any characters that would
have special meaning in
> a regular expression. Returns a new escaped string, or
self if no
> characters are escaped. For any string,
Regexp.escape(str)=~str will be
> true."
>
> I think the last part is incorrect. The left-hand side
of the =~ operator
> should be a string, the right-hand side should be a
regexp. So if the
> escape method does change anything, the condition will
not hold.
>
> I think it would be more accurate to say:
>
>    "str =~ Regexp.escape(str) will be true."
>
> Is that right? And how should one go about changing the
documentation?
>
> Cheers, Chris.

While =~ is not an operator, it is a method of String and
Regexp
instances, Regexp.escape (from quick irb testing) returns a
string.
And String#=~ expects a Regexp instance, not a string. So I
think it
would be correct to change that to something like
`Regexp.escape(str)
=~ Regexp.new(str) will be true'.

On Jul 15, 2007, at 10:39 , Chris Wilson wrote:

> Hi all,
>
> I think I found a small bug in the description of the
Regexp.escape  
> method (http://www.ruby-doc.org/core/classes/Regexp.html#M001216
).
>
> It says:
>
> "(Regexp.escape) Escapes any characters that would
have special  
> meaning in a regular expression. Returns a new escaped
string, or  
> self if no characters are escaped. For any string,
Regexp.escape 
> (str)=~str will be true."
>
> I think the last part is incorrect. The left-hand side
of the =~  
> operator should be a string, the right-hand side should
be a  
> regexp. So if the escape method does change anything,
the condition  
> will not hold.
>
> I think it would be more accurate to say:
>
>   "str =~ Regexp.escape(str) will be true."

502 % ri Regexp.=~
No, it works either way:

------------------------------------------------------------
-- Regexp#=~
      rxp.match(str)   => matchdata or nil
------------------------------------------------------------
------------
      Returns a +MatchData+ object describing the match, or
+nil+ if
      there was no match. This is equivalent to retrieving
the value of
      the special variable +$~+ following a normal match.

         /(.)(.)(.)/.match("abc")[2]   #=>
"b"

> Is that right? And how should one go about changing the
documentation?

You'd check out the source for ruby via subversion, make and
test the  
change, and thes submit the patch on the ruby project on  
rubyforge.org assigning the documentation category to it.

On 15/07/07, Chris Wilson <chrisqwirx.com> wrote:
> Hi all,
>
> I think I found a small bug in the description of the
Regexp.escape method
> (http://www.ruby-doc.org/core/classes/Regexp.html#M001216
).
>
> It says:
>
> "(Regexp.escape) Escapes any characters that would
have special meaning in
> a regular expression. Returns a new escaped string, or
self if no
> characters are escaped. For any string,
Regexp.escape(str)=~str will be
> true."
>
> I think the last part is incorrect. The left-hand side
of the =~ operator
> should be a string, the right-hand side should be a
regexp. So if the
> escape method does change anything, the condition will
not hold.
>
> I think it would be more accurate to say:
>
>    "str =~ Regexp.escape(str) will be true."
>
> Is that right? And how should one go about changing the
documentation?
>
> Cheers, Chris.

While =~ is not an operator, it is a method of String and
Regexp
instances, Regexp.escape (from quick irb testing) returns a
string.
And String#=~ expects a Regexp instance, not a string. So I
think it
would be correct to change that to something like
`Regexp.escape(str)
=~ Regexp.new(str) will be true'.

On Sun, 15 Jul 2007, Konrad Meyer wrote:

>>  "(Regexp.escape) Escapes any characters that
would have special meaning in
>>  a regular expression. Returns a new escaped
string, or self if no
>>  characters are escaped. For any string,
Regexp.escape(str)=~str will be
>>  true."
...
>>  I think it would be more accurate to say:
>>
>>     "str =~ Regexp.escape(str) will be
true."
...
> While =~ is not an operator, it is a method of String
and Regexp
> instances, Regexp.escape (from quick irb testing)
returns a string.
> And String#=~ expects a Regexp instance, not a string.
So I think it
> would be correct to change that to something like
`Regexp.escape(str)
> =~ Regexp.new(str) will be true'.

Thanks Konrad and Ryan. Is the attached patch acceptable,
documenting both 
forms in what I believe is the correct way?

Cheers, Chris.
-- 
_____ __     _
  __/ / ,__(_)_  | Chris Wilson <0000 at qwirx.com> -
Cambs UK |
/ (_/ ,/ _/ /_  | Security/C/C++/Java/Perl/SQL/HTML
Developer |
 _/_/_/_//_/___/ | We are GNU-free your mind-and your
software |

On 15/07/07, Chris Wilson <chrisqwirx.com> wrote:
> On Sun, 15 Jul 2007, Konrad Meyer wrote:
>
> >>  "(Regexp.escape) Escapes any characters
that would have special meaning in
> >>  a regular expression. Returns a new escaped
string, or self if no
> >>  characters are escaped. For any string,
Regexp.escape(str)=~str will be
> >>  true."
> ...
> >>  I think it would be more accurate to say:
> >>
> >>     "str =~ Regexp.escape(str) will be
true."
> ...
> > While =~ is not an operator, it is a method of
String and Regexp
> > instances, Regexp.escape (from quick irb testing)
returns a string.
> > And String#=~ expects a Regexp instance, not a
string. So I think it
> > would be correct to change that to something like
`Regexp.escape(str)
> > =~ Regexp.new(str) will be true'.
>
> Thanks Konrad and Ryan. Is the attached patch
acceptable, documenting both
> forms in what I believe is the correct way?

I think the bit after the `and' is excessive. It's not the
job of this
method's documentation to clarify that str =~ rxp is the
same as rxp
=~ str.

On 15/07/07, Chris Wilson <chrisqwirx.com> wrote:
> On Sun, 15 Jul 2007, Konrad Meyer wrote:
>
> >>  "(Regexp.escape) Escapes any characters
that would have special meaning in
> >>  a regular expression. Returns a new escaped
string, or self if no
> >>  characters are escaped. For any string,
Regexp.escape(str)=~str will be
> >>  true."
> ...
> >>  I think it would be more accurate to say:
> >>
> >>     "str =~ Regexp.escape(str) will be
true."
> ...
> > While =~ is not an operator, it is a method of
String and Regexp
> > instances, Regexp.escape (from quick irb testing)
returns a string.
> > And String#=~ expects a Regexp instance, not a
string. So I think it
> > would be correct to change that to something like
`Regexp.escape(str)
> > =~ Regexp.new(str) will be true'.
>
> Thanks Konrad and Ryan. Is the attached patch
acceptable, documenting both
> forms in what I believe is the correct way?

Er, and also the changelog entry for documentation is
probably a
little excessive.

Hi Konrad,

On Sun, 15 Jul 2007, Konrad Meyer wrote:

>> >  While =~ is not an operator, it is a method
of String and Regexp
>> >  instances, Regexp.escape (from quick irb
testing) returns a string.
>> >  And String#=~ expects a Regexp instance, not
a string. So I think it
>> >  would be correct to change that to something
like `Regexp.escape(str)
>> >  =~ Regexp.new(str) will be true'.

I didn't spot this when replying to your previous message,
but I believe 
that it's still incorrect, because it treats the unescaped
str as a valid 
regexp (on the right) and compares it with the escaped form
(on the left) 
as though that were the original string.

I guess that str =~ Regexp.new(Regexp.escape(str)) is
correct?

> I think the bit after the `and' is excessive. It's not
the job of this 
> method's documentation to clarify that str =~ rxp is
the same as rxp =~ 
> str.

OK, then which is the preferred form in Ruby? I'm more
accustomed to the 
Perl form, where str =~ rxp.

> Er, and also the changelog entry for documentation is
probably a
> little excessive.

Sorry, I'm new here, I was just following the advice on the
website. I'll 
remove it.

Cheers, Chris.
-- 
_____ __     _
  __/ / ,__(_)_  | Chris Wilson <0000 at qwirx.com> -
Cambs UK |
/ (_/ ,/ _/ /_  | Security/C/C++/Java/Perl/SQL/HTML
Developer |
 _/_/_/_//_/___/ | We are GNU-free your mind-and your
software |

On Sun, 15 Jul 2007, Konrad Meyer wrote:

>>  "(Regexp.escape) Escapes any characters that
would have special meaning in
>>  a regular expression. Returns a new escaped
string, or self if no
>>  characters are escaped. For any string,
Regexp.escape(str)=~str will be
>>  true."
...
>>  I think it would be more accurate to say:
>>
>>     "str =~ Regexp.escape(str) will be
true."
...
> While =~ is not an operator, it is a method of String
and Regexp
> instances, Regexp.escape (from quick irb testing)
returns a string.
> And String#=~ expects a Regexp instance, not a string.
So I think it
> would be correct to change that to something like
`Regexp.escape(str)
> =~ Regexp.new(str) will be true'.

Thanks Konrad and Ryan. Is the attached patch acceptable,
documenting both 
forms in what I believe is the correct way?

Cheers, Chris.
-- 
_____ __     _
  __/ / ,__(_)_  | Chris Wilson <0000 at qwirx.com> -
Cambs UK |
/ (_/ ,/ _/ /_  | Security/C/C++/Java/Perl/SQL/HTML
Developer |
 _/_/_/_//_/___/ | We are GNU-free your mind-and your
software |