CLI

public enum CLI

Namespace for all commandline related functions and objects.

  • Prompt handler for print output and read input for command line. Initial CLI.prompt value is set to print to stdout and stderr, and read from stdin.

    Note

    Custom PromptHandler can be useful in tests.

    Declaration

    Swift

    public static var prompt: PromptHandler

  • Flag for globally enable or disable the StringStyle formatting. If set to false, string styles not be evaluated inside strings. Default is true.

    Declaration

    Swift

    public static var enableStringStyles: Bool
  • env

    Access to environment variables of current process.

    Declaration

    Swift

    public static var env: CLI.Environment

  • Access to parsed command line arguments for current process.

    Declaration

    Swift

    public static let args: CLI.Arguments

  • Holds global instance of ProcessBuilder that is used for create Process instances for Command execution. Default is CLI.Shell.zsh on macOS and CLI.Shell.bash on Linux.

    See also

    CLI.Shell

    Declaration

    Swift

    public static var processBuilder: ProcessBuilder

String Style

  • Available string styles.

    This styles can be used in string iterpolation:

    print("Result is \(result.exitCode, styled: .fgRed, .italic)")

    or can be used with any instances of StringProtocol:

    print("Init...".styled(.bgMagenta, .bold, .fgRed))

    Note

    Uses SGR parameters from ANSI escape codes
    See more

    Declaration

    Swift

    struct StringStyle

Print - Prompt Function

  • Print string to defined prompt (default is stdout). Printed string is not terminated by newline.

    See also

    CLI.prompt for set preferred PromptHandler.

    Declaration

    Swift

    @inlinable
static func print(_ string: String)

    Parameters

    string

    The text to print.

  • Print string with a new line terminator to defined prompt (default is stdout).

    See also

    CLI.prompt for set preferred PromptHandler.

    Declaration

    Swift

    @inlinable
static func println(_ string: String)

    Parameters

    string

    The text to print.

  • Print string to defined error prompt (default is stderr). Printed string is not terminated by newline.

    See also

    CLI.prompt for set preferred PromptHandler.

    Declaration

    Swift

    @inlinable
static func print(error string: String)

    Parameters

    string

    The error text to print.

  • Print string with a new line terminator to defined error prompt (default is stderr).

    See also

    CLI.prompt for set preferred PromptHandler.

    Declaration

    Swift

    @inlinable
static func println(error string: String)

    Parameters

    string

    The error text to print.

Ask - Prompt Function

  • Displays prompt to the user.

    Declaration

    Swift

    static func ask(_ prompt: String, options: AskOption<String>...) -> String

    Parameters

    prompt

    The message to display.
    options

    The prompt customization options.

    Return Value

    The string enters from the user.

  • Displays prompt to the user.

    If the user enters a string wich cannot be converted to the expected type, ask will keep prompting until a corect value has been entered.

    Declaration

    Swift

    static func ask<T>(_ prompt: String, type: T.Type = T.self, options: AskOption<T>...) -> T where T : ExpressibleByStringArgument

    Parameters

    prompt

    The message to display.
    type

    The value type to be expected from the user.
    options

    The prompt customization options.

    Return Value

    The converted string enters from the user.

  • Options for CLI.ask(_:options:) functions which can customize value handling and custom prompt validations.

    This options are passed to CLI.ask(_:options:) functions, for example:

    // Define a default value and require the entered value confirmation.
CLI.ask("Choose directory [/tmp]: ", options: .default("/tmp"), .confirm())

// Prints:
// $ Choose directory [/tmp]: <<user input>>
// $ Are you sure? <<y>>
// The result is "<<user input>>" or "/tmp" if the user only press Enter key.
    See more

    Declaration

    Swift

    enum AskOption<T> where T : ExpressibleByStringArgument

Choose - Prompt Function

  • Displays a menu of items to the user to choose from.

    Precondition

    The choices must be non empty array.

    Declaration

    Swift

    static func choose(_ prompt: String, choices: [String]) -> String

    Parameters

    prompt

    The message to display.
    choices

    The items to choose from.

    Return Value

    An one of the choices that the user choose.

  • Displays a menu of items to the user to choose from.

    Precondition

    The choices must be non empty dictionary.

    Declaration

    Swift

    static func choose<T>(_ prompt: String, choices: [String : T]) -> T

    Parameters

    prompt

    The message to display.
    choices

    The items to choose from. The choice key will be shown to the user (sorted) and dictionary value for that key will be returned from this function.

    Return Value

    A value of the one of choices that the user choose.

Run Commands

  • Run external command with defined executor.

    Precondition

    The command arguments is not empty.

    See also

    Command.execute()

    Declaration

    Swift

    @discardableResult
@inlinable
static func run(_ args: String..., executor: CommandExecutor = .default) throws -> String

    Parameters

    args

    The command with arguments to be executed.
    executor

    The command executor for execute defined command.

    Return Value

    A command result with exit status code and parsed stdout and stderr outputs.

  • The command which to be executed.

    This struct holds all settings for command execution and can be created througt CLI.run(_:_:executor:) functions or directly.

    CLI.run("echo -n", "Hi!")
// is equivalent to
Command(["echo", "-n", "Hi!"]).execute()

    Note

    Command is more complex than simple run function. You can specify command working directory or environment variables.
    See more

    Declaration

    Swift

    struct Command : CustomStringConvertible

  • Types of supported command executors.

    See more

    Declaration

    Swift

    enum CommandExecutor

  • Basic implementation of ProcessBuilder, used to execute common shells.

    See more

    Declaration

    Swift

    struct Shell : ProcessBuilder

  • The error type that are used if command not executed correctly.

    See more

    Declaration

    Swift

    struct CommandExecutionError : Error

Environment Variables

  • A type for handle environment variables.

    See more

    Declaration

    Swift

    struct Environment

Script Argument Parser

  • A type that handles the command line arguments passed to the script.

    Note

    The arguments will be parsed only if you access to any attribute that require arguments parsing, which is the attributes command, flags and parameters. The arguments are parsed only once.
    See more

    Declaration

    Swift

    class Arguments