org.kohsuke.args4j
Class CmdLineParser

java.lang.Object
  org.kohsuke.args4j.CmdLineParser

public class CmdLineParser
extends Object

Command line argument owner.

For a typical usage, see this example.

Author:

Kohsuke Kawaguchi (kk@kohsuke.org)

Constructor Summary

CmdLineParser(Object bean)
Creates a new command line owner that parses arguments/options and set them into the given object.

Method Summary

void	addArgument(Setter setter, Argument a) Programmatically defines an argument (instead of reading it from annotations like you normally do.)
void	addOption(Setter setter, Option o) Programmatically defines an option (instead of reading it from annotations like you normally do.)
protected OptionHandler	createOptionHandler(OptionDef o, Setter setter) Creates an OptionHandler that handles the given Option annotation and the Setter instance.
List<OptionHandler>	getArguments()
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) Formats a command line example into a string.
String	printExample(ExampleMode mode, ResourceBundle rb) Formats a command line example into a string.
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 options and their usages to the screen.
static void	registerHandler(Class valueType, Class<? extends OptionHandler> handlerClass) Registers a user-defined OptionHandler class with args4j.
void	setUsageWidth(int usageWidth)
void	stopOptionParsing()

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.

Method Detail

addArgument

public void addArgument(Setter setter,
                        Argument a)

Programmatically defines an argument (instead of reading it from annotations like you normally do.)

Parameters:

setter - the setter for the type

a - the Argument

addOption

public void addOption(Setter setter,
                      Option o)

Programmatically defines an option (instead of reading it from annotations like you normally do.)

Parameters:

setter - the setter for the type

o - the Option

getArguments

public List<OptionHandler> getArguments()

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(ExampleMode mode)

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

Parameters:

mode - must not be null.

Returns:

always non-null.

printExample

public String printExample(ExampleMode mode,
                           ResourceBundle rb)

Formats a command line example into a string.

This method produces a string like " -d <dir> -v -b", which is useful for printing a command line example, perhaps as a part of the usage screen.

Parameters:

mode - One of the ExampleMode constants. Must not be null. This determines what option should be a part of the returned string.

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");

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 options and their usages 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.

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.

isOption

protected boolean isOption(String arg)

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

registerHandler

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

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)

setUsageWidth

public void setUsageWidth(int usageWidth)

stopOptionParsing

public void stopOptionParsing()

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).

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.