| // Copyright 2024 The Bazel Authors. All rights reserved. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| package com.google.devtools.common.options; |
| |
| import static java.util.Comparator.comparing; |
| |
| import java.lang.reflect.Type; |
| import java.util.Comparator; |
| import javax.annotation.Nullable; |
| |
| /** Everything the {@link OptionsParser} needs to know about how an option is defined. */ |
| public abstract class OptionDefinition implements Comparable<OptionDefinition> { |
| |
| /** An ordering relation for options that orders by the option name. */ |
| public static final Comparator<OptionDefinition> BY_OPTION_NAME = |
| Comparator.comparing(OptionDefinition::getOptionName); |
| |
| /** |
| * An ordering relation for options that first groups together options of the same category, then |
| * sorts by name within the category. |
| */ |
| public static final Comparator<OptionDefinition> BY_CATEGORY = |
| comparing(OptionDefinition::getOptionCategory).thenComparing(BY_OPTION_NAME); |
| |
| /** Returns the declaring {@link OptionsBase} class that owns this option. */ |
| public abstract <C extends OptionsBase> Class<? extends C> getDeclaringClass(Class<C> baseClass); |
| |
| /** |
| * Returns the raw value of the option. Use {@link #getValue} if possible to correctly handle |
| * default values. |
| */ |
| public abstract Object getRawValue(OptionsBase optionsBase); |
| |
| /** Returns the value of this option, taking default values into account. */ |
| public abstract Object getValue(OptionsBase optionsBase); |
| |
| /** |
| * Returns the value of this option as a boolean. If the option is not boolean-typed, throws an |
| * IllegalStateException. |
| */ |
| public boolean getBooleanValue(OptionsBase optionsBase) { |
| // Check for primitive boolean first, as it's more common. |
| if (!getType().isAssignableFrom(Boolean.TYPE) && !getType().isAssignableFrom(Boolean.class)) { |
| throw new IllegalStateException( |
| "Option " |
| + getOptionName() |
| + " is not a boolean, has type " |
| + getType().getCanonicalName()); |
| } |
| return getValue(optionsBase).equals(Boolean.TRUE); |
| } |
| |
| /** Sets the value for this option. */ |
| public abstract void setValue(OptionsBase optionsBase, Object value); |
| |
| /** Returns whether this option is deprecated. */ |
| public abstract boolean isDeprecated(); |
| |
| /** Returns the name of this option. */ |
| public abstract String getOptionName(); |
| |
| /** Returns a one-character abbreviation for this option, if any. */ |
| public abstract char getAbbreviation(); |
| |
| /** Returns the help test for this option. */ |
| public abstract String getHelpText(); |
| |
| /** Returns a short description of the expected type of this option. */ |
| public abstract String getValueTypeHelpText(); |
| |
| /** |
| * Returns the default value of this option, with no conversion performed. Should only be used by |
| * the parser. |
| */ |
| public abstract String getUnparsedDefaultValue(); |
| |
| /** |
| * Returns the deprecated option category. |
| * |
| * @deprecated Use {@link #getDocumentationCategory} instead |
| */ |
| @Deprecated |
| public abstract String getOptionCategory(); |
| |
| /** Returns the option category. */ |
| public abstract OptionDocumentationCategory getDocumentationCategory(); |
| |
| /** Returns data about the intended effects of this option. */ |
| public abstract OptionEffectTag[] getOptionEffectTags(); |
| |
| /** Returns metadata about this option. */ |
| public abstract OptionMetadataTag[] getOptionMetadataTags(); |
| |
| /** Returns a converter to use for this option. */ |
| @SuppressWarnings({"rawtypes"}) |
| public abstract Class<? extends Converter> getProvidedConverter(); |
| |
| /** Returns whether this option allows multiple instances to be combined into a list. */ |
| public abstract boolean allowsMultiple(); |
| |
| /** Returns any options which are added if this option is present. */ |
| public abstract String[] getOptionExpansion(); |
| |
| /** Returns aditional options that need to be implicitly added for this option. */ |
| public abstract String[] getImplicitRequirements(); |
| |
| /** Returns a deprecation warning for this option, if one is present. */ |
| public abstract String getDeprecationWarning(); |
| |
| /** Returns the old name for this option, if one is present. */ |
| public abstract String getOldOptionName(); |
| |
| /** Returns a warning to use with this option if the old name is specified. */ |
| public abstract boolean getOldNameWarning(); |
| |
| /** Returns whether an option --foo has a negative equivalent --nofoo. */ |
| public boolean hasNegativeOption() { |
| return getType().equals(boolean.class) || getType().equals(TriState.class); |
| } |
| |
| /** The type of the optionDefinition. */ |
| public abstract Class<?> getType(); |
| |
| /** Whether this field has type Void. */ |
| public boolean isVoidField() { |
| return getType().equals(Void.class); |
| } |
| |
| // TODO: blaze-configurability - try to remove special handling for defaults |
| public abstract boolean isSpecialNullDefault(); |
| |
| /** Returns whether the arg is an expansion option. */ |
| public boolean isExpansionOption() { |
| return getOptionExpansion().length > 0; |
| } |
| |
| /** Returns whether the arg is an expansion option. */ |
| public boolean hasImplicitRequirements() { |
| return (getImplicitRequirements().length > 0); |
| } |
| |
| /** |
| * For an option that does not use {@link Option#allowMultiple}, returns its type. For an option |
| * that does use it, asserts that the type is a {@code List<T>} and returns its element type |
| * {@code T}. |
| */ |
| public abstract Type getFieldSingularType(); |
| |
| /** Returns the {@link Converter} that will be used for this option. */ |
| public abstract Converter<?> getConverter(); |
| |
| /** |
| * Returns whether a field should be considered as boolean. |
| * |
| * <p>Can be used for usage help and controlling whether the "no" prefix is allowed. |
| */ |
| public boolean usesBooleanValueSyntax() { |
| return getType().equals(boolean.class) |
| || getType().equals(TriState.class) |
| || getConverter() instanceof BoolOrEnumConverter; |
| } |
| |
| /** |
| * Returns whether an option requires a value when instantiated, or instead can be present without |
| * an explicit value. |
| */ |
| public boolean requiresValue() { |
| return !isVoidField() && !usesBooleanValueSyntax(); |
| } |
| |
| /** Returns the evaluated default value for this option. */ |
| @Nullable |
| public abstract Object getDefaultValue(@Nullable Object conversionContext); |
| } |