|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectjoptsimple.OptionParser
public class OptionParser
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.
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:
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.has would answer true 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 Summary | |
|---|---|
OptionParser()
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. |
|
| Method Summary | |
|---|---|
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(Collection<String> options)
Tells the parser to recognize the given options, and treat them as synonymous. |
OptionSpecBuilder |
acceptsAll(Collection<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. |
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 the options which have been configured for the parser. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
|---|
public OptionParser()
public OptionParser(String optionSpecification)
String.
optionSpecification - an option specification
NullPointerException - if optionSpecification is null
OptionException - if the option specification contains illegal characters or otherwise cannot be
recognized| Method Detail |
|---|
public 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 recognize
public OptionSpecBuilder accepts(String option,
String description)
OptionDeclarer
accepts 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(Collection<String> options)
OptionDeclarer
acceptsAll in interface OptionDeclareroptions - the options to recognize and treat as synonymous
OptionDeclarer.accepts(String)
public OptionSpecBuilder acceptsAll(Collection<String> options,
String description)
OptionDeclarer
acceptsAll 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(Collection)public NonOptionArgumentSpec<String> nonOptions()
OptionDeclarer
nonOptions in interface OptionDeclarerpublic NonOptionArgumentSpec<String> nonOptions(String description)
OptionDeclarer
nonOptions 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)
OptionDeclarer
posixlyCorrect 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
recognizeAlternativeLongOptions in interface OptionDeclarerrecognize - true if the parser is to recognize the special style of long options
public void printHelpOn(OutputStream sink)
throws IOException
sink - the sink to write information to
IOException - if there is a problem writing to the sink
NullPointerException - if sink is nullprintHelpOn(Writer)
public void printHelpOn(Writer sink)
throws IOException
sink - the sink to write information to
IOException - if there is a problem writing to the sink
NullPointerException - if sink is nullprintHelpOn(OutputStream)public void formatHelpWith(HelpFormatter formatter)
formatter - the formatter to use for printing help
NullPointerException - if the formatter is nullpublic Map<String,OptionSpec<?>> recognizedOptions()
Map containing all the configured options and their corresponding OptionSpecpublic OptionSet parse(String... arguments)
arguments - arguments to parse
OptionSet describing the parsed options, their arguments, and any non-option arguments found
OptionException - if problems are detected while parsing
NullPointerException - if the argument list is null
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||