Forum: Ruby-core [Bug #1666] Confusion in documentation for lines vs each_line, etc...

Bug #1666: Confusion in documentation for lines vs each_line, etc...
http://redmine.ruby-lang.org/issues/show/1666

Author: Marc-Andre Lafortune
Status: Open, Priority: Normal
Category: core, Target version: 1.9.2
ruby -v: ruby 1.9.2dev (2009-06-20 trunk 23755) [i386-darwin9.7.0]

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

Issue #1666 has been updated by Yusuke Endoh.


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 <mame@tsg.ne.jp>
----------------------------------------
http://redmine.ruby-lang.org/issues/show/1666

Issue #1666 has been updated by Yusuke Endoh.

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

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.

----------------------------------------
http://redmine.ruby-lang.org/issues/show/1666

Issue #1666 has been updated by Marc-Andre Lafortune.


Documentation fixed in r26844.
----------------------------------------
http://redmine.ruby-lang.org/issues/show/1666