Class Option

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable

    public class Option
    extends java.lang.Object
    implements java.lang.Cloneable, java.io.Serializable
    Describes a single command-line option. It maintains information regarding the short-name of the option, the long-name, if any exists, a flag indicating if an argument is required for this option, and a self-documenting description of the option.

    An Option is not created independently, but is created through an instance of Options. An Option is required to have at least a short or a long-name.

    Note: once an Option has been added to an instance of Options, its required flag cannot be changed.

    See Also:
    Options, CommandLine, Serialized Form
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Option.Builder
      A nested builder class to create Option instances using descriptive methods.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private int argCount
      The number of argument values this option can have.
      private java.lang.String argName
      The name of the argument for this option.
      private java.lang.String description
      Description of the option.
      private java.lang.String longOption
      The long representation of the option.
      private java.lang.String option
      The name of the option.
      private boolean optionalArg
      Specifies whether the argument value of this Option is optional.
      private boolean required
      Specifies whether this option is required to be present.
      private static long serialVersionUID
      The serial version UID.
      private java.lang.Class<?> type
      The type of this Option.
      static int UNINITIALIZED
      Specifies the number of argument values has not been specified
      static int UNLIMITED_VALUES
      Specifies the number of argument values is infinite
      private java.util.List<java.lang.String> values
      The list of argument values.
      private char valuesep
      The character that is the value separator.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        Option​(java.lang.String option, boolean hasArg, java.lang.String description)
      Creates an Option using the specified parameters.
        Option​(java.lang.String option, java.lang.String description)
      Creates an Option using the specified parameters.
        Option​(java.lang.String option, java.lang.String longOption, boolean hasArg, java.lang.String description)
      Creates an Option using the specified parameters.
      private Option​(Option.Builder builder)
      Private constructor used by the nested Builder class.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      (package private) boolean acceptsArg()
      Tells if the option can accept more arguments.
      private void add​(java.lang.String value)
      Add the value to this Option.
      boolean addValue​(java.lang.String value)
      Deprecated.
      Unused.
      (package private) void addValueForProcessing​(java.lang.String value)
      Adds the specified value to this Option.
      static Option.Builder builder()
      Returns a Option.Builder to create an Option using descriptive methods.
      static Option.Builder builder​(java.lang.String option)
      Returns a Option.Builder to create an Option using descriptive methods.
      (package private) void clearValues()
      Clear the Option values.
      java.lang.Object clone()
      A rather odd clone method - due to incorrect code in 1.0 it is public and in 1.1 rather than throwing a CloneNotSupportedException it throws a RuntimeException so as to maintain backwards compat at the API level.
      boolean equals​(java.lang.Object obj)  
      java.lang.String getArgName()
      Gets the display name for the argument value.
      int getArgs()
      Gets the number of argument values this Option can take.
      java.lang.String getDescription()
      Gets the self-documenting description of this Option
      int getId()
      Gets the id of this Option.
      (package private) java.lang.String getKey()
      Gets the 'unique' Option identifier.
      java.lang.String getLongOpt()
      Gets the long name of this Option.
      java.lang.String getOpt()
      Gets the name of this Option.
      java.lang.Object getType()
      Gets the type of this Option.
      java.lang.String getValue()
      Gets the specified value of this Option or null if there is no value.
      java.lang.String getValue​(int index)
      Gets the specified value of this Option or null if there is no value.
      java.lang.String getValue​(java.lang.String defaultValue)
      Gets the value/first value of this Option or the defaultValue if there is no value.
      java.lang.String[] getValues()
      Gets the values of this Option as a String array or null if there are no values
      char getValueSeparator()
      Gets the value separator character.
      java.util.List<java.lang.String> getValuesList()
      Gets the values of this Option as a List or null if there are no values.
      boolean hasArg()
      Query to see if this Option requires an argument
      boolean hasArgName()
      Returns whether the display name for the argument value has been set.
      boolean hasArgs()
      Query to see if this Option can take many values.
      int hashCode()  
      boolean hasLongOpt()
      Query to see if this Option has a long name
      private boolean hasNoValues()
      Returns whether this Option has any values.
      boolean hasOptionalArg()  
      boolean hasValueSeparator()
      Return whether this Option has specified a value separator.
      boolean isRequired()
      Query to see if this Option is mandatory
      private void processValue​(java.lang.String value)
      Processes the value.
      (package private) boolean requiresArg()
      Tells if the option requires more arguments to be valid.
      void setArgName​(java.lang.String argName)
      Sets the display name for the argument value.
      void setArgs​(int num)
      Sets the number of argument values this Option can take.
      void setDescription​(java.lang.String description)
      Sets the self-documenting description of this Option
      void setLongOpt​(java.lang.String longOpt)
      Sets the long name of this Option.
      void setOptionalArg​(boolean optionalArg)
      Sets whether this Option can have an optional argument.
      void setRequired​(boolean required)
      Sets whether this Option is mandatory.
      void setType​(java.lang.Class<?> type)
      Sets the type of this Option.
      void setType​(java.lang.Object type)
      Deprecated.
      since 1.3, use setType(Class) instead
      void setValueSeparator​(char sep)
      Sets the value separator.
      java.lang.String toString()
      Dump state, suitable for debugging.
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • UNINITIALIZED

        public static final int UNINITIALIZED
        Specifies the number of argument values has not been specified
        See Also:
        Constant Field Values
      • UNLIMITED_VALUES

        public static final int UNLIMITED_VALUES
        Specifies the number of argument values is infinite
        See Also:
        Constant Field Values
      • serialVersionUID

        private static final long serialVersionUID
        The serial version UID.
        See Also:
        Constant Field Values
      • option

        private final java.lang.String option
        The name of the option.
      • longOption

        private java.lang.String longOption
        The long representation of the option.
      • argName

        private java.lang.String argName
        The name of the argument for this option.
      • description

        private java.lang.String description
        Description of the option.
      • required

        private boolean required
        Specifies whether this option is required to be present.
      • optionalArg

        private boolean optionalArg
        Specifies whether the argument value of this Option is optional.
      • argCount

        private int argCount
        The number of argument values this option can have.
      • type

        private java.lang.Class<?> type
        The type of this Option.
      • values

        private java.util.List<java.lang.String> values
        The list of argument values.
      • valuesep

        private char valuesep
        The character that is the value separator.
    • Constructor Detail

      • Option

        private Option​(Option.Builder builder)
        Private constructor used by the nested Builder class.
        Parameters:
        builder - builder used to create this option
      • Option

        public Option​(java.lang.String option,
                      boolean hasArg,
                      java.lang.String description)
               throws java.lang.IllegalArgumentException
        Creates an Option using the specified parameters.
        Parameters:
        option - short representation of the option
        hasArg - specifies whether the Option takes an argument or not
        description - describes the function of the option
        Throws:
        java.lang.IllegalArgumentException - if there are any non valid Option characters in opt.
      • Option

        public Option​(java.lang.String option,
                      java.lang.String description)
               throws java.lang.IllegalArgumentException
        Creates an Option using the specified parameters. The option does not take an argument.
        Parameters:
        option - short representation of the option
        description - describes the function of the option
        Throws:
        java.lang.IllegalArgumentException - if there are any non valid Option characters in opt.
      • Option

        public Option​(java.lang.String option,
                      java.lang.String longOption,
                      boolean hasArg,
                      java.lang.String description)
               throws java.lang.IllegalArgumentException
        Creates an Option using the specified parameters.
        Parameters:
        option - short representation of the option
        longOption - the long representation of the option
        hasArg - specifies whether the Option takes an argument or not
        description - describes the function of the option
        Throws:
        java.lang.IllegalArgumentException - if there are any non valid Option characters in opt.
    • Method Detail

      • builder

        public static Option.Builder builder​(java.lang.String option)
        Returns a Option.Builder to create an Option using descriptive methods.
        Parameters:
        option - short representation of the option
        Returns:
        a new Option.Builder instance
        Throws:
        java.lang.IllegalArgumentException - if there are any non valid Option characters in opt
        Since:
        1.3
      • acceptsArg

        boolean acceptsArg()
        Tells if the option can accept more arguments.
        Returns:
        false if the maximum number of arguments is reached
        Since:
        1.3
      • add

        private void add​(java.lang.String value)
        Add the value to this Option. If the number of arguments is greater than zero and there is enough space in the list then add the value. Otherwise, throw a runtime exception.
        Parameters:
        value - The value to be added to this Option
        Since:
        1.0.1
      • addValue

        @Deprecated
        public boolean addValue​(java.lang.String value)
        Deprecated.
        Unused.
        This method is not intended to be used. It was a piece of internal API that was made public in 1.0. It currently throws an UnsupportedOperationException.
        Parameters:
        value - the value to add
        Returns:
        always throws an UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException - always
      • addValueForProcessing

        void addValueForProcessing​(java.lang.String value)
        Adds the specified value to this Option.
        Parameters:
        value - is a/the value of this Option
      • clearValues

        void clearValues()
        Clear the Option values. After a parse is complete, these are left with data in them and they need clearing if another parse is done. See: CLI-71
      • clone

        public java.lang.Object clone()
        A rather odd clone method - due to incorrect code in 1.0 it is public and in 1.1 rather than throwing a CloneNotSupportedException it throws a RuntimeException so as to maintain backwards compat at the API level. After calling this method, it is very likely you will want to call clearValues().
        Overrides:
        clone in class java.lang.Object
        Returns:
        a clone of this Option instance
        Throws:
        java.lang.RuntimeException - if a CloneNotSupportedException has been thrown by super.clone()
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • getArgName

        public java.lang.String getArgName()
        Gets the display name for the argument value.
        Returns:
        the display name for the argument value.
      • getArgs

        public int getArgs()
        Gets the number of argument values this Option can take.

        A value equal to the constant UNINITIALIZED (= -1) indicates the number of arguments has not been specified. A value equal to the constant UNLIMITED_VALUES (= -2) indicates that this options takes an unlimited amount of values.

        Returns:
        num the number of argument values
        See Also:
        UNINITIALIZED, UNLIMITED_VALUES
      • getDescription

        public java.lang.String getDescription()
        Gets the self-documenting description of this Option
        Returns:
        The string description of this option
      • getId

        public int getId()
        Gets the id of this Option. This is only set when the Option shortOpt is a single character. This is used for switch statements.
        Returns:
        the id of this Option
      • getKey

        java.lang.String getKey()
        Gets the 'unique' Option identifier.
        Returns:
        the 'unique' Option identifier
      • getLongOpt

        public java.lang.String getLongOpt()
        Gets the long name of this Option.
        Returns:
        Long name of this option, or null, if there is no long name
      • getType

        public java.lang.Object getType()
        Gets the type of this Option.
        Returns:
        The type of this option
      • getValue

        public java.lang.String getValue()
        Gets the specified value of this Option or null if there is no value.
        Returns:
        the value/first value of this Option or null if there is no value.
      • getValue

        public java.lang.String getValue​(int index)
                                  throws java.lang.IndexOutOfBoundsException
        Gets the specified value of this Option or null if there is no value.
        Parameters:
        index - The index of the value to be returned.
        Returns:
        the specified value of this Option or null if there is no value.
        Throws:
        java.lang.IndexOutOfBoundsException - if index is less than 1 or greater than the number of the values for this Option.
      • getValue

        public java.lang.String getValue​(java.lang.String defaultValue)
        Gets the value/first value of this Option or the defaultValue if there is no value.
        Parameters:
        defaultValue - The value to be returned if there is no value.
        Returns:
        the value/first value of this Option or the defaultValue if there are no values.
      • getValues

        public java.lang.String[] getValues()
        Gets the values of this Option as a String array or null if there are no values
        Returns:
        the values of this Option as a String array or null if there are no values
      • getValueSeparator

        public char getValueSeparator()
        Gets the value separator character.
        Returns:
        the value separator character.
      • getValuesList

        public java.util.List<java.lang.String> getValuesList()
        Gets the values of this Option as a List or null if there are no values.
        Returns:
        the values of this Option as a List or null if there are no values
      • hasArg

        public boolean hasArg()
        Query to see if this Option requires an argument
        Returns:
        boolean flag indicating if an argument is required
      • hasArgName

        public boolean hasArgName()
        Returns whether the display name for the argument value has been set.
        Returns:
        if the display name for the argument value has been set.
      • hasArgs

        public boolean hasArgs()
        Query to see if this Option can take many values.
        Returns:
        boolean flag indicating if multiple values are allowed
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • hasLongOpt

        public boolean hasLongOpt()
        Query to see if this Option has a long name
        Returns:
        boolean flag indicating existence of a long name
      • hasNoValues

        private boolean hasNoValues()
        Returns whether this Option has any values.
        Returns:
        whether this Option has any values.
      • hasOptionalArg

        public boolean hasOptionalArg()
        Returns:
        whether this Option can have an optional argument
      • hasValueSeparator

        public boolean hasValueSeparator()
        Return whether this Option has specified a value separator.
        Returns:
        whether this Option has specified a value separator.
        Since:
        1.1
      • isRequired

        public boolean isRequired()
        Query to see if this Option is mandatory
        Returns:
        boolean flag indicating whether this Option is mandatory
      • processValue

        private void processValue​(java.lang.String value)
        Processes the value. If this Option has a value separator the value will have to be parsed into individual tokens. When n-1 tokens have been processed and there are more value separators in the value, parsing is ceased and the remaining characters are added as a single token.
        Parameters:
        value - The String to be processed.
        Since:
        1.0.1
      • requiresArg

        boolean requiresArg()
        Tells if the option requires more arguments to be valid.
        Returns:
        false if the option doesn't require more arguments
        Since:
        1.3
      • setArgName

        public void setArgName​(java.lang.String argName)
        Sets the display name for the argument value.
        Parameters:
        argName - the display name for the argument value.
      • setArgs

        public void setArgs​(int num)
        Sets the number of argument values this Option can take.
        Parameters:
        num - the number of argument values
      • setDescription

        public void setDescription​(java.lang.String description)
        Sets the self-documenting description of this Option
        Parameters:
        description - The description of this option
        Since:
        1.1
      • setLongOpt

        public void setLongOpt​(java.lang.String longOpt)
        Sets the long name of this Option.
        Parameters:
        longOpt - the long name of this Option
      • setOptionalArg

        public void setOptionalArg​(boolean optionalArg)
        Sets whether this Option can have an optional argument.
        Parameters:
        optionalArg - specifies whether the Option can have an optional argument.
      • setRequired

        public void setRequired​(boolean required)
        Sets whether this Option is mandatory.
        Parameters:
        required - specifies whether this Option is mandatory
      • setType

        public void setType​(java.lang.Class<?> type)
        Sets the type of this Option.
        Parameters:
        type - the type of this Option
        Since:
        1.3
      • setType

        @Deprecated
        public void setType​(java.lang.Object type)
        Deprecated.
        since 1.3, use setType(Class) instead
        Sets the type of this Option.

        Note: this method is kept for binary compatibility and the input type is supposed to be a Class object.

        Parameters:
        type - the type of this Option
      • setValueSeparator

        public void setValueSeparator​(char sep)
        Sets the value separator. For example if the argument value was a Java property, the value separator would be '='.
        Parameters:
        sep - The value separator.
      • toString

        public java.lang.String toString()
        Dump state, suitable for debugging.
        Overrides:
        toString in class java.lang.Object
        Returns:
        Stringified form of this object