Package org.kohsuke.args4j

Class CmdLineParser

  • public class CmdLineParser
extends java.lang.Object
    Command line argument owner.

    For a typical usage, see this example.

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

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected OptionHandler createOptionHandler​(OptionDef o, Setter setter)
      Creates an OptionHandler that handles the given Option annotation and the Setter instance.
      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.
      java.lang.String printExample​(ExampleMode mode)
      Formats a command line example into a string.
      java.lang.String printExample​(ExampleMode mode, java.util.ResourceBundle rb)
      Formats a command line example into a string.
      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 options and their usages to the screen.
      static void registerHandler​(java.lang.Class valueType, java.lang.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​(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.
        Throws:
        IllegalAnnotationError - if the option bean class is using args4j annotations incorrectly.

    • Method Detail

      • printExample

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

      • isOption

        protected boolean isOption​(java.lang.String arg)
        Returns true if the given token is an option (as opposed to an argument.)

      • registerHandler

        public static void registerHandler​(java.lang.Class valueType,
                                   java.lang.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, NamedOptionDef, Setter).

      • setUsageWidth

        public void setUsageWidth​(int usageWidth)

      • stopOptionParsing

        public void stopOptionParsing()

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

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