Package org.kohsuke.args4j

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

Author:
  Kohsuke Kawaguchi (kk@kohsuke.org)

### Constructor Summary

Constructors
`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
`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.
`java.util.List<OptionHandler>` `getArguments()` Lists up all the defined arguments in the order.
`java.util.List<OptionHandler>` `getOptions()` Lists up all the defined options.
`ParserProperties` `getProperties()`
`protected boolean` `isOption​(java.lang.String arg)` Returns `true` if the given token is an option (as opposed to an argument).
`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 as `parseArgument(String[])`
`java.lang.String` `printExample​(ExampleMode mode)` Deprecated. Use `printExample(OptionHandlerFilter)`
`java.lang.String` `printExample​(ExampleMode mode, java.util.ResourceBundle rb)` Deprecated. Use `printExample(OptionHandlerFilter,ResourceBundle)`
`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.
`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.
`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.

### Methods inherited from class java.lang.Object

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

### 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 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​(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 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:
  `java.lang.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:
  `java.lang.NullPointerException` - if `setter` or `o` is `null`.
  `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.

#### createOptionHandler

    protected OptionHandler createOptionHandler​(OptionDef o,
                                                Setter setter)

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

#### printExample

    public java.lang.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 java.lang.String printExample​(ExampleMode mode)

Deprecated.
Use `printExample(OptionHandlerFilter)`

#### 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 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:
  `java.lang.NullPointerException` - if `mode` is `null`.

#### printExample

    public java.lang.String printExample​(ExampleMode mode,
                                         java.util.ResourceBundle rb)

Deprecated.
Use `printExample(OptionHandlerFilter,ResourceBundle)`

#### 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 do `printUsage(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 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​(java.util.Collection<java.lang.String> args)
                       throws CmdLineException

Same as `parseArgument(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 if `required` option was not given.
  `java.lang.NullPointerException` - if `args` is `null`.

#### isOption

    protected boolean isOption​(java.lang.String arg)

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

Throws:
  `java.lang.NullPointerException` - if `arg` is `null`.

#### registerHandler

    public 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.
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(CmdLineParser, OptionDef, Setter)`
Throws:
  `java.lang.NullPointerException` - if `valueType` or `handlerClass` is `null`.
  `java.lang.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:
  `java.lang.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​(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 do `printUsage(System.err)`.

Throws:
  `java.lang.NullPointerException` - if `out` is `null`.

#### 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` - if `w` is `null`.