@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD,PARAMETER})
public static @interface CommandLine.Parameters
Fields annotated with @Parameters
will be initialized with positional parameters. By specifying the
index()
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 @Parameters
and @Option
or a ParameterException
is thrown.
Modifier and Type | Optional Element and Description |
---|---|
java.lang.String |
arity
Specifies the minimum number of required parameters and the maximum number of accepted parameters.
|
java.lang.Class<? extends java.lang.Iterable<java.lang.String>> |
completionCandidates
Use this attribute to specify an
Iterable<String> class that generates completion candidates for
this positional parameter. |
java.lang.Class<? extends CommandLine.ITypeConverter<?>>[] |
converter
Optionally specify one or more
CommandLine.ITypeConverter classes to use to convert the command line argument into
a strongly typed value (or key-value pair for map fields). |
java.lang.String |
defaultValue
Returns the default value of this positional parameter, before splitting and type conversion.
|
java.lang.String[] |
description
Description of the parameter(s), used when generating the usage documentation.
|
java.lang.String |
descriptionKey
ResourceBundle key for this option.
|
boolean |
hidden
Set
hidden=true if this parameter should not be included in the usage message. |
boolean |
hideParamSyntax
Returns whether usage syntax decorations around the paramLabel should be suppressed.
|
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.
|
boolean |
interactive
Set
interactive=true if this positional parameter will prompt the end user for a value (like a password). |
java.lang.String |
paramLabel
Specify a
paramLabel for the parameter to be used in the usage help message. |
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.
|
java.lang.String |
split
Specify a regular expression to use to split positional parameter values before applying them to the field.
|
java.lang.Class<?>[] |
type
Optionally specify a
type to control exactly what Class the positional parameter should be converted
to. |
public abstract java.lang.String index
public abstract java.lang.String[] description
May contain embedded format specifiers like %n
line 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's showDefaultValues
setting or the positional parameter's showDefaultValue
setting.
The string ${COMPLETION-CANDIDATES}
is replaced with the completion candidates generated by
completionCandidates()
in the description for this positional parameter.
Also, embedded %n
newline markers are converted to actual newlines.
public abstract java.lang.String arity
CommandLine.MissingParameterException
is thrown by the CommandLine.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.
public abstract java.lang.String paramLabel
paramLabel
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)
public abstract boolean hideParamSyntax
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.public abstract java.lang.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 type java.lang.Number
, and annotating @Parameters(type=Short.class)
ensures that the positional parameter value is converted to a Short
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 to Short
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 for Collection
and Map
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 type Map<TimeUnit, Long>
picocli will know the positional parameter
should be split up in key=value pairs, where the key should be converted to a java.util.concurrent.TimeUnit
enum value, and the value should be converted to a Long
. 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 explicit type
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.
public abstract java.lang.Class<? extends CommandLine.ITypeConverter<?>>[] converter
CommandLine.ITypeConverter
classes 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.Types
to the int
value of these constants, but any other int
fields should
not be affected by this and should continue to use the standard int converter that parses numeric values.
CommandLine.registerConverter(Class, ITypeConverter)
public abstract java.lang.String split
""
if the value should not be splitString.split(String)
public abstract boolean hidden
hidden=true
if this parameter should not be included in the usage message.public abstract java.lang.String defaultValue
public abstract CommandLine.Help.Visibility showDefaultValue
CommandLine.Command.showDefaultValues()
is set true
on 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 anywhere in the description that ignores this setting.
public abstract java.lang.Class<? extends java.lang.Iterable<java.lang.String>> completionCandidates
Iterable<String>
class that generates completion candidates for
this positional parameter. For map fields, completion candidates should be in key=value
form.
Completion candidates are used in bash completion scripts generated by the picocli.AutoComplete
class.
Unfortunately, picocli.AutoComplete
is not very good yet at generating completions for positional parameters.
CommandLine.IFactory
public abstract boolean interactive
interactive=true
if 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, this will use the Console.readPassword()
API to get a value without echoing input to the console.public abstract java.lang.String descriptionKey
paramLabel() + "[" + index() + "]"
as key.CommandLine.Model.PositionalParamSpec.description()