uk.ac.ed.epcc.webapp.apps

Class Option

java.lang.Object

uk.ac.ed.epcc.webapp.apps.Option

All Implemented Interfaces:

java.io.Serializable

public class Option
extends java.lang.Object
implements java.io.Serializable

Represents a command line option. See Options to see how options are processed. This class essentially holds information about each option. The inner class Option.Instance holds a specific instance of an option on the command line. As such, it holds the value or values an option has once it has been set on the command line.

All setter methods return the object that was used to call them. This allows setter methods to be chained together on one line. For example:

myOpt.setArgNum(1).setRequired(true).setValueSeparator('+');

Options have either a long name, a short name or both. The long name must be at least two characters long. The short name must be only one character long although this class enforces this by only allowing the short name to be set using a char. Both names can contain only legal characters. The legal characters are specified by the validateName(java.lang.String) method

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Option.Instance An Instance of an Option contains values assigned to an option.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MULTIPLE_ARGUMENTS Used to indicate the option takes an unlimited number of arguments (strictly speaking, the upper limit is set by Integer.MAX_VALUE)
static char	UNSET Used to indicate a character argument (such as short name or value separator) has no value

Constructor Summary

Constructors

Constructor and Description
Option(Options container, char shortName, boolean hasArg, java.lang.String description) Constructs a new Option with the specified short name and description.
Option(Options container, char shortName, java.lang.String description) Constructs a new Option with the specified short name and description.
Option(Options container, char shortName, java.lang.String longName, boolean hasArg, java.lang.String description) Constructs a new Option with the specified short name, long name name and description.
Option(Options container, char shortName, java.lang.String longName, java.lang.String description) Constructs a new Option with the specified short name, long name and description.
Option(Options container, java.lang.String longName, boolean hasArg, java.lang.String description) Constructs a new Option with the specified long name name and description.
Option(Options container, java.lang.String longName, java.lang.String description) Constructs a new Option with the specified long name and description.

Method Summary

Modifier and Type	Method and Description
Option	disableValueSeparator() Disables the use of a value separator.
boolean	equals(java.lang.Object o) Two options are considered equal if they have the same long name and short name
java.lang.String	getDescription()
java.lang.String	getId() Returns the long name for this option if it is set.
java.lang.String	getLongName()
int	getNumVals() Returns the maximum number of values this option can take.
java.lang.String	getShortName()
char	getValueSeparator() Returns the character used to denote a separation in values for this option in an argument.
int	hashCode()
boolean	hasLongName()
boolean	hasShortName()
boolean	hasValue()
boolean	hasValues()
boolean	hasValueSeparator() Returns whether or not this option has a value separator.
boolean	isRequired()
Option.Instance	newInstance() Generates a new instance of this option.
Option	setDescription(java.lang.String description) Sets a short description for this option
Option	setMultipleArgs() Allows this option to have multiple arguments.
Option	setNumValues(int num) Sets the number of values this option can take.
Option	setRequired(boolean required) Sets whether or not this option must be set on the command line
Option	setValueSeparator(char sep) Sets the value separator that separates values in an argument assigned to this option.
java.lang.String	toString() Returns one of the names of this option.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

UNSET

public static final char UNSET

Used to indicate a character argument (such as short name or value separator) has no value

See Also:

Constant Field Values

MULTIPLE_ARGUMENTS

public static final int MULTIPLE_ARGUMENTS

Used to indicate the option takes an unlimited number of arguments (strictly speaking, the upper limit is set by Integer.MAX_VALUE)

See Also:

Constant Field Values

Constructor Detail

Option

public Option(Options container,
              char shortName,
              java.lang.String description)
       throws java.lang.IllegalArgumentException,
              java.lang.NullPointerException

Constructs a new Option with the specified short name and description. The option will have no long name and take no arguments.

Parameters:

container - An Options object that this object will be added to after construction. Can be null, in which case this option won't be added to a Options object after construction

