Class CmdLineParser
- java.lang.Object
-
- org.kohsuke.args4j.CmdLineParser
-
public class CmdLineParser extends java.lang.Object
Command line argument owner.For typical usage, see this example.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private class
CmdLineParser.CmdLineImpl
Essentially a pointer over aString
array.
-
Field Summary
Fields Modifier and Type Field Description private java.util.List<OptionHandler>
arguments
DiscoveredOptionHandler
s for arguments.private OptionHandler
currentOptionHandler
private java.util.List<OptionHandler>
options
DiscoveredOptionHandler
s for options.private ParserProperties
parserProperties
settings for the parserprivate boolean
parsingOptions
-
Constructor Summary
Constructors Constructor 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.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method 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 registeredOptionHandler
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)
Returnstrue
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.lang.String... args)
Parses the command line arguments and set them to the option bean given in the constructor.void
parseArgument(java.util.Collection<java.lang.String> args)
Same asparseArgument(String[])
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 useOptionHandlerRegistry.registerHandler(java.lang.Class, java.lang.Class)
instead.void
setUsageWidth(int usageWidth)
Deprecated.UseParserProperties.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.
-
-
-
Field Detail
-
options
private final java.util.List<OptionHandler> options
DiscoveredOptionHandler
s for options.
-
arguments
private final java.util.List<OptionHandler> arguments
DiscoveredOptionHandler
s for arguments.
-
parsingOptions
private boolean parsingOptions
-
currentOptionHandler
private OptionHandler currentOptionHandler
-
parserProperties
private ParserProperties parserProperties
settings for the parser
-
-
Constructor Detail
-
CmdLineParser
public CmdLineParser(java.lang.Object bean)
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
public CmdLineParser(java.lang.Object bean, ParserProperties parserProperties)
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 Detail
-
getProperties
public ParserProperties getProperties()
-
addArgument
public void addArgument(Setter setter, Argument a)
Programmatically defines an argument (instead of reading it from annotations as normal).- Parameters:
setter
- the setter for the typea
- the Argument- Throws:
java.lang.NullPointerException
- ifsetter
ora
isnull
.
-
addOption
public void addOption(Setter setter, Option o)
Programmatically defines an option (instead of reading it from annotations as normal).- Parameters:
setter
- the setter for the typeo
- theOption
- Throws:
java.lang.NullPointerException
- ifsetter
oro
isnull
.IllegalAnnotationError
- if the option name or one of the aliases is already taken.
-
getArguments
public java.util.List<OptionHandler> getArguments()
Lists up all the defined arguments in the order.
-
getOptions
public java.util.List<OptionHandler> getOptions()
Lists up all the defined options.
-
checkOptionNotInMap
private void checkOptionNotInMap(java.lang.String name) throws IllegalAnnotationError
- Throws:
IllegalAnnotationError
-
createOptionHandler
protected OptionHandler createOptionHandler(OptionDef o, Setter setter)
-
printExample
public java.lang.String printExample(OptionHandlerFilter filter)
Formats a command line example into a string. SeeprintExample(OptionHandlerFilter, ResourceBundle)
for more details.- Parameters:
filter
- must not benull
.- Returns:
- always non-
null
.
-
printExample
public java.lang.String printExample(ExampleMode mode)
Deprecated.
-
printExample
public java.lang.String printExample(OptionHandlerFilter mode, java.util.ResourceBundle rb)
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:
java.lang.NullPointerException
- ifmode
isnull
.
-
printExample
public java.lang.String printExample(ExampleMode mode, java.util.ResourceBundle rb)
Deprecated.
-
printUsage
public void printUsage(java.io.OutputStream out)
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
public 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.Short for
printUsage(out,rb,OptionHandlerFilter.PUBLIC)
-
printUsage
public 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.- 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(java.io.PrintWriter out, OptionHandler handler, int len, java.util.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:
Setter.asAnnotatedElement()
-
createDefaultValuePart
private java.lang.String createDefaultValuePart(OptionHandler handler)
-
localize
private java.lang.String localize(java.lang.String s, java.util.ResourceBundle rb)
-
wrapLines
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.- Parameters:
line
- Line to wrapmaxLength
- maximum length for the resulting parts- Returns:
- list of all wrapped parts
-
getPrefixLen
private int getPrefixLen(OptionHandler h, java.util.ResourceBundle rb)
-
getOptionName
private java.lang.String getOptionName()
-
parseArgument
public void parseArgument(java.util.Collection<java.lang.String> args) throws CmdLineException
Same asparseArgument(String[])
- Throws:
CmdLineException
-
parseArgument
public void parseArgument(java.lang.String... args) throws CmdLineException
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.java.lang.NullPointerException
- ifargs
isnull
.
-
expandAtFiles
private java.lang.String[] expandAtFiles(java.lang.String[] args) throws CmdLineException
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
private static java.util.List<java.lang.String> readAllLines(java.io.File f) throws java.io.IOException
Reads all lines of a file with the platform encoding.- Throws:
java.io.IOException
-
checkRequiredOptionsAndArguments
private void checkRequiredOptionsAndArguments(java.util.Set<OptionHandler> present) throws CmdLineException
- Throws:
CmdLineException
-
isHandlerHasHisOptions
private boolean isHandlerHasHisOptions(NamedOptionDef option, java.util.Set<OptionHandler> present)
- Returns:
true
if all options required byoption
are present,false
otherwise
-
isHandlerAllowOtherOptions
private boolean isHandlerAllowOtherOptions(NamedOptionDef option, java.util.Set<OptionHandler> present)
- Returns:
true
if all options forbid byoption
are not present,false
otherwise
-
findOptionHandler
private OptionHandler findOptionHandler(java.lang.String name)
-
findOptionByName
private OptionHandler findOptionByName(java.lang.String name)
Finds a registeredOptionHandler
by its name or its alias.- Parameters:
name
- name- Returns:
- the
OptionHandler
ornull
-
isOption
protected boolean isOption(java.lang.String arg)
Returnstrue
if the given token is an option (as opposed to an argument).- Throws:
java.lang.NullPointerException
- ifarg
isnull
.
-
registerHandler
public static void registerHandler(java.lang.Class valueType, java.lang.Class<? extends OptionHandler> handlerClass)
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:
java.lang.NullPointerException
- ifvalueType
orhandlerClass
isnull
.java.lang.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:
java.lang.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
public void printSingleLineUsage(java.io.OutputStream out)
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:
java.lang.NullPointerException
- ifout
isnull
.
-
printSingleLineUsage
public void printSingleLineUsage(java.io.Writer w, java.util.ResourceBundle rb)
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:
java.lang.NullPointerException
- ifw
isnull
.
-
printSingleLineOption
private void printSingleLineOption(java.io.PrintWriter pw, OptionHandler h, java.util.ResourceBundle rb)
-
-