Path

public struct Path

A Path represents an absolute path on a filesystem.

All functions on Path are chainable to facilitate doing sequences of file operations.

Note

A Path does not necessarily represent an actual filesystem entry.
  • url

    The URL representation of the underlaying filesystem path.

    Declaration

    Swift

    public let url: URL

  • The normalized string representation of the underlying filesystem path.

    Declaration

    Swift

    public var path: String { get }

  • Creates a new absolute, standardized path from the provided file-scheme URL.

    Throws

    Path.Error.invalidURLScheme if URL scheme is not file.

    Declaration

    Swift

    public init(url: URL) throws

    Parameters

    url

    The path URL.

  • Creates a new absolute, standardized path.

    Throws

    Path.Error.cannotResolvePath if path cannot be resolved.

    Note

    • Resolves any .. or . components in path.
    • Resolves initial ~/ with path to current user home directory.
    • Resolves initial ~user/ with path to specified user home directory.
    • Does not resolve any symlinks.
    • If provided path is relative (not prefixed with /) then the resolved path is relative to the current working directory.
    • 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.

    Declaration

    Swift

    public init<S>(_ path: S) throws where S : StringProtocol

    Parameters

    path

    The string represented an absolute path

  • Creates a new absolute, standardized path which is constructed from path which is relative to parent path.

    Declaration

    Swift

    @inlinable
public init<S>(_ path: S, relativeTo parent: Path) where S : StringProtocol

    Parameters

    path

    A string which represends the relative part of the path.
    parent

    The parent of the target path.

Common Paths

  • The Path to the root directory.

    Declaration

    Swift

    static let root: Path

  • The Path to the current working directory.

    Declaration

    Swift

    static var current: Path { get }

  • The current user’s home

    Declaration

    Swift

    static var home: Path { get }

  • The system’s temporary directory.

    Declaration

    Swift

    static var temporary: Path { get }

  • Creates a new temporary directory, runs work closure and delete it at end.

    Declaration

    Swift

    static func temporary<T>(_ work: (Path) throws -> T) throws -> T

    Parameters

    work

    The closure with some logic related to the new tmp directory. The temporary directory is passed as an agument to this closure. Returned value from closure will be returned to the caller.

    Return Value

    The value returned from the work closure.

Filesystem Representation

  • The parent directory for this path.

    Note

    Always returns a valid path, Path.root.parent is Path.root.

    Declaration

    Swift

    var parent: Path { get }

  • A sequence containing all of this folder’s filesystem items. Initially non-recursive and skip hidden items, use recursive or includingHidden on the returned sequence to change that.

    Declaration

    Swift

    var children: ChildSequence { get }

  • The path components, or an empty array for root path.

    Declaration

    Swift

    var pathComponents: [String] { get }

  • The basename for this filesystem item including extension.

    Declaration

    Swift

    @inlinable
var basename: String { get }

  • Returns the filename extension of this path.

    Note

    • If there is no extension returns empty string.
    • If the filename ends with any number of ., returns empty string.

    Declaration

    Swift

    var `extension`: String { get }

  • The basename for this filesystem item without file extension.

    Declaration

    Swift

    var basenameWithoutExtension: String { get }

  • Returns a string representing the relative path to base. If base is not a logical prefix for self your result will be prefixed some number of ../ components.

    Declaration

    Swift

    func path(relativeTo base: Path) -> String

    Parameters

    base

    The base to which we calculate the relative path.

    Return Value

    The relative path to base.

  • Returns a new path made by appending a given path string.

    Note

    .. and . components are interpreted.

    Declaration

    Swift

    func appending<S>(_ path: S?) -> Path where S : StringProtocol

    Parameters

    path

    The path to append to this path

    Return Value

    A new path made by appending path to the receiver.

  • Create a new path by appending the append string to the specified path.

    Note

    .. and . components are interpreted.

    See also

    appending(_:)

    Declaration

    Swift

    static func + <S>(path: Path, append: S?) -> Path where S : StringProtocol

    Parameters

    path

    The base path for the new one.
    append

    The string path to join with specified path.

    Return Value

    A new joined path.

Filesystem Attributes

  • A type of a filesystem entry at this path. An .unknown value is returned if the entry doesn’t exist or the type cannot be determined.

    Declaration

    Swift

    var type: EntryType { get }

  • An attributes of a filesystem entry, or nil if entry not exist.

    Declaration

    Swift

    var attributes: Attributes? { get }

Input/Output Operations

  • Writes the text to file on this path.

    Declaration

    Swift

    @discardableResult
func write(text: String, append: Bool = false, encoding targetEncoding: String.Encoding = .utf8) throws -> Path

    Parameters

    text

    The string content to write.
    append

    Appends the string to the end of file.
    targetEncoding

    The encoding in which the string should be interpreted.

    Return Value

    Self to allow chaining.

  • Writes the data to file on this path.

    Declaration

    Swift

    @discardableResult
