Class CmdLineParser
For typical usage, see this example.
- Author:
- Kohsuke Kawaguchi (kk@kohsuke.org)
-
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).protected OptionHandler
createOptionHandler
(OptionDef o, Setter setter) Lists up all the defined arguments in the order.Lists up all the defined options.protected boolean
Returnstrue
if the given token is an option (as opposed to an argument).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.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.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.
-
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. -
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:
-
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
.
-
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
.
-
printExample(OptionHandlerFilter)