Package io.github.qishr.cascara.common.util
Class ArgSpec
java.lang.Object
io.github.qishr.cascara.common.util.CommandLine.Model.ArgSpec
Enclosing Class:
io.github.qishr.cascara.common.util.CommandLine.Model
Direct Known Subtypes:
OptionSpec, PositionalParamSpec
public static abstract class ArgSpec
Models the shared attributes of OptionSpec and PositionalParamSpec.
Field Summary
| Modifier and Type | Field | Description |
|---|---|---|
| protected final IAnnotatedElement | annotatedElement | |
| protected String | toString | |
| protected final ITypeInfo | typeInfo | |
| protected boolean | valueIsDefaultValue |
Method Summary
| Modifier and Type | Method | Description |
|---|---|---|
| public boolean | originallyRequired() | Returns the original value of the option's required attribute, regardless of whether the option is used in an exclusive group or not. |
| public boolean | required() | Returns whether this is a required option or positional parameter without a default value. |
| public boolean | interactive() | Returns whether this option will prompt the user to enter a value on the command line. |
| public boolean | echo() | Returns whether the user input is echoed to the console or not for an interactive option or positional parameter when asking for user input. |
| public String | prompt() | Returns the text displayed to the end user for an interactive option or positional parameter when asking for user input. |
| public String[] | description() | Returns the description of this option or positional parameter, after all variables have been rendered, including the ${DEFAULT-VALUE} and ${COMPLETION-CANDIDATES} variables. |
| protected abstract Collection<String> | getAdditionalDescriptionKeys() | Subclasses should override to return a collection of additional description keys that may be used to find description text for this option or positional parameter in the resource bundle. |
| public String | descriptionKey() | Returns the description key of this arg spec, used to get the description from a resource bundle. |
| public String[] | renderedDescription() | |
| public Range | arity() | Returns how many arguments this option or positional parameter requires. |
| public String | paramLabel() | Returns the name of the option or positional parameter used in the usage help message. |
| public boolean | hideParamSyntax() | Returns whether usage syntax decorations around the paramLabel.paramLabel should be suppressed. |
| public Class<?>[] | auxiliaryTypes() | Returns auxiliary type information used when the type.type is a generic type like Collection, Map or Optional; returns the concrete type when type.type is an abstract class, otherwise, returns the same as type.type. |
| public ITypeConverter<?>[] | converters() | Returns one or more CommandLine.ITypeConverter to use to convert the command line argument into a strongly typed value (or key-value pair for map fields). |
| public String | splitRegex() | Returns a regular expression to split option parameter values or "" if the value should not be split. |
| public String | splitRegexSynopsisLabel() | Returns a regular expression to split option parameter for usage information. |
| public boolean | hidden() | Returns whether this option should be excluded from the usage message. |
| public boolean | inherited() | Returns whether this option is inherited from a parent command. |
| public ArgSpec | root() | Returns the root option or positional parameter (on the parent command), if this option or positional parameter was inherited; or null if it was not. |
| public Class<?> | type() | Returns the type to convert the option or positional parameter to before setValue.setValue the value. |
| public ITypeInfo | typeInfo() | Returns the ITypeInfo that can be used both at compile time (by annotation processors) and at runtime. |
| public Object | userObject() | Returns the user object associated with this option or positional parameters. |
| public String | mapFallbackValue() | Returns the fallback value for this Map option or positional parameter: the value that is put into the Map when only the key is specified for the option or positional parameter, like -Dkey instead of -Dkey=value. |
| public String | defaultValue() | Returns the default value to assign if this option or positional parameter was not specified on the command line, before splitting and type conversion. |
| public Object | initialValue() | Returns the initial value of this option or positional parameter: the value that, if hasInitialValue.hasInitialValue is true, the option will be reset to before parsing (regardless of whether a default value exists), to clear values that would otherwise remain from parsing previous input. |
| public boolean | hasInitialValue() | Determines whether the option or positional parameter will be reset to the initialValue.initialValue before parsing new input. |
| public Visibility | showDefaultValue() | Returns whether this option or positional parameter's default value should be shown in the usage help. |
| public String | defaultValueString() | Returns the default value String for the purpose of displaying it in the description, without interpolating variables. |
| public String | defaultValueString(boolean interpolateVariables) | Returns the default value String displayed in the description; interpolating variables if specified. |
| public Iterable<String> | completionCandidates() | Returns the explicitly set completion candidates for this option or positional parameter, valid enum constant names, or null if this option or positional parameter does not have any completion candidates and its type is not an enum. |
| public IParameterConsumer | parameterConsumer() | Returns a custom IParameterConsumer to temporarily suspend picocli's parsing logic and process one or more command line arguments in a custom manner, or null. |
| public IParameterPreprocessor | preprocessor() | Returns a custom IParameterPreprocessor to either replace or complement picocli's parsing logic for the parameter(s) of this option or position. |
| public IGetter | getter() | Returns the IGetter that is responsible for supplying the value of this argument. |
| public ISetter | setter() | Returns the ISetter that is responsible for modifying the value of this argument. |
| public IScope | scope() | Returns the binding IScope that determines on which object to set the value (or from which object to get the value) of this argument. |
| public ScopeType | scopeType() | Returns the scope of this argument; is it local, or inherited (it applies to this command as well as all sub- and sub-subcommands). |
| public boolean | isValueGettable() | Check whether the getValue.getValue method is able to get an actual value from the current getter.getter. |
| public T | getValue() | Returns the current value of this argument. |
| public T | setValue(T newValue) | Sets the value of this argument to the specified value and returns the previous value. |
| public T | setValue(T newValue, CommandLine commandLine) | Sets the value of this argument to the specified value and returns the previous value. |
| public boolean | isMultiValue() | Returns true if this argument's type.type is an array, a Collection or a Map, false otherwise. |
| public abstract boolean | isOption() | Returns true if this argument is a named option, false otherwise. |
| public abstract boolean | isPositional() | Returns true if this argument is a positional parameter, false otherwise. |
| public ArgGroupSpec | group() | Returns the groups this option or positional parameter belongs to, or null if this option is not part of a group. |
| public CommandSpec | command() | Returns the command this option or positional parameter belongs to. |
| public List<String> | stringValues() | Returns the untyped command line arguments matched by this option or positional parameter spec. |
| public List<Object> | typedValues() | Returns the typed command line arguments matched by this option or positional parameter spec. |
| protected void | resetStringValues() | Sets the stringValues to a new list instance. |
| public List<String> | originalStringValues() | Returns the original command line arguments matched by this option or positional parameter spec. |
| protected void | resetOriginalStringValues() | Sets the originalStringValues to a new list instance. |
| protected boolean | internalShowDefaultValue(boolean usageHelpShowDefaults) | Returns whether the default for this option or positional parameter should be shown, potentially overriding the specified global setting. |
| public Messages | messages() | Returns the Messages for this arg specification, or null. |
| public ArgSpec | messages(Messages msgs) | Sets the Messages for this ArgSpec, and returns this ArgSpec. |
| public String | toString() | Returns a string respresentation of this option or positional parameter. |
| protected boolean | equalsImpl(ArgSpec other) | |
| protected int | hashCodeImpl() |
Field Details
annotatedElement
protected final IAnnotatedElement annotatedElement
toString
protected String toString
typeInfo
protected final ITypeInfo typeInfo
valueIsDefaultValue
protected boolean valueIsDefaultValue
Method Details
originallyRequired
public boolean originallyRequired()
Returns the original value of the option's required attribute, regardless of whether the option is used in an exclusive group or not.
Since:
4.7.8-SNAPSHOT
See Also:
required
public boolean required()
Returns whether this is a required option or positional parameter without a default value.If this argument is part of a ArgGroup, this method returns whether this argument is required within the group (so it is not necessarily a required argument for the command).
See Also:
interactive
public boolean interactive()
Returns whether this option will prompt the user to enter a value on the command line.
See Also:
echo
public boolean echo()
Returns whether the user input is echoed to the console or not for an interactive option or positional parameter when asking for user input.
Since:
4.6
See Also:
prompt
public String prompt()
Returns the text displayed to the end user for an interactive option or positional parameter when asking for user input.
Since:
4.6
See Also:
description
public String[] description()
Returns the description of this option or positional parameter, after all variables have been rendered,
including the ${DEFAULT-VALUE} and ${COMPLETION-CANDIDATES} variables.Use CommandSpec#interpolateVariables(Boolean) to switch off variable expansion if needed.
If a resource bundle has been ArgSpec.messages, this method will first try to find a value in the resource bundle:
If the resource bundle has no entry for the fully qualified commandName + "." + descriptionKey or for the unqualified descriptionKey,
an attempt is made to find the option or positional parameter description using any of the
getAdditionalDescriptionKeys.getAdditionalDescriptionKeys, first with the fully qualified commandName + "." prefix, then without.
See Also:
getAdditionalDescriptionKeys
protected abstract Collection<String> getAdditionalDescriptionKeys()
Subclasses should override to return a collection of additional description keys that may be used to find description text for this option or positional parameter in the resource bundle.
Since:
4.0
See Also:
descriptionKey
public String descriptionKey()
Returns the description key of this arg spec, used to get the description from a resource bundle.
Since:
3.6
See Also:
renderedDescription
public String[] renderedDescription()
Deprecation
Use description.description instead
arity
public Range arity()
Returns how many arguments this option or positional parameter requires.
See Also:
paramLabel
public String paramLabel()
Returns the name of the option or positional parameter used in the usage help message.
See Also:
hideParamSyntax
public boolean hideParamSyntax()
Returns whether usage syntax decorations around the paramLabel.paramLabel should be suppressed.The default is false: by default, the paramLabel is surrounded with '[' and ']' characters
if the value is optional and followed by ellipses ("...") when multiple values can be specified.
Since:
3.6.0
auxiliaryTypes
public Class<?>[] auxiliaryTypes()
Returns auxiliary type information used when the type.type is a generic type like
Collection, Map or Optional; returns the concrete type when type.type
is an abstract class, otherwise, returns the same as type.type.
See Also:
converters
public ITypeConverter<?>[] converters()
Returns one or more CommandLine.ITypeConverter to use to convert the command line argument into a strongly typed value (or key-value pair for map fields).This is useful when a particular option or positional parameter should use a custom conversion that is different from the normal conversion for the arg spec's type.
See Also:
splitRegex
public String splitRegex()
Returns a regular expression to split option parameter values or "" if the value should not be split.
See Also:
splitRegexSynopsisLabel
public String splitRegexSynopsisLabel()
Returns a regular expression to split option parameter for usage information.
Since:
4.3
See Also:
hidden
public boolean hidden()
Returns whether this option should be excluded from the usage message.
See Also:
inherited
public boolean inherited()
Returns whether this option is inherited from a parent command.
Since:
4.3.0
See Also:
root
public ArgSpec root()
Returns the root option or positional parameter (on the parent command), if this option or positional parameter was inherited;
or null if it was not.
Since:
4.6.0
See Also:
type
public Class<?> type()
Returns the type to convert the option or positional parameter to before setValue.setValue the value.This may be a container type like List, Map, or Optional,
in which case the type or types of the elements are returned by auxiliaryTypes.auxiliaryTypes.
typeInfo
public ITypeInfo typeInfo()
Returns the ITypeInfo that can be used both at compile time (by annotation processors) and at runtime.
Since:
4.0
userObject
public Object userObject()
Returns the user object associated with this option or positional parameters.
Returns:
may return the annotated program element, or some other useful object
Since:
4.0
mapFallbackValue
public String mapFallbackValue()
Returns the fallback value for this Map option or positional parameter: the value that is put into the Map when only the
key is specified for the option or positional parameter, like -Dkey instead of -Dkey=value.
If no mapFallbackValue is set, key-only Map parameters like -Dkey
are considered invalid user input and cause a ParameterException to be thrown.
By default, this method returns a special "unspecified" value indicating that no mapFallbackValue was set.
Since:
4.6
See Also:
defaultValue
public String defaultValue()
Returns the default value to assign if this option or positional parameter was not specified on the command line, before splitting and type conversion.This method returns the programmatically set value; this may differ from the default value that is actually used:
if this ArgSpec is part of a CommandSpec with a IDefaultValueProvider, picocli will first try to obtain
the default value from the default value provider, and this method is only called if the default provider is
null or returned a null value.
Returns:
the programmatically set default value of this option/positional parameter,
returning null means this option or positional parameter does not have a default
See Also:
initialValue
public Object initialValue()
Returns the initial value of this option or positional parameter: the value that, if hasInitialValue.hasInitialValue is true, the option will be reset to before parsing (regardless of whether a default value exists), to clear values that would otherwise remain from parsing previous input.
hasInitialValue
public boolean hasInitialValue()
Determines whether the option or positional parameter will be reset to the initialValue.initialValue before parsing new input.
showDefaultValue
public Visibility showDefaultValue()
Returns whether this option or positional parameter's default value should be shown in the usage help.
defaultValueString
public String defaultValueString()
Returns the default value String for the purpose of displaying it in the description, without interpolating variables.
See Also:
defaultValueString
public String defaultValueString(boolean interpolateVariables)
Returns the default value String displayed in the description; interpolating variables if specified.If this ArgSpec is part of a
CommandSpec with a IDefaultValueProvider, this method will first try to obtain
the default value from the default value provider; if the provider is null or if it
returns a null value, then next any value set to ArgSpec.defaultValue
is returned, and if this is also null, finally the ArgSpec.initialValue is returned.
Parameters:
interpolateVariables - whether to interpolate variables in the defaultValue attribute of this ArgSpec
Since:
4.0
See Also:
completionCandidates
public Iterable<String> completionCandidates()
Returns the explicitly set completion candidates for this option or positional parameter, valid enum
constant names, or null if this option or positional parameter does not have any completion
candidates and its type is not an enum.
Returns:
the completion candidates for this option or positional parameter, valid enum constant names,
or null
Since:
3.2
parameterConsumer
public IParameterConsumer parameterConsumer()
Returns a custom IParameterConsumer to temporarily suspend picocli's parsing logic
and process one or more command line arguments in a custom manner, or null.An example of when this may be useful is when passing arguments through to another program.
Since:
4.0
preprocessor
public IParameterPreprocessor preprocessor()
Returns a custom IParameterPreprocessor to either replace or complement picocli's parsing logic
for the parameter(s) of this option or position.
Since:
4.6
getter
public IGetter getter()
Returns the IGetter that is responsible for supplying the value of this argument.
setter
public ISetter setter()
Returns the ISetter that is responsible for modifying the value of this argument.
scope
public IScope scope()
Returns the binding IScope that determines on which object to set the value (or from which object to get the value) of this argument.
scopeType
public ScopeType scopeType()
Returns the scope of this argument; is it local, or inherited (it applies to this command as well as all sub- and sub-subcommands).
Returns:
whether this argument applies to all descendent subcommands of the command where it is defined
Since:
4.3
isValueGettable
public boolean isValueGettable()
Check whether the getValue.getValue method is able to get an actual value from the current getter.getter.
Since:
4.7
getValue
public T getValue()
Returns the current value of this argument.Delegates to the current getter.getter.
Throws:
setValue
public T setValue(T newValue)
Sets the value of this argument to the specified value and returns the previous value.Delegates to the current setter.setter.
Throws:
setValue
public T setValue(T newValue, CommandLine commandLine)
Sets the value of this argument to the specified value and returns the previous value.Delegates to the current setter.setter.
Deprecation
use setValue.setValue instead. This was a design mistake.
Throws:
Since:
3.5
isMultiValue
public boolean isMultiValue()
Returns true if this argument's type.type is an array, a Collection or a Map, false otherwise.
isOption
public abstract boolean isOption()
Returns true if this argument is a named option, false otherwise.
isPositional
public abstract boolean isPositional()
Returns true if this argument is a positional parameter, false otherwise.
group
public ArgGroupSpec group()
Returns the groups this option or positional parameter belongs to, or null if this option is not part of a group.
Since:
4.0
command
public CommandSpec command()
Returns the command this option or positional parameter belongs to.
Beware that it is possible to programmatically add an option or positional parameter to more than one command model. (This will not happen in models that are auto-generated from annotations). In that case this method will only return the one it was added to last.
If the option or positional parameter has not yet been attached to a command, null will be returned.
Since:
4.1
stringValues
public List<String> stringValues()
Returns the untyped command line arguments matched by this option or positional parameter spec.
Returns:
the matched arguments after splitRegex.splitRegex, but before type conversion.
For map properties, "key=value" values are split into the key and the value part.
typedValues
public List<Object> typedValues()
Returns the typed command line arguments matched by this option or positional parameter spec.
Returns:
the matched arguments after splitRegex.splitRegex and type conversion.
For map properties, "key=value" values are split into the key and the value part.
resetStringValues
protected void resetStringValues()
Sets the stringValues to a new list instance.
originalStringValues
public List<String> originalStringValues()
Returns the original command line arguments matched by this option or positional parameter spec.
Returns:
the matched arguments as found on the command line: empty Strings for options without value, the
values have not been splitRegex.splitRegex, and for map properties values may look like "key=value"
resetOriginalStringValues
protected void resetOriginalStringValues()
Sets the originalStringValues to a new list instance.
internalShowDefaultValue
protected boolean internalShowDefaultValue(boolean usageHelpShowDefaults)
Returns whether the default for this option or positional parameter should be shown, potentially overriding the specified global setting.
Parameters:
usageHelpShowDefaults - whether the command's UsageMessageSpec is configured to show default values.
messages
public Messages messages()
Returns the Messages for this arg specification, or null.
Since:
3.6
messages
public ArgSpec messages(Messages msgs)
Sets the Messages for this ArgSpec, and returns this ArgSpec.
Parameters:
msgs - the new Messages value, may be null
Since:
3.6
See Also:
toString
public String toString()
Returns a string respresentation of this option or positional parameter.
equalsImpl
protected boolean equalsImpl(ArgSpec other)
hashCodeImpl
protected int hashCodeImpl()