shortName - The short name of the option, or Option.UNSET if this option should not have a short name

description - A brief (one line) description of what the option does

Throws:

java.lang.IllegalArgumentException - if shortName is an illegal character.

java.lang.NullPointerException - if shortName is the NullPointerException character or Option.UNSET

See Also:

validateName(java.lang.String)

Option

public Option(Options container,
              char shortName,
              boolean hasArg,
              java.lang.String description)
       throws java.lang.IllegalArgumentException

Constructs a new Option with the specified short name and description. The option will have no long name and take one argument if hasArg is true or nor arguments if it is false. To allow the option to have more than one argument, use one of the setter. methods after construction.

Parameters:

container - An Options object that this object will be added to after construction. Can be null, in which case this option won't be added to a Options object after construction

shortName - The short name of the option

hasArg - Whether or not the option takes a value.

description - A brief (one line) description of what the option does

Throws:

java.lang.IllegalArgumentException - if shortName is an illegal character.

java.lang.NullPointerException - if shortName is the null character or Option.UNSET

See Also:

validateName(java.lang.String)

Option

public Option(Options container,
              java.lang.String longName,
              java.lang.String description)
       throws java.lang.IllegalArgumentException,
              java.lang.NullPointerException

Constructs a new Option with the specified long name and description. The option will have no short name and take no arguments.

Parameters:

container - An Options object that this object will be added to after construction. Can be null, in which case this option won't be added to a Options object after construction

longName - The long name of the option.

description - A brief (one line) description of what the option does.

Throws:

java.lang.IllegalArgumentException - if longName contains illegal characters or is less than two characters long.

java.lang.NullPointerException - if longName is the null.

See Also:

validateName(java.lang.String)

Option

public Option(Options container,
              java.lang.String longName,
              boolean hasArg,
              java.lang.String description)
       throws java.lang.IllegalArgumentException

Constructs a new Option with the specified long name name and description. The option will have no short name and take one argument if hasArg is true or nor arguments if it is false. To allow the option to have more than one argument, use one of the setter methods after construction.

Parameters:

container - An Options object that this object will be added to after construction. Can be null, in which case this option won't be added to a Options object after construction

longName - The long name of the option.

hasArg - Whether or not the option takes a value.

description - A brief (one line) description of what the option does.

Throws:

java.lang.IllegalArgumentException - if longName contains illegal characters or is less than two characters long.

java.lang.NullPointerException - if longName is the null.

See Also:

validateName(java.lang.String)

Option

public Option(Options container,
              char shortName,
              java.lang.String longName,
              java.lang.String description)
       throws java.lang.IllegalArgumentException

Constructs a new Option with the specified short name, long name and description. The option will take no arguments.

Parameters:

container - An Options object that this object will be added to after construction. Can be null, in which case this option won't be added to a Options object after construction

shortName - The short name of the option, or Option.UNSET if this option should not have a short name. In this case, longName cannot be null.

longName - The long name of the option (can be null so long as short name is specified).

description - A brief (one line) description of what the option does.

Throws:

java.lang.IllegalArgumentException - if shortName or longName contain illegal characters, or if long name is less than two characters long.

java.lang.NullPointerException - if longName is the null or if shortName is the null character or Option.UNSET

See Also:

validateName(java.lang.String)

Option

public Option(Options container,
              char shortName,
              java.lang.String longName,
              boolean hasArg,
              java.lang.String description)
       throws java.lang.IllegalArgumentException,
              java.lang.NullPointerException

Constructs a new Option with the specified short name, long name name and description. The option will take one argument if hasArg is true or nor arguments if it is false. To allow the option to have more than one argument, use one of the setter methods after construction.

Parameters:

container - An Options object that this object will be added to after construction. Can be null, in which case this option won't be added to a Options object after construction

shortName - The short name of the option, or Option.UNSET if this option should not have a short name In this case, longName cannot be null

