jcmdline
Class HelpCmdLineHandler

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

public class HelpCmdLineHandler
extends AbstractHandlerDecorator

A CmdLineHandler Decorator class that implements help options that display verbose help messages.

Options are provided to display a regular help message (which includes the regular usage associated with the command) or a help message that includes the hidden parameters in its usage and, optionally, additional help text specific to the hidden parameters.

The implemented options are BooleanParams whose tags are defined by "HelpCmdLineHandler.help.tag" and "HelpCmdLineHandler.helpHidden.tag" in the strings.properties file (set to "help" and "help!", in English).

Should the user specify the -help option on the command line, the command's usage, followed by the more verbose help text specified to this Object's constructor, is printed to stdout, and System.exit(0) is called.

Should the -help! option be specified the same is done, but hidden parameter information and help is displayed as well.

Sample Usage The following creates a CmdLineHandler that uses multiple Decorators to enable the help options supported by this class, the version option implemented by the VersionCmdLineHandler class, and the usage options implemented by the DefaultCmdLineHandler class:

 public static void main(String[] args) {
 
     Parameter[] arguments = new Parameter[] {
         new StringParam("pattern", "the pattern to match", 
                         StringParam.REQUIRED),
         new FileParam("file",
                       "a file to be processed - defaults to stdin",
                       FileParam.IS_FILE & FileParam.IS_READABLE,
                       FileParam.OPTIONAL,
                       FileParam.MULTI_VALUED)
     };
     Parameter[] opts = new Parameter[] {
         new BooleanParam("ignorecase", "ignore case while matching"),
         new BooleanParam("listFiles", "list filenames containing pattern")
     };
     String helpText = "This command prints to stdout all lines within " +
                       "the specified files that contain the specified " +
                       "pattern.\n\n" +
                       "Optionally, the matching may be done without " +
                       "regard to case (using the -ignorecase option).\n\n" +
                       "If the -listFiles option is specified, only the " +
                       "names of the files containing the pattern will be " +
                       "listed.";
 
     CmdLineHandler cl =
         new VersionCmdLineHandler("V 5.2",
         new HelpCmdLineHandler(helpText,
             "grep",
             "find lines in files containing a specified pattern",
             opts,
             arguments));
     cl.parse(args);
     .
     .
 

Help Text Formatting

The help text for a command will be formatted for output such that:

Information on using CmdLineHandlers can be found in the jcmdline User Guide.

Version:
jcmdline Rel. 2.0.0 $Id: HelpCmdLineHandler.java,v 1.2 2002/12/07 14:22:06 lglawrence Exp $
Author:
Lynne Lawrence
See Also:
CmdLineHandler, AbstractHandlerDecorator

Constructor Summary
HelpCmdLineHandler(java.lang.String help, CmdLineHandler handler)
          constructor
HelpCmdLineHandler(java.lang.String help, java.lang.String hiddenHelp, CmdLineHandler handler)
          constructor
HelpCmdLineHandler(java.lang.String help, 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
HelpCmdLineHandler(java.lang.String help, java.lang.String cmdName, java.lang.String cmdDesc, Parameter<?>[] options, Parameter<?>[] args)
          constructor - creates a new DefaultCmdLineHandler as its delegate
HelpCmdLineHandler(java.lang.String help, java.lang.String cmdName, java.lang.String cmdDesc, Parameter<?>[] options, Parameter<?>[] args, CmdLineParser parser)
          constructor - creates a new DefaultCmdLineHandler as its delegate
HelpCmdLineHandler(java.lang.String help, java.lang.String hiddenHelp, 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
HelpCmdLineHandler(java.lang.String help, java.lang.String hiddenHelp, java.lang.String cmdName, java.lang.String cmdDesc, Parameter<?>[] options, Parameter<?>[] args)
          constructor - creates a new DefaultCmdLineHandler as its delegate
HelpCmdLineHandler(java.lang.String help, java.lang.String hiddenHelp, java.lang.String cmdName, java.lang.String cmdDesc, Parameter<?>[] options, Parameter<?>[] args, CmdLineParser parser)
          constructor - creates a new DefaultCmdLineHandler as its delegate
 
Method Summary
protected  boolean processParsedOptions(boolean parseOk)
          Called following the call to parse() of this class's contained CmdLineHandler.
 
Methods inherited from class jcmdline.AbstractHandlerDecorator
addArg, addOption, exitUsageError, getArg, getArgs, getCmdDesc, getCmdName, getCustomOptions, getDieOnParseError, getOption, getOptions, getParseError, getParser, getUsage, parse, setArgs, setCmdDesc, setCmdName, setCustomOptions, setDieOnParseError, setOptions, setParseError, setParser
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HelpCmdLineHandler

public HelpCmdLineHandler(java.lang.String help,
                          CmdLineHandler handler)
constructor

Parameters:
help - the command's help - see Help Text Formatting.
handler - the CmdLineHandler to which most functionality will be delegated
Throws:
java.lang.IllegalArgumentException - if help is null or empty.

HelpCmdLineHandler

public HelpCmdLineHandler(java.lang.String help,
                          java.lang.String hiddenHelp,
                          CmdLineHandler handler)
constructor

Parameters:
help - the command's help - see Help Text Formatting.
hiddenHelp - the command's help for hidden Parameters - may be null or empty
handler - the CmdLineHandler to which most functionality will be delegated
Throws:
java.lang.IllegalArgumentException - if help is null or empty.

HelpCmdLineHandler

public HelpCmdLineHandler(java.lang.String help,
                          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:
help - the command's help - see Help Text Formatting.
cmdName - the name of the command creating this DefaultCmdLineHandler
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

HelpCmdLineHandler

public HelpCmdLineHandler(java.lang.String help,
                          java.lang.String cmdName,
                          java.lang.String cmdDesc,
                          Parameter<?>[] options,
                          Parameter<?>[] args)
constructor - creates a new DefaultCmdLineHandler as its delegate

Parameters:
help - the command's help - see Help Text Formatting.
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:
DefaultCmdLineHandler

HelpCmdLineHandler

public HelpCmdLineHandler(java.lang.String help,
                          java.lang.String cmdName,
                          java.lang.String cmdDesc,
                          Parameter<?>[] options,
                          Parameter<?>[] args,
                          CmdLineParser parser)
constructor - creates a new DefaultCmdLineHandler as its delegate

Parameters:
help - the command's help - see Help Text Formatting.
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:
DefaultCmdLineHandler

HelpCmdLineHandler

public HelpCmdLineHandler(java.lang.String help,
                          java.lang.String hiddenHelp,
                          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:
help - the command's help - see Help Text Formatting.
hiddenHelp - the command's help for hidden Parameters - may be null or empty
cmdName - the name of the command creating this DefaultCmdLineHandler
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

HelpCmdLineHandler

public HelpCmdLineHandler(java.lang.String help,
                          java.lang.String hiddenHelp,
                          java.lang.String cmdName,
                          java.lang.String cmdDesc,
                          Parameter<?>[] options,
                          Parameter<?>[] args)
constructor - creates a new DefaultCmdLineHandler as its delegate

Parameters:
help - the command's help - see Help Text Formatting.
hiddenHelp - the command's help for hidden Parameters - may be null or empty
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:
DefaultCmdLineHandler

HelpCmdLineHandler

public HelpCmdLineHandler(java.lang.String help,
                          java.lang.String hiddenHelp,
                          java.lang.String cmdName,
                          java.lang.String cmdDesc,
                          Parameter<?>[] options,
                          Parameter<?>[] args,
                          CmdLineParser parser)
constructor - creates a new DefaultCmdLineHandler as its delegate

Parameters:
help - the command's help - see Help Text Formatting.
hiddenHelp - the command's help for hidden Parameters - may be null or empty
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:
DefaultCmdLineHandler
Method Detail

processParsedOptions

protected boolean processParsedOptions(boolean parseOk)
Called following the call to parse() of this class's contained CmdLineHandler. This method checks for its option whether parseStatus is true or not.

Specified by:
processParsedOptions in class AbstractHandlerDecorator
Parameters:
parseOk - The result of the parse() call to this class's contained CmdLineHandler.
Returns:
This method will call System.exit(0), rather than returning, if its option is set. Otherwise, parseStatus is returned.