Annotation Type CommandLine.Parameters
-
@Retention(RUNTIME) @Target({FIELD,METHOD,PARAMETER}) public static @interface CommandLine.ParametersFields annotated with
@Parameterswill be initialized with positional parameters. By specifying theindex()attribute you can pick the exact position or a range of positional parameters to apply. If no index is specified, the field will get all positional parameters (and so it should be an array or a collection).In the case of command methods (annotated with
@Command), method parameters may be annotated with@Parameters, but are are considered positional parameters by default, unless they are annotated with@Option.Command class example:
import static picocli.CommandLine.*; public class MyCalcParameters { @Parameters(description = "Any number of input numbers") private List<BigDecimal> files = new ArrayList<BigDecimal>(); @Option(names = { "-h", "--help" }, usageHelp = true, description = "Display this help and exit") private boolean help; }A field cannot be annotated with both
@Parametersand@Optionor aParameterExceptionis thrown.
-
-
Field Summary
Fields Modifier and Type Fields Description static java.lang.StringNULL_VALUESpecial value that can be used in some annotation attributes to designatenull.
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description java.lang.StringaritySpecifies the minimum number of required parameters and the maximum number of accepted parameters.java.lang.Class<? extends java.lang.Iterable<java.lang.String>>completionCandidatesUse this attribute to specify anIterable<String>class that generates completion candidates for this positional parameter.java.lang.Class<? extends CommandLine.ITypeConverter<?>>[]converterOptionally specify one or moreCommandLine.ITypeConverterclasses to use to convert the command line argument into a strongly typed value (or key-value pair for map fields).java.lang.StringdefaultValueReturns the default value of this positional parameter, before splitting and type conversion.java.lang.String[]descriptionDescription of the parameter(s), used when generating the usage documentation.java.lang.StringdescriptionKeyResourceBundle key for this option.booleanechoUse this attribute to control whether user input for an interactive positional parameter is echoed to the console or not.booleanhiddenSethidden=trueif this parameter should not be included in the usage message.booleanhideParamSyntaxReturns whether usage syntax decorations around the paramLabel should be suppressed.java.lang.StringindexSpecify an index ("0", or "1", etc.) to pick which of the command line arguments should be assigned to this field.booleaninteractiveSetinteractive=trueif this positional parameter will prompt the end user for a value (like a password).java.lang.StringmapFallbackValueFor positional parameters of type Map, setting themapFallbackValueto any value allows end user to specify key-only parameters for this parameter.java.lang.Class<? extends CommandLine.IParameterConsumer>parameterConsumerOptionally specify a customIParameterConsumerto temporarily suspend picocli's parsing logic and process one or more command line arguments in a custom manner.java.lang.StringparamLabelSpecify aparamLabelfor the parameter to be used in the usage help message.java.lang.Class<? extends CommandLine.IParameterPreprocessor>preprocessorReturns the preprocessor for this positional parameter.java.lang.StringpromptUse this attribute to customize the text displayed to the end user for an interactive positional parameter when asking for user input.CommandLine.ScopeTypescopeDetermines on which command(s) this positional parameter exists: on this command only (the default), or whether this is a "global" parameter that is applied to this command and all subcommands, sub-subcommands, etc.CommandLine.Help.VisibilityshowDefaultValueUse this attribute to control for a specific positional parameter whether its default value should be shown in the usage help message.java.lang.StringsplitSpecify a regular expression to use to split positional parameter values before applying them to the field.java.lang.StringsplitSynopsisLabelSpecify a string to show the split option parameter values in usagejava.lang.Class<?>[]typeOptionally specify atypeto control exactly what Class the positional parameter should be converted to.
-
-
-
Field Detail
-
NULL_VALUE
static final java.lang.String NULL_VALUE
Special value that can be used in some annotation attributes to designatenull.- Since:
- 4.6
- See Also:
defaultValue(),mapFallbackValue()
-
-
Element Detail
-
index
java.lang.String index
Specify an index ("0", or "1", etc.) to pick which of the command line arguments should be assigned to this field. For array or Collection fields, you can also specify an index range ("0..3", or "2..*", etc.) to assign a subset of the command line arguments to this field. The default is "*", meaning all command line arguments.- Returns:
- an index or range specifying which of the command line arguments should be assigned to this field
- Default:
- ""
-
-
-
description
java.lang.String[] description
Description of the parameter(s), used when generating the usage documentation. Each element of the array is rendered on a separate line.May contain embedded format specifiers like
%nline separators. Literal percent'%'characters must be escaped with another%.The description may contain variables that are rendered when help is requested. The string
${DEFAULT-VALUE}is replaced with the default value of the positional parameter. This is regardless of the command'sshowDefaultValuessetting or the positional parameter'sshowDefaultValuesetting. The string${COMPLETION-CANDIDATES}is replaced with the completion candidates generated bycompletionCandidates()in the description for this positional parameter. Also, embedded%nnewline markers are converted to actual newlines.- Returns:
- the description of the parameter(s)
- See Also:
- Variable Interpolation section of the user manual
- Default:
- {}
-
-
-
arity
java.lang.String arity
Specifies the minimum number of required parameters and the maximum number of accepted parameters. If a positive arity is declared, and the user specifies an insufficient number of parameters on the command line,CommandLine.MissingParameterExceptionis thrown by theCommandLine.parse(String...)method.The default depends on the type of the parameter: booleans require no parameters, arrays and Collections accept zero to any number of parameters, and any other type accepts one parameter.
For single-value parameters, setting
arity = "0..1"makes a positional parameter optional, while settingarity = "1"makes it required.Required parameters that are part of a group are required within the group, not required within the command: the group's multiplicity determines whether the group itself is required or optional.
- Returns:
- the range of minimum and maximum parameters accepted by this command
- Default:
- ""
-
-
-
paramLabel
java.lang.String paramLabel
Specify aparamLabelfor the parameter to be used in the usage help message. If omitted, picocli uses the field name in fish brackets ('<'and'>') by default. Example:class Example { @Parameters(paramLabel="FILE", description="path of the input FILE(s)") private File[] inputFiles; }By default, the above gives a usage help message like the following:
Usage: <main class> [FILE...] [FILE...] path of the input FILE(s)
- Returns:
- name of the positional parameter used in the usage help message
- Default:
- ""
-
-
-
hideParamSyntax
boolean hideParamSyntax
Returns whether usage syntax decorations around the paramLabel should be suppressed. The default isfalse: 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
- Default:
- false
-
-
-
type
java.lang.Class<?>[] type
Optionally specify a
typeto control exactly what Class the positional parameter should be converted to. This may be useful when the field type is an interface or an abstract class. For example, a field can be declared to have typejava.lang.Number, and annotating@Parameters(type=Short.class)ensures that the positional parameter value is converted to aShortbefore setting the field value.For array fields whose component type is an interface or abstract class, specify the concrete component type. For example, a field with type
Number[]may be annotated with@Parameters(type=Short.class)to ensure that positional parameter values are converted toShortbefore adding an element to the array.Picocli will use the
CommandLine.ITypeConverterthat is registered for the specified type to convert the raw String values before modifying the field value.Prior to 2.0, the
typeattribute was necessary forCollectionandMapfields, but starting from 2.0 picocli will infer the component type from the generic type's type arguments. For example, for a field of typeMap<TimeUnit, Long>picocli will know the positional parameter should be split up in key=value pairs, where the key should be converted to ajava.util.concurrent.TimeUnitenum value, and the value should be converted to aLong. No@Parameters(type=...)type attribute is required for this. For generic types with wildcards, picocli will take the specified upper or lower bound as the Class to convert to, unless the@Parametersannotation specifies an explicittypeattribute.If the field type is a raw collection or a raw map, and you want it to contain other values than Strings, or if the generic type's type arguments are interfaces or abstract classes, you may specify a
typeattribute to control the Class that the positional parameter should be converted to.- Returns:
- the type(s) to convert the raw String values
- Default:
- {}
-
-
-
converter
java.lang.Class<? extends CommandLine.ITypeConverter<?>>[] converter
Optionally specify one or moreCommandLine.ITypeConverterclasses 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 field should use a custom conversion that is different from the normal conversion for the field's type.For example, for a specific field you may want to use a converter that maps the constant names defined in
java.sql.Typesto theintvalue of these constants, but any otherintfields should not be affected by this and should continue to use the standard int converter that parses numeric values.- Returns:
- the type converter(s) to use to convert String values to strongly typed values for this field
- See Also:
CommandLine.registerConverter(Class, ITypeConverter)
- Default:
- {}
-
-
-
split
java.lang.String split
Specify a regular expression to use to split positional parameter values before applying them to the field. All elements resulting from the split are added to the array or Collection. Previously ignored for single-value fields, from picocli 4.0 asplitregex can only be specified on multi-value options and positional parameters.- Returns:
- a regular expression to split operand values or
""if the value should not be split - See Also:
String.split(String)
- Default:
- ""
-
-
-
hidden
boolean hidden
Sethidden=trueif this parameter should not be included in the usage message.- Returns:
- whether this parameter should be excluded from the usage message
- Default:
- false
-
-
-
defaultValue
java.lang.String defaultValue
Returns the default value of this positional parameter, before splitting and type conversion.To get a
nulldefault value, omit specifying a default value or use the special valueNULL_VALUE- for positional parameters of typeOptional<T>that will result in theOptional.empty()value being assigned when the positional parameters is not specified on the command line.- Returns:
- a String that (after type conversion) will be used as the value for this positional parameter if no value was specified on the command line
- Since:
- 3.2
- Default:
- "__no_default_value__"
-
-
-
showDefaultValue
CommandLine.Help.Visibility showDefaultValue
Use this attribute to control for a specific positional parameter whether its default value should be shown in the usage help message. If not specified, the default value is only shown when theCommandLine.Command.showDefaultValues()is settrueon the command. Use this attribute to specify whether the default value for this specific positional parameter should always be shown or never be shown, regardless of the command setting.Note that picocli 3.2 allows embedding default values by specifying the variable
${DEFAULT-VALUE}anywhere in the description that ignores this setting.- Returns:
- whether this positional parameter's default value should be shown in the usage help message
- Default:
- picocli.CommandLine.Help.Visibility.ON_DEMAND
-
-
-
completionCandidates
java.lang.Class<? extends java.lang.Iterable<java.lang.String>> completionCandidates
Use this attribute to specify anIterable<String>class that generates completion candidates for this positional parameter. For map fields, completion candidates should be inkey=valueform.Completion candidates are used in bash completion scripts generated by the
picocli.AutoCompleteclass. Unfortunately,picocli.AutoCompleteis not very good yet at generating completions for positional parameters.- Returns:
- a class whose instances can iterate over the completion candidates for this positional parameter
- Since:
- 3.2
- See Also:
CommandLine.IFactory
- Default:
- picocli.CommandLine.NoCompletionCandidates.class
-
-
-
interactive
boolean interactive
Setinteractive=trueif this positional parameter will prompt the end user for a value (like a password). Only supported for single-value positional parameters (not arrays, collections or maps). When running on Java 6 or greater andecho = false(the default), this will use theConsole.readPassword()API to get a value without echoing input to the console, otherwise it will simply read a value fromSystem.in.- Returns:
- whether this positional parameter prompts the end user for a value to be entered on the command line
- Since:
- 3.5
- Default:
- false
-
-
-
echo
boolean echo
Use this attribute to control whether user input for an interactive positional parameter is echoed to the console or not. Ifecho = true, the user input is echoed to the console. This attribute is ignored wheninteractive = false(the default).- Returns:
- whether the user input for an interactive positional parameter should be echoed to the console or not
- Since:
- 4.6
- See Also:
CommandLine.Model.ArgSpec.echo()
- Default:
- false
-
-
-
prompt
java.lang.String prompt
Use this attribute to customize the text displayed to the end user for an interactive positional parameter when asking for user input. When omitted, the displayed text is derived from the positional parameter's position (index) and the first description line. This attribute is ignored wheninteractive = false(the default).- Returns:
- the text to display to the end user for an interactive positional parameter when asking for user input
- Since:
- 4.6
- See Also:
CommandLine.Model.ArgSpec.prompt()
- Default:
- ""
-
-
-
descriptionKey
java.lang.String descriptionKey
ResourceBundle key for this option. If not specified, (and a ResourceBundle exists for this command) an attempt is made to find the positional parameter description usingparamLabel() + "[" + index() + "]"as key.- Since:
- 3.6
- See Also:
CommandLine.Model.ArgSpec.description()
- Default:
- ""
-
-
-
scope
CommandLine.ScopeType scope
Determines on which command(s) this positional parameter exists: on this command only (the default), or whether this is a "global" parameter that is applied to this command and all subcommands, sub-subcommands, etc.- Since:
- 4.3
- Default:
- picocli.CommandLine.ScopeType.LOCAL
-
-
-
parameterConsumer
java.lang.Class<? extends CommandLine.IParameterConsumer> parameterConsumer
Optionally specify a customIParameterConsumerto temporarily suspend picocli's parsing logic and process one or more command line arguments in a custom manner.- Since:
- 4.0
- Default:
- picocli.CommandLine.NullParameterConsumer.class
-
-
-
mapFallbackValue
java.lang.String mapFallbackValue
For positional parameters of type Map, setting themapFallbackValueto any value allows end user to specify key-only parameters for this parameter. For example,keyinstead ofkey=value.The value specified in this annotation is the value that is put into the Map for the user-specified key. Use the special value
NULL_VALUEto specifynull- for maps of typeMap<K, Optional<V>>that will result inOptional.empty()values in the map when only the key is specified.If no
mapFallbackValueis set, key-only Map parameters like-Dkeyare considered invalid user input and cause aCommandLine.ParameterExceptionto be thrown.- Since:
- 4.6
- See Also:
CommandLine.Model.ArgSpec.mapFallbackValue()
- Default:
- "__unspecified__"
-
-
-
preprocessor
java.lang.Class<? extends CommandLine.IParameterPreprocessor> preprocessor
Returns the preprocessor for this positional parameter.- Since:
- 4.6
- See Also:
CommandLine.IParameterPreprocessor
- Default:
- picocli.CommandLine.NoOpParameterPreprocessor.class
-
-