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 has
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 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 null
OptionException
- if the option specification contains illegal characters or otherwise cannot be
recognizedpublic OptionSpecBuilder accepts(String option)
OptionDeclarer
This 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 OptionDeclarer
option
- the option to recognizepublic OptionSpecBuilder accepts(String option, String description)
OptionDeclarer
accepts
in interface OptionDeclarer
option
- 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)
OptionDeclarer
acceptsAll
in interface OptionDeclarer
options
- the options to recognize and treat as synonymousOptionDeclarer.accepts(String)
public OptionSpecBuilder acceptsAll(List<String> options, String description)
OptionDeclarer
acceptsAll
in interface OptionDeclarer
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.OptionDeclarer.acceptsAll(List)
public NonOptionArgumentSpec<String> nonOptions()
OptionDeclarer
nonOptions
in interface OptionDeclarer
public NonOptionArgumentSpec<String> nonOptions(String description)
OptionDeclarer
nonOptions
in interface OptionDeclarer
description
- 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 OptionDeclarer
setting
- true
if the parser should behave "POSIX-ly correct"-lypublic void allowsUnrecognizedOptions()
OptionDeclarer
Tells 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 OptionDeclarer
public void recognizeAlternativeLongOptions(boolean recognize)
OptionDeclarer
-W
-style long options.recognizeAlternativeLongOptions
in interface OptionDeclarer
recognize
- 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 null
printHelpOn(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 null
printHelpOn(OutputStream)
public void formatHelpWith(HelpFormatter formatter)
formatter
- the formatter to use for printing helpNullPointerException
- if the formatter is null
public 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.)OptionSpec
public 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 null
public void mutuallyExclusive(OptionSpecBuilder... specs)
specs
- descriptors for options that should be mutually exclusive on a command line.NullPointerException
- if specs
is null
© Copyright 2004-2016 Paul R. Holser, Jr. All rights reserved. Licensed under The MIT License.