org.clapper.util.cmdline
Class UsageInfo

java.lang.Object
  org.clapper.util.cmdline.UsageInfo

public final class UsageInfo
extends java.lang.Object

An instance of this class is used to specify usage information for a command-line utility. See CommandLineUtility.getCustomUsageInfo(UsageInfo) for more information how to use this class.

Version:

$Revision: 6763 $

Author:

Copyright © 2004-2007 Brian M. Clapper

See Also:

CommandLineUtility, CommandLineUtility.getCustomUsageInfo(UsageInfo)

Field Summary

static java.lang.String	LONG_OPTION_PREFIX
static char	NO_SHORT_OPTION Constant to use for a short option, to indicate that there is no short option.
static char	SHORT_OPTION_PREFIX The option prefix strings used at the command line.

Constructor Summary

UsageInfo()
Create a new UsageInfo() object.

Method Summary

void	addOption(char shortOption, java.lang.String longOption, java.lang.String explanation) Add an option and its explanation to the usage information.
void	addOption(char shortOption, java.lang.String longOption, java.lang.String argToken, java.lang.String explanation) Add an option and its explanation to the usage information.
void	addParameter(java.lang.String param, java.lang.String explanation, boolean required) Add a positional parameter (i.e., one that follows the options) and its explanation to the usage information at the end of the list of positional parameters.
void	addUsagePrologue(java.lang.String prologue) Add a prologue to be displayed before the standard usage message.
void	addUsageTrailer(java.lang.String trailer) Add a trailer to be displayed after the standard usage message.
java.lang.String	getCommandName() Get the command name to be used in the usage output.
void	setCommandName(java.lang.String commandName) Set the command name to be used in the usage output.

Methods inherited from class java.lang.Object

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

Field Detail

NO_SHORT_OPTION

public static final char NO_SHORT_OPTION

Constant to use for a short option, to indicate that there is no short option.

See Also:

Constant Field Values

SHORT_OPTION_PREFIX

public static final char SHORT_OPTION_PREFIX

The option prefix strings used at the command line.

See Also:

Constant Field Values

LONG_OPTION_PREFIX

public static final java.lang.String LONG_OPTION_PREFIX

See Also:

Constant Field Values

Constructor Detail

UsageInfo

public UsageInfo()

Create a new UsageInfo() object.

Method Detail

getCommandName

public java.lang.String getCommandName()

Get the command name to be used in the usage output. If not specified, java classname is used.

Returns:

the command name, or null if not set

See Also:

setCommandName(java.lang.String)

setCommandName

public void setCommandName(java.lang.String commandName)

Set the command name to be used in the usage output. If not specified, java classname is used.

Parameters:

commandName - the command name

See Also:

getCommandName()

addOption

public void addOption(char shortOption,
                      java.lang.String longOption,
                      java.lang.String explanation)

Add an option and its explanation to the usage information. This method is shorthand for:

addOption((shortOption, longOption, null, explanation)

That is, it's useful for options that take no parameters.

Parameters:

shortOption - The single-character short option (e.g., 'a' for "-a"), or NO_SHORT_OPTION to indicate that there is no short option.

longOption - The corresponding long option, if any, or null. The option should be specified without any leading "-" character (e.g., "logging", not "--logging").

explanation - A one-line explanation for the option. The line can be as long as you want, and can contain multiple sentences, but it must not contain a newline. It will be automatically broken up into multiple lines as necessary. If the explanation is null, then the option is "hidden" (i.e., not displayed in the usage message). This is useful, for instance, when you've deprecated an option but are retaining it for backward compatibility.

addOption

public void addOption(char shortOption,
                      java.lang.String longOption,
                      java.lang.String argToken,
                      java.lang.String explanation)

Add an option and its explanation to the usage information. Examples:

 usageInfo.addOption ('n', "total-images", "num",
                      "Total number of images to generate");
 usageInfo.addOption ('v', "verbose", null,
                      "Enable verbose mode")
 

Parameters:

shortOption - The single-character short option (e.g., 'a' for "-a"), or NO_SHORT_OPTION to indicate that there is no short option.

longOption - The corresponding long option, if any, or null. The option should be specified without any leading "-" character (e.g., "logging", not "--logging").

argToken - A token to represent the option's parameter, if any, in the generated usage message. null if the option takes no parameters.

explanation - A one-line explanation for the option. The line can be as long as you want, and can contain multiple sentences, but it must not contain a newline. It will be automatically broken up into multiple lines as necessary. If the explanation is null, then the option is "hidden" (i.e., not displayed in the usage message). This is useful, for instance, when you've deprecated an option but are retaining it for backward compatibility.

addParameter

public void addParameter(java.lang.String param,
                         java.lang.String explanation,
                         boolean required)

Add a positional parameter (i.e., one that follows the options) and its explanation to the usage information at the end of the list of positional parameters.

Parameters:

param - The parameter placeholder string

explanation - A one-line explanation for the parameter. The line can be as long as you want, and can contain multiple sentences, but it must not contain a newline. It will be automatically broken up into multiple lines as necessary.

required - true if the parameter is required, false if the parameter is optional

addUsagePrologue

public void addUsagePrologue(java.lang.String prologue)

Add a prologue to be displayed before the standard usage message. The prologue string should be one line; it'll be broken up, wrapped, and displayed as a paragraph that precedes the usage message.

Parameters:

prologue - the prologue string

See Also:

addUsageTrailer(java.lang.String)

addUsageTrailer

public void addUsageTrailer(java.lang.String trailer)

Add a trailer to be displayed after the standard usage message. The trailer string should be one line; it'll be broken up, wrapped, and displayed as a paragraph following the usage message.

Parameters:

trailer - the trailer string

See Also:

addUsageTrailer(java.lang.String)