|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjcmdline.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 CmdLineHandler
clargs
- 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, false
is 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 CmdLineHandler
parser
- the parser to be used to parse the command linegetParser()
public CmdLineParser getParser()
getParser
in interface CmdLineHandler
setParser()
public void setDieOnParseError(boolean val)
true
.
setDieOnParseError
in interface CmdLineHandler
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.parse()
public boolean getDieOnParseError()
getDieOnParseError
in interface CmdLineHandler
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 void exitUsageError(java.lang.String errMsg)
exitUsageError
in interface CmdLineHandler
errMsg
- the error message
public void setArgs(Parameter[] args)
setArgs
in interface CmdLineHandler
args
- 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 CmdLineHandler
arg
- 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 CmdLineHandler
public Parameter getArg(java.lang.String tag)
tag
getArg
in interface CmdLineHandler
tag
- identifies the argument to be returned
tag
.
If no matching argument is found, null is returned.public void setOptions(Parameter[] options)
setOptions
in interface CmdLineHandler
options
- 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 CmdLineHandler
opt
- 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 CmdLineHandler
public Parameter getOption(java.lang.String tag)
tag
getOption
in interface CmdLineHandler
tag
- identifies the option to be returned
tag
public void setCmdDesc(java.lang.String cmdDesc)
setCmdDesc
in interface CmdLineHandler
cmdDesc
- 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 CmdLineHandler
public void setCmdName(java.lang.String cmdName)
setCmdName
in interface CmdLineHandler
cmdName
- 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 CmdLineHandler
public java.lang.String getUsage(boolean hidden)
getUsage
in interface CmdLineHandler
hidden
- indicates whether hidden options are to be included
in the usage.
public void setParseError(java.lang.String parseError)
setParseError
in interface CmdLineHandler
parseError
- the error message from the last call to parse()getParseError()
public java.lang.String getParseError()
getParseError
in interface CmdLineHandler
setParseError()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |