Pathish

public protocol Pathish : Comparable, Hashable

A type that represents a filesystem path, if you conform your type to Pathish it is your responsibility to ensure the string is correctly normalized

string
The normalized string representation of the underlying filesystem path
Declaration
Swift

var string: String { get }

Filesystem Attributes

ctime Extension method
Returns the creation-time of the file.

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.
Declaration
Swift

var ctime: Date? { get }
mtime Extension method
Returns the modification-time of the file.

Note
If this returns nil and the file exists, something is very wrong.
Declaration
Swift

var mtime: Date? { get }


                    
                    
                    kind

Extension method

The type of the entry.

See also

Path.EntryType

Declaration

Swift

@available(*, deprecated, message: "- SeeAlso: Path.type")
var kind: Path.EntryType? { get }

type Extension method
The type of the entry.

See also
Path.EntryType
Declaration
Swift

var type: Path.EntryType? { get }


                    
                    
                    chmod(_:)

Extension method

Sets the file’s attributes using UNIX octal notation.

Path.home.join("foo").chmod(0o555)

Declaration

Swift

@discardableResult
func chmod(_ octal: Int) throws -> Path

Filesystem Locking

lock() Extension method
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.
Declaration
Swift

@discardableResult func lock() throws -> Path
unlock() Extension method
Note
If file isn‘t locked, does nothing.

Note
If file doesn’t exist, does nothing.

Important
On Linux does nothing.

See also
lock()
Declaration
Swift

@discardableResult func unlock() throws -> Path

File Management


                    
                    
                    copy(to:overwrite:)

Extension method

Copies a file.

try Path.root.join("bar").copy(to: Path.home/"foo")
// => "/Users/mxcl/foo"

Note

throws if to is a directory.

Note

