com.unboundid.util.args
Class ArgumentParser

java.lang.Object
  extended by com.unboundid.util.args.ArgumentParser
All Implemented Interfaces:
java.io.Serializable

@ThreadSafety(level=NOT_THREADSAFE)
public final class ArgumentParser
extends java.lang.Object
implements java.io.Serializable

This class provides an argument parser, which may be used to process command line arguments provided to Java applications. See the package-level Javadoc documentation for details regarding the capabilities of the argument parser.

See Also:
Serialized Form

Constructor Summary
ArgumentParser(java.lang.String commandName, java.lang.String commandDescription)
          Creates a new instance of this argument parser with the provided information.
ArgumentParser(java.lang.String commandName, java.lang.String commandDescription, int maxTrailingArgs, java.lang.String trailingArgsPlaceholder)
          Creates a new instance of this argument parser with the provided information.
 
Method Summary
 void addArgument(Argument argument)
          Registers the provided argument with this argument parser.
 void addDependentArgumentSet(Argument targetArgument, Argument dependentArg1, Argument... remaining)
          Adds the provided collection of arguments as dependent upon the given argument.
 void addDependentArgumentSet(Argument targetArgument, java.util.Collection<Argument> dependentArguments)
          Adds the provided collection of arguments as dependent upon the given argument.
 void addExclusiveArgumentSet(Argument arg1, Argument arg2, Argument... remaining)
          Adds the provided set of arguments as an exclusive argument set, in which at most one of the arguments may be provided.
 void addExclusiveArgumentSet(java.util.Collection<Argument> exclusiveArguments)
          Adds the provided collection of arguments as an exclusive argument set, in which at most one of the arguments may be provided.
 void addRequiredArgumentSet(Argument arg1, Argument arg2, Argument... remaining)
          Adds the provided set of arguments as a required argument set, in which at least one of the arguments must be provided.
 void addRequiredArgumentSet(java.util.Collection<Argument> requiredArguments)
          Adds the provided collection of arguments as a required argument set, in which at least one of the arguments must be provided.
 boolean allowsTrailingArguments()
          Indicates whether this argument parser allows any unnamed trailing arguments to be provided.
 ArgumentParser getCleanCopy()
          Creates a copy of this argument parser that is "clean" and appears as if it has not been used to parse an argument set.
 java.lang.String getCommandDescription()
          Retrieves a description of the application or utility with which this command line argument parser is associated.
 java.lang.String getCommandName()
          Retrieves the name of the application or utility with which this command line argument parser is associated.
 java.util.List<ObjectPair<Argument,java.util.Set<Argument>>> getDependentArgumentSets()
          Retrieves the list of dependent argument sets for this argument parser.
 java.util.List<java.util.Set<Argument>> getExclusiveArgumentSets()
          Retrieves the list of exclusive argument sets for this argument parser.
 int getMaxTrailingArguments()
          Retrieves the maximum number of unnamed trailing arguments that may be provided.
 Argument getNamedArgument(java.lang.Character shortIdentifier)
          Retrieves the named argument with the specified short identifier.
 Argument getNamedArgument(java.lang.String longIdentifier)
          Retrieves the named argument with the specified long identifier.
 java.util.List<Argument> getNamedArguments()
          Retrieves the set of named arguments defined for use with this argument parser.
 java.util.List<java.util.Set<Argument>> getRequiredArgumentSets()
          Retrieves the list of required argument sets for this argument parser.
 java.util.List<java.lang.String> getTrailingArguments()
          Retrieves the set of unnamed trailing arguments in the provided command line arguments.
 java.lang.String getTrailingArgumentsPlaceholder()
          Retrieves the placeholder string that will be provided in usage information to indicate what may be included in the trailing arguments.
 java.util.List<java.lang.String> getUsage(int maxWidth)
          Retrieves lines that make up the usage information for this program, optionally wrapping long lines.
 void getUsage(java.io.OutputStream outputStream, int maxWidth)
          Writes usage information for this program to the provided output stream using the UTF-8 encoding, optionally wrapping long lines.
 java.lang.String getUsageString(int maxWidth)
          Retrieves a string representation of the usage information.
 void getUsageString(java.lang.StringBuilder buffer, int maxWidth)
          Appends a string representation of the usage information to the provided buffer.
 void parse(java.lang.String[] args)
          Parses the provided set of arguments.
 java.lang.String toString()
          Retrieves a string representation of this argument parser.
 void toString(java.lang.StringBuilder buffer)
          Appends a string representation of this argument parser to the provided buffer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ArgumentParser

public ArgumentParser(java.lang.String commandName,
                      java.lang.String commandDescription)
               throws ArgumentException
Creates a new instance of this argument parser with the provided information. It will not allow unnamed trailing arguments.

