Path(_ url:) -> Path(url:)

Fill in this TODO in README
[skip ci]
2019-02-11 20:40:27 -05:00 · 2019-02-11 15:13:14 -05:00 · 2019-02-11 15:11:22 -05:00 · 2019-02-11 15:06:56 -05:00 · 2019-02-11 14:19:27 -05:00 · 2019-02-11 14:04:06 -05:00
15 changed files with 1038 additions and 138 deletions
--- a/.github/codecov.yml
+++ b/.github/codecov.yml
@@ -0,0 +1,2 @@
+ignore:
+  - Tests
--- a/.github/ranger.yml
+++ b/.github/ranger.yml
@@ -0,0 +1,2 @@
+merges:
+  - action: delete_branch
--- a/.travis.yml
+++ b/.travis.yml
@@ -19,9 +19,10 @@ jobs:
      name: macOS / Swift 4.2.1

    - &xcodebuild
-      before_install: swift package generate-xcodeproj
+      before_install: swift package generate-xcodeproj --enable-code-coverage
      xcode_destination: platform=iOS Simulator,OS=latest,name=iPhone XS
      name: iOS / Swift 4.2.1
+      after_success: bash <(curl -s https://codecov.io/bash)
    - <<: *xcodebuild
      xcode_destination: platform=tvOS Simulator,OS=latest,name=Apple TV
      name: tvOS / Swift 4.2.1
@@ -34,6 +35,7 @@ jobs:
          -scheme Path.swift-Package \
          -destination 'platform=watchOS Simulator,OS=latest,name=Apple Watch Series 4 - 40mm' \
          build | xcpretty
+      after_success: false

    - &linux
      env: SWIFT_VERSION=4.2.1
@@ -88,12 +90,15 @@ jobs:
          tags: true

    - name: CocoaPods
-      before_install: |
+      before_install: export TRAVIS_REPO_NAME=${TRAVIS_REPO_SLUG#*/}
+      install: gem install cocoapods
+      before_script: |
        export DESCRIPTION=$(swift - <<\ \ EOF
          import Foundation
          struct Response: Decodable { let description: String }
          let token = ProcessInfo.processInfo.environment["GITHUB_TOKEN"]!
-          let url = URL(string: "https://api.github.com/repos/mxcl/Path.swift")!
+          let slug = ProcessInfo.processInfo.environment["TRAVIS_REPO_SLUG"]!
+          let url = URL(string: "https://api.github.com/repos/\(slug)")!
          var rq = URLRequest(url: url)
          rq.setValue("token \(token)", forHTTPHeaderField: "Authorization")
          let semaphore = DispatchSemaphore(value: 0)
@@ -106,15 +111,15 @@ jobs:
          let rsp = try JSONDecoder().decode(Response.self, from: data)
          print(rsp.description, terminator: "")
        EOF)
-        cat <<\ \ EOF> Path.swift.podspec
+        cat <<\ \ EOF> $TRAVIS_REPO_NAME.podspec
        Pod::Spec.new do |s|
-          s.name = 'Path.swift'
+          s.name = ENV['TRAVIS_REPO_NAME']
          s.version = ENV['TRAVIS_TAG']
          s.summary = ENV['DESCRIPTION']
-          s.homepage = 'https://github.com/mxcl/Path.swift'
-          s.license = { :type => 'Unlicense', :file => 'LICENSE.md' }
-          s.author = { 'mxcl' => 'mxcl@me.com' }
-          s.source = { :git => 'https://github.com/mxcl/Path.swift.git', :tag => s.version.to_s }
+          s.homepage = "https://github.com/#{ENV['TRAVIS_REPO_SLUG']}"
+          s.license = { type: 'Unlicense', file: 'LICENSE.md' }
+          s.author = { mxcl: 'mxcl@me.com' }
+          s.source = { git: "https://github.com/#{ENV['TRAVIS_REPO_SLUG']}.git", tag: s.version }
          s.social_media_url = 'https://twitter.com/mxcl'
          s.osx.deployment_target = '10.10'
          s.ios.deployment_target = '8.0'
@@ -124,5 +129,4 @@ jobs:
          s.swift_version = '4.2'
        end
        EOF
-      install: gem install cocoapods --pre
      script: pod trunk push
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# 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 end
 results.
@@ -33,10 +33,10 @@ print(foo)         // => /bar/foo
 print(foo.isFile)  // => true

 // we support dynamic members (_use_sparingly_):
-let prefs = Path.home.Library.Preferences
+let prefs = Path.home.Library.Preferences  // => /Users/mxcl/Library/Preferences

 // a practical example: installing a helper executable
-try Bundle.resources.join("helper").copy(into: Path.home.join(".local/bin").mkdir(.p)).chmod(0o500)
+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
@@ -57,7 +57,8 @@ help me continue my work, I appreciate it x

 # 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

@@ -107,8 +108,9 @@ let ls = Path.root.usr.bin.ls  // => /usr/bin/ls
 ```

 This is less commonly useful than you would think, hence our documentation
-does not use it. Usually you are joining variables or other `String` arguments.
-However when you need it, it’s *lovely*.
+does not use it. Usually you are joining variables or other `String` arguments
+or trying to describe files (and files usually have extensions). However when
+you need it, it’s *lovely*.

 ## Initializing from user-input

@@ -160,13 +162,32 @@ for entry in Path.home.ls() where entry.path.mtime > yesterday {
    //…
 }

-let dirs = Path.home.ls().directories().filter {
-    //…
-}
+let dirs = Path.home.ls().directories
+
+let files = Path.home.ls().files

 let swiftFiles = Path.home.ls().files(withExtension: "swift")
 ```

+# `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 get on
+with your work without worries.
+
+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.
@@ -183,6 +204,10 @@ 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
+
 // of course, feel free to join variables:
 let b = "b"
 let c = "c"
@@ -195,39 +220,96 @@ 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.foo           // => /foo
+
+// unless you do it explicitly
+try Path.foo.readlink()  // => /bar
+                         // `readlink` only resolves the *final* path component,
+                         // thus use `realpath` if there are multiple symlinks
 ```

-*Path.swift* has the general policty that if the desired end result preexists,
+*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 with specifying `overwrite`
 and the file already exists at the destination and is identical, we don’t check
 for that as the check was deemed too expensive to be worthwhile.

+## 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`), but we do *not* for
+    `Path.init`, *nor* if you are joining a path that ends up being one of these
+    paths, (eg. `Path.root.join("var/private')`).
+
+## 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`.
+
+If you must then use `FileManager.changeCurrentDirectory`.
+
+# 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
+
 # Installation

 SwiftPM:

 ```swift
-package.append(.package(url: "https://github.com/mxcl/Path.swift", from: "0.5.0"))
+package.append(.package(url: "https://github.com/mxcl/Path.swift.git", from: "0.13.0"))
 ```

 CocoaPods:

 ```ruby
-pod 'Path.swift' ~> '0.5.0'
+pod 'Path.swift', '~> 0.13'
 ```

 Carthage:

 > Waiting on: [@Carthage#1945](https://github.com/Carthage/Carthage/pull/1945).

-## Please note
+## Pre‐1.0 status

 We are pre 1.0, thus we can change the API as we like, and we will (to the
 pursuit of getting it *right*)! We will tag 1.0 as soon as possible.
@@ -238,6 +320,7 @@ 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
@@ -245,4 +328,11 @@ https://codebasesaga.com/canopy/

 [badge-platforms]: https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20iOS%20%7C%20tvOS%20%7C%20watchOS-lightgrey.svg
 [badge-languages]: https://img.shields.io/badge/swift-4.2%20%7C%205.0-orange.svg
-[online API documentation]: https://mxcl.github.io/Path.swift/Structs/Path.html
+[docs]: https://mxcl.github.io/Path.swift/Structs/Path.html
+[badge-jazzy]: https://raw.githubusercontent.com/mxcl/Path.swift/gh-pages/badge.svg?sanitize=true
+[badge-codecov]: https://codecov.io/gh/mxcl/Path.swift/branch/master/graph/badge.svg
+[badge-ci]: https://travis-ci.com/mxcl/Path.swift.svg
+[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
--- a/Sources/Extensions.swift
+++ b/Sources/Extensions.swift
@@ -9,32 +9,25 @@ public extension Bundle {
        return str.flatMap(Path.init)
    }

-    /// Returns the path for the shared-frameworks directory in this bundle.
+    /**
+     Returns the path for the shared-frameworks directory in this bundle.
+     - Note: This is typically `ShareFrameworks`
+    */
    var sharedFrameworks: Path {
-        var `default`: Path {
-          #if os(macOS)
-            return path.join("Contents/Frameworks")
-          #elseif os(Linux)
-            return path.join("lib")
-          #else
-            return path.join("Frameworks")
-          #endif
+        return sharedFrameworksPath.flatMap(Path.init) ?? defaultSharedFrameworksPath
    }
-        return sharedFrameworksPath.flatMap(Path.init) ?? `default`
+
+    /**
+     Returns the path for the private-frameworks directory in this bundle.
+     - Note: This is typically `Frameworks`
+    */
+    var privateFrameworks: Path {
+        return privateFrameworksPath.flatMap(Path.init) ?? defaultSharedFrameworksPath
    }

    /// Returns the path for the resources directory in this bundle.
    var resources: Path {
-        var `default`: Path {
-          #if os(macOS)
-            return path.join("Contents/Resources")
-          #elseif os(Linux)
-            return path.join("share")
-          #else
-            return path
-          #endif
-        }
-        return resourcePath.flatMap(Path.init) ?? `default`
+        return resourcePath.flatMap(Path.init) ?? defaultResourcesPath
    }

    /// Returns the path for this bundle.
@@ -107,3 +100,25 @@ public extension FileHandle {
        try self.init(forUpdating: path.url)
    }
 }
+
+internal extension Bundle {
+    var defaultSharedFrameworksPath: Path {
+      #if os(macOS)
+        return path.join("Contents/Frameworks")
+      #elseif os(Linux)
+        return path.join("lib")
+      #else
+        return path.join("Frameworks")
+      #endif
+    }
+
+    var defaultResourcesPath: Path {
+      #if os(macOS)
+        return path.join("Contents/Resources")
+      #elseif os(Linux)
+        return path.join("share")
+      #else
+        return path
+      #endif
+    }
+}
--- a/Sources/Path+Attributes.swift
+++ b/Sources/Path+Attributes.swift
@@ -5,30 +5,28 @@ public extension Path {

    /**
     Returns the creation-time of the file.
-     - Note: Returns UNIX-time-zero if there is no creation-time, this should only happen if the file doesn’t exist.
+     - Note: Returns `nil` if there is no creation-time, this should only happen if the file doesn’t exist.
+     - Important: On Linux this is filesystem dependendent and may not exist.
     */
-    var ctime: Date {
+    var ctime: Date? {
        do {
            let attrs = try FileManager.default.attributesOfItem(atPath: string)
-            return attrs[.creationDate] as? Date ?? Date(timeIntervalSince1970: 0)
+            return attrs[.creationDate] as? Date
        } catch {
-            //TODO log error
-            return Date(timeIntervalSince1970: 0)
+            return nil
        }
    }

    /**
     Returns the modification-time of the file.
-     - Note: Returns the creation time if there is no modification time.
-     - Note: Returns UNIX-time-zero if neither are available, this should only happen if the file doesn’t exist.
+     - Note: If this returns `nil` and the file exists, something is very wrong.
     */
-    var mtime: Date {
+    var mtime: Date? {
        do {
            let attrs = try FileManager.default.attributesOfItem(atPath: string)
-            return attrs[.modificationDate] as? Date ?? ctime
+            return attrs[.modificationDate] as? Date
        } catch {
-            //TODO log error
-            return Date(timeIntervalSince1970: 0)
+            return nil
        }
    }

@@ -43,23 +41,34 @@ public extension Path {
        return self
    }
    
-    /// - Note: If file is already locked, does nothing
-    /// - Note: If file doesn’t exist, throws
+    /**
+     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 self
    }

-    /// - Note: If file isn‘t locked, does nothing
-    /// - Note: If file doesn’t exist, does nothing
+    /**
+     - Note: If file isn‘t locked, does nothing.
+     - Note: If file doesn’t exist, does nothing.
+     - Important: On Linux does nothing.
+     - SeeAlso: `lock()`
+     */
    @discardableResult
    func unlock() throws -> Path {
+    #if !os(Linux)
        var attrs: [FileAttributeKey: Any]
        do {
            attrs = try FileManager.default.attributesOfItem(atPath: string)
@@ -71,6 +80,7 @@ public extension Path {
            attrs[.immutable] = false
            try FileManager.default.setAttributes(attrs, ofItemAtPath: string)
        }
+    #endif
        return self
    }
 }
--- a/Sources/Path+CommonDirectories.swift
+++ b/Sources/Path+CommonDirectories.swift
@@ -47,18 +47,7 @@ extension Path {
            fatalError()
        }
    #else    
-        guard let pathString = FileManager.default.urls(for: searchPath, in: .userDomainMask).first?.path else {
-            switch searchPath {
-            case .documentDirectory:
-                return Path.home/"Documents"
-            case .applicationSupportDirectory:
-                return Path.home/"Library/Application Support"
-            case .cachesDirectory:
-                return Path.home/"Library/Caches"
-            default:
-                fatalError()
-            }
-        }
+        guard let pathString = FileManager.default.urls(for: searchPath, in: .userDomainMask).first?.path else { return defaultUrl(for: searchPath) }
        return Path(string: pathString)
    #endif
    }
@@ -90,3 +79,19 @@ extension Path {
        return path(for: .applicationSupportDirectory)
    }
 }
+
+#if !os(Linux)
+func defaultUrl(for searchPath: FileManager.SearchPathDirectory) -> Path {
+    switch searchPath {
+    case .documentDirectory:
+        return Path.home/"Documents"
+    case .applicationSupportDirectory:
+        return Path.home/"Library/Application Support"
+    case .cachesDirectory:
+        return Path.home/"Library/Caches"
+    default:
+        fatalError()
+    }
+}
+#endif
+
--- a/Sources/Path+FileManager.swift
+++ b/Sources/Path+FileManager.swift
@@ -1,4 +1,7 @@
 import Foundation
+#if os(Linux)
+import Glibc
+#endif

 public extension Path {
    //MARK: File Management
@@ -25,6 +28,11 @@ public extension Path {
        if overwrite, to.isFile, isFile {
            try FileManager.default.removeItem(at: to.url)
        }
+    #if os(Linux) && !swift(>=5.1) // check if fixed
+        if !overwrite, to.isFile {
+            throw CocoaError.error(.fileWriteFileExists)
+        }
+    #endif
        try FileManager.default.copyItem(atPath: string, toPath: to.string)
        return to
    }
@@ -38,7 +46,8 @@ public extension Path {
         // Create ~/.local/bin, copy `ls` there and make the new copy executable
         try Path.root.join("bin/ls").copy(into: Path.home.join(".local/bin").mkdir(.p)).chmod(0o500)

-     If the destination does not exist, this function creates the directory first.
+     If the destination does not exist, this function creates the directory
+     (including intermediary directories if necessary) first.

     - Parameter into: Destination directory
     - Parameter overwrite: If true overwrites any file that already exists at `into`.
@@ -48,25 +57,21 @@ public extension Path {
      `self` because even though *Path.swift’s* policy is to noop if the desired
       end result preexists, checking for this condition is too expensive a
       trade-off.
-     - SeeAlso: `copy(into:overwrite:)`
+     - SeeAlso: `copy(to:overwrite:)`
     */
    @discardableResult
    func copy(into: Path, overwrite: Bool = false) throws -> Path {
        if !into.exists {
-            try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+            try into.mkdir(.p)
        }
        let rv = into/basename()
        if overwrite, rv.isFile {
            try rv.delete()
        }
-    #if os(Linux)
-    #if swift(>=5.1)
-        // check if fixed
-    #else
+    #if os(Linux) && !swift(>=5.1) // check if fixed
        if !overwrite, rv.isFile {
            throw CocoaError.error(.fileWriteFileExists)
        }
-    #endif
    #endif
        try FileManager.default.copyItem(at: url, to: rv.url)
        return rv
@@ -86,11 +91,11 @@ public extension Path {
       `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:)
+     - SeeAlso: `move(into:overwrite:)`
     */
    @discardableResult
    func move(to: Path, overwrite: Bool = false) throws -> Path {
-        if overwrite, to.exists {
+        if overwrite, to.isFile {
            try FileManager.default.removeItem(at: to.url)
        }
        try FileManager.default.moveItem(at: url, to: to.url)
@@ -103,22 +108,26 @@ public extension Path {
         try Path.root.join("bar").move(into: .home)
         // => "/Users/mxcl/bar"

-     If the destination does not exist, this function creates the directory first.
+     If the destination does not exist, this function creates the directory
+     (including intermediary directories if necessary) first.

     - Parameter into: Destination directory
     - 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
-    func move(into: Path) throws -> Path {
+    func move(into: Path, overwrite: Bool = false) throws -> Path {
        if !into.exists {
            try into.mkdir(.p)
        } else if !into.isDirectory {
            throw CocoaError.error(.fileWriteFileExists)
        }
        let rv = into/basename()
+        if overwrite, rv.isFile {
+            try FileManager.default.removeItem(at: rv.url)
+        }
        try FileManager.default.moveItem(at: url, to: rv.url)
        return rv
    }
@@ -127,6 +136,9 @@ public extension Path {
     Deletes the path, recursively if a directory.
     - Note: noop: if the path doesn’t exist
     ∵ *Path.swift* doesn’t error if desired end result preexists.
+     - 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”
+     - SeeAlso: `lock()`
    */
    @inlinable
    func delete() throws {
@@ -136,13 +148,26 @@ public extension Path {
    }

    /**
-     Creates an empty file at this path.
+     Creates an empty file at this path or if the file exists, updates its modification time.
     - Returns: `self` to allow chaining.
     */
    @inlinable
    @discardableResult
    func touch() throws -> Path {
-        return try "".write(to: self)
+        if !exists {
+            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 self
    }

    /**
@@ -171,6 +196,47 @@ public extension Path {
        }
        return self
    }
+
+    /**
+     Renames the file at path.
+
+         Path.root.foo.bar.rename(to: "baz")  // => /foo/baz
+
+     - Parameter to: the new basename for the file
+     - Returns: The renamed path.
+     */
+    @discardableResult
+    func rename(to newname: String) throws -> Path {
+        let newpath = parent/newname
+        try FileManager.default.moveItem(atPath: string, toPath: newpath.string)
+        return newpath
+    }
+
+    /**
+     Creates a symlink of this file at `as`.
+     - Note: If `self` does not exist, is **not** an error.
+     */
+    @discardableResult
+    func symlink(as: Path) throws -> Path {
+        try FileManager.default.createSymbolicLink(atPath: `as`.string, withDestinationPath: string)
+        return `as`
+    }
+
+    /**
+     Creates a symlink of this file with the same filename in the `into` directory.
+     - Note: If into does not exist, creates the directory with intermediate directories if necessary.
+     */
+    @discardableResult
+    func symlink(into dir: Path) throws -> Path {
+        if !dir.exists {
+            try dir.mkdir(.p)
+        } else if !dir.isDirectory {
+            throw CocoaError.error(.fileWriteFileExists)
+        }
+        let dst = dir/basename()
+        try FileManager.default.createSymbolicLink(atPath: dst.string, withDestinationPath: string)
+        return dst
+    }
 }

 /// Options for `Path.mkdir(_:)`
--- a/Sources/Path+StringConvertibles.swift
+++ b/Sources/Path+StringConvertibles.swift
@@ -1,5 +1,3 @@
-import class Foundation.NSString
-
 extension Path: CustomStringConvertible {    
    /// Returns `Path.string`
    public var description: String {
@@ -10,6 +8,6 @@ extension Path: CustomStringConvertible {
 extension Path: CustomDebugStringConvertible {
    /// Returns eg. `Path(string: "/foo")`
    public var debugDescription: String {
-        return "Path(string: \(string))"
+        return "Path(\(string))"
    }
 }
--- a/Sources/Path+ls.swift
+++ b/Sources/Path+ls.swift
@@ -51,7 +51,14 @@ public extension Array where Element == Entry {
        }
    }

-    /// Filters the list of entries to be a list of Paths that are files with the specified extension
+    /// Filters the list of entries to be a list of Paths that are files.
+    var files: [Path] {
+        return compactMap {
+            $0.kind == .file ? $0.path : nil
+        }
+    }
+
+    /// Filters the list of entries to be a list of Paths that are files with the specified extension.
    func files(withExtension ext: String) -> [Path] {
        return compactMap {
            $0.kind == .file && $0.path.extension == ext ? $0.path : nil
--- a/Sources/Path->Bool.swift
+++ b/Sources/Path->Bool.swift
@@ -1,4 +1,9 @@
 import Foundation
+#if os(Linux)
+import func Glibc.access
+#else
+import Darwin
+#endif

 public extension Path {
    //MARK: Filesystem Properties
@@ -32,11 +37,29 @@ public extension Path {
        
    /// Returns true if the path represents an actual file that is also deletable by the current user.
    var isDeletable: Bool {
-        return FileManager.default.isDeletableFile(atPath: string)
+    #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 
    }
 }
--- a/Sources/Path.swift
+++ b/Sources/Path.swift
@@ -1,4 +1,11 @@
 import Foundation
+#if !os(Linux)
+import func Darwin.realpath
+let _realpath = Darwin.realpath
+#else
+import func Glibc.realpath
+let _realpath = Glibc.realpath
+#endif

 /**
 A `Path` represents an absolute path on a filesystem.
@@ -9,7 +16,7 @@ import Foundation
 `Path` supports `Codable`, and can be configured to
 [encode paths *relatively*](https://github.com/mxcl/Path.swift/#codable).

- Sorting a `Sequence` of `Path`s will return the locale-aware sort order, which
+ 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
@@ -20,32 +27,109 @@ import Foundation
     let p3 = Path.cwd/relativePathString
     let p4 = Path(userInput) ?? Path.cwd/userInput

- If you are constructing Paths from static-strings we provide support for
+ If you are constructing paths from static-strings we provide support for
 dynamic members:

     let p1 = Path.root.usr.bin.ls  // => /usr/bin/ls

- - Note: There may not be an actual filesystem entry at the path. The underlying
-   representation for `Path` is `String`.
+ - Note: A `Path` does not necessarily represent an actual filesystem entry.
 */

@dynamicMemberLookup
 public struct Path: Equatable, Hashable, Comparable {

    init(string: String) {
+        assert(string.first == "/")
+        assert(string.last != "/" || string == "/")
+        assert(string.split(separator: "/").contains("..") == false)
        self.string = string
    }

-    /// Returns `nil` unless fed an absolute path
+    /**
+     Creates a new absolute, standardized path.
+     - 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`.
+     */
    public init?(_ description: String) {
-        guard description.starts(with: "/") || description.starts(with: "~/") else { return nil }
-        self.init(string: (description as NSString).standardizingPath)
+        var pathComponents = description.split(separator: "/")
+        switch description.first {
+        case "/":
+            break
+        case "~":
+            if description == "~" {
+                self = Path.home
+                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)
+            pathComponents.insert(contentsOf: tilded.split(separator: "/"), at: 0)
+        default:
+            return nil
+        }
+
+    #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: description) {
+                pathComponents.removeFirst(n)
+            }
+        }
+
+        ifExists(withPrefix: "/private/var/automount", removeFirst: 3)
+        ifExists(withPrefix: "/var/automount", removeFirst: 2)
+        ifExists(withPrefix: "/private", removeFirst: 1)
+    #endif
+
+        self.string = join_(prefix: "/", pathComponents: pathComponents)
+    }
+
+    /**
+     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
    }

    /// :nodoc:
-    public subscript(dynamicMember pathComponent: String) -> Path {
-        let str = (string as NSString).appendingPathComponent(pathComponent)
-        return Path(string: str)
+    public subscript(dynamicMember addendum: String) -> Path {
+        //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 Path(string: join_(prefix: string, appending: addendum))
    }

 //MARK: Properties
@@ -58,6 +142,21 @@ public struct Path: Equatable, Hashable, Comparable {
        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.
+     */
+    public 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
+    }
+
    /**
     Returns the parent directory for this path.

@@ -67,16 +166,38 @@ public struct Path: Equatable, Hashable, Comparable {
     - Note: always returns a valid path, `Path.root.parent` *is* `Path.root`.
     */
    public var parent: Path {
-        return Path(string: (string as NSString).deletingLastPathComponent)
+        let index = string.lastIndex(of: "/")!
+        let substr = string[string.indices.startIndex..<index]
+        return Path(string: String(substr))
    }

    /**
     Returns the filename extension of this path.
-     - Remark: Implemented via `NSString.pathExtension`.
+     - Remark: If there is no extension returns "".
+     - Remark: If the filename ends with any number of ".", returns "".
+     - Note: We special case eg. `foo.tar.gz`.
     */
    @inlinable
    public var `extension`: String {
-        return (string as NSString).pathExtension
+        //FIXME efficiency
+        switch true {
+        case string.hasSuffix(".tar.gz"):
+            return "tar.gz"
+        case string.hasSuffix(".tar.bz"):
+            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 ""
+            }
+        }
    }

 //MARK: Pathing
@@ -89,14 +210,15 @@ public struct Path: Equatable, Hashable, Comparable {
         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./(_:, _:)`
+     - SeeAlso: `Path./(_:_:)`
     */
-    public func join<S>(_ pathComponent: S) -> Path where S: StringProtocol {
-        //TODO standardizingPath does more than we want really (eg tilde expansion)
-        let str = (string as NSString).appendingPathComponent(String(pathComponent))
-        return Path(string: (str as NSString).standardizingPath)
+    public func join<S>(_ addendum: S) -> Path where S: StringProtocol {
+        return Path(string: join_(prefix: string, appending: addendum))
    }

    /**
@@ -107,6 +229,9 @@ public struct Path: Equatable, Hashable, Comparable {
         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.
@@ -164,18 +289,72 @@ public struct Path: Equatable, Hashable, Comparable {
     - Parameter dropExtension: If `true` returns the basename without its file extension.
     */
    public func basename(dropExtension: Bool = false) -> String {
-        let str = string as NSString
+        var lastPathComponent: Substring {
+            let slash = string.lastIndex(of: "/")!
+            let index = string.index(after: slash)
+            return string[index...]
+        }
+        var go: Substring {
            if !dropExtension {
-            return str.lastPathComponent
+                return lastPathComponent
            } else {
-            let ext = str.pathExtension
+                let ext = self.extension
                if !ext.isEmpty {
-                return String(str.lastPathComponent.dropLast(ext.count + 1))
+                    return lastPathComponent.dropLast(ext.count + 1)
                } else {
-                return str.lastPathComponent
+                    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
+     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.
+     */
+    public func readlink() throws -> Path {
+        do {
+            let rv = try FileManager.default.destinationOfSymbolicLink(atPath: string)
+            return Path(rv) ?? parent/rv
+        } catch CocoaError.fileReadUnknown {
+            // file is not symlink, return `self`
+            assert(exists)
+            return self
+        } catch {
+        #if os(Linux)
+            // ugh: Swift on Linux
+            let nsError = error as NSError
+            if nsError.domain == NSCocoaErrorDomain, nsError.code == CocoaError.fileReadUnknown.rawValue, exists {
+                return self
+            }
+        #endif
+            throw error
+        }
+    }
+
+    /// Recursively resolves symlinks in this path.
+    public 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:
@@ -184,3 +363,38 @@ public struct Path: Equatable, Hashable, Comparable {
        return lhs.string.compare(rhs.string, locale: .current) == .orderedAscending
    }
 }
+
+@inline(__always)
+private func join_<S>(prefix: String, appending: S) -> String where S: StringProtocol {
+    return join_(prefix: prefix, pathComponents: appending.split(separator: "/"))
+}
+
+private func join_<S>(prefix: String, pathComponents: S) -> String where S: Sequence, S.Element: StringProtocol {
+    assert(prefix.first == "/")
+
+    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)"
+            }
+        }
+    }
+    return rv
+}
--- a/Tests/PathTests/PathTests.swift
+++ b/Tests/PathTests/PathTests.swift
@@ -1,5 +1,5 @@
+@testable import Path
 import XCTest
-import Path

 class PathTests: XCTestCase {
    func testConcatenation() {
@@ -9,26 +9,36 @@ 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.a.mkdir().c.touch()
-        try tmpdir.b.touch()
+        try tmpdir.join("b.swift").touch()
        try tmpdir.c.touch()
        try tmpdir.join(".d").mkdir().e.touch()

        var paths = Set<String>()
+        let lsrv = try tmpdir.ls()
        var dirs = 0
-        for entry in try tmpdir.ls() {
+        for entry in lsrv {
            if entry.kind == .directory {
                dirs += 1
            }
            paths.insert(entry.path.basename())
        }
        XCTAssertEqual(dirs, 2)
-        XCTAssertEqual(paths, ["a", "b", "c", ".d"])
+        XCTAssertEqual(dirs, lsrv.directories.count)
+        XCTAssertEqual(["a", ".d"], Set(lsrv.directories.map{ $0.relative(to: tmpdir) }))
+        XCTAssertEqual(["b.swift", "c"], Set(lsrv.files.map{ $0.relative(to: tmpdir) }))
+        XCTAssertEqual(["b.swift"], Set(lsrv.files(withExtension: "swift").map{ $0.relative(to: tmpdir) }))
+        XCTAssertEqual(["c"], Set(lsrv.files(withExtension: "").map{ $0.relative(to: tmpdir) }))
+        XCTAssertEqual(paths, ["a", "b.swift", "c", ".d"])
        
    }

@@ -69,6 +79,22 @@ 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!
        try Path.mktemp {
@@ -89,28 +115,32 @@ class PathTests: XCTestCase {
    }

    func testBasename() {
-        XCTAssertEqual(Path.root.join("foo.bar").basename(dropExtension: true), "foo")
-        XCTAssertEqual(Path.root.join("foo").basename(dropExtension: true), "foo")
-        XCTAssertEqual(Path.root.join("foo.").basename(dropExtension: true), "foo.")
-        XCTAssertEqual(Path.root.join("foo.bar.baz").basename(dropExtension: true), "foo.bar")
+        for prefix in [Path.root, Path.root.foo, Path.root.foo.bar] {
+            XCTAssertEqual(prefix.join("foo.bar").basename(dropExtension: true), "foo")
+            XCTAssertEqual(prefix.join("foo").basename(dropExtension: true), "foo")
+            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]
        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
        ]

        let encoder = JSONEncoder()
        encoder.userInfo[.relativePath] = root
        let data = try encoder.encode(input)

-        XCTAssertEqual(try JSONSerialization.jsonObject(with: data) as? [String], ["foo"])
+        XCTAssertEqual(try JSONSerialization.jsonObject(with: data) as? [String], ["..", "", "bar"])

        let decoder = JSONDecoder()
        XCTAssertThrowsError(try decoder.decode([Path].self, from: data))
@@ -130,8 +160,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")
@@ -144,16 +182,410 @@ class PathTests: XCTestCase {

        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.home.parent.string)/~foo")
+    }
+
+    func testCopyTo() throws {
+        try Path.mktemp { root in
+            try root.foo.touch().copy(to: root.bar)
+            XCTAssert(root.foo.isFile)
+            XCTAssert(root.bar.isFile)
+            XCTAssertThrowsError(try root.foo.copy(to: root.bar))
+            try root.foo.copy(to: root.bar, overwrite: true)
+        }
+
+        // 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
-            let bar = try root.join("bar").touch()
+            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
-                try root.join("bar").touch()
-                XCTAssertThrowsError(try bar.copy(into: root))
-                try bar.copy(into: root, overwrite: true)
+            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 !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(/)")
+    }
+
+    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 foo = try tmpdir.foo.touch()
+            let now1 = Date().timeIntervalSince1970.rounded(.down)
+        #if !os(Linux)
+            XCTAssertEqual(foo.ctime?.timeIntervalSince1970.rounded(.down), now1)  //FIXME flakey
+        #endif
+            XCTAssertEqual(foo.mtime?.timeIntervalSince1970.rounded(.down), now1)  //FIXME flakey
+            sleep(1)
+            try foo.touch()
+            let now2 = Date().timeIntervalSince1970.rounded(.down)
+            XCTAssertNotEqual(now1, now2)
+            XCTAssertEqual(foo.mtime?.timeIntervalSince1970.rounded(.down), now2)  //FIXME flakey
+
+            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
+        }
+    }
+
+    func testRelativeCodable() throws {
+        let 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.documents.foo])
+        XCTAssertThrowsError(try JSONDecoder().decode([Path].self, from: data))
+    }
+
+    func testBundleExtensions() throws {
+        try Path.mktemp { tmpdir in
+            let bndl = Bundle(path: tmpdir.string)!
+            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"))
+
+        #if os(macOS)
+            XCTAssertEqual(bndl.defaultSharedFrameworksPath, tmpdir.Contents.Frameworks)
+            XCTAssertEqual(bndl.defaultResourcesPath, tmpdir.Contents.Resources)
+        #elseif os(tvOS) || os(iOS)
+            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
+            try tmpdir.chmod(0o000)
+            XCTAssertThrowsError(try tmpdir.bar.touch())
+        }
+    }
+
+    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.bar.mkdir().fuz.touch()
+            let baz = 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"))
+    }
 }
--- a/Tests/PathTests/TemporaryDirectory.swift
+++ b/Tests/PathTests/TemporaryDirectory.swift
@@ -42,7 +42,11 @@ class TemporaryDirectory {
    }

    deinit {
-        _ = try? FileManager.default.removeItem(at: url)
+        do {
+            try path.chmod(0o777).delete()
+        } catch {
+            //TODO log
+        }
    }
 }

--- a/Tests/PathTests/XCTestManifests.swift
+++ b/Tests/PathTests/XCTestManifests.swift
@@ -3,19 +3,47 @@ import XCTest
 extension PathTests {
    static let __allTests = [
        ("testBasename", testBasename),
+        ("testBundleExtensions", testBundleExtensions),
        ("testCodable", testCodable),
+        ("testCommonDirectories", testCommonDirectories),
        ("testConcatenation", testConcatenation),
        ("testCopyInto", testCopyInto),
+        ("testCopyTo", testCopyTo),
+        ("testDataExtensions", testDataExtensions),
+        ("testDelete", testDelete),
        ("testDynamicMember", testDynamicMember),
        ("testEnumeration", testEnumeration),
        ("testEnumerationSkippingHiddenFiles", testEnumerationSkippingHiddenFiles),
        ("testExists", testExists),
+        ("testExtension", testExtension),
+        ("testFileHandleExtensions", testFileHandleExtensions),
+        ("testFileReference", testFileReference),
+        ("testFilesystemAttributes", testFilesystemAttributes),
+        ("testInitializerForRelativePath", testInitializerForRelativePath),
        ("testIsDirectory", testIsDirectory),
        ("testJoin", testJoin),
+        ("testLock", testLock),
        ("testMkpathIfExists", testMkpathIfExists),
        ("testMktemp", testMktemp),
+        ("testMoveInto", testMoveInto),
+        ("testMoveTo", testMoveTo),
+        ("testNoUndesiredSymlinkResolution", testNoUndesiredSymlinkResolution),
+        ("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),
    ]
 }
Author	SHA1	Message	Date
Max Howell	c9d300a7b6	Path(_ url:) -> Path(url:)	2019-02-11 20:40:27 -05:00
Max Howell	ed4b773870	Fill in this TODO in README [skip ci]	2019-02-11 15:13:14 -05:00
Max Howell	097e020735	There are no usernames on iOS etc.	2019-02-11 15:11:22 -05:00
Max Howell	be49fb9e49	Merge pull request #34 from mxcl/symlinks Symlink funcs & support `NSURL` file-refs	2019-02-11 15:06:56 -05:00
Max Howell	164cd2b413	Fix iOS, etc.	2019-02-11 14:19:27 -05:00
Max Howell	709c3fb99d	Symlink funcs & support `NSURL` file-refs * Also removes most `NSString` usage * Also does more thorough testing in some places * Also adds * Fixes `Path?(_:)` resolving symlinks in some cases	2019-02-11 14:04:06 -05:00
repo-ranger[bot]	6c84754ad8	Merge pull request #33 from mxcl/bundle-private-frameworks Bundle.privateFrameworks	2019-02-09 18:32:02 +00:00
Max Howell	8469565b06	Bundle.privateFrameworks	2019-02-09 13:24:57 -05:00
Max Howell	ed45d10179	Docs updates; CocoaPods 16.0 release; [ci skip]	2019-02-08 09:14:23 -05:00
Max Howell	8033ae49b4	Add [pathos] [pathos]: https://github.com/dduan/Pathos [skip ci]	2019-02-04 12:05:14 -05:00
Max Howell	b290173486	Update travis scripts	2019-02-04 12:04:48 -05:00
Max Howell	8248354a80	Some documentation improvements	2019-02-01 15:18:15 -05:00
Max Howell	14963e48f5	Merge pull request #30 from mxcl/codecov More coverage	2019-02-01 10:26:59 -05:00
Max Howell	7f5340bc19	More coverage Though I can hardly test these functions, at least we can verify they run without crashing etc.	2019-02-01 10:17:37 -05:00
Max Howell	74074c634f	Merge pull request #29 from mxcl/codecov More coverage	2019-01-31 21:33:50 -05:00
Max Howell	74656bbfcd	More coverage	2019-01-31 21:17:37 -05:00
Max Howell	cced2af2cd	Merge pull request #28 from mxcl/codecov More coverage	2019-01-31 19:17:43 -05:00
Max Howell	b9abd07318	More coverage	2019-01-31 19:09:36 -05:00
Max Howell	6b52932e7b	Merge pull request #27 from mxcl/codecov More coverage	2019-01-31 16:29:08 -05:00
Max Howell	c456081e65	More coverage	2019-01-31 14:26:09 -05:00
Max Howell	ec6c0113f9	Remaining code coverage Can’t do coverage for Linux unfortunately.	2019-01-31 13:11:50 -05:00
Max Howell	7970c4d8a7	Document robustness & XP [ci skip]	2019-01-31 12:38:41 -05:00
Max Howell	e342da8644	Remove auto-tagging since I can do this manually	2019-01-31 12:28:16 -05:00
Max Howell	9aa91c649e	Merge pull request #26 from mxcl/codecov Increase code coverage	2019-01-31 12:25:41 -05:00
Max Howell	62ea0d47b3	Fixes & increased code coverage	2019-01-31 12:15:31 -05:00
repo-ranger[bot]	ab9a70e947	Merge pull request #25 from mxcl/rename Refactor rename -> rename(to:)	2019-01-31 15:32:59 +00:00
Max Howell	49ef073e34	Refactor rename -> rename(to:)	2019-01-31 10:15:39 -05:00
Max Howell	889d825b3a	Merge pull request #24 from mxcl/rename Rename	2019-01-31 10:08:02 -05:00
Max Howell	f1cd06fdff	Add CI post success hook yamls	2019-01-31 09:58:46 -05:00
Max Howell	c6e840b9b6	Add `rename`	2019-01-31 08:39:54 -05:00
Max Howell	eb34ac4af8	Add overwrite parameter to move(into:)	2019-01-31 08:37:32 -05:00
Max Howell	66ae86c986	Enable codecov.io	2019-01-31 08:37:14 -05:00
Max Howell	c432f710eb	Merge pull request #22 from mxcl/files() Entry.files defaults to all files	2019-01-28 12:17:08 -05:00
Max Howell	19c0c19bb6	Entry.files defaults to all files	2019-01-28 12:04:47 -05:00
Max Howell	ee1f46954c	Fixes #20 [skip ci]	2019-01-28 11:05:51 -05:00