CLC Argument Configurations

Argument configurations define arguments for an application. That is, the strings that are left over once all command line arguments have been processed. Without defining any argument configurations, all arguments will be treated as strings and available in the API via the call to Clc.getInstance().getArgs() which returns List<String>. By defining argument configurations it is possible tto control the number and type (even preventing applications from having any arguments) of such configurations.

Like option configurations, argument configurations are defined blocks of CLC keys that are defined by the format args.<config-name>.<key> = <value>. Arguments must be defined in related blocks: Once an <config-name> has been defined and followed by a different <config-name>, the previous argument name cannot be defined later on in the configuration file.

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

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

Argument configurations can be used to hone and refine the arguments an application can receive. Like option configurations, argument configurations can be defined in any number of blocks of different configurations and can be assigned value types.

By default, if no length to an argument configuration is specified, any number of arguments of the specified type can be supplied, if it is the last argument configuration in a defined block of argument configurations; all preceeding argument configurations must have their length set. The term for such an argument configuration is unbounded in that it can contain any number of arguments of the specified type.

Likewise, argument configurations can be defined as optional, again only if it is the last argument configuration in a defined block of argument configurations

The last defined argument configuration can be both optional and unbounded, in which case either no arguments are expected to be supplied, or any number of arguments can be supplied.

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

Key Name Type Description
length int The number of arguments that this configuration will contain; if not defined, any number of arguments of the given type may be present and the argument configuration must be the last configuration in the block of argument configuration (or the first and only argument configuration). When length is set to zero it means no more argument configurations can be defined after the argument has been set to length zero. This is used to cap or limit the number of arguments an application can offer to callers.
optional boolean If the argument or arguments are optional. Defaults to false. If true, the argument configuration must be the last configuration in the block of argument configuration (or the first conifugration with no succeeding argument configurations). If optional is true then either none or up to the upper limit/length arguments are required be provided.
type string The value type to assign to the argument. When parsed, the string value of the option will be converted to the specified type. Defaults to string. Values types are documented below.
properties string If type is defined, the properties associated with that type, if required. Must be valid for the specified type.
argName string The argument name of the argument; defaults to arg.

A CLC file with no argument configurations, as stated previously, will be treated as an unbounded number of string values. This is the equivalent to setting the following:

args.string-vals.type = string
args.string-vals.optional = true

Since the argument configuration doesn't have a length set, this means there can be zero or more string values passed via the command line. optional means that 0 arguments can be supplied and no error will be thrown.

By constrast, the following configuration defines that at least one existing file (or more) is required for the command line arguments:

args.files.type = file
args.files.properties = fileType = exists

The missing optional value means that the configuration is not optional; this is the same as (explicitly) adding the following to the same configuration:

args.files.optional = false

It's different if the argument is bounded. The following example shows a fixed length argument configuration with length 3 and non-optional - in which case all 3 integers must be provided (no more, no less - it's fixed length):

args.int-vals.length = 3
args.int-vals.type = int
args.int-vals.optional = false

Argument configurations can be defined in blocks - the following example mimics the *nix command mknod that takes a file path, a character and two integers (minor and major) - all four arguments must be supplied since optional isn't defined (and the default is true):

args.file-path.length = 1
args.file-path.type = file
args.file-path.properties = fileType = !exists

args.device-type.length = 1
args.device-type.type = char
args.device-type.properties = includes = bcup, regex = false

args.major.length = 1
args.major.type = int
args.major.properties = min = 0

args.minor.length = 1
args.minor.type = int
args.minor.properties = min = 0

args.capped-at-zero.length = 0

The configuration specifies that the first argument must be a non-existing file; that the second argument can be a character consisting of any of the following values: b, c, u or p; and that the final two arguments must be integers that have a minimum value of zero. Finally, the definition of args.capped-at-zero.length being zero means that any extra arguments will cause an error.