Remaining code coverage

Can’t do coverage for Linux unfortunately.

.github/ranger.yml

@@ -1,3 +1,2 @@
 merges:
   - action: delete_branch
-  - action: tag

README.md

@@ -1,4 +1,4 @@
-# Path.swift ![badge-platforms] ![badge-languages][] [![Build Status](https://travis-ci.com/mxcl/Path.swift.svg)](https://travis-ci.com/mxcl/Path.swift)
+# Path.swift ![badge-platforms][] ![badge-languages][] [![badge-ci][]][travis] [![badge-jazzy][]][docs] [![badge-codecov][]][codecov] ![badge-version][]
 
 A file-system pathing library focused on developer experience and robust end
 results.
@@ -57,7 +57,7 @@ help me continue my work, I appreciate it x
 
 # Handbook
 
-Our [online API documentation] is automatically updated for new releases.
+Our [online API documentation][docs] is automatically updated for new releases.
 
 ## Codable
 
@@ -168,6 +168,20 @@ let files = Path.home.ls().files
 let swiftFiles = Path.home.ls().files(withExtension: "swift")
 ```
 
+# `Path.swift` is robust
+
+Some parts of `FileManager` are not exactly idiomatic. For example 
+`isExecutableFile` returns `true` even if there is no file there, it is instead
+telling you that *if* you made a file there it *could* be executable. Thus we
+check the POSIX permissions of the file first, before returning the result of
+`isExecutableFile`. `Path.swift` has done the leg-work for you so you can get on
+with your work without worries.
+
+# `Path.swift` is properly cross-platform
+
+`FileManager` on Linux is full of holes. We have found the holes and worked
+round them where necessary.
+
 # Rules & Caveats
 
 Paths are just string representations, there *might not* be a real file there.
@@ -200,7 +214,7 @@ Path("~/foo")!     // => /Users/mxcl/foo
 Path("~foo")       // => nil
 ```
 
-*Path.swift* has the general policty that if the desired end result preexists,
+*Path.swift* has the general policy that if the desired end result preexists,
 then it’s a noop:
 
 * If you try to delete a file, but the file doesn't exist, we do nothing.
@@ -246,4 +260,10 @@ https://codebasesaga.com/canopy/
 
 [badge-platforms]: https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20iOS%20%7C%20tvOS%20%7C%20watchOS-lightgrey.svg
 [badge-languages]: https://img.shields.io/badge/swift-4.2%20%7C%205.0-orange.svg
-[online API documentation]: https://mxcl.github.io/Path.swift/Structs/Path.html
+[docs]: https://mxcl.github.io/Path.swift/Structs/Path.html
+[badge-jazzy]: https://raw.githubusercontent.com/mxcl/Path.swift/gh-pages/badge.svg?sanitize=true
+[badge-codecov]: https://codecov.io/gh/mxcl/Path.swift/branch/master/graph/badge.svg
+[badge-ci]: https://travis-ci.com/mxcl/Path.swift.svg
+[travis]: https://travis-ci.com/mxcl/Path.swift
+[codecov]: https://codecov.io/gh/mxcl/Path.swift
+[badge-version]: https://img.shields.io/cocoapods/v/Path.swift.svg?label=version

Sources/Path+Attributes.swift

@@ -1,34 +1,35 @@
 import Foundation
