public class CmdLineParser
extends java.lang.Object
For typical usage, see this example.
Modifier and Type | Class and Description |
---|---|
private class |
CmdLineParser.CmdLineImpl
Essentially a pointer over a
String array. |
Modifier and Type | Field and Description |
---|---|
private java.util.List<OptionHandler> |
arguments
Discovered
OptionHandler s for arguments. |
private OptionHandler |
currentOptionHandler |
private java.util.List<OptionHandler> |
options
Discovered
OptionHandler s for options. |
private ParserProperties |
parserProperties
settings for the parser
|
private boolean |
parsingOptions |
Constructor and Description |
---|
CmdLineParser(java.lang.Object bean)
Creates a new command line owner that
parses arguments/options and set them into
the given object.
|
CmdLineParser(java.lang.Object bean,
ParserProperties parserProperties)
Creates a new command line owner that
parses arguments/options and set them into
the given object.
|
Modifier and Type | Method and Description |
---|---|
void |
addArgument(Setter setter,
Argument a)
Programmatically defines an argument (instead of reading it from annotations as normal).
|
void |
addOption(Setter setter,
Option o)
Programmatically defines an option (instead of reading it from annotations as normal).
|
private void |
checkOptionNotInMap(java.lang.String name) |
private void |
checkRequiredOptionsAndArguments(java.util.Set<OptionHandler> present) |
private java.lang.String |
createDefaultValuePart(OptionHandler handler) |
protected OptionHandler |
createOptionHandler(OptionDef o,
Setter setter)
|
private java.lang.String[] |
expandAtFiles(java.lang.String[] args)
Expands every entry prefixed with the AT sign by
reading the file.
|
private OptionHandler |
findOptionByName(java.lang.String name)
Finds a registered
OptionHandler by its name or its alias. |
private OptionHandler |
findOptionHandler(java.lang.String name) |
java.util.List<OptionHandler> |
getArguments()
Lists up all the defined arguments in the order.
|
private java.lang.String |
getOptionName() |
java.util.List<OptionHandler> |
getOptions()
Lists up all the defined options.
|
private int |
getPrefixLen(OptionHandler h,
java.util.ResourceBundle rb) |
ParserProperties |
getProperties() |
private boolean |
isHandlerAllowOtherOptions(NamedOptionDef option,
java.util.Set<OptionHandler> present) |
private boolean |
isHandlerHasHisOptions(NamedOptionDef option,
java.util.Set<OptionHandler> present) |
protected boolean |
isOption(java.lang.String arg)
Returns
true if the given token is an option
(as opposed to an argument). |
private java.lang.String |
localize(java.lang.String s,
java.util.ResourceBundle rb) |
void |
parseArgument(java.util.Collection<java.lang.String> args)
Same as
parseArgument(String[]) |
void |
parseArgument(java.lang.String... args)
Parses the command line arguments and set them to the option bean
given in the constructor.
|
java.lang.String |
printExample(ExampleMode mode)
Deprecated.
|
java.lang.String |
printExample(ExampleMode mode,
java.util.ResourceBundle rb)
Deprecated.
|
java.lang.String |
printExample(OptionHandlerFilter filter)
Formats a command line example into a string.
|
java.lang.String |
printExample(OptionHandlerFilter mode,
java.util.ResourceBundle rb)
Formats a command line example into a string.
|
protected void |
printOption(java.io.PrintWriter out,
OptionHandler handler,
int len,
java.util.ResourceBundle rb,
OptionHandlerFilter filter)
Prints usage information for a given option.
|
private void |
printSingleLineOption(java.io.PrintWriter pw,
OptionHandler h,
java.util.ResourceBundle rb) |
void |
printSingleLineUsage(java.io.OutputStream out)
Prints a single-line usage to the screen.
|
void |
printSingleLineUsage(java.io.Writer w,
java.util.ResourceBundle rb)
Prints a single-line usage to the screen.
|
void |
printUsage(java.io.OutputStream out)
Prints the list of options and their usages to the screen.
|
void |
printUsage(java.io.Writer out,
java.util.ResourceBundle rb)
Prints the list of all the non-hidden options and their usages to the screen.
|
void |
printUsage(java.io.Writer out,
java.util.ResourceBundle rb,
OptionHandlerFilter filter)
Prints the list of all the non-hidden options and their usages to the screen.
|
private static java.util.List<java.lang.String> |
readAllLines(java.io.File f)
Reads all lines of a file with the platform encoding.
|
static void |
registerHandler(java.lang.Class valueType,
java.lang.Class<? extends OptionHandler> handlerClass)
Deprecated.
You should use
OptionHandlerRegistry.registerHandler(java.lang.Class, java.lang.Class) instead. |
void |
setUsageWidth(int usageWidth)
Deprecated.
Use
ParserProperties.withUsageWidth(int) instead. |
void |
stopOptionParsing()
Signals the parser that parsing the options has finished.
|
private java.util.List<java.lang.String> |
wrapLines(java.lang.String line,
int maxLength)
Wraps a line so that the resulting parts are not longer than a given maximum length.
|
private final java.util.List<OptionHandler> options
OptionHandler
s for options.private final java.util.List<OptionHandler> arguments
OptionHandler
s for arguments.private boolean parsingOptions
private OptionHandler currentOptionHandler
private ParserProperties parserProperties
public CmdLineParser(java.lang.Object bean)
bean
- instance of a class annotated by Option
and Argument
.
this object will receive values. If this is null
, the processing will
be skipped, which is useful if you'd like to feed metadata from other sources.IllegalAnnotationError
- if the option bean class is using args4j annotations incorrectly.public CmdLineParser(java.lang.Object bean, ParserProperties parserProperties)
bean
- instance of a class annotated by Option
and Argument
.
this object will receive values. If this is null
, the processing will
be skipped, which is useful if you'd like to feed metadata from other sources.parserProperties
- various settings for this classIllegalAnnotationError
- if the option bean class is using args4j annotations incorrectly.public ParserProperties getProperties()
public void addArgument(Setter setter, Argument a)
setter
- the setter for the typea
- the Argumentjava.lang.NullPointerException
- if setter
or a
is null
.public void addOption(Setter setter, Option o)
setter
- the setter for the typeo
- the Option
java.lang.NullPointerException
- if setter
or o
is null
.IllegalAnnotationError
- if the option name or one of the aliases is already taken.public java.util.List<OptionHandler> getArguments()
public java.util.List<OptionHandler> getOptions()
private void checkOptionNotInMap(java.lang.String name) throws IllegalAnnotationError
IllegalAnnotationError
protected OptionHandler createOptionHandler(OptionDef o, Setter setter)
public java.lang.String printExample(OptionHandlerFilter filter)
printExample(OptionHandlerFilter, ResourceBundle)
for more details.filter
- must not be null
.null
.public java.lang.String printExample(ExampleMode mode)
printExample(OptionHandlerFilter)
public java.lang.String printExample(OptionHandlerFilter mode, java.util.ResourceBundle rb)
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).
mode
- Determines which options will be a part of the returned string.
Must not be null
.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. See Option.metaVar()
. This is to support
localization.
Passing null
would print Option.metaVar()
directly.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");
java.lang.NullPointerException
- if mode
is null
.public java.lang.String printExample(ExampleMode mode, java.util.ResourceBundle rb)
printExample(OptionHandlerFilter,ResourceBundle)
public void printUsage(java.io.OutputStream out)
This is a convenience method for calling printUsage(new OutputStreamWriter(out),null)
so that you can do printUsage(System.err)
.
public void printUsage(java.io.Writer out, java.util.ResourceBundle rb)
Short for printUsage(out,rb,OptionHandlerFilter.PUBLIC)
public void printUsage(java.io.Writer out, java.util.ResourceBundle rb, OptionHandlerFilter filter)
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.protected void printOption(java.io.PrintWriter out, OptionHandler handler, int len, java.util.ResourceBundle rb, OptionHandlerFilter filter)
Subtypes may override this method and determine which options get printed (or other things),
based on OptionHandler
(perhaps by using handler.setter.asAnnotatedElement()
).
out
- Writer to write intohandler
- handler where to receive the informationlen
- Maximum length of metadata columnrb
- ResourceBundle
for I18NSetter.asAnnotatedElement()
private java.lang.String createDefaultValuePart(OptionHandler handler)
private java.lang.String localize(java.lang.String s, java.util.ResourceBundle rb)
private java.util.List<java.lang.String> wrapLines(java.lang.String line, int maxLength)
line
- Line to wrapmaxLength
- maximum length for the resulting partsprivate int getPrefixLen(OptionHandler h, java.util.ResourceBundle rb)
private java.lang.String getOptionName()
public void parseArgument(java.util.Collection<java.lang.String> args) throws CmdLineException
parseArgument(String[])
CmdLineException
public void parseArgument(java.lang.String... args) throws CmdLineException
args
- arguments to parseCmdLineException
- if there's any error parsing arguments, or if
required
option was not given.java.lang.NullPointerException
- if args
is null
.private java.lang.String[] expandAtFiles(java.lang.String[] args) throws CmdLineException
args
- the command line arguments to be preprocessed.CmdLineException
private static java.util.List<java.lang.String> readAllLines(java.io.File f) throws java.io.IOException
java.io.IOException
private void checkRequiredOptionsAndArguments(java.util.Set<OptionHandler> present) throws CmdLineException
CmdLineException
private boolean isHandlerHasHisOptions(NamedOptionDef option, java.util.Set<OptionHandler> present)
true
if all options required by option
are present, false
otherwiseprivate boolean isHandlerAllowOtherOptions(NamedOptionDef option, java.util.Set<OptionHandler> present)
true
if all options forbid by option
are not present, false
otherwiseprivate OptionHandler findOptionHandler(java.lang.String name)
private OptionHandler findOptionByName(java.lang.String name)
OptionHandler
by its name or its alias.name
- nameOptionHandler
or null
protected boolean isOption(java.lang.String arg)
true
if the given token is an option
(as opposed to an argument).java.lang.NullPointerException
- if arg
is null
.public static void registerHandler(java.lang.Class valueType, java.lang.Class<? extends OptionHandler> handlerClass)
OptionHandlerRegistry.registerHandler(java.lang.Class, java.lang.Class)
instead.OptionHandler
class with args4j.
This method allows users to extend the behavior of args4j by writing
their own OptionHandler
implementation.
valueType
- The specified handler is used when the field/method annotated by Option
is of this type.handlerClass
- This class must have the constructor that has the same signature as
OptionHandler.OptionHandler(CmdLineParser, OptionDef, Setter)
java.lang.NullPointerException
- if valueType
or handlerClass
is null
.java.lang.IllegalArgumentException
- if handlerClass
is not a subtype of OptionHandler
.public void setUsageWidth(int usageWidth)
ParserProperties.withUsageWidth(int)
instead.usageWidth
- the width of the usage output in columns.java.lang.IllegalArgumentException
- if usageWidth
is negativepublic void stopOptionParsing()
Everything seen after this call is treated as an argument as opposed to an option.
public void printSingleLineUsage(java.io.OutputStream out)
This is a convenience method for calling printUsage(new OutputStreamWriter(out),null)
so that you can do printUsage(System.err)
.
java.lang.NullPointerException
- if out
is null
.public void printSingleLineUsage(java.io.Writer w, java.util.ResourceBundle rb)
rb
- if this is non-null
, Option.usage()
is treated
as a key to obtain the actual message from this resource bundle.java.lang.NullPointerException
- if w
is null
.private void printSingleLineOption(java.io.PrintWriter pw, OptionHandler h, java.util.ResourceBundle rb)