@Retention(value=RUNTIME) @Target(value={FIELD,METHOD,PARAMETER}) public @interface Option
This annotation can be placed on a field of type T or the method
of the form void methodName(T value). 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 AccessibleObject.setAccessible(boolean)
.
The behavior of the annotation differs depending on T --- the type of the field or the parameter of the method.
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.
When T is String
, it represents
an option that takes one operand. The value of the operand is set
to the property.
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; }
When T is a File
, it represents an option that takes a file/directory
name as an operand.
Modifier and Type | Required Element and Description |
---|---|
String |
name
Name of the option, such as "-foo" or "-bar".
|
Modifier and Type | Optional Element and Description |
---|---|
String[] |
aliases
Aliases for the options, such as "--long-option-name".
|
Class<? extends OptionHandler> |
handler
Specify the
OptionHandler that processes the command line arguments. |
String |
metaVar
When the option takes an operand, the usage screen will show something like this:
|
boolean |
multiValued
Whether the option is multi-valued.
|
boolean |
required
Specify that the option is mandatory.
|
String |
usage
Help string used to display the usage screen.
|
public abstract String name
public abstract String[] aliases
public abstract String usage
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 a ResourceBundle
instance supplied to
CmdLineParser
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.
public abstract String metaVar
-x FOO : blah blah blahYou can replace the 'FOO' token by using this parameter.
If left unspecifiied, this value is infered from the type of the option.
Just like usage()
, normally, this value is printed as is.
But if a ResourceBundle
is given to the CmdLineParser
,
it will be used to obtain the locale-specific value.
public abstract boolean required
At the end of CmdLineParser.parseArgument(String...)
,
a CmdLineException
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.
public abstract Class<? extends OptionHandler> handler
OptionHandler
that processes the command line arguments.
The default value OptionHandler
indicates that
the OptionHandler
will be infered from
the type of the field/method where a Option
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.
// 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;
public abstract boolean multiValued
Copyright © 2003-2017 Kohsuke Kawaguchi. All Rights Reserved.