@Retention(value=RUNTIME) @Target(value=FIELD) public static @interface CommandLine.Option
Annotate fields in your class with @Option
and picocli will initialize these fields when matching
arguments are specified on the command line.
For example:
import static picocli.CommandLine.*; public class MyClass { @Parameters(type = File.class, description = "Any number of input files") private List<File> files = new ArrayList<File>(); @Option(names = { "-o", "--out" }, description = "Output file (default: print to console)") private File outputFile; @Option(names = { "-v", "--verbose"}, description = "Verbosely list files processed") private boolean verbose; @Option(names = { "-h", "--help", "-?", "-help"}, help = true, description = "Display this help and exit") private boolean help; @Option(names = { "-V", "--version"}, help = true, description = "Display version information and exit") private boolean version; }
A field cannot be annotated with both @Parameters
and @Option
or a
ParameterException
is thrown.
Modifier and Type | Required Element and Description |
---|---|
String[] |
names
One or more option names.
|
Modifier and Type | Optional Element and Description |
---|---|
String |
arity
Specifies the minimum number of required parameters and the maximum number of accepted parameters.
|
String[] |
description
Description of this option, used when generating the usage documentation.
|
boolean |
help
Set
help=true if this option should disable validation of the remaining arguments:
If the help option is specified, no error message is generated for missing required options. |
boolean |
hidden
Set
hidden=true if this option should not be included in the usage documentation. |
String |
paramLabel
Specify a
paramLabel for the option parameter to be used in the usage help message. |
boolean |
required
Indicates whether this option is required.
|
String |
split
Specify a regular expression to use to split option parameter values before applying them to the field.
|
Class<?> |
type
Specify a
type if the annotated field is a Collection that should hold objects other than Strings. |
boolean |
usageHelp
Set
usageHelp=true if this option allows the user to request usage help. |
boolean |
versionHelp
Set
versionHelp=true if this option allows the user to request version information. |
public abstract String[] names
Different environments have different conventions for naming options, but usually options have a prefix
that sets them apart from parameters.
Picocli supports all of the below styles. The default separator is '='
, but this can be configured.
*nix
In Unix and Linux, options have a short (single-character) name, a long name or both.
Short options
(POSIX
style are single-character and are preceded by the '-'
character, e.g., `-v'
.
GNU-style long
(or mnemonic) options start with two dashes in a row, e.g., `--file'
.
Picocli supports the POSIX convention that short options can be grouped, with the last option
optionally taking a parameter, which may be attached to the option name or separated by a space or
a '='
character. The below examples are all equivalent:
-xvfFILE -xvf FILE -xvf=FILE -xv --file FILE -xv --file=FILE -x -v --file FILE -x -v --file=FILE
DOS
DOS options mostly have upper case single-character names and start with a single slash '/'
character.
Option parameters are separated by a ':'
character. Options cannot be grouped together but
must be specified separately. For example:
DIR /S /A:D /T:C
PowerShell
Windows PowerShell options generally are a word preceded by a single '-'
character, e.g., `-Help'
.
Option parameters are separated by a space or by a ':'
character.
public abstract boolean required
CommandLine.MissingParameterException
is thrown from the CommandLine.parse(String...)
method.public abstract boolean help
help=true
if this option should disable validation of the remaining arguments:
If the help
option is specified, no error message is generated for missing required options.
This attribute is useful for special options like help (-h
and --help
on unix,
-?
and -Help
on Windows) or version (-V
and --version
on unix,
-Version
on Windows).
Note that the CommandLine.parse(String...)
method will not print help documentation. It will only set
the value of the annotated field. It is the responsibility of the caller to inspect the annotated fields
and take the appropriate action.
public abstract boolean usageHelp
usageHelp=true
if this option allows the user to request usage help. If this option is
specified on the command line, picocli will not validate the remaining arguments (so no "missing required
option" errors) and the CommandLine.isUsageHelpRequested()
method will return true
.
This attribute is useful for special options like help (-h
and --help
on unix,
-?
and -Help
on Windows).
Note that the CommandLine.parse(String...)
method will not print usage help documentation. It will only set
the value of the annotated field. It is the responsibility of the caller to inspect the annotated fields
and take the appropriate action.
public abstract boolean versionHelp
versionHelp=true
if this option allows the user to request version information. If this option is
specified on the command line, picocli will not validate the remaining arguments (so no "missing required
option" errors) and the CommandLine.isVersionHelpRequested()
method will return true
.
This attribute is useful for special options like version (-V
and --version
on unix,
-Version
on Windows).
Note that the CommandLine.parse(String...)
method will not print version information. It will only set
the value of the annotated field. It is the responsibility of the caller to inspect the annotated fields
and take the appropriate action.
public abstract String[] description
public abstract String arity
CommandLine.MissingParameterException
is thrown by the CommandLine.parse(String...)
method.
In many cases picocli can deduce the number of required parameters from the field's type.
By default, flags (boolean options) have arity zero,
and single-valued type fields (String, int, Integer, double, Double, File, Date, etc) have arity one.
Generally, fields with types that cannot hold multiple values can omit the arity
attribute.
Fields used to capture options with arity two or higher should have a type that can hold multiple values,
like arrays or Collections. See type()
for strongly-typed Collection fields.
For example, if an option has 2 required parameters and any number of optional parameters,
specify @Option(names = "-example", arity = "2..*")
.
By default picocli does not expect boolean options (also called "flags" or "switches") to have a parameter.
You can make a boolean option take a required parameter by annotating your field with arity="1"
.
For example:
@Option(names = "-v", arity = "1") boolean verbose;
Because this boolean field is defined with arity 1, the user must specify either <program> -v false
or <program> -v true
on the command line, or a CommandLine.MissingParameterException
is thrown by the CommandLine.parse(String...)
method.
To make the boolean parameter possible but optional, define the field with arity = "0..1"
.
For example:
@Option(names="-v", arity="0..1") boolean verbose;
This will accept any of the below without throwing an exception:
-v -v true -v false
public abstract String paramLabel
paramLabel
for the option 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 { @Option(names = {"-o", "--output"}, paramLabel="FILE", description="path of the output file") private File out; @Option(names = {"-j", "--jobs"}, arity="0..1", description="Allow N jobs at once; infinite jobs with no arg.") private int maxJobs = -1; }
By default, the above gives a usage help message like the following:
Usage: <main class> [OPTIONS] -o, --output FILE path of the output file -j, --jobs [<maxJobs>] Allow N jobs at once; infinite jobs with no arg.
public abstract Class<?> type
Specify a type
if the annotated field is a Collection
that should hold objects other than Strings.
If the field's type is a Collection
, the generic type parameter of the collection is erased and
cannot be determined at runtime. Specify a type
attribute to store values other than String in
the Collection. Picocli will use the CommandLine.ITypeConverter
that is registered for that type to convert
the raw String values before they are added to the collection.
When the field's type is an array, the type
attribute is ignored: the values will be converted
to the array component type and the array will be replaced with a new instance containing both the old and
the new values.
public abstract String split
""
if the value should not be splitString.split(String)
Copyright © 1999-2018 The Apache Software Foundation. All Rights Reserved.
Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, the Apache Logging project logo, and the Apache Log4j logo are trademarks of The Apache Software Foundation.