@ThreadSafety(level=NOT_THREADSAFE) public final class ArgumentParser extends java.lang.Object implements java.io.Serializable
Constructor and Description |
---|
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.
|
Modifier and Type | Method and Description |
---|---|
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.
|
public ArgumentParser(java.lang.String commandName, java.lang.String commandDescription) throws ArgumentException
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
.ArgumentException
- If either the command name or command
description is null
,public ArgumentParser(java.lang.String commandName, java.lang.String commandDescription, int maxTrailingArgs, java.lang.String trailingArgsPlaceholder) throws ArgumentException
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.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
.public java.lang.String getCommandName()
public java.lang.String getCommandDescription()
public boolean allowsTrailingArguments()
true
if at least one unnamed trailing argument may be
provided, or false
if not.public java.lang.String getTrailingArgumentsPlaceholder()
null
if unnamed trailing arguments are not allowed.public int getMaxTrailingArguments()
public Argument getNamedArgument(java.lang.Character shortIdentifier)
shortIdentifier
- The short identifier of the argument to retrieve.
It must not be null
.null
if there is no such argument.public Argument getNamedArgument(java.lang.String longIdentifier)
longIdentifier
- The long identifier of the argument to retrieve.
It must not be null
.null
if there is no such argument.public java.util.List<Argument> getNamedArguments()
public void addArgument(Argument argument) throws ArgumentException
argument
- The argument to be registered.ArgumentException
- If the provided argument conflicts with another
argument already registered with this parser.public java.util.List<ObjectPair<Argument,java.util.Set<Argument>>> getDependentArgumentSets()
public void addDependentArgumentSet(Argument targetArgument, java.util.Collection<Argument> dependentArguments)
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.public void addDependentArgumentSet(Argument targetArgument, Argument dependentArg1, Argument... remaining)
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.public java.util.List<java.util.Set<Argument>> getExclusiveArgumentSets()
public void addExclusiveArgumentSet(java.util.Collection<Argument> exclusiveArguments)
exclusiveArguments
- The collection of arguments to form an
exclusive argument set. It must not be
null
.public void addExclusiveArgumentSet(Argument arg1, Argument arg2, Argument... remaining)
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.public java.util.List<java.util.Set<Argument>> getRequiredArgumentSets()
public void addRequiredArgumentSet(java.util.Collection<Argument> requiredArguments)
requiredArguments
- The collection of arguments to form an
required argument set. It must not be
null
.public void addRequiredArgumentSet(Argument arg1, Argument arg2, Argument... remaining)
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.public java.util.List<java.lang.String> getTrailingArguments()
public ArgumentParser getCleanCopy()
public void parse(java.lang.String[] args) throws ArgumentException
args
- An array containing the argument information to parse. It
must not be null
.ArgumentException
- If a problem occurs while attempting to parse
the argument information.public java.util.List<java.lang.String> getUsage(int maxWidth)
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.public void getUsage(java.io.OutputStream outputStream, int maxWidth) throws java.io.IOException
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.java.io.IOException
- If an error occurs while attempting to write to the
provided output stream.public java.lang.String getUsageString(int maxWidth)
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.public void getUsageString(java.lang.StringBuilder buffer, int maxWidth)
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.public java.lang.String toString()
toString
in class java.lang.Object
public void toString(java.lang.StringBuilder buffer)
buffer
- The buffer to which the information should be appended.