Command

public class Command

Command class representing a Command that can be executed.

Examples:

Create a simple command

var newCommand = Command(usage: "new") { flags, args in

}

Create a command with costumizations

var newCommand = Command(usage: "new",
                         shortMessage: "Use new to generate a new thing",
                         longMessage: "Long description",
                         example: "Example",
                         aliases: ["create", "generate"]) { flags, args in

}

Create a command with configuration block and an execute block

var rootCommand = Command(
  usage: "test", configuration: configuration, run: execute)


private func configuration(command: Command) {

  command.add(flags: [
    // Add your flags here
    ]
  )

  // Other configurations
}

private func execute(flags: Flags, args: [String]) {
  // Execute code here
  print("test called")
}

After creating a command, to execute it do:

let command = ...
command.execute()

  • The command uasage oneliner string. This is printed in the usage section. The usage must contain the command name as its first word

    Correct usages strings:

    • login [name]
    • login [flags] name

    Declaration

    Swift

    public var usage: String
    Show on GitHub

  • The short usages string This string will be visible when the help of the command is executed

    Declaration

    Swift

    public var shortMessage: String?
    Show on GitHub

  • The long usages string This string will be visible when the help of the command is executed

    Declaration

    Swift

    public var longMessage: String?
    Show on GitHub

  • The example section of the command This will be visible when displaying the command help

    Declaration

    Swift

    public var example: String?
    Show on GitHub

  • The command deprecation status. This defines if a command is deprecated or not, default not deprecated

    Declaration

    Swift

    public var deprecationStatus: DeprecationStatus
    Show on GitHub

  • The flags available for this command This list contains only the local flags added to the command

    Declaration

    Swift

    public var flags: [Flag]
    Show on GitHub

  • The subcommands this command has

    Declaration

    Swift

    public var commands: [Command]
    Show on GitHub

  • The parent of this command. If the command is the root command, the parent will be nil.

    Declaration

    Swift

    public var parent: Command? { get set }
    Show on GitHub

  • After the parsing matches the subcommand, preRun is executed before exacuting run If preRun returns true, the run is executed next If preRun returns false, the execution ends

    Declaration

    Swift

    public var preRun: ConditionalRun?
    Show on GitHub

  • After the parsing matches the subcommand, preRun is executed before exacuting run If preRun returns true, run is executed next If preRun returns false, the execution ends If the current command has an inheritablePostRun, then its called on it. Otherwise it will be executed on its parent, until the root command

    Declaration

    Swift

    public var inheritablePreRun: ConditionalRun?
    Show on GitHub
  • run

    After the parsing matches the subcommand, run is called after preRun the callback registered for preRun must return true for run to be called

    Declaration

    Swift

    public var run: Run?
    Show on GitHub

  • After the parsing matches the subcommand, postRun is called after run If postRun returns true, then inheritablePostRun is executed next If postRun returns false, the execution ends

    Declaration

    Swift

    public var postRun: ConditionalRun?
    Show on GitHub

  • After the parsing matches the subcommand, postRun is called after run If the current command has an inheritablePostRun, then its called on it. Otherwise it will be executed on its parent, until the root command

    Declaration

    Swift

    public var inheritablePostRun: ConditionalRun?
    Show on GitHub

  • The command aliases The command will be callable by its name or by any of the aliases set here

    Declaration

    Swift

    public var aliases: [String]
    Show on GitHub

  • Get the help message for the command The console help message for the command

    Declaration

    Swift

    public var helpMessage: String { get }
    Show on GitHub

  • Initialize a command

    Throws

    exception if the usage is incorrect (empty, or has wrong command name format)

    Discussion:

    The command usage must be a string that contains the command name as the first word.

    Some correct usages strings:

    • login [name]
    • login [flags] name

    The first word of the usage will be the command name

    Declaration

    Swift

    public init(usage: String,
            shortMessage: String? = nil,
            longMessage: String? = nil,
            flags: [Flag] = [],
            example: String? = nil,
            parent: Command? = nil,
            aliases: [String] = [],
            deprecationStatus: DeprecationStatus = .notDeprecated,
            run: Run? = nil)

    Parameters

    usage

    Command usage oneliner
    shortMessage

    (Optional)Short usage string. Defaults to nil
    longMessage

    (Optional)Long usage string. Defaults to nil
    flags

    (Optional)Command list of flags. Defaults to emoty array
    example

    (Optional)Example show when printing the help message. Defaults to nil
    parent

    (Optional)The command parent. Defaults to nil
    aliases

    (Optional)List of command aliases. Defaults to empty array
    deprecationStatus

    (Optional)Command deprecation status. . Defaults to .notDeprecated
    run

    (Optional)Callback called when the command is executed. Defaults to nil
    Show on GitHub

  • Initialize a command

    Throws

    exception if the usage is incorrect (empty, or has wrong command name format)

    Discussion: The command usage must be a string that contains the command name as the first word.

    Some correct usages strings:

    • login [name]
    • login [flags] name

    The first word of the usage will be the command name

    Declaration

    Swift

    public convenience init(usage: String,
                        configuration: Configuration?,
                        run: Run?)

    Parameters

    usage

    Command usage oneliner
    configuration

    Confuguration block to configure the command
    run

    Callback called when the command is executed
    Show on GitHub

  • Gets the subcommand with a name

    Declaration

    Swift

    public subscript(withName name: String) -> Command? { get }

    Parameters

    name

    the command name to get

    Return Value

    return a command if found

    Show on GitHub

  • Adds a new subcommand

    Examples:

    let command = ...
