open: deprecate positional flags for keywords (#25696)

Author: StefanKarpinski

base/deprecated.jl

@@ -1512,6 +1512,15 @@ end
 
 @deprecate lexless isless
 
+@deprecate(
+    open(filename::AbstractString, read::Bool, write::Bool, create::Bool, truncate::Bool, append::Bool),
+    open(filename, read = read, write = write, create = create, truncate = truncate, append = append)
+)
+@deprecate(
+    open(f::Function, filename::AbstractString, read::Bool, write::Bool, create::Bool, truncate::Bool, append::Bool),
+    open(f, filename, read = read, write = write, create = create, truncate = truncate, append = append)
+)
+
 @deprecate_binding iteratorsize IteratorSize
 @deprecate_binding iteratoreltype IteratorEltype
 

base/iostream.jl

@@ -211,25 +211,84 @@ function fdio(name::AbstractString, fd::Integer, own::Bool=false)
 end
 fdio(fd::Integer, own::Bool=false) = fdio(string("<fd ",fd,">"), fd, own)
 
+"""
+    open_flags(; keywords...) -> NamedTuple
+
+Compute the `read`, `write`, `create`, `truncate`, `append` flag value for
+a given set of keyword arguments to `open` a `NamedTuple`.
+"""
+function open_flags(;
+    read     :: Union{Bool,Nothing} = nothing,
+    write    :: Union{Bool,Nothing} = nothing,
+    create   :: Union{Bool,Nothing} = nothing,
+    truncate :: Union{Bool,Nothing} = nothing,
+    append   :: Union{Bool,Nothing} = nothing,
+)
+    if write === true && read !== true && append !== true
+        create   === nothing && (create   = true)
+        truncate === nothing && (truncate = true)
+    end
+
+    if truncate === true || append === true
+        write  === nothing && (write  = true)
+        create === nothing && (create = true)
+    end
+
+    write    === nothing && (write    = false)
+    read     === nothing && (read     = !write)
+    create   === nothing && (create   = false)
+    truncate === nothing && (truncate = false)
+    append   === nothing && (append   = false)
+
+    return (
+        read = read,
+        write = write,
+        create = create,
+        truncate = truncate,
+        append = append,
+    )
+end
 
 """
-    open(filename::AbstractString, [read::Bool, write::Bool, create::Bool, truncate::Bool, append::Bool]) -> IOStream
+    open(filename::AbstractString; keywords...) -> IOStream
+
+Open a file in a mode specified by five boolean keyword arguments:
+
+| Keyword    | Desciption             | Default                                 |
+|:-----------|:-----------------------|:----------------------------------------|
+| `read`     | open for reading       | `!write`                                |
+| `write`    | open for writing       | `truncate \\| append`                   |
+| `create`   | create if non-existent | `!read & write \\| truncate \\| append` |
+| `truncate` | truncate to zero size  | `!read & write`                         |
+| `append`   | seek to end            | `false`                                 |
 
-Open a file in a mode specified by five boolean arguments. The default is to open files for
-reading only. Return a stream for accessing the file.
+The default when no keywords are passed is to open files for reading only.
+Returns a stream for accessing the opened file.
 """
-function open(fname::AbstractString, rd::Bool, wr::Bool, cr::Bool, tr::Bool, ff::Bool)
+function open(fname::AbstractString;
+    read     :: Union{Bool,Nothing} = nothing,
+    write    :: Union{Bool,Nothing} = nothing,
+    create   :: Union{Bool,Nothing} = nothing,
+    truncate :: Union{Bool,Nothing} = nothing,
+    append   :: Union{Bool,Nothing} = nothing,
+)
+    flags = open_flags(
+        read = read,
+        write = write,
+        create = create,
+        truncate = truncate,
+        append = append,
+    )
     s = IOStream(string("<file ",fname,">"))
     systemerror("opening file $fname",
                 ccall(:ios_file, Ptr{Cvoid},
                       (Ptr{UInt8}, Cstring, Cint, Cint, Cint, Cint),
-                      s.ios, fname, rd, wr, cr, tr) == C_NULL)
-    if ff
+                      s.ios, fname, flags.read, flags.write, flags.create, flags.truncate) == C_NULL)
+    if flags.append
         systemerror("seeking to end of file $fname", ccall(:ios_seek_end, Int64, (Ptr{Cvoid},), s.ios) != 0)
     end
     return s
 end
-open(fname::AbstractString) = open(fname, true, false, false, false, false)
 
 """
     open(filename::AbstractString, [mode::AbstractString]) -> IOStream
@@ -238,14 +297,14 @@ Alternate syntax for open, where a string-based mode specifier is used instead o
 booleans. The values of `mode` correspond to those from `fopen(3)` or Perl `open`, and are
 equivalent to setting the following boolean groups:
 
-| Mode | Description                   |
-|:-----|:------------------------------|
-| r    | read                          |
-| r+   | read, write                   |
-| w    | write, create, truncate       |
-| w+   | read, write, create, truncate |
-| a    | write, create, append         |
-| a+   | read, write, create, append   |
+| Mode | Description                   | Keywords                            |
+|:-----|:------------------------------|:------------------------------------|
+| `r`  | read                          | none                                |
+| `w`  | write, create, truncate       | `write = true`                      |
+| `a`  | write, create, append         | `append = true`                     |
+| `r+` | read, write                   | `read = true, write = true`         |
+| `w+` | read, write, create, truncate | `truncate = true, read = true`      |
+| `a+` | read, write, create, append   | `append = true, read = true`        |
 
 # Examples
 ```jldoctest
@@ -277,19 +336,19 @@ julia> rm("myfile.txt")
 ```
 """
 function open(fname::AbstractString, mode::AbstractString)
-    mode == "r"  ? open(fname, true , false, false, false, false) :
-    mode == "r+" ? open(fname, true , true , false, false, false) :
-    mode == "w"  ? open(fname, false, true , true , true , false) :
-    mode == "w+" ? open(fname, true , true , true , true , false) :
-    mode == "a"  ? open(fname, false, true , true , false, true ) :
-    mode == "a+" ? open(fname, true , true , true , false, true ) :
+    mode == "r"  ? open(fname, read = true)                  :
+    mode == "r+" ? open(fname, read = true, write = true)    :
+    mode == "w"  ? open(fname, truncate = true)              :
+    mode == "w+" ? open(fname, truncate = true, read = true) :
+    mode == "a"  ? open(fname, append = true)                :
+    mode == "a+" ? open(fname, append = true, read = true)   :
     throw(ArgumentError("invalid open mode: $mode"))
 end
 
 """
-    open(f::Function, args...)
+    open(f::Function, args...; kwargs....)
 
-Apply the function `f` to the result of `open(args...)` and close the resulting file
+Apply the function `f` to the result of `open(args...; kwargs...)` and close the resulting file
 descriptor upon completion.
 
 # Examples
@@ -304,8 +363,8 @@ julia> open(f->read(f, String), "myfile.txt")
 julia> rm("myfile.txt")
 ```
 """
-function open(f::Function, args...)
-    io = open(args...)
+function open(f::Function, args...; kwargs...)
+    io = open(args...; kwargs...)
     try
         f(io)
     finally

stdlib/REPL/src/REPL.jl

@@ -831,7 +831,7 @@ function setup_interface(
     if repl.history_file
         try
             hist_path = find_hist_file()
-            f = open(hist_path, true, true, true, false, false)
+            f = open(hist_path, read=true, write=true, create=true)
             finalizer(replc) do replc
                 close(f)
             end