Package 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 ofOptions
, 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
BuildsOption
instances using descriptive methods.
-
Field Summary
Fields Modifier and Type Field Description private int
argCount
The number of argument values this option can have.private java.lang.String
argName
The name of the argument for this option.private Converter<?,?>
converter
The explicit converter for this option.private DeprecatedAttributes
deprecated
Specifies whether this option is deprecated, may be null.private java.lang.String
description
Description of the option.(package private) static Option[]
EMPTY_ARRAY
Empty array.private java.lang.String
longOption
The long representation of the option.private java.lang.String
option
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 long
serialVersionUID
The serial version UID.private java.lang.Class<?>
type
The type of this Option.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.private java.util.List<java.lang.String>
values
The list of argument values.private char
valuesep
The character that is the value separator.
-
Constructor Summary
Constructors Modifier Constructor Description Option(java.lang.String option, boolean hasArg, java.lang.String description)
Creates an Option using the specified parameters.Option(java.lang.String option, java.lang.String description)
Creates an Option using the specified parameters.Option(java.lang.String option, java.lang.String longOption, boolean hasArg, java.lang.String description)
Creates an Option using the specified parameters.private
Option(Option.Builder builder)
Private constructor used by the nested Builder class.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description (package private) boolean
acceptsArg()
Tests whether the option can accept more arguments.private void
add(java.lang.String value)
Adds the value to this Option.boolean
addValue(java.lang.String value)
Deprecated.Unused.static Option.Builder
builder()
Returns aOption.Builder
to create anOption
using descriptive methods.static Option.Builder
builder(java.lang.String option)
Returns aOption.Builder
to create anOption
using descriptive methods.(package private) void
clearValues()
Clears the Option values.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 compatible at the API level.boolean
equals(java.lang.Object obj)
java.lang.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.java.lang.String
getDescription()
Gets the self-documenting description of this Option.int
getId()
Gets the id of this Option.java.lang.String
getKey()
Gets the 'unique' Option identifier.java.lang.String
getLongOpt()
Gets the long name of this Option.java.lang.String
getOpt()
Gets the name of this Option.java.lang.Object
getType()
Gets the type of this Option.java.lang.String
getValue()
Gets the specified value of this Option ornull
if there is no value.java.lang.String
getValue(int index)
Gets the specified value of this Option ornull
if there is no value.java.lang.String
getValue(java.lang.String defaultValue)
Gets the value/first value of this Option or thedefaultValue
if there is no value.java.lang.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.java.util.List<java.lang.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.private boolean
hasNoValues()
Tests whether this Option has any values.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.(package private) void
processValue(java.lang.String value)
Processes the value.(package private) boolean
requiresArg()
Tests whether the option requires more arguments to be valid.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
setConverter(Converter<?,?> converter)
Sets the value to type converter.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, usesetType(Class)
instead.void
setValueSeparator(char sep)
Sets the value separator.(package private) java.lang.String
toDeprecatedString()
java.lang.String
toString()
Creates a String suitable for debugging.
-
-
-
Field Detail
-
EMPTY_ARRAY
static final Option[] EMPTY_ARRAY
Empty array.
-
serialVersionUID
private static final long serialVersionUID
The serial version UID.- See Also:
- Constant Field Values
-
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
-
argCount
private int argCount
The number of argument values this option can have.
-
argName
private java.lang.String argName
The name of the argument for this option.
-
converter
private transient Converter<?,?> converter
The explicit converter for this option. May be null.
-
deprecated
private final transient DeprecatedAttributes deprecated
Specifies whether this option is deprecated, may be null.If you want to serialize this field, use a serialization proxy.
-
description
private java.lang.String description
Description of the option.
-
longOption
private java.lang.String longOption
The long representation of the option.
-
option
private final java.lang.String option
The name of the option.
-
optionalArg
private boolean optionalArg
Specifies whether the argument value of this Option is optional.
-
required
private boolean required
Specifies whether this option is required to be present.
-
type
private java.lang.Class<?> type
The type of this Option.
-
values
private java.util.List<java.lang.String> values
The list of argument values.
-
valuesep
private char valuesep
The character that is the value separator.
-
-
Constructor Detail
-
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(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 inopt
.
-
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 inopt
.
-
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 inopt
.
-
-
Method Detail
-
builder
public static Option.Builder builder()
Returns aOption.Builder
to create anOption
using descriptive methods.- Returns:
- a new
Option.Builder
instance. - Since:
- 1.3
-
builder
public static Option.Builder builder(java.lang.String option)
Returns aOption.Builder
to create anOption
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 inopt
.- Since:
- 1.3
-
acceptsArg
boolean acceptsArg()
Tests whether the option can accept more arguments.- Returns:
- false if the maximum number of arguments is reached.
- Since:
- 1.3
-
add
private void add(java.lang.String value)
Adds 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.
-
addValue
@Deprecated public boolean addValue(java.lang.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:
java.lang.UnsupportedOperationException
- always.
-
clearValues
void clearValues()
Clears 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
-
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 compatible at the API level. After calling this method, it is very likely you will want to call clearValues().- Overrides:
clone
in classjava.lang.Object
- Returns:
- a clone of this Option instance.
- Throws:
java.lang.RuntimeException
- if aCloneNotSupportedException
has been thrown bysuper.clone()
.
-
equals
public boolean equals(java.lang.Object obj)
- Overrides:
equals
in classjava.lang.Object
-
getArgName
public java.lang.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 constantUNLIMITED_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 java.lang.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 java.lang.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 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.
-
getOpt
public java.lang.String getOpt()
Gets the name of this Option. It is this String which can be used withCommandLine.hasOption(String opt)
andCommandLine.getOptionValue(String opt)
to check for existence and argument.- Returns:
- The name of this option.
-
getType
public java.lang.Object getType()
Gets the type of this Option.- Returns:
- The type of this option.
-
getValue
public java.lang.String getValue()
Gets the specified value of this Option ornull
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
Gets the specified value of this Option ornull
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)
Gets the value/first value of this Option or thedefaultValue
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()
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 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.
-
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 classjava.lang.Object
-
hasLongOpt
public boolean hasLongOpt()
Tests whether this Option has a long name.- Returns:
- boolean flag indicating existence of a long name.
-
hasNoValues
private boolean hasNoValues()
Tests whether this Option has any values.- Returns:
- whether this Option has any values.
-
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.
-
processValue
void processValue(java.lang.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.
-
requiresArg
boolean requiresArg()
Tests whether the option requires more arguments to be valid.- Returns:
- false if the option doesn't require more arguments.
-
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.
-
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(java.lang.String description)
Sets the self-documenting description of this Option.- Parameters:
description
- The description of this option.- Since:
- 1.1
-
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.
-
setRequired
public void setRequired(boolean required)
Sets whether this Option is mandatory.- Parameters:
required
- specifies whether this Option is mandatory.
-
setType
public void setType(java.lang.Class<?> type)
Sets the type of this Option.- Parameters:
type
- the type of this Option.- Since:
- 1.3
-
setType
@Deprecated public void setType(java.lang.Object type)
Deprecated.since 1.3, usesetType(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 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.
-
toDeprecatedString
java.lang.String toDeprecatedString()
-
toString
public java.lang.String toString()
Creates a String suitable for debugging.- Overrides:
toString
in classjava.lang.Object
- Returns:
- a String suitable for debugging.
-
-