func write(data: Data, append: Bool = false) throws -> Path

    Parameters

    data

    The data content to write.
    append

    Appends the data to the end of file.

    Return Value

    Self to allow chaining.

File Management

  • Returns a Boolean value that indicates whether this path represents an actual filesystem entry. A false was returned if the entry does not exist or its existence could not be determined.

    Declaration

    Swift

    var exist: Bool { get }

  • Copies this filesystem item to the another destination. If the destination path is directory then the current item will be placed to that directory (destination/self.basename).

    Throws

    An error if file cannot be copied.

    Declaration

    Swift

    @discardableResult
func copy(to destination: Path, overwrite: Bool = false) throws -> Path

    Parameters

    destination

    The new location for item on this path.
    overwrite

    If true overwrites file on destination location.

    Return Value

    A Path to copied item location.

  • Moves this filesystem item to the another destination. If the destination path is directory then the current item will be moved into that directory (destination/self.basename).

    Throws

    An error if file cannot be moved.

    Declaration

    Swift

    @discardableResult
func move(to destination: Path, overwrite: Bool = false) throws -> Path

    Parameters

    destination

    The new location for this item.
    overwrite

    If true overwrites file on destination location.

    Return Value

    A Path to moved item.

  • Creates an empty file at this path or if the file exists, updates its modification time.

    Note

    If name is path and directories in this path not exists then throws error.

    Throws

    An error if file cannot be created or modification time cannot be change.

    Declaration

    Swift

    @discardableResult
func touch(_ name: String? = nil) throws -> Path

    Parameters

    name

    The name of the new file. If name not provided or nil then file will be created at self.path. If name is specified then new file path will be self.path.appending(name).

    Return Value

    A Path to the new file.

  • Creates a directory at this path or at new appended path if the name was supplied.

    Throws

    An error if directory cannot be created.

    Declaration

    Swift

    @discardableResult
func createDirectory(_ name: String? = nil) throws -> Path

    Parameters

    name

    The name of the new directory or nil if you want use this path. This name can be used to create intermediary directories.

    Return Value

    A Path to the new directory.

  • Deletes the path, recursively if a directory.

    If path doesn’t exist do nothing. If entry is a symlink, deletes the symlink.

    Declaration

    Swift

    func delete(useTrash: Bool = false) throws

    Parameters

    useTrash

    Move the path to the trash insted of delete.

  • Renames the filesystem item at this path.

    Throws

    Error.invalidArgumentValue if new name contain directory separator.

    Declaration

    Swift

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

    Parameters

    name

    The new name of this item.

    Return Value

    A Path to the renamed item.

String Convertible and Expressible

  • Returns Path.string

    Declaration

    Swift

    @inlinable
public var description: String { get }

String Convertible and Expressible

  • Creates an instance initialized to the given string value.

    Do not call this initializer directly. It is used by the CLI.ask(_:options:) and CLI.choose(_:chices:) functions.

    Declaration

    Swift

    @inlinable
public init?(stringArgument: String)

Equatable, Hashable, etc.

  • Declaration

    Swift

    @inlinable
public static func == (lhs: Path, rhs: Path) -> Bool

  • Declaration

    Swift

    public func hash(into hasher: inout Hasher)

  • Declaration

    Swift

    public static func < (lhs: Path, rhs: Path) -> Bool

Equatable, Hashable, etc.

  • Creates a new instance of path by decoding from the given decoder.

    Declaration

    Swift

    public init(from decoder: Decoder) throws

    Parameters

    decoder

    The decoder to read data from.

  • Encodes this path into the given encoder.

    Declaration

    Swift

    public func encode(to encoder: Encoder) throws

    Parameters

    encoder

    The encoder to write data to.

Supporting Objects

  • Filesystem entry attributes representation.

    See more

    Declaration

    Swift

    struct Attributes

  • A sequence of child locations contained within a given folder. You obtain an instance of this type by accessing children on Path instance.

    See more

    Declaration

    Swift

    struct ChildSequence : Sequence

  • The type of iterator used byt Path.ChildSequence. Don’t interact with this type directly. See Path.ChildSequence for more information.

    See more

    Declaration

    Swift

    struct ChildSequenceIterator : IteratorProtocol

  • A type of filesystem entry.

    See more

    Declaration

    Swift

    enum EntryType : CaseIterable

  • An error that occurs during initialize and operations with Path instances.

    See more

    Declaration

    Swift

    enum Error : Swift.Error

  • A filesystem entry permission representation.

    See more

    Declaration

    Swift

    struct Permissions : Equatable, OptionSet, CustomStringConvertible