Annotation Type CommandLine.Parameters
-
@Retention(RUNTIME) @Target(FIELD) public static @interface CommandLine.Parameters
Fields annotated with
@Parameters
will be initialized with positional parameters. By specifying theindex()
attribute you can pick which (or what range) of the positional parameters to apply. If no index is specified, the field will get all positional parameters (so it should be an array or a collection).When parsing the command line arguments, picocli first tries to match arguments to
Options
. Positional parameters are the arguments that follow the options, or the arguments that follow a "--" (double dash) argument on the command line.For example:
import static picocli.CommandLine.*; public class MyCalcParameters { @Parameters(type = BigDecimal.class, description = "Any number of input numbers") private List<BigDecimal> files = new ArrayList<BigDecimal>(); @Option(names = { "-h", "--help", "-?", "-help"}, help = true, description = "Display this help and exit") private boolean help; }
A field cannot be annotated with both
@Parameters
and@Option
or aParameterException
is thrown.
-
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description String
arity
Specifies the minimum number of required parameters and the maximum number of accepted parameters.String[]
description
Description of the parameter(s), used when generating the usage documentation.boolean
hidden
Sethidden=true
if this parameter should not be included in the usage message.String
index
Specify an index ("0", or "1", etc.) to pick which of the command line arguments should be assigned to this field.String
paramLabel
Specify aparamLabel
for the parameter to be used in the usage help message.String
split
Specify a regular expression to use to split positional parameter values before applying them to the field.Class<?>[]
type
Optionally specify atype
to control exactly what Class the positional parameter should be converted to.
-
-
-
Element Detail
-
index
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
String[] description
Description of the parameter(s), used when generating the usage documentation.- Returns:
- the description of the parameter(s)
- Default:
- {}
-
-
-
arity
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.MissingParameterException
is 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.
- Returns:
- the range of minimum and maximum parameters accepted by this command
- Default:
- ""
-
-
-
paramLabel
String paramLabel
Specify aparamLabel
for 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:
- ""
-
-
-
type
Class<?>[] type
Optionally specify a
type
to 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 aShort
before 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 toShort
before adding an element to the array.Picocli will use the
CommandLine.ITypeConverter
that is registered for the specified type to convert the raw String values before modifying the field value.Prior to 2.0, the
type
attribute was necessary forCollection
andMap
fields, 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.TimeUnit
enum 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@Parameters
annotation specifies an explicittype
attribute.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
type
attribute to control the Class that the positional parameter should be converted to.- Returns:
- the type(s) to convert the raw String values
- Default:
- {}
-
-
-
split
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. Ignored for single-value fields.- 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=true
if this parameter should not be included in the usage message.- Returns:
- whether this parameter should be excluded from the usage message
- Default:
- false
-
-