1 // Copyright 2014 The Bazel Authors. All rights reserved. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 package com.google.devtools.common.options; 15 16 import java.lang.annotation.ElementType; 17 import java.lang.annotation.Retention; 18 import java.lang.annotation.RetentionPolicy; 19 import java.lang.annotation.Target; 20 21 /** 22 * An interface for annotating fields in classes (derived from OptionsBase) that are options. 23 * 24 * <p>The fields of this annotation have matching getters in {@link OptionDefinition}. Please do not 25 * access these fields directly, but instead go through that class. 26 * 27 * <p>A number of checks are run on an Option's fields' values at compile time. See 28 * {@link com.google.devtools.common.options.processor.OptionProcessor} for details. 29 */ 30 @Target(ElementType.FIELD) 31 @Retention(RetentionPolicy.RUNTIME) 32 public @interface Option { 33 /** The name of the option ("--name"). */ 34 String name(); 35 36 /** The single-character abbreviation of the option ("-a"). */ 37 char abbrev() default '\0'; 38 39 /** A help string for the usage information. */ 40 String help() default ""; 41 42 /** 43 * A short text string to describe the type of the expected value. E.g., <code>regex</code>. This 44 * is ignored for boolean, tristate, boolean_or_enum, and void options. 45 */ 46 String valueHelp() default ""; 47 48 /** 49 * The default value for the option. This method should only be invoked directly by the parser 50 * implementation. Any access to default values should go via the parser to allow for application 51 * specific defaults. 52 * 53 * <p>There are two reasons this is a string. Firstly, it ensures that explicitly specifying this 54 * option at its default value (as printed in the usage message) has the same behavior as not 55 * specifying the option at all; this would be very hard to achieve if the default value was an 56 * instance of type T, since we'd need to ensure that {@link #toString()} and {@link #converter} 57 * were dual to each other. The second reason is more mundane but also more restrictive: 58 * annotation values must be compile-time constants. 59 * 60 * <p>If an option's defaultValue() is the string "null", the option's converter will not be 61 * invoked to interpret it; a null reference will be used instead. (It would be nice if 62 * defaultValue could simply return null, but bizarrely, the Java Language Specification does not 63 * consider null to be a compile-time constant.) This special interpretation of the string "null" 64 * is only applicable when computing the default value; if specified on the command-line, this 65 * string will have its usual literal meaning. 66 * 67 * <p>The default value for flags that set allowMultiple is always the empty list and its default 68 * value is ignored. 69 */ 70 String defaultValue(); 71 72 /** 73 * This category field is deprecated. Bazel is in the process of migrating all options to use the 74 * better defined enums in OptionDocumentationCategory and the tags in the option_filters.proto 75 * file. It will still be used for the usage documentation until a sufficient proportion of 76 * options are using the new system. 77 * 78 * <p>Please leave the old category field in existing options to minimize disruption to the Help 79 * output during the transition period. All uses of this field will be removed when transition is 80 * complete. This category field has no effect on the other fields below, having both set is not a 81 * problem. 82 */ 83 @Deprecated 84 String category() default "misc"; 85 86 /** 87 * Grouping categories used for usage documentation. See the enum's definition for details. 88 * 89 * <p>For undocumented flags that aren't listed anywhere, set this to 90 * OptionDocumentationCategory.UNDOCUMENTED. 91 */ 92 OptionDocumentationCategory documentationCategory(); 93 94 /** 95 * Tag about the intent or effect of this option. Unless this option is a no-op (and the reason 96 * for this should be documented) all options should have some effect, so this needs to have at 97 * least one value, and as many as apply. 98 * 99 * <p>No option should list NO_OP or UNKNOWN with other effects listed, but all other combinations 100 * are allowed. 101 */ 102 OptionEffectTag[] effectTags(); 103 104 /** 105 * Tag about the option itself, not its effect, such as option state (experimental) or intended 106 * use (a value that isn't a flag but is used internally, for example, is "internal") 107 * 108 * <p>If one or more of the OptionMetadataTag values apply, please include, but otherwise, this 109 * list can be left blank. 110 * 111 * <p>Hidden or internal options must be UNDOCUMENTED (set in {@link #documentationCategory()}). 112 */ 113 OptionMetadataTag[] metadataTags() default {}; 114 115 /** 116 * The converter that we'll use to convert the string representation of this option's value into 117 * an object or a simple type. The default is to use the builtin converters ({@link 118 * Converters#DEFAULT_CONVERTERS}). Custom converters must implement the {@link Converter} 119 * interface. 120 */ 121 @SuppressWarnings({"unchecked", "rawtypes"}) 122 // Can't figure out how to coerce Converter.class into Class<? extends Converter<?>> 123 Class<? extends Converter> converter() default Converter.class; 124 125 /** 126 * A boolean value indicating whether the option type should be allowed to occur multiple times in 127 * a single arg list. 128 * 129 * <p>If the option can occur multiple times, then the attribute value <em>must</em> be a list 130 * type {@code List<T>}, and the result type of the converter for this option must either match 131 * the parameter {@code T} or {@code List<T>}. In the latter case the individual lists are 132 * concatenated to form the full options value. 133 * 134 * <p>The {@link #defaultValue()} field of the annotation is ignored for repeatable flags and the 135 * default value will be the empty list. 136 */ 137 boolean allowMultiple() default false; 138 139 /** 140 * If the option is actually an abbreviation for other options, this field will contain the 141 * strings to expand this option into. The original option is dropped and the replacement used in 142 * its stead. It is recommended that such an option be of type {@link Void}. 143 * 144 * <p>An expanded option overrides previously specified options of the same name, even if it is 145 * explicitly specified. This is the original behavior and can be surprising if the user is not 146 * aware of it, which has led to several requests to change this behavior. This was discussed in 147 * the blaze team and it was decided that it is not a strong enough case to change the behavior. 148 */ 149 String[] expansion() default {}; 150 151 /** 152 * A mechanism for specifying an expansion that is a function of the parser's {@link 153 * IsolatedOptionsData}. This can be used to create an option that expands to different strings 154 * depending on what other options the parser knows about. 155 * 156 * <p>If provided (i.e. not {@link ExpansionFunction}{@code .class}), the {@code expansion} field 157 * must not be set. The mechanism of expansion is as if the {@code expansion} field were set to 158 * whatever the return value of this function is. 159 */ 160 Class<? extends ExpansionFunction> expansionFunction() default ExpansionFunction.class; 161 162 /** 163 * Additional options that need to be implicitly added for this option. 164 * 165 * <p>Nothing guarantees that these options are not overridden by later or higher-priority values 166 * for the same options, so if this is truly a requirement, the user should check that the correct 167 * set of options is set. 168 * 169 * <p>These requirements are added for ANY mention of this option, so may not work as intended: in 170 * the case where a user is trying to explicitly turn off a flag (say, by setting a boolean flag 171 * to its default value of false), the mention will still turn on its requirements. For this 172 * reason, it is best not to use this feature, and rely on expansion flags if multi-flag groupings 173 * are needed. 174 */ 175 String[] implicitRequirements() default {}; 176 177 /** 178 * If this field is a non-empty string, the option is deprecated, and a deprecation warning is 179 * added to the list of warnings when such an option is used. 180 */ 181 String deprecationWarning() default ""; 182 183 /** 184 * The old name for this option. If an option has a name "foo" and an old name "bar", --foo=baz 185 * and --bar=baz will be equivalent. If the old name is used, a warning will be printed indicating 186 * that the old name is deprecated and the new name should be used. 187 */ 188 String oldName() default ""; 189 190 /** 191 * Indicates that this option is a wrapper for other options, and will be unwrapped when parsed. 192 * For example, if foo is a wrapper option, then "--foo=--bar=baz" will be parsed as the flag 193 * "--bar=baz" (rather than --foo taking the value "--bar=baz"). A wrapper option should have the 194 * type {@link Void} (if it is something other than Void, the parser will not assign a value to 195 * it). The {@link Option#implicitRequirements()}, {@link Option#expansion()}, {@link 196 * Option#converter()} attributes will not be processed. Wrapper options are implicitly repeatable 197 * (i.e., as though {@link Option#allowMultiple()} is true regardless of its value in the 198 * annotation). 199 * 200 * <p>Wrapper options are provided only for transitioning flags which appear as values to other 201 * flags, to top-level flags. Wrapper options should not be used in Invocation Policy, as 202 * expansion flags to other flags, or as implicit requirements to other flags. Use the inner flags 203 * instead. 204 */ 205 @Deprecated 206 boolean wrapperOption() default false; 207 } 208
