[ruby-core:30602] The `open` Methods and Their Many Arguments

I'm documenting Kernel.open, and the related .open methods, for a book
about 1.9 I'm writing, and finding the combinatorics of the
interactions between the various options a bit difficult. The below
are some of the assumptions I'm making. Are any of these incorrect?
Any other clues to how all the parts fit together?

1. A file is opened in textmode, binmode, or a third unnamed alternative.
1.1 binmode and textmode are mutually exclusive.
1.2 binmode disables newline conversion on all platforms unless any of
the :crlf_newline, :cr_newline, or :universal_newline options are set.
1.3 binmode sets the external encoding of the stream to ASCII-8BIT
unless an external encoding is explicitly specified. (An exception to
this rule is documented in
http://redmine.ruby-lang.org/issues/show/3392)
1.4 binmode disables automatic transcoding of the stream unless a pair
of encodings have been specified via :mode, :encoding, or
:external_encoding and :internal_encoding.
1.5 binmode is obligatory when reading a file with an
ASCII-incompatible encoding.
1.6 binmode causes the stream's #binmode? method to return true
1.7 A stream can be set to binmode after opening with the stream's
#binmode method.
1.8 This applies even to a stream that was already in textmode. (I've
yet to consider the implications of this).
1.9 textmode causes \r\n to be replaced with \n, and other occurrences
of \r to be replaced by \n, when reading from a stream. I believe this
to happen on all platforms.
1.10 Therefore, textmode is equivalent the :universal_newline option
being set when reading from a stream.
1.11 textmode causes \n to be replaced with \r\n when writing to a
stream under Windows.
1.12 Therefore, textmode is equivalent to the :crlf_newline option
being set when writing to a stream under Windows.
1.13 textmode has no effect when writing to a stream on a non-Windows platform.
1.14 Unlike #binmode?, a stream cannot be queried for whether it is in textmode.
1.15 Correspondingly, a stream cannot be changed to textmode without
opening it again.
1.16 When neither textmode nor binmode are specified, the third
unnamed alternative is selected.
1.17 This option cannot be set explicitly via the opts Hash; it is
implied by the absence of both :textmode and :binmode.
1.18 This option has no effect on transcoding.
1.19 This option has no effect on newline conversion.
2 The :encoding key specifies the internal, external, or both encodings.
2.1 A value that is the name of one encoding sets the external
encoding of the stream to that encoding.
2.2 If the above value is prefixed with a colon, it is taken to be the
internal encoding of the stream.
2.3 If a pair of encodings is specified with their names separated by
a colon, they become the external and internal encodings of the
stream, respectively.
2.4 If the value consists of an encoding followed by a colon, the
named encoding becomes the external encoding of the stream. (A warning
is also triggered).
2.5 If the value consists of an encoding name followed by a colon then
a hyphen, the external encoding is set to the named encoding, and the
internal encoding is set to nil. Which is to say, the default internal
encoding is ignored.
2.6 However, if the value consists of a hyphen, followed by a colon,
followed by an encoding name, the named encoding is interpreted as the
stream's internal encoding whereas the hyphen is interpreted as
garbage.(A warning is issued).
2.7 The value may begin with the case insensitive string 'BOM|'
followed by an encoding name. This causes the external encoding to be
inferred from the BoM, if possible, or otherwise set to the named
encoding.
2.8 If an encoding that does not support a BoM is prefixed with
'BOM|', the encoding is ignored, and the stream's external encoding
defaults to Encoding.default_external. (A warning is triggered).
2.9 Otherwise, an external encoding name prefixed with 'BOM|' behaves
like any other external encoding.
2.10 If an external and/or internal encoding is specified with an
illegal name, it is ignored. (A warning is triggered).
3 The external encoding may be set by providing an encoding name as
the value of an :external_encoding key,
3.1 However, in this form the encoding name may not be prefixed with 'BOM|'.
3.2 Further, in this form illegal encoding names cause an
ArgumentError to be raised, c.f. 2.10.
4 The internal encoding may be set by providing an encoding name as
the value of an :internal_encoding key,
4.1 In this form, too, a value of a sole hyphen causes the stream's
internal encoding to be assigned nil, regardless of the value of
Encoding.default_internal
4.2 In this form illegal encoding names cause an ArgumentError to be raised.
5 Unless both an external and internal encoding is specified by a
combination of the :encoding, :internal_encoding, and
:external_encoding options, their omitted values are assumed to be
those of Encoding.default_external or Encoding.default_internal,
respectively.
6 A :perm key is accepted whose value is the permission bits of the
file being created. This isn't documented.

This is clearly only scratching the surface, but is as far as I've
gotten. I suspect that 3.1 and 6 constitute bugs--if so, should I
report them?, while 1.14 represents a possible feature in the name of
consistency.

I notice that Encoding::Converter has particularly useful #inspect
output (econv_description() in transcode.c) wherein the options that
are in effect are specified. Is there any interest in something like
this for File#inspect, or am I the only one to find it all confusing?
;-)