) constraint.getChild("params").getChildren("param"));
}
} catch (InstantiationException ex) {
throw new XMLParsingException(CLASS + ": Could not create constraint instance", ex);
} catch (ClassNotFoundException ex) {
throw new XMLParsingException(CLASS + ": Could not create constraint instance", ex);
} catch (IllegalAccessException ex) {
throw new XMLParsingException(CLASS + ": Could not create constraint instance", ex);
}
}
}
// ==========================================================================================
// Defaults handling
// ==========================================================================================
/**
* Define the default to use for the separator for value options. Note that this method can
* only be invoked before any option set has been created.
*
* @param defaultValueSeparator The default separator to use for all value options
*
* @return This instance to allow for invocation chaining
*/
public Options setDefault(Separator defaultValueSeparator) {
if (defaultValueSeparator == null) {
throw new IllegalArgumentException(CLASS + ": defaultValueSeparator may not be null");
}
if (optionSets.size() > 0) {
throw new UnsupportedOperationException(CLASS + ": method can not be invoked, OptionSets have already been defined");
}
this.defaultValueSeparator = defaultValueSeparator;
return this;
}
/**
* Define the defaults to use for the separators for value and detail options. Note that this method can
* only be invoked before any option set has been created.
*
* @param defaultValueSeparator The default separator to use for all value options
* @param defaultDetailSeparator The default separator to use for all detail options
*
* @return This instance to allow for invocation chaining
*/
public Options setDefault(Separator defaultValueSeparator, Separator defaultDetailSeparator) {
if (defaultValueSeparator == null) {
throw new IllegalArgumentException(CLASS + ": defaultValueSeparator may not be null");
}
if (defaultDetailSeparator == null) {
throw new IllegalArgumentException(CLASS + ": defaultDetailSeparator may not be null");
}
if (optionSets.size() > 0) {
throw new UnsupportedOperationException(CLASS + ": method can not be invoked, OptionSets have already been defined");
}
this.defaultValueSeparator = defaultValueSeparator;
this.defaultDetailSeparator = defaultDetailSeparator;
return this;
}
/**
* Define the default to use for the option prefix. Note that this method can
* only be invoked before any option set has been created.
*
* @param defaultPrefix The prefix to use for all options
*
* @return This instance to allow for invocation chaining
*/
public Options setDefault(Prefix defaultPrefix) {
if (defaultPrefix == null) {
throw new IllegalArgumentException(CLASS + ": defaultPrefix may not be null");
}
if (optionSets.size() > 0) {
throw new UnsupportedOperationException(CLASS + ": method can not be invoked, OptionSets have already been defined");
}
this.defaultPrefix = defaultPrefix;
return this;
}
/**
* Define the defaults to use for the option prefixes. Note that this method can
* only be invoked before any option set has been created.
*
* @param defaultPrefix The prefix to use for all options
* @param defaultAltPrefix The prefix to use for all alternate keys for options
*
* @return This instance to allow for invocation chaining
*/
public Options setDefault(Prefix defaultPrefix, Prefix defaultAltPrefix) {
if (defaultPrefix == null) {
throw new IllegalArgumentException(CLASS + ": defaultPrefix may not be null");
}
if (defaultAltPrefix == null) {
throw new IllegalArgumentException(CLASS + ": defaultAltPrefix may not be null");
}
if (defaultPrefix.equals(defaultAltPrefix)) {
throw new IllegalArgumentException(CLASS + ": The prefixes must be different");
}
if (optionSets.size() > 0) {
throw new UnsupportedOperationException(CLASS + ": method can not be invoked, OptionSets have already been defined");
}
this.defaultPrefix = defaultPrefix;
this.defaultAltPrefix = defaultAltPrefix;
return this;
}
/**
* Define the default to use for the multiplicity for options. This applies only to
* option sets and options within these sets which are created after this call.
*
* @param defaultMultiplicity The default multiplicity to use for all options
*
* @return This instance to allow for invocation chaining
*/
public Options setDefault(Multiplicity defaultMultiplicity) {
if (defaultMultiplicity == null) {
throw new IllegalArgumentException(CLASS + ": defaultMultiplicity may not be null");
}
this.defaultMultiplicity = defaultMultiplicity;
return this;
}
/**
* Define the defaults to use for the number of data items for a set. This applies only to
* option sets which are created after this call.
*
* @param defaultData The default minimum and maximum number of data items
*
* @return This instance to allow for invocation chaining
*/
public Options setDefault(int defaultData) {
if (defaultData < 0) {
throw new IllegalArgumentException(CLASS + ": defaultData must be >= 0");
}
this.defaultMinData = defaultData;
this.defaultMaxData = defaultData;
return this;
}
/**
* Define the defaults to use for the number of data items for a set. This applies only to
* option sets which are created after this call.
*
* @param defaultMinData The default minimum number of data items
* @param defaultMaxData The default maximum number of data items
*
* @return This instance to allow for invocation chaining
*/
public Options setDefault(int defaultMinData, int defaultMaxData) {
if (defaultMinData < 0) {
throw new IllegalArgumentException(CLASS + ": defaultMinData must be >= 0");
}
int limit = defaultMaxData;
if (defaultMaxData == OptionSet.INF) {
limit = Integer.MAX_VALUE;
}
if (limit < defaultMinData) {
throw new IllegalArgumentException(CLASS + ": defaultMaxData must be >= defaultMinData");
}
this.defaultMinData = defaultMinData;
this.defaultMaxData = limit;
return this;
}
// ==========================================================================================
// The actual API
// ==========================================================================================
/**
* Return the (first) matching set. This invocation does not ignore unmatched options and requires that
* data items are the last ones on the command line. It is equivalent to calling
* getMatchingSet(false, true).
*
* @return The first set which matches (i. e. the check() method returns true) - or
* null, if no set matches.
*/
public OptionSet getMatchingSet() {
return getMatchingSet(false, true);
}
/**
* Return the (first) matching set.
*
* @param ignoreUnmatched A boolean to select whether unmatched options can be ignored in the checks or not
* @param requireDataLast A boolean to indicate whether the data items
* have to be the last ones on the command line or not
*
* @return The first set which matches (i. e. the check() method returns true) - or
* null, if no set matches.
*/
public OptionSet getMatchingSet(boolean ignoreUnmatched, boolean requireDataLast) {
// If we have no set at this stage, we need to create the default set since
// chances are the user just wants to check for data (no options), and thus
// getSet() has not been invoked by the user at this stage.
if (optionSets.isEmpty()) {
getSet();
}
// Run the checks for all known sets
for (String name : optionSets.keySet()) {
if (check(name, ignoreUnmatched, requireDataLast)) {
return optionSets.get(name);
}
}
return null;
}
/**
* Add an option set.
*
* @param name The name for the set. This must be a unique identifier
* @param minData The minimum number of data items for this set
* @param maxData The maximum number of data items for this set (if set to OptionSet.INF, this
* effectively corresponds to an unlimited number)
*
* @return The new OptionSet instance created. This is useful to allow
* chaining of addOption() calls right after this method
*/
public OptionSet addSet(String name, int minData, int maxData) {
if (name == null) {
throw new IllegalArgumentException(CLASS + ": name may not be null");
}
if (optionSets.containsKey(name)) {
throw new IllegalArgumentException(CLASS + ": a set with the name " + name + " has already been defined");
}
int limit = maxData;
if (maxData == OptionSet.INF) {
limit = Integer.MAX_VALUE;
}
OptionSet os = new OptionSet(name,
defaultPrefix,
defaultAltPrefix,
defaultValueSeparator,
defaultDetailSeparator,
defaultMultiplicity,
minData,
limit,
name.equals(DEFAULT_SET));
optionSets.put(name, os);
return os;
}
/**
* Add an option set.
*
* @param name The name for the set. This must be a unique identifier
* @param data The minimum and maximum number of data items for this set
*
* @return The new OptionSet instance created. This is useful to allow chaining
* of addOption() calls right after this method
*/
public OptionSet addSet(String name, int data) {
return addSet(name, data, data);
}
/**
* Add an option set. The defaults for the number of data items are used.
*
* @param name The name for the set. This must be a unique identifier
*
* @return The new OptionSet instance created. This is useful to allow
* chaining of addOption() calls right after this method
*/
public OptionSet addSet(String name) {
return addSet(name, defaultMinData, defaultMaxData);
}
/**
* Add an option set by cloning an existing set. Note that is designed for setup purposes only, i. e. no
* check result data is copied either for the set or any options. This method can be very handy if an application
* requires two (or more) sets which have a lot of options in common and differ only in a few of them. In this
* case, one would first create a set with the common options, then clone any number of additionally required
* sets, and add the non-common options to each of these sets.
*
* Note that it is not possible to change the number of data items required for the new set.
*
* @param name The name for the new set. This must be a unique identifier
* @param set The set to clone the new set from
*
* @return The new OptionSet instance created. This is useful to allow chaining
* of addOption() calls right after this method
*/
public OptionSet addSet(String name, OptionSet set) {
if (name == null) {
throw new IllegalArgumentException(CLASS + ": name may not be null");
}
if (set == null) {
throw new IllegalArgumentException(CLASS + ": set may not be null");
}
if (optionSets.containsKey(name)) {
throw new IllegalArgumentException(CLASS + ": a set with the name " + name + " has already been defined");
}
OptionSet os = new OptionSet(name, set);
optionSets.put(name, os);
return os;
}
/**
* Return an option set - or null, if no set with the given name exists
*
* @param name The name for the set to retrieve
*
* @return The set to retrieve (or null, if no set with the given name exists)
*/
public OptionSet getSet(String name) {
return optionSets.get(name);
}
/**
* Print a help description for this instance using a {@link DefaultHelpPrinter}. This method
* provides a basic service in the sense that it loops over all known option sets
* and prints the command line for each set. If printTexts is true, also
* descriptive texts are printed for all options and the data arguments.
*
* Note that default values are used for all the components of the helper text, which can be
* overridden by various methods available in the {@link OptionSet} and {@link OptionData} classes.
*
* @param leadingText The text to precede the command line for each
* option set (see {@link HelpPrinter#getCommandLine(OptionSet, String, boolean)})
* @param lineBreak A boolean indicating whether the command lines for the option sets should
* be printed with line breaks or not
* (see {@link HelpPrinter#getCommandLine(OptionSet, String, boolean)})
* @param printTexts A boolean indicating whether the full help information should be printer (command lines
* and description texts) or just the command lines
*/
public void printHelp(String leadingText, boolean lineBreak, boolean printTexts) {
printHelp(new DefaultHelpPrinter(), leadingText, lineBreak, printTexts);
}
/**
* Print a help description for this instance using the provided {@link HelpPrinter}. This method
* provides a basic service in the sense that it loops over all known option sets
* and prints the command line for each set. If printTexts is true, also
* descriptive texts are printed for all options and the data arguments.
*
* Note that default values are used for all the components of the helper text, which can be
* overridden by various methods available in the {@link OptionSet} and {@link OptionData} classes.
*
* @param helpPrinter The {@link HelpPrinter} to use to format the output
* @param leadingText The text to precede the command line for each
* option set (see {@link HelpPrinter#getCommandLine(OptionSet, String, boolean)})
* @param lineBreak A boolean indicating whether the command lines for the option sets should
* be printed with line breaks or not
* (see {@link HelpPrinter#getCommandLine(OptionSet, String, boolean)})
* @param printTexts A boolean indicating whether the full help information should be printer (command lines
* and description texts) or just the command lines
*/
public void printHelp(HelpPrinter helpPrinter, String leadingText, boolean lineBreak, boolean printTexts) {
if (helpPrinter == null) {
throw new IllegalArgumentException(CLASS + ": helpPrinter may not be null");
}
if (leadingText == null) {
throw new IllegalArgumentException(CLASS + ": leadingText may not be null");
}
OptionSet set = null;
//.... No sets are defined, we only work with the default set
if (getSetNames().size() == 0) {
set = getSet();
System.out.println(helpPrinter.getCommandLine(set, leadingText, lineBreak));
if (printTexts) {
System.out.print('\n');
System.out.println(helpPrinter.getHelpText(set));
}
//.... Loop over all defined sets
} else {
java.util.Set sets = getSetNames();
for (String name : sets) {
set = getSet(name);
System.out.println(helpPrinter.getCommandLine(set, leadingText, lineBreak));
if (printTexts) {
System.out.print('\n');
System.out.println(helpPrinter.getHelpText(set));
if (sets.size() > 1) {
System.out.print('\n');
}
}
}
}
}
/**
* Get a set view on the known option set names. This is not public since it includes the default
* set name as well, which we don't want to expose.
*
* @return A set containing the names of the option sets, or null if no such sets are defined
*
*/
java.util.Set getSetNames() {
return optionSets.keySet();
}
/**
* This returns the (anonymous) default set
*
* @return The default set
*/
public OptionSet getSet() {
if (getSet(DEFAULT_SET) == null) {
addSet(DEFAULT_SET, defaultMinData, defaultMaxData);
}
return getSet(DEFAULT_SET);
}
/**
* Determine a default prefix depending on the OS platform. This uses the os.name Java system property.
* For Windows, Prefix.SLASH is used, else Prefix.DASH. This will likely need to be
* adapted over time for other platforms and VMs, depending on the string they return for that Java system property.
*
* @return The default prefix for the current platform
*/
private static Prefix getDefaultPrefix() {
String os = System.getProperty("os.name");
if (os.startsWith("Windows")) {
return Prefix.SLASH;
} else {
return Prefix.DASH;
}
}
/**
* This is the overloaded {@link Object#toString()} method.
*
* @return A string representing the instance
*/
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append("defaultPrefix = ");
sb.append(defaultPrefix);
sb.append('\n');
sb.append("defaultAltPrefix = ");
sb.append(defaultAltPrefix);
sb.append('\n');
sb.append("defaultValueSeparator = ");
sb.append(defaultValueSeparator);
sb.append('\n');
sb.append("defaultDetailSeparator = ");
sb.append(defaultDetailSeparator);
sb.append('\n');
sb.append("defaultMultiplicity = ");
sb.append(defaultMultiplicity);
sb.append('\n');
sb.append("defaultMinData = ");
sb.append(defaultMinData);
sb.append('\n');
sb.append("defaultMaxData = ");
sb.append(defaultMaxData);
sb.append('\n');
for (OptionSet set : optionSets.values()) {
sb.append("Set: ");
sb.append(set.getName());
sb.append('\n');
for (OptionData data : set.getOptionData()) {
sb.append(data.toString());
sb.append('\n');
}
}
return sb.toString();
}
// ==========================================================================================
// The checks
// ==========================================================================================
/**
* The error messages collected during the last option check
* (invocation of any of the check() methods). This
* is useful to determine what was wrong with the command
* line arguments provided
*
* @return A string with all collected error messages
*/
public String getCheckErrors() {
return checkErrors.toString();
}
/**
* Run the checks for the default set with default parameters. This is equivalent
* to calling check(false, true). If the default set has not yet been
* used at all, it is created here with the default settings.
*
* @return A boolean indicating whether all checks were successful or not
*/
public boolean check() {
if (getSet(DEFAULT_SET) == null) {
addSet(DEFAULT_SET, defaultMinData, defaultMaxData);
}
return check(DEFAULT_SET, false, true);
}
/**
* Run the checks for the default set. If the default set has not yet been
* used at all, it is created here with the default settings.
*
* @param ignoreUnmatched A boolean to select whether unmatched options can be ignored in the checks or not
* @param requireDataLast A boolean to indicate whether the data items have to be the last ones on the command line or not
*
* @return A boolean indicating whether all checks were successful or not
*/
public boolean check(boolean ignoreUnmatched, boolean requireDataLast) {
if (getSet(DEFAULT_SET) == null) {
addSet(DEFAULT_SET, defaultMinData, defaultMaxData);
}
return check(DEFAULT_SET, ignoreUnmatched, requireDataLast);
}
/**
* Run the checks for the given set with default parameters. This is equivalent
* to calling check(name, false, true).
*
* @param name The name for the set to check
*
* @return A boolean indicating whether all checks were successful or not
*/
public boolean check(String name) {
return check(name, false, true);
}
/**
* Run the checks for the given set.
*
* @param name The name for the set to check
* @param ignoreUnmatched A boolean to select whether unmatched options can be ignored in the checks or not
* @param requireDataLast A boolean to indicate whether the data items have to be the last
* ones on the command line or not
*
* @return A boolean indicating whether all checks were successful or not
*/
public boolean check(String name, boolean ignoreUnmatched, boolean requireDataLast) {
if (name == null) {
throw new IllegalArgumentException(CLASS + ": name may not be null");
}
if (optionSets.get(name) == null) {
throw new IllegalArgumentException(CLASS + ": Unknown OptionSet: " + name);
}
checkErrors.append("Checking set ");
checkErrors.append(name);
checkErrors.append('\n');
//.... Access the data for the set to use
OptionSet set = optionSets.get(name);
java.util.List options = set.getOptionData();
java.util.List data = set.getData();
java.util.List unmatched = set.getUnmatched();
//.... Catch some trivial cases
if (options.size() == 0) { // No options have been defined at all
if (arguments.length == 0) {
if (set.acceptsData()) {
checkErrors.append("The set expects data, but no arguments have been given\n");
return false;
} else { // No options and no data expected, no arguments given - technically true, but useless
return true;
}
}
} else if (arguments.length == 0) { // Options have been defined, but no arguments given
checkErrors.append("Options have been defined, but no arguments have been given; nothing to check\n");
return false;
}
//.... Parse all the arguments given
int ipos = 0;
int offset = 0;
int start = 0;
java.util.regex.Matcher m = null;
String value = null;
String detail = null;
String next = null;
String key = null;
String pre = defaultPrefix.getName();
String altPre = defaultAltPrefix.getName();
boolean add = true;
boolean[] matched = new boolean[arguments.length];
for (int i = 0; i < matched.length; i++) // Initially, we assume there was no match at all
{
matched[i] = false;
}
while (true) {
value = null;
detail = null;
offset = 0;
start = 1;
add = true;
key = arguments[ipos];
for (OptionData optionData : options) { // For each argument, we need to check all defined options
m = optionData.getPattern().matcher(key);
if (m.lookingAt()) {
if (optionData.useValue()) { // The code section for value options
if (optionData.hasAlternateKey()) {
start = 2;
}
if (optionData.useDetail()) {
detail = m.group(start);
offset = 2; // required for correct Matcher.group access below
}
if (optionData.getSeparator() == Separator.BLANK) { // In this case, the next argument must be the value
if (ipos + 1 == arguments.length) { // The last argument, thus no value follows it: Error
checkErrors.append("At end of arguments - no value found following argument ");
checkErrors.append(key);
checkErrors.append('\n');
add = false;
} else {
next = arguments[ipos + 1];
if (next.startsWith(pre) || next.startsWith(altPre)) { // The next item is not a value: Error
checkErrors.append("No value found following argument ");
checkErrors.append(key);
checkErrors.append('\n');
add = false;
} else {
value = next;
matched[ipos++] = true; // Mark the key and the value
matched[ipos] = true;
}
}
} else { // The value follows the separator in this case
value = m.group(start + offset);
matched[ipos] = true;
}
} else { // Simple, non-value options
matched[ipos] = true;
}
if (add) {
optionData.addResult(value, detail); // Store the result
}
break; // No need to check more options, we have a match
}
}
ipos++; // Advance to the next argument to check
if (ipos >= arguments.length) {
break;
} // Terminating condition for the check loop
}
//.... Identify unmatched arguments and actual (non-option) data
int first = -1; // Required later for requireDataLast
for (int i = 0; i < matched.length; i++) { // Assemble the list of unmatched options
if (!matched[i]) {
if (arguments[i].startsWith(pre) || arguments[i].startsWith(altPre)) { // An unmatched option
unmatched.add(arguments[i]);
checkErrors.append("No matching option found for argument ");
checkErrors.append(arguments[i]);
checkErrors.append('\n');
} else { // This is actual data
if (first < 0) {
first = i;
}
data.add(arguments[i]);
}
}
}
//.... Checks to determine overall success, start with the multiplicity of options
boolean err = true;
for (OptionData optionData : options) {
if (!optionData.isExclusive()) { // Only check options which are not part of an ExclusiveConstraint
key = optionData.getKey();
err = false; // Local check result for one option
switch (optionData.getMultiplicity()) {
case ONCE:
if (optionData.getResultCount() != 1) {
err = true;
}
break;
case ONCE_OR_MORE:
if (optionData.getResultCount() == 0) {
err = true;
}
break;
case ZERO_OR_ONCE:
if (optionData.getResultCount() > 1) {
err = true;
}
break;
}
if (err) {
checkErrors.append("Wrong number of occurences found for argument ");
checkErrors.append(pre);
checkErrors.append(key);
checkErrors.append('\n');
return false;
}
}
}
//.... Check defined constraints for all options
for (OptionData optionData : options) {
if (optionData.isSet() && (optionData.getConstraints() != null)) {
for (Constraint constraint : optionData.getConstraints()) {
if (!constraint.isSatisfied()) {
checkErrors.append("Constraint ");
checkErrors.append(constraint.toString());
checkErrors.append(" violated for option '");
checkErrors.append(optionData.getKey());
checkErrors.append("'\n");
return false;
}
}
}
}
//.... Check defined constraints for the current set
if (set.getConstraints() != null) {
for (Constraint constraint : set.getConstraints()) {
if (!constraint.isSatisfied()) {
checkErrors.append("Constraint ");
checkErrors.append(constraint.toString());
checkErrors.append(" violated for option set '");
checkErrors.append(set.getName());
checkErrors.append("'\n");
return false;
}
}
}
//.... Check range for data
int limit = set.getMaxData();
if (set.hasUnlimitedData()) {
limit = Integer.MAX_VALUE;
}
if (data.size() < set.getMinData() || data.size() > limit) {
checkErrors.append("Invalid number of data arguments: ");
checkErrors.append(data.size());
checkErrors.append(" (allowed range: ");
checkErrors.append(set.getMinData());
checkErrors.append(" ... ");
checkErrors.append(set.getMaxData());
checkErrors.append(")\n");
return false;
}
//.... Check for location of the data in the list of command line arguments
if (requireDataLast && data.size() > 0) {
if (first + data.size() != arguments.length) {
checkErrors.append("Invalid data specification: data arguments are not the last ones on the command line\n");
return false;
}
}
//.... Check for unmatched arguments
if (!ignoreUnmatched && unmatched.size() > 0) {
return false;
} // Don't accept unmatched arguments
//.... If we made it to here, all checks were successful
return true;
}
// ==========================================================================================
// Add a value option for all sets
// ==========================================================================================
/**
* Add the given option to all known sets.
*
* @param type The type of the option
* @param key The name of the option
*/
public void addOptionAllSets(OptionData.Type type, String key) {
for (String name : optionSets.keySet()) {
optionSets.get(name).addOption(type,
key,
null,
type.detail() ? defaultDetailSeparator : defaultValueSeparator,
defaultMultiplicity);
}
}
/**
* Add the given option to all known sets.
*
* @param type The type of the option
* @param key The name of the option
* @param multiplicity The multiplicity of the option
*/
public void addOptionAllSets(OptionData.Type type, String key, Multiplicity multiplicity) {
for (String name : optionSets.keySet()) {
optionSets.get(name).addOption(type,
key,
null,
type.detail() ? defaultDetailSeparator : defaultValueSeparator,
multiplicity);
}
}
/**
* Add the given option to all known sets.
*
* @param type The type of the option
* @param key The name of the option
* @param altKey The alternate name of the option
*/
public void addOptionAllSets(OptionData.Type type, String key, String altKey) {
for (String name : optionSets.keySet()) {
optionSets.get(name).addOption(type,
key,
altKey,
type.detail() ? defaultDetailSeparator : defaultValueSeparator,
defaultMultiplicity);
}
}
/**
* Add the given option to all known sets.
*
* @param type The type of the option
* @param key The name of the option
* @param altKey The alternate name of the option
* @param multiplicity The multiplicity of the option
*/
public void addOptionAllSets(OptionData.Type type, String key, String altKey, Multiplicity multiplicity) {
for (String name : optionSets.keySet()) {
optionSets.get(name).addOption(type,
key,
altKey,
type.detail() ? defaultDetailSeparator : defaultValueSeparator,
multiplicity);
}
}
}