Package com.aspectran.shell.command.option

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, it's required flag may not be changed anymore.

    See Also:
    Options, ParsedOptions, 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
      static int UNINITIALIZED
      Constant that specifies the number of argument values has not been specified
      static int UNLIMITED_VALUES
      Constant that specifies the number of argument values is infinite

    • Constructor Summary

      Constructors 
      Constructor Description
      Option​(java.lang.String name, boolean hasValue, java.lang.String description)
      Creates an Option using the specified parameters.
      Option​(java.lang.String name, java.lang.String description)
      Creates an Option using the specified parameters.
      Option​(java.lang.String name, java.lang.String longName, boolean hasValue, java.lang.String description)
      Creates an Option using the specified parameters.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addValue​(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 name)
      Returns a Option.Builder to create an Option using descriptive methods.
      Option 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 o)  
      java.lang.String getDescription()
      Retrieve the self-documenting description of this Option
      int getId()
      Returns the id of this Option.
      java.lang.String getKey()
      Returns the 'unique' Option identifier.
      java.lang.String getLongName()
      Retrieve the long name of this Option.
      java.lang.String getName()
      Retrieve the name of this Option.
      int getNumberOfValues()
      Returns the number of argument values this Option can take.
      java.lang.String getValue()
      Returns the specified value of this Option or null if there is no value.
      java.lang.String getValue​(int index)
      Returns the specified value of this Option or null if there is no value.
      java.lang.String getValue​(java.lang.String defaultValue)
      Returns the value/first value of this Option or the defaultValue if there is no value.
      java.lang.String getValueName()
      Gets the display name for the argument value.
      java.lang.String[] getValues()
      Return the values of this Option as a String array or null if there are no values.
      java.util.List<java.lang.String> getValuesList()
      Returns the values of this Option as a List or null if there are no values.
      OptionValueType getValueType()
      Retrieve the type of this Option.
      int hashCode()  
      boolean hasLongName()
      Query to see if this Option has a long name.
      boolean hasOptionalValue()
      Returns whether this Option can have an optional argument.
      boolean hasValue()
      Query to see if this Option requires an argument.
      boolean hasValueName()
      Returns whether the display name for the argument value has been set.
      boolean hasValues()
      Query to see if this Option can take many values.
      boolean isRequired()
      Query to see if this Option is mandatory
      boolean isWithEqualSign()  
      void setDescription​(java.lang.String description)
      Sets the self-documenting description of this Option
      void setLongName​(java.lang.String longName)
      Sets the long name of this Option.
      void setNumberOfValues​(int num)
      Sets the number of argument values this Option can take.
      void setOptionalValue​(boolean optionalValue)
      Sets whether this Option can have an optional argument.
      void setRequired​(boolean required)
      Sets whether this Option is mandatory.
      void setValueName​(java.lang.String valueName)
      Sets the display name for the argument value.
      void setValueType​(OptionValueType valueType)
      Sets the type of this Option.
      void setWithEqualSign​(boolean withEqualSign)  
      java.lang.String toString()
      Dump state, suitable for debugging.
      void withEqualSign()  

      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • UNINITIALIZED

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

      • UNLIMITED_VALUES

        public static final int UNLIMITED_VALUES
        Constant that specifies the number of argument values is infinite
        See Also:
        Constant Field Values

    • Constructor Detail

      • Option

        public Option​(java.lang.String name,
              java.lang.String description)
       throws java.lang.IllegalArgumentException
        Creates an Option using the specified parameters. The option does not take an argument.
        Parameters:
        name - 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 name

      • Option

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

      • Option

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

    • Method Detail

      • getId

        public int getId()
        Returns 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

        public java.lang.String getKey()
        Returns the 'unique' Option identifier.
        Returns:
        the 'unique' Option identifier

      • getLongName

        public java.lang.String getLongName()
        Retrieve the long name of this Option.
        Returns:
        the long name of this Option, or null, if there is no long name

      • setLongName

        public void setLongName​(java.lang.String longName)
        Sets the long name of this Option.
        Parameters:
        longName - the long name of this Option

      • hasLongName

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

      • getValueName

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

      • setValueName

        public void setValueName​(java.lang.String valueName)
        Sets the display name for the argument value.
        Parameters:
        valueName - the display name for the argument value

      • hasValueName

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

      • getValueType

        public OptionValueType getValueType()
        Retrieve the type of this Option.
        Returns:
        the type of this option

      • setValueType

        public void setValueType​(OptionValueType valueType)
        Sets the type of this Option.
        Parameters:
        valueType - the type of this Option

      • setOptionalValue

        public void setOptionalValue​(boolean optionalValue)
        Sets whether this Option can have an optional argument.
        Parameters:
        optionalValue - specifies whether the Option can have an optional argument.

      • hasOptionalValue

        public boolean hasOptionalValue()
        Returns whether this Option can have an optional argument.
        Returns:
        whether this Option can have an optional argument

      • getNumberOfValues

        public int getNumberOfValues()
        Returns 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

      • setNumberOfValues

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

      • hasValue

        public boolean hasValue()
        Query to see if this Option requires an argument.
        Returns:
        boolean flag indicating if an argument is required

      • hasValues

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

      • withEqualSign

        public void withEqualSign()

      • isWithEqualSign

        public boolean isWithEqualSign()

      • setWithEqualSign

        public void setWithEqualSign​(boolean withEqualSign)

      • addValue

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

      • getValue

        public java.lang.String getValue()
        Returns 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
        Returns 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)
        Returns 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()
        Return 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

      • getValuesList

        public java.util.List<java.lang.String> getValuesList()
        Returns 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

      • isRequired

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

      • setRequired

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

      • getDescription

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

      • setDescription

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

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

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

      • clone

        public Option 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()

      • toString

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

      • builder

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