let subcommand = ...
command.add(subCommand: subCommand)

    Declaration

    Swift

    public func add(subCommand command: Command, setParent: Bool = true)

    Parameters

    command

    the command to add
    setParent

    set self as parent of the passed command
    Show on GitHub

  • Add a list of commands

    Examples:

    let command = ...
let subcommand1 = ...
let subcommand2 = ...
command.add(subCommands: [subCommand1, subCommand2])

    Declaration

    Swift

    public func add(subCommands commands: [Command])

    Parameters

    commands

    the commands to add
    Show on GitHub

  • Remove a command

    Declaration

    Swift

    public func removeCommand(passingTest test: (Command) -> Bool)

    Parameters

    test

    the test to run agains the command Returning true from this callback deletes the command
    Show on GitHub

  • Adds a flag

    Examples:

    let command = ...
let flag = ...
command.add(flag: flag)

    Declaration

    Swift

    public func add(flag: Flag)

    Parameters

    flag

    the flag to add
    Show on GitHub

  • Adds a list of flag

    Examples:

    let command = ...
let flag1 = ...
let flag2 = ...
command.add(flags: [flag1, flag2])

    Declaration

    Swift

    public func add(flags: [Flag])

    Parameters

    flag

    the flags to add
    Show on GitHub

  • Remove a command

    Declaration

    Swift

    public func removeFlag(passingTest test: (Flag) -> Bool)

    Parameters

    test

    the test to run agains the flag Returning true from this callback deletes the flag
    Show on GitHub

  • Fail, print the help message and exit the application Call this method when you want to exit and print the help message

    Declaration

    Swift

    public func fail(statusCode: Int, errorMessage: String? = nil) -> Never

    Parameters

    statusCode

    the status code to report
    errorMessage

    additinal error message to print
    Show on GitHub

Execution

  • Execute a command passing all the command line arguments received

    Declaration

    Swift

    public func execute()
    Show on GitHub

  • Executes a command with a list of arguments

    Example:

    rootCommand.execute(commandLineArgs: CommandLine.arguments)

    Declaration

    Swift

    public func execute(commandLineArgs: [String])

    Parameters

    commandLineArgs

    the arguments passed to the executable The arguments include the name of the exacutable as the first input
    Show on GitHub

  • Get the actual command to execute based on the current command and the arguments passed

    Example:

    let command = rootCommand.commandToExecute(commandLineArgs: CommandLine.arguments)

    Declaration

    Swift

    public func commandToExecute(commandLineArgs: [String]) -> Command

    Parameters

    commandLineArgs

    the command line arguments passed The arguments include the name of the exacutable as the first input

    Return Value

    the actual command to execute

    Show on GitHub

  • Validate a Command it flags and subcommands

    Throws

    error if command, subcommands or flags are not valid

    Declaration

    Swift

    public func validate() throws
    Show on GitHub