com.unboundid.util.args
Class SubCommand

java.lang.Object
  extended by 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:


Constructor Summary
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
 void addName(java.lang.String name)
          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 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 names for this subcommand.

Returns:
The list of 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.

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.

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.