+//#if os(Linux)
+//import func Glibc.chmod
+//#endif
 
 public extension Path {
     //MARK: Filesystem Attributes
 
     /**
      Returns the creation-time of the file.
-     - Note: Returns UNIX-time-zero if there is no creation-time, this should only happen if the file doesn’t exist.
+     - Note: Returns `nil` if there is no creation-time, this should only happen if the file doesn’t exist.
+     - Important: On Linux this is filesystem dependendent and may not exist.
      */
-    var ctime: Date {
+    var ctime: Date? {
         do {
             let attrs = try FileManager.default.attributesOfItem(atPath: string)
-            return attrs[.creationDate] as? Date ?? Date(timeIntervalSince1970: 0)
+            return attrs[.creationDate] as? Date
         } catch {
-            //TODO log error
+            return nil
-            return Date(timeIntervalSince1970: 0)
         }
     }
 
     /**
      Returns the modification-time of the file.
-     - Note: Returns the creation time if there is no modification time.
+     - Note: If this returns `nil` and the file exists, something is very wrong.
-     - Note: Returns UNIX-time-zero if neither are available, this should only happen if the file doesn’t exist.
      */
-    var mtime: Date {
+    var mtime: Date? {
         do {
             let attrs = try FileManager.default.attributesOfItem(atPath: string)
-            return attrs[.modificationDate] as? Date ?? ctime
+            return attrs[.modificationDate] as? Date
         } catch {
-            //TODO log error
+            return nil
-            return Date(timeIntervalSince1970: 0)
         }
     }
 
@@ -39,27 +40,40 @@ public extension Path {
      */
     @discardableResult
     func chmod(_ octal: Int) throws -> Path {
+//    #if os(Linux)
+//        Glibc.chmod(string, __mode_t(octal))
+//    #else
         try FileManager.default.setAttributes([.posixPermissions: octal], ofItemAtPath: string)
+//    #endif
         return self
     }
     
-    /// - Note: If file is already locked, does nothing
+    /**
-    /// - Note: If file doesn’t exist, throws
+     - Note: If file is already locked, does nothing.
+     - Note: If file doesn’t exist, throws.
+     - Important: On Linux does nothing.
+     */
     @discardableResult
     func lock() throws -> Path {
+    #if !os(Linux)
         var attrs = try FileManager.default.attributesOfItem(atPath: string)
         let b = attrs[.immutable] as? Bool ?? false
         if !b {
             attrs[.immutable] = true
             try FileManager.default.setAttributes(attrs, ofItemAtPath: string)
         }
+    #endif
         return self
     }
 
-    /// - Note: If file isn‘t locked, does nothing
+    /**
-    /// - Note: If file doesn’t exist, does nothing
+     - Note: If file isn‘t locked, does nothing.
+     - Note: If file doesn’t exist, does nothing.
+     - Important: On Linux does nothing.
+     */
     @discardableResult
     func unlock() throws -> Path {
+    #if !os(Linux)
         var attrs: [FileAttributeKey: Any]
         do {
             attrs = try FileManager.default.attributesOfItem(atPath: string)
@@ -71,6 +85,7 @@ public extension Path {
             attrs[.immutable] = false
             try FileManager.default.setAttributes(attrs, ofItemAtPath: string)
         }
+    #endif
         return self
     }
 }

Sources/Path+FileManager.swift

@@ -130,6 +130,9 @@ public extension Path {
      Deletes the path, recursively if a directory.
      - Note: noop: if the path doesn’t exist
      ∵ *Path.swift* doesn’t error if desired end result preexists.
+     - Note: On UNIX will this function will succeed if the parent directory is writable and the current user has permission.
+     - Note: This function will fail if the file or directory is “locked”
+     - SeeAlso: `lock()`
     */
     @inlinable
     func delete() throws {
@@ -175,8 +178,16 @@ public extension Path {
         return self
     }
 
+    /**
+     Renames the file at path.
+
+         Path.root.foo.bar.rename(to: "baz")  // => /foo/baz
+
+     - Parameter to: the new basename for the file
+     - Returns: The renamed path.
+     */
     @discardableResult
-    func rename(_ newname: String) throws -> Path {
+    func rename(to newname: String) throws -> Path {
         let newpath = parent/newname
         try FileManager.default.moveItem(atPath: string, toPath: newpath.string)
         return newpath

Sources/Path+StringConvertibles.swift

@@ -10,6 +10,6 @@ extension Path: CustomStringConvertible {
 extension Path: CustomDebugStringConvertible {
     /// Returns eg. `Path(string: "/foo")`
     public var debugDescription: String {
-        return "Path(string: \(string))"
+        return "Path(\(string))"
     }
 }

Sources/Path->Bool.swift

@@ -1,4 +1,9 @@
 import Foundation
+#if os(Linux)
+import func Glibc.access
+#else
+import func Darwin.access
+#endif
 
 public extension Path {
     //MARK: Filesystem Properties
@@ -32,11 +37,22 @@ public extension Path {
         
     /// Returns true if the path represents an actual file that is also deletable by the current user.
     var isDeletable: Bool {
-        return FileManager.default.isDeletableFile(atPath: string)
+    #if os(Linux) && !swift(>=5.1)
+        return exists && access(parent.string, W_OK) == 0
+    #else
+        // FileManager.isDeletableFile returns true if there is *not* a file there
+        return exists && FileManager.default.isDeletableFile(atPath: string)
+    #endif
     }
 
     /// Returns true if the path represents an actual file that is also executable by the current user.
     var isExecutable: Bool {
-        return FileManager.default.isExecutableFile(atPath: string)
+        if access(string, X_OK) == 0 {
+            // FileManager.isExxecutableFile returns true even if there is *not*
+            // a file there *but* if there was it could be *made* executable
+            return FileManager.default.isExecutableFile(atPath: string)
+        } else {
+            return false
+        }
     }
 }

Sources/Path.swift

@@ -9,7 +9,7 @@ import Foundation
  `Path` supports `Codable`, and can be configured to
  [encode paths *relatively*](https://github.com/mxcl/Path.swift/#codable).
 
- Sorting a `Sequence` of `Path`s will return the locale-aware sort order, which
+ Sorting a `Sequence` of paths will return the locale-aware sort order, which
  will give you the same order as Finder.
 
  Converting from a `String` is a common first step, here are the recommended
@@ -20,13 +20,12 @@ import Foundation
      let p3 = Path.cwd/relativePathString
      let p4 = Path(userInput) ?? Path.cwd/userInput
 
- If you are constructing Paths from static-strings we provide support for
+ If you are constructing paths from static-strings we provide support for
  dynamic members:
 
      let p1 = Path.root.usr.bin.ls  // => /usr/bin/ls
 
- - Note: There may not be an actual filesystem entry at the path. The underlying
+ - Note: A `Path` does not necessarily represent an actual filesystem entry.
-   representation for `Path` is `String`.
  */
 
 @dynamicMemberLookup

Tests/PathTests/PathTests.swift

@@ -164,6 +164,14 @@ class PathTests: XCTestCase {
         XCTAssertEqual(a.Documents, Path.home/"foo/Documents")
     }
 
+    func testCopyTo() throws {
+        try Path.mktemp { root in
+            try root.foo.touch().copy(to: root.bar)
+            XCTAssert(root.foo.isFile)
+            XCTAssert(root.bar.isFile)
+        }
+    }
+
     func testCopyInto() throws {
         try Path.mktemp { root1 in
             let bar1 = try root1.join("bar").touch()
@@ -177,6 +185,14 @@ class PathTests: XCTestCase {
         }
     }
 
+    func testMoveTo() throws {
+        try Path.mktemp { root in
+            try root.foo.touch().move(to: root.bar)
+            XCTAssertFalse(root.foo.exists)
+            XCTAssert(root.bar.isFile)
+        }
+    }
+
     func testMoveInto() throws {
         try Path.mktemp { root1 in
             let bar1 = try root1.join("bar").touch()
@@ -194,14 +210,147 @@ class PathTests: XCTestCase {
         try Path.mktemp { root in
             do {
                 let file = try root.bar.touch()
-                let foo = try file.rename("foo")
+                let foo = try file.rename(to: "foo")
                 XCTAssertFalse(file.exists)
                 XCTAssertTrue(foo.isFile)
             }
             do {
                 let file = try root.bar.touch()
-                XCTAssertThrowsError(try file.rename("foo"))
+                XCTAssertThrowsError(try file.rename(to: "foo"))
             }
         }
     }
+
+    func testCommonDirectories() {
+        XCTAssertEqual(Path.root.string, "/")
+        XCTAssertEqual(Path.home.string, NSHomeDirectory())
+        XCTAssertEqual(Path.documents.string, NSHomeDirectory() + "/Documents")
+    #if os(macOS)
+        XCTAssertEqual(Path.caches.string, NSHomeDirectory() + "/Library/Caches")
+        XCTAssertEqual(Path.cwd.string, FileManager.default.currentDirectoryPath)
+        XCTAssertEqual(Path.applicationSupport.string, NSHomeDirectory() + "/Library/Application Support")
+    #endif
+    }
+
+    func testStringConvertibles() {
+        XCTAssertEqual(Path.root.description, "/")
+        XCTAssertEqual(Path.root.debugDescription, "Path(/)")
+    }
+
+    func testFilesystemAttributes() throws {
+        XCTAssert(Path(#file)!.isFile)
+        XCTAssert(Path(#file)!.isReadable)
+        XCTAssert(Path(#file)!.isWritable)
+        XCTAssert(Path(#file)!.isDeletable)
+        XCTAssert(Path(#file)!.parent.isDirectory)
+
+        try Path.mktemp { tmpdir in
+            XCTAssertTrue(tmpdir.isDirectory)
+            XCTAssertFalse(tmpdir.isFile)
+
+            let bar = try tmpdir.bar.touch().chmod(0o000)
+            XCTAssertFalse(bar.isReadable)
+            XCTAssertFalse(bar.isWritable)
+            XCTAssertFalse(bar.isDirectory)
+            XCTAssertFalse(bar.isExecutable)
+            XCTAssertTrue(bar.isFile)
+            XCTAssertTrue(bar.isDeletable)  // can delete even if no read permissions
+
+            try bar.chmod(0o777)
+            XCTAssertTrue(bar.isReadable)
+            XCTAssertTrue(bar.isWritable)
+            XCTAssertTrue(bar.isDeletable)
+            XCTAssertTrue(bar.isExecutable)
+
+            try bar.delete()
+            XCTAssertFalse(bar.exists)
+            XCTAssertFalse(bar.isReadable)
+            XCTAssertFalse(bar.isWritable)
+            XCTAssertFalse(bar.isExecutable)
+            XCTAssertFalse(bar.isDeletable)
+
+            let nonExistantFile = tmpdir.baz
+            XCTAssertFalse(nonExistantFile.exists)
+            XCTAssertFalse(nonExistantFile.isExecutable)
+            XCTAssertFalse(nonExistantFile.isReadable)
+            XCTAssertFalse(nonExistantFile.isWritable)
+            XCTAssertFalse(nonExistantFile.isDeletable)
+            XCTAssertFalse(nonExistantFile.isDirectory)
+            XCTAssertFalse(nonExistantFile.isFile)
+
+            let baz = try tmpdir.baz.touch()
+            XCTAssertTrue(baz.isDeletable)
+            try tmpdir.chmod(0o500)  // remove write permission on directory
+            XCTAssertFalse(baz.isDeletable)  // this is how deletion is prevented on UNIX
+        }
+    }
+
+    func testTimes() throws {
+        try Path.mktemp { tmpdir in
+            let foo = try tmpdir.foo.touch()
+            let now1 = Date().timeIntervalSince1970.rounded(.down)
+        #if !os(Linux)
+            XCTAssertEqual(foo.ctime?.timeIntervalSince1970.rounded(.down), now1)  //FIXME flakey
+        #endif
+            XCTAssertEqual(foo.mtime?.timeIntervalSince1970.rounded(.down), now1)  //FIXME flakey
+            sleep(1)
+            try foo.touch()
+            let now2 = Date().timeIntervalSince1970.rounded(.down)
+            XCTAssertNotEqual(now1, now2)
+            XCTAssertEqual(foo.mtime?.timeIntervalSince1970.rounded(.down), now2)  //FIXME flakey
+        }
+    }
+
+    func testDelete() throws {
+        try Path.mktemp { tmpdir in
+            try tmpdir.bar1.delete()
+            try tmpdir.bar2.touch().delete()
+            try tmpdir.bar3.touch().chmod(0o000).delete()
+        #if !os(Linux)
+            XCTAssertThrowsError(try tmpdir.bar3.touch().lock().delete())
+        #endif
+        }
+    }
+
+    func testRelativeCodable() throws {
+        let path = Path.home.foo
+        let encoder = JSONEncoder()
+        encoder.userInfo[.relativePath] = Path.home
+        let data = try encoder.encode([path])
+        let decoder = JSONDecoder()
+        decoder.userInfo[.relativePath] = Path.home
+        XCTAssertEqual(try decoder.decode([Path].self, from: data), [path])
+        decoder.userInfo[.relativePath] = Path.documents
+        XCTAssertEqual(try decoder.decode([Path].self, from: data), [Path.documents.foo])
+        XCTAssertThrowsError(try JSONDecoder().decode([Path].self, from: data))
+    }
+
+    func testBundleExtensions() {
+        XCTAssertTrue(Bundle.main.path.isDirectory)
+        XCTAssertTrue(Bundle.main.resources.isDirectory)
+
+        // don’t exist in tests
+        _ = Bundle.main.path(forResource: "foo", ofType: "bar")
+        _ = Bundle.main.sharedFrameworks
+    }
+
+    func testDataExentsions() throws {
+        let data = try Data(contentsOf: Path(#file)!)
+        try Path.mktemp { tmpdir in
+            _ = try data.write(to: tmpdir.foo)
+        }
+    }
+
+    func testStringExentsions() throws {
+        let string = try String(contentsOf: Path(#file)!)
+        try Path.mktemp { tmpdir in
+            _ = try string.write(to: tmpdir.foo)
+        }
+    }
+
+    func testFileHandleExtensions() throws {
+        _ = try FileHandle(forReadingAt: Path(#file)!)
+        _ = try FileHandle(forWritingAt: Path(#file)!)
+        _ = try FileHandle(forUpdatingAt: Path(#file)!)
+    }
 }

Tests/PathTests/TemporaryDirectory.swift

@@ -42,7 +42,11 @@ class TemporaryDirectory {
     }
 
     deinit {
-        _ = try? FileManager.default.removeItem(at: url)
+        do {
+            try path.chmod(0o777).delete()
+        } catch {
+            //TODO log
+        }
     }
 }
 

Tests/PathTests/XCTestManifests.swift

@@ -3,22 +3,34 @@ import XCTest
 extension PathTests {
     static let __allTests = [
         ("testBasename", testBasename),
+        ("testBundleExtensions", testBundleExtensions),
         ("testCodable", testCodable),
+        ("testCommonDirectories", testCommonDirectories),
         ("testConcatenation", testConcatenation),
         ("testCopyInto", testCopyInto),
+        ("testCopyTo", testCopyTo),
+        ("testDataExentsions", testDataExentsions),
+        ("testDelete", testDelete),
         ("testDynamicMember", testDynamicMember),
         ("testEnumeration", testEnumeration),
         ("testEnumerationSkippingHiddenFiles", testEnumerationSkippingHiddenFiles),
         ("testExists", testExists),
         ("testExtension", testExtension),
+        ("testFileHandleExtensions", testFileHandleExtensions),
+        ("testFilesystemAttributes", testFilesystemAttributes),
         ("testIsDirectory", testIsDirectory),
         ("testJoin", testJoin),
         ("testMkpathIfExists", testMkpathIfExists),
         ("testMktemp", testMktemp),
         ("testMoveInto", testMoveInto),
+        ("testMoveTo", testMoveTo),
+        ("testRelativeCodable", testRelativeCodable),
         ("testRelativePathCodable", testRelativePathCodable),
         ("testRelativeTo", testRelativeTo),
         ("testRename", testRename),
+        ("testStringConvertibles", testStringConvertibles),
+        ("testStringExentsions", testStringExentsions),
+        ("testTimes", testTimes),
     ]
 }