add keyword arguments to IOBuffer's constructors

JuliaLang · JeffBezanson · Feb 6, 2018 · Feb 4, 2018 · Feb 4, 2018 · Feb 4, 2018
commit 3906356d7d591237b2a4490fc2d2cf8469b4271a
diff --git a/base/iobuffer.jl b/base/iobuffer.jl
@@ -32,15 +32,27 @@ StringVector(n::Integer) = unsafe_wrap(Vector{UInt8}, _string_n(n))
 # IOBuffers behave like Files. They are typically readable and writable. They are seekable. (They can be appendable).
 
 """
-    IOBuffer([data, ][readable::Bool=true, writable::Bool=false[, maxsize::Int=typemax(Int)]])
+    IOBuffer([data::AbstractVector{UInt8}]; keywords...) -> IOBuffer
 
-Create an `IOBuffer`, which may optionally operate on a pre-existing array. If the
-readable/writable arguments are given, they restrict whether or not the buffer may be read
-from or written to respectively. The last argument optionally specifies a size beyond which
-the buffer may not be grown.
+Create an in-memory I/O stream, which may optionally operate on a pre-existing array.
+
+It may take optional keyword arguments:
+- `read`, `write`, `append`: restricts operations to the buffer; see `open` for details.
+- `truncate`: truncates the buffer size to zero length.
+- `maxsize`: specifies a size beyond which the buffer may not be grown.
+
+When `data` is given, the buffer will be both readable and writable by default.
 
 # Examples
 ```jldoctest
+julia> io = IOBuffer();
+
+julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.")
+56
+
+julia> String(take!(io))
+"JuliaLang is a GitHub organization. It has many members."
+
 julia> io = IOBuffer("JuliaLang is a GitHub organization.")
 IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=35, maxsize=Inf, ptr=1, mark=-1)
 
@@ -50,7 +62,7 @@ julia> read(io, String)
 julia> write(io, "This isn't writable.")
 ERROR: ArgumentError: ensureroom failed, IOBuffer is not writeable
 
-julia> io = IOBuffer(UInt8[], true, true, 34)
+julia> io = IOBuffer(UInt8[], read=true, write=true, maxsize=34)
 IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=34, ptr=1, mark=-1)
 
 julia> write(io, "JuliaLang is a GitHub organization.")
@@ -60,33 +72,49 @@ julia> String(take!(io))
 "JuliaLang is a GitHub organization"
 ```
 """
-IOBuffer(data::AbstractVector{UInt8}, readable::Bool=true, writable::Bool=false, maxsize::Integer=typemax(Int)) =
-    GenericIOBuffer(data, readable, writable, true, false, maxsize)
-function IOBuffer(readable::Bool, writable::Bool)
-    b = IOBuffer(StringVector(32), readable, writable)
-    b.data[:] = 0
-    b.size = 0
-    return b
+function IOBuffer(
+        data::AbstractVector{UInt8};
+        read::Union{Bool,Nothing}=nothing,
+        write::Union{Bool,Nothing}=nothing,
+        append::Union{Bool,Nothing}=nothing,
+        truncate::Union{Bool,Nothing}=nothing,
+        maxsize::Integer=typemax(Int))
+    if maxsize < 0
+        throw(ArgumentError("negative maxsize: $(maxsize)"))
+    end
+    flags = open_flags(read=read, write=write, append=append, truncate=truncate)
+    buf = GenericIOBuffer(data, flags.read, flags.write, true, flags.append, Int(maxsize))
+    if flags.truncate
+        buf.size = 0
+    end
+    return buf
 end
 
-"""
-    IOBuffer() -> IOBuffer
-
-Create an in-memory I/O stream, which is both readable and writable.
-
-# Examples
-```jldoctest
-julia> io = IOBuffer();
-
-julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.")
-56
-
-julia> String(take!(io))
-"JuliaLang is a GitHub organization. It has many members."
-```
-"""
-IOBuffer() = IOBuffer(true, true)
+function IOBuffer(;
+        read::Union{Bool,Nothing}=true,
+        write::Union{Bool,Nothing}=true,
+        append::Union{Bool,Nothing}=nothing,
+        truncate::Union{Bool,Nothing}=true,
+        maxsize::Integer=typemax(Int))
+    size = maxsize == typemax(Int) ? 32 : Int(maxsize)
+    flags = open_flags(read=read, write=write, append=append, truncate=truncate)
+    buf = IOBuffer(
+        StringVector(size),
+        read=flags.read,
+        write=flags.write,
+        append=flags.append,
+        truncate=flags.truncate,
+        maxsize=maxsize)
+    buf.data[:] = 0  # TODO: Is this really needed?
+    if flags.truncate
+        buf.size = 0
+    end
+    return buf
+end
 
+# TODO: deprecate these methods?
+IOBuffer(data::AbstractVector{UInt8}, read::Bool, write::Bool, maxsize::Integer=typemax(Int)) = IOBuffer(data, read=read, write=write, maxsize=maxsize)
+IOBuffer(read::Bool, write::Bool) = IOBuffer(read=read, write=write)
 """
     IOBuffer(size::Integer)
 
@@ -110,7 +138,7 @@ julia> String(take!(io))
 "Hello world "
 ```
 """
-IOBuffer(maxsize::Integer) = (x=IOBuffer(StringVector(maxsize), true, true, maxsize); x.size=0; x)
+IOBuffer(maxsize::Integer) = IOBuffer(maxsize=maxsize)
 
 # PipeBuffers behave like Unix Pipes. They are typically readable and writable, they act appendable, and are not seekable.