Package org.kohsuke.args4j

Class CmdLineParser

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

    For typical usage, see this example.

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

      • createDefaultValuePart

        private java.lang.String createDefaultValuePart​(OptionHandler handler)

      • localize

        private java.lang.String localize​(java.lang.String s,
                                  java.util.ResourceBundle rb)

      • wrapLines

        private java.util.List<java.lang.String> wrapLines​(java.lang.String line,
                                                   int maxLength)
        Wraps a line so that the resulting parts are not longer than a given maximum length.
        Parameters:
        line - Line to wrap
        maxLength - maximum length for the resulting parts
        Returns:
        list of all wrapped parts

      • getPrefixLen

        private int getPrefixLen​(OptionHandler h,
                         java.util.ResourceBundle rb)

      • getOptionName

        private java.lang.String getOptionName()

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

      • expandAtFiles

        private java.lang.String[] expandAtFiles​(java.lang.String[] args)
                                  throws CmdLineException
        Expands every entry prefixed with the AT sign by reading the file. The AT sign is used to reference another file that contains command line options separated by line breaks.
        Parameters:
        args - the command line arguments to be preprocessed.
        Returns:
        args with the @ sequences replaced by the text files referenced by the @ sequences, split around the line breaks.
        Throws:
        CmdLineException

      • readAllLines

        private static java.util.List<java.lang.String> readAllLines​(java.io.File f)
                                                      throws java.io.IOException
        Reads all lines of a file with the platform encoding.
        Throws:
        java.io.IOException

      • isHandlerHasHisOptions

        private boolean isHandlerHasHisOptions​(NamedOptionDef option,
                                       java.util.Set<OptionHandler> present)
        Returns:
        true if all options required by option are present, false otherwise

      • isHandlerAllowOtherOptions

        private boolean isHandlerAllowOtherOptions​(NamedOptionDef option,
                                           java.util.Set<OptionHandler> present)
        Returns:
        true if all options forbid by option are not present, false otherwise

      • findOptionHandler

        private OptionHandler findOptionHandler​(java.lang.String name)

      • findOptionByName

        private OptionHandler findOptionByName​(java.lang.String name)
        Finds a registered OptionHandler by its name or its alias.
        Parameters:
        name - name
        Returns:
        the OptionHandler or 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.

      • printSingleLineOption

        private void printSingleLineOption​(java.io.PrintWriter pw,
                                   OptionHandler h,
                                   java.util.ResourceBundle rb)