feat(fs): add cp helper

Author: haithium

spec/fs_spec.lua

@@ -9,14 +9,16 @@ local path = mods.path
 local isdir = mods.is.dir
 local make_tmp_dir = helpers.make_tmp_dir
 local tmpname = helpers.tmpname
-local join = mods.path.join
+local join = path.join
+local dirname = path.dirname
+
 local fmt = string.format
 
 describe("mods.fs", function()
   local is_unix = not mods.runtime.is_windows
   local cwd = path.cwd() --[[@as string]]
-  local readme_file = path.join(cwd, "README.md")
-  local spec_file = path.join(cwd, "spec", "fs_spec.lua")
+  local readme_file = join(cwd, "README.md")
+  local spec_file = join(cwd, "spec", "fs_spec.lua")
 
   for _, fname in ipairs({ "getsize", "getatime", "getmtime", "getctime" }) do
     it(fmt("%s() returns a number for an existing path", fname), function()
@@ -285,6 +287,181 @@ describe("mods.fs", function()
     end)
   end)
 
+  describe("cp()", function()
+    it("copies binary files", function()
+      local root = make_tmp_dir()
+      local src = join(root, "src.bin")
+      local dst = join(root, "dst.bin")
+      local body = "a\0b\1c\255z"
+
+      assert.is_true(fs.write_bytes(src, body))
+      assert.is_true(fs.cp(src, dst))
+      assert.are_equal(body, fs.read_bytes(dst))
+
+      assert.is_true(fs.rm(root, true))
+    end)
+
+    it("copies files", function()
+      local root = make_tmp_dir()
+      local src = join(root, "src.txt")
+      local dst = join(root, "dst.txt")
+
+      assert.is_true(fs.write_text(src, "abc"))
+      assert.is_true(fs.cp(src, dst))
+      assert.are_equal("abc", fs.read_text(dst))
+
+      assert.is_true(fs.rm(root, true))
+    end)
+
+    it("overwrites an existing destination file", function()
+      local root = make_tmp_dir()
+      local src = join(root, "src.txt")
+      local dst = join(root, "dst.txt")
+
+      assert.is_true(fs.write_text(src, "new"))
+      assert.is_true(fs.write_text(dst, "old"))
+
+      assert.is_true(fs.cp(src, dst))
+      assert.are_equal("new", fs.read_text(dst))
+
+      assert.is_true(fs.rm(root, true))
+    end)
+
+    it("copies empty directories", function()
+      local root = make_tmp_dir()
+      local src = join(root, "src")
+      local empty = join(src, "empty")
+      local dst = join(root, "copy")
+
+      assert.is_true(fs.mkdir(empty, true))
+
+      assert.is_true(fs.cp(src, dst))
+      assert.is_true(isdir(join(dst, "empty")))
+
+      assert.is_true(fs.rm(root, true))
+    end)
+
+    it("copies directories recursively", function()
+      local root = make_tmp_dir()
+      local src = join(root, "src")
+      local top_level = join(src, "top.txt")
+      local nested_dir = join(src, "deep")
+      local nested = join(nested_dir, "nested.txt")
+      local dst = join(root, "copy")
+
+      assert.is_true(fs.mkdir(nested_dir, true))
+      assert.is_true(fs.write_text(top_level, "abc"))
+      assert.is_true(fs.write_text(nested, "xyz"))
+
+      assert.is_true(fs.cp(src, dst))
+      assert.are_equal("abc", fs.read_text(join(dst, "top.txt")))
+      assert.is_true(fs.exists(join(dst, "deep")))
+      assert.are_equal("xyz", fs.read_text(join(dst, "deep", "nested.txt")))
+
+      assert.is_true(fs.rm(root, true))
+    end)
+
+    it("merges into an existing destination directory", function()
+      local root = make_tmp_dir()
+      local src = join(root, "src")
+      local nested_dir = join(src, "deep")
+      local src_file = join(src, "top.txt")
+      local nested = join(nested_dir, "nested.txt")
+      local dst = join(root, "copy")
+      local keep = join(dst, "keep.txt")
+
+      assert.is_true(fs.mkdir(nested_dir, true))
+      assert.is_true(fs.mkdir(dst, true))
+      assert.is_true(fs.write_text(src_file, "abc"))
+      assert.is_true(fs.write_text(nested, "xyz"))
+      assert.is_true(fs.write_text(keep, "keep"))
+
+      assert.is_true(fs.cp(src, dst))
+      assert.are_equal("keep", fs.read_text(keep))
+      assert.are_equal("abc", fs.read_text(join(dst, "top.txt")))
+      assert.are_equal("xyz", fs.read_text(join(dst, "deep", "nested.txt")))
+
+      assert.is_true(fs.rm(root, true))
+    end)
+
+    it("fails when the source is missing", function()
+      local root = make_tmp_dir()
+      local missing = join(root, "missing.txt")
+      local dst = join(root, "dst.txt")
+
+      local ok, errmsg, errcode = fs.cp(missing, dst)
+      assert.are_same({ "nil", "string", "number" }, { type(ok), type(errmsg), type(errcode) })
+
+      assert.is_true(fs.rm(root, true))
+    end)
+
+    it("fails when the destination parent is missing", function()
+      local root = make_tmp_dir()
+      local src = join(root, "src.txt")
+      local dst = join(root, "missing", "dst.txt")
+
+      assert.is_true(fs.write_text(src, "abc"))
+
+      local ok, errmsg, errcode = fs.cp(src, dst)
+      assert.are_same({ "nil", "string", "number" }, { type(ok), type(errmsg), type(errcode) })
+
+      assert.is_true(fs.rm(root, true))
+    end)
+
+    it("fails when a nested destination path conflicts with a file", function()
+      local root = make_tmp_dir()
+      local src = join(root, "src")
+      local nested_dir = join(src, "deep")
+      local nested = join(nested_dir, "nested.txt")
+      local dst = join(root, "copy")
+      local conflicting = join(dst, "deep")
+
+      assert.is_true(fs.mkdir(nested_dir, true))
+      assert.is_true(fs.mkdir(dst, true))
+      assert.is_true(fs.write_text(nested, "xyz"))
+      assert.is_true(fs.write_text(conflicting, "not a dir"))
+
+      local ok, errmsg, errcode = fs.cp(src, dst)
+      assert.are_same({ "nil", "string", "number" }, { type(ok), type(errmsg), type(errcode) })
+
+      assert.is_true(fs.rm(root, true))
+    end)
+
+    it("fails when copying a directory onto itself", function()
+      local root = make_tmp_dir()
+      local src = join(root, "src")
+      local nested = join(src, "nested.txt")
+
+      assert.is_true(fs.mkdir(src, true))
+      assert.is_true(fs.write_text(nested, "xyz"))
+
+      local ok, errmsg, errcode = fs.cp(src, src)
+      local msg = "cannot copy a directory into itself or its descendant"
+      assert.are_same({ "nil", msg, "nil" }, { type(ok), errmsg, type(errcode) })
+
+      assert.are_equal("xyz", fs.read_text(nested))
+      assert.is_true(fs.rm(root, true))
+    end)
+
+    it("fails when copying a directory into its descendant", function()
+      local root = make_tmp_dir()
+      local src = join(root, "src")
+      local nested = join(src, "nested.txt")
+      local dst = join(src, "child", "copy")
+
+      assert.is_true(fs.mkdir(src, true))
+      assert.is_true(fs.write_text(nested, "xyz"))
+
+      local ok, errmsg, errcode = fs.cp(src, dst)
+      local msg = "cannot copy a directory into itself or its descendant"
+      assert.are_same({ "nil", msg, "nil" }, { type(ok), errmsg, type(errcode) })
+
+      assert.is_false(fs.exists(dst))
+      assert.are_equal("xyz", fs.read_text(nested))
+      assert.is_true(fs.rm(root, true))
+    end)
+  end)
+
   describe("rm()", function()
     it("removes a file without recursive mode", function()
       local target = tmpname()
@@ -485,6 +662,7 @@ describe("mods.fs", function()
   ---@diagnostic disable: param-type-mismatch, discard-returns, missing-parameter, assign-type-mismatch
   it("errors on invalid argument types", function()
     -- Argument #1 validation.
+    assert.has_error(function() fs.cp(false)       end, "bad argument #1 to 'cp' (string expected, got boolean)")
     assert.has_error(function() fs.exists(true)    end, "bad argument #1 to 'exists' (string expected, got boolean)")
     assert.has_error(function() fs.getatime(false) end, "bad argument #1 to 'getatime' (string expected, got boolean)")
     assert.has_error(function() fs.getctime(0)     end, "bad argument #1 to 'getctime' (string expected, got number)")
@@ -500,6 +678,7 @@ describe("mods.fs", function()
     assert.has_error(function() fs.write_text({})  end, "bad argument #1 to 'write_text' (string expected, got table)")
 
     -- Argument #2 validation.
+    assert.has_error(function() fs.cp("a")                      end, "bad argument #2 to 'cp' (string expected, got no value)")
     assert.has_error(function() fs.mkdir("tmp", 1)              end, "bad argument #2 to 'mkdir' (boolean expected, got number)")
     assert.has_error(function() fs.rm("tmp", 1)                 end, "bad argument #2 to 'rm' (boolean expected, got number)")
     assert.has_error(function() fs.samefile(readme_file, 123)   end, "bad argument #2 to 'samefile' (string expected, got number)")

src/mods/fs.lua

@@ -5,12 +5,14 @@ local path = mods.path
 local utils = mods.utils
 local lfs = mods.utils.lazy_module("lfs") ---@module "lfs"
 
-local assert_arg = utils.assert_arg
-local isdir = is.dir
 local islink = is.link
-local join = path.join
-local path_parents = path.parents
+local parents = path.parents
 local normpath = path.normpath
+local is_relative_to = path.is_relative_to
+local basename = path.basename
+local join = path.join
+local assert_arg = utils.assert_arg
+local isdir = is.dir
 
 local open = io.open
 local remove = os.remove
@@ -21,11 +23,20 @@ local M = {}
 
 local CURDIR = "."
 local PARDIR = ".."
+local entry_types = {
+  ["block device"] = "block",
+  ["char device"] = "char",
+  ["named pipe"] = "fifo",
+}
 
 local function is_dir_marker(entry)
   return entry == CURDIR or entry == PARDIR
 end
 
+local function is_hidden(entry)
+  return entry:sub(1, 1) == "."
+end
+
 -- `lfs.dir` throws on failure, so use `pcall` to preserve its error text as `false, err`.
 local function open_dir(p)
   local ok, iter, dir_obj = pcall(lfs.dir, p)
@@ -100,6 +111,85 @@ local function scan_dir(root, ls, follow_symlinks)
   return true
 end
 
+local function collect_dir_items(root, opts, items, fullpath)
+  local iter, dir_obj = open_dir(root)
+  if not iter then
+    return false, dir_obj
+  end
+
+  local stat = lfs.attributes
+  local lstat = lfs.symlinkattributes
+  local follow = opts.follow_links
+  local hidden = opts.hidden
+  local recursive = opts.recursive
+  local type_filter = opts.type
+
+  for entry in iter, dir_obj do
+    if not is_dir_marker(entry) and (hidden or not is_hidden(entry)) then
+      local child = join(root, entry)
+      local link_mode = lstat(child, "mode")
+      local type = entry_types[link_mode] or link_mode or "unknown"
+      local child_is_dir = type == "directory"
+      if follow and type == "link" then
+        child_is_dir = stat(child, "mode") == "directory"
+      end
+      if not type_filter or type_filter == type then
+        items[#items + 1] = { fullpath and child or entry, type }
+      end
+      if recursive and child_is_dir and (follow or type ~= "link") then
+        local ok, err = collect_dir_items(child, opts, items, fullpath)
+        if not ok then
+          return false, err
+        end
+      end
+    end
+  end
+  return true
+end
+
+local function copy_tree(src, dst)
+  local normed_src = normpath(src)
+  local normed_dst = normpath(dst)
+  if is_relative_to(normed_dst, normed_src) then
+    return nil, "cannot copy a directory into itself or its descendant"
+  end
+
+  local ok, errmsg, errcode = M.mkdir(dst, true)
+  if not ok then
+    return nil, errmsg, errcode
+  end
+
+  local items = {}
+  local collected, collect_err = collect_dir_items(src, { recursive = false }, items, true)
+  if not collected then
+    return nil, collect_err
+  end
+
+  for i = 1, #items do
+    local child, type_ = items[i][1], items[i][2]
+    local target = join(dst, basename(child))
+    if type_ == "directory" then
+      local copied, errmsg, errcode = copy_tree(child, target)
+      if not copied then
+        return nil, errmsg, errcode
+      end
+    else
+      local body
+      body, errmsg, errcode = M.read_bytes(child)
+      if not body then
+        return nil, errmsg, errcode
+      end
+
+      ok, errmsg, errcode = M.write_bytes(target, body)
+      if not ok then
+        return nil, errmsg, errcode
+      end
+    end
+  end
+
+  return true
+end
+
 function M.getsize(p)
   assert_arg(1, p, "string")
   return get_attr(p, "size")
@@ -231,17 +321,17 @@ function M.rm(p, recursive)
   return remove(p)
 end
 
-function M.mkdir(p, parents)
+function M.mkdir(p, parents_)
   assert_arg(1, p, "string")
-  assert_arg(2, parents, "boolean", true)
+  assert_arg(2, parents_, "boolean", true)
 
   local mkdir = lfs.mkdir
-  if not parents then
+  if not parents_ then
     return mkdir(p)
   end
 
   local normed = normpath(p)
-  local parents_dirs = path_parents(normed)
+  local parents_dirs = parents(normed)
   for i = #parents_dirs, 1, -1 do
     local dir = parents_dirs[i]
     if dir ~= CURDIR and not isdir(dir) then
@@ -259,6 +349,28 @@ function M.mkdir(p, parents)
   return true
 end
 
+function M.cp(src, dst)
+  assert_arg(1, src, "string")
+  assert_arg(2, dst, "string")
+
+  if isdir(src) then
+    return copy_tree(src, dst)
+  end
+
+  local body, errmsg, errcode = M.read_bytes(src)
+  if not body then
+    return nil, errmsg, errcode
+  end
+
+  local ok
+  ok, errmsg, errcode = M.write_bytes(dst, body)
+  if not ok then
+    return nil, errmsg, errcode
+  end
+
+  return true
+end
+
 M.rename = rename
 
 return M