jcmdline
Interface CmdLineHandler

All Known Implementing Classes:
AbstractHandlerDecorator, BasicCmdLineHandler

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. 1.0.3 $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 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 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

setDieOnParseError

public 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()

getDieOnParseError

public 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()

parse

public 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().

setParser

public 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()

getParser

public 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()

setArgs

public 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.

addArg

public void addArg(Parameter arg)
Adds a command line arguement.

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

getArgs

public java.util.List 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

getArg

public 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.

setOptions

public 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.

addOption

public 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.

getOptions

public java.util.Collection getOptions()
gets the value of the options associated with the command

Returns:
the command's options

getOption

public 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

setCmdDesc

public 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.

getCmdDesc

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

Returns:
the command's description

setCmdName

public 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

getCmdName

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

Returns:
the command name

getUsage

public 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

setParseError

public 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()

getParseError

public 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()

exitUsageError

public 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: '.

Parameters:
errMsg - the error message
Returns:
Doesn't return - exits the program with exit status of 1.