com.google.devtools.common.options

Class OptionsParser

java.lang.Object

com.google.devtools.common.options.OptionsParser

All Implemented Interfaces:

OptionsClassProvider, OptionsProvider

public class OptionsParser
extends java.lang.Object
implements OptionsProvider

A parser for options. Typical use case in a main method:

 OptionsParser parser = OptionsParser.newOptionsParser(FooOptions.class, BarOptions.class);
 parser.parseAndExitUponError(args);
 FooOptions foo = parser.getOptions(FooOptions.class);
 BarOptions bar = parser.getOptions(BarOptions.class);
 List<String> otherArguments = parser.getResidue();
 

FooOptions and BarOptions would be options specification classes, derived from OptionsBase, that contain fields annotated with @Option(...).

Alternatively, rather than calling parseAndExitUponError(OptionPriority, String, String[]), client code may call parse(OptionPriority,String,List), and handle parser exceptions usage messages themselves.

This options parsing implementation has (at least) one design flaw. It allows both '--foo=baz' and '--foo baz' for all options except void, boolean and tristate options. For these, the 'baz' in '--foo baz' is not treated as a parameter to the option, making it is impossible to switch options between void/boolean/tristate and everything else without breaking backwards compatibility.

See Also:

a simpler class which you can use if you only have one options specification class

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	OptionsParser.HelpVerbosity The verbosity with which option help messages are displayed: short (just the name), medium (name, type, default, abbreviation), and long (full description).
static class	OptionsParser.OptionDescription The metadata about an option.
static class	OptionsParser.OptionValueDescription The name and value of an option with additional metadata describing its priority, source, whether it was set via an implicit dependency, and if so, by which other option.
static class	OptionsParser.UnparsedOptionValueDescription The name and unparsed value of an option with additional metadata describing its priority, source, whether it was set via an implicit dependency, and if so, by which other option.

Field Summary

Fields inherited from interface com.google.devtools.common.options.OptionsClassProvider

EMPTY

Method Summary

Modifier and Type	Method and Description
java.util.List<OptionsParser.OptionValueDescription>	asListOfEffectiveOptions() Returns a list of all options, including undocumented ones, and their effective values.
java.util.List<OptionsParser.UnparsedOptionValueDescription>	asListOfExplicitOptions() Returns a list of all explicitly specified options, suitable for logging or for displaying back to the user.
java.util.List<OptionsParser.UnparsedOptionValueDescription>	asListOfUnparsedOptions() Returns a mutable copy of the list of all options that were specified either explicitly or implicitly.
java.util.List<java.lang.String>	canonicalize() Canonicalizes the list of options that this OptionsParser has parsed.
java.util.Map<java.lang.String,OptionsParser.OptionValueDescription>	clearValue(java.lang.String optionName) Clears the given option.
boolean	containsExplicitOption(java.lang.String name) Returns if the named option was specified explicitly in a call to parse.
java.lang.String	describeOptions(java.util.Map<java.lang.String,java.lang.String> categoryDescriptions, OptionsParser.HelpVerbosity helpVerbosity) Returns a description of all the options this parser can digest.
java.lang.String	describeOptionsHtml(java.util.Map<java.lang.String,java.lang.String> categoryDescriptions, com.google.common.escape.Escaper escaper) Returns a description of all the options this parser can digest.
OptionsParser.OptionDescription	getOptionDescription(java.lang.String name) Returns a description of the option.
<O extends OptionsBase> O	getOptions(java.lang.Class<O> optionsClass) Returns the options instance for the given optionsClass, that is, the parsed options, or null if it is not among those available.
java.lang.String	getOptionsCompletion() Returns a string listing the possible flag completion for this command along with the command completion if any.
static OpaqueOptionsData	getOptionsData(com.google.common.collect.ImmutableList<java.lang.Class<? extends OptionsBase>> optionsClasses) Returns OpaqueOptionsData suitable for passing along to newOptionsParser(OpaqueOptionsData optionsData).
OptionsParser.OptionValueDescription	getOptionValueDescription(java.lang.String name) Returns a description of the option value set by the last previous call to parse(OptionPriority, String, List) that successfully set the given option.
java.util.List<java.lang.String>	getResidue() Returns an immutable copy of the residue, that is, the arguments that have not been parsed.
java.util.List<java.lang.String>	getWarnings() Returns a list of warnings about problems encountered by previous parse calls.
static OptionsParser	newOptionsParser(java.lang.Class<? extends OptionsBase> class1)
static OptionsParser	newOptionsParser(java.lang.Class<? extends OptionsBase> class1, java.lang.Class<? extends OptionsBase> class2)
static OptionsParser	newOptionsParser(java.lang.Iterable<? extends java.lang.Class<? extends OptionsBase>> optionsClasses) Create a new OptionsParser.
static OptionsParser	newOptionsParser(OpaqueOptionsData optionsData) Create a new OptionsParser, using OpaqueOptionsData previously returned from getOptionsData(com.google.common.collect.ImmutableList<java.lang.Class<? extends com.google.devtools.common.options.OptionsBase>>).
void	parse(java.util.List<java.lang.String> args) A convenience method, equivalent to parse(OptionPriority.COMMAND_LINE, null, args).
void	parse(OptionPriority priority, java.lang.String source, java.util.List<java.lang.String> args) Parses args, using the classes registered with this parser.
void	parse(java.lang.String... args) A convenience method, equivalent to parse(OptionPriority.COMMAND_LINE, null, Arrays.asList(args)).
void	parseAndExitUponError(OptionPriority priority, java.lang.String source, java.lang.String[] args) A convenience function for use in main methods.
void	parseAndExitUponError(java.lang.String[] args)
void	parseWithSourceFunction(OptionPriority priority, com.google.common.base.Function<? super java.lang.String,java.lang.String> sourceFunction, java.util.List<java.lang.String> args) Parses args, using the classes registered with this parser.
void	setAllowResidue(boolean allowResidue) Indicates whether or not the parser will allow a non-empty residue; that is, iff this value is true then a call to one of the parse methods will throw OptionsParsingException unless getResidue() is empty after parsing.
void	setAllowSingleDashLongOptions(boolean allowSingleDashLongOptions) Indicates whether or not the parser will allow long options with a single-dash, instead of the usual double-dash, too, eg.

