Annotation Type CommandLine.Parameters
- Enclosing class:
- CommandLine
Fields annotated with @Parameters
will be initialized with positional parameters. By specifying the
index()
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 a ParameterException
is thrown.
-
Optional Element Summary
Optional ElementsModifier and TypeOptional ElementDescriptionSpecifies the minimum number of required parameters and the maximum number of accepted parameters.String[]
Description of the parameter(s), used when generating the usage documentation.boolean
Sethidden=true
if this parameter should not be included in the usage message.Specify an index ("0", or "1", etc.) to pick which of the command line arguments should be assigned to this field.Specify aparamLabel
for the parameter to be used in the usage help message.Specify a regular expression to use to split positional parameter values before applying them to the field.Class<?>[]
Optionally specify atype
to control exactly what Class the positional parameter should be converted to.
-
Element Details
-
index
String indexSpecify 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[] descriptionDescription of the parameter(s), used when generating the usage documentation.- Returns:
- the description of the parameter(s)
- Default:
- {}
-
arity
String aritySpecifies 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 paramLabelSpecify 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<?>[] typeOptionally 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 splitSpecify 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:
- Default:
- ""
-