fix(base): deprecate siblings with concat

README.md

@@ -88,15 +88,6 @@ assert(tostring(foo:parent()) == "folder")
 assert(foo                    == Path("./folder/foo.txt")) -- Path object can be created with arguments
 assert(foo                    == Path(folder, "foo.txt"))  -- Unpack any of them if you want!
 
--- Create siblings mode (just like `./<foo>/../bar.txt`)
-local bar = foo .. "bar.txt"
-assert(tostring(bar)          == "folder/bar.txt")
--- Mimic string concat mode (to work with your old code).
--- This makes old code with string paths work mostly as expected.
--- This is enabled only if rhs starts with "/" or "\\".
-local old_path = folder .. "/" .. "old-way" .. "/to/make/path.txt"
-assert(old_path               == Path("folder/old-way/to/make/path.txt"))
-
 -- Calculate relativily
 assert(foo:is_relative_to(Path("folder")))
 assert(not foo:is_relative_to(Path("./different folder")))
@@ -144,8 +135,8 @@ assert(content == "File Content\n")
 -- SHORTHAND: write to file
 new_file:io_write("File Content\n")
 
-new_file:copy(new_file .. "bar.txt") -- copy `foo.txt` to `bar.txt`
-new_file:symlink_to(new_file .. "baz.txt") -- create symlink of `foo.txt` named `baz.txt`
+new_file:copy(new_file:with_basename("bar.txt")) -- copy `foo.txt` to `bar.txt`
+new_file:symlink_to(new_file:with_basename("baz.txt")) -- create symlink of `foo.txt` named `baz.txt`
 ```
 
 ## Scan Directories

README.norg

@@ -101,15 +101,6 @@ version: 1.1.1
   assert(foo                    == Path("./folder/foo.txt")) -- Path object can be created with arguments
   assert(foo                    == Path(folder, "foo.txt"))  -- Unpack any of them if you want!
 
-  -- Create siblings mode (just like `./<foo>/../bar.txt`)
-  local bar = foo .. "bar.txt"
-  assert(tostring(bar)          == "folder/bar.txt")
-  -- Mimic string concat mode (to work with your old code).
-  -- This makes old code with string paths work mostly as expected.
-  -- This is enabled only if rhs starts with "/" or "\\".
-  local old_path = folder .. "/" .. "old-way" .. "/to/make/path.txt"
-  assert(old_path               == Path("folder/old-way/to/make/path.txt"))
-
   -- Calculate relativily
   assert(foo:is_relative_to(Path("folder")))
   assert(not foo:is_relative_to(Path("./different folder")))
@@ -153,8 +144,8 @@ version: 1.1.1
    -- SHORTHAND: write to file
    new_file:io_write("File Content\n")
 
-   new_file:copy(new_file .. "bar.txt") -- copy `foo.txt` to `bar.txt`
-   new_file:symlink_to(new_file .. "baz.txt") -- create symlink of `foo.txt` named `baz.txt`
+   new_file:copy(new_file:with_basename("bar.txt")) -- copy `foo.txt` to `bar.txt`
+   new_file:symlink_to(new_file:with_basename("baz.txt")) -- create symlink of `foo.txt` named `baz.txt`
    @end
 
 ** Scan Directories

lua/pathlib/base.lua

@@ -15,9 +15,8 @@ local watcher = require("pathlib.utils.watcher")
 ---@field public __fs_event_callbacks table<string, PathlibWatcherCallback>|nil # List of functions called when a fs_event is triggered.
 ---@field public __string_cache string|nil # Cache result of `tostring(self)`.
 ---@field public __parent_cache PathlibPath|nil # Cache reference to parent object.
----@field public __concat_dir_mode boolean|nil # If the object was created with `Path() .. "/"`, next string concat will append as a file.
 ---@operator div(PathlibPath|string): PathlibPath
----@operator concat(PathlibPath|string): PathlibPath
+---@operator concat(PathlibPath|string): string
 local Path = setmetatable({
   mytype = const.path_module_enum.PathlibPath,
   sep_str = "/",
@@ -981,7 +980,7 @@ function Path:len()
 end
 
 ---Concatenate paths. `Path.cwd() / "foo" / "bar.txt" == "./foo/bar.txt"`
----@param other PathlibPath | string
+---@param other PathlibPath|string
 ---@return PathlibPath
 function Path:__div(other)
   if not utils.tables.is_path_module(self) and not utils.tables.is_path_module(other) then
@@ -991,35 +990,17 @@ function Path:__div(other)
   return self.new(self, other)
 end
 
----Concatenate paths with the parent of lhs. `Path("./foo/foo.txt") .. "bar.txt" == "./foo/bar.txt"`
----
----To keep backwards compatibility, when rhs is a string and starts with "[/\\]", it behaves as like a string.
----
---->>> Path("./foo/foo.txt") .. "bar.txt" -- sibling mode
----Path("./foo/bar.txt")
----
---->>> Path("./foo") .. "/" .. "bar.txt" -- mimic string concat mode
----Path("./foo/bar.txt")
----
----@param other PathlibPath | string
----@return PathlibPath
+---@param other PathlibPath|string
+---@return string
 function Path:__concat(other)
-  if not utils.tables.is_path_module(self) and not utils.tables.is_path_module(other) then
+  if type(self) == "table" and not utils.tables.is_path_module(self) then
+    -- one of objects must be a path object
+    errs.value_error("__concat", self)
+  elseif type(other) == "table" and not utils.tables.is_path_module(other) then
     -- one of objects must be a path object
     errs.value_error("__concat", other)
-  elseif utils.tables.is_path_module(self) and type(other) == "string" then
-    if self.__concat_dir_mode then
-      other = "/" .. other
-    end
-    local first_letter = other:sub(1, 1)
-    local last_letter = other:sub(#other)
-    if first_letter == "/" or first_letter == "\\" then
-      local new = self.new(self, other)
-      new.__concat_dir_mode = last_letter == "/" or last_letter == "\\"
-      return new
-    end
   end
-  return self.new(self:parent(), other)
+  return tostring(self) .. tostring(other)
 end
 
 ---Convert path object to string

lua/pathlib/posix.lua

@@ -3,8 +3,8 @@ local const = require("pathlib.const")
 local err = require("pathlib.utils.errors")
 
 ---@class PathlibPosixPath : PathlibPath
----@operator div(PathlibPosixPath|string): PathlibPosixPath
----@operator concat(PathlibPosixPath|string): PathlibPosixPath
+---@operator div(PathlibPath|string): PathlibPosixPath
+---@operator concat(PathlibPath|string): string
 local PosixPath = setmetatable({
   mytype = const.path_module_enum.PathlibPosixPath,
 }, {

lua/pathlib/windows.lua

@@ -9,8 +9,8 @@ local function load_winapi()
 end
 
 ---@class PathlibWindowsPath : PathlibPath
----@operator div(PathlibWindowsPath|string): PathlibWindowsPath
----@operator concat(PathlibWindowsPath|string): PathlibWindowsPath
+---@operator div(PathlibPath|string): PathlibWindowsPath
+---@operator concat(PathlibPath|string): string
 local WindowsPath = setmetatable({
   mytype = const.path_module_enum.PathlibWindows,
   sep_str = "\\",

spec/path_dunder_spec.lua

@@ -76,23 +76,14 @@ describe("Test Dunder Methods of Path Object;", function()
 
   describe("__concat", function()
     it("()", function()
-      local sibling_file = Posix.new("./folder/baz.txt")
-      assert.are.equal(foo, sibling_file .. "foo.txt")
-      assert.are.equal(foo, sibling_file .. "./foo.txt")
-      assert.are.equal(foo, sibling_file .. Posix.new("./foo.txt"))
-    end)
-
-    it("backwards compat", function()
-      local path = Posix.new("./folder")
-      assert.are.equal(foo, path .. "/foo.txt")
-      assert.are.equal(foo, path .. "/" .. "foo.txt")
-      assert.are.equal(foo, path .. "/" .. "./foo.txt")
-      assert.are_not.equal(foo, path .. "foo.txt")
+      local file = Posix.new("./folder")
+      assert.are.equal("folder/foo/bar", file .. "/foo/bar")
+      assert.are.equal(tostring(file) .. "/foo/bar", file .. "/foo/bar")
     end)
 
     it("raise error", function()
       assert.has_error(function()
-        return Posix.new(".") / {}
+        return Posix.new(".") .. {}
       end)
     end)
   end)

spec/posix_manipulate_spec.lua

@@ -70,8 +70,8 @@ describe("Posix File Manipulation;", function()
 
   describe("iterdir", function()
     it("()", function()
-      foo:copy(foo .. "bar.txt")
-      foo:symlink_to(foo .. "baz.txt")
+      foo:copy(foo:with_basename("bar.txt"))
+      foo:symlink_to(foo:with_basename("baz.txt"))
       local accum = {}
       for path in parent:iterdir() do
         table.insert(accum, path)

spec/utf8_path_spec.lua

@@ -65,8 +65,8 @@ describe("Utf8 Filename Manipulation;", function()
 
   describe("iterdir", function()
     it("()", function()
-      foo:copy(foo .. "ｂａｒ.ｔｘｔ")
-      foo:symlink_to(foo .. "ｂａｚ.ｔｘｔ")
+      foo:copy(foo:with_basename("ｂａｒ.ｔｘｔ"))
+      foo:symlink_to(foo:with_basename("ｂａｚ.ｔｘｔ"))
       local accum = {}
       for path in parent:iterdir() do
         table.insert(accum, path)