smithers.util
Class GetOpt

java.lang.Object
  extended by smithers.util.GetOpt

public class GetOpt
extends java.lang.Object

Class to parse command-line arguments. This is intended as a Java replacement to POSIX's getopt() with several extensions. The valid options are specified in a String parameter defined below. The valid options may be altered at any time during parsing using the methods setOptions() and addOptions(). This class allows both short options (such as -x) and long options (such as --ecks). In both cases an option may take no argument or an optional or required option-argument. The author apologises for the length of some of the following sentences, but is making no effort to improve them.
A program argument with a single leading hyphen ('-') consists of one or more short options. If an option takes an option-argument, then the remainder of the argument, if non-empty, is the option-argument. If the remainder of the argument is empty and an option-argument is required, then the next argument is the option-argument, otherwise there is no option-argument.
A program argument with two leading hyphens is a long option. If the argument contains an equals sign ('='), then the portion of the argument between the second hyphen and the equals sign (exclusive) is the option, which must take an (optional or required) option-argument, and the remainder of the argument after the equals sign is the option-argument. If the argument does not contain an equals sign, the whole argument after the second hyphen is the option and there is no option-argument unless the option requires one, in which case the next argument is the option-argument.
An argument which which begins with a non-hyphen is taken as an operand, as is an argument which is literally "-". If an argument is equal to "--", it is neither an option nor an operand, but all arguments after it are interpreted as operands, even if they have leading hyphens.

Option strings

The option string passed to this class (any parameter with the name optionString is interpreted as a sequence of option specifications, optionally separated by spaces. The space separation is needed in some cases to prevent ambiguity (most commonly, after a long option which takes no arguments). An option specification consists of an option name specification followed by an option-argument specification. The option-argument specification consists of a colon ':' to indicate a required argument, a question-mark '?' for an optional argument or else is empty if no option-argument is allowed. The option name specification is either a short option name specification or a long option name specification. A short option name specification consists of a single character (other than ' ' or '-', which is the name of the option. A long option name specification consists of a hyphen, then optionally another hyphen and a single character (the short equivalent name), then the name of the option - a sequence of one or more characters other than space, colon or question-mark. A long option with a short equivalent name is reported to the application as if it where the corresponding short option. Note that the short equivalent option need not be a valid short option - in this case when this class reports such a short option the application knows that it must actually have received the long option.


Field Summary
 java.lang.String option
          The last option read.
 java.lang.String optionArg
          The argument to the option, or null.
 int optionIndex
          The index of the next program argument to parse.
 
Constructor Summary
GetOpt()
          Constructs a new GetOpt object which accepts no arguments.
GetOpt(java.lang.String optionString)
          Constructs a new GetOpt object with the given option string.
 
Method Summary
 void addOptions(java.lang.String optionString)
          Add new options to those that can be read by this object.
 int getOpt(java.lang.String[] args)
          Parse the next option from the arguments.
 void removeOptions(java.lang.String optionString)
          Remove some of the options that can be read by this object.
 void setOptions(java.lang.String optionString)
          Sets the options that this object allows.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

option

public java.lang.String option
The last option read.


optionArg

public java.lang.String optionArg
The argument to the option, or null.


optionIndex

public int optionIndex
The index of the next program argument to parse.

Constructor Detail

GetOpt

public GetOpt()
Constructs a new GetOpt object which accepts no arguments.


GetOpt

public GetOpt(java.lang.String optionString)
Constructs a new GetOpt object with the given option string. Using this constructor is equivalent to using the no-argument constructor and then calling addOptions(optionString) on the newly constructed object.

Parameters:
optionString - the valid options, as described in the class summary
Method Detail

setOptions

public void setOptions(java.lang.String optionString)
Sets the options that this object allows.

Parameters:
optionString - the valid options, as described in the class summary

addOptions

public void addOptions(java.lang.String optionString)
Add new options to those that can be read by this object.

Parameters:
optionString - the valid options, as described in the class summary

removeOptions

public void removeOptions(java.lang.String optionString)
Remove some of the options that can be read by this object. The option-argument specifications need not match those originally supplied, the same applies to the short-equivalent names of long options. It is also not an error if the option to be removed does not exist. Thus calling setOptions("ab?c:d?h--hhelp") followed by removeOptions("bcd:-help?") will result in the same state as a calling setOptions("ah").

Parameters:
optionString - the options to remove

getOpt

public int getOpt(java.lang.String[] args)
Parse the next option from the arguments.
If a short option was read, returns the option name. If a long option was read, returns the short equivalent name, if any, or else '-'. If an option was read which but an option-argument was required but missing or illegal but given, returns ':'. If an invalid option was read, returns '?'. If the end of options was reached, returns -1.

Parameters:
args - the program arguments, as passed to Main()
Returns:
the short option read, or one of '-',':','?',-1 as described above
Throws:
java.lang.RuntimeException - if an error occurs due to the application altering optionIndex or supplying a different args parameter during the parsing of a group of short options