Package io.github.qishr.cascara.common.util

Class OptionSpec

java.lang.Object
        io.github.qishr.cascara.common.util.CommandLine.Model.ArgSpec
                io.github.qishr.cascara.common.util.CommandLine.Model.OptionSpec

All Implemented Interfaces:
    IOrdered

Enclosing Class:
    io.github.qishr.cascara.common.util.CommandLine.Model

---

public static class OptionSpec
extends ArgSpec

The OptionSpec class models aspects of a named option of a CommandSpec, 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(Object) 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 #converters() 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(Object) is called. Programmatically constructed OptionSpec instances will remember the value passed to the #setValue(Object) method so it can be retrieved with the #getValue() method. This behaviour can be customized by installing a custom IGetter and ISetter on the OptionSpec.

Nested Class Summary

Modifier and Type	Class	Description
public static	io.github.qishr.cascara.common.util.CommandLine.Model.OptionSpec.Builder	Builder responsible for creating valid OptionSpec objects.

Field Summary

Modifier and Type	Field	Description
public static final String	DEFAULT_FALLBACK_VALUE

Method Summary

Modifier and Type	Method	Description
public static Builder	builder(String name, String[] names)
public static Builder	builder(String[] names)
public static Builder	builder(IAnnotatedElement source, IFactory factory)
public static Builder	builder(OptionSpec original)	Returns a Builder initialized from the specified OptionSpec.
public Builder	toBuilder()	Returns a new Builder initialized with the attributes from this OptionSpec.
public boolean	isOption()
public boolean	isPositional()
protected boolean	internalShowDefaultValue(boolean usageMessageShowDefaults)
protected Collection<String>	getAdditionalDescriptionKeys()	Returns the additional lookup keys for finding description lines in the resource bundle for this option.
public String[]	names()	Returns one or more option names.
public String	longestName()	Returns the longest names.names.
public String	shortestName()	Returns the shortest names.names.
public int	order()	Returns the position in the options list in the usage help message at which this option should be shown.
public boolean	help()	Returns whether this option disables validation of the other arguments.
public boolean	usageHelp()	Returns whether this option allows the user to request usage help.
public boolean	versionHelp()	Returns whether this option allows the user to request version information.
public boolean	negatable()	Returns whether a negative version for this boolean option is automatically added.
public 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.
public boolean	equals(Object obj)
public int	hashCode()

Methods inherited from ArgSpec

preprocessor, auxiliaryTypes, interactive, renderedDescription, messages, required, splitRegexSynopsisLabel, hidden, description, hideParamSyntax, stringValues, resetOriginalStringValues, echo, initialValue, descriptionKey, converters, inherited, completionCandidates, toString, command, isMultiValue, equalsImpl, root, group, getter, setter, originalStringValues, typeInfo, setValue, resetStringValues, typedValues, prompt, arity, parameterConsumer, showDefaultValue, defaultValueString, getValue, originallyRequired, splitRegex, setValue, mapFallbackValue, defaultValue, scopeType, type, userObject, messages, hashCodeImpl, scope, isValueGettable, hasInitialValue, defaultValueString, paramLabel

Field Details

DEFAULT_FALLBACK_VALUE

public static final String DEFAULT_FALLBACK_VALUE

---

Method Details

builder

public static Builder builder(String name, String[] names)

---

builder

public static Builder builder(String[] names)

---

builder

public static Builder builder(IAnnotatedElement source, IFactory factory)

---

builder

public static Builder builder(OptionSpec original)

Returns a Builder initialized from the specified OptionSpec.

Since:

4.0

---

toBuilder

public Builder toBuilder()

Returns a new Builder initialized with the attributes from this OptionSpec.Calling build immediately will return a copy of this OptionSpec.

Returns:

a builder that can create a copy of this spec

---

isOption

public boolean isOption()

Overrides:

ArgSpec

---

isPositional

public boolean isPositional()

Overrides:

ArgSpec

---

internalShowDefaultValue

protected boolean internalShowDefaultValue(boolean usageMessageShowDefaults)

---

getAdditionalDescriptionKeys

protected Collection<String> getAdditionalDescriptionKeys()

Returns the additional lookup keys for finding description lines in the resource bundle for this option.

Returns:

option names (after variable interpolation), without leading hyphens, slashes and other non-Java identifier characters.

Overrides:

ArgSpec

Since:

4.0

---

names

public String[] names()

Returns one or more option names.The returned array will contain at least one option name.

See Also:

names

---

longestName

public String longestName()

Returns the longest names.names.

---

shortestName

public String shortestName()

Returns the shortest names.names.

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 if UsageMessageSpec#sortOptions() is false for this command.

Specified By:

IOrdered

Since:

3.9

See Also:

order

---

help

public boolean help()

Returns whether this option disables validation of the other arguments.

Deprecation

Use usageHelp.usageHelp and versionHelp.versionHelp instead.

See Also:

help

---

usageHelp

public boolean usageHelp()

Returns whether this option allows the user to request usage help.

See Also:

usageHelp

---

versionHelp

public boolean versionHelp()

Returns whether this option allows the user to request version information.

See Also:

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 the INegatableOptionTransformer.

Since:

4.0

See Also:

negatable

---

fallbackValue

public 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 #NULL_VALUE is set, this method returns null.

Since:

4.0

See Also:

fallbackValue

defaultValue

---

equals

public boolean equals(Object obj)

---

hashCode

public int hashCode()

---