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 Details

    • 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 Details

    • 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:

    • 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(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.