Merge pull request #77 from ConfusedVorlon/find_hidden_modifier

Find hidden modifier

.github/codecov.yml

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

.github/jazzy.yml

@@ -0,0 +1,13 @@
+module: Path
+custom_categories:
+  - name: Path
+    children:
+      - Path
+      - Pathish
+xcodebuild_arguments:
+  - UseModernBuildSystem=NO
+output:
+  ../output
+  # output directory is relative to config file… ugh
+exclude:
+  - Sources/Path+StringConvertibles.swift

.github/ranger.yml

@@ -0,0 +1,2 @@
+merges:
+  - action: delete_branch

.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

.gitignore

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

.travis.yml

@@ -1,77 +1,43 @@
-# only run for: merge commits, releases and pull-requests
+# Travis does CD, GHA does CI
-if: type != push OR branch = master OR branch =~ /^\d+\.\d+(\.\d+)?(-\S*)?$/
+if: branch =~ /^deploy-\d+\.\d+\.\d+(-.*)?$/ OR branch =~ /^\d+\.\d+\.\d+(-.*)?$/
 
 stages:
-  - name: pretest
-  - name: test
   - name: deploy
-    if: branch =~ ^\d+\.\d+\.\d+$
+    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:
-    - script: swift test
-      name: macOS
-
-    - &xcodebuild
-      before_install: swift package generate-xcodeproj
-      xcode_destination: platform=iOS Simulator,OS=latest,name=iPhone XS
-      name: iOS
-    - <<: *xcodebuild
-      xcode_destination: platform=tvOS Simulator,OS=latest,name=Apple TV
-      name: tvOS
-    - <<: *xcodebuild
-      name: watchOS
-      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
-
-    - env: SWIFT_VERSION=4.2.1
-      os: linux
-      name: Linux
-      language: generic
-      dist: trusty
-      sudo: false
-      install: eval "$(curl -sL https://swiftenv.fuller.li/install.sh)"
-      script: swift test
-      
-    - stage: pretest
-      name: Check if Linux tests are up-to-date
-      install: swift test --generate-linuxmain
-      script: git diff --exit-code
-
     - 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
-      before_install: |
+      osx_image: xcode11
-        cat <<\ \ EOF> .jazzy.yaml
-        module: Path
-        module_version: TRAVIS_TAG
-        custom_categories:
-          - name: Path
-            children:
-              - Path
-              - /(_:_:)
-        xcodebuild_arguments:
-          - UseModernBuildSystem=NO
-        output: output
-        github_url: https://github.com/mxcl/Path.swift
-        EOF
-        sed -i '' "s/TRAVIS_TAG/$TRAVIS_TAG/" .jazzy.yaml
-      # ^^ this weirdness because Travis multiline YAML is broken and inserts two
-      # spaces in front of the output which means we need a prefixed delimiter which
-      # also weirdly stops bash from doing variable substitution
       install: gem install jazzy
       before_script: swift package generate-xcodeproj
-      script: jazzy
+      script: |
+        jazzy --config .github/jazzy.yml \
+              --module-version $TRAVIS_TAG \
+              --github_url "https://github.com/$TRAVIS_REPO_SLUG"
       deploy:
         provider: pages
         skip-cleanup: true
@@ -81,26 +47,11 @@ jobs:
           tags: true
 
     - name: CocoaPods
-      before_install: |
+      env: HOMEBREW_NO_INSTALL_CLEANUP=1
-        cat <<\ \ EOF> Path.swift.podspec
+      osx_image: xcode11
-        Pod::Spec.new do |s|
+      install:
-          s.name = 'Path.swift'
+        - brew install mxcl/made/swift-sh
-          s.version = 'TRAVIS_TAG'
+        - curl -O https://raw.githubusercontent.com/mxcl/ops/master/deploy
-          s.summary = 'Delightful, robust file-pathing functions'
+        - chmod u+x deploy
-          s.homepage = 'https://github.com/mxcl/Path.swift'
+      before_script: ./deploy generate-podspec
-          s.license = { :type => 'Unlicense', :file => 'LICENSE.md' }
-          s.author = { 'mxcl' => 'mxcl@me.com' }
-          s.source = { :git => 'https://github.com/mxcl/Path.swift.git', :tag => s.version.to_s }
-          s.social_media_url = 'https://twitter.com/mxcl'
-          s.osx.deployment_target = '10.10'
-          s.ios.deployment_target = '8.0'
-          s.tvos.deployment_target = '10.0'
-          s.watchos.deployment_target = '3.0'
-          s.source_files = 'Sources/*'
-          s.swift_version = '4.2'
-        end
-        EOF
-        sed -i '' "s/TRAVIS_TAG/$TRAVIS_TAG/" Path.swift.podspec
-      # ^^ see the Jazzy deployment for explanation
-      install: gem install cocoapods --pre
       script: pod trunk push

Package.swift

@@ -9,5 +9,6 @@ let package = Package(
     targets: [
         .target(name: "Path", path: "Sources"),
         .testTarget(name: "PathTests", dependencies: ["Path"]),
-    ]
+    ],
+    swiftLanguageVersions: [.v4, .v4_2, .version("5")]
 )

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

@@ -1,7 +1,7 @@
-# Path.swift ![badge-platforms] ![badge-languages] [![Build Status](https://travis-ci.com/mxcl/Path.swift.svg)](https://travis-ci.com/mxcl/Path.swift)
+# Path.swift ![badge-platforms][] ![badge-languages][] [![badge-ci][]][travis] [![badge-jazzy][]][docs] [![badge-codecov][]][codecov] [![badge-version][]][cocoapods]
 
-A file-system pathing library focused on developer experience and robust
+A file-system pathing library focused on developer experience and robust end
-end‐results.
+results.
 
 ```swift
 import Path
@@ -28,32 +28,35 @@ print(bar)         // => /bar
 print(bar.isFile)  // => true
 
 // careful API considerations so as to avoid common bugs
-let foo = try Path.root.join("foo").copy(into: Path.root.mkdir("bar"))
+let foo = try Path.root.join("foo").copy(into: Path.root.join("bar").mkdir())
 print(foo)         // => /bar/foo
 print(foo.isFile)  // => true
+// ^^ 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.
 
-// A practical example: installing a helper executable
+// we support dynamic-member-syntax when joining named static members, eg:
-try Bundle.resources.join("helper").copy(into: Path.home.join(".local/bin").mkpath()).chmod(0o500)
+let prefs = Path.home.Library.Preferences  // => /Users/mxcl/Library/Preferences
+
+// a practical example: installing a helper executable
+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
+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?). Please help me so I
+a good deal of my free time 👨🏻‍💻. Sponsorship helps me justify creating new open
-can continue to make tools and software you need and love. I appreciate it x.
+source and maintaining it. Thank you.
 
-<a href="https://www.patreon.com/mxcl">
+[Sponsor @mxcl].
-	<img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160">
-</a>
-
-[Other donation/tipping options](http://mxcl.github.io/donate/)
 
 # Handbook
 
-Our [online API documentation] is automatically updated for new releases.
+Our [online API documentation][docs] covers 100% of our public API and is
+automatically updated for new releases.
 
 ## Codable
 
@@ -70,30 +73,69 @@ 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`
+**Note** if you encode with this key set you *must* decode with the key
-(unless the paths are absolute obv.)
+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`:
+
+```swift
+let ls = Path.root.usr.bin.ls  // => /usr/bin/ls
+```
+
+We only provide this for “starting” function, eg. `Path.home` or `Bundle.path`.
+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 (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
 
 The `Path` initializer returns `nil` unless fed an absolute path; thus to
@@ -107,10 +149,30 @@ This is explicit, not hiding anything that code-review may miss and preventing
 common bugs like accidentally creating `Path` objects from strings you did not
 expect to be relative.
 
-Our initializer is nameless because we conform to `LosslessStringConvertible`,
+Our initializer is nameless to be consistent with the equivalent operation for
-the same conformance as that `Int`, `Float` etc. conform. The protocol enforces
+converting strings to `Int`, `Float` etc. in the standard library.
-a nameless initialization and since it is appropriate for us to conform to it,
+
-we do.
+## 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
 
@@ -124,39 +186,100 @@ bashProfile += "\n\nfoo"
 
 try bashProfile.write(to: Path.home/".bash_profile")
 
-try Bundle.main.resources!.join("foo").copy(to: .home)
+try Bundle.main.resources.join("foo").copy(to: .home)
-// ^^ `-> Path?` because the underlying `Bundle` function is `-> String?`
 ```
 
 ## Directory listings
 
 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 {
     //…
 }
 
-let dirs = Path.home.ls().directories().filter {
+for path in Path.home.ls() where path.mtime > yesterday {
     //…
 }
 
-let swiftFiles = Path.home.ls().files(withExtension: "swift")
+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.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
+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) {
+    //…
+}
+```
+
+It can be controlled with a closure syntax:
+
+```swift
+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 }
+    //…
+    return .continue
+}
+```
+
+Or get everything at once as an array:
+
+```swift
+let paths = Path.home.find().map(\.self)
+```
+
+# `Path.swift` is robust
+
+Some parts of `FileManager` are not exactly idiomatic. For example
+`isExecutableFile` returns `true` even if there is no file there, it is instead
+telling you that *if* you made a file there it *could* be executable. Thus we
+check the POSIX permissions of the file first, before returning the result of
+`isExecutableFile`. `Path.swift` has done the leg-work for you so you can 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].
+
+[this test]: https://github.com/mxcl/Path.swift/blob/master/Tests/PathTests/PathTests.swift#L539-L554
+
+# `Path.swift` is properly cross-platform
+
+`FileManager` on Linux is full of holes. We have found the holes and worked
+round them where necessary.
+
 # Rules & Caveats
 
-Paths are just string representations, there *might not* be a real file there.
+Paths are just (normalized) string representations, there *might not* be a real
+file there.
 
 ```swift
 Path.home/"b"      // => /Users/mxcl/b
@@ -164,12 +287,19 @@ 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
 Path.home/"/b"     // => /Users/mxcl/b
 
