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 15 package com.google.devtools.common.options; 16 17 import java.util.List; 18 19 /** 20 * A read-only interface for options parser results, which does not allow any 21 * further parsing of options. 22 */ 23 public interface OptionsProvider extends OptionsClassProvider { 24 25 /** 26 * Returns an immutable copy of the residue, that is, the arguments that 27 * have not been parsed. 28 */ getResidue()29 List<String> getResidue(); 30 31 /** 32 * Returns if the named option was specified explicitly in a call to parse. 33 */ containsExplicitOption(String string)34 boolean containsExplicitOption(String string); 35 36 /** 37 * Returns a mutable copy of the list of all options that were specified either explicitly or 38 * implicitly. These options are sorted by priority, and by the order in which they were 39 * specified. If an option was specified multiple times, it is included in the result multiple 40 * times. Does not include the residue. 41 * 42 * <p>The returned list includes undocumented, hidden or implicit options, and should be filtered 43 * as needed. Since it includes all options parsed, it will also include both an expansion option 44 * and the options it expanded to, and so blindly using this list for a new invocation will cause 45 * double-application of these options. 46 */ asCompleteListOfParsedOptions()47 List<ParsedOptionDescription> asCompleteListOfParsedOptions(); 48 49 /** 50 * Returns a list of all explicitly specified options, suitable for logging or for displaying back 51 * to the user. These options are sorted by priority, and by the order in which they were 52 * specified. If an option was explicitly specified multiple times, it is included in the result 53 * multiple times. Does not include the residue. 54 * 55 * <p>The list includes undocumented options. 56 */ asListOfExplicitOptions()57 List<ParsedOptionDescription> asListOfExplicitOptions(); 58 59 /** 60 * Returns a list of the parsed options whose values are in the final value of the option, i.e. 61 * the options that were added explicitly, expanded if necessary to the valued options they 62 * affect. This will not include values that were set and then overridden by a later value of the 63 * same option. 64 * 65 * <p>The list includes undocumented options. 66 */ asListOfCanonicalOptions()67 List<ParsedOptionDescription> asListOfCanonicalOptions(); 68 69 /** 70 * Returns a list of all options, including undocumented ones, and their effective values. There 71 * is no guaranteed ordering for the result. 72 */ asListOfOptionValues()73 List<OptionValueDescription> asListOfOptionValues(); 74 75 /** 76 * Canonicalizes the list of options that this OptionsParser has parsed. 77 * 78 * <p>The contract is that if the returned set of options is passed to an options parser with the 79 * same options classes, then that will have the same effect as using the original args (which are 80 * passed in here), except for cosmetic differences. We do not guarantee that the 'canonical' list 81 * is unique, since some flags may have effects unknown to the parser (--config, for Bazel), so we 82 * do not reorder flags to further simplify the list. 83 */ canonicalize()84 List<String> canonicalize(); 85 } 86