Consistency of read() and write() functions. JuliaLang#14608

replace readall() with readstring()
replace readbytes() with read()

readbytes! returns nb whereas read! returns array, so they can't
trivially be merged.

Fix test/replutil.jl test that matches output of method error message
that has changed due to introduction of readbytes(::AbstractString).

add: +eachline(filename::AbstractString) = EachLine(open(stream), close)

revert mistaken docstring change -- read! vs readbytes!

update base/docs/helpdb/Base.jl

update rst docs, BBEditTextWrangler-julia.plist

replace missing chomp() in getmetabranch()

doc tweaks

make && make julia-genstdlib

more doc tweaks

whitespace tweak

doc: read!(stream or filename, ...)

base/LineEdit.jl

@@ -990,7 +990,7 @@ function write_response_buffer(s::PromptState, data)
     offset = s.input_buffer.ptr
     ptr = data.response_buffer.ptr
     seek(data.response_buffer, 0)
-    write(s.input_buffer, readall(data.response_buffer))
+    write(s.input_buffer, readstring(data.response_buffer))
     s.input_buffer.ptr = offset + ptr - 2
     data.response_buffer.ptr = ptr
     refresh_line(s)
@@ -1129,7 +1129,7 @@ function refresh_multi_line(termbuf::TerminalBuffer, s::SearchState)
     offset = buf.ptr
     ptr = s.response_buffer.ptr
     seek(s.response_buffer, 0)
-    write(buf, readall(s.response_buffer))
+    write(buf, readstring(s.response_buffer))
     buf.ptr = offset + ptr - 1
     s.response_buffer.ptr = ptr
     s.ias = refresh_multi_line(termbuf, s.terminal, buf, s.ias, s.backward ? "(reverse-i-search)`" : "(forward-i-search)`")

base/base64.jl

@@ -200,7 +200,7 @@ close(b::Base64DecodePipe) = nothing
 function base64decode(s)
     b = IOBuffer(s)
     try
-        return readbytes(Base64DecodePipe(b))
+        return read(Base64DecodePipe(b))
     finally
         close(b)
     end

base/client.jl

@@ -263,7 +263,7 @@ end
 
 function load_machine_file(path::AbstractString)
     machines = []
-    for line in split(readall(path),'\n'; keep=false)
+    for line in split(readstring(path),'\n'; keep=false)
         s = map!(strip, split(line,'*'; keep=false))
         if length(s) > 1
             cnt = isnumber(s[1]) ? parse(Int,s[1]) : symbol(s[1])
@@ -331,7 +331,7 @@ function _start()
                 # note: currently IOStream is used for file STDIN
                 if isa(STDIN,File) || isa(STDIN,IOStream)
                     # reading from a file, behave like include
-                    eval(Main,parse_input_line(readall(STDIN)))
+                    eval(Main,parse_input_line(readstring(STDIN)))
                 else
                     # otherwise behave repl-like
                     while !eof(STDIN)

base/datafmt.jl

@@ -46,11 +46,11 @@ function readdlm_auto(input, dlm::Char, T::Type, eol::Char, auto::Bool; opts...)
         if use_mmap && fsz > 0 && fsz < typemax(Int)
             input = as_mmap(input, fsz)
         else
-            input = readall(input)
+            input = readstring(input)
         end
     end
     sinp = isa(input, Vector{UInt8}) ? bytestring(input) :
-           isa(input, IO) ? readall(input) :
+           isa(input, IO) ? readstring(input) :
            input
     readdlm_string(sinp, dlm, T, eol, auto, optsd)
 end

base/deprecated.jl

@@ -961,4 +961,9 @@ macro boundscheck(yesno,blk)
     end
 end
 
+
 @deprecate parseip(str::AbstractString) parse(IPAddr, str)
+
+#https://github.com/JuliaLang/julia/issues/14608
+@deprecate readall readstring
+@deprecate readbytes read

base/docs/helpdb/Base.jl

@@ -48,9 +48,9 @@ the same object. `fill!(A, Foo())` will return `A` filled with the result of eva
 fill!
 
 """
-    read!(stream, array::Array)
+    read!(stream or filename, array::Array)
 
-Read binary data from a stream, filling in the argument `array`.
+Read binary data from a stream or file, filling in the argument `array`.
 """
 read!
 
