@Retention(value=RUNTIME) @Target(value={FIELD,METHOD,PARAMETER}) public static @interface CommandLine.ArgGroup
Command may define one or more ArgGroups: a group of options, positional parameters or a mixture of the two.
Groups can be used to:
exclusive attribute.
Picocli will throw a CommandLine.MutuallyExclusiveArgsException if the command line contains multiple arguments that are mutually exclusive.exclusive = false
to define a group of options and positional parameters that must always be specified together.
Picocli will throw a MissingParameterException if not all the options and positional parameters in a co-occurring group are specified together.heading (which may come from a resource bundle).
Groups without a heading are only used for validation.
Set validate = false for groups whose purpose is only to customize the usage help message.Groups may be optional (multiplicity = "0..1"), required (multiplicity = "1"), or repeating groups (multiplicity = "0..*" or multiplicity = "1..*").
For a group of mutually exclusive arguments, making the group required means that one of the arguments in the group must appear on the command line, or a MissingParameterException is thrown.
For a group of co-occurring arguments, all arguments in the group must appear on the command line.
Groups can be composed for validation purposes:
Below is an example of an ArgGroup defining a set of dependent options that must occur together.
All options are required within the group, while the group itself is optional:
public class DependentOptions {
@ArgGroup(exclusive = false, multiplicity = "0..1")
Dependent group;
static class Dependent {
@Option(names = "-a", required = true) int a;
@Option(names = "-b", required = true) int b;
@Option(names = "-c", required = true) int c;
}
}CommandLine.Model.ArgGroupSpec| Modifier and Type | Optional Element and Description |
|---|---|
boolean |
exclusive
Determines whether this is a mutually exclusive group;
true by default. |
String |
heading
The heading of this group, used when generating the usage documentation.
|
String |
headingKey
ResourceBundle key for this group's usage help message section heading.
|
String |
multiplicity
Determines how often this group can be specified on the command line;
"0..1" (optional) by default. |
int |
order
Determines the position in the options list in the usage help message at which this group should be shown.
|
boolean |
validate
Determines whether picocli should validate the rules of this group (
true by default). |
public abstract String heading
heading nor a headingKey are specified,
this group is used for validation only and does not change the usage help message.public abstract String headingKey
heading nor a headingKey are specified,
this group is used for validation only and does not change the usage help message.public abstract boolean exclusive
true by default.
If false, this is a co-occurring group. Ignored if validate() is false.public abstract String multiplicity
"0..1" (optional) by default.
For a group of mutually exclusive arguments, making the group required multiplicity = "1" means that
one of the arguments in the group must appear on the command line, or a MissingParameterException is thrown.
For a group of co-occurring arguments, making the group required means that all arguments in the group must appear on the command line.
Ignored if validate() is false.public abstract boolean validate
true by default).
For a mutually exclusive group validation means verifying that no more than one elements of the group is specified on the command line;
for a co-ocurring group validation means verifying that all elements of the group are specified on the command line.
Set validate = false for groups whose purpose is only to customize the usage help message.multiplicity(),
heading()public abstract int order
heading (or a headingKey with a non-null resource bundle value).