Bug #1666: Confusion in documentation for lines vs each_line, etc...

• Status: Closed
• Assignee: yugui (Yuki Sonoda)
• Target version: 1.9.2
• ruby -v: ruby 1.9.2dev (2009-06-20 trunk 23755) [i386-darwin9.7.0]

[marcandre (Marc-Andre Lafortune)]

=begin
Currently, IO#lines is defined as "to_enum(:each_line, *args)" and thus will ignore a block if one is given.
On the other hand, String#lines and String#each_line are aliases, and thus will both execute the block, if one given. The same is true for StringIO#lines and StringIO#each_line.

The same distinction exist in IO for #bytes vs #each_byte, #chars vs #each_char, while these pairs are aliases in String and StringIO.

To add to the confusion, the documentation is different for String#lines vs String#each_line, #bytes vs #each_byte, #chars vs #each_char (although they are aliases). StringIO#bytes, #lines & #chars are not documented at all.

So either:

1. there should not be a distinction (and IO's implementation and doc should be changed to reflect that)
   or 2) the distinction is intentional (and String + StringIO's implementation should be changed to relect that)
   or 3) there is a compelling reason why the behavior in IO should be different than in String and StringIO and that should be spelled out in the doc.

In all cases, the documentation for String should be cleaned up; for example String#each_char doesn't state that an enumerator is returned if no block is given (contrary to the doc for String#chars) and the examples are wrong since they use #each (which no longer exists) instead of #each_char.

Finally, the pair #codepoints and #each_codepoint is in a similar mismatch of documentation in String. I'll post a separate feature request to add IO#codepoints, etc...
=end

[yugui (Yuki Sonoda)]

• Assignee set to yugui (Yuki Sonoda)

=begin

=end

[mame (Yusuke Endoh)]

=begin
Hi,

Currently, IO#lines is defined as "to_enum(:each_line, *args)" and thus will ignore a block if one is given.
On the other hand, String#lines and String#each_line are aliases, and thus will both execute the block, if one given. The same is true for StringIO#lines and StringIO#each_line.

I think the inconsistency is caused by accident. Traditionally,
String#lines had returned an Enumerator ignoring a given block.
And it was changed at r11186 because of [ruby-core:09218].
I can find no reason why IO#lines are not changed similarly.
I guess it is just forgotten.

In addition, ARGF works similarly to String:

$ echo -e "foo\nbar\nbaz" | ./ruby -e '$<.lines {|x| p x }'
"foo\n"
"bar\n"
"baz\n"

$ echo -e "foo\nbar\nbaz" | ./ruby -e 'p $<.to_io.lines {|x| p x }'

This is apparently strange. So, I'll fix it soon by changing IO#
lines, etc. I'll also fix RubySpec.
(Of course, I'll revert this if matz says this is intended)

the documentation is different for String#lines vs String#each_line, #bytes vs #each_byte, #chars vs #each_char (although they are aliases).

Seems the same historical reason.

However, I wonder matz may still want people to use #each_line to
iterate and #lines to make an Enumerator, respectively.

StringIO#bytes, #lines & #chars are not documented at all.
In all cases, the documentation for String should be cleaned up

As you can see, my English is very poor. So I'll leave it to you.
Before you commit, please let us review a patch.

--
Yusuke Endoh [e-mail]
=end

[mame (Yusuke Endoh)]

• Status changed from Open to Closed
• % Done changed from 0 to 100

=begin
This issue was solved with changeset r26797.
Marc-Andre, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.

=end

[marcandre (Marc-Andre Lafortune)]

=begin
Documentation fixed in r26844.
=end