sandmark.util
Class Options

java.lang.Object
  |
  +--sandmark.util.Options

public class Options

extends java.lang.Object

The sandmark.util.Options class parses command-line options according to the Unix standard (POSIX .2 section 2.10.2) utility syntax guidelines. While the end-user sees behavior consistent with the C getopt() function, the programming interface is completely different.

Author:

Gregg Townsend, University of Arizona

Constructor Summary

Options(java.lang.String[] speclist)
Constructs an Options object for parsing an argument list.

Options(java.lang.String[] speclist, java.lang.String cmdname, java.lang.String[] arglist)
Constructs an Options object and parses a list of arguments.

Method Summary

int	getIndex() Returns the index of the first positional argument in the most recently parsed argument list.
java.lang.String	getValue(char c) Retrieves the value specified for the given option letter in the most recently parsed argument list.
java.lang.String	getWhich() Returns a string containing the option letters specified in the most recently parsed argument list.
static void	main(java.lang.String[] args) Tests the Options code.
int	parse(java.lang.String[] args) Parses an argument list and returns the index of the first non-option argument.
void	setFooter(java.lang.String s) Defines a footer string to be output at the end of any usage message, such as a copyright notice.
void	setHeader(java.lang.String s) Defines a header string to be output at the start of any usage message, such as a string announcing the full program name and version number.
void	usage(java.io.PrintStream p, java.lang.String cmdname) Synthesizes a usage message and writes it to the specified stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

Options

public Options(java.lang.String[] speclist,
               java.lang.String cmdname,
               java.lang.String[] arglist)

Constructs an Options object and parses a list of arguments. If a usage error is detected, the program is aborted with a message. After parsing, option values are found by calling getValue(char) and positional arguments are found by calling getIndex().

Parameters:

speclist - parameter specifications (see Options(String[]))

cmdname - command name, for usage message if needed

arglist - argument list (see parse(java.lang.String[]))

Options

public Options(java.lang.String[] speclist)

Constructs an Options object for parsing an argument list. The single argument is a list of strings, which are interpreted in pairs; thus the length of the argument array should be even. In each pair, the first string specifies argument and the second provides a very brief description for a usage message. There are three types of argument specifications.

A command option that does not take an argument is specified by a two-character string, a hyphen followed by the option letter (or, rarely, other character).

A command option that takes an argument is specified by a string consisting of:

• a hyphen followed by the option letter and a space
• a variable name characterizing the option value
• optionally, another space and a default value

A positional argument is specified by a variable name that does not begin with a hyphen. Positional arguments are used only for generating usage messages, and are not interpreted. All positional arguments must follow all command options.

Here is a somewhat contrived specification example:

  Options o = new Options(new String[] {
	"-d",		"delete afterwards",
	"-n nproc 1",	"use N parallel processes",	// 1 is default
	"-p",		"preserve dates and times",
	"-v",		"provide verbose commentary",
	"src",		"data source",
	"...",		"",
	"dst",		"destination",
  });
  

Method Detail

setHeader

public void setHeader(java.lang.String s)

Defines a header string to be output at the start of any usage message, such as a string announcing the full program name and version number.

See Also:

usage(java.io.PrintStream, java.lang.String)

setFooter

public void setFooter(java.lang.String s)

Defines a footer string to be output at the end of any usage message, such as a copyright notice.

See Also:

usage(java.io.PrintStream, java.lang.String)

usage

public void usage(java.io.PrintStream p,
                  java.lang.String cmdname)

Synthesizes a usage message and writes it to the specified stream. The usage message is composed of:

• a header, if one was set by setHeader(java.lang.String)
• "usage: cmdname [options] positionals"
• a list of options, omitting any having no description
• a footer, if one was set by setFooter(java.lang.String)

parse

public int parse(java.lang.String[] args)
          throws java.lang.Exception

Parses an argument list and returns the index of the first non-option argument. This is an argument that is not an option value, and that does not begin with "-", or is exactly "-", or follows "--".

After parsing, option values can be retrieved by calling getValue(char).

An Exception is thrown, with an explanatory message, if an invalid argument is found.

java.lang.Exception

getValue

public java.lang.String getValue(char c)

Retrieves the value specified for the given option letter in the most recently parsed argument list.

For an option that accepts an argument, the argument value is returned. If no value was specified, the default value is returned. If no default was specified, the null value is returned.

For an option that does not accept an argument, the empty string is returned if the option was invoked, and the null value is returned if not.

getIndex

public int getIndex()

Returns the index of the first positional argument in the most recently parsed argument list. This is an argument that is not an option value, and that does not begin with "-", or is exactly "-", or follows "--". If no argument list has been parsed, or if an error was detected, the return value is indeterminate.

getWhich

public java.lang.String getWhich()

Returns a string containing the option letters specified in the most recently parsed argument list. Letters appear in the order seen, and duplicates may be present. If no argument list has been parsed, or if an error was detected, the return value is indeterminate.

main

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

Tests the Options code. When run with arguments, parses them using a predefined options specification. When run with no arguments, executes a canned test set.