Merge pull request #24 from mxcl/rename

Rename

.github/codecov.yml

@@ -0,0 +1,2 @@
+ignore:
+  - Tests

.github/ranger.yml

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

.travis.yml

@@ -19,9 +19,10 @@ jobs:
       name: macOS / Swift 4.2.1
 
     - &xcodebuild
-      before_install: swift package generate-xcodeproj
+      before_install: swift package generate-xcodeproj --enable-code-coverage
       xcode_destination: platform=iOS Simulator,OS=latest,name=iPhone XS
       name: iOS / Swift 4.2.1
+      after_success: bash <(curl -s https://codecov.io/bash)
     - <<: *xcodebuild
       xcode_destination: platform=tvOS Simulator,OS=latest,name=Apple TV
       name: tvOS / Swift 4.2.1
@@ -34,6 +35,7 @@ jobs:
           -scheme Path.swift-Package \
           -destination 'platform=watchOS Simulator,OS=latest,name=Apple Watch Series 4 - 40mm' \
           build | xcpretty
+      after_success: false
 
     - &linux
       env: SWIFT_VERSION=4.2.1
@@ -89,11 +91,28 @@ jobs:
 
     - name: CocoaPods
       before_install: |
+        export DESCRIPTION=$(swift - <<\ \ EOF
+          import Foundation
+          struct Response: Decodable { let description: String }
+          let token = ProcessInfo.processInfo.environment["GITHUB_TOKEN"]!
+          let url = URL(string: "https://api.github.com/repos/mxcl/Path.swift")!
+          var rq = URLRequest(url: url)
+          rq.setValue("token \(token)", forHTTPHeaderField: "Authorization")
+          let semaphore = DispatchSemaphore(value: 0)
+          var data: Data!
+          URLSession.shared.dataTask(with: rq) { d, _, _ in
+              data = d
+              semaphore.signal()
+          }.resume()
+          semaphore.wait()
+          let rsp = try JSONDecoder().decode(Response.self, from: data)
+          print(rsp.description, terminator: "")
+        EOF)
         cat <<\ \ EOF> Path.swift.podspec
         Pod::Spec.new do |s|
           s.name = 'Path.swift'
-          s.version = 'TRAVIS_TAG'
+          s.version = ENV['TRAVIS_TAG']
-          s.summary = 'Delightful, robust file-pathing functions'
+          s.summary = ENV['DESCRIPTION']
           s.homepage = 'https://github.com/mxcl/Path.swift'
           s.license = { :type => 'Unlicense', :file => 'LICENSE.md' }
           s.author = { 'mxcl' => 'mxcl@me.com' }
@@ -107,7 +126,5 @@ jobs:
           s.swift_version = '4.2'
         end
         EOF
-        sed -i '' "s/TRAVIS_TAG/$TRAVIS_TAG/" Path.swift.podspec
-      # ^^ see the Jazzy deployment for explanation
       install: gem install cocoapods --pre
       script: pod trunk push

README.md

@@ -1,7 +1,7 @@
-# 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][] [![Build Status](https://travis-ci.com/mxcl/Path.swift.svg)](https://travis-ci.com/mxcl/Path.swift)
 
-A file-system pathing library focused on developer experience and robust
+A file-system pathing library focused on developer experience and robust end
-end‐results.
+results.
 
 ```swift
 import Path
@@ -28,11 +28,14 @@ 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"))
+let foo = try Path.root.join("foo").copy(into: Path.root.join("bar").mkdir())
 print(foo)         // => /bar/foo
 print(foo.isFile)  // => true
 
-// A practical example: installing a helper executable
+// we support dynamic members (_use_sparingly_):
+let prefs = Path.home.Library.Preferences  // => /Users/mxcl/Library/Preferences
+
+// a practical example: installing a helper executable
 try Bundle.resources.join("helper").copy(into: Path.home.join(".local/bin").mkdir(.p)).chmod(0o500)
 ```
 
@@ -42,8 +45,9 @@ Swift), we provide a thoughtful and comprehensive (yet concise) API.
 # Support mxcl
 
 Hi, I’m Max Howell and I have written a lot of open source software, and
-probably you already use some of it (Homebrew anyone?). Please help me so I
+probably you already use some of it (Homebrew anyone?). I work full-time on
-can continue to make tools and software you need and love. I appreciate it x.
+open source and it’s hard; currently I earn *less* than minimum wage. Please
+help me continue my work, I appreciate it x
 
 <a href="https://www.patreon.com/mxcl">
 	<img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160">
