Package Apache.CLI



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
    This Class-File has been copied, directly from the Apache Commons Software Foundation. Other than the minor, cosmetic changes (mentioned in the second-list below), this file is perfectly identical to the original that may be found on the Apache Website: apache.org.

    1. The suggested license for using this file may be read here: Apache License
    2. The Source-Code Header for this file may be viewed here: Source-File Header
    3. Partial contents of the 'site/resources/images' directory: Resource Images

    Notes about changes that have been made as a result of the import process:

    • Within all files, the original Package-Name declaration has been changed:
      Original:   package org.apache.commons.cli;
      Updated:   package Apache.CLI;

    • All Classes and Class-Members (Methods, Fields, etc...) that were previously Annotated with the @Deprecated Annotation have been summarily removed.

    • Code Formattings and Styling has been heavily modified to conform to the Standard Java-HTML Indentation & Styling Choices. The code itself remains identical, with only a few squiggly-braces '{' and '}' being removed, for cosmetic reasons (and for lowering "Developer Stress" Levels)..
    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
      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

    • Constructor Summary

      Constructors 
      Constructor Description
      Option​(String option, boolean hasArg, String description)
      Creates an Option using the specified parameters.
      Option​(String option, String description)
      Creates an Option using the specified parameters.
      Option​(String option, String longOption, boolean hasArg, String description)
      Creates an Option using the specified parameters.

    • Method Summary

       
      Create an Option-Builder Instance
      Modifier and Type Method
      static Option.Builder builder()
      Returns a Option.Builder to create an Option using descriptive methods.
      static Option.Builder builder​(String option)
      Returns a Option.Builder to create an Option using descriptive methods.
       
      Retrieve an Option's Post-Processed Values
      Modifier and Type Method
      String getValue()
      Gets the specified value of this Option or null if there is no value.
      String getValue​(int index)
      Gets the specified value of this Option or null if there is no value.
      String getValue​(String defaultValue)
      Gets the value/first value of this Option or the defaultValue if there is no value.
      String[] getValues()
      Gets the values of this Option as a String array or null if there are no values
      List<String> getValuesList()
      Gets the values of this Option as a List or null if there are no values.
       
      Retrieve & Review an Option's Initial Configurations
      Modifier and Type Method
      String getArgName()
      Gets the display name for the argument value.
      int getArgs()
      Gets the number of argument values this Option can take.
      String getDescription()
      Gets the self-documenting description of this Option
      int getId()
      Gets the id of this Option.
      String getLongOpt()
      Gets the long name of this Option.
      String getOpt()
      Gets the name of this Option.
      Object getType()
      Gets the type of this Option.
      char getValueSeparator()
      Gets the value separator character.
       
      Retrieve & Review an Option's Initial Configurations, as a Yes/No Boolean
      Modifier and Type Method
      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.
      boolean hasLongOpt()
      Query to see if this Option has a long name
      boolean hasOptionalArg()  
      boolean hasValueSeparator()
      Return whether this Option has specified a value separator.
      boolean isRequired()
      Query to see if this Option is mandatory
       
      Set Option-Configurations
      Modifier and Type Method
      void setArgName​(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​(String description)
      Sets the self-documenting description of this Option
      void setLongOpt​(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​(Class<?> type)
      Sets the type of this Option.
      void setValueSeparator​(char sep)
      Sets the value separator.
       
      Methods: class java.lang.Object
      Modifier and Type Method
      boolean equals​(Object obj)  
      int hashCode()  
      String toString()
      Dump state, suitable for debugging.
       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method
      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.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • 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
        Code:
        Exact Method Body:
         return new Builder(option);

      • 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()
        Code:
        Exact Method Body:
         try
 {
     final Option option = (Option) super.clone();
     option.values = new ArrayList<>(values);
     return option;
 }

 catch (final CloneNotSupportedException e)
     { throw new UnsupportedOperationException(e.getMessage(), e); }

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
        Code:
        Exact Method Body:
         if (this == obj)                return true;
 if (!(obj instanceof Option))   return false;

 final Option other = (Option) obj;
    
 return  Objects.equals(longOption, other.longOption)
     &&  Objects.equals(option, other.option);

      • getArgName

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String getArgName()
        Gets the display name for the argument value.
        Returns:
        the display name for the argument value.
        Code:
        Exact Method Body:
         return argName;

      • 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
        Code:
        Exact Method Body:
         return argCount;

      • getDescription

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String getDescription()
        Gets the self-documenting description of this Option
        Returns:
        The string description of this option
        Code:
        Exact Method Body:
         return description;

      • 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
        Code:
        Exact Method Body:
         return getKey().charAt(0);

      • 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
        Code:
        Exact Method Body:
         return longOption;

      • getType

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.Object getType()
        Gets the type of this Option.
        Returns:
        The type of this option
        Code:
        Exact Method Body:
         return type;

      • 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.
        Code:
        Exact Method Body:
         return hasNoValues() ? null : values.get(0);

      • 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.
        Code:
        Exact Method Body:
         return hasNoValues() ? null : values.get(index);

      • 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.
        Code:
        Exact Method Body:
         final String value = getValue();
 return value != null ? value : defaultValue;

      • 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
        Code:
        Exact Method Body:
         return hasNoValues() ? null : values.toArray(EMPTY_STRING_ARRAY);

      • 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
        Code:
        Exact Method Body:
         return values;

      • hasArg

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean hasArg()
        Query to see if this Option requires an argument
        Returns:
        boolean flag indicating if an argument is required
        Code:
        Exact Method Body:
         return argCount > 0 || argCount == UNLIMITED_VALUES;

      • 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.
        Code:
        Exact Method Body:
         return argName != null && !argName.isEmpty();

      • hasArgs

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean hasArgs()
        Query to see if this Option can take many values.
        Returns:
        boolean flag indicating if multiple values are allowed
        Code:
        Exact Method Body:
         return argCount > 1 || argCount == UNLIMITED_VALUES;

      • hashCode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
        Code:
        Exact Method Body:
         return Objects.hash(longOption, option);

      • hasLongOpt

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean hasLongOpt()
        Query to see if this Option has a long name
        Returns:
        boolean flag indicating existence of a long name
        Code:
        Exact Method Body:
         return longOption != null;

      • hasValueSeparator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean hasValueSeparator()
        Return whether this Option has specified a value separator.
        Returns:
        whether this Option has specified a value separator.
        Code:
        Exact Method Body:
         return valuesep > 0;

      • isRequired

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean isRequired()
        Query to see if this Option is mandatory
        Returns:
        boolean flag indicating whether this Option is mandatory
        Code:
        Exact Method Body:
         return required;

      • 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.
        Code:
        Exact Method Body:
         this.argName = argName;

      • setArgs

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setArgs​(int num)
        Sets the number of argument values this Option can take.
        Parameters:
        num - the number of argument values
        Code:
        Exact Method Body:
         this.argCount = num;

      • setDescription

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setDescription​(java.lang.String description)
        Sets the self-documenting description of this Option
        Parameters:
        description - The description of this option
        Code:
        Exact Method Body:
         this.description = description;

      • setLongOpt

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setLongOpt​(java.lang.String longOpt)
        Sets the long name of this Option.
        Parameters:
        longOpt - the long name of this Option
        Code:
        Exact Method Body:
         this.longOption = longOpt;

      • 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.
        Code:
        Exact Method Body:
         this.optionalArg = optionalArg;

      • setRequired

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setRequired​(boolean required)
        Sets whether this Option is mandatory.
        Parameters:
        required - specifies whether this Option is mandatory
        Code:
        Exact Method Body:
         this.required = required;

      • setType

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void setType​(java.lang.Class<?> type)
        Sets the type of this Option.
        Parameters:
        type - the type of this Option
        Code:
        Exact Method Body:
         this.type = type;

      • 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.
        Code:
        Exact Method Body:
         this.valuesep = sep;

      • toString

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Dump state, suitable for debugging.
        Overrides:
        toString in class java.lang.Object
        Returns:
        Stringified form of this object
        Code:
        Exact Method Body:
         final StringBuilder buf = new StringBuilder().append("[ option: ");

 buf.append(option);

 if (longOption != null) buf.append(" ").append(longOption);

 buf.append(" ");

 if (hasArgs())      buf.append("[ARG...]");
 else if (hasArg())  buf.append(" [ARG]");

 buf.append(" :: ").append(description);

 if (type != null) buf.append(" :: ").append(type);

 buf.append(" ]");

 return buf.toString();