Parameters:
commandName - The name of the application or utility with which this argument parser is associated. It must not be null.
commandDescription - A description of the application or utility with which this argument parser is associated. It will be included in generated usage information. It must not be null.
Throws:
ArgumentException - If either the command name or command description is null,

ArgumentParser

public ArgumentParser(java.lang.String commandName,
                      java.lang.String commandDescription,
                      int maxTrailingArgs,
                      java.lang.String trailingArgsPlaceholder)
               throws ArgumentException
Creates a new instance of this argument parser with the provided information.

Parameters:
commandName - The name of the application or utility with which this argument parser is associated. It must not be null.
commandDescription - A description of the application or utility with which this argument parser is associated. It will be included in generated usage information. It must not be null.
maxTrailingArgs - The maximum number of trailing arguments that may be provided to this command. A value of zero indicates that no trailing arguments will be allowed. A value less than zero will indicate that there is no limit on the number of trailing arguments allowed.
trailingArgsPlaceholder - A placeholder string that will be included in usage output to indicate what trailing arguments may be provided. It must not be null if maxTrailingArgs is anything other than zero.
Throws:
ArgumentException - If either the command name or command description is null, or if the maximum number of trailing arguments is non-zero and the trailing arguments placeholder is null.
Method Detail

getCommandName

public java.lang.String getCommandName()
Retrieves the name of the application or utility with which this command line argument parser is associated.

Returns:
The name of the application or utility with which this command line argument parser is associated.

getCommandDescription

public java.lang.String getCommandDescription()
Retrieves a description of the application or utility with which this command line argument parser is associated.

Returns:
A description of the application or utility with which this command line argument parser is associated.

allowsTrailingArguments

public boolean allowsTrailingArguments()
Indicates whether this argument parser allows any unnamed trailing arguments to be provided.

Returns:
true if at least one unnamed trailing argument may be provided, or false if not.

getTrailingArgumentsPlaceholder

public java.lang.String getTrailingArgumentsPlaceholder()
Retrieves the placeholder string that will be provided in usage information to indicate what may be included in the trailing arguments.

Returns:
The placeholder string that will be provided in usage information to indicate what may be included in the trailing arguments, or null if unnamed trailing arguments are not allowed.

getMaxTrailingArguments

public int getMaxTrailingArguments()
Retrieves the maximum number of unnamed trailing arguments that may be provided.

Returns:
The maximum number of unnamed trailing arguments that may be provided.

getNamedArgument

public Argument getNamedArgument(java.lang.Character shortIdentifier)
Retrieves the named argument with the specified short identifier.

Parameters:
shortIdentifier - The short identifier of the argument to retrieve. It must not be null.
Returns:
The named argument with the specified short identifier, or null if there is no such argument.

getNamedArgument

public Argument getNamedArgument(java.lang.String longIdentifier)
Retrieves the named argument with the specified long identifier.

Parameters:
longIdentifier - The long identifier of the argument to retrieve. It must not be null.
Returns:
The named argument with the specified long identifier, or null if there is no such argument.

getNamedArguments

public java.util.List<Argument> getNamedArguments()
Retrieves the set of named arguments defined for use with this argument parser.

Returns:
The set of named arguments defined for use with this argument parser.

addArgument

public void addArgument(Argument argument)
                 throws ArgumentException
Registers the provided argument with this argument parser.

Parameters:
argument - The argument to be registered.
Throws:
ArgumentException - If the provided argument conflicts with another argument already registered with this parser.

getDependentArgumentSets

public java.util.List<ObjectPair<Argument,java.util.Set<Argument>>> getDependentArgumentSets()
Retrieves the list of dependent argument sets for this argument parser. If an argument contained as the first object in the pair in a dependent argument set is provided, then at least one of the arguments in the paired set must also be provided.

Returns:
The list of dependent argument sets for this argument parser.

addDependentArgumentSet

public void addDependentArgumentSet(Argument targetArgument,
                                    java.util.Collection<Argument> dependentArguments)
Adds the provided collection of arguments as dependent upon the given argument.

Parameters:
targetArgument - The argument whose presence indicates that at least one of the dependent arguments must also be present. It must not be null.
dependentArguments - The set of arguments from which at least one argument must be present if the target argument is present. It must not be null or empty.

addDependentArgumentSet

public void addDependentArgumentSet(Argument targetArgument,
                                    Argument dependentArg1,
                                    Argument... remaining)
Adds the provided collection of arguments as dependent upon the given argument.

Parameters:
targetArgument - The argument whose presence indicates that at least one of the dependent arguments must also be present. It must not be null.
dependentArg1 - The first argument in the set of arguments in which at least one argument must be present if the target argument is present. It must not be null.
remaining - The remaining arguments in the set of arguments in which at least one argument must be present if the target argument is present.

