ArgumentParser.java revision 49026dcadd8edca32a2628f768a9e0d92a07996e
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License, Version 1.0 only
* (the "License"). You may not use this file except in compliance
* with the License.
*
* You can obtain a copy of the license at
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at
* trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable,
* add the following below this CDDL HEADER, with the fields enclosed
* by brackets "[]" replaced with your own identifying information:
* Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*
*
* Portions Copyright 2006-2007 Sun Microsystems, Inc.
*/
/**
* This class defines a utility that can be used to deal with command-line
* arguments for applications in a CLIP-compliant manner using either short
* one-character or longer word-based arguments. It is also integrated with the
* Directory Server message catalog so that it can display messages in an
* internationalizeable format, can automatically generate usage information,
* can detect conflicts between arguments, and can interact with a properties
* file to obtain default values for arguments there if they are not specified
* on the command-line.
*/
public class ArgumentParser
{
// The argument that will be used to trigger the display of usage information.
private Argument usageArgument;
// The set of unnamed trailing arguments that were provided for this parser.
// Indicates whether this parser will allow additional unnamed arguments at
// the end of the list.
private boolean allowsTrailingArguments;
// Indicates whether long arguments should be treated in a case-sensitive
// manner.
private boolean longArgumentsCaseSensitive;
// Indicates whether the usage information has been displayed.
private boolean usageDisplayed;
// The set of arguments defined for this parser, referenced by short ID.
// The set of arguments defined for this parser, referenced by argument name.
// The set of arguments defined for this parser, referenced by long ID.
// The maximum number of unnamed trailing arguments that may be provided.
private int maxTrailingArguments;
// The minimum number of unnamed trailing arguments that may be provided.
private int minTrailingArguments;
// The total set of arguments defined for this parser.
// The output stream to which usage information should be printed.
private OutputStream usageOutputStream;
// The fully-qualified name of the Java class that should be invoked to launch
// the program with which this argument parser is associated.
private String mainClassName;
// A human-readable description for the tool, which will be included when
// displaying usage information.
private String toolDescription;
// The display name that will be used for the trailing arguments in the usage
// information.
private String trailingArgsDisplayName;
// The raw set of command-line arguments that were provided.
private String[] rawArguments;
/**
* Creates a new instance of this argument parser with no arguments.
* Unnamed trailing arguments will not be allowed.
*
* @param mainClassName The fully-qualified name of the Java
* class that should be invoked to launch
* the program with which this argument
* parser is associated.
* @param toolDescription A human-readable description for the
* tool, which will be included when
* displaying usage information.
* @param longArgumentsCaseSensitive Indicates whether long arguments should
* be treated in a case-sensitive manner.
*/
boolean longArgumentsCaseSensitive)
{
this.mainClassName = mainClassName;
this.toolDescription = toolDescription;
allowsTrailingArguments = false;
usageDisplayed = false;
maxTrailingArguments = 0;
minTrailingArguments = 0;
rawArguments = null;
}
/**
* Creates a new instance of this argument parser with no arguments that may
* or may not be allowed to have unnamed trailing arguments.
*
* @param mainClassName The fully-qualified name of the Java
* class that should be invoked to launch
* the program with which this argument
* parser is associated.
* @param toolDescription A human-readable description for the
* tool, which will be included when
* displaying usage information.
* @param longArgumentsCaseSensitive Indicates whether long arguments should
* be treated in a case-sensitive manner.
* @param allowsTrailingArguments Indicates whether this parser allows
* unnamed trailing arguments to be
* provided.
* @param minTrailingArguments The minimum number of unnamed trailing
* arguments that must be provided. A
* value less than or equal to zero
* indicates that no minimum will be
* enforced.
* @param maxTrailingArguments The maximum number of unnamed trailing
* arguments that may be provided. A
* value less than or equal to zero
* indicates that no maximum will be
* enforced.
* @param trailingArgsDisplayName The display name that should be used
* as a placeholder for unnamed trailing
* arguments in the generated usage
* information.
*/
boolean longArgumentsCaseSensitive,
boolean allowsTrailingArguments,
int minTrailingArguments, int maxTrailingArguments,
{
this.mainClassName = mainClassName;
this.toolDescription = toolDescription;
usageDisplayed = false;
rawArguments = null;
}
/**
* Retrieves the fully-qualified name of the Java class that should be invoked
* to launch the program with which this argument parser is associated.
*
* @return The fully-qualified name of the Java class that should be invoked
* to launch the program with which this argument parser is
* associated.
*/
public String getMainClassName()
{
return mainClassName;
}
/**
* Retrieves a human-readable description for this tool, which should be
* included at the top of the command-line usage information.
*
* @return A human-readable description for this tool, or {@code null} if
* none is available.
*/
public String getToolDescription()
{
return toolDescription;
}
/**
* Indicates whether this parser will allow unnamed trailing arguments. These
* will be arguments at the end of the list that are not preceded by either a
* long or short identifier and will need to be manually parsed by the
* application using this parser. Note that once an unnamed trailing argument
* has been identified, all remaining arguments will be classified as such.
*
* @return <CODE>true</CODE> if this parser allows unnamed trailing
* arguments, or <CODE>false</CODE> if it does not.
*/
public boolean allowsTrailingArguments()
{
return allowsTrailingArguments;
}
/**
* Retrieves the minimum number of unnamed trailing arguments that must be
* provided.
*
* @return The minimum number of unnamed trailing arguments that must be
* provided, or a value less than or equal to zero if no minimum will
* be enforced.
*/
public int getMinTrailingArguments()
{
return minTrailingArguments;
}
/**
* Retrieves the maximum number of unnamed trailing arguments that may be
* provided.
*
* @return The maximum number of unnamed trailing arguments that may be
* provided, or a value less than or equal to zero if no maximum will
* be enforced.
*/
public int getMaxTrailingArguments()
{
return maxTrailingArguments;
}
/**
* Retrieves the list of all arguments that have been defined for this
* argument parser.
*
* @return The list of all arguments that have been defined for this argument
* parser.
*/
{
return argumentList;
}
/**
* Retrieves the argument with the specified name.
*
* @param name The name of the argument to retrieve.
*
* @return The argument with the specified name, or <CODE>null</CODE> if
* there is no such argument.
*/
{
}
/**
* Retrieves the set of arguments mapped by the short identifier that may be
* used to reference them. Note that arguments that do not have a short
* identifier will not be present in this list.
*
* @return The set of arguments mapped by the short identifier that may be
* used to reference them.
*/
{
return shortIDMap;
}
/**
* Retrieves the argument with the specified short identifier.
*
* @param shortID The short ID for the argument to retrieve.
*
* @return The argument with the specified short identifier, or
* <CODE>null</CODE> if there is no such argument.
*/
{
}
/**
* Retrieves the set of arguments mapped by the long identifier that may be
* used to reference them. Note that arguments that do not have a long
* identifier will not be present in this list.
*
* @return The set of arguments mapped by the long identifier that may be
* used to reference them.
*/
{
return longIDMap;
}
/**
* Retrieves the argument with the specified long identifier.
*
* @param longID The long identifier of the argument to retrieve.
*
* @return The argument with the specified long identifier, or
* <CODE>null</CODE> if there is no such argument.
*/
{
}
/**
* Retrieves the set of unnamed trailing arguments that were provided on the
* command line.
*
* @return The set of unnamed trailing arguments that were provided on the
* command line.
*/
{
return trailingArguments;
}
/**
* Retrieves the raw set of arguments that were provided.
*
* @return The raw set of arguments that were provided, or <CODE>null</CODE>
* if the argument list has not yet been parsed.
*/
public String[] getRawArguments()
{
return rawArguments;
}
/**
* Adds the provided argument to the set of arguments handled by this parser.
*
* @param argument The argument to be added.
*
* @throws ArgumentException If the provided argument conflicts with another
* argument that has already been defined.
*/
throws ArgumentException
{
{
}
{
if (! longArgumentsCaseSensitive)
{
}
{
}
}
{
}
{
}
}
/**
* Sets the provided argument as one which will automatically trigger the
* output of usage information if it is provided on the command line and no
* further argument validation will be performed. Note that the caller will
* still need to add this argument to the parser with the
* <CODE>addArgument</CODE> method, and the argument should not be required
* and should not take a value. Also, the caller will still need to check
* for the presence of the usage argument after calling
* <CODE>parseArguments</CODE> to know that no further processing will be
* required.
*
* @param argument The argument whose presence should automatically
* trigger the display of usage information.
*/
{
}
/**
* Sets the provided argument as one which will automatically trigger the
* output of usage information if it is provided on the command line and no
* further argument validation will be performed. Note that the caller will
* still need to add this argument to the parser with the
* <CODE>addArgument</CODE> method, and the argument should not be required
* and should not take a value. Also, the caller will still need to check
* for the presence of the usage argument after calling
* <CODE>parseArguments</CODE> to know that no further processing will be
* required.
*
* @param argument The argument whose presence should automatically
* trigger the display of usage information.
* @param outputStream The output stream to which the usage information
* should be written.
*/
{
}
/**
* Parses the provided set of arguments and updates the information associated
* with this parser accordingly.
*
* @param rawArguments The raw set of arguments to parse.
*
* @throws ArgumentException If a problem was encountered while parsing the
* provided arguments.
*/
throws ArgumentException
{
}
/**
* Parses the provided set of arguments and updates the information associated
* with this parser accordingly. Default values for unspecified arguments
* may be read from the specified properties file.
*
* @param rawArguments The set of raw arguments to parse.
* @param propertiesFile The path to the properties file to use to
* obtain default values for unspecified
* properties.
* @param requirePropertiesFile Indicates whether the parsing should fail if
* the provided properties file does not exist
* or is not accessible.
*
* @throws ArgumentException If a problem was encountered while parsing the
* provided arguments or interacting with the
* properties file.
*/
boolean requirePropertiesFile)
throws ArgumentException
{
this.rawArguments = rawArguments;
try
{
Properties p = new Properties();
argumentProperties = p;
}
catch (Exception e)
{
{
}
}
}
/**
* Parses the provided set of arguments and updates the information associated
* with this parser accordingly. Default values for unspecified arguments may
* be read from the specified properties if any are provided.
*
* @param rawArguments The set of raw arguments to parse.
* @param argumentProperties A set of properties that may be used to provide
* default values for arguments not included in
* the given raw arguments.
*
* @throws ArgumentException If a problem was encountered while parsing the
* provided arguments.
*/
throws ArgumentException
{
this.rawArguments = rawArguments;
boolean inTrailingArgs = false;
for (int i=0; i < numArguments; i++)
{
if (inTrailingArgs)
{
if ((maxTrailingArguments > 0) &&
{
}
continue;
}
{
// This is a special indicator that we have reached the end of the named
// arguments and that everything that follows after this should be
// considered trailing arguments.
inTrailingArgs = true;
}
{
// This indicates that we are using the long name to reference the
// argument. It may be in any of the following forms:
// --name
// --name value
// --name=value
if (equalPos < 0)
{
// This is fine. The value is not part of the argument name token.
}
else if (equalPos == 0)
{
// The argument starts with "--=", which is not acceptable.
}
else
{
// The argument is in the form --name=value, so parse them both out.
}
// If we're not case-sensitive, then convert the name to lowercase.
if (! longArgumentsCaseSensitive)
{
}
// Get the argument with the specified name.
if (a == null)
{
{
// "--help" will always be interpreted as requesting usage
// information.
try
{
} catch (Exception e) {}
return;
}
else
{
// There is no such argument registered.
}
}
else
{
a.setPresent(true);
// If this is the usage argument, then immediately stop and print
// usage information.
if ((usageArgument != null) &&
{
try
{
} catch (Exception e) {}
return;
}
}
// See if the argument takes a value. If so, then make sure one was
// provided. If not, then make sure none was provided.
if (a.needsValue())
{
{
if ((i+1) == numArguments)
{
}
argValue = rawArguments[++i];
}
{
}
// If the argument already has a value, then make sure it is
// acceptable to have more than one.
if (a.hasValue() && (! a.isMultiValued()))
{
}
}
else
{
{
}
}
}
{
// This indicates that we are using the 1-character name to reference
// the argument. It may be in any of the following forms:
// -n
// -nvalue
// -n value
{
}
{
}
else
{
}
// Get the argument with the specified short ID.
if (a == null)
{
if (argCharacter == '?')
{
// "-?" will always be interpreted as requesting usage information.
try
{
} catch (Exception e) {}
return;
}
else
{
// There is no such argument registered.
}
}
else
{
a.setPresent(true);
// If this is the usage argument, then immediately stop and print
// usage information.
if ((usageArgument != null) &&
{
try
{
} catch (Exception e) {}
return;
}
}
// See if the argument takes a value. If so, then make sure one was
// provided. If not, then make sure none was provided.
if (a.needsValue())
{
{
if ((i+1) == numArguments)
{
}
argValue = rawArguments[++i];
}
{
}
// If the argument already has a value, then make sure it is
// acceptable to have more than one.
if (a.hasValue() && (! a.isMultiValued()))
{
}
}
else
{
{
// If we've gotten here, then it means that we're in a scenario like
// "-abc" where "a" is a valid argument that doesn't take a value.
// However, this could still be valid if all remaining characters in
// the value are also valid argument characters that don't take
// values.
for (int j=0; j < valueLength; j++)
{
if (b == null)
{
// There is no such argument registered.
}
else if (b.needsValue())
{
// This means we're in a scenario like "-abc" where b is a
// valid argument that takes a value. We don't support that.
}
else
{
b.setPresent(true);
// If this is the usage argument, then immediately stop and
// print usage information.
if ((usageArgument != null) &&
{
try
{
} catch (Exception e) {}
return;
}
}
}
}
}
}
else if (allowsTrailingArguments)
{
// It doesn't start with a dash, so it must be a trailing argument if
// that is acceptable.
inTrailingArgs = true;
}
else
{
// It doesn't start with a dash and we don't allow trailing arguments,
// so this is illegal.
}
}
// If we allow trailing arguments and there is a minimum number, then make
// sure at least that many were provided.
{
{
}
}
// Iterate through all of the arguments. For any that were not provided on
// the command line, see if there is an alternate default that can be used.
// For cases where there is not, see that argument is required.
for (Argument a : argumentList)
{
if ((! a.isPresent()) && a.needsValue())
{
// See if there is a default value in the properties that can be used.
boolean valueSet = false;
{
{
valueSet = true;
}
}
// If there is still no value, then see if the argument defines a
// default.
{
a.addValue(a.getDefaultValue());
valueSet = true;
}
// If there is still no value and the argument is required, then that's
// a problem.
if ((! valueSet) && a.isRequired())
{
}
}
}
}
/**
* Appends usage information based on the defined arguments to the provided
* buffer.
*
* @param buffer The buffer to which the usage information should be
* appended.
*/
{
usageDisplayed = true;
{
}
{
}
else
{
}
{
if (trailingArgsDisplayName == null)
{
}
else
{
}
}
for (Argument a : argumentList)
{
// If this argument is hidden, then skip it.
if (a.isHidden())
{
continue;
}
// for the argument.
{
{
}
{
if (a.needsValue())
{
}
if (lineLength > 80)
{
}
else
{
}
}
}
else
{
{
if (a.needsValue())
{
}
}
}
// Write one or more lines with the description of the argument. We will
// indent the description five characters and try our best to wrap at or
// before column 79 so it will be friendly to 80-column displays.
{
}
else
{
String s = description;
while (s.length() > 75)
{
if (spacePos > 0)
{
}
else
{
// There are no spaces in the first 74 columns. See if there is one
// after that point. If so, then break there. If not, then don't
// break at all.
if (spacePos > 0)
{
}
else
{
s = "";
}
}
}
if (s.length() > 0)
{
}
}
}
}
/**
* Retrieves a string containing usage information based on the defined
* arguments.
*
* @return A string containing usage information based on the defined
* arguments.
*/
{
}
/**
* Writes usage information based on the defined arguments to the provided
* output stream.
*
* @param outputStream The output stream to which the usage information
* should be written.
*
* @throws IOException If a problem occurs while attempting to write the
* usage information to the provided output stream.
*/
throws IOException
{
}
/**
* Indicates whether the usage information has been displayed to the end user
* either by an explicit argument like "-H" or "--help", or by a built-in
* argument like "-?".
*
* @return {@code true} if the usage information has been displayed, or
* {@code false} if not.
*/
public boolean usageDisplayed()
{
return usageDisplayed;
}
}