public class CommandLineParser extends Object
Nomenclature:
| token | 1 or more characters delimited by white space characeters. The 1st character cannot be a "-" |
| option | a token preceded by a "-" (i.e. -verbose); options are case insensitive |
| value | one or more tokens following an option |
Syntax assumed by this class followed by some examples:
[token] ... [option] [value] ... [token]
max.txt -threads 5 -debug -mode color intense table.txt
-threads 5 -debug -verbose max.txt jon.txt
The last example would decompose as follows:
| Type | Option | Values/Tokens |
| leading_tokens | N/A | none |
| option | -threads | 5 |
| option | -debug | none |
| option | -verbose | max.txt jon.txt |
| trailing_tokens | N/A | max.txt jon.txt |
From the decompositon you can see the values for the option -verbose are the same as the tokens for the trailing_tokens. This is an ambiguous case which is beyond the scope of what this class is intended to solve. The consumer of this class needs to resolve the ambiguity or a dervied class can be created that will resolve the ambiguity.
| Modifier and Type | Class and Description |
|---|---|
class |
CommandLineParser.InvalidOptionsException
Signals that an exception occurred while the command line
arguments were being parsed.
|
class |
CommandLineParser.NoSuchOptionException
Signals that an exception occurred while looking up an option.
|
class |
CommandLineParser.OptionDataException
Signals that an exception occurred when trying to convert an
option value from one data type to another or the value(s)
associated with the option are invalid.
|
class |
CommandLineParser.OptionException
Signals that an exception occurred while doing an operation that
involved an option (lookup of the option, data retrieval, etc.)
|
class |
CommandLineParser.ValueOutOfBoundsException
Signals that an exception occurred when trying to retrieve one or
more values for an option.
|
| Modifier and Type | Field and Description |
|---|---|
static int |
ALL
Constant used to specify an indefinite number of values.
|
| Modifier | Constructor and Description |
|---|---|
protected |
CommandLineParser(String[] args)
You must call this constructor when deriving from this class and
the constructor of your derived class you must call the
parse method after your constructor has finished
all initialization. |
| Modifier and Type | Method and Description |
|---|---|
protected String |
constructErrMsg(ResourceBundle bundle,
String errFormatKey,
Object[] msgArgs)
Helper method used to construct an error message using the specified
key.
|
protected String |
constructErrMsg(String errFormatKey,
Object[] msgArgs)
Helper method used to construct an error message using the specified
key.
|
boolean |
containsOption(String option)
Tests if a option (i.e.
|
static CommandLineParser |
createParser(String[] args)
Factory method used to create a CommandLineParser.
|
String[] |
getArgs()
Get the command line argumets that were passed to the constructor
of the CommandLineParser.
|
String |
getHelp()
Get the help string that describes the syntax required by your options
class and a desciption of each option used by your class.
|
String |
getLeadingToken(int index)
Get the ith leading token using the specified index.
|
String[] |
getLeadingTokens()
Get the leading tokens.
|
int |
getNumLeadingTokens()
Get the number of leading tokens.
|
int |
getNumOptions()
Get the number of options that appeared on the command line.
|
int |
getNumTrailingTokens()
Get the number of trailing tokens.
|
int |
getNumValues(String option)
Get the number values that follow an option.
|
protected String |
getStrFromBundle(ResourceBundle bundle,
String key)
Helper method used to return a string using the specified key.
|
protected String |
getStrFromBundle(String key)
Helper method used to return a string using the specified key.
|
String |
getTrailingToken(int index)
Get the ith trailing token using the specified index.
|
String[] |
getTrailingTokens()
Get the trailing tokens.
|
String |
getValue(String option)
Gets the first value following specified option.
|
String[] |
getValues(String option)
Get all of the values following the specified option.
|
String[] |
getValues(String option,
int numValues)
Get the specified number of values following the specified
option.
|
boolean |
isHelp()
Return true if the help option was contained in the command
line or the command line is empty.
|
protected void |
parse()
Internal method that parses the argument array.
|
protected void |
postParse()
Override this method to do any post parsing.
|
protected boolean |
storeAllTokensAsLeadingTokens()
Override this method if you want to change the default behavior that
when a command line only contains tokens (no options) then the tokens
will be considered leading tokens and there will be no trailing tokens.
|
static String |
strArrayToString(String[] sa)
Simple minded helper method to output the contents of a string array
to a string.
|
String |
toString()
Convert this class to a string that will contain the following:
The arguments passed to the constructor
The leading tokens
For each option, the values associated with that option
The trailing tokens
|
protected void |
validateLeadingTokens(ArrayList tokens)
Override this method if validation of the leading tokens is
required when parsing the command line arguments.
|
protected void |
validateOption(String option,
ArrayList values,
boolean lastOption)
Override this method if validation for a particular option
is required.
|
protected void |
validateRequiredParameters()
Ensure that all required options were present on the command line.
|
protected void |
validateTrailingTokens(ArrayList tokens,
int numLastOptionArgs)
Override this method if validation of the trailing tokens is
required when parsing the command line arguments.
|
public static final int ALL
getValues() to retrieve all of the
values associated with the option.protected CommandLineParser(String[] args) throws CommandLineParser.InvalidOptionsException
parse method after your constructor has finished
all initialization. This is because the parse method
calls methods that can be overriden in your derived
class, so your dervied class must be completely instantiated for the
parse method to operate correctly and predictably.
args - The array of command line arguments passed to the program.dummy - A dummy parameter used to create a unique method signature.
Just pass null.CommandLineParser.InvalidOptionsException - An error was encountered when
parsing the command line arguments. This gets thrown by the parse()
method that the constructor in your derived class will call.public static CommandLineParser createParser(String[] args) throws CommandLineParser.InvalidOptionsException
args - The array of command line arguments passed to the program.CommandLineParser.InvalidOptionsException - An error was encountered when
parsing the command line arguments. The only error this class will
generate is when a duplicate option is encountered.public String[] getArgs()
public boolean containsOption(String option)
option - The option to check for presence in the command line.public int getNumValues(String option) throws CommandLineParser.NoSuchOptionException
option - The option (i.e. -accounts) to return the
number of values for.CommandLineParser.NoSuchOptionException - The option is not on the command
line.public String[] getValues(String option) throws CommandLineParser.NoSuchOptionException
option - The option (i.e. -accounts) to return the values for.CommandLineParser.NoSuchOptionException - The option is not on the command
line.public String[] getValues(String option, int numValues) throws CommandLineParser.NoSuchOptionException, CommandLineParser.ValueOutOfBoundsException
CommandLineParser.ALL to return
all the values following the option. If no values follow the
option an empty array will be returned.option - The option (i.e. -accounts) to return the values for.numValues - The number of values to return. Use the constant
CommandLineParser.ALL to return all the values following
the option.
CommandLineParser.NoSuchOptionException - The option is not on the command
line.CommandLineParser.ValueOutOfBoundsException - The number of values requested
exceeds the number of values associated with the option.public String getValue(String option) throws CommandLineParser.NoSuchOptionException, CommandLineParser.ValueOutOfBoundsException
option - The option (i.e. -threads) to return the first
value for.CommandLineParser.NoSuchOptionException - The option is not on the command
line.CommandLineParser.ValueOutOfBoundsException - There are no values associated
with the option.public int getNumLeadingTokens()
public String[] getLeadingTokens()
public String getLeadingToken(int index) throws CommandLineParser.ValueOutOfBoundsException
index - The zero relative index of token to return.CommandLineParser.ValueOutOfBoundsException - The ith leading token does
not exist.public int getNumTrailingTokens()
public int getNumOptions()
public String[] getTrailingTokens()
public String getTrailingToken(int index) throws CommandLineParser.ValueOutOfBoundsException
index - The zero relative index of token to return.CommandLineParser.ValueOutOfBoundsException - The ith trailing token does
not exist.public String toString()
public boolean isHelp()
public String getHelp()
public static String strArrayToString(String[] sa)
protected void validateLeadingTokens(ArrayList tokens) throws CommandLineParser.InvalidOptionsException
tokens - The list of "tokens" that appear at the beginning
of the command line. The list will be empty if there are no tokens.CommandLineParser.InvalidOptionsException - There is an error with the number
of "leading tokens" or the value of a "leading token" is invalid.protected void validateOption(String option, ArrayList values, boolean lastOption) throws CommandLineParser.InvalidOptionsException
option - The name of the option to validate. This name will
include the leading "-" (i.e. "-verbose").values - The list of values associated with the option. The
list will be empty if there are no values.lastOption - This flag will be true if this is the last option
contained in the command line.CommandLineParser.InvalidOptionsException - There is an error with the number
of values for the option or a particular value is invalid.protected void validateTrailingTokens(ArrayList tokens, int numLastOptionArgs) throws CommandLineParser.InvalidOptionsException
tokens - The list of "tokens" that appear at the end
of the command line. The list will be empty if there are no tokens.numLastOptionArgs - The number of arguments used by the
last option.CommandLineParser.InvalidOptionsException - There is an error with the number
of trailing tokens or the value of a trailing token>
is invalid.protected void validateRequiredParameters()
throws CommandLineParser.InvalidOptionsException
CommandLineParser.InvalidOptionsException - A required option was not present on
the command line.protected boolean storeAllTokensAsLeadingTokens()
protected void postParse()
throws CommandLineParser.InvalidOptionsException
CommandLineParser.InvalidOptionsException - An error was detected when extracting
option values into local member variables.protected final void parse()
throws CommandLineParser.InvalidOptionsException
parse method after your constructor has finished all
initialization. This is because the parse method calls
methods that can be overriden in your derived class, so your dervied
class must be completely instantiated for this method to function
correctly and predictably.
CommandLineParser.InvalidOptionsException - An error was encountered when
parsing the command line arguments.protected final String getStrFromBundle(String key)
key - The key to use to retrieve the string from the resource
bundle.protected final String getStrFromBundle(ResourceBundle bundle, String key)
key - The key to use to retrieve the string from the resource
bundle.bundle - The resource bundle to retrieve the string from.protected final String constructErrMsg(String errFormatKey, Object[] msgArgs)
errFormatKey - The resource key to use to retrieve the error
message (i.e. "clp.format_msg.option_not_found").msgArgs - The array of arguments to substitute into the error
message.protected final String constructErrMsg(ResourceBundle bundle, String errFormatKey, Object[] msgArgs)
errFormatKey - The resource key to use to retrieve the error
message (i.e. "clp.format_msg.option_not_found").msgArgs - The array of arguments to substitute into the error
message.bundle - The resource bundle to retrieve the error message from.Copyright © 2003, 2023, Oracle and/or its affiliates.