Rename Path->Bool.swift to PathToBool.swift

Makes path Windows-friendly

.github/codecov.yml

@@ -1,2 +1,3 @@
 ignore:
-  - Tests
+  - Tests/PathTests/etc.swift
+  - Tests/PathTests/TemporaryDirectory.swift

.github/jazzy.yml

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

.github/workflows/cd.yml

@@ -0,0 +1,24 @@
+name: CD
+on:
+  release:
+    types: published
+jobs:
+  docs:
+    runs-on: macos-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: steven0351/publish-jazzy-docs@v1
+      with:
+        personal_access_token: ${{ secrets.PAT }}
+        config: .github/jazzy.yml
+        version: ${{ github.event.release.tag_name }}
+        history: false
+
+  pods:
+    runs-on: macos-latest
+    steps:
+    - uses: actions/checkout@v2
+    - run: pod trunk push --allow-warnings
+      env:
+        COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}
+        VERSION: ${{ github.event.release.tag_name }}

.github/workflows/checks.yml

@@ -0,0 +1,14 @@
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - '**/*.swift'
+      - .github/workflows/checks.yml
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - run: swift --version
+    - run: swift test --parallel

.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: CI
+on:
+  pull_request:
+    paths:
+      - '**/*.swift'
+      - .github/workflows/ci.yml
+  schedule:
+    - cron: '3 3 * * 5'  # 3:03 AM, every Friday
+
+concurrency:
+  group: ${{ github.head_ref || 'push' }}
+  cancel-in-progress: true
+
+jobs:
+  verify-linuxmain:
+    runs-on: macos-10.15
+    steps:
+    - uses: actions/checkout@v2
+    - run: swift test --generate-linuxmain
+    - run: git diff --exit-code
+
+  apple:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - macos-10.15
+          - macos-11
+        platform:
+          - iOS
+          - tvOS
+          - macOS
+          - watchOS
+    steps:
+    - uses: actions/checkout@v2
+    - uses: mxcl/xcodebuild@v1
+      with:
+        platform: ${{ matrix.platform }}
+        code-coverage: true
+        warnings-as-errors: true
+    - uses: codecov/codecov-action@v1
+
+  linux:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        swift:
+        - swift:4.2
+        - swift:5.0
+        - swift:5.1
+        - swift:5.2
+        - swift:5.3
+        - swift:5.4
+        - swiftlang/swift:nightly-5.5
+    container:
+      image: ${{ matrix.swift }}
+    steps:
+    - uses: mxcl/get-swift-version@v1
+      id: swift
+
+    - uses: actions/checkout@v2
+
+    - run: useradd -ms /bin/bash mxcl
+    - run: chown -R mxcl .
+    # ^^ we need to be a normal user and not root for the tests to be valid
+
+    - run: echo ARGS=--enable-code-coverage >> $GITHUB_ENV
+      if: ${{ steps.swift.outputs.marketing-version > 5 }}
+
+    - run: su mxcl -c "swift test --parallel $ARGS"
+
+    - name: Generate `.lcov`
+      if: ${{ steps.swift.outputs.marketing-version > 5 }}
+      run: |
+        apt-get -qq update && apt-get -qq install curl
+        b=$(swift build --show-bin-path)
+        llvm-cov export \
+          -format lcov \
+          -instr-profile="$b"/codecov/default.profdata \
+          --ignore-filename-regex='\.build|Tests' \
+          "$b"/*.xctest \
+          > info.lcov
+
+    - uses: codecov/codecov-action@v1
+      if: ${{ steps.swift.outputs.marketing-version > 5 }}
+      with:
+        file: ./info.lcov

.travis.yml

@@ -1,81 +1,37 @@
-# only run for: merge commits, releases and pull-requests
-if: type != push OR branch = master OR branch =~ /^\d+\.\d+\.\d+(-.*)?$/
+# Travis does CD, GHA does CI
+if: branch =~ /^deploy-\d+\.\d+\.\d+(-.*)?$/ OR branch =~ /^\d+\.\d+\.\d+(-.*)?$/
 
 stages:
-  - name: pretest
-  - name: test
   - name: deploy
+    if: branch =~ /^deploy-\d+\.\d+\.\d+(-.*)?$/
+  - name: publish
     if: branch =~ /^\d+\.\d+\.\d+(-.*)?$/
 
 os: osx
-language: swift
-osx_image: xcode10.1
-xcode_project: Path.swift.xcodeproj
-xcode_scheme: Path.swift-Package
 
 jobs:
   include:
-    - name: macOS / Swift 4.0.3
-      script: swift test --parallel -Xswiftc -swift-version -Xswiftc 4
-
-    - name: macOS / Swift 4.2.1
-      script: swift test --parallel
-
-    - name: macOS / Swift 5.0
-      osx_image: xcode10.2
-      script: swift test --parallel
-
-    - name: macOS / Swift 5.1
-      osx_image: xcode11
-      script: swift test --parallel
-
-    - &xcodebuild
-      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
-
-    - <<: *xcodebuild
-      name: watchOS / Swift 4.2.1
-      script: |
-        set -o pipefail
-        xcodebuild \
-          -project Path.swift.xcodeproj \
-          -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.4
-      os: linux
-      name: Linux / Swift 4.2.4
-      language: generic
-      sudo: false
-      install: eval "$(curl -sL https://swiftenv.fuller.li/install.sh)"
-      script: swift test --parallel
-
-    - <<: *linux
-      env: SWIFT_VERSION='5.0.2'
-      name: Linux / Swift 5.0.2
-
-    - <<: *linux
-      env: SWIFT_VERSION=5.1-DEVELOPMENT-SNAPSHOT-2019-07-03-a
-      name: Linux / Swift 5.1 (2019-07-03)
-
-    - stage: pretest
-      name: Check Linux tests are sync’d
-      install: swift test --generate-linuxmain
-      script: git diff --exit-code
-      osx_image: xcode10.2
-
     - stage: deploy
+      name: Deploy
+      osx_image: xcode11
+      env: HOMEBREW_NO_INSTALL_CLEANUP=1
+      install: brew install mxcl/made/swift-sh
+      git.depth: false
+      script:
+        - set -e
+        - export VERSION=$(echo $TRAVIS_TAG | cut -c 8-)
+        - git tag "$VERSION" --force
+        - git remote set-url origin "https://$GITHUB_TOKEN@github.com/$TRAVIS_REPO_SLUG.git"
+        - git push origin "$VERSION"
+        - swift sh <(curl https://raw.githubusercontent.com/mxcl/ops/master/deploy) publish-release
+        - git push origin :$TRAVIS_TAG
+      after_failure: |
+        export VERSION=$(echo $TRAVIS_TAG | cut -c 8-)
+        git push origin :$VERSION
+
+    - stage: publish
       name: Jazzy
-      osx_image: xcode10.2
+      osx_image: xcode11
       install: gem install jazzy
       before_script: swift package generate-xcodeproj
       script: |
@@ -91,11 +47,11 @@ jobs:
           tags: true
 
     - name: CocoaPods
-      osx_image: xcode10.2
-      install: |
-        brew install mxcl/made/swift-sh
-        curl -O https://raw.githubusercontent.com/mxcl/ops/master/deploy
-        chmod u+x deploy
+      env: HOMEBREW_NO_INSTALL_CLEANUP=1
+      osx_image: xcode11
+      install:
+        - 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: ./deploy publish-release

Path.swift.podspec

@@ -0,0 +1,16 @@
+Pod::Spec.new do |spec|
+  spec.name           = "Path.swift"
+  spec.version        = ENV['VERSION'] || "0.0.1"
+  spec.summary        = "Delightful, robust, cross-platform and chainable file-pathing functions."
+  spec.homepage       = "https://github.com/mxcl/Path.swift"
+  spec.license        = "Unlicense"
+  spec.author         = { "Max Howell" => "mxcl@me.com" }
+  spec.source         = { :git => "https://github.com/mxcl/Path.swift.git", :tag => "#{spec.version}" }
+  spec.source_files   = "Sources/*.swift"
+  spec.swift_versions = ['4.2', '5']
+  spec.module_name    = 'Path'
+  spec.osx.deployment_target     = '10.10'
+  spec.ios.deployment_target     = '8.0'
+  spec.tvos.deployment_target    = '9.0'
+  spec.watchos.deployment_target = '2.0'
+end

README.md

@@ -31,6 +31,9 @@ print(bar.isFile)  // => true
 let foo = try Path.root.join("foo").copy(into: Path.root.join("bar").mkdir())
 print(foo)         // => /bar/foo
 print(foo.isFile)  // => true
+// ^^ the `into:` version will only copy *into* a directory, the `to:` version copies
+// to a file at that path, thus you will not accidentally copy into directories you
+// may not have realized existed.
 
 // we support dynamic-member-syntax when joining named static members, eg:
 let prefs = Path.home.Library.Preferences  // => /Users/mxcl/Library/Preferences
@@ -42,18 +45,13 @@ try Bundle.resources.helper.copy(into: Path.root.usr.local.bin).chmod(0o500)
 We emphasize safety and correctness, just like Swift, and also (again like
 Swift), we provide a thoughtful and comprehensive (yet concise) API.
 
-# Support mxcl
+# Sponsor @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?). I work full-time on
-open source and it’s hard; currently I earn *less* than minimum wage. Please
-help me continue my work, I appreciate it x
+Hi, I’m Max Howell and I have written a lot of open source software—generally
+a good deal of my free time 👨🏻‍💻. Sponsorship helps me justify creating new open
+source and maintaining it. Thank you.
 
-<a href="https://www.patreon.com/mxcl">
-	<img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160">
-</a>
-
-[Other donation/tipping options](http://mxcl.dev/#donate)
+[Sponsor @mxcl].
 
 # Handbook
 
@@ -75,30 +73,36 @@ try JSONEncoder().encode([Path.home, Path.home/"foo"])
 ]
 ```
 
-However, often you want to encode relative paths:
+Though we recommend encoding *relative* paths‡:
 
 ```swift
 let encoder = JSONEncoder()
 encoder.userInfo[.relativePath] = Path.home
-encoder.encode([Path.home, Path.home/"foo"])
+encoder.encode([Path.home, Path.home/"foo", Path.home/"../baz"])
 ```
 
 ```json
 [
     "",
     "foo",
+    "../baz"
 ]
 ```
 
-**Note** make sure you decode with this key set *also*, otherwise we `fatal`
-(unless the paths are absolute obv.)
+**Note** if you encode with this key set you *must* decode with the key
+set also:
 
 ```swift
 let decoder = JSONDecoder()
 decoder.userInfo[.relativePath] = Path.home
-decoder.decode(from: data)
+try decoder.decode(from: data)  // would throw if `.relativePath` not set
 ```
 
+> ‡ If you are saving files to a system provided location, eg. Documents then
+> the directory could change at Apple’s choice, or if say the user changes their
+> username. Using relative paths also provides you with the flexibility in
+> future to change where you are storing your files without hassle.
+
 ## Dynamic members
 
 We support `@dynamicMemberLookup`:
@@ -111,7 +115,26 @@ We only provide this for “starting” function, eg. `Path.home` or `Bundle.pat
 This is because we found in practice it was easy to write incorrect code, since
 everything would compile if we allowed arbituary variables to take *any* named
 property as valid syntax. What we have is what you want most of the time but
-much less dangerous.
+much less (potentially) dangerous (at runtime).
+
+### Pathish
+
+`Path`, and `DynamicPath` (the result of eg. `Path.root`) both conform to
+`Pathish` which is a protocol that contains all pathing functions. Thus if
+you create objects from a mixture of both you need to create generic
+functions or convert any `DynamicPath`s to `Path` first:
+
+```swift
+let path1 = Path("/usr/lib")!
+let path2 = Path.root.usr.bin
+var paths = [Path]()
+paths.append(path1)        // fine
+paths.append(path2)        // error
+paths.append(Path(path2))  // ok
+```
+
+This is inconvenient but as Swift stands there’s nothing we can think of
+that would help.
 
 ## Initializing from user-input
 
@@ -129,6 +152,28 @@ expect to be relative.
 Our initializer is nameless to be consistent with the equivalent operation for
 converting strings to `Int`, `Float` etc. in the standard library.
 
+## Initializing from known strings
+
+There’s no need to use the optional initializer in general if you have known
+strings that you need to be paths:
+
+```swift
+let absolutePath = "/known/path"
+let path1 = Path.root/absolutePath
+
+let pathWithoutInitialSlash = "known/path"
+let path2 = Path.root/pathWithoutInitialSlash
+
+assert(path1 == path2)
+
+let path3 = Path(absolutePath)!  // at your options
+
+assert(path2 == path3)
+
+// be cautious:
+let path4 = Path(pathWithoutInitialSlash)!  // CRASH!
+```
+
 ## Extensions
 
 We have some extensions to Apple APIs:
@@ -170,38 +215,46 @@ let files = Path.home.ls().files
 // ^^ files that both *exist* and are *not* directories
 
 let swiftFiles = Path.home.ls().files.filter{ $0.extension == "swift" }
+
+let includingHiddenFiles = Path.home.ls(.a)
 ```
 
+**Note** `ls()` does not throw, instead outputing a warning to the console if it
+fails to list the directory. The rationale for this is weak, please open a
+ticket for discussion.
+
 We provide `find()` for recursive listing:
 
 ```swift
-Path.home.find().execute { path in
+for path in Path.home.find() {
+    // descends all directories, and includes hidden files by default
+    // so it behaves the same as the terminal command `find`
+}
+```
+
+It is configurable:
+
+```swift
+for path in Path.home.find().depth(max: 1).extension("swift").type(.file).hidden(false) {
     //…
 }
 ```
 
-Which is configurable:
+It can be controlled with a closure syntax:
 
 ```swift
-Path.home.find().maxDepth(1).extension("swift").kind(.file) { path in
+Path.home.find().depth(2...3).execute { path in
+    guard path.basename() != "foo.lock" else { return .abort }
+    if path.basename() == ".build", path.isDirectory { return .skip }
     //…
-}
-```
-
-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:
+Or get everything at once as an array:
 
 ```swift
-let paths = Path.home.find().execute()
+let paths = Path.home.find().map(\.self)
 ```
 
 # `Path.swift` is robust
@@ -210,8 +263,8 @@ Some parts of `FileManager` are not exactly idiomatic. For example
 `isExecutableFile` returns `true` even if there is no file there, it is instead
 telling you that *if* you made a file there it *could* be executable. Thus we
 check the POSIX permissions of the file first, before returning the result of
-`isExecutableFile`. `Path.swift` has done the leg-work for you so you can get on
-with your work without worries.
+`isExecutableFile`. `Path.swift` has done the leg-work for you so you can just
+get on with it and not have to worry.
 
 There is also some magic going on in Foundation’s filesystem APIs, which we look
 for and ensure our API is deterministic, eg. [this test].
@@ -225,7 +278,8 @@ round them where necessary.
 
 # Rules & Caveats
 
-Paths are just string representations, there *might not* be a real file there.
+Paths are just (normalized) string representations, there *might not* be a real
+file there.
 
 ```swift
 Path.home/"b"      // => /Users/mxcl/b
@@ -233,7 +287,7 @@ Path.home/"b"      // => /Users/mxcl/b
 // joining multiple strings works as you’d expect
 Path.home/"b"/"c"  // => /Users/mxcl/b/c
 
-// joining multiple parts at a time is fine
+// joining multiple parts simultaneously is fine
 Path.home/"b/c"    // => /Users/mxcl/b/c
 
 // joining with absolute paths omits prefixed slash
@@ -243,6 +297,9 @@ Path.home/"/b"     // => /Users/mxcl/b
 Path.home.foo.bar.join("..")  // => /Users/mxcl/foo
 Path.home.foo.bar.join(".")   // => /Users/mxcl/foo/bar
 
+// though note that we provide `.parent`:
+Path.home.foo.bar.parent      // => /Users/mxcl/foo
+
 // of course, feel free to join variables:
 let b = "b"
 let c = "c"
@@ -266,13 +323,13 @@ Path("/foo/bar/../baz")  // => /foo/baz
 
 // symlinks are not resolved
 Path.root.bar.symlink(as: "foo")
-Path("foo")        // => /foo
-Path.foo           // => /foo
+Path("/foo")        // => /foo
+Path.root.foo       // => /foo
 
 // unless you do it explicitly
-try Path.foo.readlink()  // => /bar
-                         // `readlink` only resolves the *final* path component,
-                         // thus use `realpath` if there are multiple symlinks
+try Path.root.foo.readlink()  // => /bar
+                              // `readlink` only resolves the *final* path component,
+                              // thus use `realpath` if there are multiple symlinks
 ```
 
 *Path.swift* has the general policy that if the desired end result preexists,
@@ -282,7 +339,7 @@ then it’s a noop:
 * If you try to make a directory and it already exists, we do nothing.
 * If you call `readlink` on a non-symlink, we return `self`
 
-However notably if you try to copy or move a file with specifying `overwrite`
+However notably if you try to copy or move a file without specifying `overwrite`
 and the file already exists at the destination and is identical, we don’t check
 for that as the check was deemed too expensive to be worthwhile.
 
@@ -293,23 +350,27 @@ 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`), we *do* the same for
-    `Path.init`, but *do not* if you are joining a path that ends up being one of
-    these paths, (eg. `Path.root.join("var/private')`).
+    functions that you would expect it (notably `realpath`), we *do* the same
+    for `Path.init`, but *do not* if you are joining a path that ends up being
+    one of 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 `kind` is `nil`.
+no filesystem entry there at all check if `type` is `nil`.
 
 
 ## We do not provide change directory functionality
 
 Changing directory is dangerous, you should *always* try to avoid it and thus
 we don’t even provide the method. If you are executing a sub-process then
-use `Process.currentDirectoryURL`.
+use `Process.currentDirectoryURL` to change *its* working directory when it
+executes.
 
-If you must then use `FileManager.changeCurrentDirectory`.
+If you must change directory then use `FileManager.changeCurrentDirectory` as
+early in your process as *possible*. Altering the global state of your app’s
+environment is fundamentally dangerous creating hard to debug issues that
+you won‘t find for potentially *years*.
 
 # I thought I should only use `URL`s?
 
@@ -318,8 +379,8 @@ Apple recommend this because they provide a magic translation for
 
     file:///.file/id=6571367.15106761
 
-Therefore, if you are not using this feature you are fine. If you have URLs the correct
-way to get a `Path` is:
+Therefore, if you are not using this feature you are fine. If you have URLs the
+correct way to get a `Path` is:
 
 ```swift
 if let path = Path(url: url) {
@@ -332,32 +393,42 @@ actual filesystem path, however we also check the URL has a `file` scheme first.
 
 [file-refs]: https://developer.apple.com/documentation/foundation/nsurl/1408631-filereferenceurl
 
+# In defense of our naming scheme
+
+Chainable syntax demands short method names, thus we adopted the naming scheme
+of the terminal, which is absolutely not very “Apple” when it comes to how they
+design their APIs, however for users of the terminal (which *surely* is most
+developers) it is snappy and familiar.
+
 # Installation
 
 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")
+)
+
+package.targets.append(
+    .target(name: "Foo", dependencies: [
+        .product(name: "Path", package: "Path.swift")
+    ])
+)
 ```
 
 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
+# Naming Conflicts with `SwiftUI.Path`, etc.
 
-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/
+We have a typealias of `PathStruct` you can use instead.
 
 # Alternatives
 
@@ -368,12 +439,13 @@ 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.x-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
-[badge-ci]: https://travis-ci.com/mxcl/Path.swift.svg
+[badge-ci]: https://github.com/mxcl/Path.swift/workflows/Checks/badge.svg
 [travis]: https://travis-ci.com/mxcl/Path.swift
 [codecov]: https://codecov.io/gh/mxcl/Path.swift
 [badge-version]: https://img.shields.io/cocoapods/v/Path.swift.svg?label=version
 [cocoapods]: https://cocoapods.org/pods/Path.swift
+[Sponsor @mxcl]: https://github.com/sponsors/mxcl

Sources/Path+Attributes.swift

@@ -30,6 +30,29 @@ public extension Pathish {
         }
     }
 
+    /// 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.
 
@@ -40,6 +63,8 @@ public extension Pathish {
         try FileManager.default.setAttributes([.posixPermissions: octal], ofItemAtPath: string)
         return Path(self)
     }
+
+    //MARK: Filesystem Locking
     
     /**
      Applies the macOS filesystem “lock” attribute.
@@ -83,24 +108,17 @@ public extension Pathish {
     #endif
         return Path(self)
     }
-
-    var kind: Path.Kind? {
-        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
-        }
-    }
 }
 
+/// The `extension` that provides `Kind`.
 public extension Path {
-    enum Kind {
-        case file, symlink, directory
+    /// 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+CommonDirectories.swift

@@ -1,20 +1,33 @@
 import Foundation
 
-extension Path {
+/// The `extension` that provides static properties that are common directories.
+private enum Foo {
     //MARK: Common Directories
-    
+
     /// Returns a `Path` containing `FileManager.default.currentDirectoryPath`.
-    public static var cwd: DynamicPath {
+    static var cwd: DynamicPath {
         return .init(string: FileManager.default.currentDirectoryPath)
     }
 
     /// Returns a `Path` representing the root path.
-    public static var root: DynamicPath {
+    static var root: DynamicPath {
         return .init(string: "/")
     }
 
+#if swift(>=5.3)
+    public static func source(for filePath: String = #filePath) -> (file: DynamicPath, directory: DynamicPath) {
+        let file = DynamicPath(string: filePath)
+        return (file: file, directory: .init(file.parent))
+    }
+#else
+    public static func source(for filePath: String = #file) -> (file: DynamicPath, directory: DynamicPath) {
+        let file = DynamicPath(string: filePath)
+        return (file: file, directory: .init(file.parent))
+    }
+#endif
+
     /// Returns a `Path` representing the user’s home directory
-    public static var home: DynamicPath {
+    static var home: DynamicPath {
         let string: String
       #if os(macOS)
         if #available(OSX 10.12, *) {
@@ -57,7 +70,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: DynamicPath {
+    static var documents: DynamicPath {
         return path(for: .documentDirectory)
     }
 
@@ -66,7 +79,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: DynamicPath {
+    static var caches: DynamicPath {
         return path(for: .cachesDirectory)
     }
 
@@ -75,7 +88,7 @@ extension Path {
      - Note: On Linux is `XDG_DATA_HOME`.
      - Note: You should create a subdirectory before creating any files.
      */