If either self or to are directories,overwrite` is ignored.

Note

Throws if overwrite is false yet to is already identical to self because even though Path.swift’s policy is to noop if the desired end result preexists, checking for this condition is too expensive a trade-off.

See also

copy(into:overwrite:)

Declaration

Swift

@discardableResult
func copy<P>(to: P, overwrite: Bool = false) throws -> Path where P : Pathish

Parameters

`to`	Destination filename.
`overwrite`	If `true` and both `self` and `to` are files, overwrites `to`.

Return Value

to to allow chaining


                    
                    
                    copy(into:overwrite:)

Extension method

Copies a file into a directory

try Path.root.join("bar").copy(into: .home)
// => "/Users/mxcl/bar"

// 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 (including intermediary directories if necessary) first.

Note

throws if into is a file.

Note

See also

copy(to:overwrite:)

Declaration

Swift

@discardableResult
func copy<P>(into: P, overwrite: Bool = false) throws -> Path where P : Pathish

Parameters

`into`	Destination directory
`overwrite`	If true overwrites any file that already exists at `into`.

Return Value

The Path of the newly copied file.


                    
                    
                    move(to:overwrite:)

Extension method

Moves a file.

try Path.root.join("bar").move(to: Path.home/"foo")
// => "/Users/mxcl/foo"

Note

throws if to is a directory.

Note

See also

move(into:overwrite:)

Declaration

Swift

@discardableResult
func move<P>(to: P, overwrite: Bool = false) throws -> Path where P : Pathish

Parameters

`to`	Destination filename.
`overwrite`	If true overwrites any file that already exists at `to`.

Return Value

to to allow chaining


                    
                    
                    move(into:overwrite:)

Extension method

Moves a file into a directory

try Path.root.join("bar").move(into: .home)
// => "/Users/mxcl/bar"

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

Note

throws if into is a file.

See also

move(to:overwrite:)

Declaration

Swift

@discardableResult
func move<P>(into: P, overwrite: Bool = false) throws -> Path where P : Pathish

Parameters

`into`	Destination directory
`overwrite`	If true overwrites any file that already exists at `into`.

Return Value

The Path of destination filename.

delete() Extension method
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”

Note
If entry is a symlink, deletes the symlink.

See also
lock()
Declaration
Swift

@inlinable func delete() throws
touch() Extension method
Creates an empty file at this path or if the file exists, updates its modification time.
Declaration
Swift

@discardableResult @inlinable func touch() throws -> Path
Return Value

A copy of self to allow chaining.


                    
                    
                    mkdir(_:)

Extension method

Creates the directory at this path.

Note

We do not error if the directory already exists (even without .p) because Path.swift noops if the desired end result preexists.

Declaration

Swift

@discardableResult
func mkdir(_ options: MakeDirectoryOptions? = nil) throws -> Path

Parameters


                                options

Specify mkdir(.p) to create intermediary directories.

Return Value

A copy of self to allow chaining.


                    
                    
                    rename(to:)

Extension method

Renames the file (basename only) at path.

Path.root.foo.bar.rename(to: "baz")  // => /foo/baz

Declaration

Swift

@discardableResult
func rename(to newname: String) throws -> Path

Parameters

`to`	the new basename for the file

Return Value

The renamed path.

symlink(as:) Extension method
Creates a symlink of this file at as.

Note
If self does not exist, is not an error.
Declaration
Swift

@discardableResult func symlink<P>(as: P) throws -> Path where P : Pathish
symlink(into:) Extension method
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.
Declaration
Swift

@discardableResult func symlink<P>(into dir: P) throws -> Path where P : Pathish

Directory Listing


                    
                    
                    ls(_:)

Extension method

Same as the ls command ∴ output is ”shallow” and unsorted.

Note

as per ls, by default we do not return hidden files. Specify .a for hidden files.

Important

On Linux the listing is always ls -a

Declaration

Swift

func ls(_ options: ListDirectoryOptions? = nil) -> [Path]

Parameters


                                options

Configure the listing.

find() Extension method
Recursively find files under this path. If the path is a file, no files will be found.
Declaration
Swift

func find() -> Path.Finder

Filesystem Properties

exists Extension method
Note
If self is a symlink the return value represents the destination, thus if the destination doesn’t exist this returns false even if the symlink exists.

Note
To determine if a symlink exists, use .type.
Declaration
Swift

var exists: Bool { get }
Return Value

true if the path represents an actual filesystem entry.
isFile Extension method
Returns true if the path represents an actual filesystem entry that is not a directory.
Declaration
Swift

var isFile: Bool { get }
isDirectory Extension method
Returns true if the path represents an actual directory.
Declaration
Swift

var isDirectory: Bool { get }
isReadable Extension method
Returns true if the path represents an actual file that is also readable by the current user.
Declaration
Swift

var isReadable: Bool { get }
isWritable Extension method
Returns true if the path represents an actual file that is also writable by the current user.
Declaration
Swift

var isWritable: Bool { get }
isDeletable Extension method
Returns true if the path represents an actual file that is also deletable by the current user.
Declaration
Swift

var isDeletable: Bool { get }
isExecutable Extension method
Returns true if the path represents an actual file that is also executable by the current user.
Declaration
Swift

var isExecutable: Bool { get }
isSymlink Extension method
Returns true if the file is a symbolic-link (symlink).
Declaration
Swift

var isSymlink: Bool { get }

Filesystem Representation

url Extension method
Returns a URL representing this file path.
Declaration
Swift

var url: URL { get }
fileReferenceURL Extension method
Returns a file-reference URL.

Note
Only NSURL can be a file-reference-URL, hence we return NSURL.

See also
https://developer.apple.com/documentation/foundation/nsurl/1408631-filereferenceurl

Important
On Linux returns an file scheme NSURL for this path string.
Declaration
Swift

var fileReferenceURL: NSURL? { get }
parent Extension method
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.
Declaration
Swift

var parent: Path { get }
extension Extension method
Returns the filename extension of this path.

Remark
If there is no extension returns “”.

Remark
If the filename ends with any number of “.”, returns “”.

Note
We special case eg. foo.tar.gz—there are a limited number of these specializations, feel free to PR more.
Declaration
Swift

@inlinable var `extension`: String { get }
components Extension method
Splits the string representation on the directory separator.

Important
NSString.pathComponents will always return an initial / in its array for absolute paths to indicate that the path was absolute, we don’t do this because we are always absolute paths.
Declaration
Swift

@inlinable var components: [String] { get }


                    
                    
                    join(_:)

Extension method

Joins a path and a string to produce a new path.

Path.root.join("a")             // => /a
Path.root.join("a/b")           // => /a/b
Path.root.join("a").join("b")   // => /a/b
Path.root.join("a").join("/b")  // => /a/b

Note

.. and . components are interpreted.

Note

pathComponent may be multiple components.

Note

symlinks are not resolved.

See also

Path./(_:_:)

Declaration

Swift

func join<S>(_ addendum: S) -> Path where S : StringProtocol

Parameters


                                pathComponent

The string to join with this path.

Return Value

A new joined path.


                    
                    
                    /(_:_:)

Extension method

Joins a path and a string to produce a new path.

Path.root/"a"       // => /a
Path.root/"a/b"     // => /a/b
Path.root/"a"/"b"   // => /a/b
Path.root/"a"/"/b"  // => /a/b

Note

.. and . components are interpreted.

Note

pathComponent may be multiple components.

Note

symlinks are not resolved.

See also

join(_:)

Declaration

Swift

@inlinable
static func / <S>(lhs: Self, rhs: S) -> Path where S : StringProtocol

Parameters

`lhs`	The base path to join with `rhs`.
`rhs`	The string to join with this `lhs`.

Return Value

A new joined path.


                    
                    
                    relative(to:)

Extension method

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.

To do

Another variant that returns nil if result would start with ..

Declaration

Swift

func relative<P>(to base: P) -> String where P : Pathish

Parameters


                                base

The base to which we calculate the relative path.


                    
                    
                    basename(dropExtension:)

Extension method

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"

Declaration

Swift

func basename(dropExtension: Bool = false) -> String

Parameters


                                dropExtension

If true returns the basename without its file extension.

Return Value

A string that is the filename’s basename.

readlink() Extension method
If the path represents an actual entry that is a symlink, returns the symlink’s absolute destination.

Important
This is not exhaustive, the resulting path may still contain a symlink.

Important
The path will only be different if the last path component is a symlink, any symlinks in prior components are not resolved.

Note
If file exists but isn’t a symlink, returns self.

Note
If symlink destination does not exist, is not an error.
Declaration
Swift

func readlink() throws -> Path
realpath() Extension method
Recursively resolves symlinks in this path.
Declaration
Swift

func realpath() throws -> Path