Methods inherited from class java.lang.Object

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

Method Detail

getOptionsData

public static OpaqueOptionsData getOptionsData(com.google.common.collect.ImmutableList<java.lang.Class<? extends OptionsBase>> optionsClasses)

Returns OpaqueOptionsData suitable for passing along to newOptionsParser(OpaqueOptionsData optionsData). This is useful when you want to do the work of analyzing the given optionsClasses exactly once, but you want to parse lots of different lists of strings (and thus need to construct lots of different OptionsParser instances).

newOptionsParser

public static OptionsParser newOptionsParser(java.lang.Class<? extends OptionsBase> class1)

See Also:

newOptionsParser(Iterable)

newOptionsParser

public static OptionsParser newOptionsParser(java.lang.Class<? extends OptionsBase> class1,
                                             java.lang.Class<? extends OptionsBase> class2)

See Also:

newOptionsParser(Iterable)

newOptionsParser

public static OptionsParser newOptionsParser(java.lang.Iterable<? extends java.lang.Class<? extends OptionsBase>> optionsClasses)

Create a new OptionsParser.

newOptionsParser

public static OptionsParser newOptionsParser(OpaqueOptionsData optionsData)

Create a new OptionsParser, using OpaqueOptionsData previously returned from getOptionsData(com.google.common.collect.ImmutableList<java.lang.Class<? extends com.google.devtools.common.options.OptionsBase>>).

setAllowResidue

public void setAllowResidue(boolean allowResidue)

Indicates whether or not the parser will allow a non-empty residue; that is, iff this value is true then a call to one of the parse methods will throw OptionsParsingException unless getResidue() is empty after parsing.

setAllowSingleDashLongOptions

public void setAllowSingleDashLongOptions(boolean allowSingleDashLongOptions)

Indicates whether or not the parser will allow long options with a single-dash, instead of the usual double-dash, too, eg. -example instead of just --example.

parseAndExitUponError

public void parseAndExitUponError(java.lang.String[] args)

parseAndExitUponError

public void parseAndExitUponError(OptionPriority priority,
                                  java.lang.String source,
                                  java.lang.String[] args)

A convenience function for use in main methods. Parses the command line parameters, and exits upon error. Also, prints out the usage message if "--help" appears anywhere within args.

describeOptions

public java.lang.String describeOptions(java.util.Map<java.lang.String,java.lang.String> categoryDescriptions,
                                        OptionsParser.HelpVerbosity helpVerbosity)

Returns a description of all the options this parser can digest. In addition to Option annotations, this method also interprets OptionsUsage annotations which give an intuitive short description for the options.

Parameters:

categoryDescriptions - a mapping from category names to category descriptions. Options of the same category (see Option.category()) will be grouped together, preceded by the description of the category.

helpVerbosity - if long, the options will be described verbosely, including their types, defaults and descriptions. If medium, the descriptions are omitted, and if short, the options are just enumerated.

describeOptionsHtml

public java.lang.String describeOptionsHtml(java.util.Map<java.lang.String,java.lang.String> categoryDescriptions,
                                            com.google.common.escape.Escaper escaper)

Returns a description of all the options this parser can digest. In addition to Option annotations, this method also interprets OptionsUsage annotations which give an intuitive short description for the options.

Parameters:

categoryDescriptions - a mapping from category names to category descriptions. Options of the same category (see Option.category()) will be grouped together, preceded by the description of the category.

getOptionsCompletion

public java.lang.String getOptionsCompletion()

Returns a string listing the possible flag completion for this command along with the command completion if any. See OptionsUsage.getCompletion(Field, StringBuilder) for more details on the format for the flag completion.

getOptionDescription

public OptionsParser.OptionDescription getOptionDescription(java.lang.String name)

Returns a description of the option.

Returns:

The OptionsParser.OptionValueDescription for the option, or null if there is no option by the given name.

getOptionValueDescription

public OptionsParser.OptionValueDescription getOptionValueDescription(java.lang.String name)

Returns a description of the option value set by the last previous call to parse(OptionPriority, String, List) that successfully set the given option. If the option is of type List, the description will correspond to any one of the calls, but not necessarily the last.

Returns:

The OptionsParser.OptionValueDescription for the option, or null if the value has not been set.

Throws:

java.lang.IllegalArgumentException - if there is no option by the given name.

parse

public void parse(java.lang.String... args)
           throws OptionsParsingException

A convenience method, equivalent to parse(OptionPriority.COMMAND_LINE, null, Arrays.asList(args)).

Throws:

OptionsParsingException

parse

public void parse(java.util.List<java.lang.String> args)
           throws OptionsParsingException

A convenience method, equivalent to parse(OptionPriority.COMMAND_LINE, null, args).

Throws:

OptionsParsingException

parse

public void parse(OptionPriority priority,
                  java.lang.String source,
                  java.util.List<java.lang.String> args)
           throws OptionsParsingException

Parses args, using the classes registered with this parser. getOptions(Class) and getResidue() return the results. May be called multiple times; later options override existing ones if they have equal or higher priority. The source of options is a free-form string that can be used for debugging. Strings that cannot be parsed as options accumulates as residue, if this parser allows it.

Throws:

OptionsParsingException

See Also:

OptionPriority

parseWithSourceFunction

public void parseWithSourceFunction(OptionPriority priority,
                                    com.google.common.base.Function<? super java.lang.String,java.lang.String> sourceFunction,
                                    java.util.List<java.lang.String> args)
                             throws OptionsParsingException

Parses args, using the classes registered with this parser. getOptions(Class) and getResidue() return the results. May be called multiple times; later options override existing ones if they have equal or higher priority. The source of options is given as a function that maps option names to the source of the option. Strings that cannot be parsed as options accumulates as* residue, if this parser allows it.

Throws:

OptionsParsingException

clearValue

public java.util.Map<java.lang.String,OptionsParser.OptionValueDescription> clearValue(java.lang.String optionName)
                                                                                throws OptionsParsingException

Clears the given option. Also clears expansion arguments and implicit requirements for that option.

This will not affect options objects that have already been retrieved from this parser through getOptions(Class).

Parameters:

optionName - The full name of the option to clear.

Returns:

A map of an option name to the old value of the options that were cleared.

Throws:

java.lang.IllegalArgumentException - If the flag does not exist.

OptionsParsingException

getResidue

public java.util.List<java.lang.String> getResidue()

Description copied from interface: OptionsProvider

Returns an immutable copy of the residue, that is, the arguments that have not been parsed.

Specified by:

getResidue in interface OptionsProvider

getWarnings

public java.util.List<java.lang.String> getWarnings()

Returns a list of warnings about problems encountered by previous parse calls.

getOptions

public <O extends OptionsBase> O getOptions(java.lang.Class<O> optionsClass)

Description copied from interface: OptionsClassProvider

Returns the options instance for the given optionsClass, that is, the parsed options, or null if it is not among those available.

The returned options should be treated by library code as immutable and a provider is permitted to return the same options instance multiple times.

Specified by:

getOptions in interface OptionsClassProvider

containsExplicitOption

public boolean containsExplicitOption(java.lang.String name)

Description copied from interface: OptionsProvider

Returns if the named option was specified explicitly in a call to parse.

Specified by:

containsExplicitOption in interface OptionsProvider

asListOfUnparsedOptions

public java.util.List<OptionsParser.UnparsedOptionValueDescription> asListOfUnparsedOptions()

Description copied from interface: OptionsProvider

Returns a mutable copy of the list of all options that were specified either explicitly or implicitly. These options are sorted by priority, and by the order in which they were specified. If an option was specified multiple times, it is included in the result multiple times. Does not include the residue.

The returned list can be filtered if undocumented, hidden or implicit options should not be displayed.

Specified by:

asListOfUnparsedOptions in interface OptionsProvider

asListOfExplicitOptions

public java.util.List<OptionsParser.UnparsedOptionValueDescription> asListOfExplicitOptions()

Description copied from interface: OptionsProvider

Returns a list of all explicitly specified options, suitable for logging or for displaying back to the user. These options are sorted by priority, and by the order in which they were specified. If an option was explicitly specified multiple times, it is included in the result multiple times. Does not include the residue.

The list includes undocumented options.

Specified by:

asListOfExplicitOptions in interface OptionsProvider

asListOfEffectiveOptions

public java.util.List<OptionsParser.OptionValueDescription> asListOfEffectiveOptions()

Description copied from interface: OptionsProvider

Returns a list of all options, including undocumented ones, and their effective values. There is no guaranteed ordering for the result.

Specified by:

asListOfEffectiveOptions in interface OptionsProvider

canonicalize

public java.util.List<java.lang.String> canonicalize()

Description copied from interface: OptionsProvider

Canonicalizes the list of options that this OptionsParser has parsed. The contract is that if the returned set of options is passed to an options parser with the same options classes, then that will have the same effect as using the original args (which are passed in here), except for cosmetic differences.

Specified by:

canonicalize in interface OptionsProvider