Command

public protocol Command : AnyObject

Represents a description of a command that can be executed any number of times, but usually just once.


                    
                    
                    coreAsync(fdMap:)

The minimum requirement of a Command is that it can launch itself asynchronously

Declaration

Swift

func coreAsync(fdMap: FDMap) -> CommandResult

Parameters


                                fdMap

A map from child FDs to parent FDs

Return Value

a result capable of monitoring the asynchronous command

Running

run() Extension method
Run the command asynchronously, and return nothing if successful

Throws
if command fails
Declaration
Swift

@available(macOS 10.15, *) public func run() async throws
runBool() Extension method
Run the command asynchronously, and return true if the command exited zero
Declaration
Swift

@available(macOS 10.15, *) public func runBool() async -> Bool
runFile() Extension method
Run the command synchronously, directing the output to a temporary file

Throws
if command fails
Declaration
Swift

@available(macOS 10.15, *) public func runFile() async throws -> URL
Return Value

URL of temporary file with output of command
runData() Extension method
Run the command synchronously, and collect stdout. does not trim newlines (unlike $(…))

Throws
if command fails
Declaration
Swift

@available(macOS 10.15, *) public func runData() async throws -> Data
Return Value

output as Data


                    
                    
                    runString(encoding:)

Extension method

Run the command asynchronously, and collect stdout into a string. Trims trailing newlines (like $(…))

Throws

if command fails

Throws

InvalidString if the output isn’t valid

Declaration

Swift

@available(macOS 10.15, *)
public func runString(encoding: String.Encoding = .utf8) async throws -> String

Parameters


                                encoding

the encoding of the output data

Return Value

output as unicode string

runLines(encoding:) Extension method
Run the command asynchronously, and collect output line-by-line as a list of strings

Throws
if command fails
Declaration
Swift

@available(macOS 10.15, *) public func runLines(encoding: String.Encoding = .utf8) async throws -> [String]
runJSON(options:) Extension method
Run the command asynchronously, and collect output as a parsed JSON object

Throws
if command fails

Throws
if the output isn’t JSON
Declaration
Swift

@available(macOS 10.15, *) public func runJSON(options: JSONSerialization.ReadingOptions = .allowFragments) async throws -> Any
runJSON(_:decoder:) Extension method
Run the command asynchronously, and collect output as a parsed JSON object

Throws
if command fails

Throws
if parsing fails
Declaration
Swift

@available(macOS 10.15, *) public func runJSON<D>(_ type: D.Type, decoder: JSONDecoder? = nil) async throws -> D where D : Decodable


                    
                    
                    async(fdMap:)

Extension method

Run the command asynchronously, inheriting or overwriting the standard file descriptors

Declaration

Swift

public func async(fdMap: FDMap = [:]) -> CommandResult

Parameters


                                fdMap

A map from child FDs to parent FDs, will be composed with standard map

Return Value

a result capable of monitoring the asynchronous command


                    
                    
                    async(stdin:stdout:stderr:)

Extension method

Run the command asynchronously, inheriting or overwriting the standard file descriptors

Declaration

Swift

public func async(
    stdin: FileDescriptor = .stdin,
    stdout: FileDescriptor = .stdout,
    stderr: FileDescriptor = .stderr
) -> CommandResult

asyncStream() Extension method
Run the command asynchronously, and return a stream open on process’s stdout
Declaration
Swift

public func asyncStream() -> FileHandle
run() Extension method
Run the command synchronously, and return nothing if successful

Throws
if command fails
Declaration
Swift

public func run() throws
runBool() Extension method
Run the command synchronously, and return true if the command exited zero
Declaration
Swift

public func runBool() -> Bool
runFile() Extension method
Run the command synchronously, directing the output to a temporary file

Throws
if command fails
Declaration
Swift

public func runFile() throws -> URL
Return Value

URL of temporary file with output of command
runData() Extension method
Run the command synchronously, and collect stdout. does not trim newlines (unlike $(…))

Throws
if command fails
Declaration
Swift

public func runData() throws -> Data
Return Value

output as Data


                    
                    
                    runString(encoding:)

Extension method

Run the command synchronously, and collect stdout into a string. Trims trailing newlines (like $(…))

Throws

if command fails

Throws

InvalidString if the output isn’t valid

Declaration

Swift

public func runString(encoding: String.Encoding = .utf8) throws -> String

Parameters


                                encoding

the encoding of the output data

Return Value

