Class CommandLine.Model.OptionSpec
- java.lang.Object
-
- picocli.CommandLine.Model.ArgSpec
-
- picocli.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
TheOptionSpecclass 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 callsetValueon the matched option for each of the option parameters encountered.For multi-value options, the
typemay be an array, aCollectionor aMap. In this case the parser will get the data structure by callinggetValueand 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
converteris configured, this will be used for type conversion. If the option's type is aMap, the map may have different types for its keys and its values, soconvertersshould provide two converters: one for the map keys and one for the map values. - Otherwise, the option's
typeis used to look up a converter in the list of registered converters. For multi-value options, thetypemay be an array, or aCollectionor aMap. In that case the elements are converted based on the option'sauxiliaryTypes. 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, soauxiliaryTypesshould provide two types: one for the map keys and one for the map values.
OptionSpecobjects are used by the picocli command line interpreter and help message generator. Picocli can construct anOptionSpecautomatically from fields and methods with@Optionannotations. Alternatively anOptionSpeccan be constructed programmatically.When an
OptionSpecis 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 andsetValueis called. Programmatically constructedOptionSpecinstances will remember the value passed to thesetValuemethod so it can be retrieved with thegetValuemethod. This behaviour can be customized by installing a customCommandLine.Model.IGetterandCommandLine.Model.ISetteron theOptionSpec.- Since:
- 3.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classCommandLine.Model.OptionSpec.BuilderBuilder responsible for creating validOptionSpecobjects.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.StringDEFAULT_FALLBACK_VALUE-
Fields inherited from class picocli.CommandLine.Model.ArgSpec
annotatedElement, toString, typeInfo, valueIsDefaultValue
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static CommandLine.Model.OptionSpec.Builderbuilder(java.lang.String[] names)static CommandLine.Model.OptionSpec.Builderbuilder(java.lang.String name, java.lang.String... names)static CommandLine.Model.OptionSpec.Builderbuilder(CommandLine.Model.IAnnotatedElement source, CommandLine.IFactory factory)static CommandLine.Model.OptionSpec.Builderbuilder(CommandLine.Model.OptionSpec original)Returns a Builder initialized from the specifiedOptionSpec.booleanequals(java.lang.Object obj)java.lang.StringfallbackValue()Returns the fallback value for this option: the value that is assigned for options with an optional parameter (for example,arity = "0..1") if the option was specified on the command line without parameter.protected java.util.Collection<java.lang.String>getAdditionalDescriptionKeys()Returns the additional lookup keys for finding description lines in the resource bundle for this option.inthashCode()booleanhelp()Deprecated.UseusageHelp()andversionHelp()instead.protected booleaninternalShowDefaultValue(boolean usageMessageShowDefaults)Returns whether the default for this option or positional parameter should be shown, potentially overriding the specified global setting.booleanisOption()Returnstrueif this argument is a named option,falseotherwise.booleanisPositional()Returnstrueif this argument is a positional parameter,falseotherwise.java.lang.StringlongestName()Returns the longest option name.java.lang.String[]names()Returns one or more option names.booleannegatable()Returns whether a negative version for this boolean option is automatically added.intorder()Returns the position in the options list in the usage help message at which this option should be shown.java.lang.StringshortestName()Returns the shortest option name.CommandLine.Model.OptionSpec.BuildertoBuilder()Returns a new Builder initialized with the attributes from thisOptionSpec.booleanusageHelp()Returns whether this option allows the user to request usage help.booleanversionHelp()Returns whether this option allows the user to request version information.-
Methods inherited from class picocli.CommandLine.Model.ArgSpec
arity, auxiliaryTypes, command, completionCandidates, converters, defaultValue, defaultValueString, defaultValueString, description, descriptionKey, echo, equalsImpl, getter, getValue, group, hashCodeImpl, hasInitialValue, hidden, hideParamSyntax, inherited, initialValue, interactive, isMultiValue, isValueGettable, mapFallbackValue, messages, messages, originallyRequired, originalStringValues, parameterConsumer, paramLabel, preprocessor, prompt, renderedDescription, required, resetOriginalStringValues, resetStringValues, root, scope, scopeType, setter, setValue, setValue, showDefaultValue, splitRegex, splitRegexSynopsisLabel, stringValues, toString, type, typedValues, typeInfo, userObject
-
-
-
-
Field Detail
-
DEFAULT_FALLBACK_VALUE
public static final java.lang.String DEFAULT_FALLBACK_VALUE
- See Also:
- Constant Field Values
-
-
Method Detail
-
builder
public static CommandLine.Model.OptionSpec.Builder builder(java.lang.String name, java.lang.String... names)
-
builder
public static CommandLine.Model.OptionSpec.Builder builder(java.lang.String[] names)
-
builder
public static CommandLine.Model.OptionSpec.Builder builder(CommandLine.Model.IAnnotatedElement source, CommandLine.IFactory factory)
-
builder
public static CommandLine.Model.OptionSpec.Builder builder(CommandLine.Model.OptionSpec original)
Returns a Builder initialized from the specifiedOptionSpec.- Since:
- 4.0
-
toBuilder
public CommandLine.Model.OptionSpec.Builder toBuilder()
Returns a new Builder initialized with the attributes from thisOptionSpec. Callingbuildimmediately will return a copy of thisOptionSpec.- Returns:
- a builder that can create a copy of this spec
-
isOption
public boolean isOption()
Description copied from class:CommandLine.Model.ArgSpecReturnstrueif this argument is a named option,falseotherwise.- Specified by:
isOptionin classCommandLine.Model.ArgSpec
-
isPositional
public boolean isPositional()
Description copied from class:CommandLine.Model.ArgSpecReturnstrueif this argument is a positional parameter,falseotherwise.- Specified by:
isPositionalin classCommandLine.Model.ArgSpec
-
internalShowDefaultValue
protected boolean internalShowDefaultValue(boolean usageMessageShowDefaults)
Description copied from class:CommandLine.Model.ArgSpecReturns whether the default for this option or positional parameter should be shown, potentially overriding the specified global setting.- Overrides:
internalShowDefaultValuein classCommandLine.Model.ArgSpec- Parameters:
usageMessageShowDefaults- whether the command's UsageMessageSpec is configured to show default values.
-
getAdditionalDescriptionKeys
protected java.util.Collection<java.lang.String> getAdditionalDescriptionKeys()
Returns the additional lookup keys for finding description lines in the resource bundle for this option.- Specified by:
getAdditionalDescriptionKeysin classCommandLine.Model.ArgSpec- Returns:
- option names (after variable interpolation), without leading hyphens, slashes and other non-Java identifier characters.
- Since:
- 4.0
- See Also:
getAdditionalDescriptionKeys(),CommandLine.Model.PositionalParamSpec.getAdditionalDescriptionKeys()
-
names
public java.lang.String[] names()
Returns one or more option names. The returned array will contain at least one option name.- See Also:
CommandLine.Option.names()
-
longestName
public java.lang.String longestName()
Returns the longest option name.
-
shortestName
public java.lang.String shortestName()
Returns the shortest option name.- Since:
- 3.8
-
order
public int order()
Returns the position in the options list in the usage help message at which this option should be shown. Options with a lower number are shown before options with a higher number. This attribute is only honored ifCommandLine.Model.UsageMessageSpec.sortOptions()isfalsefor this command.- Specified by:
orderin interfaceCommandLine.Model.IOrdered- Since:
- 3.9
- See Also:
CommandLine.Option.order()
-
help
@Deprecated public boolean help()
Deprecated.UseusageHelp()andversionHelp()instead.Returns whether this option disables validation of the other arguments.- See Also:
CommandLine.Option.help()
-
usageHelp
public boolean usageHelp()
Returns whether this option allows the user to request usage help.- See Also:
CommandLine.Option.usageHelp()
-
versionHelp
public boolean versionHelp()
Returns whether this option allows the user to request version information.- See Also:
CommandLine.Option.versionHelp()
-
negatable
public boolean negatable()
Returns whether a negative version for this boolean option is automatically added. The form of the negative name is determined by theCommandLine.INegatableOptionTransformer.- Since:
- 4.0
- See Also:
CommandLine.Option.negatable()
-
fallbackValue
public java.lang.String fallbackValue()
Returns the fallback value for this option: the value that is assigned for options with an optional parameter (for example,arity = "0..1") if the option was specified on the command line without parameter.If the special value
CommandLine.Model.ArgSpec.NULL_VALUEis set, this method returnsnull.- Since:
- 4.0
- See Also:
CommandLine.Option.fallbackValue(),CommandLine.Model.ArgSpec.defaultValue()
-
equals
public boolean equals(java.lang.Object obj)
- Overrides:
equalsin classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCodein classjava.lang.Object
-
-