Class ncsa.horizon.util.CmdLine 
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class ncsa.horizon.util.CmdLine 

java.lang.Object
   |
   +----ncsa.horizon.util.CmdLine
public class CmdLine
extends Object
a command line processor that parses out UNIX-like options.

An option is specified on the command line by a single letter preceeded by a dash. Several options may be specified in a single argument that is preceeded by a single dash. Option arguments follow the option (assuming the option was configured to take an argument) with or without a space. This class can be used to process command line options supported by a Java application.

The class is usually configured to for a set of supported switches at construction. The configuration is given in the form of a string (using a syntax similar to the Perl package Getopts.pl) in which each letter in the string is a command line switch supported by the application. A character followed by a colon (:) indicates that the switch takes an argument. A character followed by a dash (-) indicates that the option is to be interpreted as a processing-stop switch; all characters beyond this switch (in that word and in all those after it) are taken to make up literal arguments and not additional switches. This allows one to provide literal arguments that begin with a dash.

One can pass the actual argument list to this class either via its constructor or after instantiation via the setCmdLine(String[]) method, which examines the arguments, seperating out the switches from the literal arguments. One can then check which options were set with the isSet(), getValue(), or the options(). One can also enumerate through the arguments in the order they appeared on the command line via the arguments() method.

For example, suppose you would like to support the following command line: 

    java MyApplication -qu -p -f afile.txt -x -Hello- world
You intend this command line to support 4 basic switches, one of which takes an argument, plus the -x option as a stop switch. The stop switch will prevent the "-Hello-" from being interpreted as a string of options. You can configure your CmdLine object to support this line in this way: 
    CmdLine cl = new CmdLine("f:puqx-", (CmdLine.RELAX & CmdLine.USRWARN));
Note that it doesn't matter what order the options are list in the command line. The RELAX flag tells the class not to throw an exception if an unrecognized option is encountered, while the the USRWARN flag says to inform the user of such errors via a message sent to System.err. One can then process the command line with the following code (where args is the String[] passed to main()): 
    // parse the command line
    try {
	   cl.setCmdLine(args); 
    } catch (UnrecognizedOptionException ex) {
        // this exception won't be thrown if RELAX is given as a flag;
        // however, if it isn't given, you can put your bail-out code
        // here
    }
    // check for options
    if (cl.isSet('q')) ...
    if (cl.isSet('f')) filearg = cl.getValue('f');
    ...
    // get arguments
    String arg;
    for(Enumeration e = cl.options(); e.hasMoreElements();) {
        arg = (String) e.nextElement();
        ...
    }

Variable Index

o argList
the list of normal arguments
o config
the configuration string.
o flags
flags that control reaction to arguments
o NULLFLAG
the null flag
o options
the list of options
o RELAX
do not throw UnrecognizedOptionException; instead just ignore the unrecognized options
o stopchar
the option letter that stops option processing
o USRWARN
print a warning message to System.err if user specifies an unrecognized option (when RELAX is also set) or when an option parameter appears to be missing from the end of the command line.
o WARN
print various warning messages when unexpected conditions are encountered, including any during configuration.

Constructor Index

o CmdLine(String)
o CmdLine(String, int)
o CmdLine(String, int, String[])
construct using a given configuration, flags, and input command line
o CmdLine(String, String[])

Method Index

o addFlags(int)
merge the flags with our current flags
o arguments()
return the arguments found in this command line in the form of an Enumeration
o getAllValues(char)
return a Stack of the String values associated with the requested option.
o getConfig()
return the configuration string
o getFlags()
return the current flag settings
o getNumArgs()
return the number of arguments found in this argument list
o getNumSet(char)
return the number of times the option was set or specified.
o getValue(char)
return the String value of the option if the option is set, or null if it is not.
o isAnOption(char)
return true if the input is recognized as a configured option
o isSet(char)
return true if the option given by the input character has been set.
o isSwitched(char)
return true if the input is a switched option
o main(String[])
o options()
return the options that this object is configured to look for in the form of an Enumeration
o parseStringList(String, String)
break a String containing a list of items into an array of Strings
o setCmdLine(String[])
parse the command line given as an array of Strings
o setConfig(String)
set and parse the configuration string
o setFlags(int)
set the flags

Variables

o config 
  protected String config
the configuration string.
o options 
  protected Hashtable options
the list of options
o argList 
  protected Vector argList
the list of normal arguments
o flags 
  protected int flags
flags that control reaction to arguments
o NULLFLAG 
  public final static int NULLFLAG
the null flag
o RELAX 
  public final static int RELAX
do not throw UnrecognizedOptionException; instead just ignore the unrecognized options
o USRWARN 
  public final static int USRWARN
print a warning message to System.err if user specifies an unrecognized option (when RELAX is also set) or when an option parameter appears to be missing from the end of the command line.
o WARN 
  public final static int WARN
print various warning messages when unexpected conditions are encountered, including any during configuration. This flag also sets the USRWARN flag;
o stopchar 
  protected Character stopchar
the option letter that stops option processing

Constructors

o CmdLine 
  public CmdLine(String configuration,
                 int flags,
                 String args[]) throws UnrecognizedOptionException
construct using a given configuration, flags, and input command line
o CmdLine 
  public CmdLine(String configuration,
                 int flags)
o CmdLine 
  public CmdLine(String configuration)
o CmdLine 
  public CmdLine(String configuration,
                 String args[]) throws UnrecognizedOptionException

Methods

o setConfig 
  public synchronized void setConfig(String configuration)
set and parse the configuration string
o setCmdLine 
  public synchronized void setCmdLine(String args[]) throws UnrecognizedOptionException
parse the command line given as an array of Strings
o getConfig 
  public synchronized String getConfig()
return the configuration string
o setFlags 
  public void setFlags(int flags)
set the flags
o addFlags 
  public void addFlags(int flags)
merge the flags with our current flags
o getFlags 
  public int getFlags()
return the current flag settings
o isSet 
  public boolean isSet(char c)
return true if the option given by the input character has been set.
o isAnOption 
  public boolean isAnOption(char c)
return true if the input is recognized as a configured option
o isSwitched 
  public synchronized boolean isSwitched(char c)
return true if the input is a switched option
o getNumSet 
  public synchronized int getNumSet(char c)
return the number of times the option was set or specified. This works for both switches and parameters. If the input is not configured option, this method returns -1.
o getValue 
  public synchronized String getValue(char c)
return the String value of the option if the option is set, or null if it is not. If the value was set multiple times, return the last value it was set to. If the option is a switch (i.e. does not take an argument), the string returned will be the value of Boolean.toString() (i.e. "true" or "false").
o getAllValues 
  public synchronized Stack getAllValues(char c)
return a Stack of the String values associated with the requested option. The Stack will be empty if the option was not set. If the requested option is a switched option that is set, the Stack will contain the number of elements equal to the number of times the option in the stack with each element being the same string: "true" (admittedly not useful, but nevertheless symetric).
o options 
  public synchronized Enumeration options()
return the options that this object is configured to look for in the form of an Enumeration
o arguments 
  public synchronized Enumeration arguments()
return the arguments found in this command line in the form of an Enumeration
o getNumArgs 
  public synchronized int getNumArgs()
return the number of arguments found in this argument list
o parseStringList 
  public static String[] parseStringList(String input,
                                         String delim)
break a String containing a list of items into an array of Strings
Parameters:
input - the string to break up
delim - the string containing delimiter characters; same as the delimiter string given to the StringTokenizer constructor
o main 
  public static void main(String args[])

All Packages  Class Hierarchy  This Package  Previous  Next  Index