Merge pull request #14 from mxcl/delete-noop

Delete noop

.gitignore

@@ -1,3 +1,5 @@
 .DS_Store
 /.build
 /*.xcodeproj
+/build
+/docs

.travis.yml

@@ -69,6 +69,8 @@ jobs:
           - UseModernBuildSystem=NO
         output: output
         github_url: https://github.com/mxcl/Path.swift
+        exclude:
+          - Sources/Path+StringConvertibles.swift
         EOF
         sed -i '' "s/TRAVIS_TAG/$TRAVIS_TAG/" .jazzy.yaml
       # ^^ this weirdness because Travis multiline YAML is broken and inserts

README.md

@@ -33,7 +33,7 @@ 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)
+try Bundle.resources.join("helper").copy(into: Path.home.join(".local/bin").mkdir(.p)).chmod(0o500)
 ```
 
 We emphasize safety and correctness, just like Swift, and also (again like
@@ -107,10 +107,8 @@ This is explicit, not hiding anything that code-review may miss and preventing
 common bugs like accidentally creating `Path` objects from strings you did not
 expect to be relative.
 
-Our initializer is nameless because we conform to `LosslessStringConvertible`,
-the same conformance as that `Int`, `Float` etc. conform. The protocol enforces
-a nameless initialization and since it is appropriate for us to conform to it,
-we do.
+Our initializer is nameless to be consistent with the equivalent operation for
+converting strings to `Int`, `Float` etc. in the standard library.
 
 ## Extensions
 
@@ -186,6 +184,16 @@ Path("~/foo")!     // => /Users/mxcl/foo
 Path("~foo")       // => nil
 ```
 
+*Path.swift* has the general policty 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.
+* If you try to make a directory and it already exists, we do nothing.
+
+However notably if you try to copy or move a file with specifying `overwrite`
+and the file already exists at the destination and is identical, we don’t check
+for that as the check was deemed too expensive to be worthwhile.
+
 # Installation
 
 SwiftPM:

Sources/Path+Attributes.swift

@@ -1,6 +1,34 @@
 import Foundation
 
 public extension Path {
+    //MARK: Filesystem Attributes
+
+    /**
+     Returns the modification-time.
+     - Note: Returns the creation time if there is no modification time.
+     - Note: Returns UNIX-time-zero if neither are available, though this *should* be impossible.
+     */
+    var mtime: Date {
+        do {
+            let attrs = try FileManager.default.attributesOfItem(atPath: string)
+            return attrs[.modificationDate] as? Date ?? attrs[.creationDate] as? Date ?? Date(timeIntervalSince1970: 0)
+        } catch {
+            //TODO log error
+            return Date(timeIntervalSince1970: 0)
+        }
+    }
+
+    /**
+     Sets the file’s attributes using UNIX octal notation.
+
+         Path.home.join("foo").chmod(0o555)
+     */
+    @discardableResult
+    func chmod(_ octal: Int) throws -> Path {
+        try FileManager.default.setAttributes([.posixPermissions: octal], ofItemAtPath: string)
+        return self
+    }
+    
     /// - Note: If file is already locked, does nothing
     /// - Note: If file doesn’t exist, throws
     @discardableResult
@@ -31,30 +59,4 @@ public extension Path {
         }
         return self
     }
-
-    /**
-     Sets the file’s attributes using UNIX octal notation.
-
-         Path.home.join("foo").chmod(0o555)
-     */
-    @discardableResult
-    func chmod(_ octal: Int) throws -> Path {
-        try FileManager.default.setAttributes([.posixPermissions: octal], ofItemAtPath: string)
-        return self
-    }
-
-    /**
-     Returns the modification-time.
-     - Note: Returns the creation time if there is no modification time.
-     - Note: Returns UNIX-time-zero if neither are available, though this *should* be impossible.
-     */
-    var mtime: Date {
-        do {
-            let attrs = try FileManager.default.attributesOfItem(atPath: string)
-            return attrs[.modificationDate] as? Date ?? attrs[.creationDate] as? Date ?? Date(timeIntervalSince1970: 0)
-        } catch {
-            //TODO log error
-            return Date(timeIntervalSince1970: 0)
-        }
-    }
 }

Sources/Path+Codable.swift

@@ -1,13 +1,31 @@
 import Foundation
 
