Provides for handling the command line. To use this feature you have to write a help text document. To get a CommandLine use the CommandLineFactory first.

Package Specification

The usage of any program should be documented by a help system. This package allows to write a help text as it would be displayed to the user and gets the commandline arguments and options from it. All the programmer has to do is to write the help for its arguments or options and use them in his program.

Usage

Now lets have a short example how to use this package. This example relies on a help document C:\MyApplication\cmd.help. It also relies on a batch that start the java application is is found in C:\MyApplication\cmd.bat.

The help document looks like the following:

Usage:
  cmd [options] {myArg} [{opArg}]

Description:
  Just a little example.

Required arguments:
  {myArg}    displayed to the user when running the example

Optional arguments:
  {opArg}    displayed to the user; default: (aaa)

Options:
  -{help}    displays this help text
  -{op} 

displayed to the user; default: (xxx)

And this is how the sample class looks like:

import java.io.FileNotFoundException;

import de.goerntkai.toolbox.fs.Folder;
import de.goerntkai.toolbox.fs.NoFolderException;

class MyClass {

  private static void displayText(String[] theText) {
    for (int idx = 0; idx <= theText.length; idx++) {
      System.out.println(theText[idx]);
    }
  }

  public static void main(
    String[] args
  ) throws NoFolderException, FileNotFoundException, HelpTextException {

    //...

    Folder helpDir = new Folder("C:\\MyApplication");
    CommandLine cmdLn = CommandLineFactory.createCommandLine("cmd", args, helpDir);
    if (cmdLn.isValid()) {

      //...

      CommandLineParameter helpOpt = cmdLn.getParameter("help");
      if (helpOpt.isSet()) {
        displayText(cmdLn.getHelpText());
      }

      //...

      CommandLineParameter myArg = cmdLn.getParameter("myArg");
      System.out.println(myArg.getValue());

      CommandLineParameter opArg = cmdLn.getParameter("opArg");
      System.out.println(opArg.getValue());

      CommandLineParameter op = cmdLn.getParameter("op");
      System.out.println(op.getValue());

      //...

    } else {
      displayText(cmdLn.getHelpText());
    }
  }
}
	

The Help Text Document

A help text file should always be named like {commandName}.help. As the text is displayed as it is found in the document be careful not to have lines longer than 80 characters. It is always given in the following structure:

Usage:
  commandName [options] {requiredArguments} [{optionalArguments}]

Description:
  a brief description of the commando

Required arguments:
  {argument} argumentDescription

Optional arguments:
  {argument} argumentDescription; default: (defaultValue)

Options:
  -{option}             optionDescription
  -{option}  optionDescription; default: (defaultValue)
	

Usage:, Description:, Required arguments:, Optional arguments:, Options: and default: are keywords and must not be changed or misspelled. The usage block and the description block are mandatory. The other blocks can be omitted but must not change their order when used. Indentation is for ease of legibility. Indent by two spaces and build columns also with spaces. There can be as many options and arguments as you like.

In the usage block there is no need to list up all possible options. Just use [options] to make clear that they are all optional. Though there is need to list up every argument, both required and optional.

Curly brackets mark the end and the beginning of an arguments or options name and are required. Square brackets mark beginning and end of an optional parameter. They are required in the usage block and may be omitted in the description lines. The parenthesis around the default values are mandatory as well as the angle bracket around the parameter names. Use the minus before every options name to show that an option must always be given with it in the command line.

The order of the options is not important. Indeed, the order of the arguments is very important. So you should note the description of the arguments in the same order as you gave them in the usage line.

Related Documentation

None at the moment.

For overviews, tutorials, examples, guides, and tool documentation, please see:

@since 1.4.1_02