org.apache.commons.cli

Class Option

Implemented Interfaces:
Cloneable

public class Option
extends java.lang.Object
implements Cloneable

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 independantly, but is create through an instance of Options.

Version:
$Revision: 551821 $
Authors:
bob mcwhirter (bob @ werken.com)
James Strachan
See Also:
Options, CommandLine

Field Summary

static int
UNINITIALIZED
constant that specifies the number of argument values has not been specified
static int
UNLIMITED_VALUES
constant that specifies the number of argument values is infinite
private String
argName
argName specifies the name of the argument for this option
private String
description
description of the option
private boolean
hasArg
hasArg specifies whether this option has an associated argument
private String
longOpt
longOpt is the long representation of the option
private int
numberOfArgs
numberOfArgs specifies the number of argument values this option can have
private String
opt
opt the name of the option
private boolean
optionalArg
specifies whether the argument value of this Option is optional
private boolean
required
required specifies whether this option is required to be present
private Object
type
the type of this Option
private ArrayList
values
the list of argument values *
private char
valuesep
the character that is the value separator

Constructor Summary

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.
Option(String opt, boolean hasArg, String description)
Creates an Option using the specified parameters.

Method Summary

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.
(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(String defaultValue)
Returns the value/first value of this Option or the defaultValue if there is no value.
String
getValue(int index)
Returns the specified value of this Option or null if there is no value.
char
getValueSeparator()
Returns the value separator character.
String[]
getValues()
Return the values of this Option as a String array or null if there are no values
java.util.List
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.
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.
int
hashCode()
boolean
isRequired()
Query to see if this Option requires an argument
private void
processValue(String value)
Processes the value.
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(Object type)
Sets the type of this Option.
void
setValueSeparator(char sep)
Sets the value separator.
String
toString()
Dump state, suitable for debugging.

Field Details

UNINITIALIZED

public static final int UNINITIALIZED
constant that specifies the number of argument values has not been specified
Field Value:
-1

UNLIMITED_VALUES

public static final int UNLIMITED_VALUES
constant that specifies the number of argument values is infinite
Field Value:
-2

argName

private String argName
argName specifies the name of the argument for this option

description

private String description
description of the option

hasArg

private boolean hasArg
hasArg specifies whether this option has an associated argument

longOpt

private String longOpt
longOpt is the long representation of the option

numberOfArgs

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

opt

private String opt
opt the name of the option

optionalArg

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

required

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

type

private Object type
the type of this Option

values

private ArrayList values
the list of argument values *

valuesep

private char valuesep
the character that is the value separator

Constructor Details

Option

public Option(String opt,
              String description)
            throws IllegalArgumentException
Creates an Option using the specified parameters.
Parameters:
opt - short representation of the option
description - describes the function of the option

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

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

Method Details

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

addValue

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.

addValueForProcessing

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

clearValues

(package private)  void clearValues()

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

equals

public boolean equals(Object o)

getArgName

public String getArgName()
Gets the display name for the argument value.
Returns:
the display name for the argument value.

getArgs

public int getArgs()
Returns the number of argument values this Option can take.
Returns:
num the number of argument values

getDescription

public String getDescription()
Retrieve the self-documenting description of this Option
Returns:
The string description of this option

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

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

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

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

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(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 ther is no value.
Returns:
the value/first value of this Option or the defaultValue if there are no values.

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.

getValueSeparator

public char getValueSeparator()
Returns the value separator character.
Returns:
the value separator character.

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 java.util.List getValuesList()
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

hasLongOpt

public boolean hasLongOpt()
Query to see if this Option has a long name
Returns:
boolean flag indicating existence of a long name

hasNoValues

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

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.

hashCode

public int hashCode()

isRequired

public boolean isRequired()
Query to see if this Option requires an argument
Returns:
boolean flag indicating if an argument is required

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

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

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(Object type)
Sets the type of this Option.
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.
Returns:
Stringified form of this object