com.syncbuilder.util.getopt
Class Getopt

java.lang.Object
  |
  +--com.syncbuilder.util.getopt.Getopt

public class Getopt

extends java.lang.Object

A special version of the GNU getopt for usage with the SyncBuilder framework.

See Also:

LongOpt

Field Summary

protected java.lang.String[]	argv Saved argument list passed to the program
protected int	first_nonopt The index of the first non-option in argv[]
protected int	last_nonopt The index of the last non-option in argv[]
protected boolean	long_only This flag determines whether or not we are parsing only long args
protected LongOpt[]	long_options This is an array of LongOpt objects which describ the valid long options.
protected int	longind Stores the index into the long_options array of the long option found
protected boolean	longopt_handled A flag which communicates whether or not checkLongOption() did all necessary processing for the current option
protected java.lang.String	nextchar The next char to be scanned in the option-element in which the last option character we returned was found.
protected java.lang.String	optarg For communication from `getopt' to the caller.
protected boolean	opterr Callers store false here to inhibit the error message for unrecognized options.
protected int	optind Index in ARGV of the next element to be scanned.
protected int	optopt When an unrecognized option is encountered, getopt will return a '?'
protected java.lang.String	optstring This is the string describing the valid short options.
protected int	ordering Determines whether we permute arguments or not
protected static int	PERMUTE PERMUTE is the default.
protected boolean	posixly_correct The flag determines whether or not we operate in strict POSIX compliance
protected java.lang.String	progname Name to print as the program name in error messages.
protected static int	REQUIRE_ORDER Describe how to deal with options that follow non-option ARGV-elements.
protected static int	RETURN_IN_ORDER RETURN_IN_ORDER is an option available to programs that were written to expect options and other ARGV-elements in any order and that care about the ordering of the two.

Constructor Summary

Getopt(java.lang.String progname, java.lang.String[] argv, java.lang.String optstring)
Construct a basic Getopt instance with the given input data.

Getopt(java.lang.String progname, java.lang.String[] argv, java.lang.String optstring, LongOpt[] long_options)
Construct a Getopt instance with given input data that is capable of parsing long options as well as short.

Getopt(java.lang.String progname, java.lang.String[] argv, java.lang.String optstring, LongOpt[] long_options, boolean long_only)
Construct a Getopt instance with given input data that is capable of parsing long options and short options.

Method Summary

protected int	checkLongOption() Check to see if an option is a valid long option.
protected void	exchange(java.lang.String[] argv) Exchange the shorter segment with the far end of the longer segment.
int	getLongind() Returns the index into the array of long options (NOT argv) representing the long option that was found.
int	getopt() This method returns a char that is the current option that has been parsed from the command line.
java.lang.String	getOptarg() For communication from `getopt' to the caller.
int	getOptind() optind it the index in ARGV of the next element to be scanned.
int	getOptopt() When getopt() encounters an invalid option, it stores the value of that option in optopt which can be retrieved with this method.
void	setArgv(java.lang.String[] argv) Since in GNU getopt() the argument vector is passed back in to the function every time, the caller can swap out argv on the fly.
void	setOpterr(boolean opterr) Normally Getopt will print a message to the standard error when an invalid option is encountered.
void	setOptind(int optind) This method allows the optind index to be set manually.
void	setOptstring(java.lang.String optstring) In GNU getopt, it is possible to change the string containg valid options on the fly because it is passed as an argument to getopt() each time.

Methods inherited from class java.lang.Object

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

Field Detail

REQUIRE_ORDER

protected static final int REQUIRE_ORDER

Describe how to deal with options that follow non-option ARGV-elements. If the caller did not specify anything, the default is REQUIRE_ORDER if the property gnu.posixly_correct is defined, PERMUTE otherwise. The special argument `--' forces an end of option-scanning regardless of the value of `ordering'. In the case of RETURN_IN_ORDER, only `--' can cause `getopt' to return -1 with `optind' != ARGC. REQUIRE_ORDER means don't recognize them as options; stop option processing when the first non-option is seen. This is what Unix does. This mode of operation is selected by either setting the property gnu.posixly_correct, or using `+' as the first character of the list of option characters.

PERMUTE

protected static final int PERMUTE

PERMUTE is the default. We permute the contents of ARGV as we scan, so that eventually all the non-options are at the end. This allows options to be given in any order, even with programs that were not written to expect this.

RETURN_IN_ORDER

protected static final int RETURN_IN_ORDER

RETURN_IN_ORDER is an option available to programs that were written to expect options and other ARGV-elements in any order and that care about the ordering of the two. We describe each non-option ARGV-element as if it were the argument of an option with character code 1. Using `-' as the first character of the list of option characters selects this mode of operation.

optarg

protected java.lang.String optarg

For communication from `getopt' to the caller. When `getopt' finds an option that takes an argument, the argument value is returned here. Also, when `ordering' is RETURN_IN_ORDER, each non-option ARGV-element is returned here.

optind

protected int optind

