org.kohsuke.args4j

Class CmdLineParser

java.lang.Object

org.kohsuke.args4j.CmdLineParser

public class CmdLineParser
extends Object

Command line argument owner.

For typical usage, see this example.

Author:

Kohsuke Kawaguchi (kk@kohsuke.org)

Constructor Summary

Constructors

Constructor and Description
CmdLineParser(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

Methods

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).
protected OptionHandler	createOptionHandler(OptionDef o, Setter setter) Creates an OptionHandler that handles the given Option annotation and the Setter instance.
List<OptionHandler>	getArguments() Lists up all the defined arguments in the order.
List<OptionHandler>	getOptions() Lists up all the defined options.
ParserProperties	getProperties()
protected boolean	isOption(String arg) Returns true if the given token is an option (as opposed to an argument).
void	parseArgument(Collection<String> args) Same as parseArgument(String[])
void	parseArgument(String... args) Parses the command line arguments and set them to the option bean given in the constructor.
String	printExample(ExampleMode mode) Deprecated. Use printExample(OptionHandlerFilter)
String	printExample(ExampleMode mode, ResourceBundle rb) Deprecated. Use printExample(OptionHandlerFilter,ResourceBundle)
String	printExample(OptionHandlerFilter filter) Formats a command line example into a string.
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	printSingleLineUsage(OutputStream out) Prints a single-line usage to the screen.
void	printSingleLineUsage(Writer w, ResourceBundle rb) 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 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CmdLineParser

public CmdLineParser(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 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.

Throws:

IllegalAnnotationError - if the option bean class is using args4j annotations incorrectly.

CmdLineParser

public CmdLineParser(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 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 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 type

a - the Argument

Throws:

NullPointerException - if setter or a is null.

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 type

o - the Option

Throws:

NullPointerException - if setter or o is null.

IllegalAnnotationError - if the option name or one of the aliases is already taken.

getArguments

public List<OptionHandler> getArguments()

Lists up all the defined arguments in the order.

getOptions

public List<OptionHandler> getOptions()

Lists up all the defined options.

createOptionHandler

protected OptionHandler createOptionHandler(OptionDef o,
                                Setter setter)

Creates an OptionHandler that handles the given Option annotation and the Setter instance.

printExample

public String printExample(OptionHandlerFilter filter)

Formats a command line example into a string. See printExample(OptionHandlerFilter, ResourceBundle) for more details.

Parameters:

filter - must not be null.

Returns:

always non-null.

printExample

public String printExample(ExampleMode mode)

Deprecated. Use printExample(OptionHandlerFilter)

printExample

public String printExample(OptionHandlerFilter mode,
                  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 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.

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 - if mode is null.

printExample

public String printExample(ExampleMode mode,
                  ResourceBundle rb)

Deprecated. Use printExample(OptionHandlerFilter,ResourceBundle)

printUsage

public void printUsage(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 do printUsage(System.err).

printUsage

public void printUsage(Writer out,
              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(Writer out,
              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(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 using handler.setter.asAnnotatedElement()).

Parameters:

out - Writer to write into

handler - handler where to receive the information

len - Maximum length of metadata column

rb - ResourceBundle for I18N

See Also:

Setter.asAnnotatedElement()

parseArgument

public void parseArgument(Collection<String> args)
                   throws CmdLineException

Same as parseArgument(String[])

Throws:

CmdLineException

parseArgument

public void parseArgument(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 if required option was not given.

NullPointerException - if args is null.

isOption

protected boolean isOption(String arg)

Returns true if the given token is an option (as opposed to an argument).

Throws:

NullPointerException - if arg is null.

registerHandler

public static void registerHandler(Class valueType,
                   Class<? extends OptionHandler> handlerClass)

Deprecated. You should use OptionHandlerRegistry.registerHandler(java.lang.Class, java.lang.Class) instead.

Registers a user-defined OptionHandler 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 by Option is of this type.

handlerClass - This class must have the constructor that has the same signature as OptionHandler.OptionHandler(CmdLineParser, OptionDef, Setter)

Throws:

NullPointerException - if valueType or handlerClass is null.

IllegalArgumentException - if handlerClass is not a subtype of OptionHandler.

setUsageWidth

public void setUsageWidth(int usageWidth)

Deprecated. Use ParserProperties.withUsageWidth(int) instead.

Sets the width of the usage output.

Parameters:

usageWidth - the width of the usage output in columns.

Throws:

IllegalArgumentException - if usageWidth 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(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 do printUsage(System.err).

Throws:

NullPointerException - if out is null.

printSingleLineUsage

public void printSingleLineUsage(Writer w,
                        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:

NullPointerException - if w is null.