Class SubCommand


  • @Mutable
    @ThreadSafety(level=INTERFACE_NOT_THREADSAFE)
    public final class SubCommand
    extends java.lang.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​(java.lang.String name, java.lang.String description, ArgumentParser parser, java.util.LinkedHashMap<java.lang.String[],​java.lang.String> exampleUsages)
      Creates a new subcommand with the provided information.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addName​(java.lang.String name)
      Adds the provided name that may be used to reference this subcommand.
      void addName​(java.lang.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.
      java.lang.String getDescription()
      Retrieves the description for this subcommand.
      java.util.LinkedHashMap<java.lang.String[],​java.lang.String> getExampleUsages()
      Retrieves a set of information that may be used to generate example usage information when the tool is run with this subcommand.
      java.util.List<java.lang.String> getNames()
      Retrieves the list of all names, including hidden names, for this subcommand.
      java.util.List<java.lang.String> getNames​(boolean includeHidden)
      Retrieves a list of the non-hidden names for this subcommand.
      java.lang.String getPrimaryName()
      Retrieves the primary name for this subcommand, which is the first name that was assigned to it.
      boolean hasName​(java.lang.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.
      java.lang.String toString()
      Retrieves a string representation of this subcommand.
      void toString​(java.lang.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 Detail

      • SubCommand

        public SubCommand​(java.lang.String name,
                          java.lang.String description,
                          ArgumentParser parser,
                          java.util.LinkedHashMap<java.lang.String[],​java.lang.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 Detail

      • getPrimaryName

        public java.lang.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

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

        public java.util.List<java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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

        public java.lang.String getDescription()
        Retrieves the description for this subcommand.
        Returns:
        The description for this subcommand.
      • getArgumentParser

        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

        public java.util.LinkedHashMap<java.lang.String[],​java.lang.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

        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

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

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