Package com.unboundid.util.args
Class ArgumentParser
- java.lang.Object
-
- 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
-
-
Field Summary
Fields Modifier and Type Field 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 Summary
Constructors Constructor 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.ArgumentParser(java.lang.String commandName, java.lang.String commandDescription, java.util.List<java.lang.String> additionalCommandDescriptionParagraphs, int minTrailingArgs, int maxTrailingArgs, java.lang.String trailingArgsPlaceholder)
Creates a new instance of this argument parser with the provided information.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method 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
addMutuallyDependentArgumentSet(Argument arg1, Argument arg2, Argument... remaining)
Adds the provided set of arguments as mutually dependent, such that if any of the arguments is provided, then all of them must be provided.void
addMutuallyDependentArgumentSet(java.util.Collection<Argument> arguments)
Adds the provided set of arguments as mutually dependent, such that if any of the arguments is provided, then all of them must 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.java.util.List<java.lang.String>
getAdditionalCommandDescriptionParagraphs()
Retrieves a list containing the the text for all subsequent paragraphs to include in the description for the application or utility with which this command line argument parser is associated.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.void
setCommandLineTool(CommandLineTool commandLineTool)
Sets the command-line tool with which this argument parser is associated.boolean
suppressPropertiesFileComment()
Indicates whether the comment listing arguments obtained from a properties file should be suppressed.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.
-
-
-
Field Detail
-
PROPERTY_DEFAULT_PROPERTIES_FILE_PATH
public static final 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.
-
ENV_DEFAULT_PROPERTIES_FILE_PATH
public static final 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.- See Also:
- Constant Field Values
-
-
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 benull
.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 benull
.- Throws:
ArgumentException
- If either the command name or command description isnull
,
-
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 benull
.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 benull
.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 benull
ifmaxTrailingArgs
is anything other than zero.- Throws:
ArgumentException
- If either the command name or command description isnull
, or if the maximum number of trailing arguments is non-zero and the trailing arguments placeholder isnull
.
-
ArgumentParser
public ArgumentParser(java.lang.String commandName, java.lang.String commandDescription, int minTrailingArgs, 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 benull
.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 benull
.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 benull
ifmaxTrailingArgs
is anything other than zero.- Throws:
ArgumentException
- If either the command name or command description isnull
, or if the maximum number of trailing arguments is non-zero and the trailing arguments placeholder isnull
.
-
ArgumentParser
public ArgumentParser(java.lang.String commandName, java.lang.String commandDescription, java.util.List<java.lang.String> additionalCommandDescriptionParagraphs, int minTrailingArgs, 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 benull
.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 benull
.additionalCommandDescriptionParagraphs
- A list of additional paragraphs that should be included in the tool description (withcommandDescription
providing the text for the first paragraph). This may benull
or empty if the tool description should only include a single paragraph.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 benull
ifmaxTrailingArgs
is anything other than zero.- Throws:
ArgumentException
- If either the command name or command description isnull
, or if the maximum number of trailing arguments is non-zero and the trailing arguments placeholder isnull
.
-
-
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. If the description should include multiple paragraphs, then this method will return the text for the first paragraph, and thegetAdditionalCommandDescriptionParagraphs()
method should return a list with the text for all subsequent paragraphs.- Returns:
- A description of the application or utility with which this command line argument parser is associated.
-
getAdditionalCommandDescriptionParagraphs
public java.util.List<java.lang.String> getAdditionalCommandDescriptionParagraphs()
Retrieves a list containing the the text for all subsequent paragraphs to include in the description for the application or utility with which this command line argument parser is associated. If the description should have multiple paragraphs, then thegetCommandDescription()
method will provide the text for the first paragraph and this method will provide the text for the subsequent paragraphs. If the description should only have a single paragraph, then the text of that paragraph should be returned by thegetCommandDescription
method, and this method will return an empty list.- Returns:
- A list containing the text for all subsequent paragraphs to include in the description for the application or utility with which this command line argument parser is associated, or an empty list if the description should only include a single paragraph.
-
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, orfalse
if not.
-
requiresTrailingArguments
public boolean requiresTrailingArguments()
Indicates whether this argument parser requires at least unnamed trailing argument to be provided.- Returns:
true
if at least one unnamed trailing argument must be provided, orfalse
if the tool may be invoked without any such arguments.
-
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.
-
getMinTrailingArguments
public int getMinTrailingArguments()
Retrieves the minimum number of unnamed trailing arguments that must be provided.- Returns:
- The minimum number of unnamed trailing arguments that must be provided.
-
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.
-
enablePropertiesFileSupport
public void enablePropertiesFileSupport() throws ArgumentException
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. This method should be invoked after the argument parser has been configured with all of the other arguments that it supports and before theparse(java.lang.String[])
method is invoked. In addition, after invoking theparse
method, the caller must also invoke thegetGeneratedPropertiesFile()
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.
This method will update the argument parser to add the following additional arguments:-
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 thenoPropertiesFile
argument is not present, then the argument parser may use a default properties file path specified using either thecom.unboundid.util.args.ArgumentParser..propertiesFilePath
system property or theUNBOUNDID_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.
- Throws:
ArgumentException
- If any of the arguments related to properties file processing conflicts with an argument that has already been added to the argument parser.
-
-
getGeneratedPropertiesFile
public java.io.File getGeneratedPropertiesFile()
Indicates whether this argument parser was used to generate a properties file. If so, then the tool invoking the parser should return without performing any further processing.- Returns:
- A
File
object that represents the path to the properties file that was generated, ornull
if no properties file was generated.
-
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 benull
.- Returns:
- The named argument with the specified short identifier, or
null
if there is no such argument.
-
getNamedArgument
public Argument getNamedArgument(java.lang.String identifier)
Retrieves the named argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The named argument with the specified long identifier, or
null
if there is no such argument.
-
getArgumentListArgument
public ArgumentListArgument getArgumentListArgument(java.lang.String identifier)
Retrieves the argument list argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The argument list argument with the specified identifier, or
null
if there is no such argument.
-
getBooleanArgument
public BooleanArgument getBooleanArgument(java.lang.String identifier)
Retrieves the Boolean argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The Boolean argument with the specified identifier, or
null
if there is no such argument.
-
getBooleanValueArgument
public BooleanValueArgument getBooleanValueArgument(java.lang.String identifier)
Retrieves the Boolean value argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The Boolean value argument with the specified identifier, or
null
if there is no such argument.
-
getControlArgument
public ControlArgument getControlArgument(java.lang.String identifier)
Retrieves the control argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The control argument with the specified identifier, or
null
if there is no such argument.
-
getDNArgument
public DNArgument getDNArgument(java.lang.String identifier)
Retrieves the DN argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The DN argument with the specified identifier, or
null
if there is no such argument.
-
getDurationArgument
public DurationArgument getDurationArgument(java.lang.String identifier)
Retrieves the duration argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The duration argument with the specified identifier, or
null
if there is no such argument.
-
getFileArgument
public FileArgument getFileArgument(java.lang.String identifier)
Retrieves the file argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The file argument with the specified identifier, or
null
if there is no such argument.
-
getFilterArgument
public FilterArgument getFilterArgument(java.lang.String identifier)
Retrieves the filter argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The filter argument with the specified identifier, or
null
if there is no such argument.
-
getIntegerArgument
public IntegerArgument getIntegerArgument(java.lang.String identifier)
Retrieves the integer argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The integer argument with the specified identifier, or
null
if there is no such argument.
-
getScopeArgument
public ScopeArgument getScopeArgument(java.lang.String identifier)
Retrieves the scope argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The scope argument with the specified identifier, or
null
if there is no such argument.
-
getStringArgument
public StringArgument getStringArgument(java.lang.String identifier)
Retrieves the string argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The string argument with the specified identifier, or
null
if there is no such argument.
-
getTimestampArgument
public TimestampArgument getTimestampArgument(java.lang.String identifier)
Retrieves the timestamp argument with the specified identifier.- Parameters:
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 benull
.- Returns:
- The timestamp argument with the specified 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. All of the arguments must have already been registered with this argument parser using theaddArgument(com.unboundid.util.args.Argument)
method.- Parameters:
targetArgument
- The argument whose presence indicates that at least one of the dependent arguments must also be present. It must not benull
, 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 benull
or empty, and all arguments must have already been registered with this argument parser.
-
addDependentArgumentSet
public void addDependentArgumentSet(Argument targetArgument, Argument dependentArg1, Argument... remaining)
Adds the provided collection of arguments as dependent upon the given argument. All of the arguments must have already been registered with this argument parser using theaddArgument(com.unboundid.util.args.Argument)
method.- Parameters:
targetArgument
- The argument whose presence indicates that at least one of the dependent arguments must also be present. It must not benull
, 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 benull
, 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 benull
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.
-
addMutuallyDependentArgumentSet
public void addMutuallyDependentArgumentSet(java.util.Collection<Argument> arguments)
Adds the provided set of arguments as mutually dependent, such that if any of the arguments is provided, then all of them must be provided. It will be implemented by creating multiple dependent argument sets (one for each argument in the provided collection).- Parameters:
arguments
- The collection of arguments to be used to create the dependent argument sets. It must not benull
, and must contain at least two elements.
-
addMutuallyDependentArgumentSet
public void addMutuallyDependentArgumentSet(Argument arg1, Argument arg2, Argument... remaining)
Adds the provided set of arguments as mutually dependent, such that if any of the arguments is provided, then all of them must be provided. It will be implemented by creating multiple dependent argument sets (one for each argument in the provided collection).- Parameters:
arg1
- The first argument to include in the mutually dependent argument set. It must not benull
.arg2
- The second argument to include in the mutually dependent argument set. It must not benull
.remaining
- An optional set of additional arguments to include in the mutually dependent argument set. It may benull
or empty if only two arguments should be included in the mutually dependent argument set.
-
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. All of the arguments must have already been registered with this argument parser using theaddArgument(com.unboundid.util.args.Argument)
method.- Parameters:
exclusiveArguments
- The collection of arguments to form an exclusive argument set. It must not benull
, and all of the arguments must have already been registered with this argument parser.
-
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. All of the arguments must have already been registered with this argument parser using theaddArgument(com.unboundid.util.args.Argument)
method.- Parameters:
arg1
- The first argument to include in the exclusive argument set. It must not benull
, 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 benull
, and it must have already been registered with this argument parser.remaining
- Any additional arguments to include in the exclusive argument set. It may benull
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.
-
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. All of the arguments must have already been registered with this argument parser using theaddArgument(com.unboundid.util.args.Argument)
method.- Parameters:
requiredArguments
- The collection of arguments to form an required argument set. It must not benull
, and all of the arguments must have already been registered with this argument parser.
-
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. All of the arguments must have already been registered with this argument parser using theaddArgument(com.unboundid.util.args.Argument)
method.- Parameters:
arg1
- The first argument to include in the required argument set. It must not benull
, 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 benull
, and it must have already been registered with this argument parser.remaining
- Any additional arguments to include in the required argument set. It may benull
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.
-
hasSubCommands
public boolean hasSubCommands()
Indicates whether any subcommands have been registered with this argument parser.- Returns:
true
if one or more subcommands have been registered with this argument parser, orfalse
if not.
-
getSelectedSubCommand
public SubCommand getSelectedSubCommand()
Retrieves the subcommand that was provided in the set of command-line arguments, if any.- Returns:
- The subcommand that was provided in the set of command-line
arguments, or
null
if there is none.
-
getSubCommands
public java.util.List<SubCommand> getSubCommands()
Retrieves a list of all subcommands associated with this argument parser.- Returns:
- A list of all subcommands associated with this argument parser, or an empty list if there are no associated subcommands.
-
getSubCommand
public SubCommand getSubCommand(java.lang.String name)
Retrieves the subcommand for the provided name.- Parameters:
name
- The name of the subcommand to retrieve.- Returns:
- The subcommand with the provided name, or
null
if there is no such subcommand.
-
addSubCommand
public void addSubCommand(SubCommand subCommand) throws ArgumentException
Registers the provided subcommand with this argument parser.- Parameters:
subCommand
- The subcommand to register with this argument parser. It must not benull
.- Throws:
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.
-
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.
-
getPropertiesFileUsed
public java.io.File getPropertiesFileUsed()
Retrieves the properties file that was used to obtain values for arguments not set on the command line.- Returns:
- The properties file that was used to obtain values for arguments
not set on the command line, or
null
if no properties file was used.
-
getArgumentsSetFromPropertiesFile
public 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. The values of any arguments marked as sensitive will be obscured.- Returns:
- A list of the string representations any arguments used for the associated tool that were set from a properties file rather than provided on the command line, or an empty list if no arguments were set from a properties file.
-
suppressPropertiesFileComment
public boolean suppressPropertiesFileComment()
Indicates whether the comment listing arguments obtained from a properties file should be suppressed.- Returns:
true
if the comment listing arguments obtained from a properties file should be suppressed, orfalse
if not.
-
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 benull
.- Throws:
ArgumentException
- If a problem occurs while attempting to parse the argument information.
-
setCommandLineTool
public void setCommandLineTool(CommandLineTool commandLineTool)
Sets the command-line tool with which this argument parser is associated.- Parameters:
commandLineTool
- The command-line tool with which this argument parser is associated. It may benull
if there is no associated command-line tool.
-
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 benull
.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 classjava.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.
-
-