com.google.devtools.common.options

Annotation Type Option

@Target(value=FIELD)
 @Retention(value=RUNTIME)
public @interface Option

An interface for annotating fields in classes (derived from OptionsBase) that are options.

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
java.lang.String	defaultValue The default value for the option.
java.lang.String	name The name of the option ("--name").

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
char	abbrev The single-character abbreviation of the option ("-abbrev").
boolean	allowMultiple A flag indicating whether the option type should be allowed to occur multiple times in a single option list.
java.lang.String	category A string describing the category of options that this belongs to.
java.lang.Class<? extends Converter>	converter The converter that we'll use to convert this option into an object or a simple type.
java.lang.String	deprecationWarning If this field is a non-empty string, the option is deprecated, and a deprecation warning is added to the list of warnings when such an option is used.
java.lang.String[]	expansion If the option is actually an abbreviation for other options, this field will contain the strings to expand this option into.
java.lang.String	help A help string for the usage information.
java.lang.String[]	implicitRequirements If the option requires that additional options be implicitly appended, this field will contain the additional options.
java.lang.String	oldName The old name for this option.
java.lang.String	valueHelp A short text string to describe the type of the expected value.
boolean	wrapperOption Indicates that this option is a wrapper for other options, and will be unwrapped when parsed.

Element Detail

name

public abstract java.lang.String name

The name of the option ("--name").

defaultValue

public abstract java.lang.String defaultValue

The default value for the option. This method should only be invoked directly by the parser implementation. Any access to default values should go via the parser to allow for application specific defaults.

There are two reasons this is a string. Firstly, it ensures that explicitly specifying this option at its default value (as printed in the usage message) has the same behavior as not specifying the option at all; this would be very hard to achieve if the default value was an instance of type T, since we'd need to ensure that Annotation.toString() and converter() were dual to each other. The second reason is more mundane but also more restrictive: annotation values must be compile-time constants.

If an option's defaultValue() is the string "null", the option's converter will not be invoked to interpret it; a null reference will be used instead. (It would be nice if defaultValue could simply return null, but bizarrely, the Java Language Specification does not consider null to be a compile-time constant.) This special interpretation of the string "null" is only applicable when computing the default value; if specified on the command-line, this string will have its usual literal meaning.

The default value for flags that set allowMultiple is always the empty list and its default value is ignored.

abbrev

public abstract char abbrev

The single-character abbreviation of the option ("-abbrev").

Default:

0

help

public abstract java.lang.String help

A help string for the usage information.

Default:

""

valueHelp

public abstract java.lang.String valueHelp

A short text string to describe the type of the expected value. E.g., regex. This is ignored for boolean, tristate, boolean_or_enum, and void options.

Default:

""

category

public abstract java.lang.String category

A string describing the category of options that this belongs to. OptionsParser.describeOptions(java.util.Map<java.lang.String, java.lang.String>, com.google.devtools.common.options.OptionsParser.HelpVerbosity) prints options of the same category grouped together.

Default:

"misc"

converter

public abstract java.lang.Class<? extends Converter> converter

The converter that we'll use to convert this option into an object or a simple type. The default is to use the builtin converters. Custom converters must implement the Converter interface.

Default:

com.google.devtools.common.options.Converter.class

allowMultiple

public abstract boolean allowMultiple

A flag indicating whether the option type should be allowed to occur multiple times in a single option list.

If the command can occur multiple times, then the attribute value must be a list type List<T>, and the result type of the converter for this option must either match the parameter T or List<T>. In the latter case the individual lists are concatenated to form the full options value.

The defaultValue() field of the annotation is ignored for repeatable flags and the default value will be the empty list.

Default:

false

expansion

public abstract java.lang.String[] expansion

If the option is actually an abbreviation for other options, this field will contain the strings to expand this option into. The original option is dropped and the replacement used in its stead. It is recommended that such an option be of type Void. An expanded option overrides previously specified options of the same name, even if it is explicitly specified. This is the original behavior and can be surprising if the user is not aware of it, which has led to several requests to change this behavior. This was discussed in the blaze team and it was decided that it is not a strong enough case to change the behavior.

Default:

{}

implicitRequirements

public abstract java.lang.String[] implicitRequirements

If the option requires that additional options be implicitly appended, this field will contain the additional options. Implicit dependencies are parsed at the end of each OptionsParser.parse(java.lang.String...) invocation, and override options specified in the same call. However, they can be overridden by options specified in a later call or by options with a higher priority.

See Also:

OptionPriority

Default:

{}

deprecationWarning

public abstract java.lang.String deprecationWarning

If this field is a non-empty string, the option is deprecated, and a deprecation warning is added to the list of warnings when such an option is used.

Default:

""

oldName

public abstract java.lang.String oldName

The old name for this option. If an option has a name "foo" and an old name "bar", --foo=baz and --bar=baz will be equivalent. If the old name is used, a warning will be printed indicating that the old name is deprecated and the new name should be used.

Default:

""

wrapperOption

public abstract boolean wrapperOption

Indicates that this option is a wrapper for other options, and will be unwrapped when parsed. For example, if foo is a wrapper option, then "--foo=--bar=baz" will be parsed as the flag "--bar=baz" (rather than --foo taking the value "--bar=baz"). A wrapper option should have the type Void (if it is something other than Void, the parser will not assign a value to it). The implicitRequirements(), expansion(), converter() attributes will not be processed. Wrapper options are implicitly repeatable (i.e., as though allowMultiple() is true regardless of its value in the annotation).

Wrapper options are provided only for transitioning flags which appear as values to other flags, to top-level flags. Wrapper options should not be used in Invocation Policy, as expansion flags to other flags, or as implicit requirements to other flags. Use the inner flags instead.

Default:

false