|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectjcmdline.BasicCmdLineHandler
public class BasicCmdLineHandler
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'");
}
Parameter,
CmdLineParser| Constructor Summary | |
|---|---|
BasicCmdLineHandler(java.lang.String cmdName,
java.lang.String cmdDesc,
java.util.Collection options,
java.util.Collection 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 |
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 |
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 |
|---|
public BasicCmdLineHandler(java.lang.String cmdName,
java.lang.String cmdDesc,
Parameter[] options,
Parameter[] args,
CmdLineParser parser)
cmdName - the name of the commandcmdDesc - a short description of the commandoptions - a collection of Parameter objects, describing the
command's command-line optionsargs - 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
java.lang.IllegalArgumentException - if any of the
parameters are not correctly specified.setCmdName(),
setCmdDesc(),
setOptions(),
setArgs(),
setParser()
public BasicCmdLineHandler(java.lang.String cmdName,
java.lang.String cmdDesc,
Parameter[] options,
Parameter[] args)
cmdName - the name of the commandcmdDesc - a short description of the commandoptions - a collection of Parameter objects, describing the
command's command-line optionsargs - 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)
java.lang.IllegalArgumentException - if any of the
parameters are not correctly specified.setCmdName(),
setCmdDesc(),
setOptions(),
setArgs(),
PosixCmdLineParser
public BasicCmdLineHandler(java.lang.String cmdName,
java.lang.String cmdDesc,
java.util.Collection options,
java.util.Collection args)
cmdName - the name of the command creating this
BasicCmdLineHandlercmdDesc - a short description of the command's purposeoptions - a collection of Parameter objects, describing the
command's command-line optionsargs - 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)
java.lang.IllegalArgumentException - if any of the
parameters are not correctly specified.setCmdName(),
setCmdDesc(),
setOptions(),
PosixCmdLineParser| Method Detail |
|---|
public boolean parse(java.lang.String[] clargs)
parse in interface CmdLineHandlerclargs - command line arguments passed to the main() method
of BasicCmdLineHandler's creating class.
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.
public void setParser(CmdLineParser parser)
setParser in interface CmdLineHandlerparser - the parser to be used to parse the command linegetParser()public CmdLineParser getParser()
getParser in interface CmdLineHandlersetParser()public void setDieOnParseError(boolean val)
true.
setDieOnParseError in interface CmdLineHandlerval - 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.parse()public boolean getDieOnParseError()
getDieOnParseError in interface CmdLineHandlertrue (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.parse()public void exitUsageError(java.lang.String errMsg)
exitUsageError in interface CmdLineHandlererrMsg - the error messagepublic void setArgs(Parameter[] args)
setArgs in interface CmdLineHandlerargs - A Collection of Parameter objects. This may
be null if the command accepts no command line
arguments.public void addArg(Parameter arg)
addArg in interface CmdLineHandlerarg - the new command line argument
java.lang.IllegalArgumentException - if:
arg is null
arg is a required argument but the
previous argument was optional
public java.util.List getArgs()
getArgs in interface CmdLineHandlerpublic Parameter getArg(java.lang.String tag)
tag
getArg in interface CmdLineHandlertag - identifies the argument to be returned
tag.
If no matching argument is found, null is returned.public void setOptions(Parameter[] options)
setOptions in interface CmdLineHandleroptions - A Collection of Parameter objects. This may
be null if the command accepts no command line
options.public void addOption(Parameter opt)
addOption in interface CmdLineHandleropt - the new command line option
java.lang.NullPointerException - if opt is null.
java.lang.IllegalArgumentException - if an option with the
same tag has already been added.public java.util.Collection getOptions()
getOptions in interface CmdLineHandlerpublic Parameter getOption(java.lang.String tag)
tag
getOption in interface CmdLineHandlertag - identifies the option to be returned
tagpublic void setCmdDesc(java.lang.String cmdDesc)
setCmdDesc in interface CmdLineHandlercmdDesc - a short description of the command's purpose
java.lang.IllegalArgumentException - if cmdDesc
is null or of 0 length.public java.lang.String getCmdDesc()
getCmdDesc in interface CmdLineHandlerpublic void setCmdName(java.lang.String cmdName)
setCmdName in interface CmdLineHandlercmdName - the name of the command associated with this
BasicCmdLineHandler
java.lang.IllegalArgumentException - if cmdName is null,
or of 0 lengthpublic java.lang.String getCmdName()
getCmdName in interface CmdLineHandlerpublic java.lang.String getUsage(boolean hidden)
getUsage in interface CmdLineHandlerhidden - indicates whether hidden options are to be included
in the usage.
public void setParseError(java.lang.String parseError)
setParseError in interface CmdLineHandlerparseError - the error message from the last call to parse()getParseError()public java.lang.String getParseError()
getParseError in interface CmdLineHandlersetParseError()
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||