Package org.kohsuke.args4j

Class 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 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

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

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

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