Index in ARGV of the next element to be scanned. This is used for communication to and from the caller and for communication between successive calls to `getopt'. On entry to `getopt', zero means this is the first call; initialize. When `getopt' returns -1, this is the index of the first of the non-option elements that the caller should itself scan. Otherwise, `optind' communicates from one call to the next how much of ARGV has been scanned so far.

opterr

protected boolean opterr

Callers store false here to inhibit the error message for unrecognized options.

optopt

protected int optopt

When an unrecognized option is encountered, getopt will return a '?' and store the value of the invalid option here.

nextchar

protected java.lang.String nextchar

The next char to be scanned in the option-element in which the last option character we returned was found. This allows us to pick up the scan where we left off. If this is zero, or a null string, it means resume the scan by advancing to the next ARGV-element.

optstring

protected java.lang.String optstring

This is the string describing the valid short options.

long_options

protected LongOpt[] long_options

This is an array of LongOpt objects which describ the valid long options.

long_only

protected boolean long_only

This flag determines whether or not we are parsing only long args

longind

protected int longind

Stores the index into the long_options array of the long option found

posixly_correct

protected boolean posixly_correct

The flag determines whether or not we operate in strict POSIX compliance

longopt_handled

protected boolean longopt_handled

A flag which communicates whether or not checkLongOption() did all necessary processing for the current option

first_nonopt

protected int first_nonopt

The index of the first non-option in argv[]

last_nonopt

protected int last_nonopt

The index of the last non-option in argv[]

argv

protected java.lang.String[] argv

Saved argument list passed to the program

ordering

protected int ordering

Determines whether we permute arguments or not

progname

protected java.lang.String progname

Name to print as the program name in error messages. This is necessary since Java does not place the program name in argv[0]

Constructor Detail

Getopt

public Getopt(java.lang.String progname,
              java.lang.String[] argv,
              java.lang.String optstring)

Construct a basic Getopt instance with the given input data. Note that this handles "short" options only.

Parameters:

progname - The name to display as the program name when printing errors

argv - The String array passed as the command line to the program.

optstring - A String containing a description of the valid args for this program

Getopt

public Getopt(java.lang.String progname,
              java.lang.String[] argv,
              java.lang.String optstring,
              LongOpt[] long_options)

Construct a Getopt instance with given input data that is capable of parsing long options as well as short.

Parameters:

progname - The name to display as the program name when printing errors

argv - The String array passed as the command ilne to the program

optstring - A String containing a description of the valid short args for this program

long_options - An array of LongOpt objects that describes the valid long args for this program

Getopt

public Getopt(java.lang.String progname,
              java.lang.String[] argv,
              java.lang.String optstring,
              LongOpt[] long_options,
              boolean long_only)

Construct a Getopt instance with given input data that is capable of parsing long options and short options. Contrary to what you might think, the flag 'long_only' does not determine whether or not we scan for only long arguments. Instead, a value of true here allows long arguments to start with a '-' instead of '--' unless there is a conflict with a short option name.

Parameters:

progname - The name to display as the program name when printing errors

argv - The String array passed as the command ilne to the program

optstring - A String containing a description of the valid short args for this program

long_options - An array of LongOpt objects that describes the valid long args for this program

long_only - true if long options that do not conflict with short options can start with a '-' as well as '--'

Method Detail

setOptstring

public void setOptstring(java.lang.String optstring)

In GNU getopt, it is possible to change the string containg valid options on the fly because it is passed as an argument to getopt() each time. In this version we do not pass the string on every call. In order to allow dynamic option string changing, this method is provided.

Parameters:

optstring - The new option string to use

getOptind

public int getOptind()

optind it the index in ARGV of the next element to be scanned. This is used for communication to and from the caller and for communication between successive calls to `getopt'. When `getopt' returns -1, this is the index of the first of the non-option elements that the caller should itself scan. Otherwise, `optind' communicates from one call to the next how much of ARGV has been scanned so far.

setOptind

public void setOptind(int optind)

This method allows the optind index to be set manually. Normally this is not necessary (and incorrect usage of this method can lead to serious lossage), but optind is a public symbol in GNU getopt, so this method was added to allow it to be modified by the caller if desired.

Parameters:

optind - The new value of optind

setArgv

public void setArgv(java.lang.String[] argv)

Since in GNU getopt() the argument vector is passed back in to the function every time, the caller can swap out argv on the fly. Since passing argv is not required in the Java version, this method allows the user to override argv. Note that incorrect use of this method can lead to serious lossage.

Parameters:

argv - New argument list

getOptarg

public java.lang.String getOptarg()

For communication from `getopt' to the caller. When `getopt' finds an option that takes an argument, the argument value is returned here. Also, when `ordering' is RETURN_IN_ORDER, each non-option ARGV-element is returned here. No set method is provided because setting this variable has no effect.

setOpterr

public void setOpterr(boolean opterr)

Normally Getopt will print a message to the standard error when an invalid option is encountered. This can be suppressed (or re-enabled) by calling this method. There is no get method for this variable because if you can't remember the state you set this to, why should I?

getOptopt

public int getOptopt()

When getopt() encounters an invalid option, it stores the value of that option in optopt which can be retrieved with this method. There is no corresponding set method because setting this variable has no effect.

getLongind

public int getLongind()

Returns the index into the array of long options (NOT argv) representing the long option that was found.

exchange

protected void exchange(java.lang.String[] argv)

Exchange the shorter segment with the far end of the longer segment. That puts the shorter segment into the right place. It leaves the longer segment in the right place overall, but it consists of two parts that need to be swapped next. This method is used by getopt() for argument permutation.

checkLongOption

protected int checkLongOption()

Check to see if an option is a valid long option. Called by getopt(). Put in a separate method because this needs to be done twice. (The C getopt authors just copy-pasted the code!).

Parameters:

longind - A buffer in which to store the 'val' field of found LongOpt

Returns:

Various things depending on circumstances

getopt

public int getopt()

This method returns a char that is the current option that has been parsed from the command line. If the option takes an argument, then the internal variable 'optarg' is set which is a String representing the the value of the argument. This value can be retrieved by the caller using the getOptarg() method. If an invalid option is found, an error message is printed and a '?' is returned. The name of the invalid option character can be retrieved by calling the getOptopt() method. When there are no more options to be scanned, this method returns -1. The index of first non-option element in argv can be retrieved with the getOptind() method.

Returns:

Various things as described above