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 com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions; 17 import java.lang.annotation.ElementType; 18 import java.lang.annotation.Retention; 19 import java.lang.annotation.RetentionPolicy; 20 import java.lang.annotation.Target; 21 22 /** 23 * An interface for annotating fields in classes (derived from OptionsBase) 24 * that are options. 25 */ 26 @Target(ElementType.FIELD) 27 @Retention(RetentionPolicy.RUNTIME) 28 public @interface Option { 29 /** 30 * The name of the option ("--name"). 31 */ name()32 String name(); 33 34 /** 35 * The single-character abbreviation of the option ("-abbrev"). 36 */ abbrev()37 char abbrev() default '\0'; 38 39 /** 40 * A help string for the usage information. 41 */ help()42 String help() default ""; 43 44 /** 45 * A short text string to describe the type of the expected value. E.g., <code>regex</code>. This 46 * is ignored for boolean, tristate, boolean_or_enum, and void options. 47 */ valueHelp()48 String valueHelp() default ""; 49 50 /** 51 * The default value for the option. This method should only be invoked directly by the parser 52 * implementation. Any access to default values should go via the parser to allow for application 53 * specific defaults. 54 * 55 * <p>There are two reasons this is a string. Firstly, it ensures that explicitly specifying this 56 * option at its default value (as printed in the usage message) has the same behavior as not 57 * specifying the option at all; this would be very hard to achieve if the default value was an 58 * instance of type T, since we'd need to ensure that {@link #toString()} and {@link #converter} 59 * were dual to each other. The second reason is more mundane but also more restrictive: 60 * annotation values must be compile-time constants. 61 * 62 * <p>If an option's defaultValue() is the string "null", the option's converter will not be 63 * invoked to interpret it; a null reference will be used instead. (It would be nice if 64 * defaultValue could simply return null, but bizarrely, the Java Language Specification does not 65 * consider null to be a compile-time constant.) This special interpretation of the string "null" 66 * is only applicable when computing the default value; if specified on the command-line, this 67 * string will have its usual literal meaning. 68 * 69 * <p>The default value for flags that set allowMultiple is always the empty list and its default 70 * value is ignored. 71 */ defaultValue()72 String defaultValue(); 73 74 /** 75 * A string describing the role of the option. Some existing categories are "input," "output," 76 * "config," "semantics," and "strategy," among others. 77 * 78 * <p>The category of options that this belongs to dictates how options are grouped by {@link 79 * OptionsParser#describeOptions}, for the usage documentation. 80 * 81 * <p>For undocumented flags that aren't listed anywhere, this is currently a no-op. Feel free to 82 * set the value that it would have if it were documented, which might be helpful if a flag is 83 * part of an experimental feature that might become documented in the future, or just leave it 84 * unset as the default. 85 * 86 * <p>For hidden or internal options, use the category field only if it is helpful for yourself or 87 * other Bazel developers. 88 */ category()89 String category() default "misc"; 90 91 /** 92 * Options have multiple uses, some flags, some not. For user-visible flags, they are 93 * "documented," but otherwise, there are 3 types of undocumented options. 94 * 95 * <ul> 96 * <li>{@code UNDOCUMENTED}: undocumented but user-usable flags. These options are useful for 97 * (some subset of) users, but not meant to be publicly advertised. For example, 98 * experimental options which are only meant to be used by specific testers or team members. 99 * These options will not be listed in the usage info displayed for the {@code --help} 100 * option. They are otherwise normal - {@link 101 * OptionsParser.UnparsedOptionValueDescription#isHidden()} returns {@code false} for them, 102 * and they can be parsed normally from the command line or RC files. 103 * <li>{@code HIDDEN}: flags which users should not pass or know about, but which are used by 104 * the program (e.g., communication between a command-line client and a backend server). 105 * Like {@code "undocumented"} options, these options will not be listed in the usage info 106 * displayed for the {@code --help} option. However, in addition to this, calling {@link 107 * OptionsParser.UnparsedOptionValueDescription#isHidden()} on these options will return 108 * {@code true} - for example, this can be checked to strip out such secret options when 109 * logging or otherwise reporting the command line to the user. This category does not 110 * affect the option in any other way; it can still be parsed normally from the command line 111 * or an RC file. 112 * <li>{@code INTERNAL}: these are not flags, but options which are purely for internal use 113 * within the JVM, and should never be shown to the user, nor be parsed by the options 114 * parser. Like {@code "hidden"} options, these options will not be listed in the usage info 115 * displayed for the --help option, and are considered hidden by {@link 116 * OptionsParser.UnparsedOptionValueDescription#isHidden()}. Unlike those, this type of 117 * option cannot be parsed by any call to {@link OptionsParser#parse} - it will be treated 118 * as if it was not defined. 119 * </ul> 120 */ optionUsageRestrictions()121 OptionUsageRestrictions optionUsageRestrictions() default OptionUsageRestrictions.DOCUMENTED; 122 123 /** 124 * The converter that we'll use to convert the string representation of this option's value into 125 * an object or a simple type. The default is to use the builtin converters ({@link 126 * Converters#DEFAULT_CONVERTERS}). Custom converters must implement the {@link Converter} 127 * interface. 128 */ 129 @SuppressWarnings({"unchecked", "rawtypes"}) 130 // Can't figure out how to coerce Converter.class into Class<? extends Converter<?>> converter()131 Class<? extends Converter> converter() default Converter.class; 132 133 /** 134 * A flag indicating whether the option type should be allowed to occur multiple times in a single 135 * option list. 136 * 137 * <p>If the command can occur multiple times, then the attribute value <em>must</em> be a list 138 * type {@code List<T>}, and the result type of the converter for this option must either match 139 * the parameter {@code T} or {@code List<T>}. In the latter case the individual lists are 140 * concatenated to form the full options value. 141 * 142 * <p>The {@link #defaultValue()} field of the annotation is ignored for repeatable flags and the 143 * default value will be the empty list. 144 */ allowMultiple()145 boolean allowMultiple() default false; 146 147 /** 148 * If the option is actually an abbreviation for other options, this field will contain the 149 * strings to expand this option into. The original option is dropped and the replacement used in 150 * its stead. It is recommended that such an option be of type {@link Void}. 151 * 152 * <p>An expanded option overrides previously specified options of the same name, even if it is 153 * explicitly specified. This is the original behavior and can be surprising if the user is not 154 * aware of it, which has led to several requests to change this behavior. This was discussed in 155 * the blaze team and it was decided that it is not a strong enough case to change the behavior. 156 */ expansion()157 String[] expansion() default {}; 158 159 /** 160 * A mechanism for specifying an expansion that is a function of the parser's {@link 161 * IsolatedOptionsData}. This can be used to create an option that expands to different strings 162 * depending on what other options the parser knows about. 163 * 164 * <p>If provided (i.e. not {@link ExpansionFunction}{@code .class}), the {@code expansion} field 165 * must not be set. The mechanism of expansion is as if the {@code expansion} field were set to 166 * whatever the return value of this function is. 167 */ expansionFunction()168 Class<? extends ExpansionFunction> expansionFunction() default ExpansionFunction.class; 169 170 /** 171 * If the option requires that additional options be implicitly appended, this field will contain 172 * the additional options. Implicit dependencies are parsed at the end of each {@link 173 * OptionsParser#parse} invocation, and override options specified in the same call. However, they 174 * can be overridden by options specified in a later call or by options with a higher priority. 175 * 176 * @see OptionPriority 177 */ implicitRequirements()178 String[] implicitRequirements() default {}; 179 180 /** 181 * If this field is a non-empty string, the option is deprecated, and a deprecation warning is 182 * added to the list of warnings when such an option is used. 183 */ deprecationWarning()184 String deprecationWarning() default ""; 185 186 /** 187 * The old name for this option. If an option has a name "foo" and an old name "bar", --foo=baz 188 * and --bar=baz will be equivalent. If the old name is used, a warning will be printed indicating 189 * that the old name is deprecated and the new name should be used. 190 */ oldName()191 String oldName() default ""; 192 193 /** 194 * Indicates that this option is a wrapper for other options, and will be unwrapped when parsed. 195 * For example, if foo is a wrapper option, then "--foo=--bar=baz" will be parsed as the flag 196 * "--bar=baz" (rather than --foo taking the value "--bar=baz"). A wrapper option should have the 197 * type {@link Void} (if it is something other than Void, the parser will not assign a value to 198 * it). The {@link Option#implicitRequirements()}, {@link Option#expansion()}, {@link 199 * Option#converter()} attributes will not be processed. Wrapper options are implicitly repeatable 200 * (i.e., as though {@link Option#allowMultiple()} is true regardless of its value in the 201 * annotation). 202 * 203 * <p>Wrapper options are provided only for transitioning flags which appear as values to other 204 * flags, to top-level flags. Wrapper options should not be used in Invocation Policy, as 205 * expansion flags to other flags, or as implicit requirements to other flags. Use the inner flags 206 * instead. 207 */ wrapperOption()208 boolean wrapperOption() default false; 209 } 210