Package org.apache.commons.cli
Class DefaultParser
java.lang.Object
org.apache.commons.cli.DefaultParser
- All Implemented Interfaces:
CommandLineParser
Default parser.
- Since:
- 1.3
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
A nested builder class to createDefaultParser
instances using descriptive methods. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final boolean
Flag indicating if partial matching of long options is supported.protected CommandLine
The command-line instance.protected Option
The last option parsed.protected String
The token currently processed.protected List
The required options and groups expected to be found when parsing the command line.protected Options
The current options.protected boolean
Flag indicating if tokens should no longer be analyzed and simply added as arguments of the command line.protected boolean
Flag indicating how unrecognized tokens are handled.private final Boolean
Flag indicating if balanced leading and trailing double quotes should be stripped from option arguments. -
Constructor Summary
ConstructorsModifierConstructorDescriptionCreates a new DefaultParser instance with partial matching enabled.DefaultParser
(boolean allowPartialMatching) Create a new DefaultParser instance with the specified partial matching policy.private
DefaultParser
(boolean allowPartialMatching, Boolean stripLeadingAndTrailingQuotes) Creates a new DefaultParser instance with the specified partial matching and quote stripping policy. -
Method Summary
Modifier and TypeMethodDescriptionstatic DefaultParser.Builder
builder()
Creates a newDefaultParser.Builder
to create anDefaultParser
using descriptive methods.private void
Throws aMissingArgumentException
if the current option didn't receive the number of arguments expected.protected void
Throws aMissingOptionException
if all of the required options are not present.private String
getLongPrefix
(String token) Searches for a prefix that is the long name of an option (-Xmx512m)getMatchingLongOptions
(String token) Gets a list of matching option strings for the given token, depending on the selected partial matching policy.protected void
handleConcatenatedOptions
(String token) Breakstoken
into its constituent parts using the following algorithm.private void
handleLongOption
(String token) Handles the following tokens: --L --L=V --L V --lprivate void
handleLongOptionWithEqual
(String token) Handles the following tokens: --L=V -L=V --l=V -l=Vprivate void
Handles the following tokens: --L -L --l -lprivate void
handleOption
(Option option) private void
handleProperties
(Properties properties) Sets the values of Options using the values inproperties
.private void
handleShortAndLongOption
(String token) Handles the following tokens: -S -SV -S V -S=V -S1S2 -S1S2 V -SV1=V2 -L -LV -L V -L=V -lprivate void
handleToken
(String token) Handles any command line token.private void
handleUnknownToken
(String token) Handles an unknown token.private boolean
isArgument
(String token) Tests if the token is a valid argument.private boolean
isJavaProperty
(String token) Tests if the specified token is a Java-like property (-Dkey=value).private boolean
isLongOption
(String token) Tests if the token looks like a long option.private boolean
isNegativeNumber
(String token) Tests if the token is a negative number.private boolean
Tests if the token looks like an option.private boolean
isShortOption
(String token) Tests if the token looks like a short option.Parses the arguments according to the specified options.Parses the arguments according to the specified options.parse
(Options options, String[] arguments, Properties properties) Parses the arguments according to the specified options and properties.parse
(Options options, String[] arguments, Properties properties, boolean stopAtNonOption) Parses the arguments according to the specified options and properties.private String
Strips balanced leading and trailing quotes if the stripLeadingAndTrailingQuotes is set If stripLeadingAndTrailingQuotes is null, then do not stripprivate String
Strips balanced leading and trailing quotes if the stripLeadingAndTrailingQuotes is set If stripLeadingAndTrailingQuotes is null, then do not stripprivate void
updateRequiredOptions
(Option option) Removes the option or its group from the list of expected elements.
-
Field Details
-
cmd
The command-line instance. -
options
The current options. -
stopAtNonOption
protected boolean stopAtNonOptionFlag indicating how unrecognized tokens are handled.true
to stop the parsing and add the remaining tokens to the args list.false
to throw an exception. -
currentToken
The token currently processed. -
currentOption
The last option parsed. -
skipParsing
protected boolean skipParsingFlag indicating if tokens should no longer be analyzed and simply added as arguments of the command line. -
expectedOpts
The required options and groups expected to be found when parsing the command line. -
allowPartialMatching
private final boolean allowPartialMatchingFlag indicating if partial matching of long options is supported. -
stripLeadingAndTrailingQuotes
Flag indicating if balanced leading and trailing double quotes should be stripped from option arguments. null represents the historic arbitrary behaviour
-
-
Constructor Details
-
DefaultParser
public DefaultParser()Creates a new DefaultParser instance with partial matching enabled. By "partial matching" we mean that given the following code:{ @code final Options options = new Options(); options.addOption(new Option("d", "debug", false, "Turn on debug.")); options.addOption(new Option("e", "extract", false, "Turn on extract.")); options.addOption(new Option("o", "option", true, "Turn on option with argument.")); }
with "partial matching" turned on,-de
only matches the"debug"
option. However, with "partial matching" disabled,-de
would enable bothdebug
as well asextract
options. -
DefaultParser
public DefaultParser(boolean allowPartialMatching) Create a new DefaultParser instance with the specified partial matching policy. By "partial matching" we mean that given the following code:{ @code final Options options = new Options(); options.addOption(new Option("d", "debug", false, "Turn on debug.")); options.addOption(new Option("e", "extract", false, "Turn on extract.")); options.addOption(new Option("o", "option", true, "Turn on option with argument.")); }
with "partial matching" turned on,-de
only matches the"debug"
option. However, with "partial matching" disabled,-de
would enable bothdebug
as well asextract
options.- Parameters:
allowPartialMatching
- if partial matching of long options shall be enabled
-
DefaultParser
Creates a new DefaultParser instance with the specified partial matching and quote stripping policy.- Parameters:
allowPartialMatching
- if partial matching of long options shall be enabledstripLeadingAndTrailingQuotes
- if balanced outer double quoutes should be stripped
-
-
Method Details
-
builder
Creates a newDefaultParser.Builder
to create anDefaultParser
using descriptive methods.- Returns:
- a new
DefaultParser.Builder
instance - Since:
- 1.5.0
-
checkRequiredArgs
Throws aMissingArgumentException
if the current option didn't receive the number of arguments expected.- Throws:
ParseException
-
checkRequiredOptions
Throws aMissingOptionException
if all of the required options are not present.- Throws:
MissingOptionException
- if any of the required Options are not present.
-
getLongPrefix
Searches for a prefix that is the long name of an option (-Xmx512m)- Parameters:
token
-
-
getMatchingLongOptions
Gets a list of matching option strings for the given token, depending on the selected partial matching policy.- Parameters:
token
- the token (may contain leading dashes)- Returns:
- the list of matching option strings or an empty list if no matching option could be found
-
handleConcatenatedOptions
Breakstoken
into its constituent parts using the following algorithm.- ignore the first character ("-")
- for each remaining character check if an
Option
exists with that id. - if an
Option
does exist then add that character prepended with "-" to the list of processed tokens. - if the
Option
can have an argument value and there are remaining characters in the token then add the remaining characters as a token to the list of processed tokens. - if an
Option
does NOT exist ANDstopAtNonOption
IS set then add the special token "--" followed by the remaining characters and also the remaining tokens directly to the processed tokens list. - if an
Option
does NOT exist ANDstopAtNonOption
IS NOT set then add that character prepended with "-".
- Parameters:
token
- The current token to be burst at the first non-Option encountered.- Throws:
ParseException
- if there are any problems encountered while parsing the command line token.
-
handleLongOption
Handles the following tokens: --L --L=V --L V --l- Parameters:
token
- the command line token to handle- Throws:
ParseException
-
handleLongOptionWithEqual
Handles the following tokens: --L=V -L=V --l=V -l=V- Parameters:
token
- the command line token to handle- Throws:
ParseException
-
handleLongOptionWithoutEqual
Handles the following tokens: --L -L --l -l- Parameters:
token
- the command line token to handle- Throws:
ParseException
-
handleOption
- Throws:
ParseException
-
handleProperties
Sets the values of Options using the values inproperties
.- Parameters:
properties
- The value properties to be processed.- Throws:
ParseException
-
handleShortAndLongOption
Handles the following tokens: -S -SV -S V -S=V -S1S2 -S1S2 V -SV1=V2 -L -LV -L V -L=V -l- Parameters:
token
- the command line token to handle- Throws:
ParseException
-
handleToken
Handles any command line token.- Parameters:
token
- the command line token to handle- Throws:
ParseException
-
handleUnknownToken
Handles an unknown token. If the token starts with a dash an UnrecognizedOptionException is thrown. Otherwise the token is added to the arguments of the command line. If the stopAtNonOption flag is set, this stops the parsing and the remaining tokens are added as-is in the arguments of the command line.- Parameters:
token
- the command line token to handle- Throws:
ParseException
-
isArgument
Tests if the token is a valid argument.- Parameters:
token
-
-
isJavaProperty
Tests if the specified token is a Java-like property (-Dkey=value). -
isLongOption
Tests if the token looks like a long option.- Parameters:
token
-
-
isNegativeNumber
Tests if the token is a negative number.- Parameters:
token
-
-
isOption
Tests if the token looks like an option.- Parameters:
token
-
-
isShortOption
Tests if the token looks like a short option.- Parameters:
token
-
-
parse
Description copied from interface:CommandLineParser
Parses the arguments according to the specified options.- Specified by:
parse
in interfaceCommandLineParser
- Parameters:
options
- the specified Optionsarguments
- the command line arguments- Returns:
- the list of atomic option and value tokens
- Throws:
ParseException
- if there are any problems encountered while parsing the command line tokens.
-
parse
public CommandLine parse(Options options, String[] arguments, boolean stopAtNonOption) throws ParseException Description copied from interface:CommandLineParser
Parses the arguments according to the specified options.- Specified by:
parse
in interfaceCommandLineParser
- Parameters:
options
- the specified Optionsarguments
- the command line argumentsstopAtNonOption
- iftrue
an unrecognized argument stops the parsing and the remaining arguments are added to theCommandLine
s args list. Iffalse
an unrecognized argument triggers a ParseException.- Returns:
- the list of atomic option and value tokens
- Throws:
ParseException
- if there are any problems encountered while parsing the command line tokens.
-
parse
public CommandLine parse(Options options, String[] arguments, Properties properties) throws ParseException Parses the arguments according to the specified options and properties.- Parameters:
options
- the specified Optionsarguments
- the command line argumentsproperties
- command line option name-value pairs- Returns:
- the list of atomic option and value tokens
- Throws:
ParseException
- if there are any problems encountered while parsing the command line tokens.
-
parse
public CommandLine parse(Options options, String[] arguments, Properties properties, boolean stopAtNonOption) throws ParseException Parses the arguments according to the specified options and properties.- Parameters:
options
- the specified Optionsarguments
- the command line argumentsproperties
- command line option name-value pairsstopAtNonOption
- iftrue
an unrecognized argument stops the parsing and the remaining arguments are added to theCommandLine
s args list. Iffalse
an unrecognized argument triggers a ParseException.- Returns:
- the list of atomic option and value tokens
- Throws:
ParseException
- if there are any problems encountered while parsing the command line tokens.
-
stripLeadingAndTrailingQuotesDefaultOff
Strips balanced leading and trailing quotes if the stripLeadingAndTrailingQuotes is set If stripLeadingAndTrailingQuotes is null, then do not strip- Parameters:
token
- a string- Returns:
- token with the quotes stripped (if set)
-
stripLeadingAndTrailingQuotesDefaultOn
Strips balanced leading and trailing quotes if the stripLeadingAndTrailingQuotes is set If stripLeadingAndTrailingQuotes is null, then do not strip- Parameters:
token
- a string- Returns:
- token with the quotes stripped (if set)
-
updateRequiredOptions
Removes the option or its group from the list of expected elements.- Parameters:
option
-- Throws:
AlreadySelectedException
-