Module info.picocli
Package picocli

Class CommandLine.Model.OptionSpec

  • All Implemented Interfaces:
    CommandLine.Model.IOrdered
    Enclosing class:
    CommandLine.Model
    public static class CommandLine.Model.OptionSpec
extends CommandLine.Model.ArgSpec
implements CommandLine.Model.IOrdered
    The OptionSpec class models aspects of a named option of a command, including whether it is required or optional, the option parameters supported (or required) by the option, and attributes for the usage help message describing the option.

    An option has one or more names. The option is matched when the parser encounters one of the option names in the command line arguments. Depending on the option's arity, the parser may expect it to have option parameters. The parser will call setValue on the matched option for each of the option parameters encountered.

    For multi-value options, the type may be an array, a Collection or a Map. In this case the parser will get the data structure by calling getValue and modify the contents of this data structure. (In the case of arrays, the array is replaced with a new instance with additional elements.)

    Before calling the setter, picocli converts the option parameter value from a String to the option parameter's type.

    • If a option-specific converter is configured, this will be used for type conversion. If the option's type is a Map, the map may have different types for its keys and its values, so converters should provide two converters: one for the map keys and one for the map values.
    • Otherwise, the option's type is used to look up a converter in the list of registered converters. For multi-value options, the type may be an array, or a Collection or a Map. In that case the elements are converted based on the option's auxiliaryTypes. The auxiliaryType is used to look up the converter(s) to use to convert the individual parameter values. Maps may have different types for its keys and its values, so auxiliaryTypes should provide two types: one for the map keys and one for the map values.

    OptionSpec objects are used by the picocli command line interpreter and help message generator. Picocli can construct an OptionSpec automatically from fields and methods with @Option annotations. Alternatively an OptionSpec can be constructed programmatically.

    When an OptionSpec is created from an @Option -annotated field or method, it is "bound" to that field or method: this field is set (or the method is invoked) when the option is matched and setValue is called. Programmatically constructed OptionSpec instances will remember the value passed to the setValue method so it can be retrieved with the getValue method. This behaviour can be customized by installing a custom CommandLine.Model.IGetter and CommandLine.Model.ISetter on the OptionSpec.

    Since:
    3.0