Package com.unboundid.util.args

Class SubCommand

java.lang.Object
com.unboundid.util.args.SubCommand
@Mutable @ThreadSafety(level=INTERFACE_NOT_THREADSAFE) public final class SubCommand extends Object
This class provides a data structure that represents a subcommand that can be used in conjunction with the argument parser. A subcommand can be used to allow a single command to do multiple different things. A subcommand is represented in the argument list as a string that is not prefixed by any dashes, and there can be at most one subcommand in the argument list. Each subcommand has its own argument parser that defines the arguments available for use with that subcommand, and the tool still provides support for global arguments that are not associated with any of the subcommands.

The use of subcommands imposes the following constraints on an argument parser:
  • Each subcommand must be registered with the argument parser that defines the global arguments for the tool. Subcommands cannot be registered with a subcommand's argument parser (i.e., you cannot have a subcommand with its own subcommands).
  • There must not be any conflicts between the global arguments and the subcommand-specific arguments. However, there can be conflicts between the arguments used across separate subcommands.
  • If the global argument parser cannot support both unnamed subcommands and unnamed trailing arguments.
  • Global arguments can exist anywhere in the argument list, whether before or after the subcommand. Subcommand-specific arguments must only appear after the subcommand in the argument list.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SubCommand(String name, String description, ArgumentParser parser, LinkedHashMap<String[],String> exampleUsages)
    Creates a new subcommand with the provided information.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addName(String name)
    Adds the provided name that may be used to reference this subcommand.
    void
    addName(String name, boolean isHidden)
    Adds the provided name that may be used to reference this subcommand.
    ArgumentParser
    getArgumentParser()
    Retrieves the argument parser that will be used to process arguments specific to this subcommand.
    SubCommand
    getCleanCopy()
    Creates a copy of this subcommand that is "clean" and appears as if it has not been used to parse an argument set.
    String
    getDescription()
    Retrieves the description for this subcommand.
    LinkedHashMap<String[],String>
    getExampleUsages()
    Retrieves a set of information that may be used to generate example usage information when the tool is run with this subcommand.
    List<String>
    getNames()
    Retrieves the list of all names, including hidden names, for this subcommand.
    List<String>
    getNames(boolean includeHidden)
    Retrieves a list of the non-hidden names for this subcommand.
    String
    getPrimaryName()
    Retrieves the primary name for this subcommand, which is the first name that was assigned to it.
    boolean
    hasName(String name)
    Indicates whether the provided name is assigned to this subcommand.
    boolean
    isPresent()
    Indicates whether this subcommand was provided in the set of command-line arguments.
    String
    toString()
    Retrieves a string representation of this subcommand.
    void
    toString(StringBuilder buffer)
    Appends a string representation of this subcommand to the provided buffer.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • SubCommand

      public SubCommand(@NotNull String name, @NotNull String description, @NotNull ArgumentParser parser, @NotNull LinkedHashMap<String[],String> exampleUsages) throws ArgumentException
      Creates a new subcommand with the provided information.
      Parameters:
      name - A name that may be used to reference this subcommand in the argument list. It must not be null or empty, and it will be treated in a case-insensitive manner.
      description - The description for this subcommand. It must not be null.
      parser - The argument parser that will be used to validate the subcommand-specific arguments. It must not be null, it must not be configured with any subcommands of its own, and it must not be configured to allow unnamed trailing arguments.
      exampleUsages - An optional map correlating a complete set of arguments that may be used when running the tool with this subcommand (including the subcommand and any appropriate global and/or subcommand-specific arguments) and a description of the behavior with that subcommand.
      Throws:
      ArgumentException - If there is a problem with the provided name, description, or argument parser.

  • Method Details

    • getPrimaryName

      @NotNull public String getPrimaryName()
      Retrieves the primary name for this subcommand, which is the first name that was assigned to it.
      Returns:
      The primary name for this subcommand.

    • getNames

      @NotNull public List<String> getNames()
      Retrieves the list of all names, including hidden names, for this subcommand.
      Returns:
      The list of all names for this subcommand.

    • getNames

      @NotNull public List<String> getNames(boolean includeHidden)
      Retrieves a list of the non-hidden names for this subcommand.
      Parameters:
      includeHidden - Indicates whether to include hidden names in the list that is returned.
      Returns:
      A list of the non-hidden names for this subcommand.

    • hasName

      public boolean hasName(@NotNull String name)
      Indicates whether the provided name is assigned to this subcommand.
      Parameters:
      name - The name for which to make the determination. It must not be null.
      Returns:
      true if the provided name is assigned to this subcommand, or false if not.

    • addName

      public void addName(@NotNull String name) throws ArgumentException
      Adds the provided name that may be used to reference this subcommand. It will not be hidden.
      Parameters:
      name - A name that may be used to reference this subcommand in the argument list. It must not be null or empty, and it will be treated in a case-insensitive manner.
      Throws:
      ArgumentException - If the provided name is already registered with this subcommand, or with another subcommand also registered with the global argument parser.

    • addName

      public void addName(@NotNull String name, boolean isHidden) throws ArgumentException
      Adds the provided name that may be used to reference this subcommand.
      Parameters:
      name - A name that may be used to reference this subcommand in the argument list. It must not be null or empty, and it will be treated in a case-insensitive manner.
      isHidden - Indicates whether the provided name should be hidden. A hidden name may be used to invoke this subcommand but will not be displayed in usage information.
      Throws:
      ArgumentException - If the provided name is already registered with this subcommand, or with another subcommand also registered with the global argument parser.

    • getDescription

      @NotNull public String getDescription()
      Retrieves the description for this subcommand.
      Returns:
      The description for this subcommand.

    • getArgumentParser

      @NotNull public ArgumentParser getArgumentParser()
      Retrieves the argument parser that will be used to process arguments specific to this subcommand.
      Returns:
      The argument parser that will be used to process arguments specific to this subcommand.

    • isPresent

      public boolean isPresent()
      Indicates whether this subcommand was provided in the set of command-line arguments.
      Returns:
      true if this subcommand was provided in the set of command-line arguments, or false if not.

    • getExampleUsages

      @NotNull public LinkedHashMap<String[],String> getExampleUsages()
      Retrieves a set of information that may be used to generate example usage information when the tool is run with this subcommand. Each element in the returned map should consist of a map between an example set of arguments (including the subcommand name) and a string that describes the behavior of the tool when invoked with that set of arguments.
      Returns:
      A set of information that may be used to generate example usage information, or an empty map if no example usages are available.

    • getCleanCopy

      @NotNull public SubCommand getCleanCopy()
      Creates a copy of this subcommand that is "clean" and appears as if it has not been used to parse an argument set. The new subcommand will have all of the same names and argument constraints as this subcommand.
      Returns:
      The "clean" copy of this subcommand.

    • toString

      @NotNull public String toString()
      Retrieves a string representation of this subcommand.
      Overrides:
      toString in class Object
      Returns:
      A string representation of this subcommand.

    • toString

      public void toString(@NotNull StringBuilder buffer)
      Appends a string representation of this subcommand to the provided buffer.
      Parameters:
      buffer - The buffer to which the information should be appended.