In CLI2 every element of the command line interface is modelled as an Option instance, and has the following readonly properties that are inherited by all other Option implementations:
| Property | Type | Description |
|---|---|---|
| id | int |
Some people find it useful to give each option a unique identifer
so that they can use the options within a java switch
statement. This value is entirely optional and it is up to the
user to ensure any uniqueness.
|
| preferredName | String |
Every option has a preferred name that can be used for the minimal
toString() implementation. Options can usually have
many additional names too.
|
| required | boolean | True here indicates that the command line is invalid if this option doesn't appear on it. |
-a|-b|-c|-d|-e
Groups are possible the least intuitive form of Option since they actually represent a collection of other options. Most member Options can appear on a command line in any order with the exception of Arguments; they must appear in the given order as there is no other way to identify one from another. An additional restriction of the standard Group implementation is that only the final argument can have variable size (differing minimum and maximum).
Groups inherit all the properties of Options.
| Property | Type | Description |
|---|---|---|
| minimum | int | The minimum number of member options that must be present on the command line for this group to be valid. Typically this will either be 0 where the group is optional or 1 to indicate at least one of them is needed. This value does not count anonymous options. |
| maximum | int | The maximum number of options from this Group that can appear in a command line. This would typically be used if you wanted to create an exclusive group where a maximum of 1 member is allowed to appear. This value does not count anonymous options. |
<arg1> [<arg2> ...]
Arguments are used to pass in values from the command line, for example to pass in a list of files to be operated on. Arguments can appear in two different situations within an option model, the most frequently used situation is where the value found should be associated with a Parent option; in this situation the value is expected to immediately follow the Parent in the command line. The second scenario where Arguments are used is when they are added to a Group directly rather than being composed with a Parent first. These 'anonymous' arguments have nothing that identifies them on the command line other than the order in which they appear.
Multiple values may be parsed by a single argument and the minimum and maximum attributes can used to control their validity, additionally a Validator may be used to identify whether individual values are valid. In some situations it can be useful to parse the supplied string into multiple values and so the initialSeparator and subsequentSeparator attributes can be used; assuming an initialSeparator of '=' and a subsequentSeparator of ',', the string '--file=a,b,c' would be split into a parent option '--file', and the values 'a', 'b' and 'c'.
Arguments inherit all the properties of Options.
| Property | Type | Description |
|---|---|---|
| minimum | int | The minimum number of values that must be present for the Argument to be valid. The default of 0 implies that the argument is optional. |
| maximum | int | The maximum number of values that can appear in a valid command line. A value less than minimum is not allowed. |
| consumeRemaining | String | A string that can be used to avoid parsing of the remaining values as options. Typically '--' is used and allows file names to be used as values even though they look like options. |
| initialSeparator | char | A character used to indicate the end of the parent option and the beginning of the values. |
| subsequentSeparator | char | A character used to indicate the boundry between two values in a single string. |
| defaultValue | Object | A value to be used when no other is supplied. |
--parent <arg> --child1|--child2
Parent options allow an argument to be tied to some other option, additionally a group of child options can also be added to the parent. The argument and child options are only valid in the presence of the parent option, must appear on the command line with the child options following the argument.
Parents are not usable in themselves but DefaultOption, Switch and Command all inherit the parent features. Parents inherit the properties of Options.
| Property | Type | Description |
|---|---|---|
| argument | Argument | The Argument to delegate value processing to. This property is optional. |
| children | Group | The Group to delegate child processing to. This property is optional. |
--file (-f)
The default option allows an option to exist with both long and short
aliases. Ordinarily the short aliases would be a single character
long and allow a series of options -x -v -f to be
concatenated into a single element -xvf on the command
line. This bursting of concatenated options can be turned off if
necessary and the single character restriction can be ignored where
bursting is not required.
DefaultOptions inherit all the properties of Options and Parents.
| Property | Type | Description |
|---|---|---|
| shortName | String | The short name of the option. At least one short or long name is required. |
| longName | String | The long name of the option. At least one short or long name is required. |
| burstEnabled | boolean | Whether to allow this option to be concatenated with others. |
update (up,upd)
Commands are basically an option without an identifying prefix and are usually found in applications that implement a suite of tools within a single application. Any of a number of aliases can appear on the command line with idenentical meaning.
Commands inherit all the properties of Options and Parents.
+display|-display
Switches allow the user to turn a feature on or off. This becomes useful when the value would otherwise be taken from a different source and could change, for example the default value could be configurable by the user. A default switch value can be supplied in case no other source exists and the application writer has a preference.
Switches inherit all the properties of Options and Parents.
| Property | Type | Description |
|---|---|---|
| defaultSwitch | Boolean |
The value to be used if the option has not been configured. If
not set the value null is used.
|
-Dproperty=value
Property options allow arbitrary name value pairs to be passed in by
the user. This style of option is often used to emulate the java
-D option.
PropertyOptions inherit the properties of Options.
| Property | Type | Description |
|---|---|---|
| optionString | String |
The prefix for this option, defaults to -D.
|
<src1> [<src2> ...] <dest>
Groups have the restriction that only the final argument can have variable size. Using the SourceDestArgument this rule can appear to be relaxed by shifting the variable size argument to an earlier position. A SourceDestArgument is implemented by composing two other options together. This option would typically be used when modelling commands like the unix cp command,
| Property | Type | Description |
|---|---|---|
| source | Argument | The variable size first argument. |
| dest | Argument | The fixed size last argument. |