Fix CI deploy

* Update linux-tests; fail if warnings on travis

* Fix warnings on Linux

* Typo

* Can’t test these on Linux

.github/deploy

@@ -1,168 +0,0 @@
-#!/usr/bin/swift sh
-import func Darwin.fputs
-import var Darwin.stderr
-import PMKFoundation  // PromiseKit/Foundation ~> 3.3
-import LegibleError   // @mxcl ~> 1.0
-import Foundation
-import PromiseKit     // @mxcl ~> 6.8
-import Path           // mxcl/Path.swift ~> 0.15
-
-let env = ProcessInfo.processInfo.environment
-let token = env["GITHUB_TOKEN"] ?? env["GITHUB_ACCESS_TOKEN"]!
-let slug = env["TRAVIS_REPO_SLUG"]!
-let tag = env["TRAVIS_TAG"]!
-
-func fatal(message: String) -> Never {
-    fputs("error: \(message)\n", stderr)
-    exit(1)
-}
-func fatal(error: Error) -> Never {
-    fatal(message: "\(error.legibleLocalizedDescription)\n\n\(error.legibleDescription)")
-}
-
-struct Repo: Decodable {
-    let description: String
-    let license: License
-    struct License: Decodable {
-        let spdx_id: String
-    }
-}
-
-struct Package: Decodable {
-    let swiftLanguageVersions: [String]
-    let targets: [Target]
-    struct Target: Decodable {
-        let path: String?
-        let type: Kind
-        enum Kind: String, Decodable {
-            case regular
-            case test
-        }
-    }
-}
-
-extension URLRequest {
-    init(github path: String) {
-        let url = URL(string: "https://api.github.com\(path)")!
-        self.init(url: url)
-        setValue("token \(token)", forHTTPHeaderField: "Authorization")
-        setValue("application/json", forHTTPHeaderField: "Content-Type")
-        setValue("application/json", forHTTPHeaderField: "Accept")
-    }
-}
-
-func description() -> Promise<Repo> {
-    let rq = URLRequest(github: "/repos/\(slug)")
-    return firstly {
-        URLSession.shared.dataTask(.promise, with: rq).validate()
-    }.map { data, _ in
-        try JSONDecoder().decode(Repo.self, from: data)
-    }
-}
-
-struct User: Decodable {
-    let name: String
-    let email: String
-}
-
-func email() -> Promise<User> {
-    let rq = URLRequest(github: "/user")
-    return firstly {
-        URLSession.shared.dataTask(.promise, with: rq).validate()
-    }.map { data, _ in
-        try JSONDecoder().decode(User.self, from: data)
-    }
-}
-
-func dumpPackage() -> Promise<Package> {
-    let task = Process()
-    task.launchPath = "/usr/bin/swift"
-    task.arguments = ["package", "dump-package"]
-    return firstly {
-        task.launch(.promise)
-    }.map { out, _ in
-        out.fileHandleForReading.readDataToEndOfFile()
-    }.map { data in
-        try JSONDecoder().decode(Package.self, from: data)
-    }
-}
-
-var defaultSwiftVersion: String {
-    let task = Process()
-    task.launchPath = "/usr/bin/swift"
-    task.arguments = ["--version"]
-
-    func extract(input: String) -> String {
-        let range = input.range(of: #"Apple Swift version \d+\.\d+"#, options: .regularExpression)!
-        return String(input[range].split(separator: " ").last!)
-    }
-
-    return try! firstly {
-        task.launch(.promise)
-    }.compactMap { out, _ in
-        String(data: out.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8)
-    }.map { out in
-        extract(input: out)
-    }.wait()
-}
-
-func podspec(repo: Repo, user: User, pkg: Package) -> (Substring, String) {
-    let (owner, name) = { ($0[0], $0[1]) }(slug.split(separator: "/"))
-    let swiftVersion = pkg.swiftLanguageVersions.min() ?? defaultSwiftVersion
-    let targets = pkg.targets.filter{ $0.type == .regular }
-    guard targets.count == 1 else { fatal(message: "Too many targets for this script!") }
-    guard let sources = targets[0].path else { fatal(message: "Target has no path!") }
-    return (name, """
-    Pod::Spec.new do |s|
-      s.name = '\(name)'
-      s.author = { '\(user.name)': '\(user.email)' }
-      s.source = { git: "https://github.com/\(slug).git", tag: '\(tag)' }
-      s.version = '\(tag)'
-      s.summary = '\(repo.description)'
-      s.license = '\(repo.license.spdx_id)'
-      s.homepage = "https://github.com/\(slug)"
-      s.social_media_url = 'https://twitter.com/\(owner)'
-      s.osx.deployment_target = '10.10'
-      s.ios.deployment_target = '8.0'
-      s.tvos.deployment_target = '9.0'
-      s.watchos.deployment_target = '2.0'
-      s.source_files = '\(sources)/*.swift'
-      s.swift_version = '\(swiftVersion)'
-    end
-    """)
-}
-
-func publishRelease() throws -> Promise<Void> {
-    struct Input: Encodable {
-        let tag_name = tag
-        let name = tag
-        let body = ""
-    }
-
-    var rq = URLRequest(github: "/repos/\(slug)/releases")
-    rq.httpMethod = "POST"
-    rq.httpBody = try JSONEncoder().encode(Input())
-    return URLSession.shared.dataTask(.promise, with: rq).validate().asVoid()
-}
-
-switch CommandLine.arguments[1] {
-case "generate-podspec":
-    firstly {
-        when(fulfilled: description(), email(), dumpPackage())
-    }.map(podspec).done { name, podspec in
-        try podspec.write(toFile: "\(name).podspec", atomically: false, encoding: .utf8)
-        exit(0)
-    }.catch {
-        fatal(error: $0)
-    }
-case "publish-release":
-    try publishRelease().done {
-        exit(0)
-    }.catch {
-        fatal(error: $0)
-    }
-default:
-    fatal(message: "invalid usage")
-}
-
-RunLoop.main.run()

.github/jazzy.yml

@@ -3,7 +3,7 @@ custom_categories:
   - name: Path
     children:
       - Path
-      - /(_:_:)
+      - Pathish
 xcodebuild_arguments:
   - UseModernBuildSystem=NO
 output:

.gitignore

@@ -3,3 +3,4 @@
 /*.xcodeproj
 /build
 /docs
+/.swiftpm

.travis.yml

@@ -1,11 +1,15 @@
 # only run for: merge commits, releases and pull-requests
-if: type != push OR branch = master OR branch =~ /^\d+\.\d+(\.\d+)?(-\S*)?$/
+if: type != push OR branch = master OR branch =~ /^deploy-\d+\.\d+\.\d+(-.*)?$/ OR branch =~ /^\d+\.\d+\.\d+(-.*)?$/
 
 stages:
   - name: pretest
+    if: NOT branch =~ /^deploy-\d+\.\d+\.\d+(-.*)?$/
   - name: test
+    if: NOT branch =~ /^deploy-\d+\.\d+\.\d+(-.*)?$/
   - name: deploy
-    if: branch =~ ^\d+\.\d+\.\d+$
+    if: branch =~ /^deploy-\d+\.\d+\.\d+(-.*)?$/
+  - name: publish
+    if: branch =~ /^\d+\.\d+\.\d+(-.*)?$/
 
 os: osx
 language: swift
@@ -16,14 +20,21 @@ xcode_scheme: Path.swift-Package
 jobs:
   include:
     - name: macOS / Swift 4.0.3
+      before_script: swift build -Xswiftc -warnings-as-errors
       script: swift test --parallel -Xswiftc -swift-version -Xswiftc 4
 
-    - name: macOS / Swift 4.2.1
+    - &std
+      name: macOS / Swift 4.2.1
+      before_script: swift build -Xswiftc -warnings-as-errors
       script: swift test --parallel
 
-    - name: macOS / Swift 5.0
+    - <<: *std
+      name: macOS / Swift 5.0
       osx_image: xcode10.2
-      script: swift test --parallel
+
+    - <<: *std
+      name: macOS / Swift 5.1
+      osx_image: xcode11
 
     - &xcodebuild
       before_install: swift package generate-xcodeproj --enable-code-coverage
@@ -47,18 +58,26 @@ jobs:
       after_success: false
 
     - &linux
-      env: SWIFT_VERSION=4.2.1
+      env: SWIFT_VERSION=4.2.4
       os: linux
-      name: Linux / Swift 4.2.1
+      name: Linux / Swift 4.2.4
       language: generic
-      dist: trusty
       sudo: false
       install: eval "$(curl -sL https://swiftenv.fuller.li/install.sh)"
+      before_script: swift build -Xswiftc -warnings-as-errors
       script: swift test --parallel
 
     - <<: *linux
-      env: SWIFT_VERSION='5.0-DEVELOPMENT-SNAPSHOT-2019-01-22-a'
+      env: SWIFT_VERSION=5.0.3
-      name: Linux / Swift 5.0.0-dev+2019.01.22
+      name: Linux / Swift 5.0.3
+
+    - <<: *linux
+      env: SWIFT_VERSION=5.1.3
+      name: Linux / Swift 5.1.3
+      
+    - <<: *linux
+      env: SWIFT_VERSION=5.2-DEVELOPMENT-SNAPSHOT-2020-01-22-a
+      name: Linux / Swift 5.2.0-dev+2020-01-22-a
 
     - stage: pretest
       name: Check Linux tests are sync’d
@@ -67,7 +86,23 @@ jobs:
       osx_image: xcode10.2
 
     - stage: deploy
+      name: Deploy
+      osx_image: xcode11
+      env: HOMEBREW_NO_INSTALL_CLEANUP=1
+      install: brew install mxcl/made/swift-sh
+      script:
+        - set -e
+        - export VERSION=$(echo $TRAVIS_TAG | cut -c 8-)
+        - git tag "$VERSION"
+        - git remote set-url origin "https://$GITHUB_TOKEN@github.com/$TRAVIS_REPO_SLUG.git"
+        - git fetch --unshallow origin
+        - git push origin "$VERSION"
+        - swift sh <(curl https://raw.githubusercontent.com/mxcl/ops/master/deploy) publish-release
+        - git push origin :$TRAVIS_TAG
+
+    - stage: publish
       name: Jazzy
+      osx_image: xcode10.2
       install: gem install jazzy
       before_script: swift package generate-xcodeproj
       script: |
@@ -84,7 +119,10 @@ jobs:
 
     - name: CocoaPods
       osx_image: xcode10.2
-      install: brew install mxcl/made/swift-sh
+      install: |
-      before_script: .github/deploy generate-podspec
+        brew install mxcl/made/swift-sh
+        curl -O https://raw.githubusercontent.com/mxcl/ops/master/deploy
+        chmod u+x deploy
+      before_script: ./deploy generate-podspec
       script: pod trunk push
-      after_success: .github/deploy publish-release
+      after_success: ./deploy publish-release

Package.swift

@@ -1,7 +1,7 @@
 // swift-tools-version:4.2
 import PackageDescription
 
-let pkg = Package(
+let package = Package(
     name: "Path.swift",
     products: [
         .library(name: "Path", targets: ["Path"]),

README.md

@@ -32,7 +32,7 @@ let foo = try Path.root.join("foo").copy(into: Path.root.join("bar").mkdir())
 print(foo)         // => /bar/foo
 print(foo.isFile)  // => true
 
-// we support dynamic members (_use_sparingly_):
+// we support dynamic-member-syntax when joining named static members, eg:
 let prefs = Path.home.Library.Preferences  // => /Users/mxcl/Library/Preferences
 
 // a practical example: installing a helper executable
@@ -44,10 +44,8 @@ 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
+Hi, I’m Max Howell and I have written a lot of open source software—generally
-probably you already use some of it (Homebrew anyone?). I work full-time on
+a good deal of my free time 👨🏻‍💻.
-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">
@@ -107,10 +105,11 @@ We support `@dynamicMemberLookup`:
 let ls = Path.root.usr.bin.ls  // => /usr/bin/ls
 ```
 
-This is less commonly useful than you would think, hence our documentation
+We only provide this for “starting” function, eg. `Path.home` or `Bundle.path`.
-does not use it. Usually you are joining variables or other `String` arguments
+This is because we found in practice it was easy to write incorrect code, since
-or trying to describe files (and files usually have extensions). However when
+everything would compile if we allowed arbituary variables to take *any* named
-you need it, it’s *lovely*.
+property as valid syntax. What we have is what you want most of the time but
+much less dangerous.
 
 ## Initializing from user-input
 
@@ -146,27 +145,61 @@ try Bundle.main.resources.join("foo").copy(to: .home)
 ## Directory listings
 
 We provide `ls()`, called because it behaves like the Terminal `ls` function,
-the name thus implies its behavior, ie. that it is not recursive.
+the name thus implies its behavior, ie. that it is not recursive and doesn’t
+list hidden files.
 
 ```swift
-for entry in Path.home.ls() {
+for path in Path.home.ls() {
-    print(entry.path)
-    print(entry.kind)  // .directory or .file
-}
-
-for entry in Path.home.ls() where entry.kind == .file {
     //…
 }
 
-for entry in Path.home.ls() where entry.path.mtime > yesterday {
+for path in Path.home.ls() where path.isFile {
+    //…
+}
+
+for path in Path.home.ls() where path.mtime > yesterday {
     //…
 }
 
 let dirs = Path.home.ls().directories
+// ^^ directories that *exist*
 
 let files = Path.home.ls().files
+// ^^ files that both *exist* and are *not* directories
 
-let swiftFiles = Path.home.ls().files(withExtension: "swift")
+let swiftFiles = Path.home.ls().files.filter{ $0.extension == "swift" }
+```
+
+We provide `find()` for recursive listing:
+
+```swift
+Path.home.find().execute { path in
+    //…
+}
+```
+
+Which is configurable:
+
+```swift
+Path.home.find().depth(max: 1).extension("swift").type(.file) { path in
+    //…
+}
+```
+
+And can be controlled:
+
+```swift
+Path.home.find().execute { path in
+    guard foo else { return .skip }
+    guard bar else { return .abort }
+    return .continue
+}
+```
+
+Or just get all paths at once:
+
+```swift
+let paths = Path.home.find().execute()
 ```
 
 # `Path.swift` is robust
@@ -258,9 +291,15 @@ for that as the check was deemed too expensive to be worthwhile.
     equality check is required.
 * There are several symlink paths on Mac that are typically automatically
     resolved by Foundation, eg. `/private`, we attempt to do the same for
-    functions that you would expect it (notably `realpath`), but we do *not* for
+    functions that you would expect it (notably `realpath`), we *do* the same for
-    `Path.init`, *nor* if you are joining a path that ends up being one of these
+    `Path.init`, but *do not* if you are joining a path that ends up being one of
-    paths, (eg. `Path.root.join("var/private')`).
+    these paths, (eg. `Path.root.join("var/private')`).
+
+If a `Path` is a symlink but the destination of the link does not exist `exists`
+returns `false`. This seems to be the correct thing to do since symlinks are
+meant to be an abstraction for filesystems. To instead verify that there is
+no filesystem entry there at all check if `type` is `nil`.
+
 
 ## We do not provide change directory functionality
 
@@ -296,28 +335,19 @@ actual filesystem path, however we also check the URL has a `file` scheme first.
 SwiftPM:
 
 ```swift
-package.append(.package(url: "https://github.com/mxcl/Path.swift.git", from: "0.13.0"))
+package.append(.package(url: "https://github.com/mxcl/Path.swift.git", from: "1.0.0"))
 ```
 
 CocoaPods:
 
 ```ruby
-pod 'Path.swift', '~> 0.13'
+pod 'Path.swift', '~> 1.0.0'
 ```
 
 Carthage:
 
 > Waiting on: [@Carthage#1945](https://github.com/Carthage/Carthage/pull/1945).
 
-## Pre‐1.0 status
-
-We are pre 1.0, thus we can change the API as we like, and we will (to the
-pursuit of getting it *right*)! We will tag 1.0 as soon as possible.
-
-### Get push notifications for new releases
-
-https://mxcl.dev/canopy/
-
 # Alternatives
 
 * [Pathos](https://github.com/dduan/Pathos) by Daniel Duan
@@ -327,7 +357,7 @@ https://mxcl.dev/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
+[badge-languages]: https://img.shields.io/badge/swift-4.2%20%7C%205.0%20%7C%205.1%20%7C%205.2-orange.svg
 [docs]: https://mxcl.dev/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

Sources/Extensions.swift

@@ -13,31 +13,31 @@ public extension Bundle {
      Returns the path for the shared-frameworks directory in this bundle.
      - Note: This is typically `ShareFrameworks`
     */
-    var sharedFrameworks: Path {
+    var sharedFrameworks: DynamicPath {
-        return sharedFrameworksPath.flatMap(Path.init) ?? defaultSharedFrameworksPath
+        return sharedFrameworksPath.flatMap(DynamicPath.init) ?? defaultSharedFrameworksPath
     }
 
     /**
      Returns the path for the private-frameworks directory in this bundle.
      - Note: This is typically `Frameworks`
     */
-    var privateFrameworks: Path {
+    var privateFrameworks: DynamicPath {
-        return privateFrameworksPath.flatMap(Path.init) ?? defaultSharedFrameworksPath
+        return privateFrameworksPath.flatMap(DynamicPath.init) ?? defaultSharedFrameworksPath
     }
 
     /// Returns the path for the resources directory in this bundle.
-    var resources: Path {
+    var resources: DynamicPath {
-        return resourcePath.flatMap(Path.init) ?? defaultResourcesPath
+        return resourcePath.flatMap(DynamicPath.init) ?? defaultResourcesPath
     }
 
     /// Returns the path for this bundle.
-    var path: Path {
+    var path: DynamicPath {
-        return Path(string: bundlePath)
+        return DynamicPath(string: bundlePath)
     }
     
     /// Returns the executable for this bundle, if there is one, not all bundles have one hence `Optional`.
-    var executable: Path? {
+    var executable: DynamicPath? {
-        return executablePath.flatMap(Path.init)
+        return executablePath.flatMap(DynamicPath.init)
     }
 }
 
@@ -45,14 +45,14 @@ public extension Bundle {
 public extension String {
     /// Initializes this `String` with the contents of the provided path.
     @inlinable
-    init(contentsOf path: Path) throws {
+    init<P: Pathish>(contentsOf path: P) throws {
         try self.init(contentsOfFile: path.string)
     }
 
     /// - Returns: `to` to allow chaining
     @inlinable
     @discardableResult
-    func write(to: Path, atomically: Bool = false, encoding: String.Encoding = .utf8) throws -> Path {
+    func write<P: Pathish>(to: P, atomically: Bool = false, encoding: String.Encoding = .utf8) throws -> P {
         try write(toFile: to.string, atomically: atomically, encoding: encoding)
         return to
     }
@@ -62,14 +62,14 @@ public extension String {
 public extension Data {
     /// Initializes this `Data` with the contents of the provided path.
     @inlinable
-    init(contentsOf path: Path) throws {
+    init<P: Pathish>(contentsOf path: P) throws {
         try self.init(contentsOf: path.url)
     }
 
     /// - Returns: `to` to allow chaining
     @inlinable
     @discardableResult
-    func write(to: Path, atomically: Bool = false) throws -> Path {
+    func write<P: Pathish>(to: P, atomically: Bool = false) throws -> P {
         let opts: NSData.WritingOptions
         if atomically {
         #if !os(Linux)
@@ -89,39 +89,39 @@ public extension Data {
 public extension FileHandle {
     /// Initializes this `FileHandle` for reading at the location of the provided path.
     @inlinable
-    convenience init(forReadingAt path: Path) throws {
+    convenience init<P: Pathish>(forReadingAt path: P) 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 {
+    convenience init<P: Pathish>(forWritingAt path: P) 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 {
+    convenience init<P: Pathish>(forUpdatingAt path: P) throws {
         try self.init(forUpdating: path.url)
     }
 }
 
 internal extension Bundle {
-    var defaultSharedFrameworksPath: Path {
+    var defaultSharedFrameworksPath: DynamicPath {
       #if os(macOS)
-        return path.join("Contents/Frameworks")
+        return path.Contents.Frameworks
       #elseif os(Linux)
-        return path.join("lib")
+        return path.lib
       #else
-        return path.join("Frameworks")
+        return path.Frameworks
       #endif
     }
 
-    var defaultResourcesPath: Path {
+    var defaultResourcesPath: DynamicPath {
       #if os(macOS)
-        return path.join("Contents/Resources")
+        return path.Contents.Resources
       #elseif os(Linux)
-        return path.join("share")
+        return path.share
       #else
         return path
       #endif

Sources/Path+Attributes.swift

@@ -1,6 +1,6 @@
 import Foundation
 
-public extension Path {
+public extension Pathish {
     //MARK: Filesystem Attributes
 
     /**
@@ -30,6 +30,29 @@ public extension Path {
         }
     }
 
+    /// The type of the entry.
+    /// - SeeAlso: `Path.EntryType`
+    @available(*, deprecated, message: "- SeeAlso: Path.type")
+    var kind: Path.EntryType? {
+        return type
+    }
+
+    /// The type of the entry.
+    /// - SeeAlso: `Path.EntryType`
+    var type: Path.EntryType? {
+        var buf = stat()
+        guard lstat(string, &buf) == 0 else {
+            return nil
+        }
+        if buf.st_mode & S_IFMT == S_IFLNK {
+            return .symlink
+        } else if buf.st_mode & S_IFMT == S_IFDIR {
+            return .directory
+        } else {
+            return .file
+        }
+    }
+
     /**
      Sets the file’s attributes using UNIX octal notation.
 
@@ -38,9 +61,11 @@ public extension Path {
     @discardableResult
     func chmod(_ octal: Int) throws -> Path {
         try FileManager.default.setAttributes([.posixPermissions: octal], ofItemAtPath: string)
-        return self
+        return Path(self)
     }
 
+    //MARK: Filesystem Locking
+    
     /**
      Applies the macOS filesystem “lock” attribute.
      - Note: If file is already locked, does nothing.
@@ -57,7 +82,7 @@ public extension Path {
             try FileManager.default.setAttributes(attrs, ofItemAtPath: string)
         }
     #endif
-        return self
+        return Path(self)
     }
 
     /**
@@ -73,7 +98,7 @@ public extension Path {
         do {
             attrs = try FileManager.default.attributesOfItem(atPath: string)
         } catch CocoaError.fileReadNoSuchFile {
-            return self
+            return Path(self)
         }
         let b = attrs[.immutable] as? Bool ?? false
         if b {
@@ -81,6 +106,19 @@ public extension Path {
             try FileManager.default.setAttributes(attrs, ofItemAtPath: string)
         }
     #endif
-        return self
+        return Path(self)
+    }
+}
+
+/// The `extension` that provides `Kind`.
+public extension Path {
+    /// A filesystem entry’s kind, file, directory, symlink etc.
+    enum EntryType: CaseIterable {
+        /// The entry is a file.
+        case file
+        /// The entry is a symlink.
+        case symlink
+        /// The entry is a directory.
+        case directory
     }
 }

Sources/Path+Codable.swift

@@ -30,11 +30,12 @@ extension Path: Codable {
         let value = try decoder.singleValueContainer().decode(String.self)
         if value.hasPrefix("/") {
             string = value
-        } else {
+        } else if let root = decoder.userInfo[.relativePath] as? Path {
-            guard let root = decoder.userInfo[.relativePath] as? Path else {
-                throw DecodingError.dataCorrupted(.init(codingPath: [], debugDescription: "Path cannot decode a relative path if `userInfo[.relativePath]` not set to a Path object."))
-            }
             string = (root/value).string
+        } else if let root = decoder.userInfo[.relativePath] as? DynamicPath {
+            string = (root/value).string
+        } else {
+            throw DecodingError.dataCorrupted(.init(codingPath: [], debugDescription: "Path cannot decode a relative path if `userInfo[.relativePath]` not set to a Path object."))
         }
     }
 
@@ -44,6 +45,8 @@ extension Path: Codable {
         var container = encoder.singleValueContainer()
         if let root = encoder.userInfo[.relativePath] as? Path {
             try container.encode(relative(to: root))
+        } else if let root = encoder.userInfo[.relativePath] as? DynamicPath {
+            try container.encode(relative(to: root))
         } else {
             try container.encode(string)
         }

Sources/Path+CommonDirectories.swift

@@ -1,20 +1,21 @@
 import Foundation
 
+/// The `extension` that provides static properties that are common directories.
 extension Path {
     //MARK: Common Directories
 
     /// Returns a `Path` containing `FileManager.default.currentDirectoryPath`.
-    public static var cwd: Path {
+    public static var cwd: DynamicPath {
-        return Path(string: FileManager.default.currentDirectoryPath)
+        return .init(string: FileManager.default.currentDirectoryPath)
     }
 
     /// Returns a `Path` representing the root path.
-    public static var root: Path {
+    public static var root: DynamicPath {
-        return Path(string: "/")
+        return .init(string: "/")
     }
 
     /// Returns a `Path` representing the user’s home directory
-    public static var home: Path {
+    public static var home: DynamicPath {
         let string: String
       #if os(macOS)
         if #available(OSX 10.12, *) {
@@ -25,30 +26,30 @@ extension Path {
       #else
         string = NSHomeDirectory()
       #endif
-        return Path(string: string)
+        return .init(string: string)
     }
 
     /// Helper to allow search path and domain mask to be passed in.
-    private static func path(for searchPath: FileManager.SearchPathDirectory) -> Path {
+    private static func path(for searchPath: FileManager.SearchPathDirectory) -> DynamicPath {
     #if os(Linux)
         // the urls(for:in:) function is not implemented on Linux
         //TODO strictly we should first try to use the provided binary tool
 
-        let foo = { ProcessInfo.processInfo.environment[$0].flatMap(Path.init) ?? $1 }
+        let foo = { ProcessInfo.processInfo.environment[$0].flatMap(Path.init).map(DynamicPath.init) ?? $1 }
 
         switch searchPath {
         case .documentDirectory:
-            return Path.home/"Documents"
+            return Path.home.Documents
         case .applicationSupportDirectory:
-            return foo("XDG_DATA_HOME", Path.home/".local/share")
+            return foo("XDG_DATA_HOME", Path.home[dynamicMember: ".local/share"])
         case .cachesDirectory:
-            return foo("XDG_CACHE_HOME", Path.home/".cache")
+            return foo("XDG_CACHE_HOME", Path.home[dynamicMember: ".cache"])
         default:
             fatalError()
         }
     #else    
         guard let pathString = FileManager.default.urls(for: searchPath, in: .userDomainMask).first?.path else { return defaultUrl(for: searchPath) }
-        return Path(string: pathString)
+        return DynamicPath(string: pathString)
     #endif
     }
 
@@ -57,7 +58,7 @@ extension Path {
      - Note: There is no standard location for documents on Linux, thus we return `~/Documents`.
      - Note: You should create a subdirectory before creating any files.
      */
-    public static var documents: Path {
+    public static var documents: DynamicPath {
         return path(for: .documentDirectory)
     }
 
@@ -66,7 +67,7 @@ extension Path {
      - Note: On Linux this is `XDG_CACHE_HOME`.
      - Note: You should create a subdirectory before creating any files.
      */
-    public static var caches: Path {
+    public static var caches: DynamicPath {
         return path(for: .cachesDirectory)
     }
 
@@ -75,20 +76,20 @@ extension Path {
      - Note: On Linux is `XDG_DATA_HOME`.
      - Note: You should create a subdirectory before creating any files.
      */
-    public static var applicationSupport: Path {
+    public static var applicationSupport: DynamicPath {
         return path(for: .applicationSupportDirectory)
     }
 }
 
 #if !os(Linux)
-func defaultUrl(for searchPath: FileManager.SearchPathDirectory) -> Path {
+func defaultUrl(for searchPath: FileManager.SearchPathDirectory) -> DynamicPath {
     switch searchPath {
     case .documentDirectory:
-        return Path.home/"Documents"
+        return Path.home.Documents
     case .applicationSupportDirectory:
-        return Path.home/"Library/Application Support"
+        return Path.home.Library[dynamicMember: "Application Support"]
     case .cachesDirectory:
-        return Path.home/"Library/Caches"
+        return Path.home.Library.Caches
     default:
         fatalError()
     }

Sources/Path+FileManager.swift

@@ -3,7 +3,8 @@ import Foundation
 import Glibc
 #endif
 
-public extension Path {
+public extension Pathish {
+
     //MARK: File Management
 
     /**
@@ -24,17 +25,17 @@ public extension Path {
      - SeeAlso: `copy(into:overwrite:)`
      */
     @discardableResult
-    func copy(to: Path, overwrite: Bool = false) throws -> Path {
+    func copy<P: Pathish>(to: P, overwrite: Bool = false) throws -> Path {
-        if overwrite, to.isFile, isFile {
+        if overwrite, let tokind = to.type, tokind != .directory, type != .directory {
             try FileManager.default.removeItem(at: to.url)
         }
-    #if os(Linux) && !swift(>=5.1) // check if fixed
+    #if os(Linux) && !swift(>=5.3) // check if fixed
-        if !overwrite, to.isFile {
+        if !overwrite, to.type != nil {
             throw CocoaError.error(.fileWriteFileExists)
         }
     #endif
         try FileManager.default.copyItem(atPath: string, toPath: to.string)
-        return to
+        return Path(to)
     }
 
     /**
@@ -60,16 +61,16 @@ public extension Path {
      - SeeAlso: `copy(to:overwrite:)`
      */
     @discardableResult
-    func copy(into: Path, overwrite: Bool = false) throws -> Path {
+    func copy<P: Pathish>(into: P, overwrite: Bool = false) throws -> Path {
-        if !into.exists {
+        if into.type == nil {
             try into.mkdir(.p)
         }
         let rv = into/basename()
-        if overwrite, rv.isFile {
+        if overwrite, let kind = rv.type, kind != .directory {
-            try rv.delete()
+            try FileManager.default.removeItem(at: rv.url)
         }
-    #if os(Linux) && !swift(>=5.1) // check if fixed
+    #if os(Linux) && !swift(>=5.3) // check if fixed
-        if !overwrite, rv.isFile {
+        if !overwrite, rv.type != nil {
             throw CocoaError.error(.fileWriteFileExists)
         }
     #endif
@@ -94,12 +95,12 @@ public extension Path {
      - SeeAlso: `move(into:overwrite:)`
      */
     @discardableResult
-    func move(to: Path, overwrite: Bool = false) throws -> Path {
+    func move<P: Pathish>(to: P, overwrite: Bool = false) throws -> Path {
-        if overwrite, to.isFile {
+        if overwrite, let kind = to.type, kind != .directory {
             try FileManager.default.removeItem(at: to.url)
         }
         try FileManager.default.moveItem(at: url, to: to.url)
-        return to
+        return Path(to)
     }
 
     /**
@@ -118,18 +119,22 @@ public extension Path {
      - SeeAlso: `move(to:overwrite:)`
      */
     @discardableResult
-    func move(into: Path, overwrite: Bool = false) throws -> Path {
+    func move<P: Pathish>(into: P, overwrite: Bool = false) throws -> Path {
-        if !into.exists {
+        switch into.type {
+        case nil:
             try into.mkdir(.p)
-        } else if !into.isDirectory {
+            fallthrough
-            throw CocoaError.error(.fileWriteFileExists)
+        case .directory?:
-        }
             let rv = into/basename()
-        if overwrite, rv.isFile {
+            if overwrite, let rvkind = rv.type, rvkind != .directory {
                 try FileManager.default.removeItem(at: rv.url)
             }
             try FileManager.default.moveItem(at: url, to: rv.url)
             return rv
+        case .file?, .symlink?:
+            throw CocoaError.error(.fileWriteFileExists)
+        }
+
     }
 
     /**
@@ -138,23 +143,24 @@ public extension Path {
      ∵ *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”
+     - Note: If entry is a symlink, deletes the symlink.
      - SeeAlso: `lock()`
     */
     @inlinable
     func delete() throws {
-        if exists {
+        if type != nil {
             try FileManager.default.removeItem(at: url)
         }
     }
 
     /**
      Creates an empty file at this path or if the file exists, updates its modification time.
-     - Returns: `self` to allow chaining.
+     - Returns: A copy of `self` to allow chaining.
      */
     @inlinable
     @discardableResult
     func touch() throws -> Path {
-        if !exists {
+        if type == nil {
             guard FileManager.default.createFile(atPath: string, contents: nil) else {
                 throw CocoaError.error(.fileWriteUnknown)
             }
@@ -167,7 +173,7 @@ public extension Path {
             try FileManager.default.setAttributes([.modificationDate: Date()], ofItemAtPath: string)
         #endif
         }
-        return self
+        return Path(self)
     }
 
     /**
@@ -175,7 +181,7 @@ public extension Path {
      - 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.
+     - Returns: A copy of `self` to allow chaining.
      */
     @discardableResult
     func mkdir(_ options: MakeDirectoryOptions? = nil) throws -> Path {
@@ -194,11 +200,11 @@ public extension Path {
             throw error
         #endif
         }
-        return self
+        return Path(self)
     }
 
     /**
-     Renames the file at path.
+     Renames the file (basename only) at path.
 
          Path.root.foo.bar.rename(to: "baz")  // => /foo/baz
 
@@ -217,9 +223,9 @@ public extension Path {
      - Note: If `self` does not exist, is **not** an error.
      */
     @discardableResult
-    func symlink(as: Path) throws -> Path {
+    func symlink<P: Pathish>(as: P) throws -> Path {
         try FileManager.default.createSymbolicLink(atPath: `as`.string, withDestinationPath: string)
-        return `as`
+        return Path(`as`)
     }
 
     /**
@@ -227,15 +233,18 @@ public extension Path {
      - Note: If into does not exist, creates the directory with intermediate directories if necessary.
      */
     @discardableResult
-    func symlink(into dir: Path) throws -> Path {
+    func symlink<P: Pathish>(into dir: P) throws -> Path {
-        if !dir.exists {
+        switch dir.type {
+        case nil, .symlink?:
             try dir.mkdir(.p)
-        } else if !dir.isDirectory {
+            fallthrough
-            throw CocoaError.error(.fileWriteFileExists)
+        case .directory?:
-        }
             let dst = dir/basename()
             try FileManager.default.createSymbolicLink(atPath: dst.string, withDestinationPath: string)
             return dst
+        case .file?:
+            throw CocoaError.error(.fileWriteFileExists)
+        }
     }
 }
 

Sources/Path+StringConvertibles.swift

@@ -11,3 +11,17 @@ extension Path: CustomDebugStringConvertible {
         return "Path(\(string))"
     }
 }
+
+extension DynamicPath: CustomStringConvertible {
+    /// Returns `Path.string`
+    public var description: String {
+        return string
+    }
+}
+
+extension DynamicPath: CustomDebugStringConvertible {
+    /// Returns eg. `Path(string: "/foo")`
+    public var debugDescription: String {
+        return "Path(\(string))"
+    }
+}

Sources/Path+ls.swift

@@ -1,67 +1,197 @@
 import Foundation
 
-/**
- 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
+    /// The builder for `Path.find()`
+    class Finder {
+        fileprivate init(path: Path) {
+            self.path = path
+            self.enumerator = FileManager.default.enumerator(atPath: path.string)
+        }
 
-    /**
+        /// The `path` find operations operate on.
-     Same as the `ls -a` command ∴ output is ”shallow” and unsorted.
+        public let path: Path
-     - Parameter includeHiddenFiles: If `true`, hidden files are included in the results. Defaults to `true`.
+
-     - Important: `includeHiddenFiles` does not work on Linux
+        private let enumerator: FileManager.DirectoryEnumerator!
-     */
+
-    func ls(includeHiddenFiles: Bool = true) throws -> [Entry] {
+        /// The range of directory depths for which the find operation will return entries.
-        var opts = FileManager.DirectoryEnumerationOptions()
+        private(set) public var depth: ClosedRange<Int> = 1...Int.max
-    #if !os(Linux)
+
-        if !includeHiddenFiles {
+        /// The kinds of filesystem entries find operations will return.
-            opts.insert(.skipsHiddenFiles)
+        public var types: Set<EntryType> {
+            return _types ?? Set(EntryType.allCases)
+        }
+
+        private var _types: Set<EntryType>?
+
+        /// The file extensions find operations will return. Files *and* directories unless you filter for `kinds`.
+        private(set) public var extensions: Set<String>?
+    }
+}
+
+extension Path.Finder: Sequence, IteratorProtocol {
+    public func next() -> Path? {
+        guard let enumerator = enumerator else {
+            return nil
+        }
+        while let relativePath = enumerator.nextObject() as? String {
+            let path = self.path/relativePath
+
+          #if !os(Linux) || swift(>=5.0)
+            if enumerator.level > depth.upperBound {
+                enumerator.skipDescendants()
+                continue
+            }
+            if enumerator.level < depth.lowerBound {
+                if path == self.path, depth.lowerBound == 0 {
+                    return path
+                } else {
+                    continue
+                }
             }
           #endif
-        let paths = try FileManager.default.contentsOfDirectory(at: url, includingPropertiesForKeys: nil, options: opts)
+
-        func convert(url: URL) -> Entry? {
+            if let type = path.type, !types.contains(type) { continue }
+            if let exts = extensions, !exts.contains(path.extension) { continue }
+            return path
+        }
+        return nil
+    }
+
+    public typealias Element = Path
+}
+
+public extension Path.Finder {
+    /// A max depth of `0` returns only the path we are searching, `1` is that directory’s listing.
+    func depth(max maxDepth: Int) -> Path.Finder {
+    #if os(Linux) && !swift(>=5.0)
+        fputs("warning: depth not implemented for Swift < 5\n", stderr)
+    #endif
+        depth = Swift.min(maxDepth, depth.lowerBound)...maxDepth
+        return self
+    }
+
+    /// A min depth of `0` also returns the path we are searching, `1` is that directory’s listing. Default is `1` thus not returning ourself.
+    func depth(min minDepth: Int) -> Path.Finder {
+      #if os(Linux) && !swift(>=5.0)
+        fputs("warning: depth not implemented for Swift < 5\n", stderr)
+      #endif
+        depth = minDepth...Swift.max(depth.upperBound, minDepth)
+        return self
+    }
+
+    /// A max depth of `0` returns only the path we are searching, `1` is that directory’s listing.
+    /// A min depth of `0` also returns the path we are searching, `1` is that directory’s listing. Default is `1` thus not returning ourself.
+    func depth(_ rng: Range<Int>) -> Path.Finder {
+      #if os(Linux) && !swift(>=5.0)
+        fputs("warning: depth not implemented for Swift < 5\n", stderr)
+      #endif
+        depth = rng.lowerBound...(rng.upperBound - 1)
+        return self
+    }
+
+    /// A max depth of `0` returns only the path we are searching, `1` is that directory’s listing.
+    /// A min depth of `0` also returns the path we are searching, `1` is that directory’s listing. Default is `1` thus not returning ourself.
+    func depth(_ rng: ClosedRange<Int>) -> Path.Finder {
+      #if os(Linux) && !swift(>=5.0)
+        fputs("warning: depth not implemented for Swift < 5\n", stderr)
+      #endif
+        depth = rng
+        return self
+    }
+
+    /// Multiple calls will configure the Finder with multiple kinds.
+    func type(_ type: Path.EntryType) -> Path.Finder {
+        _types = _types ?? []
+        _types!.insert(type)
+        return self
+    }
+
+    /// Multiple calls will configure the Finder with for multiple extensions
+    func `extension`(_ ext: String) -> Path.Finder {
+        extensions = extensions ?? []
+        extensions!.insert(ext)
+        return self
+    }
+
+    /// The return type for `Path.Finder`
+    enum ControlFlow {
+        /// Stop enumerating this directory, return to the parent.
+        case skip
+        /// Stop enumerating all together.
+        case abort
+        /// Keep going.
+        case `continue`
+    }
+
+    /// Enumerate, one file at a time.
+    func execute(_ closure: (Path) throws -> ControlFlow) rethrows {
+        while let path = next() {
+            switch try closure(path) {
+            case .skip:
+                enumerator.skipDescendants()
+            case .abort:
+                return
+            case .continue:
+                continue
+            }
+        }
+    }
+}
+
+public extension Pathish {
+
+    //MARK: Directory Listing
+
+    /**
+     Same as the `ls` command ∴ output is ”shallow” and unsorted.
+     - Note: as per `ls`, by default we do *not* return hidden files. Specify `.a` for hidden files.
+     - Parameter options: Configure the listing.
+     - Important: On Linux the listing is always `ls -a`
+     */
+    func ls(_ options: ListDirectoryOptions? = nil) -> [Path] {
+        guard let urls = try? FileManager.default.contentsOfDirectory(at: url, includingPropertiesForKeys: nil) else {
+            fputs("warning: could not list: \(self)\n", stderr)
+            return []
+        }
+        return urls.compactMap { url in
             guard let path = Path(url.path) else { return nil }
-            return Entry(kind: path.isDirectory ? .directory : .file, path: path)
+            if options != .a, path.basename().hasPrefix(".") { return nil }
-        }
+            // ^^ we don’t use the Foundation `skipHiddenFiles` because it considers weird things hidden and we are mirroring `ls`
-        return paths.compactMap(convert)
+            return path
         }
     }
 
-/// Convenience functions for the array return value of `Path.ls()`
+    /// Recursively find files under this path. If the path is a file, no files will be found.
-public extension Array where Element == Entry {
+    func find() -> Path.Finder {
-    /// Filters the list of entries to be a list of Paths that are directories.
+        return .init(path: Path(self))
+    }
+}
+
+/// Convenience functions for the arrays of `Path`
+public extension Array where Element == Path {
+    /// Filters the list of entries to be a list of Paths that are directories. Symlinks to directories are not returned.
     var directories: [Path] {
-        return compactMap {
+        return filter {
-            $0.kind == .directory ? $0.path : nil
+            $0.isDirectory
         }
     }
 
-    /// Filters the list of entries to be a list of Paths that are files.
+    /// Filters the list of entries to be a list of Paths that exist and are *not* directories. Thus expect symlinks, etc.
+    /// - Note: symlinks that point to files that do not exist are *not* returned.
     var files: [Path] {
-        return compactMap {
+        return filter {
-            $0.kind == .file ? $0.path : nil
+            switch $0.type {
+            case .none, .directory?:
+                return false
+            case .file?, .symlink?:
+                return true
+            }
+        }
     }
 }
 
-    /// Filters the list of entries to be a list of Paths that are files with the specified extension.
+/// Options for `Path.ls(_:)`
-    func files(withExtension ext: String) -> [Path] {
+public enum ListDirectoryOptions {
-        return compactMap {
+    /// Creates intermediary directories; works the same as `mkdir -p`.
-            $0.kind == .file && $0.path.extension == ext ? $0.path : nil
+    case a
-        }
-    }
 }

Sources/Path->Bool.swift

@@ -5,10 +5,15 @@ import func Glibc.access
 import Darwin
 #endif
 
-public extension Path {
+public extension Pathish {
+
     //MARK: Filesystem Properties
 
-    /// Returns true if the path represents an actual filesystem entry.
+    /**
+     - Returns: `true` if the path represents an actual filesystem entry.
+     - Note: If `self` is a symlink the return value represents the destination, thus if the destination doesn’t exist this returns `false` even if the symlink exists.
+     - Note: To determine if a symlink exists, use `.type`.
+     */
     var exists: Bool {
         return FileManager.default.fileExists(atPath: string)
     }

Sources/Path.swift

@@ -32,11 +32,16 @@ let _realpath = Glibc.realpath
 
      let p1 = Path.root.usr.bin.ls  // => /usr/bin/ls
 
- - Note: A `Path` does not necessarily represent an actual filesystem entry.
+ However we only provide this support off of the static members like `root` due
- */
+ to the anti-pattern where Path.swift suddenly feels like Javascript otherwise.
 
-@dynamicMemberLookup
+ - Note: A `Path` does not necessarily represent an actual filesystem entry.
-public struct Path: Equatable, Hashable, Comparable {
+ - SeeAlso: `Pathish` for most methods you will use on `Path` instances.
+ */
+public struct Path: Pathish {
+
+    /// The normalized string representation of the underlying filesystem path
+    public let string: String
 
     init(string: String) {
         assert(string.first == "/")
@@ -70,11 +75,11 @@ public struct Path: Equatable, Hashable, Comparable {
             ifExists(withPrefix: "/var/automount", removeFirst: 2)
             ifExists(withPrefix: "/private", removeFirst: 1)
         #endif
-            self.string = join_(prefix: "/", pathComponents: pathComponents)
+            string = join_(prefix: "/", pathComponents: pathComponents)
 
         case "~":
             if description == "~" {
-                self = Path.home
+                string = Path.home.string
                 return
             }
             let tilded: String
@@ -96,7 +101,7 @@ public struct Path: Equatable, Hashable, Comparable {
             #endif
             }
             pathComponents.remove(at: 0)
-            self.string = join_(prefix: tilded, pathComponents: pathComponents)
+            string = join_(prefix: tilded, pathComponents: pathComponents)
 
         default:
             return nil
@@ -124,20 +129,17 @@ public struct Path: Equatable, Hashable, Comparable {
         // ^^ works even if the url is a file-reference url
     }
 
-    /// :nodoc:
+    /// Converts anything that is `Pathish` to a `Path`
-    public subscript(dynamicMember addendum: String) -> Path {
+    public init<P: Pathish>(_ path: P) {
-        //NOTE it’s possible for the string to be anything if we are invoked via
+        string = path.string
-        // explicit subscript thus we use our fully sanitized `join` function
+    }
-        return Path(string: join_(prefix: string, appending: addendum))
 }
 
-//MARK: Properties
+public extension Pathish {
-
+    //MARK: Filesystem Representation
-    /// The underlying filesystem path
-    public let string: String
 
     /// Returns a `URL` representing this file path.
-    public var url: URL {
+    var url: URL {
         return URL(fileURLWithPath: string)
     }
 
@@ -147,7 +149,7 @@ public struct Path: Equatable, Hashable, Comparable {
      - SeeAlso: https://developer.apple.com/documentation/foundation/nsurl/1408631-filereferenceurl
      - Important: On Linux returns an file scheme NSURL for this path string.
      */
-    public var fileReferenceURL: NSURL? {
+    var fileReferenceURL: NSURL? {
     #if !os(Linux)
         // https://bugs.swift.org/browse/SR-2728
         return (url as NSURL).perform(#selector(NSURL.fileReferenceURL))?.takeUnretainedValue() as? NSURL
@@ -164,7 +166,7 @@ public struct Path: Equatable, Hashable, Comparable {
 
      - Note: always returns a valid path, `Path.root.parent` *is* `Path.root`.
      */
-    public var parent: Path {
+    var parent: Path {
         let index = string.lastIndex(of: "/")!
         let substr = string[string.indices.startIndex..<index]
         return Path(string: String(substr))
@@ -174,10 +176,10 @@ public struct Path: Equatable, Hashable, Comparable {
      Returns the filename extension of this path.
      - Remark: If there is no extension returns "".
      - Remark: If the filename ends with any number of ".", returns "".
-     - Note: We special case eg. `foo.tar.gz`.
+     - Note: We special case eg. `foo.tar.gz`—there are a limited number of these specializations, feel free to PR more.
      */
     @inlinable
-    public var `extension`: String {
+    var `extension`: String {
         //FIXME efficiency
         switch true {
         case string.hasSuffix(".tar.gz"):
@@ -201,14 +203,14 @@ public struct Path: Equatable, Hashable, Comparable {
 
     /**
      Splits the string representation on the directory separator.
-     - Important: The first element is always "/" to be consistent with `NSString.pathComponents`.
+     - Important: `NSString.pathComponents` will always return an initial `/` in its array for absolute paths to indicate that the path was absolute, we don’t do this because we are *always* absolute paths.
     */
     @inlinable
-    public var components: [String] {
+    var components: [String] {
-        return ["/"] + string.split(separator: "/").map(String.init)
+        return string.split(separator: "/").map(String.init)
     }
 
-//MARK: Pathing
+    //MARK:- Pathing
 
     /**
      Joins a path and a string to produce a new path.
@@ -225,7 +227,7 @@ public struct Path: Equatable, Hashable, Comparable {
      - Returns: A new joined path.
      - SeeAlso: `Path./(_:_:)`
      */
-    public func join<S>(_ addendum: S) -> Path where S: StringProtocol {
+    func join<S>(_ addendum: S) -> Path where S: StringProtocol {
         return Path(string: join_(prefix: string, appending: addendum))
     }
 
@@ -246,7 +248,7 @@ public struct Path: Equatable, Hashable, Comparable {
      - SeeAlso: `join(_:)`
      */
     @inlinable
-    public static func /<S>(lhs: Path, rhs: S) -> Path where S: StringProtocol {
+    static func /<S>(lhs: Self, rhs: S) -> Path where S: StringProtocol {
         return lhs.join(rhs)
     }
 
@@ -257,7 +259,7 @@ public struct Path: Equatable, Hashable, Comparable {
      - Parameter base: The base to which we calculate the relative path.
      - ToDo: Another variant that returns `nil` if result would start with `..`
      */
-    public func relative(to base: Path) -> String {
+    func relative<P: Pathish>(to base: P) -> String {
         // Split the two paths into their components.
         // FIXME: The is needs to be optimized to avoid unncessary copying.
         let pathComps = (string as NSString).pathComponents
@@ -296,7 +298,7 @@ public struct Path: Equatable, Hashable, Comparable {
      - Returns: A string that is the filename’s basename.
      - Parameter dropExtension: If `true` returns the basename without its file extension.
      */
-    public func basename(dropExtension: Bool = false) -> String {
+    func basename(dropExtension: Bool = false) -> String {
         var lastPathComponent: Substring {
             let slash = string.lastIndex(of: "/")!
             let index = string.index(after: slash)
@@ -321,27 +323,25 @@ public struct Path: Equatable, Hashable, Comparable {
      If the path represents an actual entry that is a symlink, returns the symlink’s
      absolute destination.
 
-     - Important: This is not exhaustive, the resulting path may still contain
+     - Important: This is not exhaustive, the resulting path may still contain a symlink.
-     symlink.
+     - Important: The path will only be different if the last path component is a symlink, any symlinks in prior components are not resolved.
-     - Important: The path will only be different if the last path component is a
-     symlink, any symlinks in prior components are not resolved.
      - Note: If file exists but isn’t a symlink, returns `self`.
      - Note: If symlink destination does not exist, is **not** an error.
      */
-    public func readlink() throws -> Path {
+    func readlink() throws -> Path {
         do {
             let rv = try FileManager.default.destinationOfSymbolicLink(atPath: string)
             return Path(rv) ?? parent/rv
         } catch CocoaError.fileReadUnknown {
             // file is not symlink, return `self`
             assert(exists)
-            return self
+            return Path(string: string)
         } catch {
         #if os(Linux)
             // ugh: Swift on Linux
             let nsError = error as NSError
             if nsError.domain == NSCocoaErrorDomain, nsError.code == CocoaError.fileReadUnknown.rawValue, exists {
-                return self
+                return Path(self)
             }
         #endif
             throw error
@@ -349,7 +349,7 @@ public struct Path: Equatable, Hashable, Comparable {
     }
 
     /// Recursively resolves symlinks in this path.
-    public func realpath() throws -> Path {
+    func realpath() throws -> Path {
         guard let rv = _realpath(string, nil) else { throw CocoaError.error(.fileNoSuchFile) }
         defer { free(rv) }
         guard let rvv = String(validatingUTF8: rv) else { throw CocoaError.error(.fileReadUnknownStringEncoding) }
@@ -367,7 +367,7 @@ public struct Path: Equatable, Hashable, Comparable {
     /// Returns the locale-aware sort order for the two paths.
     /// :nodoc:
     @inlinable
-    public static func <(lhs: Path, rhs: Path) -> Bool {
+    static func <(lhs: Self, rhs: Self) -> Bool {
         return lhs.string.compare(rhs.string, locale: .current) == .orderedAscending
     }
 }
@@ -406,3 +406,27 @@ private func join_<S>(prefix: String, pathComponents: S) -> String where S: Sequ
     }
     return rv
 }
+
+/// A path that supports arbituary dot notation, eg. `Path.root.usr.bin`
+@dynamicMemberLookup
+public struct DynamicPath: Pathish {
+    /// The normalized string representation of the underlying filesystem path
+    public let string: String
+
+    init(string: String) {
+        assert(string.hasPrefix("/"))
+        self.string = string
+    }
+
+    /// Converts a `Path` to a `DynamicPath`
+    public init<P: Pathish>(_ path: P) {
+        string = path.string
+    }
+
+    /// :nodoc:
+    public subscript(dynamicMember addendum: String) -> DynamicPath {
+        //NOTE it’s possible for the string to be anything if we are invoked via
+        // explicit subscript thus we use our fully sanitized `join` function
+        return DynamicPath(string: join_(prefix: string, appending: addendum))
+    }
+}

Sources/Pathish.swift

@@ -0,0 +1,6 @@
+/// A type that represents a filesystem path, if you conform your type
+/// to `Pathish` it is your responsibility to ensure the string is correctly normalized
+public protocol Pathish: Hashable, Comparable {
+    /// The normalized string representation of the underlying filesystem path
+    var string: String { get }
+}

Tests/PathTests/PathTests+ls().swift

@@ -0,0 +1,85 @@
+import XCTest
+import Path
+
+extension PathTests {
+    func testFindMaxDepth1() throws {
+        try Path.mktemp { tmpdir in
+            try tmpdir.a.touch()
+            try tmpdir.b.touch()
+            try tmpdir.c.mkdir().join("e").touch()
+
+            do {
+                let finder = tmpdir.find().depth(max: 1)
+                XCTAssertEqual(finder.depth, 1...1)
+              #if !os(Linux) || swift(>=5)
+                XCTAssertEqual(Set(finder), Set([tmpdir.a, tmpdir.b, tmpdir.c].map(Path.init)))
+              #endif
+            }
+            do {
+                let finder = tmpdir.find().depth(max: 0)
+                XCTAssertEqual(finder.depth, 0...0)
+              #if !os(Linux) || swift(>=5)
+                XCTAssertEqual(Set(finder), Set())
+              #endif
+            }
+        }
+    }
+
+    func testFindMaxDepth2() throws {
+        try Path.mktemp { tmpdir in
+            try tmpdir.a.touch()
+            try tmpdir.b.mkdir().join("c").touch()
+            try tmpdir.b.d.mkdir().join("e").touch()
+
+            do {
+                let finder = tmpdir.find().depth(max: 2)
+                XCTAssertEqual(finder.depth, 1...2)
+              #if !os(Linux) || swift(>=5)
+                XCTAssertEqual(
+                    Set(finder),
+                    Set([tmpdir.a, tmpdir.b, tmpdir.b.d, tmpdir.b.c].map(Path.init)))
+              #endif
+            }
+            do {
+                let finder = tmpdir.find().depth(max: 3)
+                XCTAssertEqual(finder.depth, 1...3)
+              #if !os(Linux) || swift(>=5)
+                XCTAssertEqual(
+                    Set(finder),
+                    Set([tmpdir.a, tmpdir.b, tmpdir.b.d, tmpdir.b.c, tmpdir.b.d.e].map(Path.init)))
+              #endif
+            }
+        }
+    }
+
+    func testFindExtension() throws {
+        try Path.mktemp { tmpdir in
+            try tmpdir.join("foo.json").touch()
+            try tmpdir.join("bar.txt").touch()
+
+            XCTAssertEqual(
+                Set(tmpdir.find().extension("json")),
+                [tmpdir.join("foo.json")])
+            XCTAssertEqual(
+                Set(tmpdir.find().extension("txt").extension("json")),
+                [tmpdir.join("foo.json"), tmpdir.join("bar.txt")])
+        }
+    }
+
+    func testFindTypes() throws {
+        try Path.mktemp { tmpdir in
+            try tmpdir.foo.mkdir()
+            try tmpdir.bar.touch()
+
+            XCTAssertEqual(
+                Set(tmpdir.find().type(.file)),
+                [tmpdir.join("bar")])
+            XCTAssertEqual(
+                Set(tmpdir.find().type(.directory)),
+                [tmpdir.join("foo")])
+            XCTAssertEqual(
+                Set(tmpdir.find().type(.file).type(.directory)),
+                Set(["foo", "bar"].map(tmpdir.join)))
+        }
+    }
+}

Tests/PathTests/PathTests.swift

@@ -1,4 +1,6 @@
 @testable import Path
+import func XCTest.XCTAssertEqual
+import Foundation
 import XCTest
 
 class PathTests: XCTestCase {
@@ -18,32 +20,31 @@ class PathTests: XCTestCase {
     func testEnumeration() throws {
         let tmpdir_ = try TemporaryDirectory()
         let tmpdir = tmpdir_.path
-        try tmpdir.a.mkdir().c.touch()
+        try tmpdir.join("a").mkdir().join("c").touch()
         try tmpdir.join("b.swift").touch()
-        try tmpdir.c.touch()
+        try tmpdir.join("c").touch()
-        try tmpdir.join(".d").mkdir().e.touch()
+        try tmpdir.join(".d").mkdir().join("e").touch()
 
         var paths = Set<String>()
-        let lsrv = try tmpdir.ls()
+        let lsrv = tmpdir.ls(.a)
         var dirs = 0
-        for entry in lsrv {
+        for path in lsrv {
-            if entry.kind == .directory {
+            if path.isDirectory {
                 dirs += 1
             }
-            paths.insert(entry.path.basename())
+            paths.insert(path.basename())
         }
         XCTAssertEqual(dirs, 2)
         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(["b.swift"], Set(lsrv.files.filter{ $0.extension == "swift" }.map{ $0.relative(to: tmpdir) }))
-        XCTAssertEqual(["c"], Set(lsrv.files(withExtension: "").map{ $0.relative(to: tmpdir) }))
+        XCTAssertEqual(["c"], Set(lsrv.files.filter{ $0.extension == "" }.map{ $0.relative(to: tmpdir) }))
         XCTAssertEqual(paths, ["a", "b.swift", "c", ".d"])
         
     }
 
     func testEnumerationSkippingHiddenFiles() throws {
-    #if !os(Linux)
         let tmpdir_ = try TemporaryDirectory()
         let tmpdir = tmpdir_.path
         try tmpdir.join("a").mkdir().join("c").touch()
@@ -53,25 +54,33 @@ class PathTests: XCTestCase {
         
         var paths = Set<String>()
         var dirs = 0
-        for entry in try tmpdir.ls(includeHiddenFiles: false) {
+        for path in tmpdir.ls() {
-            if entry.kind == .directory {
+            if path.isDirectory {
                 dirs += 1
             }
-            paths.insert(entry.path.basename())
+            paths.insert(path.basename())
         }
         XCTAssertEqual(dirs, 1)
         XCTAssertEqual(paths, ["a", "b", "c"])
-    #endif
     }
 
     func testRelativeTo() {
-        XCTAssertEqual((Path.root/"tmp/foo").relative(to: .root/"tmp"), "foo")
+        XCTAssertEqual((Path.root.tmp.foo).relative(to: Path.root/"tmp"), "foo")
-        XCTAssertEqual((Path.root/"tmp/foo/bar").relative(to: .root/"tmp/baz"), "../foo/bar")
+        XCTAssertEqual((Path.root.tmp.foo.bar).relative(to: Path.root/"tmp/baz"), "../foo/bar")
     }
 
-    func testExists() {
+    func testExists() throws {
         XCTAssert(Path.root.exists)
         XCTAssert((Path.root/"bin").exists)
+
+        try Path.mktemp { tmpdir in
+            XCTAssertTrue(tmpdir.exists)
+            XCTAssertFalse(try tmpdir.bar.symlink(as: tmpdir.foo).exists)
+            XCTAssertTrue(tmpdir.foo.type == .symlink)
+            XCTAssertTrue(try tmpdir.bar.touch().symlink(as: tmpdir.baz).exists)
+            XCTAssertTrue(tmpdir.bar.type == .file)
+            XCTAssertTrue(tmpdir.type == .directory)
+        }
     }
 
     func testIsDirectory() {
@@ -96,7 +105,7 @@ class PathTests: XCTestCase {
     }
 
     func testMktemp() throws {
-        var path: Path!
+        var path: DynamicPath!
         try Path.mktemp {
             path = $0
             XCTAssert(path.isDirectory)
@@ -124,7 +133,7 @@ class PathTests: XCTestCase {
     }
 
     func testCodable() throws {
-        let input = [Path.root.foo, Path.root.foo.bar, Path.root]
+        let input = [Path.root.foo, Path.root.foo.bar, Path.root].map(Path.init)
         XCTAssertEqual(try JSONDecoder().decode([Path].self, from: try JSONEncoder().encode(input)), input)
     }
 
@@ -134,7 +143,7 @@ class PathTests: XCTestCase {
             Path.root,
             root,
             root.bar
-        ]
+        ].map(Path.init)
 
         let encoder = JSONEncoder()
         encoder.userInfo[.relativePath] = root
@@ -195,7 +204,9 @@ class PathTests: XCTestCase {
             XCTAssertThrowsError(try root.foo.copy(to: root.bar))
             try root.foo.copy(to: root.bar, overwrite: true)
         }
+    }
 
+    func testCopyToExistingDirectoryFails() throws {
         // test copy errors if directory exists at destination, even with overwrite
         try Path.mktemp { root in
             try root.foo.touch()
@@ -379,11 +390,26 @@ class PathTests: XCTestCase {
         #if !os(Linux)
             XCTAssertThrowsError(try tmpdir.bar3.touch().lock().delete())
         #endif
+
+            // regression test: can delete a symlink that points to a non-existent file
+            let bar5 = try tmpdir.bar4.symlink(as: tmpdir.bar5)
+            XCTAssertEqual(bar5.type, .symlink)
+            XCTAssertFalse(bar5.exists)
+            XCTAssertNoThrow(try bar5.delete())
+            XCTAssertEqual(bar5.type, nil)
+
+            // test that deleting a symlink *only* deletes the symlink
+            let bar7 = try tmpdir.bar6.touch().symlink(as: tmpdir.bar7)
+            XCTAssertEqual(bar7.type, .symlink)
+            XCTAssertTrue(bar7.exists)
+            XCTAssertNoThrow(try bar7.delete())
+            XCTAssertEqual(bar7.type, nil)
+            XCTAssertEqual(tmpdir.bar6.type, .file)
         }
     }
 
     func testRelativeCodable() throws {
-        let path = Path.home.foo
+        let path = Path(Path.home.foo)
         let encoder = JSONEncoder()
         encoder.userInfo[.relativePath] = Path.home
         let data = try encoder.encode([path])
@@ -391,13 +417,15 @@ class PathTests: XCTestCase {
         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])
+        XCTAssertEqual(try decoder.decode([Path].self, from: data), [Path(Path.documents.foo)])
         XCTAssertThrowsError(try JSONDecoder().decode([Path].self, from: data))
     }
 
     func testBundleExtensions() throws {
-        try Path.mktemp { tmpdir in
+        try Path.mktemp { tmpdir -> Void in
-            let bndl = Bundle(path: tmpdir.string)!
+            guard let bndl = Bundle(path: tmpdir.string) else {
+                return XCTFail("Couldn’t make Bundle for \(tmpdir)")
+            }
             XCTAssertEqual(bndl.path, tmpdir)
             XCTAssertEqual(bndl.sharedFrameworks, tmpdir.SharedFrameworks)
             XCTAssertEqual(bndl.privateFrameworks, tmpdir.Frameworks)
@@ -489,7 +517,7 @@ class PathTests: XCTestCase {
             let foo = try tmpdir.foo.touch()
             let bar = try tmpdir.bar.mkdir()
             XCTAssertThrowsError(try foo.symlink(as: bar))
-            XCTAssert(try foo.symlink(as: bar.foo).isSymlink)
+            XCTAssert(try foo.symlink(as: bar/"foo").isSymlink)
         }
     }
 
@@ -544,8 +572,8 @@ class PathTests: XCTestCase {
 
         try Path.mktemp { tmpdir in
             let foo = try tmpdir.foo.mkdir()
-            try foo.bar.mkdir().fuz.touch()
+            try foo.join("bar").mkdir().join("fuz").touch()
-            let baz = try foo.symlink(as: tmpdir.baz)
+            let baz = DynamicPath(try foo.symlink(as: tmpdir.baz))
             XCTAssert(baz.isSymlink)
             XCTAssert(baz.bar.isDirectory)
             XCTAssertEqual(baz.bar.join("..").string, "\(tmpdir)/baz")
@@ -558,7 +586,7 @@ class PathTests: XCTestCase {
         try Path.mktemp { tmpdir in
             let b = try tmpdir.a.b.mkdir(.p)
             let c = try tmpdir.a.c.touch()
-            let e = try c.symlink(as: b.e)
+            let e = try c.symlink(as: b/"e")
             let f = try e.symlink(as: tmpdir.f)
             XCTAssertEqual(try f.readlink(), e)
             XCTAssertEqual(try f.realpath(), c)
@@ -591,8 +619,8 @@ class PathTests: XCTestCase {
     }
 
     func testPathComponents() throws {
-        XCTAssertEqual(Path.root.foo.bar.components, ["/", "foo", "bar"])
+        XCTAssertEqual(Path.root.foo.bar.components, ["foo", "bar"])
-        XCTAssertEqual(Path.root.components, ["/"])
+        XCTAssertEqual(Path.root.components, [])
     }
 
     func testFlatMap() throws {
@@ -604,4 +632,22 @@ class PathTests: XCTestCase {
         let baz: String.SubSequence? = "/a/b:1".split(separator: ":").first
         _ = baz.flatMap(Path.init)
     }
+
+    func testKind() throws {
+        try Path.mktemp { tmpdir in
+            let foo = try tmpdir.foo.touch()
+            let bar = try foo.symlink(as: tmpdir.bar)
+            XCTAssertEqual(tmpdir.type, .directory)
+            XCTAssertEqual(foo.type, .file)
+            XCTAssertEqual(bar.type, .symlink)
+        }
+    }
+}
+
+private func XCTAssertEqual<P: Pathish, Q: Pathish>(_ p: P, _ q: Q, file: StaticString = #file, line: UInt = #line) {
+    XCTAssertEqual(p.string, q.string, file: file, line: line)
+}
+
+private func XCTAssertEqual<P: Pathish, Q: Pathish>(_ p: P?, _ q: Q?, file: StaticString = #file, line: UInt = #line) {
+    XCTAssertEqual(p?.string, q?.string, file: file, line: line)
 }

Tests/PathTests/TemporaryDirectory.swift

@@ -3,7 +3,7 @@ import Foundation
 
 class TemporaryDirectory {
     let url: URL
-    var path: Path { return Path(string: url.path) }
+    var path: DynamicPath { return DynamicPath(Path(string: url.path)) }
 
     /**
      Creates a new temporary directory.
@@ -51,7 +51,7 @@ class TemporaryDirectory {
 }
 
 extension Path {
-    static func mktemp<T>(body: (Path) throws -> T) throws -> T {
+    static func mktemp<T>(body: (DynamicPath) throws -> T) throws -> T {
         let tmp = try TemporaryDirectory()
         return try body(tmp.path)
     }

Tests/PathTests/XCTestManifests.swift

@@ -13,6 +13,7 @@ extension PathTests {
         ("testConcatenation", testConcatenation),
         ("testCopyInto", testCopyInto),
         ("testCopyTo", testCopyTo),
+        ("testCopyToExistingDirectoryFails", testCopyToExistingDirectoryFails),
         ("testDataExtensions", testDataExtensions),
         ("testDelete", testDelete),
         ("testDynamicMember", testDynamicMember),
@@ -23,10 +24,15 @@ extension PathTests {
         ("testFileHandleExtensions", testFileHandleExtensions),
         ("testFileReference", testFileReference),
         ("testFilesystemAttributes", testFilesystemAttributes),
+        ("testFindExtension", testFindExtension),
+        ("testFindMaxDepth1", testFindMaxDepth1),
+        ("testFindMaxDepth2", testFindMaxDepth2),
+        ("testFindTypes", testFindTypes),
         ("testFlatMap", testFlatMap),
         ("testInitializerForRelativePath", testInitializerForRelativePath),
         ("testIsDirectory", testIsDirectory),
         ("testJoin", testJoin),
+        ("testKind", testKind),
         ("testLock", testLock),
         ("testMkpathIfExists", testMkpathIfExists),
         ("testMktemp", testMktemp),