Ruby Issue Tracking System: Issueshttps://bugs.ruby-lang.org/https://bugs.ruby-lang.org/favicon.ico?17113305112012-10-18T00:35:00ZRuby Issue Tracking System
Redmine Ruby master - Bug #7179 (Closed): IO doc: wrong/misleading text for modehttps://bugs.ruby-lang.org/issues/71792012-10-18T00:35:00Zroman-neuhauser (Roman Neuhauser)rneuhauser@suse.cz
<p>affects also 1.9.2, 1.9.1, 1.8.7</p>
<p><a href="http://www.ruby-doc.org/core-1.9.3/IO.html" class="external">http://www.ruby-doc.org/core-1.9.3/IO.html</a> makes the impression<br>
that "b" and "t" are valid on their own, when in fact they're<br>
modifiers and need to be preceded by one of the "real" modes<br>
(a, r, w, and the + variants):</p>
<blockquote>
<p>If the mode is given as a String, it must be one of the values<br>
listed in the following table.</p>
</blockquote>
<p>notice that "b" and "t" are among the listed values, so they're<br>
clearly permissible, right? (those "may appear" are also quite<br>
clear: "may" implies "does not need to").</p>
<pre><code>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").
</code></pre>
<p>i suggest splitting the table into two and adding a bit of prose<br>
explicitly saying that "b" and "t" cannot be used on their own.</p>
<p>background: i found a few occurrences of File.open(..., "b")<br>
in code by a seasoned ruby programmer who assumed "r" was implied<br>
in this situation.</p>