@@ -94,6 +98,19 @@ decoder.userInfo[.relativePath] = Path.home
 decoder.decode(from: data)
 ```
 
+## Dynamic members
+
+We support `@dynamicMemberLookup`:
+
+```swift
+let ls = Path.root.usr.bin.ls  // => /usr/bin/ls
+```
+
+This is less commonly useful than you would think, hence our documentation
+does not use it. Usually you are joining variables or other `String` arguments 
+or trying to describe files (and files usually have extensions). However when
+you need it, it’s *lovely*.
+
 ## Initializing from user-input
 
 The `Path` initializer returns `nil` unless fed an absolute path; thus to
@@ -122,8 +139,7 @@ bashProfile += "\n\nfoo"
 
 try bashProfile.write(to: Path.home/".bash_profile")
 
-try Bundle.main.resources!.join("foo").copy(to: .home)
+try Bundle.main.resources.join("foo").copy(to: .home)
-// ^^ `-> Path?` because the underlying `Bundle` function is `-> String?`
 ```
 
 ## Directory listings
@@ -145,9 +161,9 @@ for entry in Path.home.ls() where entry.path.mtime > yesterday {
     //…
 }
 
-let dirs = Path.home.ls().directories().filter {
+let dirs = Path.home.ls().directories
-    //…
+
-}
+let files = Path.home.ls().files
 
 let swiftFiles = Path.home.ls().files(withExtension: "swift")
 ```
@@ -205,7 +221,7 @@ package.append(.package(url: "https://github.com/mxcl/Path.swift", from: "0.5.0"
 CocoaPods:
 
 ```ruby
-pod 'Path.swift' ~> '0.5.0'
+pod 'Path.swift', '~> 0.5'
 ```
 
 Carthage:
@@ -229,5 +245,5 @@ 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-orange.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

Sources/Extensions.swift

@@ -10,13 +10,31 @@ public extension Bundle {
     }
 
     /// Returns the path for the shared-frameworks directory in this bundle.
-    var sharedFrameworks: Path? {
+    var sharedFrameworks: Path {
-        return sharedFrameworksPath.flatMap(Path.init)
+        var `default`: Path {
+          #if os(macOS)
+            return path.join("Contents/Frameworks")
+          #elseif os(Linux)
+            return path.join("lib")
+          #else
+            return path.join("Frameworks")
+          #endif
+        }
+        return sharedFrameworksPath.flatMap(Path.init) ?? `default`
     }
 
     /// Returns the path for the resources directory in this bundle.
-    var resources: Path? {
+    var resources: Path {
-        return resourcePath.flatMap(Path.init)
+        var `default`: Path {
+          #if os(macOS)
+            return path.join("Contents/Resources")
+          #elseif os(Linux)
+            return path.join("share")
+          #else
+            return path
+          #endif
+        }
+        return resourcePath.flatMap(Path.init) ?? `default`
     }
 
     /// Returns the path for this bundle.
@@ -68,3 +86,24 @@ public extension Data {
         return to
     }
 }
+
+/// Extensions on `FileHandle` that work with `Path` rather than `String` or `URL`
+public extension FileHandle {
+    /// Initializes this `FileHandle` for reading at the location of the provided path.
+    @inlinable
+    convenience init(forReadingAt path: Path) throws {
+        try self.init(forReadingFrom: path.url)
+    }
+    
+    /// Initializes this `FileHandle` for writing at the location of the provided path.
+    @inlinable
+    convenience init(forWritingAt path: Path) throws {
+        try self.init(forWritingTo: path.url)
+    }
+    
+    /// Initializes this `FileHandle` for reading and writing at the location of the provided path.
+    @inlinable
+    convenience init(forUpdatingAt path: Path) throws {
+        try self.init(forUpdating: path.url)
+    }
+}

Sources/Path+Attributes.swift

@@ -4,14 +4,28 @@ public extension Path {
     //MARK: Filesystem Attributes
 
     /**
-     Returns the modification-time.
+     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.
+     */
+    var ctime: Date {
+        do {
+            let attrs = try FileManager.default.attributesOfItem(atPath: string)
+            return attrs[.creationDate] as? Date ?? Date(timeIntervalSince1970: 0)
+        } catch {
+            //TODO log error
+            return Date(timeIntervalSince1970: 0)
+        }
+    }
+
+    /**
+     Returns the modification-time of the file.
      - 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.
+     - Note: Returns UNIX-time-zero if neither are available, this should only happen if the file doesn’t exist.
      */
     var mtime: Date {
         do {
             let attrs = try FileManager.default.attributesOfItem(atPath: string)
-            return attrs[.modificationDate] as? Date ?? attrs[.creationDate] as? Date ?? Date(timeIntervalSince1970: 0)
+            return attrs[.modificationDate] as? Date ?? ctime
         } catch {
             //TODO log error
             return Date(timeIntervalSince1970: 0)

Sources/Path+CommonDirectories.swift

@@ -3,7 +3,7 @@ import Foundation
 extension Path {
     //MARK: Common Directories
     
-    /// Returns a `Path` containing ``FileManager.default.currentDirectoryPath`.
+    /// Returns a `Path` containing `FileManager.default.currentDirectoryPath`.
     public static var cwd: Path {
         return Path(string: FileManager.default.currentDirectoryPath)
     }
