jcmdline
Class BasicCmdLineHandler

java.lang.Object
  extended by jcmdline.BasicCmdLineHandler
All Implemented Interfaces:
CmdLineHandler

public class BasicCmdLineHandler
extends java.lang.Object
implements CmdLineHandler

Used to define, parse, and validate the parameters associated with an executable's command line.

Objects of this class use a CmdLineParser to do the actual parsing of the command line. By default, this class uses a PosixCmdLineParser.

The following semantics are used throughout the documentation for this class. A command line parameter refers to either a command line option, or a command line argument.

A command line option is identified by a tag and may or not have an associated value. For instance, in the following posix-type option, "outfile" is the tag and "/tmp/myoutfile" is the value:

 --outfile / tmp / myoutfile
 

Command line arguments are what are left on the command line after all options have been processed. For example, again using a posix style command line, "filename1" and "filename2" would be the arguments:

  -e 's/red/blue/' filename1 filename2
 

Parameters may be designated as hidden. Hidden parameters are those that can be specified, but whose documentation is not displayed to the user when a normal usage is printed.

This class is used as in the following example of a 'cat' facsimile in java:

 public class Concat {
        static FileParam outfile = new FileParam("out",
                        "a file to receive the concatenated files (default is stdout)");
        static BooleanParam delete = new BooleanParam("delete",
                        "specifies that all of the original files are to be deleted");
        static FileParam infiles = new FileParam("filename",
                        "files to be concatenated", FileParam.IS_FILE
                                        & FileParam.IS_READABLE, FileParam.REQUIRED,
                        FileParam.MULTI_VALUED);
 
        public static void main(String[] args) {
         outfile.setOptionLabel("outfile");
         BasicCmdLineHandler clp = new BasicCmdLineHandler(
                 "Concat", "concatenates the specified files",
                 new Parameter[] { outfile, delete },
                 new Parameter[] { infiles });
         clp.parse(args);
 
         if (outfile.isSet()) {
             ....
         } else {
             ...
         }
         for (Iterator itr = infiles.getFiles().iterator(); itr.hasNext(); ) {
             ...
         }
         if (delete.isTrue()) {
             ...
         }
     }
 }
 
 

This class implements no options on its own. It it typically used in conjunction with one or more of the AbstractHandlerDecorator classes that provide some useful options.

Post Processing Command Line Parameters

It may be the case that none of the supplied Parameter types fully accomodates a program's needs. For instance, a program may require a filename option that is an html filename, ending with '.html'. In this case, the programmer has the options of creating their own Parameter subclass, or post-processing the returned FileParam parameter and generating their own error message. The exitUsageError() method is provided so that programs that post-process parameters can take the same exit as would be taken for "normal" parameter processing failures. For instance, in the case just described, the following code could be used to exit the program if the specified file did not end with '.html' (myfile being a FileParam object, and cl being the BasicCmdLineHandler object):

 cl.parse(args);
 if (!myfile.getFile().getPath().endsWith(".html")) {
        cl.exitUsageError("Filename specified for '" + myfile.getTag()
                        + "' must end with '.html'");
 }
 

Version:
jcmdline Rel. 2.0.0 $Id: BasicCmdLineHandler.java,v 1.4 2005/02/06 13:19:19 lglawrence Exp $
Author:
Lynne Lawrence
See Also:
Parameter, CmdLineParser

Constructor Summary
BasicCmdLineHandler(java.lang.String cmdName, java.lang.String cmdDesc, java.util.Collection<Parameter<?>> options, java.util.Collection<Parameter<?>> args)
          constructor - uses the PosixCmdLineParser to parse the command line
BasicCmdLineHandler(java.lang.String cmdName, java.lang.String cmdDesc, Parameter<?>[] options, Parameter<?>[] args)
          constructor - uses the PosixCmdLineParser to parse the command line
BasicCmdLineHandler(java.lang.String cmdName, java.lang.String cmdDesc, Parameter<?>[] options, Parameter<?>[] args, CmdLineParser parser)
          constructor
 
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 BasicCmdLineHandler
 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 BasicCmdLineHandler
 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BasicCmdLineHandler

public BasicCmdLineHandler(java.lang.String cmdName,
                           java.lang.String cmdDesc,
                           java.util.Collection<Parameter<?>> options,
                           java.util.Collection<Parameter<?>> args)
constructor - uses the PosixCmdLineParser to parse the command line

Parameters:
cmdName - the name of the command creating this BasicCmdLineHandler
cmdDesc - a short description of the command's purpose
options - a collection of Parameter objects, describing the command's command-line options
args - a collection of Parameter objects, describing the command's command-line arguments (what is left on the command line after all options and their parameters have been processed)
Throws:
java.lang.IllegalArgumentException - if any of the parameters are not correctly specified.
See Also:
setCmdName(), setCmdDesc(), setOptions(), PosixCmdLineParser

