Add multiplicity attribute to @Option

[remkop]

During analysis on #815, the idea came up to introduce multiplicity on @Option and @Parameters.

Multiplicity would allow applications to control exactly what number of values (minimum and maximum) is valid for a multi-value option or positional parameter. Currently there is no way to control the max number of values captured.

Example

// this guarantees that the x array will have at least 1 and at most 3 values
@Option(names = "-x", multiplicity = "1..3")
int[] x;

Multiplicity vs arity

The difference with arity is that multiplicity specifies the total number of values (min..max count range) that may be captured in the container (List, Map, array), while arity specifies the number of arguments that may be specified for each occurrence of the option on the command line.

Multiplicity and the split regex

Introducing multiplicity would also solve an outstanding issue with options that have a split regex: there currently no way to restrict the max number of values added to an option that has a split regex. Even if arity=1, user input of -x=1,2,3 is valid. With multiplicity=1, the same input would cause a MaxValuesExceededException.

Argument Groups

The @ArgGroup matching logic would need to be updated for groups that contain options with an explicit multiplicity. A new GroupMatch would then be created if the max multiplicity of a multi-value option was reached. (There would be no need for a parser configuration option greedyMatchMultiValueArgsInGroup, see #815)

Positional Parameters

Perhaps arity should be deprecated for @Parameters and applications should use multiplicity instead. That would make max count checking consistent across options and positional params.

multiplicity for single-value options and positional parameters: TBD

Does multiplicity make sense for single-value options (and for positional parameters that capture one value at a specific index)?

Default multiplicity

The default multiplicity of a multi-value option or positional parameter would be 0..*.

The default multiplicity of a single-value could be 1 for required options and 0 for non-required options.

TBD if a single-value option is defined as arity = "0..1", what is its default/implied multiplicity?

Multiplicity vs required

Setting required = true implies a minimum multiplicity of 1, and options with a minimum multiplicity of 1 or more are implicitly "required". (On a related note: the current recommendation for making a positional parameter "required" is to give it an arity of 1 or more.)