Annotation Type CommandLine.Option
-
@Retention(RUNTIME) @Target(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"}, usageHelp = true, description = "Display this help and exit") private boolean help; @Option(names = { "-V", "--version"}, versionHelp = true, description = "Display version information and exit") private boolean version; }
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 this option, used when generating the usage documentation.boolean
help
Deprecated.UseusageHelp()
andversionHelp()
instead.boolean
hidden
Sethidden=true
if this option should not be included in the usage documentation.String
paramLabel
Specify aparamLabel
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
Optionally specify atype
to control exactly what Class the option parameter should be converted to.boolean
usageHelp
SetusageHelp=true
if this option allows the user to request usage help.boolean
versionHelp
SetversionHelp=true
if this option allows the user to request version information.
-
-
-
Element Detail
-
names
String[] names
One or more option names. At least one option name is required.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.- Returns:
- one or more option names
-
-
-
required
boolean required
Indicates whether this option is required. By default this is false. If an option is required, but a user invokes the program without specifying the required option, aCommandLine.MissingParameterException
is thrown from theCommandLine.parse(String...)
method.- Returns:
- whether this option is required
- Default:
- false
-
-
-
help
boolean help
Deprecated.Sethelp=true
if this option should disable validation of the remaining arguments: If thehelp
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.- Returns:
- whether this option disables validation of the other arguments
- Default:
- false
-
-
-
usageHelp
boolean usageHelp
SetusageHelp=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 theCommandLine.isUsageHelpRequested()
method will returntrue
.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.- Returns:
- whether this option allows the user to request usage help
- Since:
- 0.9.8
- Default:
- false
-
-
-
versionHelp
boolean versionHelp
SetversionHelp=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 theCommandLine.isVersionHelpRequested()
method will returntrue
.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.- Returns:
- whether this option allows the user to request version information
- Since:
- 0.9.8
- Default:
- false
-
-
-
description
String[] description
Description of this option, used when generating the usage documentation.- Returns:
- the description of this option
- Default:
- {}
-
-
-
arity
String arity
Specifies the minimum number of required parameters and the maximum number of accepted parameters. If an option declares a positive arity, and the user specifies an insufficient number of parameters on the command line, aCommandLine.MissingParameterException
is thrown by theCommandLine.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
A note on boolean options@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 aCommandLine.MissingParameterException
is thrown by theCommandLine.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
- Returns:
- how many arguments this option requires
- Default:
- ""
-
-
-
paramLabel
String paramLabel
Specify aparamLabel
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.
- Returns:
- name of the option parameter used in the usage help message
- Default:
- ""
-
-
-
type
Class<?>[] type
Optionally specify a
type
to control exactly what Class the option 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@Option(type=Short.class)
ensures that the option 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@Option(type=Short.class)
to ensure that option 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 option 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@Option(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@Option
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 option 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 option 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 option parameter values or
""
if the value should not be split - See Also:
String.split(String)
- Default:
- ""
-
-
hidden
boolean hidden
Sethidden=true
if this option should not be included in the usage documentation.- Returns:
- whether this option should be excluded from the usage message
- Default:
- false
-
-