refactor(fs): align error returns with Lua

Author: haithium

spec/fs_spec.lua

@@ -23,9 +23,10 @@ describe("mods.fs", function()
     end)
 
     it(fmt("%s() returns nil and an error for a missing path", fname), function()
-      local value, err = fs[fname]("__mods_missing_path__")
+      local value, errmsg, errcode = fs[fname]("__mods_missing_path__")
       assert.is_nil(value)
-      assert.is_string(err)
+      assert.is_string(errmsg)
+      assert.is_number(errcode)
     end)
   end
 
@@ -36,9 +37,10 @@ describe("mods.fs", function()
     end)
 
     it("returns nil and an error for a missing path", function()
-      local attrs, err = fs.stat("__mods_missing_path__")
+      local attrs, errmsg, errcode = fs.stat("__mods_missing_path__")
       assert.is_nil(attrs)
-      assert.is_string(err)
+      assert.is_string(errmsg)
+      assert.is_number(errcode)
     end)
   end)
 
@@ -49,9 +51,10 @@ describe("mods.fs", function()
     end)
 
     it("returns nil and an error for a missing path", function()
-      local attrs, err = fs.lstat("__mods_missing_path__")
+      local attrs, errmsg, errcode = fs.lstat("__mods_missing_path__")
       assert.is_nil(attrs)
-      assert.is_string(err)
+      assert.is_string(errmsg)
+      assert.is_number(errcode)
     end)
   end)
 
@@ -70,10 +73,11 @@ describe("mods.fs", function()
       assert.is_true(os.remove(to))
     end)
 
-    it("returns nil and an error for a missing path", function()
-      local ok, err = fs.rename("__mods_missing_path__", tmpname())
+    it("fails with an error for a missing path", function()
+      local ok, errmsg, errcode = fs.rename("__mods_missing_path__", tmpname())
       assert.is_nil(ok)
-      assert.is_string(err)
+      assert.is_string(errmsg)
+      assert.is_number(errcode)
     end)
   end)
 
@@ -85,11 +89,12 @@ describe("mods.fs", function()
       assert.is_true(os.remove(target))
     end)
 
-    it("returns false and an error when the parent directory does not exist", function()
+    it("fails with an error when the parent directory does not exist", function()
       local target = path.join(tmpname(), "missing", "file.bin")
-      local ok, err = fs.write_bytes(target, "abc")
-      assert.is_false(ok)
-      assert.is_string(err)
+      local ok, errmsg, errcode = fs.write_bytes(target, "abc")
+      assert.is_nil(ok)
+      assert.is_string(errmsg)
+      assert.is_number(errcode)
     end)
   end)
 
@@ -101,11 +106,12 @@ describe("mods.fs", function()
       assert.is_true(os.remove(target))
     end)
 
-    it("returns false and an error when the parent directory does not exist", function()
+    it("fails with an error when the parent directory does not exist", function()
       local target = path.join(tmpname(), "missing", "file.txt")
-      local ok, err = fs.write_text(target, "abc")
-      assert.is_false(ok)
-      assert.is_string(err)
+      local ok, errmsg, errcode = fs.write_text(target, "abc")
+      assert.is_nil(ok)
+      assert.is_string(errmsg)
+      assert.is_number(errcode)
     end)
   end)
 
@@ -117,10 +123,11 @@ describe("mods.fs", function()
       assert.is_true(os.remove(target))
     end)
 
-    it("returns nil and an error for a missing path", function()
-      local body, err = fs.read_bytes("__mods_missing_path__")
+    it("fails with an error for a missing path", function()
+      local body, errmsg, errcode = fs.read_bytes("__mods_missing_path__")
       assert.is_nil(body)
-      assert.is_string(err)
+      assert.is_string(errmsg)
+      assert.is_number(errcode)
     end)
   end)
 
@@ -132,10 +139,11 @@ describe("mods.fs", function()
       assert.is_true(os.remove(target))
     end)
 
-    it("returns nil and an error for a missing path", function()
-      local body, err = fs.read_text("__mods_missing_path__")
+    it("fails with an error for a missing path", function()
+      local body, errmsg, errcode = fs.read_text("__mods_missing_path__")
       assert.is_nil(body)
-      assert.is_string(err)
+      assert.is_string(errmsg)
+      assert.is_number(errcode)
     end)
   end)
 
