CLC Option Configurations

Command line option configurations are defined blocks of CLC keys that are defined by the format option.<config-name>.<key> = <value> and used to define unary and binary command line switches. Options must be defined in contiguous blocks: Once an <config-name> has been defined and followed by a different <config-name>, the previous option configuration name cannot be defined later on in the configuration file (unless it's inside a command definition as commands can have the same option and argument names as top-level options and arguments).

<config-name> must contain at least one alphanumeric character, underscore or hyphen, followed by any amount of the same

Option configurations can either be a unary switch that does not take any arguments, or a binary switch that takes an argument. This is controlled by the hasArg option key.

Option configurations can also be applied to commands such that each defined command can contain its own option configurations. In this case, option names can be reused and have the same config-name as previously defined option configurations since options are specific to the section they are defined in. Thus, for example, if a top-level option configuraiton has been defined and named get-current-info, then the same option configuration can also be applied to a named command, since the command is segregated from the top-level option configurations. Commands are discussed below.

First let's take a look at the different keys that are available for option configurations, and then look at some examples.

The following keys are supported:

Key Name Required Type Description
opts Y string Either a single character, a long string or a character separated by a forward slash followed by a long option. Both forms must not be prefixed by hyphens (this is dealt with by the API).
description Y string Description of the option. Used when printing help.
hasArg N boolean Determines if the option has an argument. Defaults to false. Switches that are defined as having no arguments are unary command line switches. By constrast if a switch does have an argument then it will be a binary switch defined with a value assigned to the switch. If the option is a unary switch, of the following properties, only ignoreCliArgs may be used. The standard is to treat all unary switches that are not supplied on the command line as false and when the switch is applied to set the value to true.
ignoreCliArgs N boolean If set to true, do not parse arguments. Parsing of arguments is mandatory if any argument configurations are defined. This enables switches like --help to bypass parsing of argument coniguration. If a command line switch does not need to process any arguments, ensure this value is true.
argName N string The name of the argument for a binary switch (not used for unary switches); if not set, defaults to <arg>. This is the argument name displayed when invoking help.
type N string The value type to assign to the option. When parsed, the string value of the option will be converted to the specified type. Defaults to string. Values types are documented below.
properties N string If type is defined, the properties associated with that type. Must be valid for the specified type.
default N string Default value of the option; must conform to the specified type (if specified). All default options will be fired by the API to listeners prior to parsing of CLI options. Thus, if a command line option is supplied, listeners will receive two updates - one for the defined default value, then a second for the overridden command line option value. Otherwise (when present) listeners will receive just the default value.

If global.options.opts-type is not set then the first encountered option will use opts value to determine if short, long or both option types are supported. If this is the case then all succeeding options must match the first option format.

For example, if global.options.opts-type is not defined and the first defined option has an entry as follows which shows a short and long option named e and show-examples (respectively) being defined:

option.examples.opts = e/show-examples

… Then all subsequent defined options must also be short and long options. Likewise, if the first option is a single character then all following options must also be single characters (i.e. short options), and if the first option is more than one character then all following options will be considered long options.

The minimum keys required for an option configuration are opts and description; this will create a unary switch, for example:

option.verbose-logging.opts = v/verbose
option.verbose-logging.description = Log verbose message.

This creates a unary switch that has a short and long option (-v and --verbose, respectively) with a description that will be printed on invoking help.

Switch hasArg isn't required, and defaults to false, but if not set (or set to false) then argName, type, properties and default cannot be set, though ignoreCliArgs can be used for unary switches.

To create a binary switch, opts and description must be set and hasArg must be true.

For example,

option.time-to-live.opts = ttl
option.time-to-live.description = "Time to live. Must be greater than zero."
option.time-to-live.hasArg = true

The above option definition will create a long option (--ttl) with a help description that when help is invoked will contain the text

--ttl <arg>         Time to live. Must be greater than zero.

When a defined option listener receives the value the value will be a string.

Let's update the same definition and make the option an int, give it a minimum value using properties, a default value of 42 and change the argName and description:

option.time-to-live.opts = ttl
option.time-to-live.description = "Time to live. Must be greater than zero. Defaults to 42"
option.time-to-live.hasArg = true
option.time-to-live.argName = seconds
option.time-to-live.type = int
option.time-to-live.properties = min = 1
option.time-to-live.default = 42

The help output for this option will now be

--ttl <seconds>         Time to live. Must be greater than zero. Defaults to 42

… And when received by a listener the value will be an integer. If a user enters a value less than 1 an error will be created.

Option key ignoreCliArgs has a special purpose - it's entirely possible for an application to define an argument configuration (see next section) where arguments are mandatory. For example an application may determine that exactly 2, and only 2 arguments are required. ignoreCliArgs on an option will prevent parsing of arguments that would normally cause an error if arguments are not supplied. Classic command line switches like the ubiquitous help and version options are examples where this could be used - it signals to the API that the arguments aren't important for such switches and prevents an error being thrown.