@@ -452,7 +452,7 @@ the mantissa.
 precision
 
 """
-    readlines(stream)
+    readlines(stream or filename)
 
 Read all lines as an array.
 """
@@ -1018,7 +1018,7 @@ See `rounding` for available rounding modes.
 Float32
 
 """
-    readuntil(stream, delim)
+    readuntil(stream or filename, delim)
 
 Read a string, up to and including the given delimiter byte.
 """
@@ -2054,7 +2054,7 @@ open(file_name, mode="r")
 Apply the function `f` to the result of `open(args...)` and close the resulting file
 descriptor upon completion.
 
-**Example**: `open(readall, "file.txt")`
+**Example**: `open(readstring, "file.txt")`
 """
 open(f::Function, args...)
 
@@ -2438,19 +2438,11 @@ the process.
 triu!(M, k)
 
 """
-    readall(stream::IO)
+    readstring(stream or filename)
 
-Read the entire contents of an I/O stream as a string.
+Read the entire contents of an I/O stream or a file as a string.
 """
-readall(stream::IO)
-
-"""
-    readall(filename::AbstractString)
-
-Open `filename`, read the entire contents as a string, then close the file. Equivalent to
-`open(readall, filename)`.
-"""
-readall(filename::AbstractString)
+readstring
 
 """
     poll_file(path, interval_s::Real, timeout_s::Real) -> (previous::StatStruct, current::StatStruct)
@@ -2468,9 +2460,9 @@ it is more reliable and efficient, although in some situations it may not be ava
 poll_file
 
 """
-    eachline(stream)
+    eachline(stream or filename)
 
-Create an iterable object that will yield each line from a stream.
+Create an iterable object that will yield each line.
 """
 eachline
 
@@ -4244,9 +4236,9 @@ Squared absolute value of `x`.
 abs2
 
 """
-    write(stream, x)
+    write(stream or filename, x)
 
-Write the canonical binary representation of a value to the given stream. Returns the number
+Write the canonical binary representation of a value to the given stream or file. Returns the number
 of bytes written into the stream.
 
 You can write multiple values with the same :func:`write` call. i.e. the following are
@@ -6391,7 +6383,7 @@ besselk
 """
     readchomp(x)
 
-Read the entirety of `x` as a string but remove trailing newlines. Equivalent to `chomp(readall(x))`.
+Read the entirety of `x` as a string but remove trailing newlines. Equivalent to `chomp(readstring(x))`.
 """
 readchomp
 
@@ -6436,7 +6428,7 @@ asecd
 Read at most `nb` bytes from the stream into `b`, returning the number of bytes read
 (increasing the size of `b` as needed).
 
-See `readbytes` for a description of the `all` option.
+See `read` for a description of the `all` option.
 """
 readbytes!
 
@@ -7416,10 +7408,10 @@ Return the supertype of DataType `T`.
 supertype
 
 """
-    readline(stream=STDIN)
+    readline(stream=STDIN or filename)
 
 Read a single line of text, including a trailing newline character (if one is reached before
-the end of the input), from the given `stream` (defaults to `STDIN`),
+the end of the input), from the given stream or file (defaults to `STDIN`),
 """
 readline
 
@@ -10253,7 +10245,7 @@ a series of integer arguments.
 cell
 
 """
-    readbytes(stream, nb=typemax(Int); all=true)
+    read(stream, nb=typemax(Int); all=true)
 
 Read at most `nb` bytes from the stream, returning a `Vector{UInt8}` of the bytes read.
 
@@ -10262,7 +10254,7 @@ requested bytes, until an error or end-of-file occurs. If `all` is `false`, at m
 `read` call is performed, and the amount of data returned is device-dependent. Note that not
 all stream types support the `all` option.
 """
