info.rolandkrueger.roklib.cli
Class CommandLineArgumentEvaluator

java.lang.Object
  info.rolandkrueger.roklib.cli.CommandLineArgumentEvaluator

public class CommandLineArgumentEvaluator
extends Object

This class can be used to handle a program's command line options in an easy and uncomplicated way. To use a CommandLineArgumentEvaluator, you first have to define the set of all available command line options and pass them to the CommandLineArgumentEvaluator with the addOptions(CommandLineOption...) or addOptions(Collection) methods. After that, the evaluator object can be queried if the program was provided with the correct options.

Author:

Roland Krueger

See Also:

CommandLineOption

Nested Class Summary

static class

CommandLineArgumentEvaluator.UserInputValidity Enum which is used to describe whether the arguments provided by the user via the command line were valid and if not so, what was wrong about them.

Field Summary

private boolean	mAllowClusteredShortOptions
private boolean	mAllowStandaloneValues
private String[]	mArgs
private String	mDescription
private CommandLineOption	mErroneousOption
private boolean	mEvaluated
private String	mLongOptionsMarker
private Set<CommandLineOption>	mMandatoryList
private List<CommandLineOption>	mMutuallyExclusiveOptionsGiven
private Set<CommandLineOption>	mOptionSet
private String	mShortOptionsMarker
private List<String>	mStandaloneValues
private CommandLineArgumentEvaluator.UserInputValidity	mStatus
private String	mUnrecognizedOption

Constructor Summary

CommandLineArgumentEvaluator()

CommandLineArgumentEvaluator(String[] arguments)
Creates a new CommandLineArgumentEvaluator object that is supposed to check the given command line options.

Method Summary

void	addOptions(Collection<CommandLineOption> options) Adds a list of CommandLineOption objects to the internal option list of this evaluator
void	addOptions(CommandLineOption... options) Adds one or more options to the internal list of all available options.
void	allowClusteredShortOptions(boolean yesNo)
void	allowStandAloneValues(boolean yesNo)
private boolean	disassembleFlagCluster(String value)
void	evaluate() After all available options have been configured and added to the evaluator object, the command line options given through the constructor are evaluated, such that after that it can be checked whether the user-provided options are correct or not.
void	evaluateAndInvokeCallbacks()
String	getDescription()
String	getDescriptiveSummaryFor(CommandLineOption option)
String	getDescriptiveSummaryFor(CommandLineOption option, String descriptionSeparator)
CommandLineOption	getErroneousOption()
CommandLineArgumentEvaluator.UserInputValidity	getInputStatus() Returns the status of the command line options given by the user.
String	getLongOptionsMarker()
List<CommandLineOption>	getMissingOptions() If after having specified the set of available and mandatory options and having called evaluate() the user has omitted one or more of the mandatory options, these missing options can be queried as a list.
List<CommandLineOption>	getMutuallyExclusiveOptionsBeingUsed()
String	getOptionDescription() This method will assemble a string containing an overview of all available options together with a general blueprint of how to correctly use these options.
private CommandLineOption	getOptionFor(String value, boolean valueContainsMarker)
Set<CommandLineOption>	getOptions() Returns the internal list of CommandLineOption objects.
String	getShortOptionsMarker()
List<String>	getStandaloneValues()
String	getUnrecognizedOption()
void	invokeCallbacks()
boolean	isValid()
void	setArgumentList(String[] args)
void	setDescription(String description)
private void	setErroneousOption(CommandLineOption erroneous)
void	setLongOptionsMarker(String longOptionsMarker)
void	setShortOptionsMarker(String shortOptionsMarker)
private boolean	setUnrecognizedOption(String option)
private List<String>	splitAtEqualSign(String value)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mShortOptionsMarker

private String mShortOptionsMarker

mLongOptionsMarker

private String mLongOptionsMarker

mOptionSet

private Set<CommandLineOption> mOptionSet

mMandatoryList

private Set<CommandLineOption> mMandatoryList

mArgs

private String[] mArgs

mStatus

private CommandLineArgumentEvaluator.UserInputValidity mStatus

mEvaluated

private boolean mEvaluated

mAllowClusteredShortOptions

private boolean mAllowClusteredShortOptions

mAllowStandaloneValues

