jcmdline
Interface CmdLineHandler

All Known Implementing Classes:
AbstractHandlerDecorator, BasicCmdLineHandler, DefaultCmdLineHandler, HelpCmdLineHandler, LoggerCmdLineHandler, VersionCmdLineHandler

public interface CmdLineHandler

Interface that describes the API for a command line handler. A command line handler is an object that is passed information concerning the required structure of command's command line and then can be used to parse the command line, taking action as configured.

Information on using CmdLineHandlers can be found in the jcmdline User Guide.

Version:
jcmdline Rel. 2.0.0 $Id: CmdLineHandler.java,v 1.2 2002/12/07 14:22:06 lglawrence Exp $
Author:
Lynne Lawrence
See Also:
Parameter, CmdLineParser, UsageFormatter

Method Summary
 void addArg(Parameter<?> arg)
          Adds a command line arguement.
 void addOption(Parameter<?> opt)
          Adds a command line option.
 void exitUsageError(java.lang.String errMsg)
          Prints the usage, followed by the specified error message, to stderr and exits the program with exit status = 1.
 Parameter<?> getArg(java.lang.String tag)
          gets the argument specified by tag
 java.util.List<Parameter<?>> getArgs()
          gets the value of the arguments (what is left on the command line after all options, and their parameters, have been processed) associated with the command
 java.lang.String getCmdDesc()
          gets a description of the command's purpose
 java.lang.String getCmdName()
          gets the value of the command name associated with this CmdLineHandler
 boolean getDieOnParseError()
          Gets a flag indicating that the program should exit in the case of a parse error (after displaying the usage and an error message).
 Parameter<?> getOption(java.lang.String tag)
          gets the option specified by tag
 java.util.Collection<Parameter<?>> getOptions()
          gets the value of the options associated with the command
 java.lang.String getParseError()
          Gets the error message from the last call to parse().
 CmdLineParser getParser()
          Gets the parser to be used to parse the command line.
 java.lang.String getUsage(boolean hidden)
          Gets the usage statement associated with the command.
 boolean parse(java.lang.String[] clargs)
          parse the specified command line arguments
 void setArgs(Parameter<?>[] args)
          sets the value of the arguments (what is left on the command line after all options, and their parameters, have been processed) associated with the command
 void setCmdDesc(java.lang.String cmdDesc)
          sets a description of the command's purpose
 void setCmdName(java.lang.String cmdName)
          sets the value of the command name associated with this CmdLineHandler
 void setDieOnParseError(boolean val)
          Sets a flag indicating that the program should exit in the case of a parse error (after displaying the usage and an error message) - defaults to true.
 void setOptions(Parameter<?>[] options)
          Sets the value of the options associated with the command
 void setParseError(java.lang.String parseError)
          Sets the error message from the last call to parse().
 void setParser(CmdLineParser parser)
          Sets the parser to be used to parse the command line.
 

Method Detail

addArg

void addArg(Parameter<?> arg)
Adds a command line arguement.

Parameters:
arg - the new command line argument
Throws:
java.lang.IllegalArgumentException - if arg is null.

addOption

void addOption(Parameter<?> opt)
Adds a command line option.

Parameters:
opt - the new command line option
Throws:
java.lang.IllegalArgumentException - if the tag associated with opt has already been defined for an option.

exitUsageError

void exitUsageError(java.lang.String errMsg)
Prints the usage, followed by the specified error message, to stderr and exits the program with exit status = 1. The error message will be prefaced with 'ERROR: '. This method will never return - it exits the program with exit status of 1.

Parameters:
errMsg - the error message

getArg

Parameter<?> getArg(java.lang.String tag)
gets the argument specified by tag

Parameters:
tag - identifies the argument to be returned
Returns:
The argument associated with tag. If no matching argument is found, null is returned.

getArgs

java.util.List<Parameter<?>> getArgs()
gets the value of the arguments (what is left on the command line after all options, and their parameters, have been processed) associated with the command

Returns:
the command's options

getCmdDesc

java.lang.String getCmdDesc()
gets a description of the command's purpose

Returns:
the command's description

getCmdName

java.lang.String getCmdName()
gets the value of the command name associated with this CmdLineHandler

Returns:
the command name

getDieOnParseError

boolean getDieOnParseError()
Gets a flag indicating that the program should exit in the case of a parse error (after displaying the usage and an error message).

Returns:
true (the default) if the parse method should call System.exit() in case of a parse error, false if parse() should return to the user for error processing.
See Also:
parse()

getOption

Parameter<?> getOption(java.lang.String tag)
gets the option specified by tag

Parameters:
tag - identifies the option to be returned
Returns:
the option associated with tag

getOptions

java.util.Collection<Parameter<?>> getOptions()
gets the value of the options associated with the command

Returns:
the command's options

getParseError

java.lang.String getParseError()
Gets the error message from the last call to parse().

Returns:
the error message from the last call to parse()
See Also:
setParseError()

getParser

CmdLineParser getParser()
Gets the parser to be used to parse the command line.

Returns:
the parser to be used to parse the command line
See Also:
setParser()

getUsage

java.lang.String getUsage(boolean hidden)
Gets the usage statement associated with the command.

Parameters:
hidden - indicates whether hidden options are to be included in the usage.
Returns:
the usage statement associated with the command

parse

boolean parse(java.lang.String[] clargs)
parse the specified command line arguments

Parameters:
clargs - command line arguments passed to the main() method of CmdLineHandler's creating class.
Returns:
This method will exit, rather than returning, if one of the following conditions is met:
  • -h, or -h!, or -?, are amongst the command line arguments - the appropriate information is displayed on stdout, and the program exits with status 0.
  • OR, dieOnParseError is set to true AND:
    • a command line argument is incorrectly specified - an error message is displayed and the program exits with status 1.
    • a required command line argument is missing - an error message is displayed and the program exits with status 1.
If dieOnParseError is set to false, this method will return true if there are no parse errors. If there are parse errors, falseis returned and an appropriate error message may be obtained by calling getParseError().

setArgs

void setArgs(Parameter<?>[] args)
sets the value of the arguments (what is left on the command line after all options, and their parameters, have been processed) associated with the command

Parameters:
args - A Collection of Parameter objects. This may be null if the command accepts no command line arguments.

setCmdDesc

void setCmdDesc(java.lang.String cmdDesc)
sets a description of the command's purpose

Parameters:
cmdDesc - a short description of the command's purpose
Throws:
java.lang.IllegalArgumentException - if cmdDesc is null or of 0 length.

setCmdName

void setCmdName(java.lang.String cmdName)
sets the value of the command name associated with this CmdLineHandler

Parameters:
cmdName - the name of the command associated with this CmdLineHandler
Throws:
java.lang.IllegalArgumentException - if cmdName is null, or of 0 length

setDieOnParseError

void setDieOnParseError(boolean val)
Sets a flag indicating that the program should exit in the case of a parse error (after displaying the usage and an error message) - defaults to true.

Parameters:
val - true (the default) if the parse method should call System.exit() in case of a parse error, false if parse() should return to the user for error processing.
See Also:
parse()

setOptions

void setOptions(Parameter<?>[] options)
Sets the value of the options associated with the command

Parameters:
options - A Collection of Parameter objects. This may be null if the command accepts no command line options.

setParseError

void setParseError(java.lang.String parseError)
Sets the error message from the last call to parse().

Parameters:
parseError - the error message from the last call to parse()
See Also:
getParseError()

setParser

void setParser(CmdLineParser parser)
Sets the parser to be used to parse the command line.

Parameters:
parser - the parser to be used to parse the command line
See Also:
getParser()