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 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 Specifies the number of argument values has not been specified
static int	UNLIMITED_VALUES Specifies the number of argument values is infinite

Constructor Summary

Constructors

Constructor and 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 and 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 compat 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.
String	getDescription() Gets the self-documenting description of this Option
int	getId() Gets the id of this Option.
String	getLongOpt() Gets the long name of this Option.
String	getOpt() Gets the name of this Option.
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() 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(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 Detail

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 Detail

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 Detail

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

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

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

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

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

Query to see if this Option requires an argument

Returns:

boolean flag indicating if an argument is required

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

hashCode

public int hashCode()

Overrides:

hashCode in class Object

hasLongOpt

public boolean hasLongOpt()

Query to see if this Option has a long name

Returns:

boolean flag indicating existence of a long name

hasOptionalArg

public boolean hasOptionalArg()

Returns:

whether this Option can have an optional argument

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

isRequired

public boolean isRequired()

Query to see if this Option is mandatory

Returns:

boolean flag indicating 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.

setArgs

public void setArgs(int num)

Sets the number of argument values this Option can take.

Parameters:

num - the number of argument values

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

toString

public String toString()

Dump state, suitable for debugging.

Overrides:

toString in class Object

Returns:

Stringified form of this object