Bug #7179

IO doc: wrong/misleading text for mode

Added by Roman Neuhauser almost 3 years ago. Updated almost 3 years ago.

[ruby-core:48052]
Status:Closed
Priority:Normal
Assignee:-
ruby -v:ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-linux] Backport:

Description

affects also 1.9.2, 1.9.1, 1.8.7

http://www.ruby-doc.org/core-1.9.3/IO.html makes the impression
that "b" and "t" are valid on their own, when in fact they're
modifiers and need to be preceded by one of the "real" modes
(a, r, w, and the + variants):

If the mode is given as a String, it must be one of the values
listed in the following table.

notice that "b" and "t" are among the listed values, so they're
clearly permissible, right? (those "may appear" are also quite
clear: "may" implies "does not need to").

Mode Meaning
"r" Read-only, starts at beginning of file (default mode).
-----+--------------------------------------------------------
"r+" |  Read-write, starts at beginning of file.
-----+--------------------------------------------------------
"w"  |  Write-only, truncates existing file
     |  to zero length or creates a new file for writing.
-----+--------------------------------------------------------
"w+" |  Read-write, truncates existing file to zero length
     |  or creates a new file for reading and writing.
-----+--------------------------------------------------------
"a"  |  Write-only, starts at end of file if file exists,
     |  otherwise creates a new file for writing.
-----+--------------------------------------------------------
"a+" |  Read-write, starts at end of file if file exists,
     |  otherwise creates a new file for reading and
     |  writing.
-----+--------------------------------------------------------
 "b" |  Binary file mode (may appear with
     |  any of the key letters listed above).
     |  Suppresses EOL <-> CRLF conversion on Windows. And
     |  sets external encoding to ASCII-8BIT unless explicitly
     |  specified.
-----+--------------------------------------------------------
 "t" |  Text file mode (may appear with
     |  any of the key letters listed above except "b").

i suggest splitting the table into two and adding a bit of prose
explicitly saying that "b" and "t" cannot be used on their own.

background: i found a few occurrences of File.open(..., "b")
in code by a seasoned ruby programmer who assumed "r" was implied
in this situation.

Associated revisions

Revision 37443
Added by Zachary Scott almost 3 years ago

  • io.c (IO#new): Documentation for IO#open modes and formatting [ruby-core#48052] [Bug #7179]

Revision 37443
Added by Zachary Scott almost 3 years ago

  • io.c (IO#new): Documentation for IO#open modes and formatting [ruby-core#48052] [Bug #7179]

Revision 37444
Added by Zachary Scott almost 3 years ago

  • io.c (IO#new): Documentation for IO#open modes and formatting [ruby-core#48052] [Bug #7179]

Revision 37444
Added by Zachary Scott almost 3 years ago

  • io.c (IO#new): Documentation for IO#open modes and formatting [ruby-core#48052] [Bug #7179]

Revision 37568
Added by Zachary Scott over 2 years ago

  • io.c (IO#new): Fix indentation from r37444 [Bug #7179]

Revision 37568
Added by Zachary Scott over 2 years ago

  • io.c (IO#new): Fix indentation from r37444 [Bug #7179]

History

#1 Updated by Zachary Scott almost 3 years ago

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

This issue was solved with changeset r37443.
Roman, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.


  • io.c (IO#new): Documentation for IO#open modes and formatting [ruby-core#48052] [Bug #7179]

Also available in: Atom PDF