com.dalsemi.shell.server
Class GetOpt

java.lang.Object
  |
  +--com.dalsemi.shell.server.GetOpt

public class GetOpt

extends Object

Utility loosely based on the getopt command on UNIX, used to parse command line arguments.

Usage

Normal operation using the GetOpt class will look something like this:

       int opt;
       boolean use_ID = false;
       String name = null;
       String pass = null;
       //args is an array with the command line arguments
       GetOpt myopts = new GetOpt(args,"n:p:i");
       while ((opt = myopts.getopt()) != myopts.optEOF)
       {
           if (opt == 'i')
               use_ID = true;
           else if (opt == 'n')
               name = myopts.optArgGet();
           else if (opt == 'p')
               pass = myopts.optArgGet();
           else
           {
               //an error must have occurred
               err.println(getUsageString());
               return;
           }
       }
 

The format string passed to the Constructor tells GetOpt which arguments are valid, and which ones require more information. For this example, the arguments 'n', 'p', and 'i' are valid. Arguments 'n' and 'p' require additional information, as denoted by the colon ':' following the option letters.

Note that once an unexpected value is returned, the program stops parsing the command line input. Once GetOpt finds an error, it enters an unknown state. Subsequent calls to getopt() cannot be expected to conform to normal behavior.

GetOpt will accept several options defined together in one string. With a format string of "fdi", the argument string "-fdi" will be parsed as three separate arguments 'f', 'd', and 'i'. Note that if the format string is "f:di", it will fail unless the argument string is changed to "-dif" so that 'f' is at the end of the argument. Also, in this case another argument must follow, i.e.:

         java MyProgram -dif argument
 

Field Summary

static int	optEOF Indicates there are no more arguments to draw from this object.
static int	optERR Indicates there was an error in parsing the arguments.

Constructor Summary

GetOpt(String[] args, String opts)
Constructor for a GetOpt object to parse command line arguments.

Method Summary

int	getopt() Returns the next option found on the command line.
String	optArgGet() Returns the argument string associated with the last option reported by getopt(), or null if no argument is associated with this argument.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

optEOF

public static final int optEOF

Indicates there are no more arguments to draw from this object.

optERR

public static final int optERR

Indicates there was an error in parsing the arguments. Errors occur if an unspecified option is encountered or an option that should be followed by a String value is not. Once an error is encountered, the program should stop parsing arguments. Note that an error is only reported once it is reached in the getopt() algorithm. It is possible to receive one or more valid options and argument strings before receiving an error.

Constructor Detail

GetOpt

public GetOpt(String[] args,
              String opts)

Constructor for a GetOpt object to parse command line arguments.

The first parameter should be a String[] object containing all of the command line arguments. If a program is called with the following command line:

       java MyProgram -abc one_argument another argument -de
 

Then args should contain:

1. "-abc"
2. "one_argument"
3. "another"
4. "argument"
5. "-de"

The second parameter is a format string that tells GetOpt which options are valid and which of those options must have accompanying argument strings. All options can be only one character long. A colon ':' following an option in the option string means that an argument is expected to follow this option. For example, if the available options for MyProgram are 'a', 'b', 'c', 'd', and 'e', and option 'c' expects an extra argument, the format string is "abc:de". Order of the characters is irrelevant: the format string could also be "ebadc:".

If the format string starts with the '!' character, GetOpt will report an error if it finds any unexpected argument. For instance, with a format string of "!ab:c", the command lines:

       java MyProgram -a -b argument1 argument2
       java MyProgram -a -b argument1 -c argument2
       java MyProgram -a argument1
       java MyProgram argument1
 

will all report errors. The first line fails because argument2 does not belong to an option. The second line fails because the "-c" option does not take arguments, so argument2 again belongs to no option. Line 3 fails "-a" takes no arguments, and line 4 fails because argument1 belongs to no option.

Parameters:

args - contains all of the command line arguments

opts - format string that tells GetOpt which options are valid and which of those options must have accompanying argument strings

Method Detail

getopt

public int getopt()

Returns the next option found on the command line. If args as passed to the Constructor represents the command line:

      java MyProgram -abc argument1 -d -e
 

Then getopt() will return in order 'a', 'b', 'c', 'd', 'e', and optEOF, assuming the format string is "abc:de". If the format string is "abc:d:e", then getopt() will return this order: 'a', 'b', 'c', 'd', and optEOF. In this case, "-e" is the argument string for the option 'd'.

Returns:

the next option found on the command line

See Also:

optArgGet()

optArgGet

public String optArgGet()

Returns the argument string associated with the last option reported by getopt(), or null if no argument is associated with this argument. In the following example:

      java MyProgram -abc argument1 -d -e
 

optArgGet()'s output will differ based on the format string.

Format String:	"abc:de"	"abc:d:e"
Option/Argument 1:	'a' / null	'a' / null
Option/Argument 2:	'b' / null	'b' / null
Option/Argument 3:	'c' / "argument1"	'c' / "argument1"
Option/Argument 4:	'd' / null	'd' / "-e"
Option/Argument 5:	'e' / null	NA

Returns:

the argument string associated with the last option reported by getopt()