Class CommandLineParser
- java.lang.Object
-
- ca.cgjennings.apps.CommandLineParser
-
- Direct Known Subclasses:
ClientArguments
,register
public class CommandLineParser extends java.lang.Object
Parses command line options for an application. To use aCommandLineParser
, provide a class (possibly a subclass of this class) with public fields whose names match the desired options. The parser will search for options in the command line arguments and match them against fields in the class of the supplied object. When an option name matches a field name, the value of the field will be set to reflect the value of the option.Depending on the type of the field, an option takes either 0 or 1 parameters. If the type of the field is
boolean
orBoolean
, it will take no parameter. The value of the field will set totrue
if the option is found, and otherwise it will not be changed. For other types, the argument immediately following the option is taken to be its parameter. The following field types can all be filled in automatically from this argument:String
,File
, int,Integer
, double,Double
,Class
,Locale
, andEnum
. Strings are copied as-is. Files are filled in as if bynew File( argument )
; classes as if byClass.forName( argument )
. Numeric types are filled in as if by the appropriatevalueOf
orparseInt
method. If a class is not found or there is a syntax error in the format of a numeric parameter, a suitable error message is printed.Locales
are interpreted using the same mechanism as that used for resource bundles, e.g., en_CA would refer to Canadian English.Enum
types will be assigned a value by converting the parameter to upper case and invoking the enum'svalueOf
method on the result.If the type of a field is not one of the predefined types above, then the type will be checked for a constructor that takes a single
String
argument. If one exists, then it will be used to create the value to be filled in the field by calling the constructor with the parameter string. Otherwise, anAssertionError
will be thrown.Any arguments that are neither an option nor a parameter for an option will be collected and, after parsing is completed, may be fetched using
getPlainArguments()
orgetPlainFiles()
.- Since:
- 3.0
- Author:
- Chris Jennings
-
-
Constructor Summary
Constructors Constructor Description CommandLineParser()
Creates a new command line parser that matches the public fields of the subclass.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected void
displayUsageText(java.lang.Object target)
Called to display usage information when help is requested.protected java.lang.String
getOptionName(java.lang.String argument)
Returns the name of an option in a command line argument, stripped of its prefix; if the argument does not represent an option, returnsnull
.java.lang.String[]
getPlainArguments()
Returns a copy of all of the arguments that were not used as options or the value of an option.java.io.File[]
getPlainFiles()
Returns a copy of all of the arguments that were not used as options or the value of an option asFile
objects.java.lang.String
getUsageText()
Returns the usage text to display when command line help is requested.protected void
handleParsingError(java.lang.String message)
Called when there is an error with the command line syntax.protected boolean
isCaseSensitive()
If this returnstrue
, then the matching of option names to fields will be case sensitive.protected boolean
isHelpOption(java.lang.String argument)
Returnstrue
if and only if the supplied argument should be interpreted as a request for help.void
parse(java.lang.Object target, java.lang.String... args)
Parses an application's command line arguments, filling in the matching public fields oftarget
as appropriate.protected void
setOption(java.lang.Object target, java.lang.String name, java.lang.reflect.Field field, java.lang.String value)
This is called by the parser to set the value for an option in its associated field.void
setUsageText(java.lang.String commandHelp)
Sets the usage information to display when command line help is requested.
-
-
-
Method Detail
-
setUsageText
public void setUsageText(java.lang.String commandHelp)
Sets the usage information to display when command line help is requested.- Parameters:
commandHelp
- the banner and help information to display
-
getUsageText
public java.lang.String getUsageText()
Returns the usage text to display when command line help is requested.- Returns:
- the help information to display, or
null
if none set
-
getPlainArguments
public java.lang.String[] getPlainArguments()
Returns a copy of all of the arguments that were not used as options or the value of an option. For a typical command line utility, this would be the list of files on which the command is to operate. If the parser has not parsed a command line, or if an error occurred during the last parse, this will returnnull
.- Returns:
- the unused command line arguments, or
null
-
getPlainFiles
public java.io.File[] getPlainFiles()
Returns a copy of all of the arguments that were not used as options or the value of an option asFile
objects. For a typical command line utility, this would be the list of files on which the command is to operate. If the parser has not parsed a command line, or if an error occurred during the last parse, this will returnnull
.- Returns:
- the unused command line arguments, or
null
- See Also:
getPlainArguments()
-
getOptionName
protected java.lang.String getOptionName(java.lang.String argument)
Returns the name of an option in a command line argument, stripped of its prefix; if the argument does not represent an option, returnsnull
. The base class checks for a prefix of either "--" or "-". If present, it returns the remainder of the argument. Otherwise, it returnsnull
. Subclasses may override this to enforce other conventions.- Parameters:
argument
- the argument which might represent an option name- Returns:
- the option name represented, or
null
if the argument is not an option
-
isCaseSensitive
protected boolean isCaseSensitive()
If this returnstrue
, then the matching of option names to fields will be case sensitive. The base class returnsfalse
.- Returns:
true
to make option names case sensitive
-
isHelpOption
protected boolean isHelpOption(java.lang.String argument)
Returnstrue
if and only if the supplied argument should be interpreted as a request for help. The base class returnstrue
for any of: "--help", "-help", "--h", "-?", or "/?".- Parameters:
argument
- the argument to test- Returns:
true
if help should be displayed
-
displayUsageText
protected void displayUsageText(java.lang.Object target)
Called to display usage information when help is requested. The base class prints a message to the output stream and exits. If a non-null
usage text has been set withsetUsageText(java.lang.String)
, then this will be used as the text to display. If no other usage text is defined, the base class will display a default message that is generated from the fields in the target.- Parameters:
target
- the object being used as a parsing template
-
handleParsingError
protected void handleParsingError(java.lang.String message)
Called when there is an error with the command line syntax. The base class prints the supplied message, then prints a line inviting the user to use the--help
option for more information, and then exits the application with a return code of 20 (indicating an abnormal termination).- Parameters:
message
- the message to display, ornull
for the default message "The command line arguments are incorrect"
-
parse
public void parse(java.lang.Object target, java.lang.String... args)
Parses an application's command line arguments, filling in the matching public fields oftarget
as appropriate.- Parameters:
target
- the object whose fields will be filled in, ornull
to use this objectargs
- the command line arguments to parse
-
setOption
protected void setOption(java.lang.Object target, java.lang.String name, java.lang.reflect.Field field, java.lang.String value)
This is called by the parser to set the value for an option in its associated field.- Parameters:
target
- the object whose fields should be modifiedname
- the name of the optionfield
- the field in which the option's value should be placedvalue
- the argument from which the option's value must be derived;null
if the option takes no value
-
-