ucb.util
Class CommandArgs

java.lang.Object
  |
  +--ucb.util.CommandArgs

public class CommandArgs

extends java.lang.Object

A CommandArgs object is a sequence of arguments (Strings), typically extracted from the command-line arguments to a main procedure. It expects such arguments to conform to Sun's standard guidelines, according to which, a command (issued to a shell) has the following general form:

     COMMAND [ OPTION ... ] [ -- ] [ OTHER_ARGUMENT ... ]
  

([]'s indicate optional parts; ... indicates one or more). Each OPTION has one of the following forms (x, y, etc. denote non-blank characters):

  Single parameterless short option:
     -x 

  Several parameterless short options:
     -xyz...

  Single short option with parameter:
     -x OPTARG        
or
     -xOPTARG
 
  Long parameterless option:
     --opt

  Long option with parameter:
     --opt=foo
  

If a short option takes an additional argument, that argument is always required to follow; it cannot be omitted. When a long argument takes an argument, it is optional.

The '--' before the first OTHER_ARGUMENT is optional unless that OTHER_ARGUMENT starts with '-'.

One creates a CommandArgs object by supplying an array of legal option names (without leading "-"s or "--"s), and an array of command-line argument strings (as sent to the main function). To indicate options that take an additional parameter value, affix a trailing '=' to the option name. If all options are single-letter, you can use the alternative form of the constructor, which takes as its option a single string with all option letters, with those that take arguments followed by a colon (:).

The CommandArgs object then parses the command-line arguments according to the specification, and presents the options and other arguments by means of a set of access methods.

Any short option is considered equivalent to a one-character long option, and vice-versa.

For example, suppose that we have a program whose usage is

     foo [ -c ] [ -h ] [ -o FILE ] ARG1
  

where []'s indicate optional arguments. It's main program would begin

    import ucb.util.CommandArgs;
    class foo {
      public static void main (String[] args0) {
         boolean cOptionSpecified;
         boolean hOptionSpecified;
         String oOptionValue;
         String arg1;
         CommandArgs args = new CommandArgs ("cho:", args0);
         if (! args.ok () 
             || args.number ('o') > 1  // multiple o options
             || args.numOtherArgs () != 1)
            ERROR ();
         cOptionSpecified = args.present ('c');
         hOptionSpecified = args.present ('h');
         oOptionValue = args.optionValue ('o', 0); // null if absent.
         arg1 = args.otherArg (0);
         ...
   

For a program whose usage is

      bar [ -c ] [ -o FILE ] [ --dry-run ] [ --form=NAME ] ARG1
   

we can write

    import ucb.util.CommandArgs;
    class foo {
      public static void main (String[] args0) {
         ...
         String[] options = { "c", "o=", "dry-run", "form=" };
         CommandArgs args = new CommandArgs (options, args0);
         ...
         formValue = args.optionValue ("form", 0);
    

Constructor Summary

CommandArgs(java.lang.String[] longOptions, java.lang.String[] rawArgs)

CommandArgs(java.lang.String shortOptions, java.lang.String[] rawArgs)
A new stream of arguments conforming to SHORTOPTIONS and LONGOPTIONS, extracted from RAWARGS (typically the argument to the main program).

Method Summary

java.lang.String	name(int i) The option name associated with the Ith option occurrence (0 <= I < numOptions ()).
int	number(char c) The number of occurrences of option C in the arguments to the constructor.
int	number(java.lang.String s) The number of occurrences of option S in the arguments to the constructor.
int	numOptions() The number of option occurrences in the arguments.
int	numOtherArgs() The number of other (non-option) arguments (does not include --).
boolean	ok() True iff all options provided to the constructor were correct.
boolean	ok(int i) True iff the Ith option occurrence was legal, 0 <= I < numOptions ().
char	option(int i) The option letter associated with the Ith option occurrence (0 <= I < numOptions ()).
java.lang.String	optionValue(char c, int i) The argument value of the Ith occurrence of option C, where I >= 0.
java.lang.String	optionValue(int i) The argument value associated with the Ith option occurrence (0 <= I < numOptions ()).
java.lang.String	optionValue(java.lang.String s, int i) The argument value of the Ith occurrence of option S, where I >= 0.
java.lang.String	otherArg(int i) The Ith other (non-option) argument, 0 <= I < numOtherArgs ().
boolean	present(char c) True iff at least one instance of option C is present.
boolean	present(java.lang.String s) True iff at least one instance of option S is present.

Methods inherited from class java.lang.Object

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

Constructor Detail

CommandArgs

public CommandArgs(java.lang.String shortOptions,
                   java.lang.String[] rawArgs)

A new stream of arguments conforming to SHORTOPTIONS and LONGOPTIONS, extracted from RAWARGS (typically the argument to the main program). SHORTOPTIONS consists of a sequence of "option specifiers", each consisting of a single option character -- defining the character to denote a parameterless option), or an option character followed by ':' --defining that character to denote an option that takes a parameter. LONGOPTIONS is an array of long-style option names, without their leading "--". Long options that may take an argument are suffixed by "=".

CommandArgs

public CommandArgs(java.lang.String[] longOptions,
                   java.lang.String[] rawArgs)

Method Detail

number

public int number(char c)

The number of occurrences of option C in the arguments to the constructor. C is taken to denote a short-form option.

number

public int number(java.lang.String s)

The number of occurrences of option S in the arguments to the constructor. S may denote either kind of option (short- or long-form).

present

public boolean present(char c)

True iff at least one instance of option C is present. C is taken to denote a one-character short-form option (e.g., -g).

present

public boolean present(java.lang.String s)

True iff at least one instance of option S is present. S may denote either kind of option (short- or long-form).

optionValue

public java.lang.String optionValue(char c,
                                    int i)

The argument value of the Ith occurrence of option C, where I >= 0. Yields null if there is no Ith occurrence of option C, or if option C is parameterless. C is taken to denote a short option.

optionValue

public java.lang.String optionValue(java.lang.String s,
                                    int i)

The argument value of the Ith occurrence of option S, where I >= 0. Yields null if there is no Ith occurrence of option S, or if option S is parameterless. S may denote either a long or short option.

numOptions

public int numOptions()

The number of option occurrences in the arguments.

ok

public boolean ok(int i)

True iff the Ith option occurrence was legal, 0 <= I < numOptions ().

ok

public boolean ok()

True iff all options provided to the constructor were correct.

option

public char option(int i)

The option letter associated with the Ith option occurrence (0 <= I < numOptions ()). For long options, returns the null character.

name

public java.lang.String name(int i)

The option name associated with the Ith option occurrence (0 <= I < numOptions ()). For short options, returns the one-character String containing just the option letter.

optionValue

public java.lang.String optionValue(int i)

The argument value associated with the Ith option occurrence (0 <= I < numOptions ()). This is null for parameterless options.

numOtherArgs

public int numOtherArgs()

The number of other (non-option) arguments (does not include --).

otherArg

public java.lang.String otherArg(int i)

The Ith other (non-option) argument, 0 <= I < numOtherArgs ().