CLC Commands

Commands allow extra functionality to an application by offering a unique set of commands that offer a different set of options/switches to the switches available via the top-level switches of an application. Commands when used on the command line are always entered immediately before any command line switches are entered, and are consumed by the API to determine what option and argument configurations are available to that command.

Commands can be nested such that command A has its own sub-commands B, C and D; to call command D, we would invoke the application with command A followed by command D, followed by any switches to the command.

An example with the above for an imagined application named foo-app calling commands A and D with some made up options, then we'd call:

foo-app A D --foo --bar

If global help has been defined, the help will also be applied to all commands; the API will print all options available when the help switch is applied to a given command. The API will use the command.usage value as the help header. Continuing the previous example, to get help for the D command we'd call:

foo-app A D --help

Commands must be defined after all top-level option configurations and (if defined) argument configurations. Commands are defined using the declaration:

command.name = <command-name>
command.usage = <command-usage>

<command-name> must begin with an alphabetic character and may contain any mix of characters, digits or hyphens.

Once a command has been defined, like top-level option definitions, may contain any number of contiguously defined option configurations, followed by any number of argument configurations. If no argument configurations are defined, all arguments will be treated as an unbounded number of strings.

To define a nested command, the command name must be defined with the full path to the command via its parent commands, separated by forward slashes. Commands must never contain a leading or traling slash. Nested commands must have been preceeded by any parent commands prior to defining a nested commmand.

For example to define a command A, which has nested commmand B, C and D, where command C has nested commands E, F and G, the configuration would look as folllows:


# global, top-level option and argument configurations omitted

command.name = A
command.usage = run command A

# ^ Command A option and argument configurations omitted
# A must be defined before B (same for siblings of B):

command.name = A/B
command.usage = run command B

# ^ Command B option and argument configurations omitted

command.name = A/C
command.usage = run command C

# ^ Command C option and argument configurations omitted
# C must be defined before E (same for siblings of E):

command.name = A/C/E
command.usage = run command E

# ^ Command E option and argument configurations omitted

command.name = A/C/F
command.usage = run command F

# ^ Command F option and argument configurations omitted

command.name = A/C/G
command.usage = run command G

# ^ Command G option and argument configurations omitted

command.name = A/D
command.usage = run command D

# ^ Command D option and argument configurations omitted