Make file operations return the path they created

NEWS.md

@@ -469,6 +469,9 @@ This section lists changes that do not have deprecation warnings.
   * `widen` on 8- and 16-bit integer types now widens to the platform word size (`Int`)
     instead of to a 32-bit type ([#26859]).
 
+  * `mv`,`cp`, `touch`, `mkdir`, `mkpath` now return the path that was created/modified
+    rather than `nothing` ([#27071]).
+
 Library improvements
 --------------------
 

base/file.jl

@@ -98,6 +98,7 @@ modified by the current file creation mask. This function never creates more tha
 directory. If the directory already exists, or some intermediate directories do not exist,
 this function throws an error. See [`mkpath`](@ref) for a function which creates all
 required intermediate directories.
+Return `path`.
 """
 function mkdir(path::AbstractString; mode::Integer = 0o777)
     @static if Sys.iswindows()
@@ -106,13 +107,15 @@ function mkdir(path::AbstractString; mode::Integer = 0o777)
         ret = ccall(:mkdir, Int32, (Cstring, UInt32), path, checkmode(mode))
     end
     systemerror(:mkdir, ret != 0; extrainfo=path)
+    path
 end
 
 """
     mkpath(path::AbstractString; mode::Unsigned = 0o777)
 
 Create all directories in the given `path`, with permissions `mode`. `mode` defaults to
 `0o777`, modified by the current file creation mask.
+Return `path`.
 """
 function mkpath(path::AbstractString; mode::Integer = 0o777)
     isdirpath(path) && (path = dirname(path))
@@ -124,12 +127,11 @@ function mkpath(path::AbstractString; mode::Integer = 0o777)
     # If there is a problem with making the directory, but the directory
     # does in fact exist, then ignore the error. Else re-throw it.
     catch err
-        if isa(err, SystemError) && isdir(path)
-            return
-        else
+        if !isa(err, SystemError) || !isdir(path)
             rethrow()
         end
     end
+    path
 end
 
 """
@@ -228,6 +230,7 @@ Copy the file, link, or directory from `src` to `dest`.
 If `follow_symlinks=false`, and `src` is a symbolic link, `dst` will be created as a
 symbolic link. If `follow_symlinks=true` and `src` is a symbolic link, `dst` will be a copy
 of the file or directory `src` refers to.
+Return `dst`.
 """
 function cp(src::AbstractString, dst::AbstractString; force::Bool=false,
                                                       follow_symlinks::Bool=false,
@@ -246,13 +249,15 @@ function cp(src::AbstractString, dst::AbstractString; force::Bool=false,
     else
         sendfile(src, dst)
     end
+    dst
 end
 
 """
     mv(src::AbstractString, dst::AbstractString; force::Bool=false)
 
 Move the file, link, or directory from `src` to `dst`.
 `force=true` will first remove an existing `dst`.
+Return `dst`.
 """
 function mv(src::AbstractString, dst::AbstractString; force::Bool=false,
                                                       remove_destination::Union{Bool,Nothing}=nothing)
@@ -264,12 +269,14 @@ function mv(src::AbstractString, dst::AbstractString; force::Bool=false,
     end
     checkfor_mv_cp_cptree(src, dst, "moving"; force=force)
     rename(src, dst)
+    dst
 end
 
 """
     touch(path::AbstractString)
 
 Update the last-modified timestamp on a file to the current time.
+Return `path`.
 """
 function touch(path::AbstractString)
     f = open(path, JL_O_WRONLY | JL_O_CREAT, 0o0666)
@@ -279,6 +286,7 @@ function touch(path::AbstractString)
     finally
         close(f)
     end
+    path
 end
 
 if Sys.iswindows()
@@ -650,6 +658,7 @@ end
 Change the permissions mode of `path` to `mode`. Only integer `mode`s (e.g. `0o777`) are
 currently supported. If `recursive=true` and the path is a directory all permissions in
 that directory will be recursively changed.
+Return `path`.
 """
 function chmod(path::AbstractString, mode::Integer; recursive::Bool=false)
     err = ccall(:jl_fs_chmod, Int32, (Cstring, Cint), path, mode)
@@ -661,17 +670,18 @@ function chmod(path::AbstractString, mode::Integer; recursive::Bool=false)
             end
         end
     end
-    nothing
+    path
 end
 
 """
     chown(path::AbstractString, owner::Integer, group::Integer=-1)
 
 Change the owner and/or group of `path` to `owner` and/or `group`. If the value entered for `owner` or `group`
 is `-1` the corresponding ID will not change. Only integer `owner`s and `group`s are currently supported.
+Return `path`
 """
 function chown(path::AbstractString, owner::Integer, group::Integer=-1)
     err = ccall(:jl_fs_chown, Int32, (Cstring, Cint, Cint), path, owner, group)
     uv_error("chown",err)
-    nothing
+    path
 end

test/file.jl

@@ -62,7 +62,7 @@ end
 
 @test filemode(file) & 0o444 > 0 # readable
 @test filemode(file) & 0o222 > 0 # writable
-chmod(file, filemode(file) & 0o7555)
+@test chmod(file, filemode(file) & 0o7555) == file
 @test filemode(file) & 0o222 == 0
 chmod(file, filemode(file) | 0o222)
 @test filemode(file) & 0o111 == 0
@@ -171,7 +171,7 @@ if !Sys.iswindows()
         chown(file, 0, -2)  # Change the file group to nogroup (and owner back to root)
         @test stat(file).gid !=0
         @test stat(file).uid ==0
-        chown(file, -1, 0)
+        @test chown(file, -1, 0) == file
         @test stat(file).gid ==0
         @test stat(file).uid ==0
     else
@@ -180,7 +180,7 @@ if !Sys.iswindows()
     end
 else
     # test that chown doesn't cause any errors for Windows
-    @test chown(file, -2, -2) === nothing
+    @test chown(file, -2, -2) == file
 end
 
 ##############
@@ -978,6 +978,26 @@ rm(dir)
 @test !ispath(file)
 @test !ispath(dir)
 
+
+
+##################
+# Return values of mkpath, mkdir, cp, mv and touch
+####################
+mktempdir() do dir
+    name1 = joinpath(dir, "apples")
+    name2 = joinpath(dir, "bannanas")
+    @test touch(name1)==name1
+    @test mv(name1, name2) == name2
+    @test cp(name2, name1) == name1
+    namedir = joinpath(dir, "chalk")
+    namepath = joinpath(dir, "chalk","cheese","fresh")
+    @test mkdir(namedir) == namedir
+    @test mkpath(namepath) == namepath
+end
+
+
+
+
 # issue #9687
 let n = tempname()
     w = open(n, "a")