Package io.github.qishr.cascara.common.util
Class PositionalParamSpec
java.lang.Object
io.github.qishr.cascara.common.util.CommandLine.Model.ArgSpec
io.github.qishr.cascara.common.util.CommandLine.Model.PositionalParamSpec
Enclosing Class:
io.github.qishr.cascara.common.util.CommandLine.Model
public static class PositionalParamSpec
extends ArgSpec
The PositionalParamSpec class models aspects of a positional parameter of a CommandSpec, including whether
it is required or optional, and attributes for the usage help message describing the positional parameter.
Positional parameters have an index (or a range of indices). A positional parameter is matched when the parser encounters a command line argument at that index. Named options and their parameters do not change the index counter, so the command line can contain a mixture of positional parameters and named options.
Depending on the positional parameter's #arity(), the parser may consume multiple command line
arguments starting from the current index. The parser will call #setValue(Object) on
the PositionalParamSpec for each of the parameters encountered.
For multi-value positional parameters, 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 positional parameter value from a String to the parameter's type.
If a positional parameter-specific #converters() is configured, this will be used for type conversion.
If the positional parameter'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 positional parameter's #type() is used to look up a converter in the list of
registered converters. For multi-value positional parameters,
the type may be an array, or a Collection or a Map. In that case the elements are converted
based on the positional parameter'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.
PositionalParamSpec objects are used by the picocli command line interpreter and help message generator.
Picocli can construct a PositionalParamSpec automatically from fields and methods with Parameters
annotations. Alternatively a PositionalParamSpec can be constructed programmatically.
When a PositionalParamSpec is created from a Parameters -annotated field or method,
it is "bound" to that field or method: this field is set (or the method is invoked) when the position is matched
and #setValue(Object) is called.
Programmatically constructed PositionalParamSpec 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 PositionalParamSpec.
Nested Class Summary
| Modifier and Type | Class | Description |
|---|---|---|
| public static | io.github.qishr.cascara.common.util.CommandLine.Model.PositionalParamSpec.Builder | Builder responsible for creating valid PositionalParamSpec objects. |
Method Summary
| Modifier and Type | Method | Description |
|---|---|---|
| public static Builder | builder() | |
| public static Builder | builder(PositionalParamSpec original) | Returns a Builder initialized from the specified PositionalSpec. |
| public static Builder | builder(IAnnotatedElement source, IFactory factory) | |
| public Builder | toBuilder() | Returns a new Builder initialized with the attributes from this PositionalParamSpec. |
| public boolean | isOption() | |
| public boolean | isPositional() | |
| protected Collection<String> | getAdditionalDescriptionKeys() | Returns the additional lookup keys for finding description lines in the resource bundle for this positional parameter. |
| public Range | index() | Returns an index or range specifying which of the command line arguments should be assigned to this positional parameter. |
| public int | hashCode() | |
| public boolean | equals(Object obj) |
Methods inherited from ArgSpec
preprocessor, auxiliaryTypes, interactive, renderedDescription, messages, required, splitRegexSynopsisLabel, internalShowDefaultValue, 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
Method Details
builder
public static Builder builder()
builder
public static Builder builder(PositionalParamSpec original)
Returns a Builder initialized from the specified PositionalSpec.
Since:
4.0
builder
public static Builder builder(IAnnotatedElement source, IFactory factory)
toBuilder
public Builder toBuilder()
Returns a new Builder initialized with the attributes from this PositionalParamSpec.Calling build immediately will return a copy of this PositionalParamSpec.
Returns:
a builder that can create a copy of this spec
isOption
public boolean isOption()
Overrides:
isPositional
public boolean isPositional()
Overrides:
getAdditionalDescriptionKeys
protected Collection<String> getAdditionalDescriptionKeys()
Returns the additional lookup keys for finding description lines in the resource bundle for this positional parameter.
Returns:
a collection with the following single value: paramLabel() + "[" + index() + "]".
Overrides:
Since:
4.0
index
public Range index()
Returns an index or range specifying which of the command line arguments should be assigned to this positional parameter.
See Also:
hashCode
public int hashCode()
equals
public boolean equals(Object obj)