com.townleyenterprises.command
Class CommandParser

java.lang.Object
  com.townleyenterprises.command.CommandParser

All Implemented Interfaces:

CommandListener

public final class CommandParser

extends java.lang.Object

implements CommandListener

This class provides support for parsing command-line arguments.

Since:

2.0

Version:

$Id: CommandParser.java,v 1.19 2004/11/28 20:15:27 atownley Exp $

Author:

Andrew S. Townley

Constructor Summary

CommandParser(java.lang.String appName)
The default constructor initializes the parser with the standard '-' and '--' switches for the short and long options.

CommandParser(java.lang.String appName, java.lang.String argHelp)
This version of the constructor alows a description for the unhandled arguments to be supplied to the parser.

CommandParser(java.lang.String appName, java.lang.String argHelp, char sSwitch, java.lang.String lSwitch)
This version of the constructor allows the client to specify the switch characters to be used for the short and long options.

CommandParser(java.lang.String appName, java.lang.String argHelp, char sSwitch, java.lang.String lSwitch, java.lang.String endOfArgsMarker)
This version of the constructor allows the client to specify the switch characters to be used for the short and long options.

Method Summary

void	addCommandListener(CommandListener listener) This method is used to register a new command listener with the parser.
void	addConstraint(OptionConstraint constraint) This method is used to add an option constraint to the parser.
void	enableAutohelp(boolean autohelp, boolean allowZeroArgs) This method tells the parser to automatically handle command lines with the help character.
void	executeCommands() This method is used to check all of the command constraints and execute all of the options.
java.lang.String	getDescription() This method is used to retrieve the description of the command listener's options when printing the help message.
CommandOption[]	getOptions() This method is called by the CommandParser to determine all of the arguments that should be handled by the listener.
java.lang.String[]	getUnhandledArguments() This method allows the client of the argument parser to retrieve any unhandled arguments in the argument list.
void	help() This method prints the automatically generated help messages for the registered options.
void	optionMatched(CommandOption opt, java.lang.String arg) This method is called whenever an arguement registered with the parser is detected in the argument stream.
void	parse(java.lang.String[] args) This is the main parsing function that should be called to trigger the parsing of the command-line arguments registered with the parser.
void	removeCommandListener(CommandListener listener) This method is used to unregister a command listener with the parser.
void	removeConstraint(OptionConstraint constraint) This method is used to remove a constraint from the parser.
void	setAbortExecuteOnError(boolean val) This method is used to configure the command parser to stop executing commands when an unhandled exeception is thrown by an option.
void	setExitOnMissingArg(boolean val, int status) This method is used to configure the command parser to exit with the specified return code when it encounters arguments with missing required parameters.
void	setExtraHelpText(java.lang.String preamble, java.lang.String postamble) This method is used to set optional text which can be printed before and after the command option descriptions.
void	usage() This method is used to print the usage summary information.

Methods inherited from class java.lang.Object

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

Constructor Detail

CommandParser

public CommandParser(java.lang.String appName)

The default constructor initializes the parser with the standard '-' and '--' switches for the short and long options. To use a different switch, the alternate constructor may be used instead.

Parameters:

appName - the name of the application

CommandParser

public CommandParser(java.lang.String appName,
                     java.lang.String argHelp)

This version of the constructor alows a description for the unhandled arguments to be supplied to the parser. Primarily this is intended for use by the autohelp feature.

Parameters:

appName - the name of the application

argHelp - the help for the additional arguments which may be supplied to the application

CommandParser

public CommandParser(java.lang.String appName,
                     java.lang.String argHelp,
                     char sSwitch,
                     java.lang.String lSwitch)

This version of the constructor allows the client to specify the switch characters to be used for the short and long options.

Parameters:

appName - the name of the application

argHelp - the help for the additional arguments which may be supplied to the application

sSwitch - the single character option switch

lSwitch - the long option switch

Throws:

java.lang.RuntimeException - if a single character is used for the long switch

CommandParser

public CommandParser(java.lang.String appName,
                     java.lang.String argHelp,
                     char sSwitch,
                     java.lang.String lSwitch,
                     java.lang.String endOfArgsMarker)

