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

Class ncsa.horizon.util.CmdLine

java.lang.Object
  |
  +--ncsa.horizon.util.CmdLine

public class CmdLine

extends java.lang.Object

implements CmdLine.Flags

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.arguments(); e.hasMoreElements();) {
         arg = (String) e.nextElement();
         ...
     }
 

Inner Class Summary

static	CmdLine.Flags flags for configuring CmdLine objects
	CmdLine.UnrecognizedOptionException an Exception that can be thrown if an unrecognized option has been encountered.

Field Summary

java.util.Vector	argList the list of normal arguments
java.lang.String	config the configuration string.
int	flags flags that control reaction to arguments
java.util.Hashtable	options the list of options
java.lang.Character	stopchar the option letter that stops option processing

Constructor Summary

CmdLine(java.lang.String configuration, int flags, java.lang.String[] args)
construct using a given configuration, flags, and input command line

CmdLine(java.lang.String configuration, int flags)

CmdLine(java.lang.String configuration)

CmdLine(java.lang.String configuration, java.lang.String[] args)

Method Summary

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

Methods inherited from class java.lang.Object

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

Field Detail

config

protected java.lang.String config

the configuration string.

options

protected java.util.Hashtable options

the list of options

argList

protected java.util.Vector argList

the list of normal arguments

flags

protected int flags

flags that control reaction to arguments

stopchar

protected java.lang.Character stopchar

the option letter that stops option processing

Constructor Detail

CmdLine

public CmdLine(java.lang.String configuration,
               int flags,
               java.lang.String[] args)
        throws CmdLine.UnrecognizedOptionException

construct using a given configuration, flags, and input command line

CmdLine

public CmdLine(java.lang.String configuration,
               int flags)

CmdLine

public CmdLine(java.lang.String configuration)

CmdLine

public CmdLine(java.lang.String configuration,
               java.lang.String[] args)
        throws CmdLine.UnrecognizedOptionException

Method Detail

setConfig

public void setConfig(java.lang.String configuration)

set and parse the configuration string

setCmdLine

public void setCmdLine(java.lang.String[] args)
               throws CmdLine.UnrecognizedOptionException

parse the command line given as an array of Strings

getConfig

public java.lang.String getConfig()

return the configuration string

setFlags

public void setFlags(int flags)

set the flags

addFlags

public void addFlags(int flags)

merge the flags with our current flags

getFlags

public int getFlags()

return the current flag settings

isSet

public boolean isSet(char c)

return true if the option given by the input character has been set.

isAnOption

public boolean isAnOption(char c)

return true if the input is recognized as a configured option

isSwitched

public boolean isSwitched(char c)

return true if the input is a switched option

getNumSet

public 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.

getValue

public java.lang.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").

getAllValues

public java.util.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).

options

public java.util.Enumeration options()

return the options that this object is configured to look for in the form of an Enumeration

arguments

public java.util.Enumeration arguments()

return the arguments found in this command line in the form of an Enumeration

getNumArgs

public int getNumArgs()

return the number of arguments found in this argument list

parseStringList

public static java.lang.String[] parseStringList(java.lang.String input,
                                       java.lang.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

main

public static void main(java.lang.String[] args)