-    public static var applicationSupport: DynamicPath {
+    static var applicationSupport: DynamicPath {
         return path(for: .applicationSupportDirectory)
     }
 }
@@ -95,3 +108,35 @@ func defaultUrl(for searchPath: FileManager.SearchPathDirectory) -> DynamicPath
 }
 #endif
 
+/// The `extension` that provides static properties that are common directories.
+#if swift(>=5.5)
+public extension Pathish where Self == Path {
+    static var home: DynamicPath { return Foo.home }
+    static var root: DynamicPath { return Foo.root }
+    static var cwd: DynamicPath { return Foo.cwd }
+    static var documents: DynamicPath { return Foo.documents }
+    static var caches: DynamicPath { return Foo.caches }
+    static var applicationSupport: DynamicPath { return Foo.applicationSupport }
+    static func source(for filePath: String = #filePath) -> (file: DynamicPath, directory: DynamicPath) {
+        return Foo.source(for: filePath)
+    }
+}
+#else
+public extension Path {
+    static var home: DynamicPath { return Foo.home }
+    static var root: DynamicPath { return Foo.root }
+    static var cwd: DynamicPath { return Foo.cwd }
+    static var documents: DynamicPath { return Foo.documents }
+    static var caches: DynamicPath { return Foo.caches }
+    static var applicationSupport: DynamicPath { return Foo.applicationSupport }
+#if swift(>=5.3)
+    static func source(for filePath: String = #filePath) -> (file: DynamicPath, directory: DynamicPath) {
+        return Foo.source(for: filePath)
+    }
+#else
+    static func source(for file: String = #file) -> (file: DynamicPath, directory: DynamicPath) {
+        return Foo.source(for: file)
+    }
+#endif
+}
+#endif

