Fix copy(into:) overwrite mode

Seems like Linux Foundation has a bug

I checked, seems fixed in Swift 5. But added a swift version check se we can verify and if not report the bug.

README.md

@@ -15,21 +15,29 @@ let docs = Path.home/"Documents"
 // paths are *always* absolute thus avoiding common bugs
 let path = Path(userInput) ?? Path.cwd/userInput
 
-// chainable syntax so you have less boilerplate
+// elegant, chainable syntax
 try Path.home.join("foo").mkdir().join("bar").touch().chmod(0o555)
 
-// easy file-management
-try Path.root.join("foo").copy(to: Path.root/"bar")
+// sensible considerations
+try Path.home.join("bar").mkdir()
+try Path.home.join("bar").mkdir()  // doesn’t throw ∵ we already have the desired result
 
-// careful API to avoid common bugs
-try Path.root.join("foo").copy(into: Path.root.mkdir("bar"))
-// ^^ other libraries would make the above `to:` form handle both these cases
-// but that can easily lead to bugs where you accidentally write files that
-// were meant to be directory destinations
+// easy file-management
+let bar = try Path.root.join("foo").copy(to: Path.root/"bar")
+print(bar)         // => /bar
+print(bar.isFile)  // => true
+
+// careful API considerations so as to avoid common bugs
+let foo = try Path.root.join("foo").copy(into: Path.root.mkdir("bar"))
+print(foo)         // => /bar/foo
+print(foo.isFile)  // => true
+
+// A practical example: installing a helper executable
+try Bundle.resources.join("helper").copy(into: Path.home.join(".local/bin").mkpath()).chmod(0o500)
 ```
 
-We emphasize safety and correctness, just like Swift, and also just
-like Swift, we provide a thoughtful and comprehensive (yet concise) API.
+We emphasize safety and correctness, just like Swift, and also (again like
+Swift), we provide a thoughtful and comprehensive (yet concise) API.
 
 # Support mxcl
 

Sources/Extensions.swift

@@ -1,5 +1,6 @@
 import Foundation
 
+/// Extensions on Foundation’s `Bundle` so you get `Path` rather than `String` or `URL`.
 public extension Bundle {
     /// Returns the path for requested resource in this bundle.
     func path(forResource: String, ofType: String?) -> Path? {
@@ -24,6 +25,7 @@ public extension Bundle {
     }
 }
 
+/// Extensions on `String` that work with `Path` rather than `String` or `URL`
 public extension String {
     /// Initializes this `String` with the contents of the provided path.
     @inlinable
@@ -40,6 +42,7 @@ public extension String {
     }
 }
 
+/// Extensions on `Data` that work with `Path` rather than `String` or `URL`
 public extension Data {
     /// Initializes this `Data` with the contents of the provided path.
     @inlinable

Sources/Path+Codable.swift

@@ -1,10 +1,12 @@
 import Foundation
 
+/// Provided for relative-path coding. See the instructions in our `README`.
 public extension CodingUserInfoKey {
     /// If set paths are encoded as relative to this path.
     static let relativePath = CodingUserInfoKey(rawValue: "dev.mxcl.Path.relative")!
 }
 
+/// Provided for relative-path coding. See the instructions in our `README`.
 extension Path: Codable {
     public init(from decoder: Decoder) throws {
         let value = try decoder.singleValueContainer().decode(String.self)

Sources/Path+FileManager.swift

@@ -7,7 +7,7 @@ public extension Path {
      - Parameter to: Destination filename.
      - Parameter overwrite: If true overwrites any file that already exists at `to`.
      - Returns: `to` to allow chaining
-     - SeeAlso: copy(into:overwrite:)
+     - SeeAlso: `copy(into:overwrite:)`
      */
     @discardableResult
     public func copy(to: Path, overwrite: Bool = false) throws -> Path {
@@ -22,21 +22,34 @@ public extension Path {
      Copies a file into a directory
 
      If the destination does not exist, this function creates the directory first.
+    
+        // Create ~/.local/bin, copy `ls` there and make the new copy executable
+        try Path.root.join("bin/ls").copy(into: Path.home.join(".local/bin").mkpath()).chmod(0o500)
 
      - Note: `throws` if `into` is a file.
      - Parameter into: Destination directory
      - Parameter overwrite: If true overwrites any file that already exists at `into`.
      - Returns: The `Path` of the newly copied file.
-     - SeeAlso: copy(into:overwrite:)
+     - SeeAlso: `copy(into:overwrite:)`
      */
     @discardableResult
     public func copy(into: Path, overwrite: Bool = false) throws -> Path {
         if !into.exists {
             try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
-        } else if overwrite, !into.isDirectory {
-            try into.delete()
         }
         let rv = into/basename()
+        if overwrite, rv.isFile {
+            try rv.delete()
+        }
+    #if os(Linux)
+    #if swift(>=5)
+        // check if fixed
+    #else
+        if !overwrite, rv.isFile {
+            throw CocoaError.error(.fileWriteFileExists)
+        }
+    #endif
+    #endif
         try FileManager.default.copyItem(at: url, to: rv.url)
         return rv
     }

Sources/Path.swift

@@ -10,7 +10,7 @@ import Foundation
      let p3 = Path.cwd/relativePathString
      let p4 = Path(userInput) ?? Path.cwd/userInput
 
- - Note: There may not be an actual filename at the path.
+ - Note: There may not be an actual filesystem entry at the path.
  */
 public struct Path: Equatable, Hashable, Comparable {
     /// The underlying filesystem path
@@ -113,7 +113,7 @@ public struct Path: Equatable, Hashable, Comparable {
 
      - Parameter pathComponent: The string to join with this path.
      - Returns: A new joined path.
-     - SeeAlso: /(:Path,:String)
+     - SeeAlso: `/(_:, _:)`
      */
     public func join<S>(_ pathComponent: S) -> Path where S: StringProtocol {
         //TODO standardizingPath does more than we want really (eg tilde expansion)
@@ -154,7 +154,7 @@ public struct Path: Equatable, Hashable, Comparable {
  - Parameter lhs: The base path to join with `rhs`.
  - Parameter rhs: The string to join with this `lhs`.
  - Returns: A new joined path.
- - SeeAlso: Path.join(_:)
+ - SeeAlso: `Path.join(_:)`
  */
 @inlinable
 public func /<S>(lhs: Path, rhs: S) -> Path where S: StringProtocol {

Tests/PathTests/PathTests.swift

@@ -132,5 +132,21 @@ class PathTests: XCTestCase {
         XCTAssertEqual(Path.root/"~/b", Path("/~/b"))
         XCTAssertEqual(Path("~/foo"), Path.home/"foo")
         XCTAssertNil(Path("~foo"))
+
+        XCTAssertEqual(Path.root/"a/foo"/"../bar", Path.root/"a/bar")
+        XCTAssertEqual(Path.root/"a/foo"/"/../bar", Path.root/"a/bar")
+        XCTAssertEqual(Path.root/"a/foo"/"../../bar", Path.root/"bar")
+        XCTAssertEqual(Path.root/"a/foo"/"../../../bar", Path.root/"bar")
+    }
+
+    func testCopyInto() throws {
+        try Path.mktemp { root in
+            let bar = try root.join("bar").touch()
+            try Path.mktemp { root in
+                try root.join("bar").touch()
+                XCTAssertThrowsError(try bar.copy(into: root))
+                try bar.copy(into: root, overwrite: true)
+            }
+        }
     }
 }

Tests/PathTests/XCTestManifests.swift

@@ -5,6 +5,7 @@ extension PathTests {
         ("testBasename", testBasename),
         ("testCodable", testCodable),
         ("testConcatenation", testConcatenation),
+        ("testCopyInto", testCopyInto),
         ("testEnumeration", testEnumeration),
         ("testEnumerationSkippingHiddenFiles", testEnumerationSkippingHiddenFiles),
         ("testExists", testExists),