Option
Date: 2017-04-22

org.apache.commons.cli

## Class Option

- java.lang.Object
- - org.apache.commons.cli.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`, `CommandLine`, Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Option.Builder` A nested builder class to create `Option` instances using descriptive methods.

  - ### Field Summary

    Fields
    Modifier and Type | Field and 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 and Description
    `Option(java.lang.String opt, boolean hasArg, java.lang.String description)` Creates an Option using the specified parameters.
    `Option(java.lang.String opt, java.lang.String description)` Creates an Option using the specified parameters.
    `Option(java.lang.String opt, java.lang.String longOpt, boolean hasArg, java.lang.String description)` Creates an Option using the specified parameters.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addValue(java.lang.String value)` Deprecated.
    `static Option.Builder` | `builder()` Returns a `Option.Builder` to create an `Option` using descriptive methods.
    `static Option.Builder` | `builder(java.lang.String opt)` Returns a `Option.Builder` to create an `Option` using descriptive methods.
    `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 o)`
    `java.lang.String` | `getArgName()` Gets the display name for the argument value.
    `int` | `getArgs()` Returns the number of argument values this Option can take.
    `java.lang.String` | `getDescription()` Retrieve the self-documenting description of this Option
    `int` | `getId()` Returns the id of this Option.
    `java.lang.String` | `getLongOpt()` Retrieve the long name of this Option.
    `java.lang.String` | `getOpt()` Retrieve the name of this Option.
    `java.lang.Object` | `getType()` Retrieve the type of this Option.
    `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[]` | `getValues()` Return the values of this Option as a String array or null if there are no values
    `char` | `getValueSeparator()` Returns the value separator character.
    `java.util.List<java.lang.String>` | `getValuesList()`
    `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
    `boolean` | `hasOptionalArg()`
    `boolean` | `hasValueSeparator()` Return whether this Option has specified a value separator.
    `boolean` | `isRequired()` Query to see if this Option is mandatory
    `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

      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 opt,
                java.lang.String description)
                 throws java.lang.IllegalArgumentException

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

      Creates an Option using the specified parameters.
      Parameters:
        `opt` - 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 opt,
                java.lang.String longOpt,
                boolean hasArg,
                java.lang.String description)
                 throws java.lang.IllegalArgumentException

      Creates an Option using the specified parameters.
      Parameters:
        `opt` - short representation of the option
        `longOpt` - 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

    - #### 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

    - #### getOpt

          public java.lang.String getOpt()

      Retrieve the name of this Option. It is this String which can be used with `CommandLine.hasOption(String opt)` and `CommandLine.getOptionValue(String opt)` to check for existence and argument.
      Returns:
        The name of this option

    - #### getType

          public java.lang.Object getType()

      Retrieve the type of this Option.
      Returns:
        The type of this option

    - #### 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

    - #### setType

          public void setType(java.lang.Class<?> type)

      Sets the type of this Option.
      Parameters:
        `type` - the type of this Option
      Since:
        1.3

    - #### getLongOpt

          public java.lang.String getLongOpt()

      Retrieve the long name of this Option.
      Returns:
        Long name of this option, or null, if there is no long name

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

    - #### hasOptionalArg

          public boolean hasOptionalArg()

      Returns:
        whether this Option can have an optional argument

    - #### hasLongOpt

          public boolean hasLongOpt()

      Query to see if this Option has a long name
      Returns:
        boolean flag indicating existence of a long name

    - #### hasArg

          public boolean hasArg()

      Query to see if this Option requires an argument
      Returns:
        boolean flag indicating if an argument is required

    - #### 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
      Since:
        1.1

    - #### 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

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

    - #### getArgName

          public java.lang.String getArgName()

      Gets the display name for the argument value.
      Returns:
        the display name for the argument value.

    - #### 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

    - #### setArgs

          public void setArgs(int num)

      Sets the number of argument values this Option can take.
      Parameters:
        `num` - the number of argument values

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

    - #### getValueSeparator

          public char getValueSeparator()

      Returns the value separator character.
      Returns:
        the value separator character.

    - #### 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

    - #### getArgs

          public int getArgs()

      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`

    - #### 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

    - #### toString

          public java.lang.String toString()

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

    - #### 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 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()`

    - #### addValue

          @Deprecated
          public boolean addValue(java.lang.String value)

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

    - #### builder

          public static Option.Builder builder()

      Returns a `Option.Builder` to create an `Option` using descriptive methods.
      Returns:
        a new `Option.Builder` instance
      Since:
        1.3

    - #### builder

          public static Option.Builder builder(java.lang.String opt)

      Returns a `Option.Builder` to create an `Option` using descriptive methods.
      Parameters:
        `opt` - 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