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

Version:
$Id: Option.java 1756753 2016-08-18 10:18:43Z britter $
See Also:

  • Nested Class Summary

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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private String
    argName
    the name of the argument for this option
    private String
    description
    description of the option
    private String
    longOpt
    the long representation of the option
    private int
    numberOfArgs
    the number of argument values this option can have
    private final String
    opt
    the name of the option
    private boolean
    optionalArg
    specifies whether the argument value of this Option is optional
    private boolean
    required
    specifies whether this option is required to be present
    private static final long
    serialVersionUID
    The serial version UID.
    private Class<?>
    type
    the type of this Option
    static final int
    UNINITIALIZED
    constant that specifies the number of argument values has not been specified
    static final int
    UNLIMITED_VALUES
    constant that specifies the number of argument values is infinite
    private List<String>
    values
    the list of argument values
    private char
    valuesep
    the character that is the value separator

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
     
    Option(String opt, boolean hasArg, String description)
    Creates an Option using the specified parameters.
     
    Option(String opt, String description)
    Creates an Option using the specified parameters.
     
    Option(String opt, String longOpt, boolean hasArg, String description)
    Creates an Option using the specified parameters.
    private
    Option(Option.Builder builder)
    Private constructor used by the nested Builder class.

  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) boolean
    acceptsArg()
    Tells if the option can accept more arguments.
    private void
    add(String value)
    Add the value to this Option.
    boolean
    addValue(String value)
    Deprecated. 
    (package private) void
    addValueForProcessing(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(String opt)
    Returns a Option.Builder to create an Option using descriptive methods.
    (package private) void
    clearValues()
    Clear the Option values.
    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(Object o)
     
    String
    getArgName()
    Gets the display name for the argument value.
    int
    getArgs()
    Returns the number of argument values this Option can take.
    String
    getDescription()
    Retrieve the self-documenting description of this Option
    int
    getId()
    Returns the id of this Option.
    (package private) String
    getKey()
    Returns the 'unique' Option identifier.
    String
    getLongOpt()
    Retrieve the long name of this Option.
    String
    getOpt()
    Retrieve the name of this Option.
    Object
    getType()
    Retrieve the type of this Option.
    String
    getValue()
    Returns the specified value of this Option or null if there is no value.
    String
    getValue(int index)
    Returns the specified value of this Option or null if there is no value.
    String
    getValue(String defaultValue)
    Returns the value/first value of this Option or the defaultValue if there is no value.
    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.
    List<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
    private boolean
    hasNoValues()
    Returns whether this Option has any values.
    boolean
    hasOptionalArg()
     
    boolean
    hasValueSeparator()
    Return whether this Option has specified a value separator.
    boolean
    isRequired()
    Query to see if this Option is mandatory
    private void
    processValue(String value)
    Processes the value.
    (package private) boolean
    requiresArg()
    Tells if the option requires more arguments to be valid.
    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
    setType(Object type)
    Deprecated.
    since 1.3, use setType(Class) instead
    void
    setValueSeparator(char sep)
    Sets the value separator.
    String
    toString()
    Dump state, 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
      constant that specifies the number of argument values has not been specified
      See Also:

    • UNLIMITED_VALUES

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

    • serialVersionUID

      private static final long serialVersionUID
      The serial version UID.
      See Also:

    • opt

      private final String opt
      the name of the option

    • longOpt

      private String longOpt
      the long representation of the option

    • argName

      private String argName
      the name of the argument for this option

    • description

      private String description
      description of the option

    • required

      private boolean required
      specifies whether this option is required to be present

    • optionalArg

      private boolean optionalArg
      specifies whether the argument value of this Option is optional

    • numberOfArgs

      private int numberOfArgs
      the number of argument values this option can have

    • type

      private Class<?> type
      the type of this Option

    • values

      private List<String> values
      the list of argument values

    • valuesep

      private char valuesep
      the character that is the value separator

  • Constructor Details

    • Option

      private Option(Option.Builder builder)
      Private constructor used by the nested Builder class.
      Parameters:
      builder - builder used to create this option

    • Option

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

    • Option

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

    • Option

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

  • Method Details

    • 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

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

    • getOpt

      public 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 Object getType()
      Retrieve the type of this Option.
      Returns:
      The type of this option

    • 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

    • setType

      public void setType(Class<?> type)
      Sets the type of this Option.
      Parameters:
      type - the type of this Option
      Since:
      1.3

    • getLongOpt

      public 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(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 String getDescription()
      Retrieve the self-documenting description of this Option
      Returns:
      The string description of this option

    • setDescription

      public void setDescription(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(String argName)
      Sets the display name for the argument value.
      Parameters:
      argName - the display name for the argument value.

    • getArgName

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

    • addValueForProcessing

      void addValueForProcessing(String value)
      Adds the specified value to this Option.
      Parameters:
      value - is a/the value of this Option

    • processValue

      private void processValue(String value)
      Processes the value. If this Option has a value separator the value will have to be parsed into individual tokens. When n-1 tokens have been processed and there are more value separators in the value, parsing is ceased and the remaining characters are added as a single token.
      Parameters:
      value - The String to be processed.
      Since:
      1.0.1

    • add

      private void add(String value)
      Add the value to this Option. If the number of arguments is greater than zero and there is enough space in the list then add the value. Otherwise, throw a runtime exception.
      Parameters:
      value - The value to be added to this Option
      Since:
      1.0.1

    • getValue

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

    • getValue

      public String getValue(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 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 List<String> getValuesList()
      Returns:
      the values of this Option as a List or null if there are no values

    • toString

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

    • hasNoValues

      private boolean hasNoValues()
      Returns whether this Option has any values.
      Returns:
      whether this Option has any values.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • 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 compat 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()

    • clearValues

      void clearValues()
      Clear the Option values. After a parse is complete, these are left with data in them and they need clearing if another parse is done. See: CLI-71

    • addValue

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

    • acceptsArg

      boolean acceptsArg()
      Tells if the option can accept more arguments.
      Returns:
      false if the maximum number of arguments is reached
      Since:
      1.3

    • requiresArg

      boolean requiresArg()
      Tells if the option requires more arguments to be valid.
      Returns:
      false if the option doesn't require more arguments
      Since:
      1.3

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