longName - The long name of the option (can be null so long as short name is specified)

hasArg - Whether or not the option takes a value.

description - A brief (one line) description of what the option does

Throws:

java.lang.IllegalArgumentException - if shortName or longName contain illegal characters, or if long name is less than two characters long.

java.lang.NullPointerException - if longName is the null or if shortName is the null character or Option.UNSET

See Also:

validateName(java.lang.String)

Method Detail

disableValueSeparator

public Option disableValueSeparator()

Disables the use of a value separator. No attempt will be made to break an argument of a multi-valued option into many values

Returns:

This Option

getDescription

public java.lang.String getDescription()

Returns:

a brief description of this option.

getId

public java.lang.String getId()

Returns the long name for this option if it is set. If it isn't, returns the short name. This method is useful if one needs a single name or identifier to denote this option.

Returns:

An appropriate name for this option.

getLongName

public java.lang.String getLongName()

Returns:

This option's long name.

getNumVals

public int getNumVals()

Returns the maximum number of values this option can take. If there is no limit on the number of values, MULTIPLE_ARGUMENTS will be returned.

Returns:

The maximum number of arguments this option can take.

getShortName

public java.lang.String getShortName()

Returns:

This option's short name.

getValueSeparator

public char getValueSeparator()

Returns the character used to denote a separation in values for this option in an argument. If this option does not have a value separator, UNSET is returned. Even if this option only takes one value or no values at all, a value separator may still be set. However, in these cases it will never be used.

Returns:

The value separator used in arguments.

hasValue

public boolean hasValue()

Returns:

true if this option takes one or more values. false otherwise.

hasValues

public boolean hasValues()

Returns:

true if this option takes more than one value. false otherwise.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

hasLongName

public boolean hasLongName()

Returns:

true if this option has a long name. false otherwise.

hasShortName

public boolean hasShortName()

Returns:

true if this option has a short name. false otherwise.

hasValueSeparator

public boolean hasValueSeparator()

Returns whether or not this option has a value separator. Even if this option only takes one value or no values at all, a value separator may still be set. However, in these cases it will never be used.

Returns:

true if this option has a value separator. false otherwise.

isRequired

public boolean isRequired()

Returns:

true if this option must be set on the command line. false otherwise

newInstance

public Option.Instance newInstance()

Generates a new instance of this option. The instance can be populated with values, however it will conform to the constraints applied by this option.

Returns:

An instance of this option

See Also:

Option.Instance

setNumValues

public Option setNumValues(int num)
                    throws java.lang.IllegalArgumentException

Sets the number of values this option can take. If this option can take many options, use MULTIPLE_ARGUMENTS as the value.

Parameters:

num - The number of values this option can take

Returns:

This Option

Throws:

java.lang.IllegalArgumentException - if num is less than zero

setDescription

public Option setDescription(java.lang.String description)

Sets a short description for this option

Parameters:

description - The description

Returns:

This Option

setMultipleArgs

public Option setMultipleArgs()

Allows this option to have multiple arguments. There is no limit set on the maximum number of arguments, although technically, there cannot be more than the maximum value stored in an int

Returns:

This Option

setRequired

public Option setRequired(boolean required)

Sets whether or not this option must be set on the command line

Parameters:

required - Whether or not this option must be set on the command line

Returns:

This Option

setValueSeparator

public Option setValueSeparator(char sep)

Sets the value separator that separates values in an argument assigned to this option. The character used is not checked in any way so technically, any character could be used. Obviously, characters such as the line feed character or system bell character are not the best choices for value separator, however this object allows them to be used as value separators.

Parameters:

sep - the value separator to use when assigning an argument to this option

Returns:

This Option

equals

public boolean equals(java.lang.Object o)

Two options are considered equal if they have the same long name and short name

Overrides:

equals in class java.lang.Object

See Also:

Object.equals(java.lang.Object)

toString

public java.lang.String toString()

Returns one of the names of this option.

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()