Package com.unboundid.util.args

Class 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.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • PROPERTY_DEFAULT_PROPERTIES_FILE_PATH

        @NotNull
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

        @NotNull
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​(@NotNull
                      java.lang.String commandName,
                      @NotNull
                      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​(@NotNull
                      java.lang.String commandName,
                      @NotNull
                      java.lang.String commandDescription,
                      int maxTrailingArgs,
                      @Nullable
                      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.

      • ArgumentParser

        public ArgumentParser​(@NotNull
                      java.lang.String commandName,
                      @NotNull
                      java.lang.String commandDescription,
                      int minTrailingArgs,
                      int maxTrailingArgs,
                      @Nullable
                      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.
        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.
        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.

      • ArgumentParser

        public ArgumentParser​(@NotNull
                      java.lang.String commandName,
                      @NotNull
                      java.lang.String commandDescription,
                      @Nullable
                      java.util.List<java.lang.String> additionalCommandDescriptionParagraphs,
                      int minTrailingArgs,
                      int maxTrailingArgs,
                      @Nullable
                      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.
        additionalCommandDescriptionParagraphs - A list of additional paragraphs that should be included in the tool description (with commandDescription providing the text for the first paragraph). This may be null 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 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

        @NotNull
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

        @NotNull
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 the getAdditionalCommandDescriptionParagraphs() 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

        @NotNull
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 the getCommandDescription() 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 the getCommandDescription 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, or false 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, or false if the tool may be invoked without any such arguments.

      • getTrailingArgumentsPlaceholder

        @Nullable
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 the 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.

        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 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.
        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

        @Nullable
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, or null if no properties file was generated.

      • getNamedArgument

        @Nullable
public Argument getNamedArgument​(@NotNull
                                 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

        @Nullable
public Argument getNamedArgument​(@NotNull
                                 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 be null.
        Returns:
        The named argument with the specified long identifier, or null if there is no such argument.

      • getArgumentListArgument

        @Nullable
public ArgumentListArgument getArgumentListArgument​(@NotNull
                                                    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 be null.
        Returns:
        The argument list argument with the specified identifier, or null if there is no such argument.

      • getBooleanArgument

        @Nullable
public BooleanArgument getBooleanArgument​(@NotNull
                                          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 be null.
        Returns:
        The Boolean argument with the specified identifier, or null if there is no such argument.

      • getBooleanValueArgument

        @Nullable
public BooleanValueArgument getBooleanValueArgument​(@NotNull
                                                    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 be null.
        Returns:
        The Boolean value argument with the specified identifier, or null if there is no such argument.

      • getControlArgument

        @Nullable
public ControlArgument getControlArgument​(@NotNull
                                          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 be null.
        Returns:
        The control argument with the specified identifier, or null if there is no such argument.

      • getDNArgument

        @Nullable
public DNArgument getDNArgument​(@NotNull
                                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 be null.
        Returns:
        The DN argument with the specified identifier, or null if there is no such argument.

      • getDurationArgument

        @Nullable
public DurationArgument getDurationArgument​(@NotNull
                                            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 be null.
        Returns:
        The duration argument with the specified identifier, or null if there is no such argument.

      • getFileArgument

        @Nullable
public FileArgument getFileArgument​(@NotNull
                                    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 be null.
        Returns:
        The file argument with the specified identifier, or null if there is no such argument.

      • getFilterArgument

        @Nullable
public FilterArgument getFilterArgument​(@NotNull
                                        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 be null.
        Returns:
        The filter argument with the specified identifier, or null if there is no such argument.

      • getIntegerArgument

        @Nullable
public IntegerArgument getIntegerArgument​(@NotNull
                                          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 be null.
        Returns:
        The integer argument with the specified identifier, or null if there is no such argument.

      • getScopeArgument

        @Nullable
public ScopeArgument getScopeArgument​(@NotNull
                                      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 be null.
        Returns:
        The scope argument with the specified identifier, or null if there is no such argument.

      • getStringArgument

        @Nullable
public StringArgument getStringArgument​(@NotNull
                                        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 be null.
        Returns:
        The string argument with the specified identifier, or null if there is no such argument.

      • getTimestampArgument

        @Nullable
public TimestampArgument getTimestampArgument​(@NotNull
                                              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 be null.
        Returns:
        The timestamp argument with the specified identifier, or null if there is no such argument.

      • getNamedArguments

        @NotNull
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​(@NotNull
                        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

        @NotNull
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​(@NotNull
                                    Argument targetArgument,
                                    @NotNull
                                    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 the addArgument(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 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.

      • addDependentArgumentSet

        public void addDependentArgumentSet​(@NotNull
                                    Argument targetArgument,
                                    @NotNull
                                    Argument dependentArg1,
                                    @Nullable
                                    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 the addArgument(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 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.

      • addMutuallyDependentArgumentSet

        public void addMutuallyDependentArgumentSet​(@NotNull
                                            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 be null, and must contain at least two elements.

      • addMutuallyDependentArgumentSet

        public void addMutuallyDependentArgumentSet​(@NotNull
                                            Argument arg1,
                                            @NotNull
                                            Argument arg2,
                                            @Nullable
                                            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 be null.
        arg2 - The second argument to include in the mutually dependent argument set. It must not be null.
        remaining - An optional set of additional arguments to include in the mutually dependent argument set. It may be null or empty if only two arguments should be included in the mutually dependent argument set.

      • getExclusiveArgumentSets

        @NotNull
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​(@NotNull
                                    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 the addArgument(com.unboundid.util.args.Argument) method.
        Parameters:
        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.

      • addExclusiveArgumentSet

        public void addExclusiveArgumentSet​(@NotNull
                                    Argument arg1,
                                    @NotNull
                                    Argument arg2,
                                    @Nullable
                                    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 the addArgument(com.unboundid.util.args.Argument) method.
        Parameters:
        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.

      • getRequiredArgumentSets

        @NotNull
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​(@NotNull
                                   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 the addArgument(com.unboundid.util.args.Argument) method.
        Parameters:
        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.

      • addRequiredArgumentSet

        public void addRequiredArgumentSet​(@NotNull
                                   Argument arg1,
                                   @NotNull
                                   Argument arg2,
                                   @Nullable
                                   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 the addArgument(com.unboundid.util.args.Argument) method.
        Parameters:
        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.

      • 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, or false if not.

      • getSelectedSubCommand

        @Nullable
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

        @NotNull
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

        @Nullable
public SubCommand getSubCommand​(@Nullable
                                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​(@NotNull
                          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 be null.
        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

        @NotNull
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

        @Nullable
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

        @NotNull
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, or false if not.

      • getCleanCopy

        @NotNull
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​(@NotNull
                  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.

      • setCommandLineTool

        public void setCommandLineTool​(@Nullable
                               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 be null if there is no associated command-line tool.

      • getUsage

        @NotNull
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​(@NotNull
                     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

        @NotNull
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​(@NotNull
                           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

        @NotNull
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​(@NotNull
                     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.