@@ -74,7 +74,7 @@ extension Path {
 
     /**
      The root for cache files.
-     - Note: On Linux this is 'XDG_CACHE_HOME'.
+     - Note: On Linux this is `XDG_CACHE_HOME`.
      - Note: You should create a subdirectory before creating any files.
      */
     public static var caches: Path {

Sources/Path+FileManager.swift

@@ -90,7 +90,7 @@ public extension Path {
      */
     @discardableResult
     func move(to: Path, overwrite: Bool = false) throws -> Path {
-        if overwrite, to.exists {
+        if overwrite, to.isFile {
             try FileManager.default.removeItem(at: to.url)
         }
         try FileManager.default.moveItem(at: url, to: to.url)
@@ -112,13 +112,16 @@ public extension Path {
      - SeeAlso: move(into:overwrite:)
      */
     @discardableResult
-    func move(into: Path) throws -> Path {
+    func move(into: Path, overwrite: Bool = false) throws -> Path {
         if !into.exists {
             try into.mkdir(.p)
         } else if !into.isDirectory {
             throw CocoaError.error(.fileWriteFileExists)
         }
         let rv = into/basename()
+        if overwrite, rv.isFile {
+            try FileManager.default.removeItem(at: rv.url)
+        }
         try FileManager.default.moveItem(at: url, to: rv.url)
         return rv
     }
@@ -147,7 +150,6 @@ public extension Path {
 
     /**
      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.
@@ -172,10 +174,17 @@ public extension Path {
         }
         return self
     }
+
+    @discardableResult
+    func rename(_ newname: String) throws -> Path {
+        let newpath = parent/newname
+        try FileManager.default.moveItem(atPath: string, toPath: newpath.string)
+        return newpath
+    }
 }
 
-/// Options for `Path.mkdir`
+/// Options for `Path.mkdir(_:)`
 public enum MakeDirectoryOptions {
-    /// Creates intermediary directories. Works the same as mkdir -p.
+    /// Creates intermediary directories; works the same as `mkdir -p`.
     case p
 }

Sources/Path+ls.swift

@@ -1,8 +1,26 @@
 import Foundation
 
-public extension Path {
+/**
+ A file entry from a directory listing.
+ - SeeAlso: `ls()`
+*/
+public struct Entry {
+    /// The kind of this directory entry.
+    public enum Kind {
+        /// The path is a file.
+        case file
+        /// The path is a directory.
+        case directory
+    }
+    /// The kind of this entry.
+    public let kind: Kind
+    /// The path of this entry.
+    public let path: Path
+}
+
+public extension Path {    
     //MARK: Directory Listings
-    
+
     /**
      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`.
@@ -25,7 +43,7 @@ public extension Path {
 }
 
 /// Convenience functions for the array return value of `Path.ls()`
-public extension Array where Element == Path.Entry {
+public extension Array where Element == Entry {
     /// Filters the list of entries to be a list of Paths that are directories.
     var directories: [Path] {
         return compactMap {
@@ -33,7 +51,14 @@ public extension Array where Element == Path.Entry {
         }
     }
 
-    /// Filters the list of entries to be a list of Paths that are files with the specified extension
+    /// Filters the list of entries to be a list of Paths that are files.
+    var files: [Path] {
+        return compactMap {
+            $0.kind == .file ? $0.path : nil
+        }
+    }
+
+    /// Filters the list of entries to be a list of Paths that are files with the specified extension.
     func files(withExtension ext: String) -> [Path] {
         return compactMap {
             $0.kind == .file && $0.path.extension == ext ? $0.path : nil

Sources/Path.swift

@@ -1,14 +1,16 @@
 import Foundation
 
 /**
- Represents a platform filesystem absolute path.
+ A `Path` represents an absolute path on a filesystem.
+
+ All functions on `Path` are chainable and short to facilitate doing sequences
+ of file operations in a concise manner.
 
  `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
+ will give you the same order as Finder.
- first).
 
  Converting from a `String` is a common first step, here are the recommended
  ways to do that:
@@ -18,21 +20,34 @@ 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
+ 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
    representation for `Path` is `String`.
  */
+
+@dynamicMemberLookup
 public struct Path: Equatable, Hashable, Comparable {
 
     init(string: String) {
         self.string = string
     }
 
-    /// Returns `nil` unless fed an absolute path
+    /// 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)
     }
 
+    /// :nodoc:
+    public subscript(dynamicMember pathComponent: String) -> Path {
+        let str = (string as NSString).appendingPathComponent(pathComponent)
+        return Path(string: str)
+    }
+
 //MARK: Properties
 
     /// The underlying filesystem path
@@ -58,10 +73,15 @@ public struct Path: Equatable, Hashable, Comparable {
     /**
      Returns the filename extension of this path.
      - Remark: Implemented via `NSString.pathExtension`.
+     - Note: We special case eg. `foo.tar.gz`.
      */
     @inlinable
     public var `extension`: String {
-        return (string as NSString).pathExtension
+        if string.hasSuffix(".tar.gz") {
+            return "tar.gz"
+        } else {
+            return (string as NSString).pathExtension
+        }
     }
 
 //MARK: Pathing
@@ -76,7 +96,7 @@ public struct Path: Equatable, Hashable, Comparable {
 
      - Parameter pathComponent: The string to join with this path.
      - Returns: A new joined path.
-     - SeeAlso: `Path./(_:, _:)`
+     - SeeAlso: `Path./(_:_:)`
      */
     public func join<S>(_ pathComponent: S) -> Path where S: StringProtocol {
         //TODO standardizingPath does more than we want really (eg tilde expansion)
@@ -168,24 +188,4 @@ public struct Path: Equatable, Hashable, Comparable {
     public static func <(lhs: Path, rhs: Path) -> Bool {
         return lhs.string.compare(rhs.string, locale: .current) == .orderedAscending
     }
-
-//MARK: Entry
-
-    /**
-     A file entry from a directory listing.
-     - SeeAlso: `ls()`
-    */
-    public struct Entry {
-        /// The kind of this directory entry.
-        public enum Kind {
-            /// The path is a file.
-            case file
-            /// The path is a directory.
-            case directory
-        }
-        /// The kind of this entry.
-        public let kind: Kind
-        /// The path of this entry.
-        public let path: Path
-    }
 }

Tests/PathTests/PathTests.swift

@@ -14,21 +14,27 @@ class PathTests: XCTestCase {
     func testEnumeration() throws {
         let tmpdir_ = try TemporaryDirectory()
         let tmpdir = tmpdir_.path
-        try tmpdir.join("a").mkdir().join("c").touch()
+        try tmpdir.a.mkdir().c.touch()
-        try tmpdir.join("b").touch()
+        try tmpdir.join("b.swift").touch()
-        try tmpdir.join("c").touch()
+        try tmpdir.c.touch()
-        try tmpdir.join(".d").mkdir().join("e").touch()
+        try tmpdir.join(".d").mkdir().e.touch()
 
         var paths = Set<String>()
+        let lsrv = try tmpdir.ls()
         var dirs = 0
-        for entry in try tmpdir.ls() {
+        for entry in lsrv {
             if entry.kind == .directory {
                 dirs += 1
             }
             paths.insert(entry.path.basename())
         }
         XCTAssertEqual(dirs, 2)
-        XCTAssertEqual(paths, ["a", "b", "c", ".d"])
+        XCTAssertEqual(dirs, lsrv.directories.count)
+        XCTAssertEqual(["a", ".d"], Set(lsrv.directories.map{ $0.relative(to: tmpdir) }))
+        XCTAssertEqual(["b.swift", "c"], Set(lsrv.files.map{ $0.relative(to: tmpdir) }))
+        XCTAssertEqual(["b.swift"], Set(lsrv.files(withExtension: "swift").map{ $0.relative(to: tmpdir) }))
+        XCTAssertEqual(["c"], Set(lsrv.files(withExtension: "").map{ $0.relative(to: tmpdir) }))
+        XCTAssertEqual(paths, ["a", "b.swift", "c", ".d"])
         
     }
 
@@ -69,6 +75,18 @@ class PathTests: XCTestCase {
         XCTAssert((Path.root/"bin").isDirectory)
     }
 
+    func testExtension() {
+        XCTAssertEqual(Path.root.join("a.swift").extension, "swift")
+        XCTAssertEqual(Path.root.join("a").extension, "")
+        XCTAssertEqual(Path.root.join("a.").extension, "")
+        XCTAssertEqual(Path.root.join("a..").extension, "")
+        XCTAssertEqual(Path.root.join("a..swift").extension, "swift")
+        XCTAssertEqual(Path.root.join("a..swift.").extension, "")
+        XCTAssertEqual(Path.root.join("a.tar.gz").extension, "tar.gz")
+        XCTAssertEqual(Path.root.join("a..tar.gz").extension, "tar.gz")
+        XCTAssertEqual(Path.root.join("a..tar..gz").extension, "gz")
+    }
+
     func testMktemp() throws {
         var path: Path!
         try Path.mktemp {
@@ -139,13 +157,50 @@ class PathTests: XCTestCase {
         XCTAssertEqual(Path.root/"a/foo"/"../../../bar", Path.root/"bar")
     }
 
+    func testDynamicMember() {
+        XCTAssertEqual(Path.root.Documents, Path.root/"Documents")
+
+        let a = Path.home.foo
+        XCTAssertEqual(a.Documents, Path.home/"foo/Documents")
+    }
+
     func testCopyInto() throws {
+        try Path.mktemp { root1 in
+            let bar1 = try root1.join("bar").touch()
+            try Path.mktemp { root2 in
+                let bar2 = try root2.join("bar").touch()
+                XCTAssertThrowsError(try bar1.copy(into: root2))
+                try bar1.copy(into: root2, overwrite: true)
+                XCTAssertTrue(bar1.exists)
+                XCTAssertTrue(bar2.exists)
+            }
+        }
+    }
+
+    func testMoveInto() throws {
+        try Path.mktemp { root1 in
+            let bar1 = try root1.join("bar").touch()
+            try Path.mktemp { root2 in
+                let bar2 = try root2.join("bar").touch()
+                XCTAssertThrowsError(try bar1.move(into: root2))
+                try bar1.move(into: root2, overwrite: true)
+                XCTAssertFalse(bar1.exists)
+                XCTAssertTrue(bar2.exists)
+            }
+        }
+    }
+
+    func testRename() throws {
         try Path.mktemp { root in
-            let bar = try root.join("bar").touch()
+            do {
-            try Path.mktemp { root in
+                let file = try root.bar.touch()
-                try root.join("bar").touch()
+                let foo = try file.rename("foo")
-                XCTAssertThrowsError(try bar.copy(into: root))
+                XCTAssertFalse(file.exists)
-                try bar.copy(into: root, overwrite: true)
+                XCTAssertTrue(foo.isFile)
+            }
+            do {
+                let file = try root.bar.touch()
+                XCTAssertThrowsError(try file.rename("foo"))
             }
         }
     }

Tests/PathTests/XCTestManifests.swift

@@ -6,15 +6,19 @@ extension PathTests {
         ("testCodable", testCodable),
         ("testConcatenation", testConcatenation),
         ("testCopyInto", testCopyInto),
+        ("testDynamicMember", testDynamicMember),
         ("testEnumeration", testEnumeration),
         ("testEnumerationSkippingHiddenFiles", testEnumerationSkippingHiddenFiles),
         ("testExists", testExists),
+        ("testExtension", testExtension),
         ("testIsDirectory", testIsDirectory),
         ("testJoin", testJoin),
         ("testMkpathIfExists", testMkpathIfExists),
         ("testMktemp", testMktemp),
+        ("testMoveInto", testMoveInto),
         ("testRelativePathCodable", testRelativePathCodable),
         ("testRelativeTo", testRelativeTo),
+        ("testRename", testRename),
     ]
 }