getExclusiveArgumentSets

public java.util.List<java.util.Set<Argument>> getExclusiveArgumentSets()
Retrieves the list of exclusive argument sets for this argument parser. If an argument contained in an exclusive argument set is provided, then none of the other arguments in that set may be provided. It is acceptable for none of the arguments in the set to be provided, unless the same set of arguments is also defined as a required argument set.

Returns:
The list of exclusive argument sets for this argument parser.

addExclusiveArgumentSet

public void addExclusiveArgumentSet(java.util.Collection<Argument> exclusiveArguments)
Adds the provided collection of arguments as an exclusive argument set, in which at most one of the arguments may be provided.

Parameters:
exclusiveArguments - The collection of arguments to form an exclusive argument set. It must not be null.

addExclusiveArgumentSet

public void addExclusiveArgumentSet(Argument arg1,
                                    Argument arg2,
                                    Argument... remaining)
Adds the provided set of arguments as an exclusive argument set, in which at most one of the arguments may be provided.

Parameters:
arg1 - The first argument to include in the exclusive argument set. It must not be null.
arg2 - The second argument to include in the exclusive argument set. It must not be null.
remaining - Any additional arguments to include in the exclusive argument set.

getRequiredArgumentSets

public java.util.List<java.util.Set<Argument>> getRequiredArgumentSets()
Retrieves the list of required argument sets for this argument parser. At least one of the arguments contained in this set must be provided. If this same set is also defined as an exclusive argument set, then exactly one of those arguments must be provided.

Returns:
The list of required argument sets for this argument parser.

addRequiredArgumentSet

public void addRequiredArgumentSet(java.util.Collection<Argument> requiredArguments)
Adds the provided collection of arguments as a required argument set, in which at least one of the arguments must be provided.

Parameters:
requiredArguments - The collection of arguments to form an required argument set. It must not be null.

addRequiredArgumentSet

public void addRequiredArgumentSet(Argument arg1,
                                   Argument arg2,
                                   Argument... remaining)
Adds the provided set of arguments as a required argument set, in which at least one of the arguments must be provided.

Parameters:
arg1 - The first argument to include in the required argument set. It must not be null.
arg2 - The second argument to include in the required argument set. It must not be null.
remaining - Any additional arguments to include in the required argument set.

getTrailingArguments

public java.util.List<java.lang.String> getTrailingArguments()
Retrieves the set of unnamed trailing arguments in the provided command line arguments.

Returns:
The set of unnamed trailing arguments in the provided command line arguments, or an empty list if there were none.

getCleanCopy

public ArgumentParser getCleanCopy()
Creates a copy of this argument parser that is "clean" and appears as if it has not been used to parse an argument set. The new parser will have all of the same arguments and constraints as this parser.

Returns:
The "clean" copy of this argument parser.

parse

public void parse(java.lang.String[] args)
           throws ArgumentException
Parses the provided set of arguments.

Parameters:
args - An array containing the argument information to parse. It must not be null.
Throws:
ArgumentException - If a problem occurs while attempting to parse the argument information.

getUsage

public java.util.List<java.lang.String> getUsage(int maxWidth)
Retrieves lines that make up the usage information for this program, optionally wrapping long lines.

Parameters:
maxWidth - The maximum line width to use for the output. If this is less than or equal to zero, then no wrapping will be performed.
Returns:
The lines that make up the usage information for this program.

getUsage

public void getUsage(java.io.OutputStream outputStream,
                     int maxWidth)
              throws java.io.IOException
Writes usage information for this program to the provided output stream using the UTF-8 encoding, optionally wrapping long lines.

Parameters:
outputStream - The output stream to which the usage information should be written. It must not be null.
maxWidth - The maximum line width to use for the output. If this is less than or equal to zero, then no wrapping will be performed.
Throws:
java.io.IOException - If an error occurs while attempting to write to the provided output stream.

getUsageString

public java.lang.String getUsageString(int maxWidth)
Retrieves a string representation of the usage information.

Parameters:
maxWidth - The maximum line width to use for the output. If this is less than or equal to zero, then no wrapping will be performed.
Returns:
A string representation of the usage information

getUsageString

public void getUsageString(java.lang.StringBuilder buffer,
                           int maxWidth)
Appends a string representation of the usage information to the provided buffer.

Parameters:
buffer - The buffer to which the information should be appended.
maxWidth - The maximum line width to use for the output. If this is less than or equal to zero, then no wrapping will be performed.

toString

public java.lang.String toString()
Retrieves a string representation of this argument parser.

Overrides:
toString in class java.lang.Object
Returns:
A string representation of this argument parser.

toString

public void toString(java.lang.StringBuilder buffer)
Appends a string representation of this argument parser to the provided buffer.

Parameters:
buffer - The buffer to which the information should be appended.