Deploy to CocoaPods

Common Directories

.travis.yml

@@ -0,0 +1,72 @@
+# only run for: merge commits, releases and pull-requests
+if: type != push OR branch = master OR branch =~ /^\d+\.\d+(\.\d+)?(-\S*)?$/
+
+stages:
+  - name: test
+  - name: deploy
+    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
+
+    - <<: *xcodebuild
+      stage: deploy
+      name: Jazzy
+      install: gem install jazzy
+      script: |
+        jazzy \
+          --no-hide-documentation-coverage \
+          --theme fullwidth \
+          --output output \
+          --readme README.md \
+          --root-url https://mxcl.github.io/Path.swift/ \
+          --github_url https://github.com/mxcl/Path.swift \
+          --module Path \
+          --module-version $TRAVIS_TAG
+      deploy:
+        provider: pages
+        skip-cleanup: true
+        github-token: $GITHUB_TOKEN
+        local-dir: output
+        on:
+          tags: true
+
+    - stage: deploy
+      name: CocoaPods
+      install: gem install cocoapods --pre
+      script: pod trunk push --allow-warnings

Path.swift.podspec

@@ -0,0 +1,19 @@
+Pod::Spec.new do |s|
+  s.name             = 'Path.swift'
+  s.version          = '0.4.0'
+  s.summary          = 'Delightful, robust file-pathing functions'
+  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.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

README.md

@@ -1,9 +1,11 @@
-# Path.swift
+# Path.swift ![badge-platforms] ![badge-languages] [![Build Status](https://travis-ci.com/mxcl/Path.swift.svg)](https://travis-ci.com/mxcl/Path.swift)
 
 A file-system pathing library focused on developer experience and robust
 end‐results.
 
 ```swift
+import Path
+
 // convenient static members
 let home = Path.home
 
@@ -14,19 +16,20 @@ let docs = Path.home/"Documents"
 let path = Path(userInput) ?? Path.cwd/userInput
 
 // chainable syntax so you have less boilerplate
-try Path.home.join("foo").mkpath().join("bar").chmod(0o555)
+try Path.home.join("foo").mkdir().join("bar").touch().chmod(0o555)
 
 // easy file-management
-try Path.root.join("foo").copy(to: Path.root.join("bar"))
+try Path.root.join("foo").copy(to: Path.root/"bar")
 
 // careful API to avoid common bugs
 try Path.root.join("foo").copy(into: Path.root.mkdir("bar"))
-// ^^ other libraries would make the `to:` form handle both these cases
+// ^^ other libraries would make the above `to:` form handle both these cases
 // but that can easily lead to bugs where you accidentally write files that
 // were meant to be directory destinations
 ```
 
-Paths are just string representations, there *may not* be a real file there.
+We emphasize safety and correctness, just like Swift, and also just
+like Swift, we provide a thoughtful and comprehensive (yet concise) API.
 
 # Support mxcl
 
@@ -38,6 +41,12 @@ can continue to make tools and software you need and love. I appreciate it x.
 	<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.
+
 ## Codable
 
 We support `Codable` as you would expect:
@@ -90,6 +99,11 @@ 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`,
+the same conformance as that `Int`, `Float` etc. conform. The protocol enforces
+a nameless initialization and since it is appropriate for us to conform to it,
+we do.
+
 ## Extensions
 
 We have some extensions to Apple APIs:
@@ -112,16 +126,16 @@ We provide `ls()`, called because it behaves like the Terminal `ls` function,
 the name thus implies its behavior, ie. that it is not recursive.
 
 ```swift
