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

Modifier and Type	Method and 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(@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 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

@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 be null.

Returns:

true if the provided name is assigned to this subcommand, or false 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 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
                    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

@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, or false 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 class java.lang.Object

Returns:

A string representation of this subcommand.

toString

public void toString(@NotNull
                     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.