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 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.
-
-
-
Constructor Detail
-
SubCommand
public SubCommand(@NotNull java.lang.String name, @NotNull java.lang.String description, @NotNull ArgumentParser parser, @NotNull 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 benull
or empty, and it will be treated in a case-insensitive manner.description
- The description for this subcommand. It must not benull
.parser
- The argument parser that will be used to validate the subcommand-specific arguments. It must not benull
, 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
@NotNull 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
@NotNull 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
@NotNull 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(@NotNull 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 benull
.- Returns:
true
if the provided name is assigned to this subcommand, orfalse
if not.
-
addName
public void addName(@NotNull 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 benull
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 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 benull
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 java.lang.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, orfalse
if not.
-
getExampleUsages
@NotNull 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
@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 java.lang.String toString()
Retrieves a string representation of this subcommand.- Overrides:
toString
in classjava.lang.Object
- Returns:
- A string representation of this subcommand.
-
-