output as unicode string

runLines(encoding:) Extension method
Run the command synchronously, and collect output line-by-line as a list of strings

Throws
if command fails
Declaration
Swift

public func runLines(encoding: String.Encoding = .utf8) throws -> [String]
runJSON(options:) Extension method
Run the command synchronously, and collect output as a parsed JSON object

Throws
if command fails

Throws
if the output isn’t JSON
Declaration
Swift

public func runJSON(options: JSONSerialization.ReadingOptions = .allowFragments) throws -> Any
runJSON(_:decoder:) Extension method
Run the command synchronously, and collect output as a parsed JSON object

Throws
if command fails

Throws
if parsing fails
Declaration
Swift

public func runJSON<D>(_ type: D.Type, decoder: JSONDecoder? = nil) throws -> D where D : Decodable

Output redirection


                    
                    
                    output(creatingFile:fd:)

Extension method

Bind output to a file. Similar to “>” in bash, but will not overwrite the file

Declaration

Swift

public func output(creatingFile path: String, fd: FileDescriptor = .stdout) -> Command

Parameters

`path`	Path to write output to
`fd`	File descriptor to bind. Defaults to stdout


                    
                    
                    output(overwritingFile:fd:)

Extension method

Bind output to a file, creating if needed. Similar to “>” in bash

Declaration

Swift

public func output(overwritingFile path: String, fd: FileDescriptor = .stdout) -> Command

Parameters

`path`	Path to write output to
`fd`	File descriptor to bind. Defaults to stdout


                    
                    
                    append(toFile:fd:createFile:)

Extension method

Bind output to end of a file. Similar to “>>” in bash

Throws

FileDoesntExist if createFile is false, and the file doesn’t exist

Declaration

Swift

public func append(toFile path: String, fd: FileDescriptor = .stdout, createFile: Bool = true) -> Command

Parameters

`path`	Path to write output to
`fd`	File descriptor to bind. Defaults to stdout
`createFile`	fail if the file doesn’t exist


                    
                    
                    duplicateFd(source:destination:)

Extension method

Duplicate a file handle. In bash, this is expressed like “2>&1”. See also dup2(2)

Declaration

Swift

public func duplicateFd(source srcFd: FileDescriptor, destination dstFd: FileDescriptor) -> Command

Parameters

`srcFd`	File descriptor to duplicate
`dstFd`	Descriptor of new, duplicated handle

combineError Extension method
Redirect standard error to standard output. “2>&1” in bash
Declaration
Swift

public var combineError: Command { get }

Input


                    
                    
                    input(_:encoding:fd:)

Extension method

Bind stdin to contents of string

Throws

Declaration

Swift

public func input(
    _ string: String,
    encoding: String.Encoding = .utf8,
    fd: FileDescriptor = .stdin
) throws -> Command

Parameters

`encoding`	how encoding the outgoing data
`fd`	File descriptor to bind. Defaults to stdin


                    
                    
                    input(_:fd:)

Extension method

Bind stdin to contents of data

Declaration

Swift

public func input(_ data: Data, fd: FileDescriptor = .stdin) -> Command

Parameters

`fd`	File descriptor to bind. Defaults to stdin


                    
                    
                    input(withJSONObject:fd:options:)

Extension method

Bind stdin to the the JSON representation of a JSON-like value

Throws

if encoding fails

Declaration

Swift

public func input(
    withJSONObject json: Any,
    fd: FileDescriptor = .stdin,
    options: JSONSerialization.WritingOptions = .init()
) throws -> Command

Parameters

`json`	Anything `JSONSerialization` can deal with
`fd`	File descriptor to bind. Defaults to stdin


                    
                    
                    inputJSON(from:fd:encoder:)

Extension method

Bind stdin to the the JSON representation of a JSON-encodable value

Throws

if encoding fails

Declaration

Swift

public func inputJSON<E: Encodable>(
    from object: E,
    fd: FileDescriptor = .stdin,
    encoder: JSONEncoder = .init()
) throws -> Command

Parameters

`object`	The object to be encoded and sent
`fd`	File descriptor to bind. Defaults to stdin
`encoder`	JSONEncoder to use


                    
                    
                    input(fromFile:fd:)

Extension method

Bind stdin to a file, similar to < file in bash

Declaration

Swift

public func input(fromFile path: String, fd: FileDescriptor = .stdin) -> Command

Parameters

`fd`	File descriptor to bind. Defaults to stdin