-/// Provided for relative-path coding. See the instructions in our `README`.
+/**
+ Provided for relative-path coding. See the instructions in our
+ [README](https://github.com/mxcl/Path.swift/#codable).
+*/
 public extension CodingUserInfoKey {
-    /// If set paths are encoded as relative to this path.
+    /**
+     If set on an `Encoder`’s `userInfo` all paths are encoded relative to this path.
+
+     For example:
+
+         let encoder = JSONEncoder()
+         encoder.userInfo[.relativePath] = Path.home
+         encoder.encode([Path.home, Path.home/"foo"])
+
+     - Remark: See the [README](https://github.com/mxcl/Path.swift/#codable) for more information.
+    */
     static let relativePath = CodingUserInfoKey(rawValue: "dev.mxcl.Path.relative")!
 }
 
-/// Provided for relative-path coding. See the instructions in our `README`.
-extension Path: Codable {
+/**
+ Provided for relative-path coding. See the instructions in our
+ [README](https://github.com/mxcl/Path.swift/#codable).
+*/
+extension Path: Codable {    
+    /// - SeeAlso: `CodingUserInfoKey.relativePath`
+    /// :nodoc:
     public init(from decoder: Decoder) throws {
         let value = try decoder.singleValueContainer().decode(String.self)
         if value.hasPrefix("/") {
@@ -20,6 +38,8 @@ extension Path: Codable {
         }
     }
 
+    /// - SeeAlso: `CodingUserInfoKey.relativePath`
+    /// :nodoc:
     public func encode(to encoder: Encoder) throws {
         var container = encoder.singleValueContainer()
         if let root = encoder.userInfo[.relativePath] as? Path {

Sources/Path+CommonDirectories.swift

@@ -1,6 +1,8 @@
 import Foundation
 
 extension Path {
+    //MARK: Common Directories
+    
     /// Returns a `Path` containing ``FileManager.default.currentDirectoryPath`.
     public static var cwd: Path {
         return Path(string: FileManager.default.currentDirectoryPath)

Sources/Path+FileManager.swift

@@ -1,12 +1,22 @@
 import Foundation
 
 public extension Path {
+    //MARK: File Management
+    
     /**
      Copies a file.
+
+         try Path.root.join("bar").copy(to: Path.home/"foo")
+         // => "/Users/mxcl/foo"
+
      - Note: `throws` if `to` is a directory.
      - Parameter to: Destination filename.
      - Parameter overwrite: If `true` and both `self` and `to` are files, overwrites `to`.
      - Note: If either `self` or `to are directories, `overwrite` is ignored.
+     - Note: Throws if `overwrite` is `false` yet `to` is *already* identical to
+      `self` because even though *Path.swift’s* policy is to noop if the desired
+       end result preexists, checking for this condition is too expensive a
+       trade-off.
      - Returns: `to` to allow chaining
      - SeeAlso: `copy(into:overwrite:)`
      */
@@ -22,15 +32,22 @@ 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)
+         try Path.root.join("bar").copy(into: .home)
+         // => "/Users/mxcl/bar"
+
+         // 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").mkdir(.p)).chmod(0o500)
+
+     If the destination does not exist, this function creates the directory first.
 
-     - 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.
+     - Note: `throws` if `into` is a file.
+     - Note: Throws if `overwrite` is `false` yet `to` is *already* identical to
+      `self` because even though *Path.swift’s* policy is to noop if the desired
+       end result preexists, checking for this condition is too expensive a
+       trade-off.
      - SeeAlso: `copy(into:overwrite:)`
      */
     @discardableResult
@@ -57,10 +74,18 @@ public extension Path {
 
     /**
      Moves a file.
-     - Note: `throws` if `to` is a directory.
+
+         try Path.root.join("bar").move(to: Path.home/"foo")
+         // => "/Users/mxcl/foo"
+
      - Parameter to: Destination filename.
      - Parameter overwrite: If true overwrites any file that already exists at `to`.
      - Returns: `to` to allow chaining
+     - Note: `throws` if `to` is a directory.
+     - Note: Throws if `overwrite` is `false` yet `to` is *already* identical to
+       `self` because even though *Path.swift’s* policy is to noop if the desired
+       end result preexists, checking for this condition is too expensive a
+       trade-off.
      - SeeAlso: move(into:overwrite:)
      */
     @discardableResult
@@ -75,18 +100,21 @@ public extension Path {
     /**
      Moves a file into a directory
 
+         try Path.root.join("bar").move(into: .home)
+         // => "/Users/mxcl/bar"
+
      If the destination does not exist, this function creates the directory first.
 
-     - Note: `throws` if `into` is a file.
      - Parameter into: Destination directory
-     - Parameter overwrite: If true overwrites any file that already exists at `into`.
+     - Parameter overwrite: If true *overwrites* any file that already exists at `into`.
+     - Note: `throws` if `into` is a file.
      - Returns: The `Path` of destination filename.
      - SeeAlso: move(into:overwrite:)
      */
     @discardableResult
     func move(into: Path) throws -> Path {
         if !into.exists {
-            try into.mkpath()
+            try into.mkdir(.p)
         } else if !into.isDirectory {
             throw CocoaError.error(.fileWriteFileExists)
         }
@@ -95,10 +123,16 @@ public extension Path {
         return rv
     }
 
-    /// Deletes the path, recursively if a directory.
+    /**
+     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.
+    */
     @inlinable
     func delete() throws {
-        try FileManager.default.removeItem(at: url)
+        if exists {
+            try FileManager.default.removeItem(at: url)
+        }
     }
 
     /**
@@ -111,49 +145,37 @@ public extension Path {
         return try "".write(to: self)
     }
 
-    /// Helper due to Linux Swift being incomplete.
-    private func _foo(go: () throws -> Void) throws {
-    #if !os(Linux)
+    /**
+     Creates the directory at this path.
+     - Note: Does not create any intermediary directories.
+     - Parameter options: Specify `mkdir(.p)` to create intermediary directories.
+     - Note: We do not error if the directory already exists (even without `.p`)
+       because *Path.swift* noops if the desired end result preexists.
+     - Returns: `self` to allow chaining.
+     */
+    @discardableResult
+    func mkdir(_ options: MakeDirectoryOptions? = nil) throws -> Path {
         do {
-            try go()
+            let wid = options == .p
+            try FileManager.default.createDirectory(at: self.url, withIntermediateDirectories: wid, attributes: nil)
         } catch CocoaError.Code.fileWriteFileExists {
-            // noop
-        }
-    #else
-        do {
-            try go()
+            //noop (fails to trigger on Linux)
         } catch {
+        #if os(Linux)
             let error = error as NSError
             guard error.domain == NSCocoaErrorDomain, error.code == CocoaError.Code.fileWriteFileExists.rawValue else {
                 throw error
             }
-        }
-    #endif
-    }
-
-    /**
-     Creates the directory at this path.
-     - Note: Does not create any intermediary directories.
-     - Returns: `self` to allow chaining.
-     */
-    @discardableResult
-    func mkdir() throws -> Path {
-        try _foo {
-            try FileManager.default.createDirectory(at: self.url, withIntermediateDirectories: false, attributes: nil)
-        }
-        return self
-    }
-
-    /**
-     Creates the directory at this path.
-     - Note: Creates any intermediary directories, if required.
-     - Returns: `self` to allow chaining.
-     */
-    @discardableResult
-    func mkpath() throws -> Path {
-        try _foo {
-            try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true, attributes: nil)
+        #else
+            throw error
+        #endif
         }
         return self
     }
 }
+
+/// Options for `Path.mkdir`
+public enum MakeDirectoryOptions {
+    /// Creates intermediary directories. Works the same as mkdir -p.
+    case p
+}

Sources/Path+StringConvertibles.swift

@@ -1,14 +1,6 @@
 import class Foundation.NSString
 
-extension Path: LosslessStringConvertible {
-    /// Returns `nil` unless fed an absolute path
-    public init?(_ description: String) {
-        guard description.starts(with: "/") || description.starts(with: "~/") else { return nil }
-        self.init(string: (description as NSString).standardizingPath)
-    }
-}
-
-extension Path: CustomStringConvertible {
+extension Path: CustomStringConvertible {    
     /// Returns `Path.string`
     public var description: String {
         return string

Sources/Path+ls.swift

@@ -1,8 +1,10 @@
 import Foundation
 
 public extension Path {
+    //MARK: Directory Listings
+    
     /**
-     Same as the `ls -a` command ∴ is ”shallow”
+     Same as the `ls -a` command ∴ output is ”shallow” and unsorted.
      - Parameter includeHiddenFiles: If `true`, hidden files are included in the results. Defaults to `true`.
      - Important: `includeHiddenFiles` does not work on Linux
      */
@@ -22,6 +24,7 @@ public extension Path {
     }
 }
 
+/// Convenience functions for the array return value of `Path.ls()`
 public extension Array where Element == Path.Entry {
     /// Filters the list of entries to be a list of Paths that are directories.
     var directories: [Path] {

Sources/Path->Bool.swift

@@ -1,25 +1,11 @@
 import Foundation
 
 public extension Path {
-    /// Returns true if the path represents an actual file that is also writable by the current user.
-    var isWritable: Bool {
-        return FileManager.default.isWritableFile(atPath: string)
-    }
-    
-    /// Returns true if the path represents an actual file that is also readable by the current user.
-    var isReadable: Bool {
-        return FileManager.default.isReadableFile(atPath: string)
-    }
-    
-    /// 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)
-    }
+    //MARK: Filesystem Properties
 
-    /// Returns true if the path represents an actual directory.
-    var isDirectory: Bool {
-        var isDir: ObjCBool = false
-        return FileManager.default.fileExists(atPath: string, isDirectory: &isDir) && isDir.boolValue
+    /// Returns true if the path represents an actual filesystem entry.
+    var exists: Bool {
+        return FileManager.default.fileExists(atPath: string)
     }
 
     /// Returns true if the path represents an actual filesystem entry that is *not* a directory.
@@ -28,13 +14,29 @@ public extension Path {
         return FileManager.default.fileExists(atPath: string, isDirectory: &isDir) && !isDir.boolValue
     }
 
+    /// Returns true if the path represents an actual directory.
+    var isDirectory: Bool {
+        var isDir: ObjCBool = false
+        return FileManager.default.fileExists(atPath: string, isDirectory: &isDir) && isDir.boolValue
+    }
+
+    /// Returns true if the path represents an actual file that is also readable by the current user.
+    var isReadable: Bool {
+        return FileManager.default.isReadableFile(atPath: string)
+    }
+
+    /// Returns true if the path represents an actual file that is also writable by the current user.
+    var isWritable: Bool {
+        return FileManager.default.isWritableFile(atPath: string)
+    }
+        
+    /// 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)
+    }
+
     /// 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)
     }
-
-    /// Returns true if the path represents an actual filesystem entry.
-    var exists: Bool {
-        return FileManager.default.fileExists(atPath: string)
-    }
 }

Sources/Path.swift

@@ -3,26 +3,44 @@ import Foundation
 /**
  Represents a platform filesystem absolute path.
 
- The recommended conversions from string are:
+ `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
+ will give you the same order as Finder, (though folders will not be sorted
+ first).
+
+ Converting from a `String` is a common first step, here are the recommended
+ ways to do that:
 
      let p1 = Path.root/pathString
      let p2 = Path.root/url.path
      let p3 = Path.cwd/relativePathString
      let p4 = Path(userInput) ?? Path.cwd/userInput
 
- - Note: There may not be an actual filesystem entry at the path.
+ - Note: There may not be an actual filesystem entry at the path. The underlying
+   representation for `Path` is `String`.
  */
 public struct Path: Equatable, Hashable, Comparable {
+
+    init(string: String) {
+        self.string = string
+    }
+
+    /// Returns `nil` unless fed an absolute path
+    public init?(_ description: String) {
+        guard description.starts(with: "/") || description.starts(with: "~/") else { return nil }
+        self.init(string: (description as NSString).standardizingPath)
+    }
+
+//MARK: Properties
+
     /// The underlying filesystem path
     public let string: String
 
-    /**
-     Returns the filename extension of this path.
-     - Remark: Implemented via `NSString.pathExtension`.
-     */
-    @inlinable
-    public var `extension`: String {
-        return (string as NSString).pathExtension
+    /// Returns a `URL` representing this file path.
+    public var url: URL {
+        return URL(fileURLWithPath: string)
     }
 
     /**
@@ -37,33 +55,51 @@ public struct Path: Equatable, Hashable, Comparable {
         return Path(string: (string as NSString).deletingLastPathComponent)
     }
 
-    /// Returns a `URL` representing this file path.
+    /**
+     Returns the filename extension of this path.
+     - Remark: Implemented via `NSString.pathExtension`.
+     */
     @inlinable
-    public var url: URL {
-        return URL(fileURLWithPath: string)
+    public var `extension`: String {
+        return (string as NSString).pathExtension
+    }
+
+//MARK: Pathing
+
+    /**
+     Joins a path and a string to produce a new path.
+
+         Path.root.join("a")             // => /a
+         Path.root.join("a/b")           // => /a/b
+         Path.root.join("a").join("b")   // => /a/b
+         Path.root.join("a").join("/b")  // => /a/b
+
+     - Parameter pathComponent: The string to join with this path.
+     - Returns: A new joined path.
+     - SeeAlso: `Path./(_:, _:)`
+     */
+    public func join<S>(_ pathComponent: S) -> Path where S: StringProtocol {
+        //TODO standardizingPath does more than we want really (eg tilde expansion)
+        let str = (string as NSString).appendingPathComponent(String(pathComponent))
+        return Path(string: (str as NSString).standardizingPath)
     }
 
     /**
-     The basename for the provided file, optionally dropping the file extension.
+     Joins a path and a string to produce a new path.
 
-         Path.root.join("foo.swift").basename()  // => "foo.swift"
-         Path.root.join("foo.swift").basename(dropExtension: true)  // => "foo"
+         Path.root/"a"       // => /a
+         Path.root/"a/b"     // => /a/b
+         Path.root/"a"/"b"   // => /a/b
+         Path.root/"a"/"/b"  // => /a/b
 
-     - Returns: A string that is the filename’s basename.
-     - Parameter dropExtension: If `true` returns the basename without its file extension.
+     - Parameter lhs: The base path to join with `rhs`.
+     - Parameter rhs: The string to join with this `lhs`.
+     - Returns: A new joined path.
+     - SeeAlso: `join(_:)`
      */
-    public func basename(dropExtension: Bool = false) -> String {
-        let str = string as NSString
-        if !dropExtension {
-            return str.lastPathComponent
-        } else {
-            let ext = str.pathExtension
-            if !ext.isEmpty {
-                return String(str.lastPathComponent.dropLast(ext.count + 1))
-            } else {
-                return str.lastPathComponent
-            }
-        }
+    @inlinable
+    public static func /<S>(lhs: Path, rhs: S) -> Path where S: StringProtocol {
+        return lhs.join(rhs)
     }
 
     /**
@@ -104,30 +140,41 @@ public struct Path: Equatable, Hashable, Comparable {
     }
 
     /**
-     Joins a path and a string to produce a new path.
+     The basename for the provided file, optionally dropping the file extension.
 
-         Path.root.join("a")             // => /a
-         Path.root.join("a/b")           // => /a/b
-         Path.root.join("a").join("b")   // => /a/b
-         Path.root.join("a").join("/b")  // => /a/b
+         Path.root.join("foo.swift").basename()  // => "foo.swift"
+         Path.root.join("foo.swift").basename(dropExtension: true)  // => "foo"
 
-     - Parameter pathComponent: The string to join with this path.
-     - Returns: A new joined path.
-     - SeeAlso: `/(_:, _:)`
+     - Returns: A string that is the filename’s basename.
+     - Parameter dropExtension: If `true` returns the basename without its file extension.
      */
-    public func join<S>(_ pathComponent: S) -> Path where S: StringProtocol {
-        //TODO standardizingPath does more than we want really (eg tilde expansion)
-        let str = (string as NSString).appendingPathComponent(String(pathComponent))
-        return Path(string: (str as NSString).standardizingPath)
+    public func basename(dropExtension: Bool = false) -> String {
+        let str = string as NSString
+        if !dropExtension {
+            return str.lastPathComponent
+        } else {
+            let ext = str.pathExtension
+            if !ext.isEmpty {
+                return String(str.lastPathComponent.dropLast(ext.count + 1))
+            } else {
+                return str.lastPathComponent
+            }
+        }
     }
 
     /// Returns the locale-aware sort order for the two paths.
+    /// :nodoc:
     @inlinable
     public static func <(lhs: Path, rhs: Path) -> Bool {
         return lhs.string.compare(rhs.string, locale: .current) == .orderedAscending
     }
 
-    /// A file entry from a directory listing.
+//MARK: Entry
+
+    /**
+     A file entry from a directory listing.
+     - SeeAlso: `ls()`
+    */
     public struct Entry {
         /// The kind of this directory entry.
         public enum Kind {
@@ -142,21 +189,3 @@ public struct Path: Equatable, Hashable, Comparable {
         public let path: Path
     }
 }
-
-/**
- Joins a path and a string to produce a new path.
-
-     Path.root/"a"       // => /a
-     Path.root/"a/b"     // => /a/b
-     Path.root/"a"/"b"   // => /a/b
-     Path.root/"a"/"/b"  // => /a/b
-
- - 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(_:)`
- */
-@inlinable
-public func /<S>(lhs: Path, rhs: S) -> Path where S: StringProtocol {
-    return lhs.join(rhs)
-}

Tests/PathTests/PathTests.swift

@@ -83,7 +83,7 @@ class PathTests: XCTestCase {
         try Path.mktemp {
             for _ in 0...1 {
                 try $0.join("a").mkdir()
-                try $0.join("b/c").mkpath()
+                try $0.join("b/c").mkdir(.p)
             }
         }
     }