|
|||||||||
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<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 |
---|
public BasicCmdLineHandler(java.lang.String cmdName, java.lang.String cmdDesc, java.util.Collection<Parameter<?>> options, java.util.Collection<Parameter<?>> 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
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, 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()
Method Detail |
---|
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 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 void exitUsageError(java.lang.String errMsg)
exitUsageError
in interface CmdLineHandler
errMsg
- the error messagepublic 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 java.util.List<Parameter<?>> getArgs()
getArgs
in interface CmdLineHandler
public java.lang.String getCmdDesc()
getCmdDesc
in interface CmdLineHandler
public java.lang.String getCmdName()
getCmdName
in interface CmdLineHandler
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 Parameter<?> getOption(java.lang.String tag)
tag
getOption
in interface CmdLineHandler
tag
- identifies the option to be returned
tag
public java.util.Collection<Parameter<?>> getOptions()
getOptions
in interface CmdLineHandler
public java.lang.String getParseError()
getParseError
in interface CmdLineHandler
setParseError()
public CmdLineParser getParser()
getParser
in interface CmdLineHandler
setParser()
public java.lang.String getUsage(boolean hidden)
getUsage
in interface CmdLineHandler
hidden
- indicates whether hidden options are to be included in the
usage.
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 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 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 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 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 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 setParseError(java.lang.String parseError)
setParseError
in interface CmdLineHandler
parseError
- the error message from the last call to parse()getParseError()
public void setParser(CmdLineParser parser)
setParser
in interface CmdLineHandler
parser
- the parser to be used to parse the command linegetParser()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |