plume

Class Options

java.lang.Object

plume.Options

Deprecated.

Use org.plumelib.options.Options

@Deprecated
public class Options
extends java.lang.Object

The Options class:

• parses command-line options and sets fields in your program accordingly,
• creates usage messages (such as printed by a --help option), and
• creates documentation suitable for a manual or manpage.

Thus, the programmer is freed from writing duplicative, boilerplate code and documentation that could get out of sync with the rest of the program.

The programmer does not have to write any code, only declare and document variables. For each field that you want to set from a command-line argument, you write Javadoc and an @Option annotation. Then, the field is automatically set from a command-line option of the same name, and usage messages and printed documentation are generated automatically.

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

 import plume.*;

 public class MyProgram {

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

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

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

   public static void main(String[] args) {
     MyProgram myInstance = new MyProgram();
     Options options = new Options("MyProgram [options] infile outfile",
                                   myInstance, MyUtilityClass.class);
     String[] remaining_args = options.parse_or_usage(args);
     ...
   }
 }
 

A user may invoke the program using the command-line arguments -o, --outfile, -i, --ignore-case, and --temperature.

The call to parse_or_usage(java.lang.String[]) sets fields in object myInstance, and sets static fields in class MyUtilityClass. It returns the original command line, with all options removed.

@Option indicates a command-line option

The @Option annotation on a field specifies brief 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; for example, the --multi-word-variable command-line option would set the variable multi_word_variable.

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; method parse_or_usage returns all subsequent arguments (along with any preceding non-option arguments) without scanning them for options.

A user may provide an option multiple times on the command line. If the field is a list, each entry is 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.

There are forms of the usage-message methods that can include even unpublicized options; for example, see usage(boolean,String...).

Option groups

The @OptionGroup annotation can be used to assign a name to a set of related options. This is useful for organizing a list of options. Options in the same group are displayed under the same heading in usage texts.

The @OptionGroup annotation must be specified on a field in addition to an @Option annotation. Note that, due to a deficiency in Javadoc, an @OptionGroup annotation must appear underneath any Javadoc comment for the field it applies to.

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.

If an option group itself is unpublicized:

• The default usage message omits the group and all options belonging to it.
• An unpublicized option group (that has any publicized options) is included in documentation for a manual.
• A field with an @Unpublicized annotation is excluded even when passing the group's name explicitly as a parameter to usage(String...).

If an option group is not unpublicized but contains only unpublicized options, it will not be included in the default usage message.

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. For example:

     // The user may supply --help, -h, or -help, all of which mean the same thing and set this variable
     @Option(value="-h Print a help message", aliases={"-help"})
     public static boolean help;

Aliases should start with a single dash or double dash. If there is only a single, one-character alias, it can be put at the beginning of the value field without the need for an aliases field. It is the user's responsibility to ensure that no alias is the same as other options or aliases and that they can be parsed unambiguously.

Generating documentation for a manual or manpage

The class Javadoc for a class that has a main method should generally contain a summary of all command-line options. Such a summary can also be useful in other circumstances. See the OptionsDoclet class for instructions about generating HTML documentation.

Supported field types

A field with an @Option annotation may be of the following types:

• Primitive types: boolean, int, long, float, double.
• Primitive type 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.
• enums.
• Lists of any of the above reference types.

More examples

Example clients of the Options library include Lookup, Randoop, and Javarifier, among many others.

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 constructor that takes a single String argument 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, OptionsDoclet

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Options.ArgException Deprecated. Indicates an exception encountered during argument processing.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	split_lists Deprecated. When true, an argument to a option of list type is split, on whitespace, into multiple arguments each of which is added to the list.
java.lang.String	usage_synopsis Deprecated. Synopsis of usage.

Constructor Summary

Constructors

Constructor and Description
Options(java.lang.Object... args) Deprecated. Prepare for option processing.
Options(java.lang.String usage_synopsis, java.lang.Object... args) Deprecated. Prepare for option processing.

Method Summary

