Package org.apache.commons.cli

# Class Option

java.lang.Object
org.apache.commons.cli.Option

All Implemented Interfaces:
  `Serializable`, `Cloneable`

public class Option extends Object implements Cloneable, 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 final class`
  `Option.Builder`
  Builds `Option` instances using descriptive methods.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `UNINITIALIZED`
  Specifies the number of argument values has not been specified.
  `static final 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

  Modifier and Type
  Method
  Description
  `boolean`
  `addValue(String value)`
  Deprecated.
  Unused.
  `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.
  `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 compatible at the API level.
  `boolean`
  `equals(Object obj)`
  `String`
  `getArgName()`
  Gets the display name for the argument value.
  `int`
  `getArgs()`
  Gets the number of argument values this Option can take.
  `Converter<?,?>`
  `getConverter()`
  Gets the value to type converter.
  `DeprecatedAttributes`
  `getDeprecated()`
  Gets deprecated attributes if any.
  `String`
  `getDescription()`
  Gets the self-documenting description of this Option.
  `int`
  `getId()`
  Gets the id of this Option.
  `String`
  `getKey()`
  Gets the 'unique' Option identifier.
  `String`
  `getLongOpt()`
  Gets the long name of this Option.
  `String`
  `getOpt()`
  Gets the name of this Option.
  `String`
  `getSince()`
  Gets the version when this option was added.
  `Object`
  `getType()`
  Gets the type of this Option.
  `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.
  `char`
  `getValueSeparator()`
  Gets the value separator character.
  `List<String>`
  `getValuesList()`
  Gets the values of this Option as a List or null if there are no values.
  `boolean`
  `hasArg()`
  Tests whether this Option requires an argument.
  `boolean`
  `hasArgName()`
  Tests whether the display name for the argument value has been set.
  `boolean`
  `hasArgs()`
  Tests whether this Option can take many values.
  `int`
  `hashCode()`
  `boolean`
  `hasLongOpt()`
  Tests whether this Option has a long name.
  `boolean`
  `hasOptionalArg()`
  Tests whether this Option can have an optional argument.
  `boolean`
  `hasValueSeparator()`
  Tests whether this Option has specified a value separator.
  `boolean`
  `isDeprecated()`
  Tests whether this Option is deprecated.
  `boolean`
  `isRequired()`
  Tests whether this Option is required.
  `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`
  `setConverter(Converter<?,?> converter)`
  Sets the value to type converter.
  `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`
  `setType(Object type)`
  Deprecated.
  since 1.3, use `setType(Class)` instead.
  `void`
  `setValueSeparator(char valueSeparator)`
  Sets the value separator.
  `String`
  `toString()`
  Creates a String suitable for debugging.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

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

- ## Constructor Details

  - ### Option

    public Option(String option, boolean hasArg, String description) throws 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:
      `IllegalArgumentException` - if there are any non valid Option characters in `opt`.

  - ### Option

    public Option(String option, String description) throws 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:
      `IllegalArgumentException` - if there are any non valid Option characters in `opt`.

  - ### Option

    public Option(String option, String longOption, boolean hasArg, String description) throws 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:
      `IllegalArgumentException` - if there are any non valid Option characters in `opt`.

- ## Method Details

  - ### 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(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:
      `IllegalArgumentException` - if there are any non valid Option characters in `opt`.
    Since:
      1.3

  - ### addValue

    @Deprecated public boolean addValue(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:
      `UnsupportedOperationException` - always.

  - ### clone

    public 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 compatible at the API level. After calling this method, it is very likely you will want to call clearValues().
    Overrides:
      `clone` in class `Object`
    Returns:
      a clone of this Option instance.
    Throws:
      `RuntimeException` - if a `CloneNotSupportedException` has been thrown by `super.clone()`.

  - ### equals

    public boolean equals(Object obj)
    Overrides:
      `equals` in class `Object`

  - ### getArgName

    public 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`

  - ### getConverter

    public Converter<?,?> getConverter()
    Gets the value to type converter.
    Returns:
      the value to type converter.
    Since:
      1.7.0

  - ### getDeprecated

    public DeprecatedAttributes getDeprecated()
    Gets deprecated attributes if any.
    Returns:
      boolean deprecated attributes or null.
    Since:
      1.7.0

  - ### getDescription

    public 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

    public String getKey()
    Gets the 'unique' Option identifier. This is the option value if set or the long value if the options value is not set.
    Returns:
      the 'unique' Option identifier.
    Since:
      1.7.0

  - ### getLongOpt

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

  - ### getOpt

    public String getOpt()
    Gets 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.

  - ### getSince

    public String getSince()
    Gets the version when this option was added.
    Returns:
      the version when this option was added, or `null` if not set.

  - ### getType

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

  - ### getValue

    public 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 String getValue(int index) throws 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:
      `IndexOutOfBoundsException` - if index is less than 1 or greater than the number of the values for this Option.

  - ### getValue

    public String getValue(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 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 List<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()
    Tests whether this Option requires an argument.
    Returns:
      boolean flag indicating if an argument is required.

  - ### hasArgName

    public boolean hasArgName()
    Tests 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()
    Tests whether this Option can take many values.
    Returns:
      boolean flag indicating if multiple values are allowed.

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### hasLongOpt

    public boolean hasLongOpt()
    Tests whether this Option has a long name.
    Returns:
      boolean flag indicating existence of a long name.

  - ### hasOptionalArg

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

  - ### hasValueSeparator

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

  - ### isDeprecated

    public boolean isDeprecated()
    Tests whether this Option is deprecated.
    Returns:
      boolean flag indicating whether this Option is deprecated.
    Since:
      1.7.0

  - ### isRequired

    public boolean isRequired()
    Tests whether this Option is required.
    Returns:
      boolean flag indicating whether this Option is required.

  - ### setArgName

    public void setArgName(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.

  - ### setConverter

    public void setConverter(Converter<?,?> converter)
    Sets the value to type converter.
    Parameters:
      `converter` - The converter to convert the string value to the type.
    Since:
      1.7.0

  - ### setDescription

    public void setDescription(String description)
    Sets the self-documenting description of this Option.
    Parameters:
      `description` - The description of this option.
    Since:
      1.1

  - ### setLongOpt

    public void setLongOpt(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(Class<?> type)
    Sets the type of this Option.
    Parameters:
      `type` - the type of this Option.
    Since:
      1.3

  - ### setType

    @Deprecated public void setType(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 valueSeparator)
    Sets the value separator. For example if the argument value was a Java property, the value separator would be '='.
    Parameters:
      `valueSeparator` - The value separator.

  - ### toString

    public String toString()
    Creates a String suitable for debugging.
    Overrides:
      `toString` in class `Object`
    Returns:
      a String suitable for debugging.