com.ccg.util
Class CommandLine

java.lang.Object
  com.ccg.util.CommandLine

All Implemented Interfaces:

Lookup

public class CommandLine
extends Object
implements Lookup

Useful when looking for command line switches.

This class is designed to help one parse command line options for an array of strings. For example, if you want to allow the user to specify one or more different command line options, these routines can be very handy when looking for command line switches. Assume you had a program which would output random numbers in the range of [0,99] by default, you could then indicate that the minumum and maximum values could be overridden by the user via command line switches like the following:

 java RandomNumGen -min 10 -max 20
 

This class makes this easy to do and lets you look to see if any command line switches have be specified by the user.

Version:

$Revision: 1.1.1.1 $

Author:

$Author: pkb $

See Also:

com.ccg.example.util.Random

Constructor Summary

CommandLine(String[] args)
Constructor for the class - sets the list of command line switches.

Method Summary

Object	get(Object key) Fetch the value associated with a "key" Try to lookup the Object which is associated with the key.
int	getIntOrDefault(String switchName, int defaultValue) Function to retrieve an integer value following a command line switch.
String	getString(Object key) Fetch a String "value" associated with a "key".
String	getStringAfter(int index) Get the String value of the argument after the specified index.
String	getStringOrDefault(String sw, String defValue) Returns command line argument following switch or default value.
char	getSwitchChar() Get the character used to specify command line arguments In order to differentiate a command line switch from a data or value, this function returns the character that is used to indicate a command line switch.
int	getSwitchPosition(String switchName) Locates the position of a specific command line switch.
boolean	isSwitchSet(String switchName) Determine if a boolean switch is present.
void	setSwitchChar(char val) Set the character used to specify command line arguments

Methods inherited from class java.lang.Object

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

Constructor Detail

CommandLine

public CommandLine(String[] args)

Constructor for the class - sets the list of command line switches. Constructor for the CommandLine class, performs the following tasks:

• Initializes the list of strings to be used as command line arguments.
• Initializes a corresponding array of booleans indicating that known of the arguments have been used yet.

Method Detail

get

public Object get(Object key)

Fetch the value associated with a "key" Try to lookup the Object which is associated with the key. This method should never throw an exception and is required so that the CommandLine class can be used as a standard Lookup object.

Specified by:

get in interface Lookup

Parameters:

key - Key to use to look up object with (if you pass null, you will get null back).

Returns:

Object found (if exists) or null if not found.

Since:

1.0

See Also:

Lookup

getString

public String getString(Object key)

Fetch a String "value" associated with a "key". Try to lookup the String object which is associated with the key. This method should never throw an exception and is required so that the CommandLine class can be used as a standard Lookup object.

Specified by:

getString in interface Lookup

Parameters:

key - Key to use to look up object with (if you pass null, you will get null back).

Returns:

Object found (if exists) returned as a String or null if not found.

Since:

1.0

See Also:

Lookup

setSwitchChar

public void setSwitchChar(char val)

Set the character used to specify command line arguments

Parameters:

val - New char value to assign.

See Also:

getSwitchChar()

getSwitchChar

public char getSwitchChar()

Get the character used to specify command line arguments In order to differentiate a command line switch from a data or value, this function returns the character that is used to indicate a command line switch. By default, this class will set it to the dash character '-' by default (you can change this via setSwitchChar(char), but this is seldom needed.

Returns:

The character used to recognize command line switches with (default is '-')

See Also:

setSwitchChar(char)

getSwitchPosition

public int getSwitchPosition(String switchName)

Locates the position of a specific command line switch. This routine is used to locate the position of a specific command line switch (if its present) in the list of tokens making up the command line. For example, if the command line contained the following words:

        -min 5 -max 12
 

Then invoking this function with "max" as the name of the switch to look for, this routine would return 2.

Parameters:

switchName - Name of the switch to look for in the array of arguments. NOTE: you MUST NOT include the "-" character in front of the switch name. For example, if you expect the user to specify something like "-quiet", then you would pass "quiet" as the parameter to this function.

Returns:

Position of the switch (where 0 corresponds to the first position - similar to an array), or -1 if the switch was not found.

See Also:

isSwitchSet(java.lang.String)

isSwitchSet

public boolean isSwitchSet(String switchName)

Determine if a boolean switch is present. This routine is handy when one needs to determine if a switch is present in the command line. It scans all of the command line arguments looking for a match. If the specified switch is found, then true is returned, otherwise false is returned.

Parameters:

switchName - Name of the switch to look for in the array of arguments. NOTE: you MUST NOT include the "-" character in front of the switch name. For example, if you expect the user to specify something like "-quiet", then you would pass "quiet" as the parameter to this function.

Returns:

ret-description

See Also:

Example Program

getStringAfter

public String getStringAfter(int index)

Get the String value of the argument after the specified index. Often after determining that a switch has been set on the command line, one may want to get the value of the string following the switch. This is a convience function to retrieve the string following a switch and returns null if it can't be satisfied. For example to see if the user specified a command line option like: -config FILE, the following code fragment would return null if the user didn't specify -config FILE on the command line (otherwise it will return the FILE name the user specified):

 String getConfigFileName(CommandLine cl) {
   return cl.getStringAfter(cl.getSwitchPosition("config"));
 }
 

Parameters:

index - Index into the array of arguments one prior to the entry you are interested in (typically the result of the getSwitchPosition() member). This must be in the range of [0,

Returns:

null if the index is out of range, otherwise, the string at [index+1]

See Also:

getSwitchPosition(java.lang.String)

getStringOrDefault

public String getStringOrDefault(String sw,
                                 String defValue)

Returns command line argument following switch or default value. This routine checks to see if the user has specified a command line switch, if so, it will return the argument following the switch, otherwise it will return the default value specified. For example, if one invoked a java program like: "java example -file myfile.txt", then invoking this command like: getStringOrDefault("file",null) would return "myfile.txt".

Parameters:

sw - Command line switch to look for.

default - Default value to return if user didn't specify a value for the command line switch (or omitted the command line switch from the command line).

Returns:

Value following command line switch

See Also:

isSwitchSet(java.lang.String)

getIntOrDefault

public int getIntOrDefault(String switchName,
                           int defaultValue)
                    throws NumberFormatException

Function to retrieve an integer value following a command line switch. This routine will attempt to parse an integer value following a specified command line switch if the user provides one. There are several things which can occur:

1. The user could have omitted the switch on the command line. In this case the default value passed will be returned.
2. The user could have specified the switch and followed by a valid integer. In this case the integer value specified by the user would be returned. Also, in this case the arguments will be marked as used (they will still be available).
3. The user could specify the switch, but not follow it with any value. In this case the default value is returned
4. The user could follow the command line switch with something that is not a valid integer. In this case a NumberFormatException will be thrown.

The following demonstrates how one could allow the user to specify -max VALUE on the command line:

 int getMax(CommandLine cl) {
   return cl.getIntOrDefault("max",100);
 }
 

Parameters:

switchName - Name of the command line switch which the integer value should follow.

defaultValue - Default value to return if the user did not specify a command line argument.

Returns:

The integer value of specified by the user following the specified switch, or the 'defaultValue'.

Throws:

NumberFormatException

See Also:

getStringAfter(int)