private boolean mAllowStandaloneValues

mDescription

private String mDescription

mStandaloneValues

private List<String> mStandaloneValues

mUnrecognizedOption

private String mUnrecognizedOption

mErroneousOption

private CommandLineOption mErroneousOption

mMutuallyExclusiveOptionsGiven

private List<CommandLineOption> mMutuallyExclusiveOptionsGiven

Constructor Detail

CommandLineArgumentEvaluator

public CommandLineArgumentEvaluator()

CommandLineArgumentEvaluator

public CommandLineArgumentEvaluator(String[] arguments)

Creates a new CommandLineArgumentEvaluator object that is supposed to check the given command line options.

Parameters:

arguments - the command line options for this application as optained by the main() method, for example

Method Detail

setArgumentList

public void setArgumentList(String[] args)

addOptions

public void addOptions(CommandLineOption... options)

Adds one or more options to the internal list of all available options.

Parameters:

options - an option array which contains all necessary information of a specific command line option

allowClusteredShortOptions

public void allowClusteredShortOptions(boolean yesNo)

allowStandAloneValues

public void allowStandAloneValues(boolean yesNo)

getStandaloneValues

public List<String> getStandaloneValues()

addOptions

public void addOptions(Collection<CommandLineOption> options)

Adds a list of CommandLineOption objects to the internal option list of this evaluator

Parameters:

options - a collection of CommandLineOption objects

getOptions

public Set<CommandLineOption> getOptions()

Returns the internal list of CommandLineOption objects.

Returns:

the internal list of CommandLineOption objects.

evaluate

public void evaluate()

After all available options have been configured and added to the evaluator object, the command line options given through the constructor are evaluated, such that after that it can be checked whether the user-provided options are correct or not. Note that this method can only be called once and only once.

Throws:

IllegalStateException - if this method was called more than once

setUnrecognizedOption

private boolean setUnrecognizedOption(String option)

getUnrecognizedOption

public String getUnrecognizedOption()

setErroneousOption

private void setErroneousOption(CommandLineOption erroneous)

getErroneousOption

public CommandLineOption getErroneousOption()

getDescriptiveSummaryFor

public String getDescriptiveSummaryFor(CommandLineOption option)

getDescriptiveSummaryFor

public String getDescriptiveSummaryFor(CommandLineOption option,
                                       String descriptionSeparator)

getMutuallyExclusiveOptionsBeingUsed

public List<CommandLineOption> getMutuallyExclusiveOptionsBeingUsed()

disassembleFlagCluster

private boolean disassembleFlagCluster(String value)

splitAtEqualSign

private List<String> splitAtEqualSign(String value)

getOptionFor

private CommandLineOption getOptionFor(String value,
                                       boolean valueContainsMarker)

isValid

public boolean isValid()

evaluateAndInvokeCallbacks

public void evaluateAndInvokeCallbacks()

invokeCallbacks

public void invokeCallbacks()

getInputStatus

public CommandLineArgumentEvaluator.UserInputValidity getInputStatus()

Returns the status of the command line options given by the user. This method can only be called after invoking method evaluate(). Otherwise, a IllegalStateException will be thrown.

Returns:

the validity status of the user's command line options

Throws:

IllegalStateException - if this method is called without invoking evaluate() beforehand

See Also:

CommandLineArgumentEvaluator.UserInputValidity

getOptionDescription

public String getOptionDescription()

This method will assemble a string containing an overview of all available options together with a general blueprint of how to correctly use these options. Additionally for each option a short description is provided as defined by the respective CommandLineOption object.

Returns:

a string containing an overview over all available options

getMissingOptions

public List<CommandLineOption> getMissingOptions()

If after having specified the set of available and mandatory options and having called evaluate() the user has omitted one or more of the mandatory options, these missing options can be queried as a list.

Returns:

list of mandatory options that were omitted by the user

getShortOptionsMarker

public String getShortOptionsMarker()

setShortOptionsMarker

public void setShortOptionsMarker(String shortOptionsMarker)

getLongOptionsMarker

public String getLongOptionsMarker()

setDescription

public void setDescription(String description)

getDescription

public String getDescription()

setLongOptionsMarker

public void setLongOptionsMarker(String longOptionsMarker)