+// joining with .. or . works as expected
+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"
@@ -182,38 +312,136 @@ Path.root/"~/b"    // => /~/b
 // but is here
 Path("~/foo")!     // => /Users/mxcl/foo
 
-// this does not work though
+// this works provided the user `Guest` exists
+Path("~Guest")     // => /Users/Guest
+
+// but if the user does not exist
 Path("~foo")       // => nil
+
+// paths with .. or . are resolved
+Path("/foo/bar/../baz")  // => /foo/baz
+
+// symlinks are not resolved
+Path.root.bar.symlink(as: "foo")
+Path("/foo")        // => /foo
+Path.root.foo       // => /foo
+
+// unless you do it explicitly
+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,
+then it’s a noop:
+
+* If you try to delete a file, but the file doesn't exist, we do nothing.
+* If you try to make a directory and it already exists, we do nothing.
+* If you call `readlink` on a non-symlink, we return `self`
+
+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.
+
+## Symbolic links
+
+* Two paths may represent the same *resolved* path yet not be equal due to
+    symlinks in such cases you should use `realpath` on both first if an
+    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')`).
+
+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
+
+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` to change *its* working directory when it
+executes.
+
+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?
+
+Apple recommend this because they provide a magic translation for
+[file-references embodied by URLs][file-refs], which gives you URLs like so:
+
+    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:
+
+```swift
+if let path = Path(url: url) {
+    /*…*/
+}
+```
+
+Our initializer calls `path` on the URL which resolves any reference to an
+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", from: "0.4.1"))
+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.4.1'
+pod 'Path.swift', '~> 1.0.0'
 ```
 
-Please note! We are pre 1.0, thus we can change the API as we like! We will tag
+Carthage:
-1.0 as soon as possible.
 
