1 #!/usr/bin/env python 2 3 """ 4 Reference abstractions. 5 6 Copyright (C) 2016 Paul Boddie <paul@boddie.org.uk> 7 8 This program is free software; you can redistribute it and/or modify it under 9 the terms of the GNU General Public License as published by the Free Software 10 Foundation; either version 3 of the License, or (at your option) any later 11 version. 12 13 This program is distributed in the hope that it will be useful, but WITHOUT 14 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 15 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 16 details. 17 18 You should have received a copy of the GNU General Public License along with 19 this program. If not, see <http://www.gnu.org/licenses/>. 20 """ 21 22 class Reference: 23 24 "A reference abstraction." 25 26 def __init__(self, kind, origin=None, name=None): 27 28 """ 29 Initialise a reference using 'kind' to indicate the kind of object, 30 'origin' to indicate the actual origin of a referenced object, and a 31 'name' indicating an alias for the object in the program structure. 32 """ 33 34 if isinstance(kind, Reference): 35 raise ValueError, (kind, origin) 36 self.kind = kind 37 self.origin = origin 38 self.name = name 39 40 def __repr__(self): 41 return "Reference(%r, %r, %r)" % (self.kind, self.origin, self.name) 42 43 def __str__(self): 44 45 """ 46 Serialise the reference as '<var>' or a description incorporating the 47 kind and origin. 48 """ 49 50 if self.kind == "<var>": 51 return self.kind 52 else: 53 alias = self.name and self.name != self.origin and ";%s" % self.name or "" 54 return "%s:%s%s" % (self.kind, self.origin, alias) 55 56 def __hash__(self): 57 58 "Hash instances using the kind and origin only." 59 60 return hash((self.kind, self.get_origin())) 61 62 def __cmp__(self, other): 63 64 "Compare with 'other' using the kind and origin only." 65 66 if isinstance(other, Reference): 67 return cmp((self.kind, self.get_origin()), (other.kind, other.get_origin())) 68 else: 69 return cmp(str(self), other) 70 71 def get_name(self): 72 73 "Return the name used for this reference." 74 75 return self.name 76 77 def get_origin(self): 78 79 "Return the origin of the reference." 80 81 return self.kind != "<var>" and self.origin or None 82 83 def get_kind(self): 84 85 "Return the kind of object referenced." 86 87 return self.kind 88 89 def has_kind(self, kinds): 90 91 """ 92 Return whether the reference describes an object from the given 'kinds', 93 where such kinds may be "<class>", "<function>", "<instance>", 94 "<module>" or "<var>". Unresolved references may also have kinds of 95 "<depends>" and "<invoke>". 96 """ 97 98 if not isinstance(kinds, (list, tuple)): 99 kinds = [kinds] 100 return self.get_kind() in kinds 101 102 def get_path(self): 103 104 "Return the attribute names comprising the path to the origin." 105 106 return self.get_origin().split(".") 107 108 def unresolved(self): 109 110 "Return whether this reference is unresolved." 111 112 return self.has_kind(["<depends>", "<invoke>"]) 113 114 def static(self): 115 116 "Return this reference if it refers to a static object, None otherwise." 117 118 return self.has_kind(["<class>", "<function>", "<module>"]) and self or None 119 120 def final(self): 121 122 "Return a reference to either a static object or None." 123 124 static = self.static() 125 return static and static.origin or None 126 127 def instance_of(self): 128 129 "Return a reference to an instance of the referenced class." 130 131 return self.has_kind("<class>") and Reference("<instance>", self.origin) or None 132 133 def as_var(self): 134 135 """ 136 Return a variable version of this reference. Any origin information is 137 discarded since variable references are deliberately ambiguous. 138 """ 139 140 return Reference("<var>", None, self.name) 141 142 def alias(self, name): 143 144 "Alias this reference employing 'name'." 145 146 return Reference(self.get_kind(), self.get_origin(), name) 147 148 def unaliased(self): 149 150 "Return this reference without any alias." 151 152 return Reference(self.get_kind(), self.get_origin()) 153 154 def mutate(self, ref): 155 156 "Mutate this reference to have the same details as 'ref'." 157 158 self.kind = ref.kind 159 self.origin = ref.origin 160 self.name = ref.name 161 162 def parent(self): 163 164 "Return the parent of this reference's origin." 165 166 if not self.get_origin(): 167 return None 168 169 return self.get_origin().rsplit(".", 1)[0] 170 171 def name_parent(self): 172 173 "Return the parent of this reference's aliased name." 174 175 if not self.get_name(): 176 return None 177 178 return self.get_name().rsplit(".", 1)[0] 179 180 def ancestors(self): 181 182 """ 183 Return ancestors of this reference's origin in order of decreasing 184 depth. 185 """ 186 187 if not self.get_origin(): 188 return None 189 190 parts = self.get_origin().split(".") 191 ancestors = [] 192 193 for i in range(len(parts) - 1, 0, -1): 194 ancestors.append(".".join(parts[:i])) 195 196 return ancestors 197 198 def get_types(self): 199 200 "Return class, instance-only and module types for this reference." 201 202 class_types = self.has_kind("<class>") and [self.get_origin()] or [] 203 instance_types = [] 204 module_types = self.has_kind("<module>") and [self.get_origin()] or [] 205 return class_types, instance_types, module_types 206 207 def decode_reference(s, name=None): 208 209 "Decode 's', making a reference." 210 211 if isinstance(s, Reference): 212 return s.alias(name) 213 214 # Null value. 215 216 elif not s: 217 return Reference("<var>", None, name) 218 219 # Kind and origin. 220 221 elif ":" in s: 222 kind, origin = s.split(":") 223 if ";" in origin: 224 origin, name = origin.split(";") 225 return Reference(kind, origin, name) 226 227 # Kind-only, origin is indicated name. 228 229 elif s[0] == "<": 230 return Reference(s, name, name) 231 232 # Module-only. 233 234 else: 235 return Reference("<module>", s, name) 236 237 238 239 # Type/reference collection functions. 240 241 def is_single_class_type(all_types): 242 243 """ 244 Return whether 'all_types' is a mixture of class and instance kinds for 245 a single class type. 246 """ 247 248 kinds = set() 249 types = set() 250 251 for type in all_types: 252 kinds.add(type.get_kind()) 253 types.add(type.get_origin()) 254 255 return len(types) == 1 and kinds == set(["<class>", "<instance>"]) 256 257 def combine_types(class_types, instance_types, module_types): 258 259 """ 260 Combine 'class_types', 'instance_types', 'module_types' into a single 261 list of references. 262 """ 263 264 all_types = [] 265 for kind, l in [("<class>", class_types), ("<instance>", instance_types), ("<module>", module_types)]: 266 for t in l: 267 all_types.append(Reference(kind, t)) 268 return all_types 269 270 def separate_types(refs): 271 272 """ 273 Separate 'refs' into type-specific lists, returning a tuple containing 274 lists of class types, instance types, module types, function types and 275 unknown "var" types. 276 """ 277 278 class_types = [] 279 instance_types = [] 280 module_types = [] 281 function_types = [] 282 var_types = [] 283 284 for kind, l in [ 285 ("<class>", class_types), ("<instance>", instance_types), ("<module>", module_types), 286 ("<function>", function_types), ("<var>", var_types) 287 ]: 288 289 for ref in refs: 290 if ref.get_kind() == kind: 291 l.append(ref.get_origin()) 292 293 return class_types, instance_types, module_types, function_types, var_types 294 295 # vim: tabstop=4 expandtab shiftwidth=4