Merge pull request JuliaLang#33113 from JuliaLang/sk/readdir

readdir: add `join` option to join `dir` with names

NEWS.md

@@ -24,6 +24,7 @@ New library functions
 * The `splitpath` function now accepts any `AbstractString` whereas previously it only accepted paths of type `String` ([#33012]).
 * The `tempname` function now takes an optional `parent::AbstractString` argument to give it a directory in which to attempt to produce a temporary path name ([#33090]).
 * The `tempname` function now takes a `cleanup::Bool` keyword argument defaulting to `true`, which causes the process to try to ensure that any file or directory at the path returned by `tempname` is deleted upon process exit ([#33090]).
+* The `readdir` function now takes a `join::Bool` keyword argument defaulting to `false`, which when set causes `readdir` to join its directory argument with each listed name ([#33113]).
 
 
 Standard library changes

base/file.jl

@@ -671,41 +671,87 @@ struct uv_dirent_t
 end
 
 """
- readdir(dir::AbstractString=".") -> Vector{String}
+ readdir(dir::AbstractString=pwd(); join::Bool=true) -> Vector{String}
 
-Return the files and directories in the directory `dir` (or the current working directory if not given).
+Return the names in the directory `dir` or the current working directory if not
+given. When `join` is false, `readdir` returns just the names in the directory
+as is; when `join` is true, it returns `joinpath(dir, name)` for each `name` so
+that the returned strings are full paths. If you want to get absolute paths
+back, call `readdir` with an absolute directory path and `join` set to true.
+
+!!! compat "Julia 1.4"
+ The `join` keyword argument requires at least Julia 1.4.
 
 # Examples
 ```julia-repl
-julia> readdir("/home/JuliaUser/Projects/julia")
-34-element Array{String,1}:
- ".circleci"
- ".freebsdci.sh"
+julia> cd("/home/JuliaUser/dev/julia")
+
+julia> readdir()
+30-element Array{String,1}:
+ ".appveyor.yml"
  ".git"
  ".gitattributes"
- ".github"
  ⋮
- "test"
  "ui"
  "usr"
  "usr-staging"
+
+julia> readdir(join=true)
+30-element Array{String,1}:
+ "/home/JuliaUser/dev/julia/.appveyor.yml"
+ "/home/JuliaUser/dev/julia/.git"
+ "/home/JuliaUser/dev/julia/.gitattributes"
+ ⋮
+ "/home/JuliaUser/dev/julia/ui"
+ "/home/JuliaUser/dev/julia/usr"
+ "/home/JuliaUser/dev/julia/usr-staging"
+
+julia> readdir("base")
+145-element Array{String,1}:
+ ".gitignore"
+ "Base.jl"
+ "Enums.jl"
+ ⋮
+ "version_git.sh"
+ "views.jl"
+ "weakkeydict.jl"
+
+julia> readdir("base", join=true)
+145-element Array{String,1}:
+ "base/.gitignore"
+ "base/Base.jl"
+ "base/Enums.jl"
+ ⋮
+ "base/version_git.sh"
+ "base/views.jl"
+ "base/weakkeydict.jl"```
+
+julia> readdir(abspath("base"), join=true)
+145-element Array{String,1}:
+ "/home/JuliaUser/dev/julia/base/.gitignore"
+ "/home/JuliaUser/dev/julia/base/Base.jl"
+ "/home/JuliaUser/dev/julia/base/Enums.jl"
+ ⋮
+ "/home/JuliaUser/dev/julia/base/version_git.sh"
+ "/home/JuliaUser/dev/julia/base/views.jl"
+ "/home/JuliaUser/dev/julia/base/weakkeydict.jl"
 ```
 """
-function readdir(path::AbstractString)
+function readdir(dir::AbstractString=pwd(); join::Bool=false)
  # Allocate space for uv_fs_t struct
  uv_readdir_req = zeros(UInt8, ccall(:jl_sizeof_uv_fs_t, Int32, ()))
 
  # defined in sys.c, to call uv_fs_readdir, which sets errno on error.
  err = ccall(:uv_fs_scandir, Int32, (Ptr{Cvoid}, Ptr{UInt8}, Cstring, Cint, Ptr{Cvoid}),
- C_NULL, uv_readdir_req, path, 0, C_NULL)
- err < 0 && throw(SystemError("unable to read directory $path", -err))
- #uv_error("unable to read directory $path", err)
+ C_NULL, uv_readdir_req, dir, 0, C_NULL)
+ err < 0 && throw(SystemError("unable to read directory $dir", -err))
 
  # iterate the listing into entries
  entries = String[]
  ent = Ref{uv_dirent_t}()
  while Base.UV_EOF != ccall(:uv_fs_scandir_next, Cint, (Ptr{Cvoid}, Ptr{uv_dirent_t}), uv_readdir_req, ent)
- push!(entries, unsafe_string(ent[].name))
+ name = unsafe_string(ent[].name)
+ push!(entries, join ? joinpath(dir, name) : name)
  end
 
  # Clean up the request string
@@ -714,8 +760,6 @@ function readdir(path::AbstractString)
  return entries
 end
 
-readdir() = readdir(".")
-
 """
  walkdir(dir; topdown=true, follow_symlinks=false, onerror=throw)
 

test/file.jl

@@ -1404,3 +1404,31 @@ end
  @test sizeof(basename(tmpdir)) == 6
  end
 end
+
+@testset "readir tests" begin
+ ≛(a, b) = sort(a) == sort(b)
+ mktempdir() do dir
+ d = cd(pwd, dir) # might resolve symlinks
+ @test isempty(readdir(d))
+ @test isempty(readdir(d, join=true))
+ cd(d) do
+ @test isempty(readdir())
+ @test isempty(readdir(join=true))
+ end
+ touch(joinpath(d, "file"))
+ mkdir(joinpath(d, "dir"))
+ names = ["dir", "file"]
+ paths = [joinpath(d, x) for x in names]
+ @test readdir(d) ≛ names
+ @test readdir(d, join=true) ≛ paths
+ cd(d) do
+ @test readdir() ≛ names
+ @test readdir(join=true) ≛ paths
+ end
+ t, b = splitdir(d)
+ cd(t) do
+ @test readdir(b) ≛ names
+ @test readdir(b, join=true) ≛ [joinpath(b, x) for x in names]
+ end
+ end
+end