BasicCmdLineHandler

public BasicCmdLineHandler(java.lang.String cmdName,
                           java.lang.String cmdDesc,
                           Parameter<?>[] options,
                           Parameter<?>[] args)
constructor - uses the PosixCmdLineParser to parse the command line

Parameters:
cmdName - the name of the command
cmdDesc - a short description of the command
options - a collection of Parameter objects, describing the command's command-line options
args - a collection of Parameter objects, describing the command's command-line arguments (what is left on the command line after all options and their parameters have been processed)
Throws:
java.lang.IllegalArgumentException - if any of the parameters are not correctly specified.
See Also:
setCmdName(), setCmdDesc(), setOptions(), setArgs(), PosixCmdLineParser

BasicCmdLineHandler

public BasicCmdLineHandler(java.lang.String cmdName,
                           java.lang.String cmdDesc,
                           Parameter<?>[] options,
                           Parameter<?>[] args,
                           CmdLineParser parser)
constructor

Parameters:
cmdName - the name of the command
cmdDesc - a short description of the command
options - a collection of Parameter objects, describing the command's command-line options
args - a collection of Parameter objects, describing the command's command-line arguments (what is left on the command line after all options and their parameters have been processed)
parser - a CmdLineParser to be used to parse the command line
Throws:
java.lang.IllegalArgumentException - if any of the parameters are not correctly specified.
See Also:
setCmdName(), setCmdDesc(), setOptions(), setArgs(), setParser()
Method Detail

addArg

public void addArg(Parameter<?> arg)
Adds a command line arguement. Command line arguments must be added in the order that they will be specified on the command line.

Specified by:
addArg in interface CmdLineHandler
Parameters:
arg - the new command line argument
Throws:
java.lang.IllegalArgumentException - if:
  • arg is null
  • the previously added argument was multi-valued (only the last argument can be multi-valued)
  • arg is a required argument but the previous argument was optional

addOption

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

Specified by:
addOption in interface CmdLineHandler
Parameters:
opt - the new command line option
Throws:
java.lang.NullPointerException - if opt is null.
java.lang.IllegalArgumentException - if an option with the same tag has already been added.

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: '. This method never returns - it exits the program with exit status of 1.

Specified by:
exitUsageError in interface CmdLineHandler
Parameters:
errMsg - the error message

getArg

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

Specified by:
getArg in interface CmdLineHandler
Parameters:
tag - identifies the argument to be returned
Returns:
The argument associated with tag. If no matching argument is found, null is returned.

getArgs

public 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

Specified by:
getArgs in interface CmdLineHandler
Returns:
the command's options

getCmdDesc

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

Specified by:
getCmdDesc in interface CmdLineHandler
Returns:
the command's description

getCmdName

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

Specified by:
getCmdName in interface CmdLineHandler
Returns:
the command name

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

Specified by:
getDieOnParseError in interface CmdLineHandler
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

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

Specified by:
getOption in interface CmdLineHandler
Parameters:
tag - identifies the option to be returned
Returns:
the option associated with tag

getOptions

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

Specified by:
getOptions in interface CmdLineHandler
Returns:
the command's options

getParseError

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

Specified by:
getParseError in interface CmdLineHandler
Returns:
the error message from the last call to parse()
See Also:
setParseError()

getParser

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

Specified by:
getParser in interface CmdLineHandler
Returns:
the parser to be used to parse the command line
See Also:
setParser()

getUsage

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

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

parse

public boolean parse(java.lang.String[] clargs)
Parse the specified command line arguments. This method will fail if:

Specified by:
parse in interface CmdLineHandler
Parameters:
clargs - command line arguments passed to the main() method of BasicCmdLineHandler's creating class.
Returns:
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().

If dieOnParseError is set to true and the method fails, the program will exit with exit code 1 after printing the usage to stderr.


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

Specified by:
setArgs in interface CmdLineHandler
Parameters:
args - A Collection of Parameter objects. This may be null if the command accepts no command line arguments.

setCmdDesc

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

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

setCmdName

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

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

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.

Specified by:
setDieOnParseError in interface CmdLineHandler
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

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

Specified by:
setOptions in interface CmdLineHandler
Parameters:
options - A Collection of Parameter objects. This may be null if the command accepts no command line options.

setParseError

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

Specified by:
setParseError in interface CmdLineHandler
Parameters:
parseError - the error message from the last call to parse()
See Also:
getParseError()

setParser

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

Specified by:
setParser in interface CmdLineHandler
Parameters:
parser - the parser to be used to parse the command line
See Also:
getParser()