ArgsOptionParser
public
class
ArgsOptionParser
extends OptionSetter
Populates Option
fields from parsed command line arguments.
Strings in the passed-in String[] are parsed left-to-right. Each String is classified as a short
option (such as "-v"), a long option (such as "--verbose"), an argument to an option (such as
"out.txt" in "-f out.txt"), or a non-option positional argument.
Each option argument must map to one or more
Option
fields. A long option maps to the
Option
name, and a short option maps to
Option
short name. Each option name and
option short name must be unique with respect to all other
Option
fields within the same object.
A single option argument can get mapped to multiple
Option
fields with the same name
across multiple objects.
Option
arguments can be namespaced to uniquely refer to an
Option
field within a single object using that object's full class name or its
OptionClass
alias value separated by ':'. ie
--classname:optionname optionvalue or
--optionclassalias:optionname optionvalue.
A simple short option is a "-" followed by a short option character. If the option requires an
argument (which is true of any non-boolean option), it may be written as a separate parameter,
but need not be. That is, "-f out.txt" and "-fout.txt" are both acceptable.
It is possible to specify multiple short options after a single "-" as long as all (except
possibly the last) do not require arguments.
A long option begins with "--" followed by several characters. If the option requires an
argument, it may be written directly after the option name, separated by "=", or as the next
argument. (That is, "--file=out.txt" or "--file out.txt".)
A boolean long option '--name' automatically gets a '--no-name' companion. Given an option
"--flag", then, "--flag", "--no-flag", "--flag=true" and "--flag=false" are all valid, though
neither "--flag true" nor "--flag false" are allowed (since "--flag" by itself is sufficient, the
following "true" or "false" is interpreted separately). You can use "yes" and "no" as synonyms
for "true" and "false".
Each String not starting with a "-" and not a required argument of a previous option is a
non-option positional argument, as are all successive Strings. Each String after a "--" is a
non-option positional argument.
The fields corresponding to options are updated as their options are processed. Any remaining
positional arguments are returned as a List<String>.
Here's a simple example:
// Non-@Option fields will be ignored.
class Options {
@Option(name = "quiet", shortName = 'q')
boolean quiet = false;
// Here the user can use --no-color.
@Option(name = "color")
boolean color = true;
@Option(name = "mode", shortName = 'm')
String mode = "standard; // Supply a default just by setting the field.
@Option(name = "port", shortName = 'p')
int portNumber = 8888;
// There's no need to offer a short name for rarely-used options.
@Option(name = "timeout" )
double timeout = 1.0;
@Option(name = "output-file", shortName = 'o' })
File output;
// Multiple options are added to the collection.
// The collection field itself must be non-null.
@Option(name = "input-file", shortName = 'i')
List<File> inputs = new ArrayList<File>();
}
Options options = new Options();
List<String> posArgs = new OptionParser(options).parse("--input-file", "/tmp/file1.txt");
for (File inputFile : options.inputs) {
if (!options.quiet) {
...
}
...
}
See also:
- the getopt(1) man page
- Python's "optparse" module (http://docs.python.org/library/optparse.html)
- the POSIX "Utility Syntax Guidelines"
(http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap12.html#tag_12_02)
- the GNU "Standards for Command Line Interfaces"
(http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces)
Summary
Public constructors
ArgsOptionParser
public ArgsOptionParser ( optionSources)
Creates a ArgsOptionParser
for a collection of objects.
Parameters |
optionSources |
: the config objects. |
Throws |
ConfigurationException |
if config objects is improperly configured.
|
ArgsOptionParser
public ArgsOptionParser (Object... optionSources)
Creates a ArgsOptionParser
for one or more objects.
Parameters |
optionSources |
Object : the config objects. |
Throws |
ConfigurationException |
if config objects is improperly configured.
|
Public methods
getOptionHelp
public static String getOptionHelp (boolean importantOnly,
Object optionObject)
Output help text for all Option
fields in optionObject.
The help text for each option will be in the following format
[-option_shortname, --option_name] [option_description] Default:
[current option field's value in optionObject]
The 'Default..." text will be omitted if the option field is null or empty.
Parameters |
importantOnly |
boolean : if true only print help for the important options |
optionObject |
Object : the object to print help text for |
Returns |
String |
a String containing user-friendly help text for all Option fields
|
parse
public parse (String... args)
Parses the command-line arguments 'args', setting the @Option fields of the 'optionSource'
provided to the constructor.
Returns |
|
a ERROR(/List) of the positional arguments left over after processing all options. |
Throws |
ConfigurationException |
if error occurred parsing the arguments.
|
parse
public parse ( args)
Alternate parse(String)
method that takes a ERROR(/List)
of arguments
Returns |
|
a ERROR(/List) of the positional arguments left over after processing all options. |
Throws |
ConfigurationException |
if error occurred parsing the arguments.
|
parseBestEffort
public parseBestEffort ( args,
boolean forceContinue)
Alternate parseBestEffort(String)
method that takes a ERROR(/List)
of
arguments, and can be forced to continue parsing until the end, even if some args do not
parse.
Parameters |
args |
: list that will contain the left over args. |
forceContinue |
boolean : True if it should continue to parse even if some args do not parse. |
parseBestEffort
public parseBestEffort (String... args)
A best-effort version of parse(String)
. If a ConfigurationException is
thrown, that exception is captured internally, and the remaining arguments (including the
argument which caused the exception to be thrown) are returned. This method does not throw.
validateMandatoryOptions
public void validateMandatoryOptions ()
Validates that all fields marked as mandatory have been set.
Throws |
ConfigurationException |
|