Class CmdLineParser
For typical usage, see this example.
-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final List
<OptionHandler> DiscoveredOptionHandler
s for arguments.private OptionHandler
private final List
<OptionHandler> DiscoveredOptionHandler
s for options.private ParserProperties
settings for the parserprivate boolean
-
Constructor Summary
ConstructorsConstructorDescriptionCmdLineParser
(Object bean) Creates a new command line owner that parses arguments/options and set them into the given object.CmdLineParser
(Object bean, ParserProperties parserProperties) Creates a new command line owner that parses arguments/options and set them into the given object. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addArgument
(Setter setter, Argument a) Programmatically defines an argument (instead of reading it from annotations as normal).void
Programmatically defines an option (instead of reading it from annotations as normal).private void
checkOptionNotInMap
(String name) private void
checkRequiredOptionsAndArguments
(Set<OptionHandler> present) private String
createDefaultValuePart
(OptionHandler handler) protected OptionHandler
createOptionHandler
(OptionDef o, Setter setter) private String[]
expandAtFiles
(String[] args) Expands every entry prefixed with the AT sign by reading the file.private OptionHandler
findOptionByName
(String name) Finds a registeredOptionHandler
by its name or its alias.private OptionHandler
findOptionHandler
(String name) Lists up all the defined arguments in the order.private String
Lists up all the defined options.private int
private boolean
isHandlerAllowOtherOptions
(NamedOptionDef option, Set<OptionHandler> present) private boolean
isHandlerHasHisOptions
(NamedOptionDef option, Set<OptionHandler> present) protected boolean
Returnstrue
if the given token is an option (as opposed to an argument).private String
localize
(String s, ResourceBundle rb) void
parseArgument
(String... args) Parses the command line arguments and set them to the option bean given in the constructor.void
parseArgument
(Collection<String> args) Same asparseArgument(String[])
printExample
(ExampleMode mode) Deprecated.printExample
(ExampleMode mode, ResourceBundle rb) Deprecated.printExample
(OptionHandlerFilter filter) Formats a command line example into a string.printExample
(OptionHandlerFilter mode, ResourceBundle rb) Formats a command line example into a string.protected void
printOption
(PrintWriter out, OptionHandler handler, int len, ResourceBundle rb, OptionHandlerFilter filter) Prints usage information for a given option.private void
void
Prints a single-line usage to the screen.void
Prints a single-line usage to the screen.void
printUsage
(OutputStream out) Prints the list of options and their usages to the screen.void
printUsage
(Writer out, ResourceBundle rb) Prints the list of all the non-hidden options and their usages to the screen.void
printUsage
(Writer out, ResourceBundle rb, OptionHandlerFilter filter) Prints the list of all the non-hidden options and their usages to the screen.readAllLines
(File f) Reads all lines of a file with the platform encoding.static void
registerHandler
(Class valueType, Class<? extends OptionHandler> handlerClass) Deprecated.You should useOptionHandlerRegistry.registerHandler(java.lang.Class, java.lang.Class)
instead.void
setUsageWidth
(int usageWidth) Deprecated.UseParserProperties.withUsageWidth(int)
instead.void
Signals the parser that parsing the options has finished.Wraps a line so that the resulting parts are not longer than a given maximum length.
-
Field Details
-
options
DiscoveredOptionHandler
s for options. -
arguments
DiscoveredOptionHandler
s for arguments. -
parsingOptions
private boolean parsingOptions -
currentOptionHandler
-
parserProperties
settings for the parser
-
-
Constructor Details
-
CmdLineParser
Creates a new command line owner that parses arguments/options and set them into the given object.- Parameters:
bean
- instance of a class annotated byOption
andArgument
. this object will receive values. If this isnull
, the processing will be skipped, which is useful if you'd like to feed metadata from other sources.- Throws:
IllegalAnnotationError
- if the option bean class is using args4j annotations incorrectly.
-
CmdLineParser
Creates a new command line owner that parses arguments/options and set them into the given object.- Parameters:
bean
- instance of a class annotated byOption
andArgument
. this object will receive values. If this isnull
, the processing will be skipped, which is useful if you'd like to feed metadata from other sources.parserProperties
- various settings for this class- Throws:
IllegalAnnotationError
- if the option bean class is using args4j annotations incorrectly.
-
-
Method Details
-
getProperties
-
addArgument
Programmatically defines an argument (instead of reading it from annotations as normal).- Parameters:
setter
- the setter for the typea
- the Argument- Throws:
NullPointerException
- ifsetter
ora
isnull
.
-
addOption
Programmatically defines an option (instead of reading it from annotations as normal).- Parameters:
setter
- the setter for the typeo
- theOption
- Throws:
NullPointerException
- ifsetter
oro
isnull
.IllegalAnnotationError
- if the option name or one of the aliases is already taken.
-
getArguments
Lists up all the defined arguments in the order. -
getOptions
Lists up all the defined options. -
checkOptionNotInMap
- Throws:
IllegalAnnotationError
-
createOptionHandler
-
printExample
Formats a command line example into a string. SeeprintExample(OptionHandlerFilter, ResourceBundle)
for more details.- Parameters:
filter
- must not benull
.- Returns:
- always non-
null
.
-
printExample
Deprecated. -
printExample
Formats a command line example into a string.This method produces a string like
-d <dir> -v -b
. This is useful for printing a command line example (perhaps as a part of the usage screen).- Parameters:
mode
- Determines which options will be a part of the returned string. Must not benull
.rb
- If non-null
, meta variables (<dir>
in the above example) is treated as a key to this resource bundle, and the associated value is printed. SeeOption.metaVar()
. This is to support localization. Passingnull
would printOption.metaVar()
directly.- Returns:
- always non-
null
. If there's no option, this method returns just the empty string""
. Otherwise, this method returns a string that contains a space at the beginning (but not at the end). This allows you to do something like:System.err.println("java -jar my.jar"+parser.printExample(REQUIRED)+" arg1 arg2");
- Throws:
NullPointerException
- ifmode
isnull
.
-
printExample
Deprecated. -
printUsage
Prints the list of options and their usages to the screen.This is a convenience method for calling
printUsage(new OutputStreamWriter(out),null)
so that you can doprintUsage(System.err)
. -
printUsage
Prints the list of all the non-hidden options and their usages to the screen.Short for
printUsage(out,rb,OptionHandlerFilter.PUBLIC)
-
printUsage
Prints the list of all the non-hidden options and their usages to the screen.- Parameters:
rb
- If non-null
,Option.usage()
is treated as a key to obtain the actual message from this resource bundle.filter
- Controls which options to be printed.
-
printOption
protected void printOption(PrintWriter out, OptionHandler handler, int len, ResourceBundle rb, OptionHandlerFilter filter) Prints usage information for a given option.Subtypes may override this method and determine which options get printed (or other things), based on
OptionHandler
(perhaps by usinghandler.setter.asAnnotatedElement()
).- Parameters:
out
- Writer to write intohandler
- handler where to receive the informationlen
- Maximum length of metadata columnrb
-ResourceBundle
for I18N- See Also:
-
createDefaultValuePart
-
localize
-
wrapLines
Wraps a line so that the resulting parts are not longer than a given maximum length.- Parameters:
line
- Line to wrapmaxLength
- maximum length for the resulting parts- Returns:
- list of all wrapped parts
-
getPrefixLen
-
getOptionName
-
parseArgument
Same asparseArgument(String[])
- Throws:
CmdLineException
-
parseArgument
Parses the command line arguments and set them to the option bean given in the constructor.- Parameters:
args
- arguments to parse- Throws:
CmdLineException
- if there's any error parsing arguments, or ifrequired
option was not given.NullPointerException
- ifargs
isnull
.
-
expandAtFiles
Expands every entry prefixed with the AT sign by reading the file. The AT sign is used to reference another file that contains command line options separated by line breaks.- Parameters:
args
- the command line arguments to be preprocessed.- Returns:
- args with the @ sequences replaced by the text files referenced by the @ sequences, split around the line breaks.
- Throws:
CmdLineException
-
readAllLines
Reads all lines of a file with the platform encoding.- Throws:
IOException
-
checkRequiredOptionsAndArguments
- Throws:
CmdLineException
-
isHandlerHasHisOptions
- Returns:
true
if all options required byoption
are present,false
otherwise
-
isHandlerAllowOtherOptions
- Returns:
true
if all options forbid byoption
are not present,false
otherwise
-
findOptionHandler
-
findOptionByName
Finds a registeredOptionHandler
by its name or its alias.- Parameters:
name
- name- Returns:
- the
OptionHandler
ornull
-
isOption
Returnstrue
if the given token is an option (as opposed to an argument).- Throws:
NullPointerException
- ifarg
isnull
.
-
registerHandler
Deprecated.You should useOptionHandlerRegistry.registerHandler(java.lang.Class, java.lang.Class)
instead.Registers a user-definedOptionHandler
class with args4j.This method allows users to extend the behavior of args4j by writing their own
OptionHandler
implementation.- Parameters:
valueType
- The specified handler is used when the field/method annotated byOption
is of this type.handlerClass
- This class must have the constructor that has the same signature asOptionHandler(CmdLineParser, OptionDef, Setter)
- Throws:
NullPointerException
- ifvalueType
orhandlerClass
isnull
.IllegalArgumentException
- ifhandlerClass
is not a subtype ofOptionHandler
.
-
setUsageWidth
public void setUsageWidth(int usageWidth) Deprecated.UseParserProperties.withUsageWidth(int)
instead.Sets the width of the usage output.- Parameters:
usageWidth
- the width of the usage output in columns.- Throws:
IllegalArgumentException
- ifusageWidth
is negative
-
stopOptionParsing
public void stopOptionParsing()Signals the parser that parsing the options has finished.Everything seen after this call is treated as an argument as opposed to an option.
-
printSingleLineUsage
Prints a single-line usage to the screen.This is a convenience method for calling
printUsage(new OutputStreamWriter(out),null)
so that you can doprintUsage(System.err)
.- Throws:
NullPointerException
- ifout
isnull
.
-
printSingleLineUsage
Prints a single-line usage to the screen.- Parameters:
rb
- if this is non-null
,Option.usage()
is treated as a key to obtain the actual message from this resource bundle.- Throws:
NullPointerException
- ifw
isnull
.
-
printSingleLineOption
-
printExample(OptionHandlerFilter)