-### Get push notifications for new releases
+> Waiting on: [@Carthage#1945](https://github.com/Carthage/Carthage/pull/1945).
-
-https://codebasesaga.com/canopy/
 
 # Alternatives
 
+* [Pathos](https://github.com/dduan/Pathos) by Daniel Duan
 * [PathKit](https://github.com/kylef/PathKit) by Kyle Fuller
 * [Files](https://github.com/JohnSundell/Files) by John Sundell
 * [Utility](https://github.com/apple/swift-package-manager) by Apple
 
 
 [badge-platforms]: https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20iOS%20%7C%20tvOS%20%7C%20watchOS-lightgrey.svg
-[badge-languages]: https://img.shields.io/badge/swift-4.2-orange.svg
+[badge-languages]: https://img.shields.io/badge/swift-4.2%20%7C%205.x-orange.svg
-[online API documentation]: https://mxcl.github.io/Path.swift/Structs/Path.html
+[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://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/Extensions.swift

@@ -9,19 +9,35 @@ public extension Bundle {
         return str.flatMap(Path.init)
     }
 
-    /// Returns the path for the shared-frameworks directory in this bundle.
+    /**
-    public var sharedFrameworks: Path? {
+     Returns the path for the shared-frameworks directory in this bundle.
-        return sharedFrameworksPath.flatMap(Path.init)
+     - Note: This is typically `ShareFrameworks`
+    */
+    var sharedFrameworks: DynamicPath {
+        return sharedFrameworksPath.flatMap(DynamicPath.init) ?? defaultSharedFrameworksPath
+    }
+
+    /**
+     Returns the path for the private-frameworks directory in this bundle.
+     - Note: This is typically `Frameworks`
+    */
+    var privateFrameworks: DynamicPath {
+        return privateFrameworksPath.flatMap(DynamicPath.init) ?? defaultSharedFrameworksPath
     }
 
     /// Returns the path for the resources directory in this bundle.
-    public var resources: Path? {
+    var resources: DynamicPath {
-        return resourcePath.flatMap(Path.init)
+        return resourcePath.flatMap(DynamicPath.init) ?? defaultResourcesPath
     }
 
     /// Returns the path for this bundle.
-    public 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: DynamicPath? {
+        return executablePath.flatMap(DynamicPath.init)
     }
 }
 
@@ -29,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
     }
@@ -46,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)
@@ -68,3 +84,46 @@ public extension Data {
         return to
     }
 }
+
+/// Extensions on `FileHandle` that work with `Path` rather than `String` or `URL`
+public extension FileHandle {
+    /// Initializes this `FileHandle` for reading at the location of the provided path.
+    @inlinable
+    convenience init<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<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<P: Pathish>(forUpdatingAt path: P) throws {
+        try self.init(forUpdating: path.url)
+    }
+}
+
+internal extension Bundle {
+    var defaultSharedFrameworksPath: DynamicPath {
+      #if os(macOS)
+        return path.Contents.Frameworks
+      #elseif os(Linux)
+        return path.lib
+      #else
+        return path.Frameworks
+      #endif
+    }
+
+    var defaultResourcesPath: DynamicPath {
+      #if os(macOS)
+        return path.Contents.Resources
+      #elseif os(Linux)
+        return path.share
+      #else
+        return path
+      #endif
+    }
+}

Sources/Path+Attributes.swift

@@ -1,35 +1,56 @@
 import Foundation
 
-public extension Path {
+public extension Pathish {
-    /// - Note: If file is already locked, does nothing
+    //MARK: Filesystem Attributes
-    /// - Note: If file doesn’t exist, throws
+
-    @discardableResult
+    /**
-    public func lock() throws -> Path {
+     Returns the creation-time of the file.
-        var attrs = try FileManager.default.attributesOfItem(atPath: string)
+     - Note: Returns `nil` if there is no creation-time, this should only happen if the file doesn’t exist.
-        let b = attrs[.immutable] as? Bool ?? false
+     - Important: On Linux this is filesystem dependendent and may not exist.
-        if !b {
+     */
-            attrs[.immutable] = true
+    var ctime: Date? {
-            try FileManager.default.setAttributes(attrs, ofItemAtPath: string)
+        do {
+            let attrs = try FileManager.default.attributesOfItem(atPath: string)
+            return attrs[.creationDate] as? Date
+        } catch {
+            return nil
         }
-        return self
     }
 
-    /// - Note: If file isn‘t locked, does nothing
+    /**
-    /// - Note: If file doesn’t exist, does nothing
+     Returns the modification-time of the file.
-    @discardableResult
+     - Note: If this returns `nil` and the file exists, something is very wrong.
-    public func unlock() throws -> Path {
+     */
-        var attrs: [FileAttributeKey: Any]
+    var mtime: Date? {
         do {
-            attrs = try FileManager.default.attributesOfItem(atPath: string)
+            let attrs = try FileManager.default.attributesOfItem(atPath: string)
-        } catch CocoaError.fileReadNoSuchFile {
+            return attrs[.modificationDate] as? Date
-            return self
+        } catch {
+            return nil
         }
-        let b = attrs[.immutable] as? Bool ?? false
+    }
-        if b {
+
-            attrs[.immutable] = false
+    /// The type of the entry.
-            try FileManager.default.setAttributes(attrs, ofItemAtPath: string)
+    /// - 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
         }
-        return self
     }
 
     /**
@@ -38,23 +59,66 @@ public extension Path {
          Path.home.join("foo").chmod(0o555)
      */
     @discardableResult
-    public func chmod(_ octal: Int) throws -> Path {
+    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.
+     - Note: If file doesn’t exist, throws.
+     - Important: On Linux does nothing.
+     */
+    @discardableResult
+    func lock() throws -> Path {
+    #if !os(Linux)
+        var attrs = try FileManager.default.attributesOfItem(atPath: string)
+        let b = attrs[.immutable] as? Bool ?? false
+        if !b {
+            attrs[.immutable] = true
+            try FileManager.default.setAttributes(attrs, ofItemAtPath: string)
+        }
+    #endif
+        return Path(self)
     }
 
     /**
-     Returns the modification-time.
+     - Note: If file isn‘t locked, does nothing.
-     - Note: Returns the creation time if there is no modification time.
+     - Note: If file doesn’t exist, does nothing.
-     - Note: Returns UNIX-time-zero if neither are available, though this *should* be impossible.
+     - Important: On Linux does nothing.
+     - SeeAlso: `lock()`
      */
-    public var mtime: Date {
+    @discardableResult
+    func unlock() throws -> Path {
+    #if !os(Linux)
+        var attrs: [FileAttributeKey: Any]
         do {
-            let attrs = try FileManager.default.attributesOfItem(atPath: string)
+            attrs = try FileManager.default.attributesOfItem(atPath: string)
-            return attrs[.modificationDate] as? Date ?? attrs[.creationDate] as? Date ?? Date()
+        } catch CocoaError.fileReadNoSuchFile {
-        } catch {
+            return Path(self)
-            //TODO log error
-            return Date(timeIntervalSince1970: 0)
         }
+        let b = attrs[.immutable] as? Bool ?? false
+        if b {
+            attrs[.immutable] = false
+            try FileManager.default.setAttributes(attrs, ofItemAtPath: string)
+        }
+    #endif
+        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

@@ -1,29 +1,52 @@
 import Foundation
 
-/// Provided for relative-path coding. See the instructions in our `README`.
+/**
+ Provided for relative-path coding. See the instructions in our
+ [README](https://github.com/mxcl/Path.swift/#codable).
+*/
 public extension CodingUserInfoKey {
-    /// If set paths are encoded as relative to this path.
+    /**
+     If set on an `Encoder`’s `userInfo` all paths are encoded relative to this path.
+
+     For example:
+
+         let encoder = JSONEncoder()
+         encoder.userInfo[.relativePath] = Path.home
+         encoder.encode([Path.home, Path.home/"foo"])
+
+     - Remark: See the [README](https://github.com/mxcl/Path.swift/#codable) for more information.
+    */
     static let relativePath = CodingUserInfoKey(rawValue: "dev.mxcl.Path.relative")!
 }
 
-/// Provided for relative-path coding. See the instructions in our `README`.
+/**
+ Provided for relative-path coding. See the instructions in our
+ [README](https://github.com/mxcl/Path.swift/#codable).
+*/
 extension Path: Codable {
+    /// - SeeAlso: `CodingUserInfoKey.relativePath`
+    /// :nodoc:
     public init(from decoder: Decoder) throws {
         let value = try decoder.singleValueContainer().decode(String.self)
         if value.hasPrefix("/") {
             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."))
         }
     }
 
+    /// - SeeAlso: `CodingUserInfoKey.relativePath`
+    /// :nodoc:
     public func encode(to encoder: Encoder) throws {
         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,18 +1,33 @@
 import Foundation
 
-extension Path {
+/// The `extension` that provides static properties that are common directories.
-    /// Returns a `Path` containing ``FileManager.default.currentDirectoryPath`.
+private enum Foo {
-    public static var cwd: Path {
+    //MARK: Common Directories
-        return Path(string: FileManager.default.currentDirectoryPath)
+
+    /// Returns a `Path` containing `FileManager.default.currentDirectoryPath`.
+    static var cwd: DynamicPath {
+        return .init(string: FileManager.default.currentDirectoryPath)
     }
 
     /// Returns a `Path` representing the root path.
-    public static var root: Path {
+    static var root: DynamicPath {
-        return Path(string: "/")
+        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: Path {
+    static var home: DynamicPath {
         let string: String
       #if os(macOS)
         if #available(OSX 10.12, *) {
@@ -23,41 +38,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 {
+        guard let pathString = FileManager.default.urls(for: searchPath, in: .userDomainMask).first?.path else { return defaultUrl(for: searchPath) }
-            switch searchPath {
+        return DynamicPath(string: pathString)
-            case .documentDirectory:
-                return Path.home/"Documents"
-            case .applicationSupportDirectory:
-                return Path.home/"Library/Application Support"
-            case .cachesDirectory:
-                return Path.home/"Library/Caches"
-            default:
-                fatalError()
-            }
-        }
-        return Path(string: pathString)
     #endif
     }
 
@@ -66,16 +70,16 @@ 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 {
+    static var documents: DynamicPath {
         return path(for: .documentDirectory)
     }
 
     /**
      The root for cache files.
-     - Note: On Linux this is 'XDG_CACHE_HOME'.
+     - Note: On Linux this is `XDG_CACHE_HOME`.
      - Note: You should create a subdirectory before creating any files.
      */
-    public static var caches: Path {
+    static var caches: DynamicPath {
         return path(for: .cachesDirectory)
     }
 
@@ -84,7 +88,55 @@ extension Path {
      - Note: On Linux is `XDG_DATA_HOME`.
      - Note: You should create a subdirectory before creating any files.
      */
-    public static var applicationSupport: Path {
+    static var applicationSupport: DynamicPath {
         return path(for: .applicationSupportDirectory)
     }
 }
+
+#if !os(Linux)
+func defaultUrl(for searchPath: FileManager.SearchPathDirectory) -> DynamicPath {
+    switch searchPath {
+    case .documentDirectory:
+        return Path.home.Documents
+    case .applicationSupportDirectory:
+        return Path.home.Library[dynamicMember: "Application Support"]
+    case .cachesDirectory:
+        return Path.home.Library.Caches
+    default:
+        fatalError()
+    }
+}
+#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

@@ -1,54 +1,80 @@
 import Foundation
+#if os(Linux)
+import Glibc
+#endif
+
+public extension Pathish {
+
+    //MARK: File Management
 
-public extension Path {
     /**
      Copies a file.
+
+         try Path.root.join("bar").copy(to: Path.home/"foo")
+         // => "/Users/mxcl/foo"
+
      - Note: `throws` if `to` is a directory.
      - Parameter to: Destination filename.
-     - Parameter overwrite: If true overwrites any file that already exists at `to`.
+     - Parameter overwrite: If `true` and both `self` and `to` are files, overwrites `to`.
+     - Note: If either `self` or `to are directories, `overwrite` is ignored.
+     - Note: Throws if `overwrite` is `false` yet `to` is *already* identical to
+      `self` because even though *Path.swift’s* policy is to noop if the desired
+       end result preexists, checking for this condition is too expensive a
+       trade-off.
      - Returns: `to` to allow chaining
      - SeeAlso: `copy(into:overwrite:)`
      */
     @discardableResult
-    public func copy(to: Path, overwrite: Bool = false) throws -> Path {
+    func copy<P: Pathish>(to: P, overwrite: Bool = false) throws -> Path {
-        if overwrite, to.exists {
+        if overwrite, let tokind = to.type, tokind != .directory, type != .directory {
             try FileManager.default.removeItem(at: to.url)
         }
+    #if os(Linux)
+        //NOTE doing manually due to inconsistency in Linux Foundation behavior
+        if !overwrite, to.type != nil {
+            throw CocoaError.error(.fileWriteFileExists)
+        }
+    #endif
         try FileManager.default.copyItem(atPath: string, toPath: to.string)
-        return to
+        return Path(to)
     }
 
     /**
      Copies a file into a directory
 
-     If the destination does not exist, this function creates the directory first.
+         try Path.root.join("bar").copy(into: .home)
+         // => "/Users/mxcl/bar"
 
-        // Create ~/.local/bin, copy `ls` there and make the new copy executable
+         // Create ~/.local/bin, copy `ls` there and make the new copy executable
-        try Path.root.join("bin/ls").copy(into: Path.home.join(".local/bin").mkpath()).chmod(0o500)
+         try Path.root.join("bin/ls").copy(into: Path.home.join(".local/bin").mkdir(.p)).chmod(0o500)
+
+     If the destination does not exist, this function creates the directory
+     (including intermediary directories if necessary) first.
 
-     - Note: `throws` if `into` is a file.
      - Parameter into: Destination directory
      - Parameter overwrite: If true overwrites any file that already exists at `into`.
      - Returns: The `Path` of the newly copied file.
-     - SeeAlso: `copy(into:overwrite:)`
+     - Note: `throws` if `into` is a file.
+     - Note: Throws if `overwrite` is `false` yet `to` is *already* identical to
+      `self` because even though *Path.swift’s* policy is to noop if the desired
+       end result preexists, checking for this condition is too expensive a
+       trade-off.
+     - SeeAlso: `copy(to:overwrite:)`
      */
     @discardableResult
-    public 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 FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+            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)
-    #if swift(>=5)
+        //NOTE doing manually due to inconsistency in Linux Foundation behavior
-        // check if fixed
+        if !overwrite, rv.type != nil {
-    #else
-        if !overwrite, rv.isFile {
             throw CocoaError.error(.fileWriteFileExists)
         }
-    #endif
     #endif
         try FileManager.default.copyItem(at: url, to: rv.url)
         return rv
@@ -56,132 +82,176 @@ public extension Path {
 
     /**
      Moves a file.
-     - Note: `throws` if `to` is a directory.
+
+         try Path.root.join("bar").move(to: Path.home/"foo")
+         // => "/Users/mxcl/foo"
+
      - Parameter to: Destination filename.
      - Parameter overwrite: If true overwrites any file that already exists at `to`.
      - Returns: `to` to allow chaining
-     - SeeAlso: move(into:overwrite:)
+     - Note: `throws` if `to` is a directory.
+     - Note: Throws if `overwrite` is `false` yet `to` is *already* identical to
+       `self` because even though *Path.swift’s* policy is to noop if the desired
+       end result preexists, checking for this condition is too expensive a
+       trade-off.
+     - SeeAlso: `move(into:overwrite:)`
      */
     @discardableResult
-    public func move(to: Path, overwrite: Bool = false) throws -> Path {
+    func move<P: Pathish>(to: P, overwrite: Bool = false) throws -> Path {
-        if overwrite, to.exists {
+        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)
     }
 
     /**
      Moves a file into a directory
 
-     If the destination does not exist, this function creates the directory first.
+         try Path.root.join("bar").move(into: .home)
+         // => "/Users/mxcl/bar"
+
+     If the destination does not exist, this function creates the directory
+     (including intermediary directories if necessary) first.
 
-     - Note: `throws` if `into` is a file.
      - Parameter into: Destination directory
-     - Parameter overwrite: If true overwrites any file that already exists at `into`.
+     - Parameter overwrite: If true *overwrites* any file that already exists at `into`.
+     - Note: `throws` if `into` is a file.
      - Returns: The `Path` of destination filename.
-     - SeeAlso: move(into:overwrite:)
+     - SeeAlso: `move(to:overwrite:)`
      */
     @discardableResult
-    public func move(into: Path) throws -> Path {
+    func move<P: Pathish>(into: P, overwrite: Bool = false) throws -> Path {
-        if !into.exists {
+        switch into.type {
-            try into.mkpath()
+        case nil:
-        } else if !into.isDirectory {
+            try into.mkdir(.p)
+            fallthrough
+        case .directory?:
+            let rv = into/basename()
+            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)
         }
-        let rv = into/basename()
-        try FileManager.default.moveItem(at: url, to: rv.url)
-        return rv
-    }
 
-    /// Deletes the path, recursively if a directory.
-    @inlinable
-    public func delete() throws {
-        try FileManager.default.removeItem(at: url)
     }
 
     /**
-     Creates an empty file at this path.
+     Deletes the path, recursively if a directory.
-     - Returns: `self` to allow chaining.
+     - Note: noop: if the path doesn’t exist
+     ∵ *Path.swift* doesn’t error if desired end result preexists.
+     - Note: On UNIX will this function will succeed if the parent directory is writable and the current user has permission.
+     - Note: This function will fail if the file or directory is “locked”
+     - Note: If entry is a symlink, deletes the symlink.
+     - SeeAlso: `lock()`
+    */
+    @inlinable
+    func delete() throws {
+        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: A copy of `self` to allow chaining.
      */
     @inlinable
     @discardableResult
     func touch() throws -> Path {
-        return try "".write(to: self)
+        if type == nil {
+            guard FileManager.default.createFile(atPath: string, contents: nil) else {
+                throw CocoaError.error(.fileWriteUnknown)
+            }
+        } else {
+        #if os(Linux)
+            let fd = open(string, O_WRONLY)
+            defer { close(fd) }
+            futimens(fd, nil)
+        #else
+            try FileManager.default.setAttributes([.modificationDate: Date()], ofItemAtPath: string)
+        #endif
+        }
+        return Path(self)
     }
 
-    /// Helper due to Linux Swift being incomplete.
+    /**
-    private func _foo(go: () throws -> Void) throws {
+     Creates the directory at this path.
-    #if !os(Linux)
+     - 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: A copy of `self` to allow chaining.
+     */
+    @discardableResult
+    func mkdir(_ options: MakeDirectoryOptions? = nil) throws -> Path {
         do {
-            try go()
+            let wid = options == .p
+            try FileManager.default.createDirectory(at: self.url, withIntermediateDirectories: wid, attributes: nil)
         } catch CocoaError.Code.fileWriteFileExists {
-            // noop
+            //noop (fails to trigger on Linux)
-        }
-    #else
-        do {
-            try go()
         } catch {
+        #if os(Linux)
             let error = error as NSError
             guard error.domain == NSCocoaErrorDomain, error.code == CocoaError.Code.fileWriteFileExists.rawValue else {
                 throw error
             }
+        #else
+            throw error
+        #endif
         }
-    #endif
+        return Path(self)
     }
 
     /**
-     Creates the directory at this path.
+     Renames the file (basename only) at path.
-     - Note: Does not create any intermediary directories.
+
-     - Returns: `self` to allow chaining.
+         Path.root.foo.bar.rename(to: "baz")  // => /foo/baz
+
+     - Parameter to: the new basename for the file
+     - Returns: The renamed path.
      */
     @discardableResult
-    public func mkdir() throws -> Path {
+    func rename(to newname: String) throws -> Path {
-        try _foo {
+        let newpath = parent/newname
-            try FileManager.default.createDirectory(at: self.url, withIntermediateDirectories: false, attributes: nil)
+        try FileManager.default.moveItem(atPath: string, toPath: newpath.string)
-        }
+        return newpath
-        return self
     }
 
     /**
-     Creates the directory at this path.
+     Creates a symlink of this file at `as`.
-     - Note: Creates any intermediary directories, if required.
+     - Note: If `self` does not exist, is **not** an error.
-     - Returns: `self` to allow chaining.
      */
     @discardableResult
-    public func mkpath() throws -> Path {
+    func symlink<P: Pathish>(as: P) throws -> Path {
-        try _foo {
+        try FileManager.default.createSymbolicLink(atPath: `as`.string, withDestinationPath: string)
-            try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true, attributes: nil)
+        return Path(`as`)
-        }
-        return self
     }
 
     /**
-     Replaces the contents of the file at this path with the provided string.
+     Creates a symlink of this file with the same filename in the `into` directory.
-     - Note: If file doesn’t exist, creates file
+     - Note: If into does not exist, creates the directory with intermediate directories if necessary.
-     - Note: If file is not writable, makes writable first, resetting permissions after the write
-     - Parameter contents: The string that will become the contents of this file.
-     - Parameter atomically: If `true` the operation will be performed atomically.
-     - Parameter encoding: The string encoding to use.
-     - Returns: `self` to allow chaining.
      */
     @discardableResult
-    public func replaceContents(with contents: String, atomically: Bool = false, encoding: String.Encoding = .utf8) throws -> Path {
+    func symlink<P: Pathish>(into dir: P) throws -> Path {
-        let resetPerms: Int?
+        switch dir.type {
-        if exists, !isWritable {
+        case nil, .symlink?:
-            resetPerms = try FileManager.default.attributesOfItem(atPath: string)[.posixPermissions] as? Int
+            try dir.mkdir(.p)
-            let perms = resetPerms ?? 0o777
+            fallthrough
-            try chmod(perms | 0o200)
+        case .directory?:
-        } else {
+            let dst = dir/basename()
-            resetPerms = nil
+            try FileManager.default.createSymbolicLink(atPath: dst.string, withDestinationPath: string)
+            return dst
+        case .file?:
+            throw CocoaError.error(.fileWriteFileExists)
         }
-
-        defer {
-            _ = try? resetPerms.map(self.chmod)
-        }
-
-        try contents.write(to: self)
-
-        return self
     }
 }
+
+/// Options for `Path.mkdir(_:)`
+public enum MakeDirectoryOptions {
+    /// Creates intermediary directories; works the same as `mkdir -p`.
+    case p
+}

Sources/Path+StringConvertibles.swift

@@ -1,13 +1,3 @@
-import class Foundation.NSString
-
-extension Path: LosslessStringConvertible {
-    /// Returns `nil` unless fed an absolute path
-    public init?(_ description: String) {
-        guard description.starts(with: "/") || description.starts(with: "~/") else { return nil }
-        self.init(string: (description as NSString).standardizingPath)
-    }
-}
-
 extension Path: CustomStringConvertible {    
     /// Returns `Path.string`
     public var description: String {
@@ -18,6 +8,20 @@ extension Path: CustomStringConvertible {
 extension Path: CustomDebugStringConvertible {
     /// Returns eg. `Path(string: "/foo")`
     public var debugDescription: String {
-        return "Path(string: \(string))"
+        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,39 +1,219 @@
 import Foundation
 
 public extension Path {
-    /**
+    /// The builder for `Path.find()`
-     Same as the `ls -a` command ∴ is ”shallow”
+    class Finder {
-     - Parameter includeHiddenFiles: If `true`, hidden files are included in the results. Defaults to `true`.
+        fileprivate init(path: Path) {
-     - Important: `includeHiddenFiles` does not work on Linux
+            self.path = path
-     */
+            self.enumerator = FileManager.default.enumerator(atPath: path.string)
-    func ls(includeHiddenFiles: Bool = true) throws -> [Entry] {
-        var opts = FileManager.DirectoryEnumerationOptions()
-    #if !os(Linux)
-        if !includeHiddenFiles {
-            opts.insert(.skipsHiddenFiles)
         }
+
+        /// The `path` find operations operate on.
+        public let path: Path
+
+        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 {
+    /// 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
-        let paths = try FileManager.default.contentsOfDirectory(at: url, includingPropertiesForKeys: nil, options: opts)
+        depth = Swift.min(maxDepth, depth.lowerBound)...maxDepth
-        func convert(url: URL) -> Entry? {
+        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
+    }
+    
+    /// 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`
+    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:
+              #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:
+                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
+        }.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))
     }
 }
 
-public extension Array where Element == Path.Entry {
+/// Convenience functions for the arrays of `Path`
-    /// Filters the list of entries to be a list of Paths that are directories.
+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 with the specified extension
+    /// Filters the list of entries to be a list of Paths that exist and are *not* directories. Thus expect symlinks, etc.
-    func files(withExtension ext: String) -> [Path] {
+    /// - Note: symlinks that point to files that do not exist are *not* returned.
-        return compactMap {
+    var files: [Path] {
-            $0.kind == .file && $0.path.extension == ext ? $0.path : nil
+        return filter {
+            switch $0.type {
+            case .none, .directory?:
+                return false
+            case .file?, .symlink?:
+                return true
+            }
         }
     }
 }
+
+/// Options for `Path.ls(_:)`
+public enum ListDirectoryOptions {
+    /// Lists hidden files also
+    case a
+}

Sources/Path->Bool.swift

@@ -1,25 +1,21 @@
 import Foundation
+#if os(Linux)
+import func Glibc.access
+#else
+import Darwin
+#endif
 
-public extension Path {
+public extension Pathish {
-    /// Returns true if the path represents an actual file that is also writable by the current user.
-    var isWritable: Bool {
-        return FileManager.default.isWritableFile(atPath: string)
-    }
 
-    /// Returns true if the path represents an actual file that is also readable by the current user.
+    //MARK: Filesystem Properties
-    var isReadable: Bool {
-        return FileManager.default.isReadableFile(atPath: string)
-    }
 
-    /// Returns true if the path represents an actual file that is also deletable by the current user.
+    /**
-    var isDeletable: Bool {
+     - Returns: `true` if the path represents an actual filesystem entry.
-        return FileManager.default.isDeletableFile(atPath: string)
+     - 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`.
-
+     */
-    /// Returns true if the path represents an actual directory.
+    var exists: Bool {
-    var isDirectory: Bool {
+        return FileManager.default.fileExists(atPath: string)
-        var isDir: ObjCBool = false
-        return FileManager.default.fileExists(atPath: string, isDirectory: &isDir) && isDir.boolValue
     }
 
     /// Returns true if the path represents an actual filesystem entry that is *not* a directory.
@@ -28,13 +24,47 @@ public extension Path {
         return FileManager.default.fileExists(atPath: string, isDirectory: &isDir) && !isDir.boolValue
     }
 
-    /// Returns true if the path represents an actual file that is also executable by the current user.
+    /// Returns true if the path represents an actual directory.
-    var isExecutable: Bool {
+    var isDirectory: Bool {
-        return FileManager.default.isExecutableFile(atPath: string)
+        var isDir: ObjCBool = false
+        return FileManager.default.fileExists(atPath: string, isDirectory: &isDir) && isDir.boolValue
     }
 
-    /// Returns true if the path represents an actual filesystem entry.
+    /// Returns true if the path represents an actual file that is also readable by the current user.
-    var exists: Bool {
+    var isReadable: Bool {
-        return FileManager.default.fileExists(atPath: string)
+        return FileManager.default.isReadableFile(atPath: string)
+    }
+
+    /// Returns true if the path represents an actual file that is also writable by the current user.
+    var isWritable: Bool {
+        return FileManager.default.isWritableFile(atPath: string)
+    }
+        
+    /// Returns true if the path represents an actual file that is also deletable by the current user.
+    var isDeletable: Bool {
+    #if os(Linux) && !swift(>=5.1)
+        return exists && access(parent.string, W_OK) == 0
+    #else
+        // FileManager.isDeletableFile returns true if there is *not* a file there
+        return exists && FileManager.default.isDeletableFile(atPath: string)
+    #endif
+    }
+
+    /// Returns true if the path represents an actual file that is also executable by the current user.
+    var isExecutable: Bool {
+        if access(string, X_OK) == 0 {
+            // FileManager.isExxecutableFile returns true even if there is *not*
+            // a file there *but* if there was it could be *made* executable
+            return FileManager.default.isExecutableFile(atPath: string)
+        } else {
+            return false
+        }
+    }
+
+    /// Returns `true` if the file is a symbolic-link (symlink).
+    var isSymlink: Bool {
+        var sbuf = stat()
+        lstat(string, &sbuf)
+        return (sbuf.st_mode & S_IFMT) == S_IFLNK 
     }
 }

Sources/Path.swift

@@ -1,28 +1,163 @@
 import Foundation
+#if !os(Linux)
+import func Darwin.realpath
+let _realpath = Darwin.realpath
+#else
+import func Glibc.realpath
+let _realpath = Glibc.realpath
+#endif
+
+public typealias PathStruct = Path
 
 /**
- Represents a platform filesystem absolute path.
+ A `Path` represents an absolute path on a filesystem.
 
- The recommended conversions from string are:
+ All functions on `Path` are chainable and short to facilitate doing sequences
+ of file operations in a concise manner.
+
+ `Path` supports `Codable`, and can be configured to
+ [encode paths *relatively*](https://github.com/mxcl/Path.swift/#codable).
+
+ Sorting a `Sequence` of paths will return the locale-aware sort order, which
+ will give you the same order as Finder.
+
+ Converting from a `String` is a common first step, here are the recommended
+ ways to do that:
 
      let p1 = Path.root/pathString
      let p2 = Path.root/url.path
      let p3 = Path.cwd/relativePathString
      let p4 = Path(userInput) ?? Path.cwd/userInput
 
- - Note: There may not be an actual filesystem entry at the path.
+ If you are constructing paths from static-strings we provide support for
+ dynamic members:
+
+     let p1 = Path.root.usr.bin.ls  // => /usr/bin/ls
+
+ 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.
+
+ - 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: Equatable, Hashable, Comparable {
+public struct Path: Pathish {
-    /// The underlying filesystem path
+
+    /// The normalized string representation of the underlying filesystem path
     public let string: String
 
+    init(string: String) {
+        assert(string.first == "/")
+        assert(string.last != "/" || string == "/")
+        assert(string.split(separator: "/").contains("..") == false)
+        self.string = string
+    }
+
     /**
-     Returns the filename extension of this path.
+     Creates a new absolute, standardized path.
-     - Remark: Implemented via `NSString.pathExtension`.
+     - Note: Resolves any .. or . components.
+     - Note: Removes multiple subsequent and trailing occurences of `/`.
+     - Note: Does *not* resolve any symlinks.
+     - Note: On macOS, removes an initial component of “/private/var/automount”, “/var/automount”, or “/private” from the path, if the result still indicates an existing file or directory (checked by consulting the file system).
+     - Returns: The path or `nil` if fed a relative path or a `~foo` string where there is no user `foo`.
      */
-    @inlinable
+    public init?<S: StringProtocol>(_ description: S) {
-    public var `extension`: String {
+        var pathComponents = description.split(separator: "/")
-        return (string as NSString).pathExtension
+        switch description.first {
+        case "/":
+        #if os(macOS)
+            func ifExists(withPrefix prefix: String, removeFirst n: Int) {
+                assert(prefix.split(separator: "/").count == n)
+
+                if description.hasPrefix(prefix), FileManager.default.fileExists(atPath: String(description)) {
+                    pathComponents.removeFirst(n)
+                }
+            }
+
+            ifExists(withPrefix: "/private/var/automount", removeFirst: 3)
+            ifExists(withPrefix: "/var/automount", removeFirst: 2)
+            ifExists(withPrefix: "/private", removeFirst: 1)
+        #endif
+            string = join_(prefix: "/", pathComponents: pathComponents)
+
+        case "~":
+            if description == "~" {
+                string = Path.home.string
+                return
+            }
+            let tilded: String
+            if description.hasPrefix("~/") {
+                tilded = Path.home.string
+            } else {
+                let username = String(pathComponents[0].dropFirst())
+            #if os(macOS) || os(Linux)
+                if #available(OSX 10.12, *) {
+                    guard let url = FileManager.default.homeDirectory(forUser: username) else { return nil }
+                    assert(url.scheme == "file")
+                    tilded = url.path
+                } else {
+                    guard let dir = NSHomeDirectoryForUser(username) else { return nil }
+                    tilded = dir
+                }
+            #else
+                return nil  // there are no usernames on iOS, etc.
+            #endif
+            }
+            pathComponents.remove(at: 0)
+            string = join_(prefix: tilded, pathComponents: pathComponents)
+
+        default:
+            return nil
+        }
+    }
+
+    /**
+     Creates a new absolute, standardized path from the provided file-scheme URL.
+     - Note: If the URL is not a file URL, returns `nil`.
+    */
+    public init?(url: URL) {
+        guard url.scheme == "file" else { return nil }
+        self.init(url.path)
+        //NOTE: URL cannot be a file-reference url, unlike NSURL, so this always works
+    }
+
+    /**
+     Creates a new absolute, standardized path from the provided file-scheme URL.
+     - Note: If the URL is not a file URL, returns `nil`.
+     - Note: If the URL is a file reference URL, converts it to a POSIX path first.
+    */
+    public init?(url: NSURL) {
+        guard url.scheme == "file", let path = url.path else { return nil }
+        self.init(string: path)
+        // ^^ works even if the url is a file-reference url
+    }
+
+    /// Converts anything that is `Pathish` to a `Path`
+    public init<P: Pathish>(_ path: P) {
+        string = path.string
+    }
+}
+
+public extension Pathish {
+    //MARK: Filesystem Representation
+
+    /// Returns a `URL` representing this file path.
+    var url: URL {
+        return URL(fileURLWithPath: string)
+    }
+
+    /**
+     Returns a file-reference URL.
+     - Note: Only NSURL can be a file-reference-URL, hence we return NSURL.
+     - SeeAlso: https://developer.apple.com/documentation/foundation/nsurl/1408631-filereferenceurl
+     - Important: On Linux returns an file scheme NSURL for this path string.
+     */
+    var fileReferenceURL: NSURL? {
+    #if !os(Linux)
+        // https://bugs.swift.org/browse/SR-2728
+        return (url as NSURL).perform(#selector(NSURL.fileReferenceURL))?.takeUnretainedValue() as? NSURL
+    #else
+        return NSURL(fileURLWithPath: string)
+    #endif
     }
 
     /**
@@ -33,39 +168,93 @@ 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 {
-        return Path(string: (string as NSString).deletingLastPathComponent)
+        let index = string.lastIndex(of: "/")!
-    }
+        guard index != string.indices.startIndex else { return Path(string: "/") }
-
+        let substr = string[string.indices.startIndex..<index]
-    /// Returns a `URL` representing this file path.
+        return Path(string: String(substr))
-    @inlinable
-    public var url: URL {
-        return URL(fileURLWithPath: string)
     }
 
     /**
-     The basename for the provided file, optionally dropping the file extension.
+     Returns the filename extension of this path.
-
+     - Remark: If there is no extension returns "".
-         Path.root.join("foo.swift").basename()  // => "foo.swift"
+     - Remark: If the filename ends with any number of ".", returns "".
-         Path.root.join("foo.swift").basename(dropExtension: true)  // => "foo"
+     - Note: We special case eg. `foo.tar.gz`—there are a limited number of these specializations, feel free to PR more.
-
-     - 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 {
+    @inlinable
-        let str = string as NSString
+    var `extension`: String {
-        if !dropExtension {
+        //FIXME efficiency
-            return str.lastPathComponent
+        switch true {
-        } else {
+        case string.hasSuffix(".tar.gz"):
-            let ext = str.pathExtension
+            return "tar.gz"
-            if !ext.isEmpty {
+        case string.hasSuffix(".tar.bz"):
-                return String(str.lastPathComponent.dropLast(ext.count + 1))
+            return "tar.bz"
+        case string.hasSuffix(".tar.bz2"):
+            return "tar.bz2"
+        case string.hasSuffix(".tar.xz"):
+            return "tar.xz"
+        default:
+            let slash = string.lastIndex(of: "/")!
+            if let dot = string.lastIndex(of: "."), slash < dot {
+                let foo = string.index(after: dot)
+                return String(string[foo...])
             } else {
-                return str.lastPathComponent
+                return ""
             }
         }
     }
 
+    /**
+     Splits the string representation on the directory separator.
+     - 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)
+    }
+
+    //MARK:- Pathing
+
+    /**
+     Joins a path and a string to produce a new path.
+
+         Path.root.join("a")             // => /a
+         Path.root.join("a/b")           // => /a/b
+         Path.root.join("a").join("b")   // => /a/b
+         Path.root.join("a").join("/b")  // => /a/b
+
+     - Note: `..` and `.` components are interpreted.
+     - Note: pathComponent *may* be multiple components.
+     - Note: symlinks are *not* resolved.
+     - Parameter pathComponent: The string to join with this path.
+     - Returns: A new joined path.
+     - SeeAlso: `Path./(_:_:)`
+     */
+    func join<S>(_ addendum: S) -> Path where S: StringProtocol {
+        return Path(string: join_(prefix: string, appending: addendum))
+    }
+
+    /**
+     Joins a path and a string to produce a new path.
+
+         Path.root/"a"       // => /a
+         Path.root/"a/b"     // => /a/b
+         Path.root/"a"/"b"   // => /a/b
+         Path.root/"a"/"/b"  // => /a/b
+
+     - Note: `..` and `.` components are interpreted.
+     - Note: pathComponent *may* be multiple components.
+     - Note: symlinks are *not* resolved.
+     - Parameter lhs: The base path to join with `rhs`.
+     - Parameter rhs: The string to join with this `lhs`.
+     - Returns: A new joined path.
+     - SeeAlso: `join(_:)`
+     */
+    @inlinable
+    static func /<S>(lhs: Self, rhs: S) -> Path where S: StringProtocol {
+        return lhs.join(rhs)
+    }
+
     /**
      Returns a string representing the relative path to `base`.
 
@@ -73,7 +262,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
@@ -104,59 +293,143 @@ public struct Path: Equatable, Hashable, Comparable {
     }
 
     /**
-     Joins a path and a string to produce a new path.
+     The basename for the provided file, optionally dropping the file extension.
 
-         Path.root.join("a")             // => /a
+         Path.root.join("foo.swift").basename()  // => "foo.swift"
-         Path.root.join("a/b")           // => /a/b
+         Path.root.join("foo.swift").basename(dropExtension: true)  // => "foo"
-         Path.root.join("a").join("b")   // => /a/b
-         Path.root.join("a").join("/b")  // => /a/b
 
-     - Parameter pathComponent: The string to join with this path.
+     - Returns: A string that is the filename’s basename.
-     - Returns: A new joined path.
+     - Parameter dropExtension: If `true` returns the basename without its file extension.
-     - SeeAlso: `/(_:, _:)`
      */
-    public func join<S>(_ pathComponent: S) -> Path where S: StringProtocol {
+    func basename(dropExtension: Bool = false) -> String {
-        //TODO standardizingPath does more than we want really (eg tilde expansion)
+        var lastPathComponent: Substring {
-        let str = (string as NSString).appendingPathComponent(String(pathComponent))
+            let slash = string.lastIndex(of: "/")!
-        return Path(string: (str as NSString).standardizingPath)
+            let index = string.index(after: slash)
+            return string[index...]
+        }
+        var go: Substring {
+            if !dropExtension {
+                return lastPathComponent
+            } else {
+                let ext = self.extension
+                if !ext.isEmpty {
+                    return lastPathComponent.dropLast(ext.count + 1)
+                } else {
+                    return lastPathComponent
+                }
+            }
+        }
+        return String(go)
+    }
+
+    /**
+     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 a symlink.
+     - 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.
+     */
+    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 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 Path(self)
+            }
+        #endif
+            throw error
+        }
+    }
+
+    /// Recursively resolves symlinks in this 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) }
+
+        // “Removing an initial component of “/private/var/automount”, “/var/automount”,
+        // or “/private” from the path, if the result still indicates an existing file or
+        // directory (checked by consulting the file system).”
+        // ^^ we do this to not conflict with the results that other Apple APIs give
+        // which is necessary if we are to have equality checks work reliably
+        let rvvv = (rvv as NSString).standardizingPath
+
+        return Path(string: rvvv)
     }
 
     /// 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
     }
+}
 
-    /// A file entry from a directory listing.
+@inline(__always)
-    public struct Entry {
+private func join_<S>(prefix: String, appending: S) -> String where S: StringProtocol {
-        /// The kind of this directory entry.
+    return join_(prefix: prefix, pathComponents: appending.split(separator: "/"))
-        public enum Kind {
+}
-            /// The path is a file.
+
-            case file
+private func join_<S>(prefix: String, pathComponents: S) -> String where S: Sequence, S.Element: StringProtocol {
-            /// The path is a directory.
+    assert(prefix.first == "/")
-            case directory
+
+    var rv = prefix
+    for component in pathComponents {
+
+        assert(!component.contains("/"))
+
+        switch component {
+        case "..":
+            let start = rv.indices.startIndex
+            let index = rv.lastIndex(of: "/")!
+            if start == index {
+                rv = "/"
+            } else {
+                rv = String(rv[start..<index])
+            }
+        case ".":
+            break
+        default:
+            if rv == "/" {
+                rv = "/\(component)"
+            } else {
+                rv = "\(rv)/\(component)"
+            }
         }
-        /// The kind of this entry.
+    }
-        public let kind: Kind
+    return rv
-        /// The path of this entry.
+}
-        public let path: Path
+
+/// 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))
     }
 }
-
-/**
- Joins a path and a string to produce a new path.
-
-     Path.root/"a"       // => /a
-     Path.root/"a/b"     // => /a/b
-     Path.root/"a"/"b"   // => /a/b
-     Path.root/"a"/"/b"  // => /a/b
-
- - Parameter lhs: The base path to join with `rhs`.
- - Parameter rhs: The string to join with this `lhs`.
- - Returns: A new joined path.
- - SeeAlso: `Path.join(_:)`
- */
-@inlinable
-public func /<S>(lhs: Path, rhs: S) -> Path where S: StringProtocol {
-    return lhs.join(rhs)
-}

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,251 @@
+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 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")),
+                [tmpdir.join("foo.json")])
+            XCTAssertEqual(
+                Set(tmpdir.find().extension("txt").extension("json")),
+                [tmpdir.join("foo.json"), tmpdir.join("bar.txt")])
+        }
+    }
+
+    //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().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)))
+        }
+    }
+
+    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

@@ -1,7 +1,22 @@
+@testable import Path
+import func XCTest.XCTAssertEqual
+import Foundation
 import XCTest
-import Path
+
+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)
@@ -9,31 +24,40 @@ class PathTests: XCTestCase {
         XCTAssertEqual((Path.root/"///bar").string, "/bar")
         XCTAssertEqual((Path.root/"foo///bar////").string, "/foo/bar")
         XCTAssertEqual((Path.root/"foo"/"/bar").string, "/foo/bar")
+
+        XCTAssertEqual(Path.root.foo.bar.join(".."), Path.root.foo)
+        XCTAssertEqual(Path.root.foo.bar.join("."), Path.root.foo.bar)
+        XCTAssertEqual(Path.root.foo.bar.join("../baz"), Path.root.foo.baz)
     }
 
     func testEnumeration() throws {
         let tmpdir_ = try TemporaryDirectory()
         let tmpdir = tmpdir_.path
         try tmpdir.join("a").mkdir().join("c").touch()
-        try tmpdir.join("b").touch()
+        try tmpdir.join("b.swift").touch()
         try tmpdir.join("c").touch()
         try tmpdir.join(".d").mkdir().join("e").touch()
 
         var paths = Set<String>()
+        let lsrv = tmpdir.ls(.a)
         var dirs = 0
-        for entry in try tmpdir.ls() {
+        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(paths, ["a", "b", "c", ".d"])
+        XCTAssertEqual(dirs, lsrv.directories.count)
+        XCTAssertEqual(["a", ".d"], Set(lsrv.directories.map{ $0.relative(to: tmpdir) }))
+        XCTAssertEqual(["b.swift", "c"], Set(lsrv.files.map{ $0.relative(to: tmpdir) }))
+        XCTAssertEqual(["b.swift"], Set(lsrv.files.filter{ $0.extension == "swift" }.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()
@@ -43,25 +67,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() {
@@ -69,8 +101,24 @@ class PathTests: XCTestCase {
         XCTAssert((Path.root/"bin").isDirectory)
     }
 
+    func testExtension() {
+        for prefix in [Path.root, Path.root.foo, Path.root.foo.bar] {
+            XCTAssertEqual(prefix.join("a.swift").extension, "swift")
+            XCTAssertEqual(prefix.join("a").extension, "")
+            XCTAssertEqual(prefix.join("a.").extension, "")
+            XCTAssertEqual(prefix.join("a..").extension, "")
+            XCTAssertEqual(prefix.join("a..swift").extension, "swift")
+            XCTAssertEqual(prefix.join("a..swift.").extension, "")
+            XCTAssertEqual(prefix.join("a.tar.gz").extension, "tar.gz")
+            XCTAssertEqual(prefix.join("a.tar.bz2").extension, "tar.bz2")
+            XCTAssertEqual(prefix.join("a.tar.xz").extension, "tar.xz")
+            XCTAssertEqual(prefix.join("a..tar.bz").extension, "tar.bz")
+            XCTAssertEqual(prefix.join("a..tar..xz").extension, "xz")
+        }
+    }
+
     func testMktemp() throws {
-        var path: Path!
+        var path: DynamicPath!
         try Path.mktemp {
             path = $0
             XCTAssert(path.isDirectory)
@@ -83,39 +131,49 @@ class PathTests: XCTestCase {
         try Path.mktemp {
             for _ in 0...1 {
                 try $0.join("a").mkdir()
-                try $0.join("b/c").mkpath()
+                try $0.join("b/c").mkdir(.p)
             }
         }
     }
 
     func testBasename() {
-        XCTAssertEqual(Path.root.join("foo.bar").basename(dropExtension: true), "foo")
+        for prefix in [Path.root, Path.root.foo, Path.root.foo.bar] {
-        XCTAssertEqual(Path.root.join("foo").basename(dropExtension: true), "foo")
+            XCTAssertEqual(prefix.join("foo.bar").basename(dropExtension: true), "foo")
-        XCTAssertEqual(Path.root.join("foo.").basename(dropExtension: true), "foo.")
+            XCTAssertEqual(prefix.join("foo").basename(dropExtension: true), "foo")
-        XCTAssertEqual(Path.root.join("foo.bar.baz").basename(dropExtension: true), "foo.bar")
+            XCTAssertEqual(prefix.join("foo.").basename(dropExtension: true), "foo.")
+            XCTAssertEqual(prefix.join("foo.bar.baz").basename(dropExtension: true), "foo.bar")
+        }
     }
 
     func testCodable() throws {
-        let input = [Path.root/"bar"]
+        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)
     }
 
     func testRelativePathCodable() throws {
-        let root = Path.root/"bar"
+        let root = Path.root.foo
         let input = [
-            root/"foo"
+            Path.root,
-        ]
+            root,
+            root.bar
+        ].map(Path.init)
 
         let encoder = JSONEncoder()
-        encoder.userInfo[.relativePath] = root
-        let data = try encoder.encode(input)
 
-        XCTAssertEqual(try JSONSerialization.jsonObject(with: data) as? [String], ["foo"])
+        func test<P: Pathish>(relativePath: P, line: UInt = #line) throws {
+            encoder.userInfo[.relativePath] = relativePath
+            let data = try encoder.encode(input)
 
-        let decoder = JSONDecoder()
+            XCTAssertEqual(try JSONSerialization.jsonObject(with: data) as? [String], ["..", "", "bar"], line: line)
-        XCTAssertThrowsError(try decoder.decode([Path].self, from: data))
+
-        decoder.userInfo[.relativePath] = root
+            let decoder = JSONDecoder()
-        XCTAssertEqual(try decoder.decode([Path].self, from: data), input)
+            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() {
@@ -130,8 +188,16 @@ class PathTests: XCTestCase {
         XCTAssertEqual(prefix/b/c, Path("/Users/mxcl/b/c"))
         XCTAssertEqual(Path.root/"~b", Path("/~b"))
         XCTAssertEqual(Path.root/"~/b", Path("/~/b"))
+
         XCTAssertEqual(Path("~/foo"), Path.home/"foo")
+        XCTAssertEqual(Path("~"), Path.home)
+        XCTAssertEqual(Path("~/"), Path.home)
+        XCTAssertEqual(Path("~///"), Path.home)
+        XCTAssertEqual(Path("/~///"), Path.root/"~")
         XCTAssertNil(Path("~foo"))
+        XCTAssertNil(Path("~foo/bar"))
+
+        XCTAssertEqual(Path("~\(NSUserName())"), Path.home)
 
         XCTAssertEqual(Path.root/"a/foo"/"../bar", Path.root/"a/bar")
         XCTAssertEqual(Path.root/"a/foo"/"/../bar", Path.root/"a/bar")
@@ -139,14 +205,493 @@ class PathTests: XCTestCase {
         XCTAssertEqual(Path.root/"a/foo"/"../../../bar", Path.root/"bar")
     }
 
-    func testCopyInto() throws {
+    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")
+
+        let a = Path.home.foo
+        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(Path.home).parent.join("~foo").string)
+    }
+
+    func testCopyTo() throws {
         try Path.mktemp { root in
-            let bar = try root.join("bar").touch()
+            try root.foo.touch().copy(to: root.bar)
-            try Path.mktemp { root in
+            XCTAssert(root.foo.isFile)
-                try root.join("bar").touch()
+            XCTAssert(root.bar.isFile)
-                XCTAssertThrowsError(try bar.copy(into: root))
+            XCTAssertThrowsError(try root.foo.copy(to: root.bar))
-                try bar.copy(into: root, overwrite: true)
+            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()
+            XCTAssert(root.foo.isFile)
+            XCTAssertThrowsError(try root.foo.copy(to: root.bar.mkdir()))
+            XCTAssertThrowsError(try root.foo.copy(to: root.bar, overwrite: true))
+        }
+    }
+
+    func testCopyInto() throws {
+        try Path.mktemp { root1 in
+            let bar1 = try root1.join("bar").touch()
+            try Path.mktemp { root2 in
+                let bar2 = try root2.join("bar").touch()
+                XCTAssertThrowsError(try bar1.copy(into: root2))
+                try bar1.copy(into: root2, overwrite: true)
+                XCTAssertTrue(bar1.exists)
+                XCTAssertTrue(bar2.exists)
+            }
+
+            // test creates intermediary directories
+            try bar1.copy(into: root1.create.directories)
+
+            // test doesn’t replace file if “copy into” a file
+            let d = try root1.fuz.touch()
+            XCTAssertThrowsError(try root1.baz.touch().copy(into: d))
+            XCTAssert(d.isFile)
+            XCTAssert(root1.baz.isFile)
+        }
+    }
+
+    func testMoveTo() throws {
+        try Path.mktemp { tmpdir in
+            try tmpdir.foo.touch().move(to: tmpdir.bar)
+            XCTAssertFalse(tmpdir.foo.exists)
+            XCTAssert(tmpdir.bar.isFile)
+            XCTAssertThrowsError(try tmpdir.foo.touch().move(to: tmpdir.bar))
+            try tmpdir.foo.move(to: tmpdir.bar, overwrite: true)
+        }
+
+        // test move errors if directory exists at destination, even with overwrite
+        try Path.mktemp { root in
+            try root.foo.touch()
+            XCTAssert(root.foo.isFile)
+            XCTAssertThrowsError(try root.foo.move(to: root.bar.mkdir()))
+            XCTAssertThrowsError(try root.foo.move(to: root.bar, overwrite: true))
+        }
+    }
+
+    func testMoveInto() throws {
+        try Path.mktemp { root1 in
+            let bar1 = try root1.join("bar").touch()
+            try Path.mktemp { root2 in
+                let bar2 = try root2.join("bar").touch()
+                XCTAssertThrowsError(try bar1.move(into: root2))
+                try bar1.move(into: root2, overwrite: true)
+                XCTAssertFalse(bar1.exists)
+                XCTAssertTrue(bar2.exists)
+            }
+
+            // test creates intermediary directories
+            try root1.baz.touch().move(into: root1.create.directories)
+            XCTAssertFalse(root1.baz.exists)
+            XCTAssert(root1.create.directories.baz.isFile)
+
+            // test doesn’t replace file if “move into” a file
+            let d = try root1.fuz.touch()
+            XCTAssertThrowsError(try root1.baz.touch().move(into: d))
+            XCTAssert(d.isFile)
+            XCTAssert(root1.baz.isFile)
+        }
+    }
+
+    func testRename() throws {
+        try Path.mktemp { root in
+            do {
+                let file = try root.bar.touch()
+                let foo = try file.rename(to: "foo")
+                XCTAssertFalse(file.exists)
+                XCTAssertTrue(foo.isFile)
+            }
+            do {
+                let file = try root.bar.touch()
+                XCTAssertThrowsError(try file.rename(to: "foo"))
             }
         }
     }
+
+    func testCommonDirectories() {
+        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)
+        XCTAssertEqual(Path.applicationSupport.string, NSHomeDirectory() + "/Library/Application Support")
+
+        _ = defaultUrl(for: .documentDirectory)
+        _ = defaultUrl(for: .cachesDirectory)
+        _ = defaultUrl(for: .applicationSupportDirectory)
+    #endif
+    }
+
+    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 {
+        XCTAssert(Path(#file)!.isFile)
+        XCTAssert(Path(#file)!.isReadable)
+        XCTAssert(Path(#file)!.isWritable)
+        XCTAssert(Path(#file)!.isDeletable)
+        XCTAssert(Path(#file)!.parent.isDirectory)
+
+        try Path.mktemp { tmpdir in
+            XCTAssertTrue(tmpdir.isDirectory)
+            XCTAssertFalse(tmpdir.isFile)
+
+            let bar = try tmpdir.bar.touch().chmod(0o000)
+            XCTAssertFalse(bar.isReadable)
+            XCTAssertFalse(bar.isWritable)
+            XCTAssertFalse(bar.isDirectory)
+            XCTAssertFalse(bar.isExecutable)
+            XCTAssertTrue(bar.isFile)
+            XCTAssertTrue(bar.isDeletable)  // can delete even if no read permissions
+
+            try bar.chmod(0o777)
+            XCTAssertTrue(bar.isReadable)
+            XCTAssertTrue(bar.isWritable)
+            XCTAssertTrue(bar.isDeletable)
+            XCTAssertTrue(bar.isExecutable)
+
+            try bar.delete()
+            XCTAssertFalse(bar.exists)
+            XCTAssertFalse(bar.isReadable)
+            XCTAssertFalse(bar.isWritable)
+            XCTAssertFalse(bar.isExecutable)
+            XCTAssertFalse(bar.isDeletable)
+
+            let nonExistantFile = tmpdir.baz
+            XCTAssertFalse(nonExistantFile.exists)
+            XCTAssertFalse(nonExistantFile.isExecutable)
+            XCTAssertFalse(nonExistantFile.isReadable)
+            XCTAssertFalse(nonExistantFile.isWritable)
+            XCTAssertFalse(nonExistantFile.isDeletable)
+            XCTAssertFalse(nonExistantFile.isDirectory)
+            XCTAssertFalse(nonExistantFile.isFile)
+
+            let baz = try tmpdir.baz.touch()
+            XCTAssertTrue(baz.isDeletable)
+            try tmpdir.chmod(0o500)  // remove write permission on directory
+            XCTAssertFalse(baz.isDeletable)  // this is how deletion is prevented on UNIX
+        }
+    }
+
+    func testTimes() throws {
+        try Path.mktemp { tmpdir in
+            let now1 = Date().timeIntervalSince1970.rounded(.down)
+            sleep(1)
+            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)
+        }
+    }
+
+    func testDelete() throws {
+        try Path.mktemp { tmpdir in
+            try tmpdir.bar1.delete()
+            try tmpdir.bar2.touch().delete()
+            try tmpdir.bar3.touch().chmod(0o000).delete()
+        #if !os(Linux)
+            XCTAssertThrowsError(try tmpdir.bar3.touch().lock().delete())
+        #endif
+
+            // 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)
+
+            // for code-coverage
+            XCTAssertEqual(tmpdir.bar6.kind, .file)
+        }
+    }
+
+    func testRelativeCodable() throws {
+        let path = Path(Path.home.foo)
+        let encoder = JSONEncoder()
+        encoder.userInfo[.relativePath] = Path.home
+        let data = try encoder.encode([path])
+        let decoder = JSONDecoder()
+        decoder.userInfo[.relativePath] = Path.home
+        XCTAssertEqual(try decoder.decode([Path].self, from: data), [path])
+        decoder.userInfo[.relativePath] = Path.documents
+        XCTAssertEqual(try decoder.decode([Path].self, from: data), [Path(Path.documents.foo)])
+        XCTAssertThrowsError(try JSONDecoder().decode([Path].self, from: data))
+    }
+
+    func testBundleExtensions() throws {
+        try Path.mktemp { tmpdir -> Void in
+            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)
+            XCTAssertEqual(bndl.resources, tmpdir)
+            XCTAssertNil(bndl.path(forResource: "foo", ofType: "bar"))
+            XCTAssertNil(bndl.executable)
+
+        #if os(macOS)
+            XCTAssertEqual(bndl.defaultSharedFrameworksPath, tmpdir.Contents.Frameworks)
+            XCTAssertEqual(bndl.defaultResourcesPath, tmpdir.Contents.Resources)
+        #elseif os(tvOS) || os(iOS) || os(watchOS)
+            XCTAssertEqual(bndl.defaultSharedFrameworksPath, tmpdir.Frameworks)
+            XCTAssertEqual(bndl.defaultResourcesPath, tmpdir)
+        #else
+            XCTAssertEqual(bndl.defaultSharedFrameworksPath, tmpdir.lib)
+            XCTAssertEqual(bndl.defaultResourcesPath, tmpdir.share)
+        #endif
+        }
+    }
+
+    func testDataExtensions() throws {
+        let data = try Data(contentsOf: Path(#file)!)
+        try Path.mktemp { tmpdir in
+            _ = try data.write(to: tmpdir.foo)
+            _ = try data.write(to: tmpdir.foo, atomically: true)
+        }
+    }
+
+    func testStringExtensions() throws {
+        let string = try String(contentsOf: Path(#file)!)
+        try Path.mktemp { tmpdir in
+            _ = try string.write(to: tmpdir.foo)
+        }
+    }
+
+    func testFileHandleExtensions() throws {
+        _ = try FileHandle(forReadingAt: Path(#file)!)
+        _ = try FileHandle(forWritingAt: Path(#file)!)
+        _ = try FileHandle(forUpdatingAt: Path(#file)!)
+    }
+
+    func testSort() {
+        XCTAssertEqual([Path.root.a, Path.root.c, Path.root.b].sorted(), [Path.root.a, Path.root.b, Path.root.c])
+    }
+
+    func testLock() throws {
+    #if !os(Linux)
+        try Path.mktemp { tmpdir in
+            let bar = try tmpdir.bar.touch()
+            try bar.lock()
+            XCTAssertThrowsError(try bar.touch())
+            try bar.unlock()
+            try bar.touch()
+
+            // a non existant file is already “unlocked”
+            try tmpdir.nonExit.unlock()
+        }
+    #endif
+    }
+
+    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)
+        }
+    }
+
+    func testSymlinkFunctions() throws {
+        try Path.mktemp { tmpdir in
+            let foo = try tmpdir.foo.touch()
+            let bar = try foo.symlink(as: tmpdir.bar)
+            XCTAssert(bar.isSymlink)
+            XCTAssertEqual(try bar.readlink(), foo)
+        }
+
+        try Path.mktemp { tmpdir in
+            let foo1 = try tmpdir.foo.touch()
+            let foo2 = try foo1.symlink(into: tmpdir.bar)
+            XCTAssert(foo2.isSymlink)
+            XCTAssert(tmpdir.bar.isDirectory)
+            XCTAssertEqual(try foo2.readlink(), foo1)
+
+            // cannot symlink into when `into` is an existing entry that is not a directory
+            let baz = try tmpdir.baz.touch()
+            XCTAssertThrowsError(try foo1.symlink(into: baz))
+        }
+
+        try Path.mktemp { tmpdir in
+            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)
+        }
+    }
+
+    func testReadlinkOnRelativeSymlink() throws {
+        //TODO how to test on iOS etc.?
+    #if os(macOS) || os(Linux)
+        try Path.mktemp { tmpdir in
+            let foo = try tmpdir.foo.mkdir()
+            let bar = try tmpdir.bar.touch()
+
+            let task = Process()
+            task.currentDirectoryPath = foo.string
+            task.launchPath = "/bin/ln"
+            task.arguments = ["-s", "../bar", "baz"]
+            task.launch()
+            task.waitUntilExit()
+            XCTAssertEqual(task.terminationStatus, 0)
+
+            XCTAssert(tmpdir.foo.baz.isSymlink)
+
+            XCTAssertEqual(try FileManager.default.destinationOfSymbolicLink(atPath: tmpdir.foo.baz.string), "../bar")
+
+            XCTAssertEqual(try tmpdir.foo.baz.readlink(), bar)
+        }
+    #endif
+    }
+
+    func testReadlinkOnFileReturnsSelf() throws {
+        try Path.mktemp { tmpdir in
+            XCTAssertEqual(try tmpdir.foo.touch(), tmpdir.foo)
+            XCTAssertEqual(try tmpdir.foo.readlink(), tmpdir.foo)
+        }
+    }
+
+    func testReadlinkOnNonExistantFileThrows() throws {
+        try Path.mktemp { tmpdir in
+            XCTAssertThrowsError(try tmpdir.bar.readlink())
+        }
+    }
+
+    func testReadlinkWhereLinkDestinationDoesNotExist() throws {
+        try Path.mktemp { tmpdir in
+            let bar = try tmpdir.foo.symlink(as: tmpdir.bar)
+            XCTAssertEqual(try bar.readlink(), tmpdir.foo)
+        }
+    }
+
+    func testNoUndesiredSymlinkResolution() throws {
+
+        // this test because NSString.standardizingPath will resolve symlinks
+        // if the path you give it contains .. and the result is an actual entry
+
+        try Path.mktemp { tmpdir in
+            let foo = try tmpdir.foo.mkdir()
+            try foo.join("bar").mkdir().join("fuz").touch()
+            let baz = DynamicPath(try foo.symlink(as: tmpdir.baz))
+            XCTAssert(baz.isSymlink)
+            XCTAssert(baz.bar.isDirectory)
+            XCTAssertEqual(baz.bar.join("..").string, "\(tmpdir)/baz")
+
+            XCTAssertEqual(Path("\(tmpdir)/baz/bar/..")?.string, "\(tmpdir)/baz")
+        }
+    }
+
+    func testRealpath() throws {
+        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 f = try e.symlink(as: tmpdir.f)
+            XCTAssertEqual(try f.readlink(), e)
+            XCTAssertEqual(try f.realpath(), c)
+        }
+
+        try Path.mktemp { tmpdir in
+            XCTAssertThrowsError(try tmpdir.foo.realpath())
+        }
+    }
+
+    func testFileReference() throws {
+        let ref = Path.home.fileReferenceURL
+    #if !os(Linux)
+        XCTAssertTrue(ref?.isFileReferenceURL() ?? false)
+    #endif
+        XCTAssertEqual(ref?.path, Path.home.string)
+    }
+
+    func testURLInitializer() throws {
+        XCTAssertEqual(Path(url: Path.home.url), Path.home)
+        XCTAssertEqual(Path.home.fileReferenceURL.flatMap(Path.init), Path.home)
+        XCTAssertNil(Path(url: URL(string: "https://foo.com")!))
+        XCTAssertNil(Path(url: NSURL(string: "https://foo.com")!))
+    }
+
+    func testInitializerForRelativePath() throws {
+        XCTAssertNil(Path("foo"))
+        XCTAssertNil(Path("../foo"))
+        XCTAssertNil(Path("./foo"))
+    }
+
+    func testPathComponents() throws {
+        XCTAssertEqual(Path.root.foo.bar.components, ["foo", "bar"])
+        XCTAssertEqual(Path.root.components, [])
+    }
+
+    func testFlatMap() throws {
+        // testing compile works
+        let foo: String? = "/a"
+        _ = foo.flatMap(Path.init)
+        let bar: Substring? = "/a"
+        _ = bar.flatMap(Path.init)
+        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)
+        }
+    }
+    
+    func testOptionalInitializer() throws {
+        XCTAssertNil(Path(""))
+        XCTAssertNil(Path("./foo"))
+        XCTAssertEqual(Path("/foo"), Path.root.foo)
+    }
 }

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.
@@ -42,12 +42,16 @@ class TemporaryDirectory {
     }
 
     deinit {
-        _ = try? FileManager.default.removeItem(at: url)
+        do {
+            try path.chmod(0o777).delete()
+        } catch {
+            //TODO log
+        }
     }
 }
 
 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

@@ -1,27 +1,78 @@
+#if !canImport(ObjectiveC)
 import XCTest
 
 extension PathTests {
-    static let __allTests = [
+    // DO NOT MODIFY: This is autogenerated, use:
+    //   `swift test --generate-linuxmain`
+    // to regenerate.
+    static let __allTests__PathTests = [
         ("testBasename", testBasename),
+        ("testBundleExtensions", testBundleExtensions),
         ("testCodable", testCodable),
+        ("testCommonDirectories", testCommonDirectories),
         ("testConcatenation", testConcatenation),
         ("testCopyInto", testCopyInto),
+        ("testCopyTo", testCopyTo),
+        ("testCopyToExistingDirectoryFails", testCopyToExistingDirectoryFails),
+        ("testDataExtensions", testDataExtensions),
+        ("testDelete", testDelete),
+        ("testDynamicMember", testDynamicMember),
         ("testEnumeration", testEnumeration),
         ("testEnumerationSkippingHiddenFiles", testEnumerationSkippingHiddenFiles),
         ("testExists", testExists),
+        ("testExtension", testExtension),
+        ("testFileHandleExtensions", testFileHandleExtensions),
+        ("testFileReference", testFileReference),
+        ("testFilesystemAttributes", testFilesystemAttributes),
+        ("testFindCallingExecuteTwice", testFindCallingExecuteTwice),
+        ("testFindDepth0", testFindDepth0),
+        ("testFindDepthRange", testFindDepthRange),
+        ("testFindExecute", testFindExecute),
+        ("testFindExtension", testFindExtension),
+        ("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),
+        ("testReadlinkOnRelativeSymlink", testReadlinkOnRelativeSymlink),
+        ("testReadlinkWhereLinkDestinationDoesNotExist", testReadlinkWhereLinkDestinationDoesNotExist),
+        ("testRealpath", testRealpath),
+        ("testRelativeCodable", testRelativeCodable),
         ("testRelativePathCodable", testRelativePathCodable),
         ("testRelativeTo", testRelativeTo),
+        ("testRename", testRename),
+        ("testSort", testSort),
+        ("testStringConvertibles", testStringConvertibles),
+        ("testStringExtensions", testStringExtensions),
+        ("testSymlinkFunctions", testSymlinkFunctions),
+        ("testTimes", testTimes),
+        ("testTouchThrowsIfCannotWrite", testTouchThrowsIfCannotWrite),
+        ("testURLInitializer", testURLInitializer),
     ]
 }
 
-#if !os(macOS)
 public func __allTests() -> [XCTestCaseEntry] {
     return [
-        testCase(PathTests.__allTests),
+        testCase(PathTests.__allTests__PathTests),
     ]
 }
 #endif

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