-readbytes
+read
 
 """
     eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V

base/exports.jl

@@ -1165,10 +1165,9 @@ export
     RawFD,
     read,
     read!,
-    readall,
+    readstring,
     readavailable,
     readbytes!,
-    readbytes,
     readchomp,
     readcsv,
     readdir,

base/filesystem.jl

@@ -39,7 +39,7 @@ export File,
        S_IROTH, S_IWOTH, S_IXOTH, S_IRWXO
 
 import Base: uvtype, uvhandle, eventloop, fd, position, stat, close,
-            write, read, read!, readbytes, isopen, show,
+            write, read, read!, isopen, show,
             check_open, _sizeof_uv_fs, uv_error, UVError
 
 include("path.jl")
@@ -172,14 +172,8 @@ function readbytes!(f::File, b::Array{UInt8}, nb=length(b))
     read!(f, b, nr)
     return nr
 end
-readbytes(io::File) = read!(io, Array(UInt8, nb_available(io)))
-readbytes(io::File, nb) = read!(io, Array(UInt8, min(nb, nb_available(io))))
-
-function readbytes(f::File)
-    a = Array(UInt8, nb_available(f))
-    read!(f,a)
-    return a
-end
+read(io::File) = read!(io, Array(UInt8, nb_available(io)))
+read(io::File, nb::Integer) = read!(io, Array(UInt8, min(nb, nb_available(io))))
 
 const SEEK_SET = Int32(0)
 const SEEK_CUR = Int32(1)

base/interactiveutil.jl

@@ -93,7 +93,7 @@ less(file, line::Integer) = error("could not find source file for function")
             print(io, x)
         end
     end
-    clipboard() = readall(`pbpaste`)
+    clipboard() = readstring(`pbpaste`)
 end
 
 @linux_only begin
@@ -120,7 +120,7 @@ end
         cmd = c == :xsel  ? `xsel --nodetach --output --clipboard` :
               c == :xclip ? `xclip -quiet -out -selection clipboard` :
             error("unexpected clipboard command: $c")
-        readall(pipeline(cmd, stderr=STDERR))
+        readstring(pipeline(cmd, stderr=STDERR))
     end
 end
 
@@ -181,7 +181,7 @@ function versioninfo(io::IO=STDOUT, verbose::Bool=false)
     if verbose
         lsb = ""
         @linux_only try lsb = readchomp(pipeline(`lsb_release -ds`, stderr=DevNull)) end
-        @windows_only try lsb = strip(readall(`$(ENV["COMSPEC"]) /c ver`)) end
+        @windows_only try lsb = strip(readstring(`$(ENV["COMSPEC"]) /c ver`)) end
         if lsb != ""
             println(io,     "           ", lsb)
         end
@@ -416,7 +416,7 @@ function runtests(tests = ["all"], numcores = ceil(Int,CPU_CORES/2))
         buf = PipeBuffer()
         versioninfo(buf)
         error("A test has failed. Please submit a bug report (https://github.com/JuliaLang/julia/issues)\n" *
-              "including error messages above and the output of versioninfo():\n$(readall(buf))")
+              "including error messages above and the output of versioninfo():\n$(readstring(buf))")
     end
 end
 

base/io.jl

@@ -45,7 +45,7 @@ read!(io::AbstractPipe, bytes::Vector{UInt8}) = read!(pipe_reader(io), bytes)
 read{T<:AbstractPipe}(io::T, args...) = read(pipe_reader(io), args...)
 read!{T<:AbstractPipe}(io::T, args...) = read!(pipe_reader(io), args...)
 readuntil{T<:AbstractPipe}(io::T, args...) = readuntil(pipe_reader(io), args...)
-readbytes(io::AbstractPipe) = readbytes(pipe_reader(io))
+read(io::AbstractPipe) = read(pipe_reader(io))
 readavailable(io::AbstractPipe) = readavailable(pipe_reader(io))
 
 isreadable(io::AbstractPipe) = isreadable(pipe_reader(io))
@@ -60,6 +60,18 @@ eof(io::AbstractPipe) = eof(pipe_reader(io))
 reseteof(io::AbstractPipe) = reseteof(pipe_reader(io))
 
 
+# Exception-safe wrappes. (io = open(); try f(io) finally close(io))
+
+write(filename::AbstractString, args...) = open(io->write(io, args...), filename, "w")
+
+read(filename::AbstractString, args...) = open(io->read(io, args...), filename)
+read!(filename::AbstractString, a) = open(io->read!(io, a), filename)
+readstring(filename::AbstractString) = open(readstring, filename)
+readuntil(filename::AbstractString, args...) = open(io->readuntil(io, args...), filename)
+readline(filename::AbstractString) = open(readline, filename)
+readlines(filename::AbstractString) = open(readlines, filename)
+
+
 ## byte-order mark, ntoh & hton ##
 
 const ENDIAN_BOM = reinterpret(UInt32,UInt8[1:4;])[1]
@@ -160,6 +172,13 @@ function write(io::IO, s::Symbol)
     return write(io, pname, Int(ccall(:strlen, Csize_t, (Cstring,), pname)))
 end
 
+function write(to::IO, from::IO)
+    while !eof(from)
+        write(to, readavailable(from))
+    end
+end
+
+
 read(s::IO, ::Type{Int8}) = reinterpret(Int8, read(s,UInt8))
 
 function read{T <: Union{Int16,UInt16,Int32,UInt32,Int64,UInt64,Int128,UInt128}}(s::IO, ::Type{T})
@@ -285,7 +304,7 @@ end
 
 readline() = readline(STDIN)
 readline(s::IO) = readuntil(s, '\n')
-readchomp(x) = chomp!(readall(x))
+readchomp(x) = chomp!(readstring(x))
 
 # read up to nb bytes into nb, returning # bytes read
 function readbytes!(s::IO, b::AbstractArray{UInt8}, nb=length(b))
@@ -307,19 +326,18 @@ function readbytes!(s::IO, b::AbstractArray{UInt8}, nb=length(b))
 end
 
 # read up to nb bytes from s, returning a Vector{UInt8} of bytes read.
-function readbytes(s::IO, nb=typemax(Int))
+function read(s::IO, nb=typemax(Int))
     # Let readbytes! grow the array progressively by default
     # instead of taking of risk of over-allocating
     b = Array(UInt8, nb == typemax(Int) ? 1024 : nb)
     nr = readbytes!(s, b, nb)
     resize!(b, nr)
 end
 
-function readall(s::IO)
-    b = readbytes(s)
+function readstring(s::IO)
+    b = read(s)
     return isvalid(ASCIIString, b) ? ASCIIString(b) : UTF8String(b)
 end
-readall(filename::AbstractString) = open(readall, filename)
 
 ## high-level iterator interfaces ##
 
@@ -330,6 +348,7 @@ type EachLine
     EachLine(stream, ondone) = new(stream, ondone)
 end
 eachline(stream::IO) = EachLine(stream)
+eachline(filename::AbstractString) = EachLine(open(filename), close)
 
 start(itr::EachLine) = nothing
 function done(itr::EachLine, nada)

base/iobuffer.jl

@@ -336,8 +336,8 @@ function readbytes!(io::AbstractIOBuffer, b::Array{UInt8}, nb=length(b))
     read_sub(io, b, 1, nr)
     return nr
 end
-readbytes(io::AbstractIOBuffer) = read!(io, Array(UInt8, nb_available(io)))
-readbytes(io::AbstractIOBuffer, nb) = read!(io, Array(UInt8, min(nb, nb_available(io))))
+read(io::AbstractIOBuffer) = read!(io, Array(UInt8, nb_available(io)))
+read(io::AbstractIOBuffer, nb::Integer) = read!(io, Array(UInt8, min(nb, nb_available(io))))
 
 function search(buf::IOBuffer, delim::UInt8)
     p = pointer(buf.data, buf.ptr)

base/iostream.jl

@@ -241,7 +241,7 @@ function readbytes!(s::IOStream, b::Array{UInt8}, nb=length(b); all::Bool=true)
     return all ? readbytes_all!(s, b, nb) : readbytes_some!(s, b, nb)
 end
 
-function readbytes(s::IOStream)
+function read(s::IOStream)
     sz = 0
     try # filesize is just a hint, so ignore if it fails
         sz = filesize(s)
@@ -255,7 +255,7 @@ function readbytes(s::IOStream)
     resize!(b, nr)
 end
 
-function readbytes(s::IOStream, nb::Integer; all::Bool=true)
+function read(s::IOStream, nb::Integer; all::Bool=true)
     b = Array(UInt8, nb)
     nr = readbytes!(s, b, nb, all=all)
     resize!(b, nr)