public class OptionParser extends Object implements OptionDeclarer
Parses command line arguments, using a syntax that attempts to take from the best of POSIX getopt()
and GNU getopt_long().
This parser supports short options and long options.
-") followed by a single letter or digit,
or question mark ("?"), or dot ("."), or underscore ("_").-d /tmp-d/tmp"="), as in -d=/tmp-d /tmp -d /var -d /opt; or, when using the
"separated values" clause of the "fluent
interface" (see below), give multiple values separated by a given character as a single argument to the
option.-abc is treated as -a -b -c. If a short option
in the cluster can accept an argument, the remaining characters are interpreted as the argument for that
option."--") signals that the remaining arguments are to be
treated as non-options."--"), followed by multiple letters, digits,
hyphens, question marks, or dots. A hyphen cannot be the first character of a long option specification when
configuring the parser.--directory /tmp"="), as in
--directory=/tmp
"-") instead of a double hyphen ("--") for a long
option.-W is reserved. If you tell the parser to recognize alternative long options, then it will treat, for example,
-W foo=bar as the long option foo with argument bar, as though you had written
--foo=bar.-W as a valid short option, or use it as an abbreviation for a long option, but
recognizing alternative long options will always supersede
this behavior.Number, then that argument is treated as the
negative number argument of the option, even if the parser recognizes the corresponding numeric option.
For example:
OptionParser parser = new OptionParser();
parser.accepts( "a" ).withOptionalArg().ofType( Integer.class );
parser.accepts( "2" );
OptionSet options = parser.parse( "-a", "-2" );
In this case, the option set contains "a" with argument -2, not both "a" and
"2". Swapping the elements in the args array gives the latter.There are two ways to tell the parser what options to recognize:
accepts or acceptsAll methods; calls on the ensuing chain of objects describe whether the options can take an argument,
whether the argument is required or optional, to what type arguments of the options should be converted if any,
etc. Since version 3, these calls return an instance of OptionSpec, which can subsequently be used to
retrieve the arguments of the associated option in a type-safe manner.String.
Here are the rules for the format of the specification strings this constructor accepts:
*) to indicate that
the option is a "help" option.":"),
then the option requires an argument."::"),
then the option accepts an optional argument."+" ), the parser will behave
"POSIX-ly correct"."W;" (capital W followed by a
semicolon), the parser will recognize the alternative form of long options.Each of the options in a list of options given to acceptsAll is treated as a
synonym of the others. For example:
OptionParser parser = new OptionParser();
parser.acceptsAll( asList( "w", "interactive", "confirmation" ) );
OptionSet options = parser.parse( "-w" );
In this case, options. would answer hastrue when given arguments
"w", "interactive", and "confirmation". The OptionSet would give the same
responses to these arguments for its other methods as well.
By default, as with GNU getopt(), the parser allows intermixing of options and non-options. If, however,
the parser has been created to be "POSIX-ly correct", then the first argument that does not look lexically like an
option, and is not a required argument of a preceding option, signals the end of options. You can still bind
optional arguments to their options using the abutting (for short options) or = syntax.
Unlike GNU getopt(), this parser does not honor the environment variable POSIXLY_CORRECT.
"POSIX-ly correct" parsers are configured by either:
posixlyCorrect(boolean), or"+")| Constructor and Description |
|---|
OptionParser()
Creates an option parser that initially recognizes no options, and does not exhibit "POSIX-ly correct"
behavior.
|
OptionParser(boolean allowAbbreviations)
Creates an option parser that initially recognizes no options, and does not exhibit "POSIX-ly correct"
behavior.
|
OptionParser(String optionSpecification)
Creates an option parser and configures it to recognize the short options specified in the given string.
|
| Modifier and Type | Method and Description |
|---|---|
OptionSpecBuilder |
accepts(String option)
Tells the parser to recognize the given option.
|
OptionSpecBuilder |
accepts(String option,
String description)
Tells the parser to recognize the given option.
|
OptionSpecBuilder |
acceptsAll(List<String> options)
Tells the parser to recognize the given options, and treat them as synonymous.
|
OptionSpecBuilder |
acceptsAll(List<String> options,
String description)
Tells the parser to recognize the given options, and treat them as synonymous.
|
void |
allowsUnrecognizedOptions()
Tells the parser to treat unrecognized options as non-option arguments.
|
void |
formatHelpWith(HelpFormatter formatter)
Tells the parser to use the given formatter when asked to print help.
|
void |
mutuallyExclusive(OptionSpecBuilder... specs)
Mandates mutual exclusiveness for the options built by the specified builders.
|
NonOptionArgumentSpec<String> |
nonOptions()
Gives an object that represents an access point for non-option arguments on a command line.
|
NonOptionArgumentSpec<String> |
nonOptions(String description)
Gives an object that represents an access point for non-option arguments on a command line.
|
OptionSet |
parse(String... arguments)
Parses the given command line arguments according to the option specifications given to the parser.
|
void |
posixlyCorrect(boolean setting)
Tells the parser whether or not to behave "POSIX-ly correct"-ly.
|
void |
printHelpOn(OutputStream sink)
Writes information about the options this parser recognizes to the given output sink.
|
void |
printHelpOn(Writer sink)
Writes information about the options this parser recognizes to the given output sink.
|
void |
recognizeAlternativeLongOptions(boolean recognize)
Tells the parser either to recognize or ignore
-W-style long options. |
Map<String,OptionSpec<?>> |
recognizedOptions()
Retrieves all options-spec pairings which have been configured for the parser in the same order as declared
during training.
|
public OptionParser()
public OptionParser(boolean allowAbbreviations)
allowAbbreviations - whether unambiguous abbreviations of long options should be recognized
by the parserpublic OptionParser(String optionSpecification)
String.optionSpecification - an option specificationNullPointerException - if optionSpecification is nullOptionException - if the option specification contains illegal characters or otherwise cannot be
recognizedpublic OptionSpecBuilder accepts(String option)
OptionDeclarerThis method returns an instance of OptionSpecBuilder to allow the formation of parser directives
as sentences in a fluent interface language. For example:
OptionDeclarer parser = new OptionParser();
parser.accepts( "c" ).withRequiredArg().ofType( Integer.class );
If no methods are invoked on the returned OptionSpecBuilder, then the parser treats the option as
accepting no argument.
accepts in interface OptionDeclareroption - the option to recognizepublic OptionSpecBuilder accepts(String option, String description)
OptionDeclareraccepts in interface OptionDeclareroption - the option to recognizedescription - a string that describes the purpose of the option. This is used when generating help
information about the parser.OptionDeclarer.accepts(String)public OptionSpecBuilder acceptsAll(List<String> options)
OptionDeclareracceptsAll in interface OptionDeclareroptions - the options to recognize and treat as synonymousOptionDeclarer.accepts(String)public OptionSpecBuilder acceptsAll(List<String> options, String description)
OptionDeclareracceptsAll in interface OptionDeclareroptions - the options to recognize and treat as synonymousdescription - a string that describes the purpose of the option. This is used when generating help
information about the parser.OptionDeclarer.acceptsAll(List)public NonOptionArgumentSpec<String> nonOptions()
OptionDeclarernonOptions in interface OptionDeclarerpublic NonOptionArgumentSpec<String> nonOptions(String description)
OptionDeclarernonOptions in interface OptionDeclarerdescription - a string that describes the purpose of the non-option arguments. This is used when generating
help information about the parser.OptionDeclarer.nonOptions()public void posixlyCorrect(boolean setting)
OptionDeclarerposixlyCorrect in interface OptionDeclarersetting - true if the parser should behave "POSIX-ly correct"-lypublic void allowsUnrecognizedOptions()
OptionDeclarerTells the parser to treat unrecognized options as non-option arguments.
If not called, then the parser raises an OptionException when it encounters an unrecognized
option.
allowsUnrecognizedOptions in interface OptionDeclarerpublic void recognizeAlternativeLongOptions(boolean recognize)
OptionDeclarer-W-style long options.recognizeAlternativeLongOptions in interface OptionDeclarerrecognize - true if the parser is to recognize the special style of long optionspublic void printHelpOn(OutputStream sink) throws IOException
sink - the sink to write information toIOException - if there is a problem writing to the sinkNullPointerException - if sink is nullprintHelpOn(Writer)public void printHelpOn(Writer sink) throws IOException
sink - the sink to write information toIOException - if there is a problem writing to the sinkNullPointerException - if sink is nullprintHelpOn(OutputStream)public void formatHelpWith(HelpFormatter formatter)
formatter - the formatter to use for printing helpNullPointerException - if the formatter is nullpublic Map<String,OptionSpec<?>> recognizedOptions()
OptionSpec.options(); only the order of the
specs is preserved.
(Note: prior to 4.7 the order was alphabetical across all options regardless of spec.)OptionSpecpublic OptionSet parse(String... arguments)
arguments - arguments to parseOptionSet describing the parsed options, their arguments, and any non-option arguments foundOptionException - if problems are detected while parsingNullPointerException - if the argument list is nullpublic void mutuallyExclusive(OptionSpecBuilder... specs)
specs - descriptors for options that should be mutually exclusive on a command line.NullPointerException - if specs is nullCopyright © 2017. All Rights Reserved.