|
||||||||||
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 according to GNU's conventions.
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:
parser.accepts( "a" ).withOptionalArg().ofType( Integer.class );
parser.accepts( "2" );
OptionSet options = parser.parse( new String[] { "-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 on
the ensuing chain of objects describe whether the options can take an argument,
whether the argument is required or optional, and to what type arguments of the
options should be converted.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:
parser.acceptsAll(
Arrays.asList( new String[] { "w", "interactive", "confirmation" } ) );
OptionSet options = parser.parse( new String[] { "-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
Field Summary | |
---|---|
private boolean |
posixlyCorrect
|
private AbbreviationMap |
recognizedOptions
|
private OptionParserState |
state
|
Constructor Summary | |
---|---|
OptionParser()
Creates an option parser that initially recognizes no options, and does not exhibit "POSIX-ly correct" behavior. |
|
OptionParser(java.lang.String optionSpecification)
Creates an option parser and configures it to recognize the short options specified in the given string. |
Method Summary | |
---|---|
OptionSpecBuilder |
accepts(java.lang.String option)
Tells the parser to recognize the given option. |
OptionSpecBuilder |
accepts(java.lang.String option,
java.lang.String description)
Tells the parser to recognize the given option. |
OptionSpecBuilder |
acceptsAll(java.util.List options)
Tells the parser to recognize the given options, and treat them as synonymous. |
OptionSpecBuilder |
acceptsAll(java.util.List options,
java.lang.String description)
Tells the parser to recognize the given options, and treat them as synonymous. |
private static char[] |
extractShortOptionsFrom(java.lang.String argument)
|
(package private) void |
handleLongOptionToken(java.lang.String candidate,
ArgumentList arguments,
OptionSet detected)
|
private void |
handleShortOptionCluster(java.lang.String candidate,
ArgumentList arguments,
OptionSet detected)
|
(package private) void |
handleShortOptionToken(java.lang.String candidate,
ArgumentList arguments,
OptionSet detected)
|
private boolean |
isRecognized(java.lang.String option)
|
(package private) boolean |
looksLikeAnOption(java.lang.String argument)
|
(package private) void |
noMoreOptions()
|
OptionSet |
parse(java.lang.String[] arguments)
Parses the given command line arguments according to the option specifications given to the parser. |
private static KeyValuePair |
parseLongOptionWithArgument(java.lang.String argument)
|
private static KeyValuePair |
parseShortOptionWithArgument(java.lang.String argument)
|
(package private) boolean |
posixlyCorrect()
|
void |
posixlyCorrect(boolean setting)
Tells the parser whether or not to behave "POSIX-ly correct"-ly. |
void |
printHelpOn(java.io.OutputStream sink)
Writes information about the options this parser recognizes to the given output sink. |
void |
printHelpOn(java.io.Writer sink)
Writes information about the options this parser recognizes to the given output sink. |
(package private) void |
recognize(OptionSpec spec)
|
void |
recognizeAlternativeLongOptions(boolean recognize)
Tells the parser either to recognize or ignore "-W"-style long options. |
private void |
reset()
|
void |
setPosixlyCorrect(boolean setting)
Deprecated. Use posixlyCorrect(boolean) instead. |
private OptionSpec |
specFor(char option)
|
private OptionSpec |
specFor(java.lang.String option)
|
private void |
validateOptionCharacters(char[] options)
|
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
private final AbbreviationMap recognizedOptions
private OptionParserState state
private boolean posixlyCorrect
Constructor Detail |
---|
public OptionParser()
Creates an option parser that initially recognizes no options, and does not exhibit "POSIX-ly correct" behavior.
public OptionParser(java.lang.String optionSpecification)
Creates an option parser and configures it to recognize the short options specified in the given string.
Arguments of options specified this way will be of type String
.
optionSpecification
- an option specification
java.lang.NullPointerException
- if optionSpecification is
null
OptionException
- if the option specification contains illegal characters
or otherwise cannot be recognizedMethod Detail |
---|
public OptionSpecBuilder accepts(java.lang.String option)
Tells the parser to recognize the given option.
This method returns an instance of OptionSpecBuilder
to allow the
formation of parser directives as sentences in an internal domain-specific
language. For example:
OptionParser 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.
option
- the option to recognize
OptionException
- if the option contains illegal characters
java.lang.NullPointerException
- if the option is null
public OptionSpecBuilder accepts(java.lang.String option, java.lang.String description)
Tells the parser to recognize the given option.
option
- the option to recognizedescription
- a string that describes the purpose of the option. This is
used when generating help information about the parser.
OptionException
- if the option contains illegal characters
java.lang.NullPointerException
- if the option is null
accepts(String)
public OptionSpecBuilder acceptsAll(java.util.List options)
Tells the parser to recognize the given options, and treat them as synonymous.
options
- the options to recognize and treat as synonymous
OptionException
- if any of the options contain illegal characters
java.lang.NullPointerException
- if the option list or any of its elements are
null
java.lang.ClassCastException
- if any of the items in the option list is not a
String
accepts(String)
public OptionSpecBuilder acceptsAll(java.util.List options, java.lang.String description)
Tells the parser to recognize the given options, and treat them as synonymous.
options
- 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.
OptionException
- if any of the options contain illegal characters
java.lang.NullPointerException
- if the option list or any of its elements are
null
java.lang.IllegalArgumentException
- if the option list is empty
java.lang.ClassCastException
- if any of the items in the option list is not a
String
acceptsAll(List)
public void setPosixlyCorrect(boolean setting)
posixlyCorrect(boolean)
instead.
Tells the parser whether or not to behave "POSIX-ly correct"-ly.
setting
- true
if the parser should behave "POSIX-ly
correct"-lypublic void posixlyCorrect(boolean setting)
Tells the parser whether or not to behave "POSIX-ly correct"-ly.
setting
- true
if the parser should behave "POSIX-ly
correct"-lyboolean posixlyCorrect()
public void recognizeAlternativeLongOptions(boolean recognize)
Tells the parser either to recognize or ignore "-W"-style long options.
recognize
- true
if the parser is to recognize the special style
of long optionsvoid recognize(OptionSpec spec)
public void printHelpOn(java.io.OutputStream sink) throws java.io.IOException
Writes information about the options this parser recognizes to the given output sink.
sink
- the sink to write information to
java.io.IOException
- if there is a problem writing to the sink
java.lang.NullPointerException
- if sink is null
public void printHelpOn(java.io.Writer sink) throws java.io.IOException
Writes information about the options this parser recognizes to the given output sink.
sink
- the sink to write information to
java.io.IOException
- if there is a problem writing to the sink
java.lang.NullPointerException
- if sink is null
public OptionSet parse(java.lang.String[] arguments)
Parses the given command line arguments according to the option specifications given to the parser.
arguments
- arguments to parse
OptionSet
describing the parsed options, their arguments, and
any non-option arguments found
OptionException
- if problems are detected while parsing
java.lang.NullPointerException
- if the argument list is null
void handleLongOptionToken(java.lang.String candidate, ArgumentList arguments, OptionSet detected)
void handleShortOptionToken(java.lang.String candidate, ArgumentList arguments, OptionSet detected)
private void handleShortOptionCluster(java.lang.String candidate, ArgumentList arguments, OptionSet detected)
void noMoreOptions()
boolean looksLikeAnOption(java.lang.String argument)
private boolean isRecognized(java.lang.String option)
private OptionSpec specFor(char option)
private OptionSpec specFor(java.lang.String option)
private void reset()
private static char[] extractShortOptionsFrom(java.lang.String argument)
private void validateOptionCharacters(char[] options)
private static KeyValuePair parseLongOptionWithArgument(java.lang.String argument)
private static KeyValuePair parseShortOptionWithArgument(java.lang.String argument)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |