Annotation Interface Option
This annotation can be placed on a field of type T or the method
of the form void
. Its access
modified can be anything, but if it's not public, your application
needs to run in a security context that allows args4j to access
the field/method (see methodName
(T value)AccessibleObject.setAccessible(boolean)
.
The behavior of the annotation differs depending on T --- the type of the field or the parameter of the method.
Boolean Switch
When T is boolean
, it represents
a boolean
option that takes the form of -OPT
. When this option is set,
the property will be set to true
.
String Switch
When T is String
, it represents
an option that takes one operand. The value of the operand is set
to the property.
Enum Switch
When T is derived from Enum
, it represents an option that takes
an operand, which must be one of the enum constant. The comparion between
the operand and the enum constant name is done in a case insensitive fashion.
For example, the following definition will represent command line options
like -coin penny
or -coin DIME
,
but things like -coin
or -coin abc
are errors.
enum Coin { PENNY,NICKEL,DIME,QUARTER } class Option { @Option(name="-coin") public Coin coin; }
File Switch
When T is a File
, it represents an option that takes a file/directory
name as an operand.
-
Required Element Summary
Required Elements -
Optional Element Summary
Optional ElementsModifier and TypeOptional ElementDescriptionString[]
Aliases for the options, such as--long-option-name
.String[]
List of other options that this option depends on.String[]
List of other options that this option is incompatible with..Class<? extends OptionHandler>
Specify theOptionHandler
that processes the command line arguments.boolean
Specify that the option is a help option.boolean
Specify that the option is hidden from the usage, by default.When the option takes an operand, the usage screen will show something like thisboolean
Specify that the option is mandatory.Help string used to display the usage screen.
-
Element Details
-
name
String nameName of the option, such as-foo
or-bar
.
-
-
-
aliases
String[] aliasesAliases for the options, such as--long-option-name
.- Default:
- {}
-
usage
String usageHelp string used to display the usage screen.This parameter works in two ways. For a simple use, you can just encode the human-readable help string directly, and that will be used as the message. This is easier, but it doesn't support localization.
For more advanced use, this property is set to a key of a
ResourceBundle
. The actual message is obtained by querying aResourceBundle
instance supplied toCmdLineParser
by this key. This allows the usage screen to be properly localized.If this value is empty, the option will not be displayed in the usage screen.
- Default:
- ""
-
metaVar
String metaVarWhen the option takes an operand, the usage screen will show something like this-x FOO : blah blah blah
You can replace theFOO
token by using this parameter.If left unspecified, this value is infered from the type of the option.
Just like
usage()
, normally, this value is printed as is. But if aResourceBundle
is given to theCmdLineParser
, it will be used to obtain the locale-specific value.- Default:
- ""
-
required
boolean requiredSpecify that the option is mandatory.At the end of
CmdLineParser.parseArgument(String...)
, aCmdLineException
will be thrown if a required option is not present.Note that in most of the command line interface design principles, options should be really optional. So use caution when using this flag.
- Default:
- false
-
help
boolean helpSpecify that the option is a help option.When flagging an option being the help option, required arguments or options that are missing in an actual command line don't cause an exception to be thrown.
- See Also:
- Default:
- false
-
handler
Class<? extends OptionHandler> handlerSpecify theOptionHandler
that processes the command line arguments.The default value
OptionHandler
indicates that theOptionHandler
will be infered from the type of the field/method where aOption
annotation is placed.If this annotation element is used, it overrides the inference and determines the handler to be used. This is convenient for defining a non-standard option parsing semantics.
Example
// this is a normal "-r" option @Option(name="-r") boolean value; // this causes arg4j to use MyHandler, not the default // handler provided for boolean @Option(name="-b",handler=MyHandler.class) boolean value;
- Default:
- org.kohsuke.args4j.spi.OptionHandler.class
-
depends
String[] dependsList of other options that this option depends on.Example
@Option(name="-a") int a; //-b is not required but if it's provided, then a becomes required @Option(name="-b", depends={"-a"}) int b;
At the end of
CmdLineParser.parseArgument(String...)
, aCmdLineException
will be thrown if options required by another one are not present.- Default:
- {}
-
forbids
String[] forbidsList of other options that this option is incompatible with..Example
@Option(name="-a") int a; // -h and -a cannot be specified together @Option(name="-h", forbids={"-a"}) boolean h;
At the end of
CmdLineParser.parseArgument(String...)
, aCmdLineException
will be thrown if forbidden option combinations are present.- Default:
- {}
-