Modifier and Type	Method and Description
void	enableDebugLogging(boolean enabled) Deprecated. Enable or disable debug logging.
java.lang.String	get_options_str() Deprecated. Returns a string containing all of the options that were set and their arguments.
void	parse_options_after_arg(boolean val) Deprecated. If true, Options will parse arguments even after a non-option command-line argument.
java.lang.String[]	parse_or_message(java.lang.String message, java.lang.String args) Deprecated. Parses a command line and sets the options accordingly.
java.lang.String[]	parse_or_message(java.lang.String message, java.lang.String[] args) Deprecated. Parses a command line and sets the options accordingly.
java.lang.String[]	parse_or_usage(java.lang.String args) Deprecated. Parses a command line and sets the options accordingly.
java.lang.String[]	parse_or_usage(java.lang.String[] args) Deprecated. Parses a command line and sets the options accordingly.
java.lang.String[]	parse(java.lang.String args) Deprecated. Parses a command line and sets the options accordingly.
java.lang.String[]	parse(java.lang.String[] args) Deprecated. Parses a command line and sets the options accordingly.
void	print_usage() Deprecated. Prints, to standard output, usage information.
void	print_usage(java.io.PrintStream ps) Deprecated. Prints usage information.
void	print_usage(java.io.PrintStream ps, java.lang.String msg) Deprecated. Prints a message followed by indented usage information.
void	print_usage(java.io.PrintStream ps, java.lang.String format, java.lang.Object... args) Deprecated. Prints a message followed by usage information.
void	print_usage(java.lang.String msg) Deprecated. Prints, to standard output, a message followed by usage information.
void	print_usage(java.lang.String format, java.lang.Object... args) Deprecated. Prints, to standard output, a message followed by usage information.
java.lang.String	settings() Deprecated. Returns a string containing the current setting for each option, in a format that can be parsed by Options.
java.lang.String	settings(boolean include_unpublicized) Deprecated. Returns a string containing the current setting for each option, in a format that can be parsed by Options.
java.lang.String	toString() Deprecated. Return a description of all of the known options.
java.lang.String	usage(boolean include_unpublicized, java.lang.String... group_names) Deprecated. Returns the String containing the usage message for command-line options.
java.lang.String	usage(java.lang.String... group_names) Deprecated. Return the String containing the usage message for command-line options.
void	use_single_dash(boolean val) Deprecated. If true, long options (those derived from field names) will be parsed with a single dash prefix as in -longOption.

Methods inherited from class java.lang.Object

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

Field Detail

split_lists

public static boolean split_lists

Deprecated.

When true, an argument to a option of list type is split, on whitespace, into multiple arguments each of which is added to the list. When false, each argument to an option of list type is treated as a single element, no matter what characters it contains.

usage_synopsis

public java.lang.String usage_synopsis

Deprecated.

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(java.lang.Object... args)

Deprecated.

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:

args - the classes whose options to process

Options

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

Deprecated.

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 it must be fully initalized and 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

args - the classes whose options to process

Method Detail

enableDebugLogging

public void enableDebugLogging(boolean enabled)

Deprecated.

Enable or disable debug logging.

Parameters:

enabled - whether to enable or disable logging

parse_options_after_arg

public void parse_options_after_arg(boolean val)

Deprecated.

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.

Parameters:

val - whether to parse arguments after a non-option command-line argument

use_single_dash

public void use_single_dash(boolean val)

Deprecated.

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.

Parameters:

val - whether to parse long options with a single dash, as in -longOption

parse

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

Deprecated.

Parses a command line and sets the options accordingly.

Parameters:

args - the commandline to be parsed

Returns:

all non-option arguments

Throws:

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

parse

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

Deprecated.

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

You should usually call parse(String[]) instead of this method. This method is only appropriate when the String[] version of the arguments is not available — for example, for the premain method of a Java agent.

Parameters:

args - the command line to parse

Returns:

all non-option arguments

Throws:

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

See Also:

parse(String[])

