Package ca.cgjennings.apps

Class CommandLineParser

  • Direct Known Subclasses:
    ClientArguments, register
    public class CommandLineParser
extends java.lang.Object
    Parses command line options for an application. To use a CommandLineParser, provide a class (possibly a subclass of this class) with public fields whose names match the desired options. The parser will search for options in the command line arguments and match them against fields in the class of the supplied object. When an option name matches a field name, the value of the field will be set to reflect the value of the option.

    Depending on the type of the field, an option takes either 0 or 1 parameters. If the type of the field is boolean or Boolean, it will take no parameter. The value of the field will set to true if the option is found, and otherwise it will not be changed. For other types, the argument immediately following the option is taken to be its parameter. The following field types can all be filled in automatically from this argument: String, File, int, Integer, double, Double, Class, Locale, and Enum. Strings are copied as-is. Files are filled in as if by new File( argument ); classes as if by Class.forName( argument ). Numeric types are filled in as if by the appropriate valueOf or parseInt method. If a class is not found or there is a syntax error in the format of a numeric parameter, a suitable error message is printed. Locales are interpreted using the same mechanism as that used for resource bundles, e.g., en_CA would refer to Canadian English. Enum types will be assigned a value by converting the parameter to upper case and invoking the enum's valueOf method on the result.

    If the type of a field is not one of the predefined types above, then the type will be checked for a constructor that takes a single String argument. If one exists, then it will be used to create the value to be filled in the field by calling the constructor with the parameter string. Otherwise, an AssertionError will be thrown.

    Any arguments that are neither an option nor a parameter for an option will be collected and, after parsing is completed, may be fetched using getPlainArguments() or getPlainFiles().

    Since:
    3.0
    Author:
    Chris Jennings

    • Constructor Summary

      Constructors 
      Constructor Description
      CommandLineParser()
      Creates a new command line parser that matches the public fields of the subclass.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void displayUsageText​(java.lang.Object target)
      Called to display usage information when help is requested.
      protected java.lang.String getOptionName​(java.lang.String argument)
      Returns the name of an option in a command line argument, stripped of its prefix; if the argument does not represent an option, returns null.
      java.lang.String[] getPlainArguments()
      Returns a copy of all of the arguments that were not used as options or the value of an option.
      java.io.File[] getPlainFiles()
      Returns a copy of all of the arguments that were not used as options or the value of an option as File objects.
      java.lang.String getUsageText()
      Returns the usage text to display when command line help is requested.
      protected void handleParsingError​(java.lang.String message)
      Called when there is an error with the command line syntax.
      protected boolean isCaseSensitive()
      If this returns true, then the matching of option names to fields will be case sensitive.
      protected boolean isHelpOption​(java.lang.String argument)
      Returns true if and only if the supplied argument should be interpreted as a request for help.
      void parse​(java.lang.Object target, java.lang.String... args)
      Parses an application's command line arguments, filling in the matching public fields of target as appropriate.
      protected void setOption​(java.lang.Object target, java.lang.String name, java.lang.reflect.Field field, java.lang.String value)
      This is called by the parser to set the value for an option in its associated field.
      void setUsageText​(java.lang.String commandHelp)
      Sets the usage information to display when command line help is requested.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • CommandLineParser

        public CommandLineParser()
        Creates a new command line parser that matches the public fields of the subclass.

    • Method Detail

      • setUsageText

        public void setUsageText​(java.lang.String commandHelp)
        Sets the usage information to display when command line help is requested.
        Parameters:
        commandHelp - the banner and help information to display

      • getUsageText

        public java.lang.String getUsageText()
        Returns the usage text to display when command line help is requested.
        Returns:
        the help information to display, or null if none set

      • getPlainArguments

        public java.lang.String[] getPlainArguments()
        Returns a copy of all of the arguments that were not used as options or the value of an option. For a typical command line utility, this would be the list of files on which the command is to operate. If the parser has not parsed a command line, or if an error occurred during the last parse, this will return null.
        Returns:
        the unused command line arguments, or null

      • getPlainFiles

        public java.io.File[] getPlainFiles()
        Returns a copy of all of the arguments that were not used as options or the value of an option as File objects. For a typical command line utility, this would be the list of files on which the command is to operate. If the parser has not parsed a command line, or if an error occurred during the last parse, this will return null.
        Returns:
        the unused command line arguments, or null
        See Also:
        getPlainArguments()

      • getOptionName

        protected java.lang.String getOptionName​(java.lang.String argument)
        Returns the name of an option in a command line argument, stripped of its prefix; if the argument does not represent an option, returns null. The base class checks for a prefix of either "--" or "-". If present, it returns the remainder of the argument. Otherwise, it returns null. Subclasses may override this to enforce other conventions.
        Parameters:
        argument - the argument which might represent an option name
        Returns:
        the option name represented, or null if the argument is not an option

      • isCaseSensitive

        protected boolean isCaseSensitive()
        If this returns true, then the matching of option names to fields will be case sensitive. The base class returns false.
        Returns:
        true to make option names case sensitive

      • isHelpOption

        protected boolean isHelpOption​(java.lang.String argument)
        Returns true if and only if the supplied argument should be interpreted as a request for help. The base class returns true for any of: "--help", "-help", "--h", "-?", or "/?".
        Parameters:
        argument - the argument to test
        Returns:
        true if help should be displayed

      • displayUsageText

        protected void displayUsageText​(java.lang.Object target)
        Called to display usage information when help is requested. The base class prints a message to the output stream and exits. If a non-null usage text has been set with setUsageText(java.lang.String), then this will be used as the text to display. If no other usage text is defined, the base class will display a default message that is generated from the fields in the target.
        Parameters:
        target - the object being used as a parsing template

      • handleParsingError

        protected void handleParsingError​(java.lang.String message)
        Called when there is an error with the command line syntax. The base class prints the supplied message, then prints a line inviting the user to use the --help option for more information, and then exits the application with a return code of 20 (indicating an abnormal termination).
        Parameters:
        message - the message to display, or null for the default message "The command line arguments are incorrect"

      • parse

        public void parse​(java.lang.Object target,
                  java.lang.String... args)
        Parses an application's command line arguments, filling in the matching public fields of target as appropriate.
        Parameters:
        target - the object whose fields will be filled in, or null to use this object
        args - the command line arguments to parse

      • setOption

        protected void setOption​(java.lang.Object target,
                         java.lang.String name,
                         java.lang.reflect.Field field,
                         java.lang.String value)
        This is called by the parser to set the value for an option in its associated field.
        Parameters:
        target - the object whose fields should be modified
        name - the name of the option
        field - the field in which the option's value should be placed
        value - the argument from which the option's value must be derived; null if the option takes no value