utilMDE
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 instance, 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, users 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'. 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.

An option may be specified multiple times. 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).

The field may be of the following types:

• Primitive types: boolean, int, and double. (Primitives can also be represented as wrappers (Boolean, Integer, 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 = "/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);
    }
  }

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.
• Non-option information could be supported in the same manner as options which would be cleaner than simply returning all of the non-options as an array.
• The "--no-long" option to turn off a boolean option named "long" is not supported; use "--long=false" instead.

See Also:

Option

Nested Class Summary

static class

Options.ArgException Exceptions encountered during argument processing.

Field Summary

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.
void	set_arg(Options.OptionInfo oi, String arg_name, String arg_value) Set the specified option to the value specified in arg_value.
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() Returns an array of Strings, where each String describes the usage of one command-line option.

Methods inherited from class Object

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

Field Detail

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).

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()

Returns an array of Strings, where each String describes the usage of one command-line option. Does not include the usage synopsis.

set_arg

public void set_arg(Options.OptionInfo oi,
                    String arg_name,
                    String arg_value)
             throws Options.ArgException

Set the specified option to the value specified in arg_value. Throws an ArgException if there are any errors.

Throws:

Options.ArgException

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

jdoc

public void jdoc(RootDoc doc)

Entry point for creating HTML documentation.