daikon.util
Class Options

Object
  Options

public class Options
extends Object

The Options class parses command-line options and sets fields in your program accordingly. Each field that is annotated with @Option is set from a command-line argument of the same name. The Options class can also create usage messages and HTML documentation. The Options class interprets annotations and Javadoc comments, so that you do not have to write duplicative, boilerplate code and documentation that could get out of sync with the rest of your program.

The main entry point is parse_or_usage(String[]). Typical use in your program is:

    public static void main(String[] args) {
      MyProgram myInstance = new MyProgram();
      Options options = new Options("MyProgram [options] infile outfile",
                                    myInstance, MyUtilityClass.class);
      // Sets fields in object myInstance, and sets static fields in
      // class MyUtilityClass.
      // Returns the original command line, with all options removed.
      String[] file_args = options.parse_or_usage (args);
      ...
 

The @Option annotation on a field specifies user documentation and, optionally, a one-character short name that users may supply on the command line. The long name is taken from the name of the variable; when the name contains an underscore, the user may substitute a hyphen on the command line instead.

On the command line, the values for options are specified in the form '--longname=value', '-shortname=value', '--longname value', or '-shortname value'. If use_single_dash(boolean) is true, then the long names take the form '-longname=value' or '-longname value'. The value is mandatory for all options except booleans. Booleans are set to true if no value is specified.

All arguments that start with '-' are processed as options. To terminate option processing at the first non-option argument, see parse_options_after_arg(boolean). Also, the special option '--' terminates option processing; all subsequent arguments are passed to the program (along with any preceding non-option arguments) without being scanned for options.

A user may provide an option multiple times on the command line. If the field is a list, each entry is be added to the list. If the field is not a list, then only the last occurrence is used (subsequent occurrences overwrite the previous value).

Unpublicized options

The @Unpublicized annotation causes an option not to be displayed in the usage message. This can be useful for options that are preliminary, experimental, or for internal purposes only. The @Unpublicized annotation must be specified in addition to the @Option annotation.

Option groups

The @OptionGroup annotation can be used to assign a name to a set of related options. This is useful for providing organization when working with many options. Options in the same group are displayed under the same heading in usage texts. Option groups themselves can be unpublicized causing the set of options belonging to the group to not be displayed in the default usage message.

The @OptionGroup annotation must be specified on a field in addition to an @Option annotation. The @OptionGroup annotation acts like a delimiter—all @Option-annotated fields up to the next @OptionGroup annotation belong to the same group. When using option groups, the first @Option-annotated field of every class and object passed to the Options(String, Object...) constructor must have an @OptionGroup annotation. Furthermore, the first parameter of an @OptionGroup annotation (the group name) must be unique among all classes and objects passed to the Options(String, Object...) constructor.

When an @Unpublicized annotation is used on a field that is in an unpublicized option group, that field is excluded in all usage messages, even when passing the group's name explicitly as a parameter to usage(String...).

Option aliases

The @Option annotation has an optional parameter aliases which accepts an array of strings. Each string in the array is an alias for the option being defined and can be used in place of an option's long name or short name. Aliases should start with a single dash or double dash. It is the user's responsibility to ensure that aliases does not cause ambiguity and do not collide with other options.

Note that parameters must be named when passing more than one parameter to an annotation, as in the following examples.

For option groups:

     @OptionGroup(value="Debugging Options", unpublicized=true)
 

For option aliases:

     @Option(value="-h Print the detailed help", aliases={"-help", "--help"})
 

Supported field types

The field may be of the following types:

• Primitive types: boolean, int, long, float, double. (Primitives can also be represented as wrappers (Boolean, Integer, Long, Float, Double). Use of a wrapper type allows the argument to have no default value.)
• Reference types that have a constructor with a single string parameter.
• java.util.regex.Pattern.
• Lists of any supported reference type. Lists must be initialized to a valid list (e.g., the empty list) before using Options on that list.

Example:

  public static class Test {

    @Option ("-o <filename> the output file ")
    public static File outfile = new File("/tmp/foobar");

    @Option ("-i ignore case")
    public static boolean ignore_case;

    @Option ("-t set the initial temperature")
    public static double temperature = 75.0;

    public static void main (String[] args) {
      Options options = new Options ("Test [options] files", new Test());
      String[] file_args = options.parse_or_usage (args);
    }
  }

For an example of this library being used in practice see Lookup.

Limitations

• Short options are only supported as separate entries (e.g., "-a -b") and not as a single group (e.g., "-ab").
• Not all primitive types are supported.
• Types without a string constructor are not supported.
• The "--no-long" option to turn off a boolean option named "long" is not supported; use "--long=false" instead.

Possible enhancements

• Positional arguments (non-options that must be provided in a given order) could be supported.

See Also:

Option, OptionGroup, Unpublicized

Nested Class Summary

static class

Options.ArgException Exceptions encountered during argument processing.

Field Summary

static boolean	split_lists
String	usage_synopsis Synopsis of usage.

Constructor Summary

Options(Object... args)
Prepare for option processing.

Options(String usage_synopsis, Object... args)
Prepare for option processing.

Method Summary

String	get_options_str() Returns a string containing all of the options that were set and their arguments.
void	ignore_options_after_arg(boolean val) Deprecated. Use parse_options_after_arg(boolean).
void	jdoc(RootDoc doc) Entry point for creating HTML documentation.
String[]	parse_and_usage(String args) Deprecated. Use parse_or_usage(String).
String[]	parse_and_usage(String[] args) Deprecated. Use parse_or_usage(String[]).
void	parse_options_after_arg(boolean val) If true, Options will parse arguments even after a non-option command-line argument.
String[]	parse_or_usage(String args) Parses a command line and sets the options accordingly.
String[]	parse_or_usage(String[] args) Parses a command line and sets the options accordingly.
String[]	parse(String args) Parses a command line and sets the options accordingly.
String[]	parse(String[] args) Parses a command line and sets the options accordingly.
void	print_usage() Prints, to standard output, usage information.
void	print_usage(PrintStream ps) Prints usage information.
void	print_usage(PrintStream ps, String msg) Prints a message followed by indented usage information.
void	print_usage(PrintStream ps, String format, Object... args) Prints a message followed by usage information.
void	print_usage(String msg) Prints, to standard output, a message followed by usage information.
void	print_usage(String format, Object... args) Prints, to standard output, a message followed by usage information.
String	settings() Returns a string containing the current setting for each option, in a format that can be parsed by Options.
String	toString() Returns a description of all of the known options.
String	usage(String... group_names) Returns the String containing the usage message for command-line options.
void	use_single_dash(boolean val) If true, long options (those derived from field names) will be parsed with a single dash prefix as in -longOption.

Methods inherited from class Object

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

Field Detail

split_lists

public static boolean split_lists

usage_synopsis

public String usage_synopsis

Synopsis of usage. Example: "prog [options] arg1 arg2 ..."

This variable is public so that clients can reset it (useful for masquerading as another program, based on parsed options).

Constructor Detail

Options

public Options(Object... args)

Prepare for option processing. Creates an object that will set fields in all the given arguments. An argument to this method may be a Class, in which case its static fields are set. The names of all the options (that is, the fields annotated with @Option) must be unique across all the arguments.

Options

public Options(String usage_synopsis,
               Object... args)

Prepare for option processing. Creates an object that will set fields in all the given arguments. An argument to this method may be a Class, in which case its static fields are set. The names of all the options (that is, the fields annotated with @Option) must be unique across all the arguments.

Parameters:

usage_synopsis - A synopsis of how to call your program

Method Detail

parse_options_after_arg

public void parse_options_after_arg(boolean val)

If true, Options will parse arguments even after a non-option command-line argument. Setting this to true is useful to permit users to write options at the end of a command line. Setting this to false is useful to avoid processing arguments that are actually options/arguments for another program that this one will invoke.

ignore_options_after_arg

@Deprecated
public void ignore_options_after_arg(boolean val)

Deprecated. Use parse_options_after_arg(boolean).

use_single_dash

public void use_single_dash(boolean val)

If true, long options (those derived from field names) will be parsed with a single dash prefix as in -longOption. The default is false and long options will be parsed with a double dash prefix as in --longOption.

parse

public String[] parse(String[] args)
               throws Options.ArgException

Parses a command line and sets the options accordingly.

Returns:

all non-option arguments

Throws:

Options.ArgException - if the command line contains unknown option or misused options.

parse

public String[] parse(String args)
               throws Options.ArgException

Parses a command line and sets the options accordingly. This method splits the argument string into command line arguments, respecting single and double quotes, then calls parse(String[]).

Returns:

all non-option arguments

Throws:

Options.ArgException - if the command line contains unknown option or misused options.

See Also:

parse(String[])

parse_or_usage

public String[] parse_or_usage(String[] args)

Parses a command line and sets the options accordingly. If an error occurs, prints the usage and terminates the program. The program is terminated rather than throwing an error to create cleaner output.

Returns:

all non-option arguments

See Also:

parse(String[])

parse_or_usage

public String[] parse_or_usage(String args)

Parses a command line and sets the options accordingly. If an error occurs, prints the usage and terminates the program. The program is terminated rather than throwing an error to create cleaner output. This method splits the argument string into command line arguments, respecting single and double quotes, then calls parse_or_usage(String[]).

Returns:

all non-option arguments

See Also:

parse_or_usage(String[])

parse_and_usage

@Deprecated
public String[] parse_and_usage(String[] args)

Deprecated. Use parse_or_usage(String[]).

parse_and_usage

@Deprecated
public String[] parse_and_usage(String args)

Deprecated. Use parse_or_usage(String).

print_usage

public void print_usage(PrintStream ps)

Prints usage information. Uses the usage synopsis passed into the constructor, if any.

print_usage

public void print_usage()

Prints, to standard output, usage information.

print_usage

public void print_usage(PrintStream ps,
                        String msg)

Prints a message followed by indented usage information. The message is printed in addition to (not replacing) the usage synopsis.

print_usage

public void print_usage(String msg)

Prints, to standard output, a message followed by usage information. The message is printed in addition to (not replacing) the usage synopsis.

print_usage

public void print_usage(PrintStream ps,
                        String format,
                        Object... args)

Prints a message followed by usage information. The message is printed in addition to (not replacing) the usage synopsis.

print_usage

public void print_usage(String format,
                        Object... args)

Prints, to standard output, a message followed by usage information. The message is printed in addition to (not replacing) the usage synopsis.

usage

public String usage(String... group_names)

Returns the String containing the usage message for command-line options.

Parameters:

group_names - The list of option groups to include in the usage message. If empty, will return usage for all option groups which are not unpublicized. Or if option groups are not being used, will return usage for all options which are not unpublicized.

jdoc

public void jdoc(RootDoc doc)

Entry point for creating HTML documentation. HTML documentation includes unpublicized option groups but not @Unpublicized options.

get_options_str

public String get_options_str()

Returns a string containing all of the options that were set and their arguments. This is essentially the contents of args[] with all non-options removed.

See Also:

settings()

settings

public String settings()

Returns a string containing the current setting for each option, in a format that can be parsed by Options. This differs from get_options_str() in that it contains each known option exactly once: it never contains duplicates, and it contains every known option even if the option was not specified on the command line.

toString

public String toString()

Returns a description of all of the known options. Each option is described on its own line in the output.

Overrides:

toString in class Object