Sources/Path+FileManager.swift

@@ -4,8 +4,9 @@ import Glibc
 #endif
 
 public extension Pathish {
+
     //MARK: File Management
-    
+
     /**
      Copies a file.
 
@@ -25,11 +26,12 @@ public extension Pathish {
      */
     @discardableResult
     func copy<P: Pathish>(to: P, overwrite: Bool = false) throws -> Path {
-        if overwrite, let tokind = to.kind, tokind != .directory, kind != .directory {
+        if overwrite, let tokind = to.type, tokind != .directory, type != .directory {
             try FileManager.default.removeItem(at: to.url)
         }
-    #if os(Linux) && !swift(>=5.2) // check if fixed
-        if !overwrite, to.kind != nil {
+    #if os(Linux)
+        //NOTE doing manually due to inconsistency in Linux Foundation behavior
+        if !overwrite, to.type != nil {
             throw CocoaError.error(.fileWriteFileExists)
         }
     #endif
@@ -61,15 +63,16 @@ public extension Pathish {
      */
     @discardableResult
     func copy<P: Pathish>(into: P, overwrite: Bool = false) throws -> Path {
-        if into.kind == nil {
+        if into.type == nil {
             try into.mkdir(.p)
         }
         let rv = into/basename()
-        if overwrite, let kind = rv.kind, kind != .directory {
+        if overwrite, let kind = rv.type, kind != .directory {
             try FileManager.default.removeItem(at: rv.url)
         }
-    #if os(Linux) && !swift(>=5.2) // check if fixed
-        if !overwrite, rv.kind != nil {
+    #if os(Linux)
+        //NOTE doing manually due to inconsistency in Linux Foundation behavior
+        if !overwrite, rv.type != nil {
             throw CocoaError.error(.fileWriteFileExists)
         }
     #endif
@@ -95,7 +98,7 @@ public extension Pathish {
      */
     @discardableResult
     func move<P: Pathish>(to: P, overwrite: Bool = false) throws -> Path {
-        if overwrite, let kind = to.kind, kind != .directory {
+        if overwrite, let kind = to.type, kind != .directory {
             try FileManager.default.removeItem(at: to.url)
         }
         try FileManager.default.moveItem(at: url, to: to.url)
@@ -119,13 +122,13 @@ public extension Pathish {
      */
     @discardableResult
     func move<P: Pathish>(into: P, overwrite: Bool = false) throws -> Path {
-        switch into.kind {
+        switch into.type {
         case nil:
             try into.mkdir(.p)
             fallthrough
         case .directory?:
             let rv = into/basename()
-            if overwrite, let rvkind = rv.kind, rvkind != .directory {
+            if overwrite, let rvkind = rv.type, rvkind != .directory {
                 try FileManager.default.removeItem(at: rv.url)
             }
             try FileManager.default.moveItem(at: url, to: rv.url)
@@ -147,7 +150,7 @@ public extension Pathish {
     */
     @inlinable
     func delete() throws {
-        if kind != nil {
+        if type != nil {
             try FileManager.default.removeItem(at: url)
         }
     }
@@ -159,7 +162,7 @@ public extension Pathish {
     @inlinable
     @discardableResult
     func touch() throws -> Path {
-        if kind == nil {
+        if type == nil {
             guard FileManager.default.createFile(atPath: string, contents: nil) else {
                 throw CocoaError.error(.fileWriteUnknown)
             }
@@ -203,7 +206,7 @@ public extension Pathish {
     }
 
     /**
-     Renames the file at path.
+     Renames the file (basename only) at path.
 
          Path.root.foo.bar.rename(to: "baz")  // => /foo/baz
 
@@ -233,7 +236,7 @@ public extension Pathish {
      */
     @discardableResult
     func symlink<P: Pathish>(into dir: P) throws -> Path {
-        switch dir.kind {
+        switch dir.type {
         case nil, .symlink?:
             try dir.mkdir(.p)
             fallthrough

Sources/Path+ls.swift

@@ -1,32 +1,117 @@
 import Foundation
 
 public extension Path {
+    /// 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.
         public let path: Path
-        fileprivate(set) public var maxDepth: Int? = nil
-        fileprivate(set) public var kinds: Set<Path.Kind>?
-        fileprivate(set) public var extensions: Set<String>?
+
+        private let enumerator: FileManager.DirectoryEnumerator!
+
+        /// The range of directory depths for which the find operation will return entries.
+        private(set) public var depth: ClosedRange<Int> = 1...Int.max {
+            didSet {
+                if depth.lowerBound < 0 {
+                    depth = 0...depth.upperBound
+                }
+            }
+        }
+
+        /// The kinds of filesystem entries find operations will return.
+        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>?
+        
+        /// Whether to return hidden files
+        public var hidden:Bool = true
     }
 }
 
+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 {
+                continue
+            }
+          
+            if !hidden, path.basename().hasPrefix(".") {
+                enumerator.skipDescendants()
+                continue
+            }
+          #endif
+            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 {
-    /// Multiple calls will configure the Finder for the final depth call only.
-    func maxDepth(_ maxDepth: Int) -> 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: maxDepth not implemented for Swift < 5\n", stderr)
+        fputs("warning: depth not implemented for Swift < 5\n", stderr)
     #endif
-        self.maxDepth = maxDepth
+        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 kind(_ kind: Path.Kind) -> Path.Finder {
-        kinds = kinds ?? []
-        kinds!.insert(kind)
+    func type(_ type: Path.EntryType) -> Path.Finder {
+        _types = _types ?? []
+        _types!.insert(type)
         return self
     }
 
@@ -36,12 +121,14 @@ public extension Path.Finder {
         extensions!.insert(ext)
         return self
     }
-
-    /// Enumerate and return all results, note that this may take a while since we are recursive.
-    func execute() -> [Path] {
-        var rv: [Path] = []
-        execute{ rv.append($0); return .continue }
-        return rv
+    
+    /// Whether to skip hidden files and folders.
+    func hidden(_ hidden: Bool) -> Path.Finder {
+        #if os(Linux) && !swift(>=5.0)
+          fputs("warning: hidden not implemented for Swift < 5\n", stderr)
+        #endif
+        self.hidden = hidden
+        return self
     }
 
     /// The return type for `Path.Finder`
@@ -56,35 +143,26 @@ public extension Path.Finder {
 
     /// Enumerate, one file at a time.
     func execute(_ closure: (Path) throws -> ControlFlow) rethrows {
-        guard let finder = FileManager.default.enumerator(atPath: path.string) else {
-            fputs("warning: could not enumerate: \(path)\n", stderr)
-            return
-        }
-        while let relativePath = finder.nextObject() as? String {
-        #if !os(Linux) || swift(>=5.0)
-            if let maxDepth = maxDepth, finder.level > maxDepth {
-                finder.skipDescendants()
-            }
-        #endif
-            let path = self.path/relativePath
-            if path == self.path { continue }
-            if let kinds = kinds, let kind = path.kind, !kinds.contains(kind) { continue }
-            if let exts = extensions, !exts.contains(path.extension) { continue }
-
+        while let path = next() {
             switch try closure(path) {
             case .skip:
-                finder.skipDescendants()
+              #if !os(Linux) || swift(>=5.0)
+                enumerator.skipDescendants()
+              #else
+                fputs("warning: skip is not implemented for Swift < 5.0\n", stderr)
+              #endif
             case .abort:
                 return
             case .continue:
-                break
+                continue
             }
         }
     }
 }
 
-public extension Pathish {    
-    //MARK: Directory Listings
+public extension Pathish {
+
+    //MARK: Directory Listing
 
     /**
      Same as the `ls` command ∴ output is ”shallow” and unsorted.
@@ -102,15 +180,16 @@ public extension Pathish {
             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 path
-        }
+        }.sorted()
     }
 
+    /// Recursively find files under this path. If the path is a file, no files will be found.
     func find() -> Path.Finder {
         return .init(path: Path(self))
     }
 }
 
-/// Convenience functions for the arraies of `Path`
+/// 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] {
@@ -123,13 +202,18 @@ public extension Array where Element == Path {
     /// - Note: symlinks that point to files that do not exist are *not* returned.
     var files: [Path] {
         return filter {
-            $0.exists && !$0.isDirectory
+            switch $0.type {
+            case .none, .directory?:
+                return false
+            case .file?, .symlink?:
+                return true
+            }
         }
     }
 }
 
-/// Options for `Path.mkdir(_:)`
+/// Options for `Path.ls(_:)`
 public enum ListDirectoryOptions {
-    /// Creates intermediary directories; works the same as `mkdir -p`.
+    /// Lists hidden files also
     case a
 }

Sources/Path.swift

@@ -7,6 +7,8 @@ import func Glibc.realpath
 let _realpath = Glibc.realpath
 #endif
 
+public typealias PathStruct = Path
+
 /**
  A `Path` represents an absolute path on a filesystem.
 
@@ -36,6 +38,7 @@ let _realpath = Glibc.realpath
  to the anti-pattern where Path.swift suddenly feels like Javascript otherwise.
 
  - Note: A `Path` does not necessarily represent an actual filesystem entry.
+ - SeeAlso: `Pathish` for most methods you will use on `Path` instances.
  */
 public struct Path: Pathish {
 
@@ -135,6 +138,8 @@ public struct Path: Pathish {
 }
 
 public extension Pathish {
+    //MARK: Filesystem Representation
+
     /// Returns a `URL` representing this file path.
     var url: URL {
         return URL(fileURLWithPath: string)
@@ -165,6 +170,7 @@ public extension Pathish {
      */
     var parent: Path {
         let index = string.lastIndex(of: "/")!
+        guard index != string.indices.startIndex else { return Path(string: "/") }
         let substr = string[string.indices.startIndex..<index]
         return Path(string: String(substr))
     }
@@ -173,7 +179,7 @@ public extension Pathish {
      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
     var `extension`: String {
@@ -200,14 +206,14 @@ public extension Pathish {
 
     /**
      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
     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.
@@ -404,7 +410,7 @@ 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
+/// 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
@@ -416,7 +422,7 @@ public struct DynamicPath: Pathish {
     }
 
     /// Converts a `Path` to a `DynamicPath`
-    public init(_ path: Path) {
+    public init<P: Pathish>(_ path: P) {
         string = path.string
     }
 

Sources/PathToBool.swift

@@ -6,11 +6,13 @@ import Darwin
 #endif
 
 public extension Pathish {
+
     //MARK: Filesystem Properties
 
     /**
      - Returns: `true` if the path represents an actual filesystem entry.
-     - Note: If `self` is a symlink the return value represents the destination.
+     - 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/Pathish.swift

@@ -1,13 +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 }
 }
-
-public extension Pathish {
-    static func ==<P: Pathish> (lhs: Self, rhs: P) -> Bool {
-        return lhs.string == rhs.string
-    }
-}

Tests/PathTests/PathTests+ls().swift

@@ -2,69 +2,250 @@ import XCTest
 import Path
 
 extension PathTests {
-    func testFindMaxDepth0() throws {
-    #if !os(Linux) || swift(>=5)
+    func testFindMaxDepth1() throws {
         try Path.mktemp { tmpdir in
             try tmpdir.a.touch()
             try tmpdir.b.touch()
             try tmpdir.c.mkdir().join("e").touch()
 
-            XCTAssertEqual(
-                Set(tmpdir.find().maxDepth(0).execute()),
-                Set([tmpdir.a, tmpdir.b, tmpdir.c].map(Path.init)))
+            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
+            }
         }
-    #endif
     }
 
-    func testFindMaxDepth1() throws {
-    #if !os(Linux) || swift(>=5)
+    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()
 
-        #if !os(Linux)
-            XCTAssertEqual(
-                Set(tmpdir.find().maxDepth(1).execute()),
-                Set([tmpdir.a, tmpdir.b, tmpdir.b.c].map(Path.init)))
-        #else
-            // Linux behavior is different :-/
-            XCTAssertEqual(
-                Set(tmpdir.find().maxDepth(1).execute()),
-                Set([tmpdir.a, tmpdir.b, tmpdir.b.d, tmpdir.b.c].map(Path.init)))
-        #endif
+            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
+            }
         }
-    #endif
     }
 
+    func testFindMinDepth() 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()
+            try tmpdir.b.d.f.mkdir().join("g").touch()
+
+            do {
+                let finder = tmpdir.find().depth(min: 2)
+                XCTAssertEqual(finder.depth, 2...Int.max)
+              #if !os(Linux) || swift(>=5)
+                XCTAssertEqual(
+                    Set(finder),
+                    Set([tmpdir.b.c, tmpdir.b.d, tmpdir.b.d.e, tmpdir.b.d.f, tmpdir.b.d.f.g].map(Path.init)),
+                    relativeTo: tmpdir)
+              #endif
+            }
+        }
+    }
+
+    func testFindDepth0() 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()
+            try tmpdir.b.d.f.mkdir().join("g").touch()
+
+            do {
+                let finder = tmpdir.find().depth(min: 0)
+                XCTAssertEqual(finder.depth, 0...Int.max)
+              #if !os(Linux) || swift(>=5)
+                XCTAssertEqual(
+                    Set(finder),
+                    Set([tmpdir.a, tmpdir.b, tmpdir.b.c, tmpdir.b.d, tmpdir.b.d.e, tmpdir.b.d.f, tmpdir.b.d.f.g].map(Path.init)),
+                    relativeTo: tmpdir)
+              #endif
+            }
+            do {
+                // this should work, even though it’s weird
+                let finder = tmpdir.find().depth(min: -1)
+                XCTAssertEqual(finder.depth, 0...Int.max)
+              #if !os(Linux) || swift(>=5)
+                XCTAssertEqual(
+                    Set(finder),
+                    Set([tmpdir.a, tmpdir.b, tmpdir.b.c, tmpdir.b.d, tmpdir.b.d.e, tmpdir.b.d.f, tmpdir.b.d.f.g].map(Path.init)),
+                    relativeTo: tmpdir)
+              #endif
+            }
+        }
+    }
+
+    func testFindDepthRange() 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()
+            try tmpdir.b.d.f.mkdir().join("g").touch()
+
+            do {
+                let range = 2...3
+                let finder = tmpdir.find().depth(range)
+                XCTAssertEqual(finder.depth, range)
+              #if !os(Linux) || swift(>=5)
+                XCTAssertEqual(
+                    Set(finder),
+                    Set([tmpdir.b.d, tmpdir.b.c, tmpdir.b.d.e, tmpdir.b.d.f].map(Path.init)),
+                    relativeTo: tmpdir)
+              #endif
+            }
+
+            do {
+                let range = 2..<4
+                let finder = tmpdir.find().depth(range)
+                XCTAssertEqual(finder.depth, 2...3)
+              #if !os(Linux) || swift(>=5)
+                XCTAssertEqual(
+                    Set(finder),
+                    Set([tmpdir.b.d, tmpdir.b.c, tmpdir.b.d.e, tmpdir.b.d.f].map(Path.init)),
+                    relativeTo: tmpdir)
+              #endif
+            }
+        }
+    }
+
+    func testFindHidden() throws {
+        try Path.mktemp { tmpdir in
+            let dotFoo = try tmpdir.join(".foo.txt").touch()
+            let tmpDotA = try tmpdir.join(".a").mkdir()
+            let tmpDotAFoo = try tmpdir.join(".a").join("foo.txt").touch()
+            let tmpB = try tmpdir.b.mkdir()
+            let tmpBFoo = try tmpdir.b.join("foo.txt").touch()
+
+            XCTAssertEqual(
+                Set(tmpdir.find().hidden(true)),
+                Set([dotFoo,tmpDotA,tmpDotAFoo,tmpB,tmpBFoo]),
+                relativeTo: tmpdir)
+            
+            #if !os(Linux) || swift(>=5)
+            XCTAssertEqual(
+                Set(tmpdir.find().hidden(false)),
+                Set([tmpB,tmpBFoo]),
+                relativeTo: tmpdir)
+            #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").execute()),
+                Set(tmpdir.find().extension("json")),
                 [tmpdir.join("foo.json")])
             XCTAssertEqual(
-                Set(tmpdir.find().extension("txt").extension("json").execute()),
+                Set(tmpdir.find().extension("txt").extension("json")),
                 [tmpdir.join("foo.json"), tmpdir.join("bar.txt")])
         }
     }
 
-    func testFindKinds() throws {
+    //NOTE this is how iterators work, so we have a test to validate that behavior
+    func testFindCallingExecuteTwice() throws {
+        try Path.mktemp { tmpdir in
+            try tmpdir.join("foo.json").touch()
+            try tmpdir.join("bar.txt").touch()
+
+            let finder = tmpdir.find()
+
+            XCTAssertEqual(finder.map{ $0 }.count, 2)
+            XCTAssertEqual(finder.map{ $0 }.count, 0)
+        }
+    }
+
+    func testFindExecute() 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()
+            try tmpdir.b.d.f.mkdir().join("g").touch()
+          #if !os(Linux) || swift(>=5)
+            do {
+                var rv = Set<Path>()
+
+                tmpdir.find().execute {
+                    switch $0 {
+                        case Path(tmpdir.b.d): return .skip
+                        default:
+                            rv.insert($0)
+                            return .continue
+                    }
+                }
+
+                XCTAssertEqual(rv, Set([tmpdir.a, tmpdir.b, tmpdir.b.c].map(Path.init)))
+            }
+          #endif
+            do {
+                var x = 0
+
+                tmpdir.find().execute { _ in
+                    x += 1
+                    return .abort
+                }
+
+                XCTAssertEqual(x, 1)
+            }
+        }
+    }
+
+    func testFindTypes() throws {
         try Path.mktemp { tmpdir in
             try tmpdir.foo.mkdir()
             try tmpdir.bar.touch()
 
             XCTAssertEqual(
-                Set(tmpdir.find().kind(.file).execute()),
+                Set(tmpdir.find().type(.file)),
                 [tmpdir.join("bar")])
             XCTAssertEqual(
-                Set(tmpdir.find().kind(.directory).execute()),
+                Set(tmpdir.find().type(.directory)),
                 [tmpdir.join("foo")])
             XCTAssertEqual(
-                Set(tmpdir.find().kind(.file).kind(.directory).execute()),
+                Set(tmpdir.find().type(.file).type(.directory)),
                 Set(["foo", "bar"].map(tmpdir.join)))
         }
     }
+
+    func testLsOnNonexistentDirectoryReturnsEmptyArray() throws {
+        try Path.mktemp { tmpdir in
+            XCTAssertEqual(tmpdir.a.ls(), [])
+        }
+    }
+
+    func testFindOnNonexistentDirectoryHasNoContent() throws {
+        try Path.mktemp { tmpdir in
+            XCTAssertNil(tmpdir.a.find().next())
+        }
+    }
 }

Tests/PathTests/PathTests.swift

@@ -3,7 +3,20 @@ import func XCTest.XCTAssertEqual
 import Foundation
 import XCTest
 
+extension PathStruct {
+    var foo: Int { fatalError()}
+}
+
 class PathTests: XCTestCase {
+    func testNewStuff() {
+    #if swift(>=5.5)
+        func foo<P: Pathish>(_ path: P) {}
+
+        foo(.home)
+        foo(.root)
+    #endif
+    }
+
     func testConcatenation() {
         XCTAssertEqual((Path.root/"bar").string, "/bar")
         XCTAssertEqual(Path.cwd.string, FileManager.default.currentDirectoryPath)
@@ -76,10 +89,10 @@ class PathTests: XCTestCase {
         try Path.mktemp { tmpdir in
             XCTAssertTrue(tmpdir.exists)
             XCTAssertFalse(try tmpdir.bar.symlink(as: tmpdir.foo).exists)
-            XCTAssertTrue(tmpdir.foo.kind == .symlink)
+            XCTAssertTrue(tmpdir.foo.type == .symlink)
             XCTAssertTrue(try tmpdir.bar.touch().symlink(as: tmpdir.baz).exists)
-            XCTAssertTrue(tmpdir.bar.kind == .file)
-            XCTAssertTrue(tmpdir.kind == .directory)
+            XCTAssertTrue(tmpdir.bar.type == .file)
+            XCTAssertTrue(tmpdir.type == .directory)
         }
     }
 
@@ -146,15 +159,21 @@ class PathTests: XCTestCase {
         ].map(Path.init)
 
         let encoder = JSONEncoder()
-        encoder.userInfo[.relativePath] = root
-        let data = try encoder.encode(input)
 
-        XCTAssertEqual(try JSONSerialization.jsonObject(with: data) as? [String], ["..", "", "bar"])
+        func test<P: Pathish>(relativePath: P, line: UInt = #line) throws {
+            encoder.userInfo[.relativePath] = relativePath
+            let data = try encoder.encode(input)
 
-        let decoder = JSONDecoder()
-        XCTAssertThrowsError(try decoder.decode([Path].self, from: data))
-        decoder.userInfo[.relativePath] = root
-        XCTAssertEqual(try decoder.decode([Path].self, from: data), input)
+            XCTAssertEqual(try JSONSerialization.jsonObject(with: data) as? [String], ["..", "", "bar"], line: line)
+
+            let decoder = JSONDecoder()
+            XCTAssertThrowsError(try decoder.decode([Path].self, from: data), line: line)
+            decoder.userInfo[.relativePath] = relativePath
+            XCTAssertEqual(try decoder.decode([Path].self, from: data), input, line: line)
+        }
+
+        try test(relativePath: root)       // DynamicPath
+        try test(relativePath: Path(root)) // Path
     }
 
     func testJoin() {
@@ -186,6 +205,14 @@ class PathTests: XCTestCase {
         XCTAssertEqual(Path.root/"a/foo"/"../../../bar", Path.root/"bar")
     }
 
+    func testParent() {
+        XCTAssertEqual(Path("/root/boot")!.parent.string, "/root")
+        XCTAssertEqual(Path("/root/boot")!.parent.parent.string, "/")
+        XCTAssertEqual(Path("/root/boot")!.parent.parent.parent.string, "/")
+        XCTAssertEqual(Path("/root")!.parent.string, "/")
+        XCTAssertEqual(Path("/root")!.parent.parent.string, "/")
+    }
+
     func testDynamicMember() {
         XCTAssertEqual(Path.root.Documents, Path.root/"Documents")
 
@@ -193,7 +220,7 @@ class PathTests: XCTestCase {
         XCTAssertEqual(a.Documents, Path.home/"foo/Documents")
 
         // verify use of the dynamic-member-subscript works according to our rules
-        XCTAssertEqual(Path.home[dynamicMember: "../~foo"].string, "\(Path.home.parent.string)/~foo")
+        XCTAssertEqual(Path.home[dynamicMember: "../~foo"].string, Path(Path.home).parent.join("~foo").string)
     }
 
     func testCopyTo() throws {
@@ -299,6 +326,13 @@ class PathTests: XCTestCase {
         XCTAssertEqual(Path.root.string, "/")
         XCTAssertEqual(Path.home.string, NSHomeDirectory())
         XCTAssertEqual(Path.documents.string, NSHomeDirectory() + "/Documents")
+    #if swift(>=5.3)
+        let filePath = Path(#filePath)!
+    #else
+        let filePath = Path(#file)!
+    #endif
+        XCTAssertEqual(Path.source().file, filePath)
+        XCTAssertEqual(Path.source().directory, filePath.parent)
     #if !os(Linux)
         XCTAssertEqual(Path.caches.string, NSHomeDirectory() + "/Library/Caches")
         XCTAssertEqual(Path.cwd.string, FileManager.default.currentDirectoryPath)
@@ -313,6 +347,8 @@ class PathTests: XCTestCase {
     func testStringConvertibles() {
         XCTAssertEqual(Path.root.description, "/")
         XCTAssertEqual(Path.root.debugDescription, "Path(/)")
+        XCTAssertEqual(Path(Path.root).description, "/")
+        XCTAssertEqual(Path(Path.root).debugDescription, "Path(/)")
     }
 
     func testFilesystemAttributes() throws {
@@ -365,17 +401,13 @@ class PathTests: XCTestCase {
 
     func testTimes() throws {
         try Path.mktemp { tmpdir in
-            let foo = try tmpdir.foo.touch()
             let now1 = Date().timeIntervalSince1970.rounded(.down)
-        #if !os(Linux)
-            XCTAssertEqual(foo.ctime?.timeIntervalSince1970.rounded(.down), now1)  //FIXME flakey
-        #endif
-            XCTAssertEqual(foo.mtime?.timeIntervalSince1970.rounded(.down), now1)  //FIXME flakey
             sleep(1)
-            try foo.touch()
-            let now2 = Date().timeIntervalSince1970.rounded(.down)
-            XCTAssertNotEqual(now1, now2)
-            XCTAssertEqual(foo.mtime?.timeIntervalSince1970.rounded(.down), now2)  //FIXME flakey
+            let foo = try tmpdir.foo.touch()
+        #if !os(Linux)
+            XCTAssertGreaterThan(foo.ctime?.timeIntervalSince1970.rounded(.down) ?? 0, now1)  //FIXME flakey
+        #endif
+            XCTAssertGreaterThan(foo.mtime?.timeIntervalSince1970.rounded(.down) ?? 0, now1)  //FIXME flakey
 
             XCTAssertNil(tmpdir.void.mtime)
             XCTAssertNil(tmpdir.void.ctime)
@@ -393,17 +425,20 @@ class PathTests: XCTestCase {
 
             // regression test: can delete a symlink that points to a non-existent file
             let bar5 = try tmpdir.bar4.symlink(as: tmpdir.bar5)
-            XCTAssertEqual(bar5.kind, .symlink)
+            XCTAssertEqual(bar5.type, .symlink)
             XCTAssertFalse(bar5.exists)
             XCTAssertNoThrow(try bar5.delete())
-            XCTAssertEqual(bar5.kind, nil)
+            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.kind, .symlink)
+            XCTAssertEqual(bar7.type, .symlink)
             XCTAssertTrue(bar7.exists)
             XCTAssertNoThrow(try bar7.delete())
-            XCTAssertEqual(bar7.kind, nil)
+            XCTAssertEqual(bar7.type, nil)
+            XCTAssertEqual(tmpdir.bar6.type, .file)
+
+            // for code-coverage
             XCTAssertEqual(tmpdir.bar6.kind, .file)
         }
     }
@@ -436,7 +471,7 @@ class PathTests: XCTestCase {
         #if os(macOS)
             XCTAssertEqual(bndl.defaultSharedFrameworksPath, tmpdir.Contents.Frameworks)
             XCTAssertEqual(bndl.defaultResourcesPath, tmpdir.Contents.Resources)
-        #elseif os(tvOS) || os(iOS)
+        #elseif os(tvOS) || os(iOS) || os(watchOS)
             XCTAssertEqual(bndl.defaultSharedFrameworksPath, tmpdir.Frameworks)
             XCTAssertEqual(bndl.defaultResourcesPath, tmpdir)
         #else
@@ -488,8 +523,19 @@ class PathTests: XCTestCase {
 
     func testTouchThrowsIfCannotWrite() throws {
         try Path.mktemp { tmpdir in
+
+            print(try FileManager.default.attributesOfItem(atPath: tmpdir.string)[.posixPermissions])
+
+            //FIXME fails in Docker image (only)
             try tmpdir.chmod(0o000)
+
+            let attrs = try FileManager.default.attributesOfItem(atPath: tmpdir.string)
+            XCTAssertEqual(attrs[.posixPermissions] as? Int, 0)
+
+            print(attrs[.posixPermissions])
+
             XCTAssertThrowsError(try tmpdir.bar.touch())
+            XCTAssertFalse(tmpdir.bar.exists)
         }
     }
 
@@ -619,8 +665,8 @@ class PathTests: XCTestCase {
     }
 
     func testPathComponents() throws {
-        XCTAssertEqual(Path.root.foo.bar.components, ["/", "foo", "bar"])
-        XCTAssertEqual(Path.root.components, ["/"])
+        XCTAssertEqual(Path.root.foo.bar.components, ["foo", "bar"])
+        XCTAssertEqual(Path.root.components, [])
     }
 
     func testFlatMap() throws {
@@ -637,17 +683,15 @@ class PathTests: XCTestCase {
         try Path.mktemp { tmpdir in
             let foo = try tmpdir.foo.touch()
             let bar = try foo.symlink(as: tmpdir.bar)
-            XCTAssertEqual(tmpdir.kind, .directory)
-            XCTAssertEqual(foo.kind, .file)
-            XCTAssertEqual(bar.kind, .symlink)
+            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)
+    
+    func testOptionalInitializer() throws {
+        XCTAssertNil(Path(""))
+        XCTAssertNil(Path("./foo"))
+        XCTAssertEqual(Path("/foo"), Path.root.foo)
+    }
 }

Tests/PathTests/XCTestManifests.swift

@@ -24,21 +24,32 @@ extension PathTests {
         ("testFileHandleExtensions", testFileHandleExtensions),
         ("testFileReference", testFileReference),
         ("testFilesystemAttributes", testFilesystemAttributes),
+        ("testFindCallingExecuteTwice", testFindCallingExecuteTwice),
+        ("testFindDepth0", testFindDepth0),
+        ("testFindDepthRange", testFindDepthRange),
+        ("testFindExecute", testFindExecute),
         ("testFindExtension", testFindExtension),
-        ("testFindKinds", testFindKinds),
-        ("testFindMaxDepth0", testFindMaxDepth0),
+        ("testFindHidden", testFindHidden),
         ("testFindMaxDepth1", testFindMaxDepth1),
+        ("testFindMaxDepth2", testFindMaxDepth2),
+        ("testFindMinDepth", testFindMinDepth),
+        ("testFindOnNonexistentDirectoryHasNoContent", testFindOnNonexistentDirectoryHasNoContent),
+        ("testFindTypes", testFindTypes),
         ("testFlatMap", testFlatMap),
         ("testInitializerForRelativePath", testInitializerForRelativePath),
         ("testIsDirectory", testIsDirectory),
         ("testJoin", testJoin),
         ("testKind", testKind),
         ("testLock", testLock),
+        ("testLsOnNonexistentDirectoryReturnsEmptyArray", testLsOnNonexistentDirectoryReturnsEmptyArray),
         ("testMkpathIfExists", testMkpathIfExists),
         ("testMktemp", testMktemp),
         ("testMoveInto", testMoveInto),
         ("testMoveTo", testMoveTo),
+        ("testNewStuff", testNewStuff),
         ("testNoUndesiredSymlinkResolution", testNoUndesiredSymlinkResolution),
+        ("testOptionalInitializer", testOptionalInitializer),
+        ("testParent", testParent),
         ("testPathComponents", testPathComponents),
         ("testReadlinkOnFileReturnsSelf", testReadlinkOnFileReturnsSelf),
         ("testReadlinkOnNonExistantFileThrows", testReadlinkOnNonExistantFileThrows),

Tests/PathTests/etc.swift

@@ -0,0 +1,43 @@
+import XCTest
+import Path
+
+#if swift(>=5.3)
+func XCTAssertEqual<P: Pathish>(_ set1: Set<Path>, _ set2: Set<Path>, _ message: @autoclosure () -> String = "", file: StaticString = #filePath, line: UInt = #line, relativeTo: P) {
+    logic(set1, set2, relativeTo: relativeTo) {
+        XCTFail($0, file: file, line: line)
+    }
+}
+#else
+func XCTAssertEqual<P: Pathish>(_ set1: Set<Path>, _ set2: Set<Path>, _ message: @autoclosure () -> String = "", file: StaticString = #file, line: UInt = #line, relativeTo: P) {
+    logic(set1, set2, relativeTo: relativeTo) {
+        XCTFail($0, file: file, line: line)
+    }
+}
+#endif
+
+private func logic<P: Pathish>(_ set1: Set<Path>, _ set2: Set<Path>, relativeTo: P, fail: (String) -> Void) {
+    if set1 != set2 {
+        let cvt: (Path) -> String = { $0.relative(to: relativeTo) }
+        let out1 = set1.map(cvt).sorted()
+        let out2 = set2.map(cvt).sorted()
+        fail("Set(\(out1)) is not equal to Set(\(out2))")
+    }
+}
+
+#if swift(>=5.3)
+func XCTAssertEqual<P: Pathish, Q: Pathish>(_ p: P, _ q: Q, file: StaticString = #filePath, line: UInt = #line) {
+    XCTAssertEqual(p.string, q.string, file: file, line: line)
+}
+
+func XCTAssertEqual<P: Pathish, Q: Pathish>(_ p: P?, _ q: Q?, file: StaticString = #filePath, line: UInt = #line) {
+    XCTAssertEqual(p?.string, q?.string, file: file, line: line)
+}
+#else
+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)
+}
+
+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)
+}
+#endif