This version of the constructor allows the client to specify the switch characters to be used for the short and long options. It also allows the specification of the string to mark the end of the argument list. By default, this string is -- which conforms to the POSIX standard.

Parameters:

appName - the name of the application

argHelp - the help for the additional arguments which may be supplied to the application

sSwitch - the single character option switch

lSwitch - the long option switch

endOfArgsMarker - the string marking the end of the argument list (may be null). Anything after this string is treated as a leftover argument.

Throws:

java.lang.RuntimeException - if a single character is used for the long switch

Since:

2.1

Method Detail

enableAutohelp

public void enableAutohelp(boolean autohelp,
                           boolean allowZeroArgs)

This method tells the parser to automatically handle command lines with the help character. Optionally, the help or usage can be printed when no arguments are specified. By default autohelp is enabled and zero arguments are allowed.

Parameters:

autohelp - true to use autohelp; false to disable

allowZeroArgs - true to allow commands to have no arguments; false to require at least one argument

addCommandListener

public void addCommandListener(CommandListener listener)

This method is used to register a new command listener with the parser.

Parameters:

listener - the CommandListener instance

removeCommandListener

public void removeCommandListener(CommandListener listener)

This method is used to unregister a command listener with the parser.

Parameters:

listener - the CommandListener instance

parse

public void parse(java.lang.String[] args)

This is the main parsing function that should be called to trigger the parsing of the command-line arguments registered with the parser.

Parameters:

args - the command-line arguments to parse

getUnhandledArguments

public java.lang.String[] getUnhandledArguments()

This method allows the client of the argument parser to retrieve any unhandled arguments in the argument list. The main use of this method is to get options such as file names from the command line.

Returns:

an array of String objects or a zero-length array if none were present

optionMatched

public void optionMatched(CommandOption opt,
                          java.lang.String arg)

Description copied from interface: CommandListener

This method is called whenever an arguement registered with the parser is detected in the argument stream.

Specified by:

optionMatched in interface CommandListener

Parameters:

opt - the CommandOption matched by the parser

arg - the argument (if any) specified for the option

getOptions

public CommandOption[] getOptions()

Description copied from interface: CommandListener

This method is called by the CommandParser to determine all of the arguments that should be handled by the listener.

Specified by:

getOptions in interface CommandListener

Returns:

an array of CommandOption arguments. In the case where no arguments are specified (why would you bother?), a zero-length array should be returned.

getDescription

public java.lang.String getDescription()

Description copied from interface: CommandListener

This method is used to retrieve the description of the command listener's options when printing the help message. Usually it is the name of the application or subsystem.

Specified by:

getDescription in interface CommandListener

help

public void help()

This method prints the automatically generated help messages for the registered options.

usage

public void usage()

This method is used to print the usage summary information.

setExitOnMissingArg

public void setExitOnMissingArg(boolean val,
                                int status)

This method is used to configure the command parser to exit with the specified return code when it encounters arguments with missing required parameters.

Parameters:

val - toggles the behavior

status - the exit status to pass to System.exit()

setAbortExecuteOnError

public void setAbortExecuteOnError(boolean val)

This method is used to configure the command parser to stop executing commands when an unhandled exeception is thrown by an option.

Parameters:

val - toggles the behavior

Since:

3.0

setExtraHelpText

public void setExtraHelpText(java.lang.String preamble,
                             java.lang.String postamble)

This method is used to set optional text which can be printed before and after the command option descriptions.

Parameters:

preamble - the text to be printed before the option descriptions

postamble - the text to be printed after the option descriptions

executeCommands

public void executeCommands()
                     throws java.lang.Exception

This method is used to check all of the command constraints and execute all of the options.

Throws:

java.lang.Exception - if anything bad happens

Since:

3.0

addConstraint

public void addConstraint(OptionConstraint constraint)

This method is used to add an option constraint to the parser.

Parameters:

constraint - the constraint to check

Since:

3.0

removeConstraint

public void removeConstraint(OptionConstraint constraint)

This method is used to remove a constraint from the parser.

Parameters:

constraint - the constraint to remove

Since:

3.0