Keyword argument docs for read are misleading

[tkelman]

This is via @aviks, we were looking at this in the morning:

help?> read
search: read read! readdlm readdir readcsv readall readlink readline readuntil readlines readchomp

  read(stream::IO, T)

  Read a single value of type T from stream, in canonical binary representation.

  read(stream::IO, T, dims)

  Read a series of values of type T from stream, in canonical binary representation. dims is either
  a tuple or a series of integer arguments specifying the size of the Array{T} to return.

  read(filename::AbstractString, args...)

  Open a file and read its contents. args is passed to read: this is equivalent to open(io->read(io,
  args...), filename).

  read(stream::IO, nb=typemax(Int); all=true)

  Read at most nb bytes from stream, returning a Vector{UInt8} of the bytes read.

  If all is true (the default), this function will block repeatedly trying to read all requested
  bytes, until an error or end-of-file occurs. If all is false, at most one read call is performed,
  and the amount of data returned is device-dependent. Note that not all stream types support the
  all option.

julia> s = TCPSocket()
TCPSocket(init, 0 bytes waiting)

julia> read(s, 10; all=true)
ERROR: MethodError: no method matching (::Base.#kw##read)(::Array{Any,1}, ::Base.#read, ::TCPSocket, ::Int64)
Closest candidates are:
  #read(::Array{Any,1}, ::Base.#read, ::IOStream, ::Integer)
 in eval(::Module, ::Any) at .\boot.jl:231
 in macro expansion at .\REPL.jl:92 [inlined]
 in (::Base.REPL.##1#2{Base.REPL.REPLBackend})() at .\event.jl:46

The all keyword argument is actually only implemented for IOStream, not all subtypes of IO.

[samoconnor]

I think this is more than a doc issue.

The doc for read(s::IO, nb=typemax(Int)) says "Read at most nb bytes from s ...".

This is inconsistent with the default value of the all= option: read(s::IOStream, nb::Integer; all=true).

Currently, if I have x::IO and I want to read at most nb bytes, but not wait for more, I have to do this:

v = x isa IOStream ? read(x, 7; all=false) : read(x, 7)

Otherwise, the code will run nicely until the day someone passes in an IOStream, at which point it will hang forever.

Related: #24526

[samoconnor]

Should this be reopened?