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
  • Gets the subcommand with a name

    Declaration

    Swift

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

    Parameters

    name

    the command name to get

    Return Value

    return a command if found

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

    Declaration

    Swift

    public var shortMessage: String?
  • The long usages string This string will be visible when the help of the command is executed

    Declaration

    Swift

    public var longMessage: String?
  • The example section of the command This will be visible when displaying the command help

    Declaration

    Swift

    public var example: String?
  • The command deprecation status. This defines if a command is deprecated or not, default not deprecated

    Declaration

    Swift

    public var deprecationStatus = DeprecationStatus.notDeprecated
  • The flags available for this command This list contains only the local flags added to the command

    Declaration

    Swift

    public var flags: [Flag] = []
  • The subcommands this command has

    Declaration

    Swift

    public var commands: [Command] = []
  • The parent of this command. If the command is the root command, the parent will be nil.

    Declaration

    Swift

    public var parent: Command?
  • 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?
  • 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?
  • 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?
  • 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?
  • 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?
  • 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] = []
  • Get the help message for the command The console help message for the command

    Declaration

    Swift

    public var helpMessage: String
  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • Execute a command passing all the command line arguments received

    Declaration

    Swift

    public func execute()
  • 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

  • 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

  • Validate a Command it flags and subcommands

    Throws

    error if command, subcommands or flags are not valid

    Declaration

    Swift

    public func validate() throws