: Class GetOpt

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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()`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD