1 # Copyright 2013 The Chromium Authors. All rights reserved. 2 # Use of this source code is governed by a BSD-style license that can be 3 # found in the LICENSE file. 4 5 """Configuration variable management for the cr tool. 6 7 This holds the classes that support the hierarchical variable management used 8 in the cr tool to provide all the command configuration controls. 9 """ 10 11 import string 12 13 import cr.visitor 14 15 _PARSE_CONSTANT_VALUES = [None, True, False] 16 _PARSE_CONSTANTS = dict((str(value), value) for value in _PARSE_CONSTANT_VALUES) 17 18 # GLOBALS is the singleton used to tie static global configuration objects 19 # together. 20 GLOBALS = [] 21 22 23 class _MissingToErrorFormatter(string.Formatter): 24 """A string formatter used in value resolve. 25 26 The main extra it adds is a new conversion specifier 'e' that throws a 27 KeyError if it could not find the value. 28 This allows a string value to use {A_KEY!e} to indicate that it is a 29 formatting error if A_KEY is not present. 30 """ 31 32 def convert_field(self, value, conversion): 33 if conversion == 'e': 34 result = str(value) 35 if not result: 36 raise KeyError('unknown') 37 return result 38 return super(_MissingToErrorFormatter, self).convert_field( 39 value, conversion) 40 41 42 class _Tracer(object): 43 """Traces variable lookups. 44 45 This adds a hook to a config object, and uses it to track all variable 46 lookups that happen and add them to a trail. When done, it removes the hook 47 again. This is used to provide debugging information about what variables are 48 used in an operation. 49 """ 50 51 def __init__(self, config): 52 self.config = config 53 self.trail = [] 54 55 def __enter__(self): 56 self.config.fixup_hooks.append(self._Trace) 57 return self 58 59 def __exit__(self, *_): 60 self.config.fixup_hooks.remove(self._Trace) 61 self.config.trail = self.trail 62 return False 63 64 def _Trace(self, _, key, value): 65 self.trail.append((key, value)) 66 return value 67 68 69 class Config(cr.visitor.Node, cr.loader.AutoExport): 70 """The main variable holding class. 71 72 This holds a set of unresolved key value pairs, and the set of child Config 73 objects that should be referenced when looking up a key. 74 Key search is one in a pre-order traversal, and new children are prepended. 75 This means parents override children, and the most recently added child 76 overrides the rest. 77 78 Values can be simple python types, callable dynamic values, or strings. 79 If the value is a string, it is assumed to be a standard python format string 80 where the root config object is used to resolve the keys. This allows values 81 to refer to variables that are overriden in another part of the hierarchy. 82 """ 83 84 @classmethod 85 def From(cls, *args, **kwargs): 86 """Builds an unnamed config object from a set of key,value args.""" 87 return Config('??').Apply(args, kwargs) 88 89 @classmethod 90 def If(cls, condition, true_value, false_value=''): 91 """Returns a config value that selects a value based on the condition. 92 93 Args: 94 condition: The variable name to select a value on. 95 true_value: The value to use if the variable is True. 96 false_value: The value to use if the resolved variable is False. 97 Returns: 98 A dynamic value. 99 """ 100 def Resolve(base): 101 test = base.Get(condition) 102 if test: 103 value = true_value 104 else: 105 value = false_value 106 return base.Substitute(value) 107 return Resolve 108 109 @classmethod 110 def Optional(cls, value, alternate=''): 111 """Returns a dynamic value that defaults to an alternate. 112 113 Args: 114 value: The main value to resolve. 115 alternate: The value to use if the main value does not resolve. 116 Returns: 117 value if it resolves, alternate otherwise. 118 """ 119 def Resolve(base): 120 try: 121 return base.Substitute(value) 122 except KeyError: 123 return base.Substitute(alternate) 124 return Resolve 125 126 def __init__(self, name='--', literal=False, export=None, enabled=True): 127 super(Config, self).__init__(name=name, enabled=enabled, export=export) 128 self._literal = literal 129 self._formatter = _MissingToErrorFormatter() 130 self.fixup_hooks = [] 131 self.trail = [] 132 133 @property 134 def literal(self): 135 return self._literal 136 137 def Substitute(self, value): 138 return self._formatter.vformat(str(value), (), self) 139 140 def Resolve(self, visitor, key, value): 141 """Resolves a value to it's final form. 142 143 Raw values can be callable, simple values, or contain format strings. 144 Args: 145 visitor: The visitor asking to resolve a value. 146 key: The key being visited. 147 value: The unresolved value associated with the key. 148 Returns: 149 the fully resolved value. 150 """ 151 error = None 152 if callable(value): 153 value = value(self) 154 # Using existence of value.swapcase as a proxy for is a string 155 elif hasattr(value, 'swapcase'): 156 if not visitor.current_node.literal: 157 try: 158 value = self.Substitute(value) 159 except KeyError as e: 160 error = e 161 return self.Fixup(key, value), error 162 163 def Fixup(self, key, value): 164 for hook in self.fixup_hooks: 165 value = hook(self, key, value) 166 return value 167 168 def Missing(self, key): 169 for hook in self.fixup_hooks: 170 hook(self, key, None) 171 raise KeyError(key) 172 173 @staticmethod 174 def ParseValue(value): 175 """Converts a string to a value. 176 177 Takes a string from something like an environment variable, and tries to 178 build an internal typed value. Recognizes Null, booleans, and numbers as 179 special. 180 Args: 181 value: The the string value to interpret. 182 Returns: 183 the parsed form of the value. 184 """ 185 if value in _PARSE_CONSTANTS: 186 return _PARSE_CONSTANTS[value] 187 try: 188 return int(value) 189 except ValueError: 190 pass 191 try: 192 return float(value) 193 except ValueError: 194 pass 195 return value 196 197 def _Set(self, key, value): 198 # early out if the value did not change, so we don't call change callbacks 199 if value == self._values.get(key, None): 200 return 201 self._values[key] = value 202 self.NotifyChanged() 203 return self 204 205 def ApplyMap(self, arg): 206 for key, value in arg.items(): 207 self._Set(key, value) 208 return self 209 210 def Apply(self, args, kwargs): 211 """Bulk set variables from arguments. 212 213 Intended for internal use by the Set and From methods. 214 Args: 215 args: must be either a dict or something that can build a dict. 216 kwargs: must be a dict. 217 Returns: 218 self for easy chaining. 219 """ 220 if len(args) == 1: 221 arg = args[0] 222 if isinstance(arg, dict): 223 self.ApplyMap(arg) 224 else: 225 self.ApplyMap(dict(arg)) 226 elif len(args) > 1: 227 self.ApplyMap(dict(args)) 228 self.ApplyMap(kwargs) 229 return self 230 231 def Set(self, *args, **kwargs): 232 return self.Apply(args, kwargs) 233 234 def Trace(self): 235 return _Tracer(self) 236 237 def __getitem__(self, key): 238 return self.Get(key) 239 240 def __setitem__(self, key, value): 241 self._Set(key, value) 242 243 def __contains__(self, key): 244 return self.Find(key) is not None 245