@ThreadSafety(level=NOT_THREADSAFE) public final class ArgumentParser extends java.lang.Object implements java.io.Serializable
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
ENV_DEFAULT_PROPERTIES_FILE_PATH
The name of an environment variable that can be used to specify the default
properties file that should be used to obtain the default values for
arguments not specified via the command line.
|
static java.lang.String |
PROPERTY_DEFAULT_PROPERTIES_FILE_PATH
The name of the system property that can be used to specify the default
properties file that should be used to obtain the default values for
arguments not specified via the command line.
|
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 minTrailingArgs,
int maxTrailingArgs,
java.lang.String trailingArgsPlaceholder)
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.
|
void |
addSubCommand(SubCommand subCommand)
Registers the provided subcommand with this argument parser.
|
boolean |
allowsTrailingArguments()
Indicates whether this argument parser allows any unnamed trailing
arguments to be provided.
|
void |
enablePropertiesFileSupport()
Updates this argument parser to enable support for a properties file that
can be used to specify the default values for any properties that were not
supplied via the command line.
|
ArgumentListArgument |
getArgumentListArgument(java.lang.String identifier)
Retrieves the argument list argument with the specified identifier.
|
java.util.List<java.lang.String> |
getArgumentsSetFromPropertiesFile()
Retrieves a list of the string representations of any arguments used for
the associated tool that were set from a properties file rather than
provided on the command line.
|
BooleanArgument |
getBooleanArgument(java.lang.String identifier)
Retrieves the Boolean argument with the specified identifier.
|
BooleanValueArgument |
getBooleanValueArgument(java.lang.String identifier)
Retrieves the Boolean value argument with the specified identifier.
|
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.
|
ControlArgument |
getControlArgument(java.lang.String identifier)
Retrieves the control argument with the specified identifier.
|
java.util.List<ObjectPair<Argument,java.util.Set<Argument>>> |
getDependentArgumentSets()
Retrieves the list of dependent argument sets for this argument parser.
|
DNArgument |
getDNArgument(java.lang.String identifier)
Retrieves the DN argument with the specified identifier.
|
DurationArgument |
getDurationArgument(java.lang.String identifier)
Retrieves the duration argument with the specified identifier.
|
java.util.List<java.util.Set<Argument>> |
getExclusiveArgumentSets()
Retrieves the list of exclusive argument sets for this argument parser.
|
FileArgument |
getFileArgument(java.lang.String identifier)
Retrieves the file argument with the specified identifier.
|
FilterArgument |
getFilterArgument(java.lang.String identifier)
Retrieves the filter argument with the specified identifier.
|
java.io.File |
getGeneratedPropertiesFile()
Indicates whether this argument parser was used to generate a properties
file.
|
IntegerArgument |
getIntegerArgument(java.lang.String identifier)
Retrieves the integer argument with the specified identifier.
|
int |
getMaxTrailingArguments()
Retrieves the maximum number of unnamed trailing arguments that may be
provided.
|
int |
getMinTrailingArguments()
Retrieves the minimum number of unnamed trailing arguments that must be
provided.
|
Argument |
getNamedArgument(java.lang.Character shortIdentifier)
Retrieves the named argument with the specified short identifier.
|
Argument |
getNamedArgument(java.lang.String identifier)
Retrieves the named argument with the specified identifier.
|
java.util.List<Argument> |
getNamedArguments()
Retrieves the set of named arguments defined for use with this argument
parser.
|
java.io.File |
getPropertiesFileUsed()
Retrieves the properties file that was used to obtain values for arguments
not set on the command line.
|
java.util.List<java.util.Set<Argument>> |
getRequiredArgumentSets()
Retrieves the list of required argument sets for this argument parser.
|
ScopeArgument |
getScopeArgument(java.lang.String identifier)
Retrieves the scope argument with the specified identifier.
|
SubCommand |
getSelectedSubCommand()
Retrieves the subcommand that was provided in the set of command-line
arguments, if any.
|
StringArgument |
getStringArgument(java.lang.String identifier)
Retrieves the string argument with the specified identifier.
|
SubCommand |
getSubCommand(java.lang.String name)
Retrieves the subcommand for the provided name.
|
java.util.List<SubCommand> |
getSubCommands()
Retrieves a list of all subcommands associated with this argument parser.
|
TimestampArgument |
getTimestampArgument(java.lang.String identifier)
Retrieves the timestamp argument with the specified identifier.
|
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.
|
boolean |
hasSubCommands()
Indicates whether any subcommands have been registered with this argument
parser.
|
void |
parse(java.lang.String[] args)
Parses the provided set of arguments.
|
boolean |
requiresTrailingArguments()
Indicates whether this argument parser requires at least unnamed trailing
argument to be provided.
|
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 static final java.lang.String PROPERTY_DEFAULT_PROPERTIES_FILE_PATH
public static final java.lang.String ENV_DEFAULT_PROPERTIES_FILE_PATH
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 ArgumentParser(java.lang.String commandName, java.lang.String commandDescription, int minTrailingArgs, 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
.minTrailingArgs
- The minimum number of trailing arguments
that must be provided for this command. A
value of zero indicates that the command
may be invoked without any trailing
arguments.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 boolean requiresTrailingArguments()
true
if at least one unnamed trailing argument must be
provided, or false
if the tool may be invoked without any
such arguments.public java.lang.String getTrailingArgumentsPlaceholder()
null
if unnamed trailing arguments are not allowed.public int getMinTrailingArguments()
public int getMaxTrailingArguments()
public void enablePropertiesFileSupport() throws ArgumentException
parse(java.lang.String[])
method is invoked. In addition,
after invoking the parse
method, the caller must also invoke the
getGeneratedPropertiesFile()
method to determine if the only
processing performed that should be performed is the generation of a
properties file that will have already been performed.
propertiesFilePath
-- Specifies the path to the properties file
that should be used to obtain default values for any arguments not
provided on the command line. If this is not specified and the
noPropertiesFile
argument is not present, then the argument
parser may use a default properties file path specified using either
the com.unboundid.util.args.ArgumentParser..propertiesFilePath
system property or the UNBOUNDID_TOOL_PROPERTIES_FILE_PATH
environment variable.
generatePropertiesFile
-- Indicates that the tool should
generate a properties file for this argument parser and write it to the
specified location. The generated properties file will not have any
properties set, but will include comments that describe all of the
supported arguments, as well general information about the use of a
properties file. If this argument is specified on the command line,
then no other arguments should be given.
noPropertiesFile
-- Indicates that the tool should not use a
properties file to obtain default values for any arguments not provided
on the command line.
ArgumentException
- If any of the arguments related to properties
file processing conflicts with an argument that
has already been added to the argument parser.public java.io.File getGeneratedPropertiesFile()
File
object that represents the path to the properties
file that was generated, or null
if no properties file was
generated.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 identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public ArgumentListArgument getArgumentListArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public BooleanArgument getBooleanArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public BooleanValueArgument getBooleanValueArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public ControlArgument getControlArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public DNArgument getDNArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public DurationArgument getDurationArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public FileArgument getFileArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public FilterArgument getFilterArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public IntegerArgument getIntegerArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public ScopeArgument getScopeArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public StringArgument getStringArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. It must not be
null
.null
if there is no such argument.public TimestampArgument getTimestampArgument(java.lang.String identifier)
identifier
- The identifier of the argument to retrieve. It may be
the long identifier without any dashes, the short
identifier character preceded by a single dash, or the
long identifier preceded by two dashes. 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)
addArgument(com.unboundid.util.args.Argument)
method.targetArgument
- The argument whose presence indicates that at
least one of the dependent arguments must also
be present. It must not be null
, and
it must have already been registered with this
argument parser.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, and all arguments must have already been
registered with this argument parser.public void addDependentArgumentSet(Argument targetArgument, Argument dependentArg1, Argument... remaining)
addArgument(com.unboundid.util.args.Argument)
method.targetArgument
- The argument whose presence indicates that at least
one of the dependent arguments must also be
present. It must not be null
, and it must
have already been registered with this argument
parser.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
,
and it must have already been registered with this
argument parser.remaining
- The remaining arguments in the set of arguments in
which at least one argument must be present if the
target argument is present. It may be null
or empty if no additional dependent arguments are
needed, but if it is non-empty then all arguments
must have already been registered with this
argument parser.public java.util.List<java.util.Set<Argument>> getExclusiveArgumentSets()
public void addExclusiveArgumentSet(java.util.Collection<Argument> exclusiveArguments)
addArgument(com.unboundid.util.args.Argument)
method.exclusiveArguments
- The collection of arguments to form an
exclusive argument set. It must not be
null
, and all of the arguments must
have already been registered with this argument
parser.public void addExclusiveArgumentSet(Argument arg1, Argument arg2, Argument... remaining)
addArgument(com.unboundid.util.args.Argument)
method.arg1
- The first argument to include in the exclusive argument
set. It must not be null
, and it must have
already been registered with this argument parser.arg2
- The second argument to include in the exclusive argument
set. It must not be null
, and it must have
already been registered with this argument parser.remaining
- Any additional arguments to include in the exclusive
argument set. It may be null
or empty if no
additional exclusive arguments are needed, but if it is
non-empty then all arguments must have already been
registered with this argument parser.public java.util.List<java.util.Set<Argument>> getRequiredArgumentSets()
public void addRequiredArgumentSet(java.util.Collection<Argument> requiredArguments)
addArgument(com.unboundid.util.args.Argument)
method.requiredArguments
- The collection of arguments to form an
required argument set. It must not be
null
, and all of the arguments must have
already been registered with this argument
parser.public void addRequiredArgumentSet(Argument arg1, Argument arg2, Argument... remaining)
addArgument(com.unboundid.util.args.Argument)
method.arg1
- The first argument to include in the required argument
set. It must not be null
, and it must have
already been registered with this argument parser.arg2
- The second argument to include in the required argument
set. It must not be null
, and it must have
already been registered with this argument parser.remaining
- Any additional arguments to include in the required
argument set. It may be null
or empty if no
additional required arguments are needed, but if it is
non-empty then all arguments must have already been
registered with this argument parser.public boolean hasSubCommands()
true
if one or more subcommands have been registered with
this argument parser, or false
if not.public SubCommand getSelectedSubCommand()
null
if there is none.public java.util.List<SubCommand> getSubCommands()
public SubCommand getSubCommand(java.lang.String name)
name
- The name of the subcommand to retrieve.null
if there is
no such subcommand.public void addSubCommand(SubCommand subCommand) throws ArgumentException
subCommand
- The subcommand to register with this argument parser.
It must not be null
.ArgumentException
- If this argument parser does not allow
subcommands, if there is a conflict between any
of the names of the provided subcommand and an
already-registered subcommand, or if there is a
conflict between any of the subcommand-specific
arguments and global arguments.public java.util.List<java.lang.String> getTrailingArguments()
public java.io.File getPropertiesFileUsed()
null
if no properties file
was used.public java.util.List<java.lang.String> getArgumentsSetFromPropertiesFile()
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.