@@ -167,9 +175,10 @@ describe("mods.fs", function()
     it("fails when the parent directory does not exist", function()
       local root = tmpname()
       local target = path.join(root, "missing", "file.txt")
-      local ok, err = fs.touch(target)
-      assert.is_false(ok)
-      assert.is_string(err)
+      local ok, errmsg, errcode = fs.touch(target)
+      assert.is_nil(ok)
+      assert.is_string(errmsg)
+      assert.is_number(errcode)
     end)
 
     if is_unix then
@@ -355,13 +364,15 @@ describe("mods.fs", function()
     assert.are_same({ false }, { fs.samefile(readme_file, spec_file) })
 
     it("fails on missing path", function()
-      local ok, err = fs.samefile(readme_file, "__mods_missing_path__")
+      local ok, errmsg, errcode = fs.samefile(readme_file, "__mods_missing_path__")
       assert.is_nil(ok)
-      assert.is_string(err)
+      assert.is_string(errmsg)
+      assert.is_number(errcode)
 
-      ok, err = fs.samefile("__mods_missing_path__", readme_file)
+      ok, errmsg, errcode = fs.samefile("__mods_missing_path__", readme_file)
       assert.is_nil(ok)
-      assert.is_string(err)
+      assert.is_string(errmsg)
+      assert.is_number(errcode)
     end)
 
     if is_unix then

src/mods/fs.lua

@@ -36,19 +36,19 @@ end
 
 ---@param name LuaFileSystem.AttributeName
 local function get_attr(p, name)
-  local value, err = lfs.attributes(p, name)
-  if value == nil then
-    return nil, err
+  local value, errmsg, errcode = lfs.attributes(p, name)
+  if not value then
+    return nil, errmsg, errcode
   end
   return value
 end
 
 ---Read entire file contents using given mode.
----@return string? body, string? err
+---@return string? body, string? err, integer? errcode
 local function read(p, mode)
-  local f, err = open(p, mode)
+  local f, errmsg, errcode = open(p, mode)
   if not f then
-    return nil, err
+    return nil, errmsg, errcode
   end
 
   local body = f:read("*a")
@@ -58,15 +58,15 @@ end
 
 ---Write file contents using the given mode.
 local function write(p, data, mode)
-  local f, err = open(p, mode)
+  local f, errmsg, errcode = open(p, mode)
   if not f then
-    return false, err
+    return nil, errmsg, errcode
   end
 
   local ok, write_err = f:write(data)
   f:close()
   if not ok then
-    return false, write_err
+    return nil, write_err
   end
 
   return true
@@ -122,16 +122,16 @@ function M.samefile(path_a, path_b)
   assert_arg(1, path_a, "string")
   assert_arg(2, path_b, "string")
 
-  local a, b, err
+  local a, b, errmsg, errcode
 
-  a, err = M.stat(path_a)
+  a, errmsg, errcode = M.stat(path_a)
   if not a then
-    return nil, err
+    return nil, errmsg, errcode
   end
 
-  b, err = M.stat(path_b)
+  b, errmsg, errcode = M.stat(path_b)
   if not b then
-    return nil, err
+    return nil, errmsg, errcode
   end
 
   return a.dev == b.dev and a.ino == b.ino
@@ -142,14 +142,12 @@ function M.touch(p)
 
   -- `lfs.touch` updates timestamps for existing files but does not create new ones.
   if M.exists(p) then
-    local ok, err = lfs.touch(p)
-    -- Normalize `lfs.touch` failure from `nil` to `false`.
-    return ok == true, err
+    return lfs.touch(p)
   end
 
-  local file, err = open(p, "ab")
+  local file, errmsg, errcode = open(p, "ab")
   if not file then
-    return false, err
+    return nil, errmsg, errcode
   end
 
   file:close()

types/fs.lua

@@ -19,7 +19,8 @@ local M = {}
 ---
 ---@param path string Input path.
 ---@return string? body File contents read in binary mode, or `nil` on failure.
----@return string? err Error message when the check fails.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 ---@nodiscard
 function M.read_bytes(path) end
 
@@ -32,7 +33,8 @@ function M.read_bytes(path) end
 ---
 ---@param path string Input path.
 ---@return string? body File contents read in text mode, or `nil` on failure.
----@return string? err Error message when the check fails.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 ---@nodiscard
 function M.read_text(path) end
 
@@ -49,8 +51,9 @@ function M.read_text(path) end
 ---
 ---@param path string Input path.
 ---@param data string Input data.
----@return boolean written `true` when writing succeeds, `false` on failure.
----@return string? err Error message when the check fails.
+---@return true? written `true` when writing succeeds, or `nil` on failure.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 function M.write_bytes(path, data) end
 
 ---
@@ -62,8 +65,9 @@ function M.write_bytes(path, data) end
 ---
 ---@param path string Input path.
 ---@param data string Input data.
----@return boolean written `true` when writing succeeds, `false` on failure.
----@return string? err Error message when the check fails.
+---@return true? written `true` when writing succeeds, or `nil` on failure.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 function M.write_text(path, data) end
 
 ---
@@ -74,8 +78,9 @@ function M.write_text(path, data) end
 ---```
 ---
 ---@param path string Input path.
----@return boolean touched `true` when the file exists after touch, `false` on failure.
----@return string? err Error message when the check fails.
+---@return true? touched `true` when the file exists after touch, or `nil` on failure.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 function M.touch(path) end
 
 ---
@@ -90,8 +95,9 @@ function M.touch(path) end
 ---
 ---@param oldname string Existing path.
 ---@param newname string Replacement path.
----@return boolean renamed `true` when the rename succeeds, `false` on failure.
----@return string? err Error message when the check fails.
+---@return true? renamed `true` when the rename succeeds, or `nil` on failure.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 function M.rename(oldname, newname) end
 
 ---
@@ -105,7 +111,7 @@ function M.rename(oldname, newname) end
 ---@param path string Input path.
 ---@param recursive? boolean Remove a directory tree recursively when `true`.
 ---@return true? removed `true` when removal succeeds, or `nil` on failure.
----@return string? err Error message when the check fails.
+---@return string? errmsg Error message when the check fails.
 ---@return integer? errcode OS error code when available.
 function M.rm(path, recursive) end
 
@@ -122,7 +128,8 @@ function M.rm(path, recursive) end
 ---
 ---@param path string Input path.
 ---@return integer? size File size in bytes.
----@return string? err Error message when the check fails.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 ---@nodiscard
 function M.getsize(path) end
 
@@ -135,7 +142,8 @@ function M.getsize(path) end
 ---
 ---@param path string Input path.
 ---@return number? timestamp Access time (seconds since epoch).
----@return string? err Error message when the check fails.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 ---@nodiscard
 function M.getatime(path) end
 
@@ -148,7 +156,8 @@ function M.getatime(path) end
 ---
 ---@param path string Input path.
 ---@return number? timestamp Modification time (seconds since epoch).
----@return string? err Error message when the check fails.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 ---@nodiscard
 function M.getmtime(path) end
 
@@ -161,7 +170,8 @@ function M.getmtime(path) end
 ---
 ---@param path string Input path.
 ---@return number? timestamp Change time (seconds since epoch).
----@return string? err Error message when the check fails.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 ---@nodiscard
 function M.getctime(path) end
 
@@ -174,7 +184,8 @@ function M.getctime(path) end
 ---
 ---@param path string Input path.
 ---@return LuaFileSystem.Attributes? attrs Symlink-aware attributes, or `nil` on failure.
----@return string? err Error message when the check fails.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 ---@nodiscard
 function M.lstat(path) end
 
@@ -187,7 +198,8 @@ function M.lstat(path) end
 ---
 ---@param path string Input path.
 ---@return string|integer|LuaFileSystem.AttributeMode|LuaFileSystem.Attributes? attrs File attributes, or `nil` on failure.
----@return string? err Error message when the check fails.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 ---@nodiscard
 function M.stat(path) end
 
@@ -201,7 +213,8 @@ function M.stat(path) end
 ---@param path_a string Input path.
 ---@param path_b string Input path.
 ---@return boolean? isSameFile True when both paths refer to the same file.
----@return string? err Error message when the check fails.
+---@return string? errmsg Error message when the check fails.
+---@return integer? errcode OS error code when available.
 ---@nodiscard
 function M.samefile(path_a, path_b) end