Adds a new option description to the parser. The method takes two arguments: a specification string, and a result holder in which to store the associated value.
The specification string has the general form
optionNames %conversionCode [{rangeSpec}] [Xmultiplier] [#valueDescription] [#optionDescription]
where
- optionNames is a comma-separated list of names for the option (such as
-f, --file). - conversionCode is a single letter, following a
% character, specifying information about what value the option requires: %f | a floating point number |
%i | an integer, in either decimal, hex (if preceeded by 0x), or octal (if preceeded by 0) |
%d | a decimal integer |
%o | an octal integer |
%h | a hex integer (without the preceeding 0x) |
%c | a single character, including escape sequences (such as \n or \007), and optionally enclosed in single quotes |
%b | a boolean value (true or false) |
%s | a string. This will be the argument string itself (or its remainder, in the case of a single word option) |
%v | no explicit value is expected, but a boolean value of true (by default) will be stored into the associated result holder if this option is matched. If one wishes to have a value of false stored instead, then the %v should be followed by a "range spec" containing false, as in %v{false}. |
- rangeSpec is an optional range specification, placed inside curly braces, consisting of a comma-separated list of range items each specifying permissible values for the option. A range item may be an individual value, or it may itself be a subrange, consisting of two individual values, separated by a comma, and enclosed in square or round brackets. Square and round brackets denote closed and open endpoints of a subrange, indicating that the associated endpoint value is included or excluded from the subrange. The values specified in the range spec need to be consistent with the type of value expected by the option.
Examples:
A range spec of {2,4,8,16} for an integer value will allow the integers 2, 4, 8, or 16.
A range spec of {[-1.0,1.0]} for a floating point value will allow any floating point number in the range -1.0 to 1.0.
A range spec of {(-88,100],1000} for an integer value will allow values > -88 and <= 100, as well as 1000.
A range spec of {"foo", "bar", ["aaa","zzz")} for a string value will allow strings equal to "foo" or "bar", plus any string lexically greater than or equal to "aaa" but less then "zzz".
- multiplier is an optional integer, following a
X character, indicating the number of values which the option expects. If the multiplier is not specified, it is assumed to be 1. If the multiplier value is greater than 1, then the result holder should be either an array (of appropriate type) with a length greater than or equal to the multiplier value, or a java.util.Vector as discussed below. - valueDescription is an optional description of the option's value requirements, and consists of all characters between two
# characters. The final # character initiates the option description, which may be empty. The value description is used in generating help messages. - optionDescription is an optional description of the option itself, consisting of all characters between a
# character and the end of the specification string. The option description is used in generating help messages.
The result holder must be an object capable of holding a value compatible with the conversion code, or it must be a java.util.Vector. When the option is matched, its associated value is placed in the result holder. If the same option is matched repeatedly, the result holder value will be overwritten, unless the result holder is a java.util.Vector, in which case new holder objects for each match will be allocated and added to the vector. Thus if multiple instances of an option are desired by the program, the result holder should be a java.util.Vector.
If the result holder is not a Vector, then it must correspond as follows to the conversion code:
%i, %d, %x, %o | {@link argparser.IntHolder IntHolder}, {@link argparser.LongHolder LongHolder}, int[], or long[] |
%f | {@link argparser.FloatHolder FloatHolder}, {@link argparser.DoubleHolder DoubleHolder}, float[], or double[] |
%b, %v | {@link argparser.BooleanHolder BooleanHolder} orboolean[] |
%s | {@link argparser.StringHolder StringHolder} orString[] |
%c | {@link argparser.CharHolder CharHolder} orchar[] |
In addition, if the multiplier is greater than 1, then only the array type indicated above may be used, and the array must be at least as long as the multiplier.
If the result holder is a Vector, then the system will create an appropriate result holder object and add it to the vector. Multiple occurances of the option will cause multiple results to be added to the vector. The object allocated by the system to store the result will correspond to the conversion code as follows:
%i, %d, %x, %o | {@link argparser.LongHolder LongHolder}, or long[] if the multiplier value exceeds 1 |
%f | {@link argparser.DoubleHolder DoubleHolder}, or double[] if the multiplier value exceeds 1 |
%b, %v | {@link argparser.BooleanHolder BooleanHolder}, or boolean[] if the multiplier value exceeds 1 |
%s | {@link argparser.StringHolder StringHolder}, or String[] if the multiplier value exceeds 1 |
%c | {@link argparser.CharHolder CharHolder}, or char[] if the multiplier value exceeds 1 |
@param spec the specification string
@param resHolder object in which to store the associatedvalue
@throws IllegalArgumentException if there is an error inthe specification or if the result holder is of an invalid type.