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:

  • 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

  • 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:

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