parse_or_message

public java.lang.String[] parse_or_message(java.lang.String message,
                                           java.lang.String[] args)

Deprecated.

Parses a command line and sets the options accordingly. Returns non-option arguments.

If an error occurs, prints the exception's message, prints the given message, and then terminates the program. The program is terminated rather than throwing an error to create cleaner output.

Parameters:

message - a message to print, such as "Pass --help for a list of all command-line arguments."

args - the command line to parse

Returns:

all non-option arguments

See Also:

parse(String[])

parse_or_message

public java.lang.String[] parse_or_message(java.lang.String message,
                                           java.lang.String args)

Deprecated.

Parses a command line and sets the options accordingly. Returns non-option arguments.

If an error occurs, prints the exception's message, prints the given message, and then 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_message(String, String[]).

You should usually call parse_or_message(String, String[]) instead of this method. This method is only appropriate when the String[] version of the arguments is not available — for example, for the premain method of a Java agent.

Parameters:

message - a message to print, such as "Pass --help for a list of all command-line arguments."

args - the command line to parse

Returns:

all non-option arguments

See Also:

parse_or_message(String, String[])

parse_or_usage

public java.lang.String[] parse_or_usage(java.lang.String[] args)

Deprecated.

Parses a command line and sets the options accordingly. Returns non-option arguments.

If an error occurs, prints the exception's message, prints usage inoframtion, and then terminates the program. The program is terminated rather than throwing an error to create cleaner output.

Parameters:

args - the command line to parse

Returns:

all non-option arguments

See Also:

parse(String[])

parse_or_usage

public java.lang.String[] parse_or_usage(java.lang.String args)

Deprecated.

Parses a command line and sets the options accordingly. Returns non-option arguments.

If an error occurs, prints the exception's message, calls print_usage, and then 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[]).

You should usually call parse_or_usage(String[]) instead of this method. This method is only appropriate when the String[] version of the arguments is not available — for example, for the premain method of a Java agent.

Parameters:

args - the command line to parse

Returns:

all non-option arguments

See Also:

parse_or_usage(String[])

print_usage

public void print_usage(java.io.PrintStream ps)

Deprecated.

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

Parameters:

ps - where to print usage information

print_usage

public void print_usage()

Deprecated.

Prints, to standard output, usage information.

print_usage

public void print_usage(java.io.PrintStream ps,
                        java.lang.String msg)

Deprecated.

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

Parameters:

ps - where to print usage information

msg - message to print before usage information

print_usage

public void print_usage(java.lang.String msg)

Deprecated.

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

Parameters:

msg - message to print before usage information

print_usage

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

Deprecated.

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

Parameters:

ps - where to print usage information

format - message to print before usage information

args - objects to put in formatted message

print_usage

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

Deprecated.

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

Parameters:

format - message to print before usage information

args - objects to put in formatted message

usage

public java.lang.String usage(java.lang.String... group_names)

Deprecated.

Return 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 and option groups are being used, will return usage for all option groups that are not unpublicized. If empty and option groups are not being used, will return usage for all options that are not unpublicized.

Returns:

the command-line usage message

usage

public java.lang.String usage(boolean include_unpublicized,
                              java.lang.String... group_names)

Deprecated.

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

Parameters:

include_unpublicized - if true, treat all unpublicized options and option groups as publicized

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

Returns:

the command-line usage message

get_options_str

public java.lang.String get_options_str()

Deprecated.

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.

Returns:

options, similarly to supplied on the command line

See Also:

settings()

settings

public java.lang.String settings()

Deprecated.

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.

Returns:

options, similarly to supplied on the command line

settings

public java.lang.String settings(boolean include_unpublicized)

Deprecated.

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.

Parameters:

include_unpublicized - if true, treat all unpublicized options and option groups as publicized

Returns:

options, similarly to supplied on the command line

toString

public java.lang.String toString()

Deprecated.

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

Overrides:

toString in class java.lang.Object

Returns:

a description of all of the known options