-for path in Path.home.ls() {
-    print(path.path)
-    print(path.kind)  // .directory or .file
+for entry in Path.home.ls() {
+    print(entry.path)
+    print(entry.kind)  // .directory or .file
 }
 
-for path in Path.home.ls() where path.kind == .file {
+for entry in Path.home.ls() where entry.kind == .file {
     //…
 }
 
-for path in Path.home.ls() where path.mtime > yesterday {
+for entry in Path.home.ls() where entry.path.mtime > yesterday {
     //…
 }
 
@@ -132,14 +146,66 @@ let dirs = Path.home.ls().directories().filter {
 let swiftFiles = Path.home.ls().files(withExtension: "swift")
 ```
 
-# Installation
+# Rules & Caveats
 
-SwiftPM only:
+Paths are just string representations, there *might not* be a real file there.
 
 ```swift
-package.append(.package(url: "https://github.com/mxcl/Path.swift", from: "0.0.0"))
+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
+Path.home/"b/c"    // => /Users/mxcl/b/c
+
+// joining with absolute paths omits prefixed slash
+Path.home/"/b"     // => /Users/mxcl/b
+
+// of course, feel free to join variables:
+let b = "b"
+let c = "c"
+Path.home/b/c      // => /Users/mxcl/b/c
+
+// tilde is not special here
+Path.root/"~b"     // => /~b
+Path.root/"~/b"    // => /~/b
+
+// but is here
+Path("~/foo")!     // => /Users/mxcl/foo
+
+// this does not work though
+Path("~foo")       // => nil
 ```
 
+# Installation
+
+SwiftPM:
+
+```swift
+package.append(.package(url: "https://github.com/mxcl/Path.swift", from: "0.4.0"))
+```
+
+CocoaPods:
+
+```ruby
+pod 'Path.swift' ~> 0.4.0
+```
+
+Please note! We are pre 1.0, thus we can change the API as we like! We will tag
+1.0 as soon as possible.
+
 ### Get push notifications for new releases
 
 https://codebasesaga.com/canopy/
+
+# Alternatives
+
+* [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
+[online API documentation]: https://mxcl.github.io/Path.swift/

Sources/Extensions.swift

@@ -1,22 +1,31 @@
 import Foundation
 
 public extension Bundle {
+    /// Returns the path for requested resource in this bundle.
     func path(forResource: String, ofType: String?) -> Path? {
         let f: (String?, String?) -> String? = path(forResource:ofType:)
         let str = f(forResource, ofType)
         return str.flatMap(Path.init)
     }
 
+    /// Returns the path for the shared-frameworks directory in this bundle.
     public var sharedFrameworks: Path? {
         return sharedFrameworksPath.flatMap(Path.init)
     }
 
+    /// Returns the path for the resources directory in this bundle.
     public var resources: Path? {
         return resourcePath.flatMap(Path.init)
     }
+
+    /// Returns the path for this bundle.
+    public var path: Path {
+        return Path(string: bundlePath)
+    }
 }
 
 public extension String {
+    /// Initializes this `String` with the contents of the provided path.
     @inlinable
     init(contentsOf path: Path) throws {
         try self.init(contentsOfFile: path.string)
@@ -32,6 +41,7 @@ public extension String {
 }
 
 public extension Data {
+    /// Initializes this `Data` with the contents of the provided path.
     @inlinable
     init(contentsOf path: Path) throws {
         try self.init(contentsOf: path.url)
@@ -43,7 +53,11 @@ public extension Data {
     func write(to: Path, atomically: Bool = false) throws -> Path {
         let opts: NSData.WritingOptions
         if atomically {
+        #if !os(Linux)
             opts = .atomicWrite
+        #else
+            opts = .atomic
+        #endif
         } else {
             opts = []
         }

Sources/Path+Attributes.swift

@@ -43,14 +43,18 @@ public extension Path {
         return self
     }
 
-    /// - Returns: modification-time or creation-time if none
+    /**
+     Returns the modification-time.
+     - Note: Returns the creation time if there is no modification time.
+     - Note: Returns UNIX-time-zero if neither are available, though this *should* be impossible.
+     */
     public var mtime: Date {
         do {
             let attrs = try FileManager.default.attributesOfItem(atPath: string)
             return attrs[.modificationDate] as? Date ?? attrs[.creationDate] as? Date ?? Date()
         } catch {
-            //TODO print(error)
-            return Date()
+            //TODO log error
+            return Date(timeIntervalSince1970: 0)
         }
     }
 }

Sources/Path+Codable.swift

@@ -1,6 +1,7 @@
 import Foundation
 
 public extension CodingUserInfoKey {
+    /// If set paths are encoded as relative to this path.
     static let relativePath = CodingUserInfoKey(rawValue: "dev.mxcl.Path.relative")!
 }
 

Sources/Path+CommonDirectories.swift

@@ -0,0 +1,90 @@
+import Foundation
+
+extension Path {
+    /// Returns a `Path` containing ``FileManager.default.currentDirectoryPath`.
+    public static var cwd: Path {
+        return Path(string: FileManager.default.currentDirectoryPath)
+    }
+
+    /// Returns a `Path` representing the root path.
+    public static var root: Path {
+        return Path(string: "/")
+    }
+
+    /// Returns a `Path` representing the user’s home directory
+    public static var home: Path {
+        let string: String
+      #if os(macOS)
+        if #available(OSX 10.12, *) {
+            string = FileManager.default.homeDirectoryForCurrentUser.path
+        } else {
+            string = NSHomeDirectory()
+        }
+      #else
+        string = NSHomeDirectory()
+      #endif
+        return Path(string: string)
+    }
+
+    /// Helper to allow search path and domain mask to be passed in.
+    private static func path(for searchPath: FileManager.SearchPathDirectory) -> Path {
+    #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 }
+
+        switch searchPath {
+        case .documentDirectory:
+            return Path.home/"Documents"
+        case .applicationSupportDirectory:
+            return foo("XDG_DATA_HOME", Path.home/".local/share")
+        case .cachesDirectory:
+            return foo("XDG_CACHE_HOME", Path.home/".cache")
+        default:
+            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()
+            }
+        }
+        return Path(string: pathString)
+    #endif
+    }
+
+    /**
+     The root for user documents.
+     - 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 {
+        return path(for: .documentDirectory)
+    }
+
+    /**
+     The root for cache files.
+     - Note: On Linux this is 'XDG_CACHE_HOME'.
+     - Note: You should create a subdirectory before creating any files.
+     */
+    public static var caches: Path {
+        return path(for: .cachesDirectory)
+    }
+
+    /**
+     For data that supports your running application.
+     - Note: On Linux is `XDG_DATA_HOME`.
+     - Note: You should create a subdirectory before creating any files.
+     */
+    public static var applicationSupport: Path {
+        return path(for: .applicationSupportDirectory)
+    }
+}

Sources/Path+FileManager.swift

@@ -41,6 +41,34 @@ public extension Path {
         return rv
     }
 
+    /**
+     Moves a file.
+     - Note: `throws` if `to` is a directory.
+     - 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:)
+     */
+    @discardableResult
+    public func move(to: Path, overwrite: Bool = false) throws -> Path {
+        if overwrite, to.exists {
+            try FileManager.default.removeItem(at: to.url)
+        }
+        try FileManager.default.moveItem(at: url, to: to.url)
+        return to
+    }
+
+    /**
+     Moves a file into a directory
+
+     If the destination does not exist, this function creates the directory 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 destination filename.
+     - SeeAlso: move(into:overwrite:)
+     */
     @discardableResult
     public func move(into: Path) throws -> Path {
         if !into.exists {
@@ -48,45 +76,82 @@ public extension Path {
         } else if !into.isDirectory {
             throw CocoaError.error(.fileWriteFileExists)
         }
-        try FileManager.default.moveItem(at: url, to: into.join(basename()).url)
-        return self
+        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.
+     - Returns: `self` to allow chaining.
+     */
     @inlinable
     @discardableResult
     func touch() throws -> Path {
         return try "".write(to: self)
     }
 
-    @inlinable
+    /// Helper due to Linux Swift being incomplete.
+    private func _foo(go: () throws -> Void) throws {
+    #if !os(Linux)
+        do {
+            try go()
+        } catch CocoaError.Code.fileWriteFileExists {
+            // noop
+        }
+    #else
+        do {
+            try go()
+        } catch {
+            let error = error as NSError
+            guard error.domain == NSCocoaErrorDomain, error.code == CocoaError.Code.fileWriteFileExists.rawValue else {
+                throw error
+            }
+        }
+    #endif
+    }
+
+    /**
+     Creates the directory at this path.
+     - Note: Does not create any intermediary directories.
+     - Returns: `self` to allow chaining.
+     */
     @discardableResult
     public func mkdir() throws -> Path {
-        do {
-            try FileManager.default.createDirectory(at: url, withIntermediateDirectories: false, attributes: nil)
-        } catch CocoaError.Code.fileWriteFileExists {
-            // noop
+        try _foo {
+            try FileManager.default.createDirectory(at: self.url, withIntermediateDirectories: false, attributes: nil)
         }
         return self
     }
 
-    @inlinable
+    /**
+     Creates the directory at this path.
+     - Note: Creates any intermediary directories, if required.
+     - Returns: `self` to allow chaining.
+     */
     @discardableResult
     public func mkpath() throws -> Path {
-        do {
+        try _foo {
             try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true, attributes: nil)
-        } catch CocoaError.Code.fileWriteFileExists {
-            // noop
         }
         return self
     }
 
-    /// - Note: If file doesn’t exist, creates file
-    /// - Note: If file is not writable, makes writable first, resetting permissions after the write
+    /**
+     Replaces the contents of the file at this path with the provided string.
+     - Note: If file doesn’t exist, creates file
+     - 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 {
         let resetPerms: Int?

Sources/Path+StringConvertibles.swift

@@ -9,12 +9,14 @@ extension Path: LosslessStringConvertible {
 }
 
 extension Path: CustomStringConvertible {
+    /// Returns `Path.string`
     public var description: String {
         return string
     }
 }
 
 extension Path: CustomDebugStringConvertible {
+    /// Returns eg. `Path(string: "/foo")`
     public var debugDescription: String {
         return "Path(string: \(string))"
     }

Sources/Path+ls.swift

@@ -13,12 +13,14 @@ public extension Path {
 }
 
 public extension Array where Element == Path.Entry {
+    /// Filters the list of entries to be a list of Paths that are directories.
     var directories: [Path] {
         return compactMap {
             $0.kind == .directory ? $0.path : nil
         }
     }
 
+    /// Filters the list of entries to be a list of Paths that are files with the specified extension
     func files(withExtension ext: String) -> [Path] {
         return compactMap {
             $0.kind == .file && $0.path.extension == ext ? $0.path : nil

Sources/Path->Bool.swift

@@ -1,20 +1,29 @@
 import Foundation
 
 public extension Path {
+    /// 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 directory.
     var isDirectory: Bool {
         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.
     var isFile: Bool {
         var isDir: ObjCBool = true
         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.
+    var isExecutable: Bool {
+        return FileManager.default.isExecutableFile(atPath: string)
+    }
+
+    /// Returns true if the path represents an actual filesystem entry.
     var exists: Bool {
         return FileManager.default.fileExists(atPath: string)
     }

Sources/Path.swift

@@ -1,35 +1,57 @@
 import Foundation
 
+/**
+ Represents a platform filesystem absolute path.
+
+ The recommended conversions from string are:
+
+     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 filename at the path.
+ */
 public struct Path: Equatable, Hashable, Comparable {
+    /// The underlying filesystem path
     public let string: String
 
-    public static var cwd: Path {
-        return Path(string: FileManager.default.currentDirectoryPath)
-    }
-
-    public static var root: Path {
-        return Path(string: "/")
-    }
-
-    public static var home: Path {
-        return Path(string: NSHomeDirectory())
-    }
-
+    /**
+     Returns the filename extension of this path.
+     - Remark: Implemented via `NSString.pathExtension`.
+     */
     @inlinable
     public var `extension`: String {
         return (string as NSString).pathExtension
     }
 
-    /// - Note: always returns a valid path, `Path.root.parent` *is* `Path.root`
+    /**
+     Returns the parent directory for this path.
+
+     Path is not aware of the nature of the underlying file, but this is
+     irrlevant since the operation is the same irrespective of this fact.
+
+     - Note: always returns a valid path, `Path.root.parent` *is* `Path.root`.
+     */
     public var parent: Path {
         return Path(string: (string as NSString).deletingLastPathComponent)
     }
 
+    /// Returns a `URL` representing this file path.
     @inlinable
     public var url: URL {
         return URL(fileURLWithPath: string)
     }
 
+    /**
+     The basename for the provided file, optionally dropping the file extension.
+
+         Path.root.join("foo.swift").basename()  // => "foo.swift"
+         Path.root.join("foo.swift").basename(dropExtension: true)  // => "foo"
+
+     - 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 {
         let str = string as NSString
         if !dropExtension {
@@ -44,7 +66,13 @@ public struct Path: Equatable, Hashable, Comparable {
         }
     }
 
-    //TODO another variant that returns `nil` if result would start with `..`
+    /**
+     Returns a string representing the relative path to `base`.
+
+     - Note: If `base` is not a logical prefix for `self` your result will be prefixed some number of `../` components.
+     - 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 {
         // Split the two paths into their components.
         // FIXME: The is needs to be optimized to avoid unncessary copying.
@@ -75,27 +103,59 @@ public struct Path: Equatable, Hashable, Comparable {
         }
     }
 
-    public func join<S>(_ part: S) -> Path where S: StringProtocol {
+    /**
+     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
+
+     - Parameter pathComponent: The string to join with this path.
+     - Returns: A new joined path.
+     - SeeAlso: /(:Path,:String)
+     */
+    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(part))
+        let str = (string as NSString).appendingPathComponent(String(pathComponent))
         return Path(string: (str as NSString).standardizingPath)
     }
 
+    /// Returns the locale-aware sort order for the two paths.
     @inlinable
     public static func <(lhs: Path, rhs: Path) -> Bool {
         return lhs.string.compare(rhs.string, locale: .current) == .orderedAscending
     }
 
+    /// A file entry from a directory listing.
     public struct Entry {
+        /// The kind of this directory entry.
         public enum Kind {
+            /// The path is a file.
             case file
+            /// The path is a directory.
             case directory
         }
+        /// The kind of this entry.
         public let kind: Kind
+        /// The path of this entry.
         public let path: Path
     }
 }
 
+/**
+ 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/TemporaryDirectory.swift

@@ -1,21 +0,0 @@
-import Foundation
-
-public class TemporaryDirectory {
-    public let url: URL
-    public var path: Path { return Path(string: url.path) }
-
-    public init() throws {
-        url = try FileManager.default.url(for: .itemReplacementDirectory, in: .userDomainMask, appropriateFor: URL(fileURLWithPath: "/"), create: true)
-    }
-
-    deinit {
-        _ = try? FileManager.default.removeItem(at: url)
-    }
-}
-
-public extension Path {
-    static func mktemp<T>(body: (Path) throws -> T) throws -> T {
-        let tmp = try TemporaryDirectory()
-        return try body(tmp.path)
-    }
-}

Tests/PathTests/PathTests.swift

@@ -37,12 +37,12 @@ class PathTests: XCTestCase {
 
     func testExists() {
         XCTAssert(Path.root.exists)
-        XCTAssert((Path.root/"Users").exists)
+        XCTAssert((Path.root/"bin").exists)
     }
 
     func testIsDirectory() {
         XCTAssert(Path.root.isDirectory)
-        XCTAssert((Path.root/"Users").isDirectory)
+        XCTAssert((Path.root/"bin").isDirectory)
     }
 
     func testMktemp() throws {
@@ -93,4 +93,20 @@ class PathTests: XCTestCase {
         decoder.userInfo[.relativePath] = root
         XCTAssertEqual(try decoder.decode([Path].self, from: data), input)
     }
+
+    func testJoin() {
+        let prefix = Path.root/"Users/mxcl"
+
+        XCTAssertEqual(prefix/"b", Path("/Users/mxcl/b"))
+        XCTAssertEqual(prefix/"b"/"c", Path("/Users/mxcl/b/c"))
+        XCTAssertEqual(prefix/"b/c", Path("/Users/mxcl/b/c"))
+        XCTAssertEqual(prefix/"/b", Path("/Users/mxcl/b"))
+        let b = "b"
+        let c = "c"
+        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")
+        XCTAssertNil(Path("~foo"))
+    }
 }

Tests/PathTests/TemporaryDirectory.swift

@@ -0,0 +1,54 @@
+@testable import Path
+import Foundation
+
+class TemporaryDirectory {
+    let url: URL
+    var path: Path { return Path(string: url.path) }
+
+    /**
+     Creates a new temporary directory.
+
+     The directory is recursively deleted when this object deallocates.
+
+     If you need a temporary directory on a specific volume use the `appropriateFor`
+     parameter.
+
+     - Important: If you are moving a file, ensure to use the `appropriateFor`
+     parameter, since it is volume aware and moving the file across volumes will take
+     exponentially longer!
+     - Important: The `appropriateFor` parameter does not work on Linux.
+     - Parameter appropriateFor: The temporary directory will be located on this
+     volume.
+    */
+    init(appropriateFor: URL? = nil) throws {
+      #if !os(Linux)
+        let appropriate: URL
+        if let appropriateFor = appropriateFor {
+            appropriate = appropriateFor
+        } else if #available(OSX 10.12, iOS 10, tvOS 10, watchOS 3, *) {
+            appropriate = FileManager.default.temporaryDirectory
+        } else {
+            appropriate = URL(fileURLWithPath: NSTemporaryDirectory())
+        }
+        url = try FileManager.default.url(for: .itemReplacementDirectory, in: .userDomainMask, appropriateFor: appropriate, create: true)
+      #else
+        let envs = ProcessInfo.processInfo.environment
+        let env = envs["TMPDIR"] ?? envs["TEMP"] ?? envs["TMP"] ?? "/tmp"
+        let dir = Path.root/env/"swift-sh.XXXXXX"
+        var template = [UInt8](dir.string.utf8).map({ Int8($0) }) + [Int8(0)]
+        guard mkdtemp(&template) != nil else { throw CocoaError.error(.featureUnsupported) }
+        url = URL(fileURLWithPath: String(cString: template))
+      #endif
+    }
+
+    deinit {
+        _ = try? FileManager.default.removeItem(at: url)
+    }
+}
+
+extension Path {
+    static func mktemp<T>(body: (Path) throws -> T) throws -> T {
+        let tmp = try TemporaryDirectory()
+        return try body(tmp.path)
+    }
+}

Tests/PathTests/XCTestManifests.swift

@@ -15,7 +15,7 @@ extension PathTests {
     ]
 }
 
-#if !os(macOS)
+#if os(Linux)
 public func __allTests() -> [XCTestCaseEntry] {
     return [
         testCase(PathTests.__allTests),