cindex.py revision da6a6f087b70cdac18c37028f8cff707f10f91cf
1#===- cindex.py - Python Indexing Library Bindings -----------*- python -*--===# 2# 3# The LLVM Compiler Infrastructure 4# 5# This file is distributed under the University of Illinois Open Source 6# License. See LICENSE.TXT for details. 7# 8#===------------------------------------------------------------------------===# 9 10r""" 11Clang Indexing Library Bindings 12=============================== 13 14This module provides an interface to the Clang indexing library. It is a 15low-level interface to the indexing library which attempts to match the Clang 16API directly while also being "pythonic". Notable differences from the C API 17are: 18 19 * string results are returned as Python strings, not CXString objects. 20 21 * null cursors are translated to None. 22 23 * access to child cursors is done via iteration, not visitation. 24 25The major indexing objects are: 26 27 Index 28 29 The top-level object which manages some global library state. 30 31 TranslationUnit 32 33 High-level object encapsulating the AST for a single translation unit. These 34 can be loaded from .ast files or parsed on the fly. 35 36 Cursor 37 38 Generic object for representing a node in the AST. 39 40 SourceRange, SourceLocation, and File 41 42 Objects representing information about the input source. 43 44Most object information is exposed using properties, when the underlying API 45call is efficient. 46""" 47 48# TODO 49# ==== 50# 51# o API support for invalid translation units. Currently we can't even get the 52# diagnostics on failure because they refer to locations in an object that 53# will have been invalidated. 54# 55# o fix memory management issues (currently client must hold on to index and 56# translation unit, or risk crashes). 57# 58# o expose code completion APIs. 59# 60# o cleanup ctypes wrapping, would be nice to separate the ctypes details more 61# clearly, and hide from the external interface (i.e., help(cindex)). 62# 63# o implement additional SourceLocation, SourceRange, and File methods. 64 65from ctypes import * 66import collections 67 68import clang.enumerations 69 70# ctypes doesn't implicitly convert c_void_p to the appropriate wrapper 71# object. This is a problem, because it means that from_parameter will see an 72# integer and pass the wrong value on platforms where int != void*. Work around 73# this by marshalling object arguments as void**. 74c_object_p = POINTER(c_void_p) 75 76callbacks = {} 77 78### Exception Classes ### 79 80class TranslationUnitLoadError(Exception): 81 """Represents an error that occurred when loading a TranslationUnit. 82 83 This is raised in the case where a TranslationUnit could not be 84 instantiated due to failure in the libclang library. 85 86 FIXME: Make libclang expose additional error information in this scenario. 87 """ 88 pass 89 90class TranslationUnitSaveError(Exception): 91 """Represents an error that occurred when saving a TranslationUnit. 92 93 Each error has associated with it an enumerated value, accessible under 94 e.save_error. Consumers can compare the value with one of the ERROR_ 95 constants in this class. 96 """ 97 98 # Indicates that an unknown error occurred. This typically indicates that 99 # I/O failed during save. 100 ERROR_UNKNOWN = 1 101 102 # Indicates that errors during translation prevented saving. The errors 103 # should be available via the TranslationUnit's diagnostics. 104 ERROR_TRANSLATION_ERRORS = 2 105 106 # Indicates that the translation unit was somehow invalid. 107 ERROR_INVALID_TU = 3 108 109 def __init__(self, enumeration, message): 110 assert isinstance(enumeration, int) 111 112 if enumeration < 1 or enumeration > 3: 113 raise Exception("Encountered undefined TranslationUnit save error " 114 "constant: %d. Please file a bug to have this " 115 "value supported." % enumeration) 116 117 self.save_error = enumeration 118 Exception.__init__(self, 'Error %d: %s' % (enumeration, message)) 119 120### Structures and Utility Classes ### 121 122class CachedProperty(object): 123 """Decorator that lazy-loads the value of a property. 124 125 The first time the property is accessed, the original property function is 126 executed. The value it returns is set as the new value of that instance's 127 property, replacing the original method. 128 """ 129 130 def __init__(self, wrapped): 131 self.wrapped = wrapped 132 try: 133 self.__doc__ = wrapped.__doc__ 134 except: 135 pass 136 137 def __get__(self, instance, instance_type=None): 138 if instance is None: 139 return self 140 141 value = self.wrapped(instance) 142 setattr(instance, self.wrapped.__name__, value) 143 144 return value 145 146 147class _CXString(Structure): 148 """Helper for transforming CXString results.""" 149 150 _fields_ = [("spelling", c_char_p), ("free", c_int)] 151 152 def __del__(self): 153 conf.lib.clang_disposeString(self) 154 155 @staticmethod 156 def from_result(res, fn, args): 157 assert isinstance(res, _CXString) 158 return conf.lib.clang_getCString(res) 159 160class SourceLocation(Structure): 161 """ 162 A SourceLocation represents a particular location within a source file. 163 """ 164 _fields_ = [("ptr_data", c_void_p * 2), ("int_data", c_uint)] 165 _data = None 166 167 def _get_instantiation(self): 168 if self._data is None: 169 f, l, c, o = c_object_p(), c_uint(), c_uint(), c_uint() 170 conf.lib.clang_getInstantiationLocation(self, byref(f), byref(l), 171 byref(c), byref(o)) 172 if f: 173 f = File(f) 174 else: 175 f = None 176 self._data = (f, int(l.value), int(c.value), int(o.value)) 177 return self._data 178 179 @staticmethod 180 def from_position(tu, file, line, column): 181 """ 182 Retrieve the source location associated with a given file/line/column in 183 a particular translation unit. 184 """ 185 return conf.lib.clang_getLocation(tu, file, line, column) 186 187 @staticmethod 188 def from_offset(tu, file, offset): 189 """Retrieve a SourceLocation from a given character offset. 190 191 tu -- TranslationUnit file belongs to 192 file -- File instance to obtain offset from 193 offset -- Integer character offset within file 194 """ 195 return conf.lib.clang_getLocationForOffset(tu, file, offset) 196 197 @property 198 def file(self): 199 """Get the file represented by this source location.""" 200 return self._get_instantiation()[0] 201 202 @property 203 def line(self): 204 """Get the line represented by this source location.""" 205 return self._get_instantiation()[1] 206 207 @property 208 def column(self): 209 """Get the column represented by this source location.""" 210 return self._get_instantiation()[2] 211 212 @property 213 def offset(self): 214 """Get the file offset represented by this source location.""" 215 return self._get_instantiation()[3] 216 217 def __eq__(self, other): 218 return conf.lib.clang_equalLocations(self, other) 219 220 def __ne__(self, other): 221 return not self.__eq__(other) 222 223 def __repr__(self): 224 if self.file: 225 filename = self.file.name 226 else: 227 filename = None 228 return "<SourceLocation file %r, line %r, column %r>" % ( 229 filename, self.line, self.column) 230 231class SourceRange(Structure): 232 """ 233 A SourceRange describes a range of source locations within the source 234 code. 235 """ 236 _fields_ = [ 237 ("ptr_data", c_void_p * 2), 238 ("begin_int_data", c_uint), 239 ("end_int_data", c_uint)] 240 241 # FIXME: Eliminate this and make normal constructor? Requires hiding ctypes 242 # object. 243 @staticmethod 244 def from_locations(start, end): 245 return conf.lib.clang_getRange(start, end) 246 247 @property 248 def start(self): 249 """ 250 Return a SourceLocation representing the first character within a 251 source range. 252 """ 253 return conf.lib.clang_getRangeStart(self) 254 255 @property 256 def end(self): 257 """ 258 Return a SourceLocation representing the last character within a 259 source range. 260 """ 261 return conf.lib.clang_getRangeEnd(self) 262 263 def __eq__(self, other): 264 return conf.lib.clang_equalRanges(self, other) 265 266 def __ne__(self, other): 267 return not self.__eq__(other) 268 269 def __repr__(self): 270 return "<SourceRange start %r, end %r>" % (self.start, self.end) 271 272class Diagnostic(object): 273 """ 274 A Diagnostic is a single instance of a Clang diagnostic. It includes the 275 diagnostic severity, the message, the location the diagnostic occurred, as 276 well as additional source ranges and associated fix-it hints. 277 """ 278 279 Ignored = 0 280 Note = 1 281 Warning = 2 282 Error = 3 283 Fatal = 4 284 285 def __init__(self, ptr): 286 self.ptr = ptr 287 288 def __del__(self): 289 conf.lib.clang_disposeDiagnostic(self) 290 291 @property 292 def severity(self): 293 return conf.lib.clang_getDiagnosticSeverity(self) 294 295 @property 296 def location(self): 297 return conf.lib.clang_getDiagnosticLocation(self) 298 299 @property 300 def spelling(self): 301 return conf.lib.clang_getDiagnosticSpelling(self) 302 303 @property 304 def ranges(self): 305 class RangeIterator: 306 def __init__(self, diag): 307 self.diag = diag 308 309 def __len__(self): 310 return int(conf.lib.clang_getDiagnosticNumRanges(self.diag)) 311 312 def __getitem__(self, key): 313 if (key >= len(self)): 314 raise IndexError 315 return conf.lib.clang_getDiagnosticRange(self.diag, key) 316 317 return RangeIterator(self) 318 319 @property 320 def fixits(self): 321 class FixItIterator: 322 def __init__(self, diag): 323 self.diag = diag 324 325 def __len__(self): 326 return int(conf.lib.clang_getDiagnosticNumFixIts(self.diag)) 327 328 def __getitem__(self, key): 329 range = SourceRange() 330 value = conf.lib.clang_getDiagnosticFixIt(self.diag, key, 331 byref(range)) 332 if len(value) == 0: 333 raise IndexError 334 335 return FixIt(range, value) 336 337 return FixItIterator(self) 338 339 @property 340 def category_number(self): 341 """The category number for this diagnostic.""" 342 return conf.lib.clang_getDiagnosticCategory(self) 343 344 @property 345 def category_name(self): 346 """The string name of the category for this diagnostic.""" 347 return conf.lib.clang_getDiagnosticCategoryName(self.category_number) 348 349 @property 350 def option(self): 351 """The command-line option that enables this diagnostic.""" 352 return conf.lib.clang_getDiagnosticOption(self, None) 353 354 @property 355 def disable_option(self): 356 """The command-line option that disables this diagnostic.""" 357 disable = _CXString() 358 conf.lib.clang_getDiagnosticOption(self, byref(disable)) 359 360 return conf.lib.clang_getCString(disable) 361 362 def __repr__(self): 363 return "<Diagnostic severity %r, location %r, spelling %r>" % ( 364 self.severity, self.location, self.spelling) 365 366 def from_param(self): 367 return self.ptr 368 369class FixIt(object): 370 """ 371 A FixIt represents a transformation to be applied to the source to 372 "fix-it". The fix-it shouldbe applied by replacing the given source range 373 with the given value. 374 """ 375 376 def __init__(self, range, value): 377 self.range = range 378 self.value = value 379 380 def __repr__(self): 381 return "<FixIt range %r, value %r>" % (self.range, self.value) 382 383class TokenGroup(object): 384 """Helper class to facilitate token management. 385 386 Tokens are allocated from libclang in chunks. They must be disposed of as a 387 collective group. 388 389 One purpose of this class is for instances to represent groups of allocated 390 tokens. Each token in a group contains a reference back to an instance of 391 this class. When all tokens from a group are garbage collected, it allows 392 this class to be garbage collected. When this class is garbage collected, 393 it calls the libclang destructor which invalidates all tokens in the group. 394 395 You should not instantiate this class outside of this module. 396 """ 397 def __init__(self, tu, memory, count): 398 self._tu = tu 399 self._memory = memory 400 self._count = count 401 402 def __del__(self): 403 conf.lib.clang_disposeTokens(self._tu, self._memory, self._count) 404 405 @staticmethod 406 def get_tokens(tu, extent): 407 """Helper method to return all tokens in an extent. 408 409 This functionality is needed multiple places in this module. We define 410 it here because it seems like a logical place. 411 """ 412 tokens_memory = POINTER(Token)() 413 tokens_count = c_uint() 414 415 conf.lib.clang_tokenize(tu, extent, byref(tokens_memory), 416 byref(tokens_count)) 417 418 count = int(tokens_count.value) 419 420 # If we get no tokens, no memory was allocated. Be sure not to return 421 # anything and potentially call a destructor on nothing. 422 if count < 1: 423 return 424 425 tokens_array = cast(tokens_memory, POINTER(Token * count)).contents 426 427 token_group = TokenGroup(tu, tokens_memory, tokens_count) 428 429 for i in xrange(0, count): 430 token = Token() 431 token.int_data = tokens_array[i].int_data 432 token.ptr_data = tokens_array[i].ptr_data 433 token._tu = tu 434 token._group = token_group 435 436 yield token 437 438class TokenKind(object): 439 """Describes a specific type of a Token.""" 440 441 _value_map = {} # int -> TokenKind 442 443 def __init__(self, value, name): 444 """Create a new TokenKind instance from a numeric value and a name.""" 445 self.value = value 446 self.name = name 447 448 def __repr__(self): 449 return 'TokenKind.%s' % (self.name,) 450 451 @staticmethod 452 def from_value(value): 453 """Obtain a registered TokenKind instance from its value.""" 454 result = TokenKind._value_map.get(value, None) 455 456 if result is None: 457 raise ValueError('Unknown TokenKind: %d' % value) 458 459 return result 460 461 @staticmethod 462 def register(value, name): 463 """Register a new TokenKind enumeration. 464 465 This should only be called at module load time by code within this 466 package. 467 """ 468 if value in TokenKind._value_map: 469 raise ValueError('TokenKind already registered: %d' % value) 470 471 kind = TokenKind(value, name) 472 TokenKind._value_map[value] = kind 473 setattr(TokenKind, name, kind) 474 475### Cursor Kinds ### 476 477class CursorKind(object): 478 """ 479 A CursorKind describes the kind of entity that a cursor points to. 480 """ 481 482 # The unique kind objects, indexed by id. 483 _kinds = [] 484 _name_map = None 485 486 def __init__(self, value): 487 if value >= len(CursorKind._kinds): 488 CursorKind._kinds += [None] * (value - len(CursorKind._kinds) + 1) 489 if CursorKind._kinds[value] is not None: 490 raise ValueError,'CursorKind already loaded' 491 self.value = value 492 CursorKind._kinds[value] = self 493 CursorKind._name_map = None 494 495 def from_param(self): 496 return self.value 497 498 @property 499 def name(self): 500 """Get the enumeration name of this cursor kind.""" 501 if self._name_map is None: 502 self._name_map = {} 503 for key,value in CursorKind.__dict__.items(): 504 if isinstance(value,CursorKind): 505 self._name_map[value] = key 506 return self._name_map[self] 507 508 @staticmethod 509 def from_id(id): 510 if id >= len(CursorKind._kinds) or CursorKind._kinds[id] is None: 511 raise ValueError,'Unknown cursor kind %d' % id 512 return CursorKind._kinds[id] 513 514 @staticmethod 515 def get_all_kinds(): 516 """Return all CursorKind enumeration instances.""" 517 return filter(None, CursorKind._kinds) 518 519 def is_declaration(self): 520 """Test if this is a declaration kind.""" 521 return conf.lib.clang_isDeclaration(self) 522 523 def is_reference(self): 524 """Test if this is a reference kind.""" 525 return conf.lib.clang_isReference(self) 526 527 def is_expression(self): 528 """Test if this is an expression kind.""" 529 return conf.lib.clang_isExpression(self) 530 531 def is_statement(self): 532 """Test if this is a statement kind.""" 533 return conf.lib.clang_isStatement(self) 534 535 def is_attribute(self): 536 """Test if this is an attribute kind.""" 537 return conf.lib.clang_isAttribute(self) 538 539 def is_invalid(self): 540 """Test if this is an invalid kind.""" 541 return conf.lib.clang_isInvalid(self) 542 543 def is_translation_unit(self): 544 """Test if this is a translation unit kind.""" 545 return conf.lib.clang_isTranslationUnit(self) 546 547 def is_preprocessing(self): 548 """Test if this is a preprocessing kind.""" 549 return conf.lib.clang_isPreprocessing(self) 550 551 def is_unexposed(self): 552 """Test if this is an unexposed kind.""" 553 return conf.lib.clang_isUnexposed(self) 554 555 def __repr__(self): 556 return 'CursorKind.%s' % (self.name,) 557 558# FIXME: Is there a nicer way to expose this enumeration? We could potentially 559# represent the nested structure, or even build a class hierarchy. The main 560# things we want for sure are (a) simple external access to kinds, (b) a place 561# to hang a description and name, (c) easy to keep in sync with Index.h. 562 563### 564# Declaration Kinds 565 566# A declaration whose specific kind is not exposed via this interface. 567# 568# Unexposed declarations have the same operations as any other kind of 569# declaration; one can extract their location information, spelling, find their 570# definitions, etc. However, the specific kind of the declaration is not 571# reported. 572CursorKind.UNEXPOSED_DECL = CursorKind(1) 573 574# A C or C++ struct. 575CursorKind.STRUCT_DECL = CursorKind(2) 576 577# A C or C++ union. 578CursorKind.UNION_DECL = CursorKind(3) 579 580# A C++ class. 581CursorKind.CLASS_DECL = CursorKind(4) 582 583# An enumeration. 584CursorKind.ENUM_DECL = CursorKind(5) 585 586# A field (in C) or non-static data member (in C++) in a struct, union, or C++ 587# class. 588CursorKind.FIELD_DECL = CursorKind(6) 589 590# An enumerator constant. 591CursorKind.ENUM_CONSTANT_DECL = CursorKind(7) 592 593# A function. 594CursorKind.FUNCTION_DECL = CursorKind(8) 595 596# A variable. 597CursorKind.VAR_DECL = CursorKind(9) 598 599# A function or method parameter. 600CursorKind.PARM_DECL = CursorKind(10) 601 602# An Objective-C @interface. 603CursorKind.OBJC_INTERFACE_DECL = CursorKind(11) 604 605# An Objective-C @interface for a category. 606CursorKind.OBJC_CATEGORY_DECL = CursorKind(12) 607 608# An Objective-C @protocol declaration. 609CursorKind.OBJC_PROTOCOL_DECL = CursorKind(13) 610 611# An Objective-C @property declaration. 612CursorKind.OBJC_PROPERTY_DECL = CursorKind(14) 613 614# An Objective-C instance variable. 615CursorKind.OBJC_IVAR_DECL = CursorKind(15) 616 617# An Objective-C instance method. 618CursorKind.OBJC_INSTANCE_METHOD_DECL = CursorKind(16) 619 620# An Objective-C class method. 621CursorKind.OBJC_CLASS_METHOD_DECL = CursorKind(17) 622 623# An Objective-C @implementation. 624CursorKind.OBJC_IMPLEMENTATION_DECL = CursorKind(18) 625 626# An Objective-C @implementation for a category. 627CursorKind.OBJC_CATEGORY_IMPL_DECL = CursorKind(19) 628 629# A typedef. 630CursorKind.TYPEDEF_DECL = CursorKind(20) 631 632# A C++ class method. 633CursorKind.CXX_METHOD = CursorKind(21) 634 635# A C++ namespace. 636CursorKind.NAMESPACE = CursorKind(22) 637 638# A linkage specification, e.g. 'extern "C"'. 639CursorKind.LINKAGE_SPEC = CursorKind(23) 640 641# A C++ constructor. 642CursorKind.CONSTRUCTOR = CursorKind(24) 643 644# A C++ destructor. 645CursorKind.DESTRUCTOR = CursorKind(25) 646 647# A C++ conversion function. 648CursorKind.CONVERSION_FUNCTION = CursorKind(26) 649 650# A C++ template type parameter 651CursorKind.TEMPLATE_TYPE_PARAMETER = CursorKind(27) 652 653# A C++ non-type template paramater. 654CursorKind.TEMPLATE_NON_TYPE_PARAMETER = CursorKind(28) 655 656# A C++ template template parameter. 657CursorKind.TEMPLATE_TEMPLATE_PARAMETER = CursorKind(29) 658 659# A C++ function template. 660CursorKind.FUNCTION_TEMPLATE = CursorKind(30) 661 662# A C++ class template. 663CursorKind.CLASS_TEMPLATE = CursorKind(31) 664 665# A C++ class template partial specialization. 666CursorKind.CLASS_TEMPLATE_PARTIAL_SPECIALIZATION = CursorKind(32) 667 668# A C++ namespace alias declaration. 669CursorKind.NAMESPACE_ALIAS = CursorKind(33) 670 671# A C++ using directive 672CursorKind.USING_DIRECTIVE = CursorKind(34) 673 674# A C++ using declaration 675CursorKind.USING_DECLARATION = CursorKind(35) 676 677# A Type alias decl. 678CursorKind.TYPE_ALIAS_DECL = CursorKind(36) 679 680# A Objective-C synthesize decl 681CursorKind.OBJC_SYNTHESIZE_DECL = CursorKind(37) 682 683# A Objective-C dynamic decl 684CursorKind.OBJC_DYNAMIC_DECL = CursorKind(38) 685 686# A C++ access specifier decl. 687CursorKind.CXX_ACCESS_SPEC_DECL = CursorKind(39) 688 689 690### 691# Reference Kinds 692 693CursorKind.OBJC_SUPER_CLASS_REF = CursorKind(40) 694CursorKind.OBJC_PROTOCOL_REF = CursorKind(41) 695CursorKind.OBJC_CLASS_REF = CursorKind(42) 696 697# A reference to a type declaration. 698# 699# A type reference occurs anywhere where a type is named but not 700# declared. For example, given: 701# typedef unsigned size_type; 702# size_type size; 703# 704# The typedef is a declaration of size_type (CXCursor_TypedefDecl), 705# while the type of the variable "size" is referenced. The cursor 706# referenced by the type of size is the typedef for size_type. 707CursorKind.TYPE_REF = CursorKind(43) 708CursorKind.CXX_BASE_SPECIFIER = CursorKind(44) 709 710# A reference to a class template, function template, template 711# template parameter, or class template partial specialization. 712CursorKind.TEMPLATE_REF = CursorKind(45) 713 714# A reference to a namespace or namepsace alias. 715CursorKind.NAMESPACE_REF = CursorKind(46) 716 717# A reference to a member of a struct, union, or class that occurs in 718# some non-expression context, e.g., a designated initializer. 719CursorKind.MEMBER_REF = CursorKind(47) 720 721# A reference to a labeled statement. 722CursorKind.LABEL_REF = CursorKind(48) 723 724# A reference to a set of overloaded functions or function templates 725# that has not yet been resolved to a specific function or function template. 726CursorKind.OVERLOADED_DECL_REF = CursorKind(49) 727 728# A reference to a variable that occurs in some non-expression 729# context, e.g., a C++ lambda capture list. 730CursorKind.VARIABLE_REF = CursorKind(50) 731 732### 733# Invalid/Error Kinds 734 735CursorKind.INVALID_FILE = CursorKind(70) 736CursorKind.NO_DECL_FOUND = CursorKind(71) 737CursorKind.NOT_IMPLEMENTED = CursorKind(72) 738CursorKind.INVALID_CODE = CursorKind(73) 739 740### 741# Expression Kinds 742 743# An expression whose specific kind is not exposed via this interface. 744# 745# Unexposed expressions have the same operations as any other kind of 746# expression; one can extract their location information, spelling, children, 747# etc. However, the specific kind of the expression is not reported. 748CursorKind.UNEXPOSED_EXPR = CursorKind(100) 749 750# An expression that refers to some value declaration, such as a function, 751# varible, or enumerator. 752CursorKind.DECL_REF_EXPR = CursorKind(101) 753 754# An expression that refers to a member of a struct, union, class, Objective-C 755# class, etc. 756CursorKind.MEMBER_REF_EXPR = CursorKind(102) 757 758# An expression that calls a function. 759CursorKind.CALL_EXPR = CursorKind(103) 760 761# An expression that sends a message to an Objective-C object or class. 762CursorKind.OBJC_MESSAGE_EXPR = CursorKind(104) 763 764# An expression that represents a block literal. 765CursorKind.BLOCK_EXPR = CursorKind(105) 766 767# An integer literal. 768CursorKind.INTEGER_LITERAL = CursorKind(106) 769 770# A floating point number literal. 771CursorKind.FLOATING_LITERAL = CursorKind(107) 772 773# An imaginary number literal. 774CursorKind.IMAGINARY_LITERAL = CursorKind(108) 775 776# A string literal. 777CursorKind.STRING_LITERAL = CursorKind(109) 778 779# A character literal. 780CursorKind.CHARACTER_LITERAL = CursorKind(110) 781 782# A parenthesized expression, e.g. "(1)". 783# 784# This AST node is only formed if full location information is requested. 785CursorKind.PAREN_EXPR = CursorKind(111) 786 787# This represents the unary-expression's (except sizeof and 788# alignof). 789CursorKind.UNARY_OPERATOR = CursorKind(112) 790 791# [C99 6.5.2.1] Array Subscripting. 792CursorKind.ARRAY_SUBSCRIPT_EXPR = CursorKind(113) 793 794# A builtin binary operation expression such as "x + y" or 795# "x <= y". 796CursorKind.BINARY_OPERATOR = CursorKind(114) 797 798# Compound assignment such as "+=". 799CursorKind.COMPOUND_ASSIGNMENT_OPERATOR = CursorKind(115) 800 801# The ?: ternary operator. 802CursorKind.CONDITIONAL_OPERATOR = CursorKind(116) 803 804# An explicit cast in C (C99 6.5.4) or a C-style cast in C++ 805# (C++ [expr.cast]), which uses the syntax (Type)expr. 806# 807# For example: (int)f. 808CursorKind.CSTYLE_CAST_EXPR = CursorKind(117) 809 810# [C99 6.5.2.5] 811CursorKind.COMPOUND_LITERAL_EXPR = CursorKind(118) 812 813# Describes an C or C++ initializer list. 814CursorKind.INIT_LIST_EXPR = CursorKind(119) 815 816# The GNU address of label extension, representing &&label. 817CursorKind.ADDR_LABEL_EXPR = CursorKind(120) 818 819# This is the GNU Statement Expression extension: ({int X=4; X;}) 820CursorKind.StmtExpr = CursorKind(121) 821 822# Represents a C11 generic selection. 823CursorKind.GENERIC_SELECTION_EXPR = CursorKind(122) 824 825# Implements the GNU __null extension, which is a name for a null 826# pointer constant that has integral type (e.g., int or long) and is the same 827# size and alignment as a pointer. 828# 829# The __null extension is typically only used by system headers, which define 830# NULL as __null in C++ rather than using 0 (which is an integer that may not 831# match the size of a pointer). 832CursorKind.GNU_NULL_EXPR = CursorKind(123) 833 834# C++'s static_cast<> expression. 835CursorKind.CXX_STATIC_CAST_EXPR = CursorKind(124) 836 837# C++'s dynamic_cast<> expression. 838CursorKind.CXX_DYNAMIC_CAST_EXPR = CursorKind(125) 839 840# C++'s reinterpret_cast<> expression. 841CursorKind.CXX_REINTERPRET_CAST_EXPR = CursorKind(126) 842 843# C++'s const_cast<> expression. 844CursorKind.CXX_CONST_CAST_EXPR = CursorKind(127) 845 846# Represents an explicit C++ type conversion that uses "functional" 847# notion (C++ [expr.type.conv]). 848# 849# Example: 850# \code 851# x = int(0.5); 852# \endcode 853CursorKind.CXX_FUNCTIONAL_CAST_EXPR = CursorKind(128) 854 855# A C++ typeid expression (C++ [expr.typeid]). 856CursorKind.CXX_TYPEID_EXPR = CursorKind(129) 857 858# [C++ 2.13.5] C++ Boolean Literal. 859CursorKind.CXX_BOOL_LITERAL_EXPR = CursorKind(130) 860 861# [C++0x 2.14.7] C++ Pointer Literal. 862CursorKind.CXX_NULL_PTR_LITERAL_EXPR = CursorKind(131) 863 864# Represents the "this" expression in C++ 865CursorKind.CXX_THIS_EXPR = CursorKind(132) 866 867# [C++ 15] C++ Throw Expression. 868# 869# This handles 'throw' and 'throw' assignment-expression. When 870# assignment-expression isn't present, Op will be null. 871CursorKind.CXX_THROW_EXPR = CursorKind(133) 872 873# A new expression for memory allocation and constructor calls, e.g: 874# "new CXXNewExpr(foo)". 875CursorKind.CXX_NEW_EXPR = CursorKind(134) 876 877# A delete expression for memory deallocation and destructor calls, 878# e.g. "delete[] pArray". 879CursorKind.CXX_DELETE_EXPR = CursorKind(135) 880 881# Represents a unary expression. 882CursorKind.CXX_UNARY_EXPR = CursorKind(136) 883 884# ObjCStringLiteral, used for Objective-C string literals i.e. "foo". 885CursorKind.OBJC_STRING_LITERAL = CursorKind(137) 886 887# ObjCEncodeExpr, used for in Objective-C. 888CursorKind.OBJC_ENCODE_EXPR = CursorKind(138) 889 890# ObjCSelectorExpr used for in Objective-C. 891CursorKind.OBJC_SELECTOR_EXPR = CursorKind(139) 892 893# Objective-C's protocol expression. 894CursorKind.OBJC_PROTOCOL_EXPR = CursorKind(140) 895 896# An Objective-C "bridged" cast expression, which casts between 897# Objective-C pointers and C pointers, transferring ownership in the process. 898# 899# \code 900# NSString *str = (__bridge_transfer NSString *)CFCreateString(); 901# \endcode 902CursorKind.OBJC_BRIDGE_CAST_EXPR = CursorKind(141) 903 904# Represents a C++0x pack expansion that produces a sequence of 905# expressions. 906# 907# A pack expansion expression contains a pattern (which itself is an 908# expression) followed by an ellipsis. For example: 909CursorKind.PACK_EXPANSION_EXPR = CursorKind(142) 910 911# Represents an expression that computes the length of a parameter 912# pack. 913CursorKind.SIZE_OF_PACK_EXPR = CursorKind(143) 914 915# Represents a C++ lambda expression that produces a local function 916# object. 917# 918# \code 919# void abssort(float *x, unsigned N) { 920# std::sort(x, x + N, 921# [](float a, float b) { 922# return std::abs(a) < std::abs(b); 923# }); 924# } 925# \endcode 926CursorKind.LAMBDA_EXPR = CursorKind(144) 927 928# Objective-c Boolean Literal. 929CursorKind.OBJ_BOOL_LITERAL_EXPR = CursorKind(145) 930 931# Represents the "self" expression in a ObjC method. 932CursorKind.OBJ_SELF_EXPR = CursorKind(146) 933 934 935# A statement whose specific kind is not exposed via this interface. 936# 937# Unexposed statements have the same operations as any other kind of statement; 938# one can extract their location information, spelling, children, etc. However, 939# the specific kind of the statement is not reported. 940CursorKind.UNEXPOSED_STMT = CursorKind(200) 941 942# A labelled statement in a function. 943CursorKind.LABEL_STMT = CursorKind(201) 944 945# A compound statement 946CursorKind.COMPOUND_STMT = CursorKind(202) 947 948# A case statement. 949CursorKind.CASE_STMT = CursorKind(203) 950 951# A default statement. 952CursorKind.DEFAULT_STMT = CursorKind(204) 953 954# An if statement. 955CursorKind.IF_STMT = CursorKind(205) 956 957# A switch statement. 958CursorKind.SWITCH_STMT = CursorKind(206) 959 960# A while statement. 961CursorKind.WHILE_STMT = CursorKind(207) 962 963# A do statement. 964CursorKind.DO_STMT = CursorKind(208) 965 966# A for statement. 967CursorKind.FOR_STMT = CursorKind(209) 968 969# A goto statement. 970CursorKind.GOTO_STMT = CursorKind(210) 971 972# An indirect goto statement. 973CursorKind.INDIRECT_GOTO_STMT = CursorKind(211) 974 975# A continue statement. 976CursorKind.CONTINUE_STMT = CursorKind(212) 977 978# A break statement. 979CursorKind.BREAK_STMT = CursorKind(213) 980 981# A return statement. 982CursorKind.RETURN_STMT = CursorKind(214) 983 984# A GNU-style inline assembler statement. 985CursorKind.ASM_STMT = CursorKind(215) 986 987# Objective-C's overall @try-@catch-@finally statement. 988CursorKind.OBJC_AT_TRY_STMT = CursorKind(216) 989 990# Objective-C's @catch statement. 991CursorKind.OBJC_AT_CATCH_STMT = CursorKind(217) 992 993# Objective-C's @finally statement. 994CursorKind.OBJC_AT_FINALLY_STMT = CursorKind(218) 995 996# Objective-C's @throw statement. 997CursorKind.OBJC_AT_THROW_STMT = CursorKind(219) 998 999# Objective-C's @synchronized statement. 1000CursorKind.OBJC_AT_SYNCHRONIZED_STMT = CursorKind(220) 1001 1002# Objective-C's autorealease pool statement. 1003CursorKind.OBJC_AUTORELEASE_POOL_STMT = CursorKind(221) 1004 1005# Objective-C's for collection statement. 1006CursorKind.OBJC_FOR_COLLECTION_STMT = CursorKind(222) 1007 1008# C++'s catch statement. 1009CursorKind.CXX_CATCH_STMT = CursorKind(223) 1010 1011# C++'s try statement. 1012CursorKind.CXX_TRY_STMT = CursorKind(224) 1013 1014# C++'s for (* : *) statement. 1015CursorKind.CXX_FOR_RANGE_STMT = CursorKind(225) 1016 1017# Windows Structured Exception Handling's try statement. 1018CursorKind.SEH_TRY_STMT = CursorKind(226) 1019 1020# Windows Structured Exception Handling's except statement. 1021CursorKind.SEH_EXCEPT_STMT = CursorKind(227) 1022 1023# Windows Structured Exception Handling's finally statement. 1024CursorKind.SEH_FINALLY_STMT = CursorKind(228) 1025 1026# A MS inline assembly statement extension. 1027CursorKind.MS_ASM_STMT = CursorKind(229) 1028 1029# The null statement. 1030CursorKind.NULL_STMT = CursorKind(230) 1031 1032# Adaptor class for mixing declarations with statements and expressions. 1033CursorKind.DECL_STMT = CursorKind(231) 1034 1035### 1036# Other Kinds 1037 1038# Cursor that represents the translation unit itself. 1039# 1040# The translation unit cursor exists primarily to act as the root cursor for 1041# traversing the contents of a translation unit. 1042CursorKind.TRANSLATION_UNIT = CursorKind(300) 1043 1044### 1045# Attributes 1046 1047# An attribute whoe specific kind is note exposed via this interface 1048CursorKind.UNEXPOSED_ATTR = CursorKind(400) 1049 1050CursorKind.IB_ACTION_ATTR = CursorKind(401) 1051CursorKind.IB_OUTLET_ATTR = CursorKind(402) 1052CursorKind.IB_OUTLET_COLLECTION_ATTR = CursorKind(403) 1053 1054CursorKind.CXX_FINAL_ATTR = CursorKind(404) 1055CursorKind.CXX_OVERRIDE_ATTR = CursorKind(405) 1056CursorKind.ANNOTATE_ATTR = CursorKind(406) 1057CursorKind.ASM_LABEL_ATTR = CursorKind(407) 1058 1059### 1060# Preprocessing 1061CursorKind.PREPROCESSING_DIRECTIVE = CursorKind(500) 1062CursorKind.MACRO_DEFINITION = CursorKind(501) 1063CursorKind.MACRO_INSTANTIATION = CursorKind(502) 1064CursorKind.INCLUSION_DIRECTIVE = CursorKind(503) 1065 1066### 1067# Extra declaration 1068 1069# A module import declaration. 1070CursorKind.MODULE_IMPORT_DECL = CursorKind(600) 1071 1072### Cursors ### 1073 1074class Cursor(Structure): 1075 """ 1076 The Cursor class represents a reference to an element within the AST. It 1077 acts as a kind of iterator. 1078 """ 1079 _fields_ = [("_kind_id", c_int), ("xdata", c_int), ("data", c_void_p * 3)] 1080 1081 @staticmethod 1082 def from_location(tu, location): 1083 # We store a reference to the TU in the instance so the TU won't get 1084 # collected before the cursor. 1085 cursor = conf.lib.clang_getCursor(tu, location) 1086 cursor._tu = tu 1087 1088 return cursor 1089 1090 def __eq__(self, other): 1091 return conf.lib.clang_equalCursors(self, other) 1092 1093 def __ne__(self, other): 1094 return not self.__eq__(other) 1095 1096 def is_definition(self): 1097 """ 1098 Returns true if the declaration pointed at by the cursor is also a 1099 definition of that entity. 1100 """ 1101 return conf.lib.clang_isCursorDefinition(self) 1102 1103 def is_static_method(self): 1104 """Returns True if the cursor refers to a C++ member function or member 1105 function template that is declared 'static'. 1106 """ 1107 return conf.lib.clang_CXXMethod_isStatic(self) 1108 1109 def get_definition(self): 1110 """ 1111 If the cursor is a reference to a declaration or a declaration of 1112 some entity, return a cursor that points to the definition of that 1113 entity. 1114 """ 1115 # TODO: Should probably check that this is either a reference or 1116 # declaration prior to issuing the lookup. 1117 return conf.lib.clang_getCursorDefinition(self) 1118 1119 def get_usr(self): 1120 """Return the Unified Symbol Resultion (USR) for the entity referenced 1121 by the given cursor (or None). 1122 1123 A Unified Symbol Resolution (USR) is a string that identifies a 1124 particular entity (function, class, variable, etc.) within a 1125 program. USRs can be compared across translation units to determine, 1126 e.g., when references in one translation refer to an entity defined in 1127 another translation unit.""" 1128 return conf.lib.clang_getCursorUSR(self) 1129 1130 @property 1131 def kind(self): 1132 """Return the kind of this cursor.""" 1133 return CursorKind.from_id(self._kind_id) 1134 1135 @property 1136 def spelling(self): 1137 """Return the spelling of the entity pointed at by the cursor.""" 1138 if not self.kind.is_declaration(): 1139 # FIXME: clang_getCursorSpelling should be fixed to not assert on 1140 # this, for consistency with clang_getCursorUSR. 1141 return None 1142 if not hasattr(self, '_spelling'): 1143 self._spelling = conf.lib.clang_getCursorSpelling(self) 1144 1145 return self._spelling 1146 1147 @property 1148 def displayname(self): 1149 """ 1150 Return the display name for the entity referenced by this cursor. 1151 1152 The display name contains extra information that helps identify the cursor, 1153 such as the parameters of a function or template or the arguments of a 1154 class template specialization. 1155 """ 1156 if not hasattr(self, '_displayname'): 1157 self._displayname = conf.lib.clang_getCursorDisplayName(self) 1158 1159 return self._displayname 1160 1161 @property 1162 def location(self): 1163 """ 1164 Return the source location (the starting character) of the entity 1165 pointed at by the cursor. 1166 """ 1167 if not hasattr(self, '_loc'): 1168 self._loc = conf.lib.clang_getCursorLocation(self) 1169 1170 return self._loc 1171 1172 @property 1173 def extent(self): 1174 """ 1175 Return the source range (the range of text) occupied by the entity 1176 pointed at by the cursor. 1177 """ 1178 if not hasattr(self, '_extent'): 1179 self._extent = conf.lib.clang_getCursorExtent(self) 1180 1181 return self._extent 1182 1183 @property 1184 def type(self): 1185 """ 1186 Retrieve the Type (if any) of the entity pointed at by the cursor. 1187 """ 1188 if not hasattr(self, '_type'): 1189 self._type = conf.lib.clang_getCursorType(self) 1190 1191 return self._type 1192 1193 @property 1194 def canonical(self): 1195 """Return the canonical Cursor corresponding to this Cursor. 1196 1197 The canonical cursor is the cursor which is representative for the 1198 underlying entity. For example, if you have multiple forward 1199 declarations for the same class, the canonical cursor for the forward 1200 declarations will be identical. 1201 """ 1202 if not hasattr(self, '_canonical'): 1203 self._canonical = conf.lib.clang_getCanonicalCursor(self) 1204 1205 return self._canonical 1206 1207 @property 1208 def result_type(self): 1209 """Retrieve the Type of the result for this Cursor.""" 1210 if not hasattr(self, '_result_type'): 1211 self._result_type = conf.lib.clang_getResultType(self.type) 1212 1213 return self._result_type 1214 1215 @property 1216 def underlying_typedef_type(self): 1217 """Return the underlying type of a typedef declaration. 1218 1219 Returns a Type for the typedef this cursor is a declaration for. If 1220 the current cursor is not a typedef, this raises. 1221 """ 1222 if not hasattr(self, '_underlying_type'): 1223 assert self.kind.is_declaration() 1224 self._underlying_type = \ 1225 conf.lib.clang_getTypedefDeclUnderlyingType(self) 1226 1227 return self._underlying_type 1228 1229 @property 1230 def enum_type(self): 1231 """Return the integer type of an enum declaration. 1232 1233 Returns a Type corresponding to an integer. If the cursor is not for an 1234 enum, this raises. 1235 """ 1236 if not hasattr(self, '_enum_type'): 1237 assert self.kind == CursorKind.ENUM_DECL 1238 self._enum_type = conf.lib.clang_getEnumDeclIntegerType(self) 1239 1240 return self._enum_type 1241 1242 @property 1243 def enum_value(self): 1244 """Return the value of an enum constant.""" 1245 if not hasattr(self, '_enum_value'): 1246 assert self.kind == CursorKind.ENUM_CONSTANT_DECL 1247 # Figure out the underlying type of the enum to know if it 1248 # is a signed or unsigned quantity. 1249 underlying_type = self.type 1250 if underlying_type.kind == TypeKind.ENUM: 1251 underlying_type = underlying_type.get_declaration().enum_type 1252 if underlying_type.kind in (TypeKind.CHAR_U, 1253 TypeKind.UCHAR, 1254 TypeKind.CHAR16, 1255 TypeKind.CHAR32, 1256 TypeKind.USHORT, 1257 TypeKind.UINT, 1258 TypeKind.ULONG, 1259 TypeKind.ULONGLONG, 1260 TypeKind.UINT128): 1261 self._enum_value = \ 1262 conf.lib.clang_getEnumConstantDeclUnsignedValue(self) 1263 else: 1264 self._enum_value = conf.lib.clang_getEnumConstantDeclValue(self) 1265 return self._enum_value 1266 1267 @property 1268 def objc_type_encoding(self): 1269 """Return the Objective-C type encoding as a str.""" 1270 if not hasattr(self, '_objc_type_encoding'): 1271 self._objc_type_encoding = \ 1272 conf.lib.clang_getDeclObjCTypeEncoding(self) 1273 1274 return self._objc_type_encoding 1275 1276 @property 1277 def hash(self): 1278 """Returns a hash of the cursor as an int.""" 1279 if not hasattr(self, '_hash'): 1280 self._hash = conf.lib.clang_hashCursor(self) 1281 1282 return self._hash 1283 1284 @property 1285 def semantic_parent(self): 1286 """Return the semantic parent for this cursor.""" 1287 if not hasattr(self, '_semantic_parent'): 1288 self._semantic_parent = conf.lib.clang_getCursorSemanticParent(self) 1289 1290 return self._semantic_parent 1291 1292 @property 1293 def lexical_parent(self): 1294 """Return the lexical parent for this cursor.""" 1295 if not hasattr(self, '_lexical_parent'): 1296 self._lexical_parent = conf.lib.clang_getCursorLexicalParent(self) 1297 1298 return self._lexical_parent 1299 1300 @property 1301 def translation_unit(self): 1302 """Returns the TranslationUnit to which this Cursor belongs.""" 1303 # If this triggers an AttributeError, the instance was not properly 1304 # created. 1305 return self._tu 1306 1307 @property 1308 def referenced(self): 1309 """ 1310 For a cursor that is a reference, returns a cursor 1311 representing the entity that it references. 1312 """ 1313 if not hasattr(self, '_referenced'): 1314 self._referenced = conf.lib.clang_getCursorReferenced(self) 1315 1316 return self._referenced 1317 1318 def get_arguments(self): 1319 """Return an iterator for accessing the arguments of this cursor.""" 1320 num_args = conf.lib.clang_Cursor_getNumArguments(self) 1321 for i in range(0, num_args): 1322 yield conf.lib.clang_Cursor_getArgument(self, i) 1323 1324 def get_children(self): 1325 """Return an iterator for accessing the children of this cursor.""" 1326 1327 # FIXME: Expose iteration from CIndex, PR6125. 1328 def visitor(child, parent, children): 1329 # FIXME: Document this assertion in API. 1330 # FIXME: There should just be an isNull method. 1331 assert child != conf.lib.clang_getNullCursor() 1332 1333 # Create reference to TU so it isn't GC'd before Cursor. 1334 child._tu = self._tu 1335 children.append(child) 1336 return 1 # continue 1337 children = [] 1338 conf.lib.clang_visitChildren(self, callbacks['cursor_visit'](visitor), 1339 children) 1340 return iter(children) 1341 1342 def get_tokens(self): 1343 """Obtain Token instances formulating that compose this Cursor. 1344 1345 This is a generator for Token instances. It returns all tokens which 1346 occupy the extent this cursor occupies. 1347 """ 1348 return TokenGroup.get_tokens(self._tu, self.extent) 1349 1350 def is_bitfield(self): 1351 """ 1352 Check if the field is a bitfield. 1353 """ 1354 return conf.lib.clang_Cursor_isBitField(self) 1355 1356 def get_bitfield_width(self): 1357 """ 1358 Retrieve the width of a bitfield. 1359 """ 1360 return conf.lib.clang_getFieldDeclBitWidth(self) 1361 1362 @staticmethod 1363 def from_result(res, fn, args): 1364 assert isinstance(res, Cursor) 1365 # FIXME: There should just be an isNull method. 1366 if res == conf.lib.clang_getNullCursor(): 1367 return None 1368 1369 # Store a reference to the TU in the Python object so it won't get GC'd 1370 # before the Cursor. 1371 tu = None 1372 for arg in args: 1373 if isinstance(arg, TranslationUnit): 1374 tu = arg 1375 break 1376 1377 if hasattr(arg, 'translation_unit'): 1378 tu = arg.translation_unit 1379 break 1380 1381 assert tu is not None 1382 1383 res._tu = tu 1384 return res 1385 1386 @staticmethod 1387 def from_cursor_result(res, fn, args): 1388 assert isinstance(res, Cursor) 1389 if res == conf.lib.clang_getNullCursor(): 1390 return None 1391 1392 res._tu = args[0]._tu 1393 return res 1394 1395### Type Kinds ### 1396 1397class TypeKind(object): 1398 """ 1399 Describes the kind of type. 1400 """ 1401 1402 # The unique kind objects, indexed by id. 1403 _kinds = [] 1404 _name_map = None 1405 1406 def __init__(self, value): 1407 if value >= len(TypeKind._kinds): 1408 TypeKind._kinds += [None] * (value - len(TypeKind._kinds) + 1) 1409 if TypeKind._kinds[value] is not None: 1410 raise ValueError,'TypeKind already loaded' 1411 self.value = value 1412 TypeKind._kinds[value] = self 1413 TypeKind._name_map = None 1414 1415 def from_param(self): 1416 return self.value 1417 1418 @property 1419 def name(self): 1420 """Get the enumeration name of this cursor kind.""" 1421 if self._name_map is None: 1422 self._name_map = {} 1423 for key,value in TypeKind.__dict__.items(): 1424 if isinstance(value,TypeKind): 1425 self._name_map[value] = key 1426 return self._name_map[self] 1427 1428 @property 1429 def spelling(self): 1430 """Retrieve the spelling of this TypeKind.""" 1431 return conf.lib.clang_getTypeKindSpelling(self.value) 1432 1433 @staticmethod 1434 def from_id(id): 1435 if id >= len(TypeKind._kinds) or TypeKind._kinds[id] is None: 1436 raise ValueError,'Unknown type kind %d' % id 1437 return TypeKind._kinds[id] 1438 1439 def __repr__(self): 1440 return 'TypeKind.%s' % (self.name,) 1441 1442TypeKind.INVALID = TypeKind(0) 1443TypeKind.UNEXPOSED = TypeKind(1) 1444TypeKind.VOID = TypeKind(2) 1445TypeKind.BOOL = TypeKind(3) 1446TypeKind.CHAR_U = TypeKind(4) 1447TypeKind.UCHAR = TypeKind(5) 1448TypeKind.CHAR16 = TypeKind(6) 1449TypeKind.CHAR32 = TypeKind(7) 1450TypeKind.USHORT = TypeKind(8) 1451TypeKind.UINT = TypeKind(9) 1452TypeKind.ULONG = TypeKind(10) 1453TypeKind.ULONGLONG = TypeKind(11) 1454TypeKind.UINT128 = TypeKind(12) 1455TypeKind.CHAR_S = TypeKind(13) 1456TypeKind.SCHAR = TypeKind(14) 1457TypeKind.WCHAR = TypeKind(15) 1458TypeKind.SHORT = TypeKind(16) 1459TypeKind.INT = TypeKind(17) 1460TypeKind.LONG = TypeKind(18) 1461TypeKind.LONGLONG = TypeKind(19) 1462TypeKind.INT128 = TypeKind(20) 1463TypeKind.FLOAT = TypeKind(21) 1464TypeKind.DOUBLE = TypeKind(22) 1465TypeKind.LONGDOUBLE = TypeKind(23) 1466TypeKind.NULLPTR = TypeKind(24) 1467TypeKind.OVERLOAD = TypeKind(25) 1468TypeKind.DEPENDENT = TypeKind(26) 1469TypeKind.OBJCID = TypeKind(27) 1470TypeKind.OBJCCLASS = TypeKind(28) 1471TypeKind.OBJCSEL = TypeKind(29) 1472TypeKind.COMPLEX = TypeKind(100) 1473TypeKind.POINTER = TypeKind(101) 1474TypeKind.BLOCKPOINTER = TypeKind(102) 1475TypeKind.LVALUEREFERENCE = TypeKind(103) 1476TypeKind.RVALUEREFERENCE = TypeKind(104) 1477TypeKind.RECORD = TypeKind(105) 1478TypeKind.ENUM = TypeKind(106) 1479TypeKind.TYPEDEF = TypeKind(107) 1480TypeKind.OBJCINTERFACE = TypeKind(108) 1481TypeKind.OBJCOBJECTPOINTER = TypeKind(109) 1482TypeKind.FUNCTIONNOPROTO = TypeKind(110) 1483TypeKind.FUNCTIONPROTO = TypeKind(111) 1484TypeKind.CONSTANTARRAY = TypeKind(112) 1485TypeKind.VECTOR = TypeKind(113) 1486 1487class Type(Structure): 1488 """ 1489 The type of an element in the abstract syntax tree. 1490 """ 1491 _fields_ = [("_kind_id", c_int), ("data", c_void_p * 2)] 1492 1493 @property 1494 def kind(self): 1495 """Return the kind of this type.""" 1496 return TypeKind.from_id(self._kind_id) 1497 1498 def argument_types(self): 1499 """Retrieve a container for the non-variadic arguments for this type. 1500 1501 The returned object is iterable and indexable. Each item in the 1502 container is a Type instance. 1503 """ 1504 class ArgumentsIterator(collections.Sequence): 1505 def __init__(self, parent): 1506 self.parent = parent 1507 self.length = None 1508 1509 def __len__(self): 1510 if self.length is None: 1511 self.length = conf.lib.clang_getNumArgTypes(self.parent) 1512 1513 return self.length 1514 1515 def __getitem__(self, key): 1516 # FIXME Support slice objects. 1517 if not isinstance(key, int): 1518 raise TypeError("Must supply a non-negative int.") 1519 1520 if key < 0: 1521 raise IndexError("Only non-negative indexes are accepted.") 1522 1523 if key >= len(self): 1524 raise IndexError("Index greater than container length: " 1525 "%d > %d" % ( key, len(self) )) 1526 1527 result = conf.lib.clang_getArgType(self.parent, key) 1528 if result.kind == TypeKind.INVALID: 1529 raise IndexError("Argument could not be retrieved.") 1530 1531 return result 1532 1533 assert self.kind == TypeKind.FUNCTIONPROTO 1534 return ArgumentsIterator(self) 1535 1536 @property 1537 def element_type(self): 1538 """Retrieve the Type of elements within this Type. 1539 1540 If accessed on a type that is not an array, complex, or vector type, an 1541 exception will be raised. 1542 """ 1543 result = conf.lib.clang_getElementType(self) 1544 if result.kind == TypeKind.INVALID: 1545 raise Exception('Element type not available on this type.') 1546 1547 return result 1548 1549 @property 1550 def element_count(self): 1551 """Retrieve the number of elements in this type. 1552 1553 Returns an int. 1554 1555 If the Type is not an array or vector, this raises. 1556 """ 1557 result = conf.lib.clang_getNumElements(self) 1558 if result < 0: 1559 raise Exception('Type does not have elements.') 1560 1561 return result 1562 1563 @property 1564 def translation_unit(self): 1565 """The TranslationUnit to which this Type is associated.""" 1566 # If this triggers an AttributeError, the instance was not properly 1567 # instantiated. 1568 return self._tu 1569 1570 @staticmethod 1571 def from_result(res, fn, args): 1572 assert isinstance(res, Type) 1573 1574 tu = None 1575 for arg in args: 1576 if hasattr(arg, 'translation_unit'): 1577 tu = arg.translation_unit 1578 break 1579 1580 assert tu is not None 1581 res._tu = tu 1582 1583 return res 1584 1585 def get_canonical(self): 1586 """ 1587 Return the canonical type for a Type. 1588 1589 Clang's type system explicitly models typedefs and all the 1590 ways a specific type can be represented. The canonical type 1591 is the underlying type with all the "sugar" removed. For 1592 example, if 'T' is a typedef for 'int', the canonical type for 1593 'T' would be 'int'. 1594 """ 1595 return conf.lib.clang_getCanonicalType(self) 1596 1597 def is_const_qualified(self): 1598 """Determine whether a Type has the "const" qualifier set. 1599 1600 This does not look through typedefs that may have added "const" 1601 at a different level. 1602 """ 1603 return conf.lib.clang_isConstQualifiedType(self) 1604 1605 def is_volatile_qualified(self): 1606 """Determine whether a Type has the "volatile" qualifier set. 1607 1608 This does not look through typedefs that may have added "volatile" 1609 at a different level. 1610 """ 1611 return conf.lib.clang_isVolatileQualifiedType(self) 1612 1613 def is_restrict_qualified(self): 1614 """Determine whether a Type has the "restrict" qualifier set. 1615 1616 This does not look through typedefs that may have added "restrict" at 1617 a different level. 1618 """ 1619 return conf.lib.clang_isRestrictQualifiedType(self) 1620 1621 def is_function_variadic(self): 1622 """Determine whether this function Type is a variadic function type.""" 1623 assert self.kind == TypeKind.FUNCTIONPROTO 1624 1625 return conf.lib.clang_isFunctionTypeVariadic(self) 1626 1627 def is_pod(self): 1628 """Determine whether this Type represents plain old data (POD).""" 1629 return conf.lib.clang_isPODType(self) 1630 1631 def get_pointee(self): 1632 """ 1633 For pointer types, returns the type of the pointee. 1634 """ 1635 return conf.lib.clang_getPointeeType(self) 1636 1637 def get_declaration(self): 1638 """ 1639 Return the cursor for the declaration of the given type. 1640 """ 1641 return conf.lib.clang_getTypeDeclaration(self) 1642 1643 def get_result(self): 1644 """ 1645 Retrieve the result type associated with a function type. 1646 """ 1647 return conf.lib.clang_getResultType(self) 1648 1649 def get_array_element_type(self): 1650 """ 1651 Retrieve the type of the elements of the array type. 1652 """ 1653 return conf.lib.clang_getArrayElementType(self) 1654 1655 def get_array_size(self): 1656 """ 1657 Retrieve the size of the constant array. 1658 """ 1659 return conf.lib.clang_getArraySize(self) 1660 1661 def get_align(self): 1662 """ 1663 Retrieve the alignment of the record. 1664 """ 1665 return conf.lib.clang_Type_getAlignOf(self) 1666 1667 def get_size(self): 1668 """ 1669 Retrieve the size of the record. 1670 """ 1671 return conf.lib.clang_Type_getSizeOf(self) 1672 1673 def get_offset(self, fieldname): 1674 """ 1675 Retrieve the offset of a field in the record. 1676 """ 1677 return conf.lib.clang_Type_getOffsetOf(self, c_char_p(fieldname)) 1678 1679 def __eq__(self, other): 1680 if type(other) != type(self): 1681 return False 1682 1683 return conf.lib.clang_equalTypes(self, other) 1684 1685 def __ne__(self, other): 1686 return not self.__eq__(other) 1687 1688## CIndex Objects ## 1689 1690# CIndex objects (derived from ClangObject) are essentially lightweight 1691# wrappers attached to some underlying object, which is exposed via CIndex as 1692# a void*. 1693 1694class ClangObject(object): 1695 """ 1696 A helper for Clang objects. This class helps act as an intermediary for 1697 the ctypes library and the Clang CIndex library. 1698 """ 1699 def __init__(self, obj): 1700 assert isinstance(obj, c_object_p) and obj 1701 self.obj = self._as_parameter_ = obj 1702 1703 def from_param(self): 1704 return self._as_parameter_ 1705 1706 1707class _CXUnsavedFile(Structure): 1708 """Helper for passing unsaved file arguments.""" 1709 _fields_ = [("name", c_char_p), ("contents", c_char_p), ('length', c_ulong)] 1710 1711# Functions calls through the python interface are rather slow. Fortunately, 1712# for most symboles, we do not need to perform a function call. Their spelling 1713# never changes and is consequently provided by this spelling cache. 1714SpellingCache = { 1715 # 0: CompletionChunk.Kind("Optional"), 1716 # 1: CompletionChunk.Kind("TypedText"), 1717 # 2: CompletionChunk.Kind("Text"), 1718 # 3: CompletionChunk.Kind("Placeholder"), 1719 # 4: CompletionChunk.Kind("Informative"), 1720 # 5 : CompletionChunk.Kind("CurrentParameter"), 1721 6: '(', # CompletionChunk.Kind("LeftParen"), 1722 7: ')', # CompletionChunk.Kind("RightParen"), 1723 8: ']', # CompletionChunk.Kind("LeftBracket"), 1724 9: ']', # CompletionChunk.Kind("RightBracket"), 1725 10: '{', # CompletionChunk.Kind("LeftBrace"), 1726 11: '}', # CompletionChunk.Kind("RightBrace"), 1727 12: '<', # CompletionChunk.Kind("LeftAngle"), 1728 13: '>', # CompletionChunk.Kind("RightAngle"), 1729 14: ', ', # CompletionChunk.Kind("Comma"), 1730 # 15: CompletionChunk.Kind("ResultType"), 1731 16: ':', # CompletionChunk.Kind("Colon"), 1732 17: ';', # CompletionChunk.Kind("SemiColon"), 1733 18: '=', # CompletionChunk.Kind("Equal"), 1734 19: ' ', # CompletionChunk.Kind("HorizontalSpace"), 1735 # 20: CompletionChunk.Kind("VerticalSpace") 1736} 1737 1738class CompletionChunk: 1739 class Kind: 1740 def __init__(self, name): 1741 self.name = name 1742 1743 def __str__(self): 1744 return self.name 1745 1746 def __repr__(self): 1747 return "<ChunkKind: %s>" % self 1748 1749 def __init__(self, completionString, key): 1750 self.cs = completionString 1751 self.key = key 1752 self.__kindNumberCache = -1 1753 1754 def __repr__(self): 1755 return "{'" + self.spelling + "', " + str(self.kind) + "}" 1756 1757 @CachedProperty 1758 def spelling(self): 1759 if self.__kindNumber in SpellingCache: 1760 return SpellingCache[self.__kindNumber] 1761 return conf.lib.clang_getCompletionChunkText(self.cs, self.key).spelling 1762 1763 # We do not use @CachedProperty here, as the manual implementation is 1764 # apparently still significantly faster. Please profile carefully if you 1765 # would like to add CachedProperty back. 1766 @property 1767 def __kindNumber(self): 1768 if self.__kindNumberCache == -1: 1769 self.__kindNumberCache = \ 1770 conf.lib.clang_getCompletionChunkKind(self.cs, self.key) 1771 return self.__kindNumberCache 1772 1773 @CachedProperty 1774 def kind(self): 1775 return completionChunkKindMap[self.__kindNumber] 1776 1777 @CachedProperty 1778 def string(self): 1779 res = conf.lib.clang_getCompletionChunkCompletionString(self.cs, 1780 self.key) 1781 1782 if (res): 1783 return CompletionString(res) 1784 else: 1785 None 1786 1787 def isKindOptional(self): 1788 return self.__kindNumber == 0 1789 1790 def isKindTypedText(self): 1791 return self.__kindNumber == 1 1792 1793 def isKindPlaceHolder(self): 1794 return self.__kindNumber == 3 1795 1796 def isKindInformative(self): 1797 return self.__kindNumber == 4 1798 1799 def isKindResultType(self): 1800 return self.__kindNumber == 15 1801 1802completionChunkKindMap = { 1803 0: CompletionChunk.Kind("Optional"), 1804 1: CompletionChunk.Kind("TypedText"), 1805 2: CompletionChunk.Kind("Text"), 1806 3: CompletionChunk.Kind("Placeholder"), 1807 4: CompletionChunk.Kind("Informative"), 1808 5: CompletionChunk.Kind("CurrentParameter"), 1809 6: CompletionChunk.Kind("LeftParen"), 1810 7: CompletionChunk.Kind("RightParen"), 1811 8: CompletionChunk.Kind("LeftBracket"), 1812 9: CompletionChunk.Kind("RightBracket"), 1813 10: CompletionChunk.Kind("LeftBrace"), 1814 11: CompletionChunk.Kind("RightBrace"), 1815 12: CompletionChunk.Kind("LeftAngle"), 1816 13: CompletionChunk.Kind("RightAngle"), 1817 14: CompletionChunk.Kind("Comma"), 1818 15: CompletionChunk.Kind("ResultType"), 1819 16: CompletionChunk.Kind("Colon"), 1820 17: CompletionChunk.Kind("SemiColon"), 1821 18: CompletionChunk.Kind("Equal"), 1822 19: CompletionChunk.Kind("HorizontalSpace"), 1823 20: CompletionChunk.Kind("VerticalSpace")} 1824 1825class CompletionString(ClangObject): 1826 class Availability: 1827 def __init__(self, name): 1828 self.name = name 1829 1830 def __str__(self): 1831 return self.name 1832 1833 def __repr__(self): 1834 return "<Availability: %s>" % self 1835 1836 def __len__(self): 1837 self.num_chunks 1838 1839 @CachedProperty 1840 def num_chunks(self): 1841 return conf.lib.clang_getNumCompletionChunks(self.obj) 1842 1843 def __getitem__(self, key): 1844 if self.num_chunks <= key: 1845 raise IndexError 1846 return CompletionChunk(self.obj, key) 1847 1848 @property 1849 def priority(self): 1850 return conf.lib.clang_getCompletionPriority(self.obj) 1851 1852 @property 1853 def availability(self): 1854 res = conf.lib.clang_getCompletionAvailability(self.obj) 1855 return availabilityKinds[res] 1856 1857 @property 1858 def briefComment(self): 1859 if conf.function_exists("clang_getCompletionBriefComment"): 1860 return conf.lib.clang_getCompletionBriefComment(self.obj) 1861 return _CXString() 1862 1863 def __repr__(self): 1864 return " | ".join([str(a) for a in self]) \ 1865 + " || Priority: " + str(self.priority) \ 1866 + " || Availability: " + str(self.availability) \ 1867 + " || Brief comment: " + str(self.briefComment.spelling) 1868 1869availabilityKinds = { 1870 0: CompletionChunk.Kind("Available"), 1871 1: CompletionChunk.Kind("Deprecated"), 1872 2: CompletionChunk.Kind("NotAvailable"), 1873 3: CompletionChunk.Kind("NotAccessible")} 1874 1875class CodeCompletionResult(Structure): 1876 _fields_ = [('cursorKind', c_int), ('completionString', c_object_p)] 1877 1878 def __repr__(self): 1879 return str(CompletionString(self.completionString)) 1880 1881 @property 1882 def kind(self): 1883 return CursorKind.from_id(self.cursorKind) 1884 1885 @property 1886 def string(self): 1887 return CompletionString(self.completionString) 1888 1889class CCRStructure(Structure): 1890 _fields_ = [('results', POINTER(CodeCompletionResult)), 1891 ('numResults', c_int)] 1892 1893 def __len__(self): 1894 return self.numResults 1895 1896 def __getitem__(self, key): 1897 if len(self) <= key: 1898 raise IndexError 1899 1900 return self.results[key] 1901 1902class CodeCompletionResults(ClangObject): 1903 def __init__(self, ptr): 1904 assert isinstance(ptr, POINTER(CCRStructure)) and ptr 1905 self.ptr = self._as_parameter_ = ptr 1906 1907 def from_param(self): 1908 return self._as_parameter_ 1909 1910 def __del__(self): 1911 conf.lib.clang_disposeCodeCompleteResults(self) 1912 1913 @property 1914 def results(self): 1915 return self.ptr.contents 1916 1917 @property 1918 def diagnostics(self): 1919 class DiagnosticsItr: 1920 def __init__(self, ccr): 1921 self.ccr= ccr 1922 1923 def __len__(self): 1924 return int(\ 1925 conf.lib.clang_codeCompleteGetNumDiagnostics(self.ccr)) 1926 1927 def __getitem__(self, key): 1928 return conf.lib.clang_codeCompleteGetDiagnostic(self.ccr, key) 1929 1930 return DiagnosticsItr(self) 1931 1932 1933class Index(ClangObject): 1934 """ 1935 The Index type provides the primary interface to the Clang CIndex library, 1936 primarily by providing an interface for reading and parsing translation 1937 units. 1938 """ 1939 1940 @staticmethod 1941 def create(excludeDecls=False): 1942 """ 1943 Create a new Index. 1944 Parameters: 1945 excludeDecls -- Exclude local declarations from translation units. 1946 """ 1947 return Index(conf.lib.clang_createIndex(excludeDecls, 0)) 1948 1949 def __del__(self): 1950 conf.lib.clang_disposeIndex(self) 1951 1952 def read(self, path): 1953 """Load a TranslationUnit from the given AST file.""" 1954 return TranslationUnit.from_ast_file(path, self) 1955 1956 def parse(self, path, args=None, unsaved_files=None, options = 0): 1957 """Load the translation unit from the given source code file by running 1958 clang and generating the AST before loading. Additional command line 1959 parameters can be passed to clang via the args parameter. 1960 1961 In-memory contents for files can be provided by passing a list of pairs 1962 to as unsaved_files, the first item should be the filenames to be mapped 1963 and the second should be the contents to be substituted for the 1964 file. The contents may be passed as strings or file objects. 1965 1966 If an error was encountered during parsing, a TranslationUnitLoadError 1967 will be raised. 1968 """ 1969 return TranslationUnit.from_source(path, args, unsaved_files, options, 1970 self) 1971 1972class TranslationUnit(ClangObject): 1973 """Represents a source code translation unit. 1974 1975 This is one of the main types in the API. Any time you wish to interact 1976 with Clang's representation of a source file, you typically start with a 1977 translation unit. 1978 """ 1979 1980 # Default parsing mode. 1981 PARSE_NONE = 0 1982 1983 # Instruct the parser to create a detailed processing record containing 1984 # metadata not normally retained. 1985 PARSE_DETAILED_PROCESSING_RECORD = 1 1986 1987 # Indicates that the translation unit is incomplete. This is typically used 1988 # when parsing headers. 1989 PARSE_INCOMPLETE = 2 1990 1991 # Instruct the parser to create a pre-compiled preamble for the translation 1992 # unit. This caches the preamble (included files at top of source file). 1993 # This is useful if the translation unit will be reparsed and you don't 1994 # want to incur the overhead of reparsing the preamble. 1995 PARSE_PRECOMPILED_PREAMBLE = 4 1996 1997 # Cache code completion information on parse. This adds time to parsing but 1998 # speeds up code completion. 1999 PARSE_CACHE_COMPLETION_RESULTS = 8 2000 2001 # Flags with values 16 and 32 are deprecated and intentionally omitted. 2002 2003 # Do not parse function bodies. This is useful if you only care about 2004 # searching for declarations/definitions. 2005 PARSE_SKIP_FUNCTION_BODIES = 64 2006 2007 # Used to indicate that brief documentation comments should be included 2008 # into the set of code completions returned from this translation unit. 2009 PARSE_INCLUDE_BRIEF_COMMENTS_IN_CODE_COMPLETION = 128 2010 2011 @classmethod 2012 def from_source(cls, filename, args=None, unsaved_files=None, options=0, 2013 index=None): 2014 """Create a TranslationUnit by parsing source. 2015 2016 This is capable of processing source code both from files on the 2017 filesystem as well as in-memory contents. 2018 2019 Command-line arguments that would be passed to clang are specified as 2020 a list via args. These can be used to specify include paths, warnings, 2021 etc. e.g. ["-Wall", "-I/path/to/include"]. 2022 2023 In-memory file content can be provided via unsaved_files. This is an 2024 iterable of 2-tuples. The first element is the str filename. The 2025 second element defines the content. Content can be provided as str 2026 source code or as file objects (anything with a read() method). If 2027 a file object is being used, content will be read until EOF and the 2028 read cursor will not be reset to its original position. 2029 2030 options is a bitwise or of TranslationUnit.PARSE_XXX flags which will 2031 control parsing behavior. 2032 2033 index is an Index instance to utilize. If not provided, a new Index 2034 will be created for this TranslationUnit. 2035 2036 To parse source from the filesystem, the filename of the file to parse 2037 is specified by the filename argument. Or, filename could be None and 2038 the args list would contain the filename(s) to parse. 2039 2040 To parse source from an in-memory buffer, set filename to the virtual 2041 filename you wish to associate with this source (e.g. "test.c"). The 2042 contents of that file are then provided in unsaved_files. 2043 2044 If an error occurs, a TranslationUnitLoadError is raised. 2045 2046 Please note that a TranslationUnit with parser errors may be returned. 2047 It is the caller's responsibility to check tu.diagnostics for errors. 2048 2049 Also note that Clang infers the source language from the extension of 2050 the input filename. If you pass in source code containing a C++ class 2051 declaration with the filename "test.c" parsing will fail. 2052 """ 2053 if args is None: 2054 args = [] 2055 2056 if unsaved_files is None: 2057 unsaved_files = [] 2058 2059 if index is None: 2060 index = Index.create() 2061 2062 args_array = None 2063 if len(args) > 0: 2064 args_array = (c_char_p * len(args))(* args) 2065 2066 unsaved_array = None 2067 if len(unsaved_files) > 0: 2068 unsaved_array = (_CXUnsavedFile * len(unsaved_files))() 2069 for i, (name, contents) in enumerate(unsaved_files): 2070 if hasattr(contents, "read"): 2071 contents = contents.read() 2072 2073 unsaved_array[i].name = name 2074 unsaved_array[i].contents = contents 2075 unsaved_array[i].length = len(contents) 2076 2077 ptr = conf.lib.clang_parseTranslationUnit(index, filename, args_array, 2078 len(args), unsaved_array, 2079 len(unsaved_files), options) 2080 2081 if not ptr: 2082 raise TranslationUnitLoadError("Error parsing translation unit.") 2083 2084 return cls(ptr, index=index) 2085 2086 @classmethod 2087 def from_ast_file(cls, filename, index=None): 2088 """Create a TranslationUnit instance from a saved AST file. 2089 2090 A previously-saved AST file (provided with -emit-ast or 2091 TranslationUnit.save()) is loaded from the filename specified. 2092 2093 If the file cannot be loaded, a TranslationUnitLoadError will be 2094 raised. 2095 2096 index is optional and is the Index instance to use. If not provided, 2097 a default Index will be created. 2098 """ 2099 if index is None: 2100 index = Index.create() 2101 2102 ptr = conf.lib.clang_createTranslationUnit(index, filename) 2103 if not ptr: 2104 raise TranslationUnitLoadError(filename) 2105 2106 return cls(ptr=ptr, index=index) 2107 2108 def __init__(self, ptr, index): 2109 """Create a TranslationUnit instance. 2110 2111 TranslationUnits should be created using one of the from_* @classmethod 2112 functions above. __init__ is only called internally. 2113 """ 2114 assert isinstance(index, Index) 2115 2116 ClangObject.__init__(self, ptr) 2117 2118 def __del__(self): 2119 conf.lib.clang_disposeTranslationUnit(self) 2120 2121 @property 2122 def cursor(self): 2123 """Retrieve the cursor that represents the given translation unit.""" 2124 return conf.lib.clang_getTranslationUnitCursor(self) 2125 2126 @property 2127 def spelling(self): 2128 """Get the original translation unit source file name.""" 2129 return conf.lib.clang_getTranslationUnitSpelling(self) 2130 2131 def get_includes(self): 2132 """ 2133 Return an iterable sequence of FileInclusion objects that describe the 2134 sequence of inclusions in a translation unit. The first object in 2135 this sequence is always the input file. Note that this method will not 2136 recursively iterate over header files included through precompiled 2137 headers. 2138 """ 2139 def visitor(fobj, lptr, depth, includes): 2140 if depth > 0: 2141 loc = lptr.contents 2142 includes.append(FileInclusion(loc.file, File(fobj), loc, depth)) 2143 2144 # Automatically adapt CIndex/ctype pointers to python objects 2145 includes = [] 2146 conf.lib.clang_getInclusions(self, 2147 callbacks['translation_unit_includes'](visitor), includes) 2148 2149 return iter(includes) 2150 2151 def get_file(self, filename): 2152 """Obtain a File from this translation unit.""" 2153 2154 return File.from_name(self, filename) 2155 2156 def get_location(self, filename, position): 2157 """Obtain a SourceLocation for a file in this translation unit. 2158 2159 The position can be specified by passing: 2160 2161 - Integer file offset. Initial file offset is 0. 2162 - 2-tuple of (line number, column number). Initial file position is 2163 (0, 0) 2164 """ 2165 f = self.get_file(filename) 2166 2167 if isinstance(position, int): 2168 return SourceLocation.from_offset(self, f, position) 2169 2170 return SourceLocation.from_position(self, f, position[0], position[1]) 2171 2172 def get_extent(self, filename, locations): 2173 """Obtain a SourceRange from this translation unit. 2174 2175 The bounds of the SourceRange must ultimately be defined by a start and 2176 end SourceLocation. For the locations argument, you can pass: 2177 2178 - 2 SourceLocation instances in a 2-tuple or list. 2179 - 2 int file offsets via a 2-tuple or list. 2180 - 2 2-tuple or lists of (line, column) pairs in a 2-tuple or list. 2181 2182 e.g. 2183 2184 get_extent('foo.c', (5, 10)) 2185 get_extent('foo.c', ((1, 1), (1, 15))) 2186 """ 2187 f = self.get_file(filename) 2188 2189 if len(locations) < 2: 2190 raise Exception('Must pass object with at least 2 elements') 2191 2192 start_location, end_location = locations 2193 2194 if hasattr(start_location, '__len__'): 2195 start_location = SourceLocation.from_position(self, f, 2196 start_location[0], start_location[1]) 2197 elif isinstance(start_location, int): 2198 start_location = SourceLocation.from_offset(self, f, 2199 start_location) 2200 2201 if hasattr(end_location, '__len__'): 2202 end_location = SourceLocation.from_position(self, f, 2203 end_location[0], end_location[1]) 2204 elif isinstance(end_location, int): 2205 end_location = SourceLocation.from_offset(self, f, end_location) 2206 2207 assert isinstance(start_location, SourceLocation) 2208 assert isinstance(end_location, SourceLocation) 2209 2210 return SourceRange.from_locations(start_location, end_location) 2211 2212 @property 2213 def diagnostics(self): 2214 """ 2215 Return an iterable (and indexable) object containing the diagnostics. 2216 """ 2217 class DiagIterator: 2218 def __init__(self, tu): 2219 self.tu = tu 2220 2221 def __len__(self): 2222 return int(conf.lib.clang_getNumDiagnostics(self.tu)) 2223 2224 def __getitem__(self, key): 2225 diag = conf.lib.clang_getDiagnostic(self.tu, key) 2226 if not diag: 2227 raise IndexError 2228 return Diagnostic(diag) 2229 2230 return DiagIterator(self) 2231 2232 def reparse(self, unsaved_files=None, options=0): 2233 """ 2234 Reparse an already parsed translation unit. 2235 2236 In-memory contents for files can be provided by passing a list of pairs 2237 as unsaved_files, the first items should be the filenames to be mapped 2238 and the second should be the contents to be substituted for the 2239 file. The contents may be passed as strings or file objects. 2240 """ 2241 if unsaved_files is None: 2242 unsaved_files = [] 2243 2244 unsaved_files_array = 0 2245 if len(unsaved_files): 2246 unsaved_files_array = (_CXUnsavedFile * len(unsaved_files))() 2247 for i,(name,value) in enumerate(unsaved_files): 2248 if not isinstance(value, str): 2249 # FIXME: It would be great to support an efficient version 2250 # of this, one day. 2251 value = value.read() 2252 print value 2253 if not isinstance(value, str): 2254 raise TypeError,'Unexpected unsaved file contents.' 2255 unsaved_files_array[i].name = name 2256 unsaved_files_array[i].contents = value 2257 unsaved_files_array[i].length = len(value) 2258 ptr = conf.lib.clang_reparseTranslationUnit(self, len(unsaved_files), 2259 unsaved_files_array, options) 2260 2261 def save(self, filename): 2262 """Saves the TranslationUnit to a file. 2263 2264 This is equivalent to passing -emit-ast to the clang frontend. The 2265 saved file can be loaded back into a TranslationUnit. Or, if it 2266 corresponds to a header, it can be used as a pre-compiled header file. 2267 2268 If an error occurs while saving, a TranslationUnitSaveError is raised. 2269 If the error was TranslationUnitSaveError.ERROR_INVALID_TU, this means 2270 the constructed TranslationUnit was not valid at time of save. In this 2271 case, the reason(s) why should be available via 2272 TranslationUnit.diagnostics(). 2273 2274 filename -- The path to save the translation unit to. 2275 """ 2276 options = conf.lib.clang_defaultSaveOptions(self) 2277 result = int(conf.lib.clang_saveTranslationUnit(self, filename, 2278 options)) 2279 if result != 0: 2280 raise TranslationUnitSaveError(result, 2281 'Error saving TranslationUnit.') 2282 2283 def codeComplete(self, path, line, column, unsaved_files=None, 2284 include_macros=False, include_code_patterns=False, 2285 include_brief_comments=False): 2286 """ 2287 Code complete in this translation unit. 2288 2289 In-memory contents for files can be provided by passing a list of pairs 2290 as unsaved_files, the first items should be the filenames to be mapped 2291 and the second should be the contents to be substituted for the 2292 file. The contents may be passed as strings or file objects. 2293 """ 2294 options = 0 2295 2296 if include_macros: 2297 options += 1 2298 2299 if include_code_patterns: 2300 options += 2 2301 2302 if include_brief_comments: 2303 options += 4 2304 2305 if unsaved_files is None: 2306 unsaved_files = [] 2307 2308 unsaved_files_array = 0 2309 if len(unsaved_files): 2310 unsaved_files_array = (_CXUnsavedFile * len(unsaved_files))() 2311 for i,(name,value) in enumerate(unsaved_files): 2312 if not isinstance(value, str): 2313 # FIXME: It would be great to support an efficient version 2314 # of this, one day. 2315 value = value.read() 2316 print value 2317 if not isinstance(value, str): 2318 raise TypeError,'Unexpected unsaved file contents.' 2319 unsaved_files_array[i].name = name 2320 unsaved_files_array[i].contents = value 2321 unsaved_files_array[i].length = len(value) 2322 ptr = conf.lib.clang_codeCompleteAt(self, path, line, column, 2323 unsaved_files_array, len(unsaved_files), options) 2324 if ptr: 2325 return CodeCompletionResults(ptr) 2326 return None 2327 2328 def get_tokens(self, locations=None, extent=None): 2329 """Obtain tokens in this translation unit. 2330 2331 This is a generator for Token instances. The caller specifies a range 2332 of source code to obtain tokens for. The range can be specified as a 2333 2-tuple of SourceLocation or as a SourceRange. If both are defined, 2334 behavior is undefined. 2335 """ 2336 if locations is not None: 2337 extent = SourceRange(start=locations[0], end=locations[1]) 2338 2339 return TokenGroup.get_tokens(self, extent) 2340 2341class File(ClangObject): 2342 """ 2343 The File class represents a particular source file that is part of a 2344 translation unit. 2345 """ 2346 2347 @staticmethod 2348 def from_name(translation_unit, file_name): 2349 """Retrieve a file handle within the given translation unit.""" 2350 return File(conf.lib.clang_getFile(translation_unit, file_name)) 2351 2352 @property 2353 def name(self): 2354 """Return the complete file and path name of the file.""" 2355 return conf.lib.clang_getCString(conf.lib.clang_getFileName(self)) 2356 2357 @property 2358 def time(self): 2359 """Return the last modification time of the file.""" 2360 return conf.lib.clang_getFileTime(self) 2361 2362 def __str__(self): 2363 return self.name 2364 2365 def __repr__(self): 2366 return "<File: %s>" % (self.name) 2367 2368 @staticmethod 2369 def from_cursor_result(res, fn, args): 2370 assert isinstance(res, File) 2371 2372 # Copy a reference to the TranslationUnit to prevent premature GC. 2373 res._tu = args[0]._tu 2374 return res 2375 2376class FileInclusion(object): 2377 """ 2378 The FileInclusion class represents the inclusion of one source file by 2379 another via a '#include' directive or as the input file for the translation 2380 unit. This class provides information about the included file, the including 2381 file, the location of the '#include' directive and the depth of the included 2382 file in the stack. Note that the input file has depth 0. 2383 """ 2384 2385 def __init__(self, src, tgt, loc, depth): 2386 self.source = src 2387 self.include = tgt 2388 self.location = loc 2389 self.depth = depth 2390 2391 @property 2392 def is_input_file(self): 2393 """True if the included file is the input file.""" 2394 return self.depth == 0 2395 2396class CompilationDatabaseError(Exception): 2397 """Represents an error that occurred when working with a CompilationDatabase 2398 2399 Each error is associated to an enumerated value, accessible under 2400 e.cdb_error. Consumers can compare the value with one of the ERROR_ 2401 constants in this class. 2402 """ 2403 2404 # An unknown error occured 2405 ERROR_UNKNOWN = 0 2406 2407 # The database could not be loaded 2408 ERROR_CANNOTLOADDATABASE = 1 2409 2410 def __init__(self, enumeration, message): 2411 assert isinstance(enumeration, int) 2412 2413 if enumeration > 1: 2414 raise Exception("Encountered undefined CompilationDatabase error " 2415 "constant: %d. Please file a bug to have this " 2416 "value supported." % enumeration) 2417 2418 self.cdb_error = enumeration 2419 Exception.__init__(self, 'Error %d: %s' % (enumeration, message)) 2420 2421class CompileCommand(object): 2422 """Represents the compile command used to build a file""" 2423 def __init__(self, cmd, ccmds): 2424 self.cmd = cmd 2425 # Keep a reference to the originating CompileCommands 2426 # to prevent garbage collection 2427 self.ccmds = ccmds 2428 2429 @property 2430 def directory(self): 2431 """Get the working directory for this CompileCommand""" 2432 return conf.lib.clang_CompileCommand_getDirectory(self.cmd) 2433 2434 @property 2435 def arguments(self): 2436 """ 2437 Get an iterable object providing each argument in the 2438 command line for the compiler invocation as a _CXString. 2439 2440 Invariant : the first argument is the compiler executable 2441 """ 2442 length = conf.lib.clang_CompileCommand_getNumArgs(self.cmd) 2443 for i in xrange(length): 2444 yield conf.lib.clang_CompileCommand_getArg(self.cmd, i) 2445 2446class CompileCommands(object): 2447 """ 2448 CompileCommands is an iterable object containing all CompileCommand 2449 that can be used for building a specific file. 2450 """ 2451 def __init__(self, ccmds): 2452 self.ccmds = ccmds 2453 2454 def __del__(self): 2455 conf.lib.clang_CompileCommands_dispose(self.ccmds) 2456 2457 def __len__(self): 2458 return int(conf.lib.clang_CompileCommands_getSize(self.ccmds)) 2459 2460 def __getitem__(self, i): 2461 cc = conf.lib.clang_CompileCommands_getCommand(self.ccmds, i) 2462 if not cc: 2463 raise IndexError 2464 return CompileCommand(cc, self) 2465 2466 @staticmethod 2467 def from_result(res, fn, args): 2468 if not res: 2469 return None 2470 return CompileCommands(res) 2471 2472class CompilationDatabase(ClangObject): 2473 """ 2474 The CompilationDatabase is a wrapper class around 2475 clang::tooling::CompilationDatabase 2476 2477 It enables querying how a specific source file can be built. 2478 """ 2479 2480 def __del__(self): 2481 conf.lib.clang_CompilationDatabase_dispose(self) 2482 2483 @staticmethod 2484 def from_result(res, fn, args): 2485 if not res: 2486 raise CompilationDatabaseError(0, 2487 "CompilationDatabase loading failed") 2488 return CompilationDatabase(res) 2489 2490 @staticmethod 2491 def fromDirectory(buildDir): 2492 """Builds a CompilationDatabase from the database found in buildDir""" 2493 errorCode = c_uint() 2494 try: 2495 cdb = conf.lib.clang_CompilationDatabase_fromDirectory(buildDir, 2496 byref(errorCode)) 2497 except CompilationDatabaseError as e: 2498 raise CompilationDatabaseError(int(errorCode.value), 2499 "CompilationDatabase loading failed") 2500 return cdb 2501 2502 def getCompileCommands(self, filename): 2503 """ 2504 Get an iterable object providing all the CompileCommands available to 2505 build filename. Returns None if filename is not found in the database. 2506 """ 2507 return conf.lib.clang_CompilationDatabase_getCompileCommands(self, 2508 filename) 2509 2510class Token(Structure): 2511 """Represents a single token from the preprocessor. 2512 2513 Tokens are effectively segments of source code. Source code is first parsed 2514 into tokens before being converted into the AST and Cursors. 2515 2516 Tokens are obtained from parsed TranslationUnit instances. You currently 2517 can't create tokens manually. 2518 """ 2519 _fields_ = [ 2520 ('int_data', c_uint * 4), 2521 ('ptr_data', c_void_p) 2522 ] 2523 2524 @property 2525 def spelling(self): 2526 """The spelling of this token. 2527 2528 This is the textual representation of the token in source. 2529 """ 2530 return conf.lib.clang_getTokenSpelling(self._tu, self) 2531 2532 @property 2533 def kind(self): 2534 """Obtain the TokenKind of the current token.""" 2535 return TokenKind.from_value(conf.lib.clang_getTokenKind(self)) 2536 2537 @property 2538 def location(self): 2539 """The SourceLocation this Token occurs at.""" 2540 return conf.lib.clang_getTokenLocation(self._tu, self) 2541 2542 @property 2543 def extent(self): 2544 """The SourceRange this Token occupies.""" 2545 return conf.lib.clang_getTokenExtent(self._tu, self) 2546 2547 @property 2548 def cursor(self): 2549 """The Cursor this Token corresponds to.""" 2550 cursor = Cursor() 2551 2552 conf.lib.clang_annotateTokens(self._tu, byref(self), 1, byref(cursor)) 2553 2554 return cursor 2555 2556# Now comes the plumbing to hook up the C library. 2557 2558# Register callback types in common container. 2559callbacks['translation_unit_includes'] = CFUNCTYPE(None, c_object_p, 2560 POINTER(SourceLocation), c_uint, py_object) 2561callbacks['cursor_visit'] = CFUNCTYPE(c_int, Cursor, Cursor, py_object) 2562 2563# Functions strictly alphabetical order. 2564functionList = [ 2565 ("clang_annotateTokens", 2566 [TranslationUnit, POINTER(Token), c_uint, POINTER(Cursor)]), 2567 2568 ("clang_CompilationDatabase_dispose", 2569 [c_object_p]), 2570 2571 ("clang_CompilationDatabase_fromDirectory", 2572 [c_char_p, POINTER(c_uint)], 2573 c_object_p, 2574 CompilationDatabase.from_result), 2575 2576 ("clang_CompilationDatabase_getCompileCommands", 2577 [c_object_p, c_char_p], 2578 c_object_p, 2579 CompileCommands.from_result), 2580 2581 ("clang_CompileCommands_dispose", 2582 [c_object_p]), 2583 2584 ("clang_CompileCommands_getCommand", 2585 [c_object_p, c_uint], 2586 c_object_p), 2587 2588 ("clang_CompileCommands_getSize", 2589 [c_object_p], 2590 c_uint), 2591 2592 ("clang_CompileCommand_getArg", 2593 [c_object_p, c_uint], 2594 _CXString, 2595 _CXString.from_result), 2596 2597 ("clang_CompileCommand_getDirectory", 2598 [c_object_p], 2599 _CXString, 2600 _CXString.from_result), 2601 2602 ("clang_CompileCommand_getNumArgs", 2603 [c_object_p], 2604 c_uint), 2605 2606 ("clang_codeCompleteAt", 2607 [TranslationUnit, c_char_p, c_int, c_int, c_void_p, c_int, c_int], 2608 POINTER(CCRStructure)), 2609 2610 ("clang_codeCompleteGetDiagnostic", 2611 [CodeCompletionResults, c_int], 2612 Diagnostic), 2613 2614 ("clang_codeCompleteGetNumDiagnostics", 2615 [CodeCompletionResults], 2616 c_int), 2617 2618 ("clang_createIndex", 2619 [c_int, c_int], 2620 c_object_p), 2621 2622 ("clang_createTranslationUnit", 2623 [Index, c_char_p], 2624 c_object_p), 2625 2626 ("clang_CXXMethod_isPureVirtual", 2627 [Cursor], 2628 bool), 2629 2630 ("clang_CXXMethod_isStatic", 2631 [Cursor], 2632 bool), 2633 2634 ("clang_CXXMethod_isVirtual", 2635 [Cursor], 2636 bool), 2637 2638 ("clang_defaultSaveOptions", 2639 [TranslationUnit], 2640 c_uint), 2641 2642 ("clang_disposeCodeCompleteResults", 2643 [CodeCompletionResults]), 2644 2645# ("clang_disposeCXTUResourceUsage", 2646# [CXTUResourceUsage]), 2647 2648 ("clang_disposeDiagnostic", 2649 [Diagnostic]), 2650 2651 ("clang_disposeIndex", 2652 [Index]), 2653 2654 ("clang_disposeString", 2655 [_CXString]), 2656 2657 ("clang_disposeTokens", 2658 [TranslationUnit, POINTER(Token), c_uint]), 2659 2660 ("clang_disposeTranslationUnit", 2661 [TranslationUnit]), 2662 2663 ("clang_equalCursors", 2664 [Cursor, Cursor], 2665 bool), 2666 2667 ("clang_equalLocations", 2668 [SourceLocation, SourceLocation], 2669 bool), 2670 2671 ("clang_equalRanges", 2672 [SourceRange, SourceRange], 2673 bool), 2674 2675 ("clang_equalTypes", 2676 [Type, Type], 2677 bool), 2678 2679 ("clang_getArgType", 2680 [Type, c_uint], 2681 Type, 2682 Type.from_result), 2683 2684 ("clang_getArrayElementType", 2685 [Type], 2686 Type, 2687 Type.from_result), 2688 2689 ("clang_getArraySize", 2690 [Type], 2691 c_longlong), 2692 2693 ("clang_getFieldDeclBitWidth", 2694 [Cursor], 2695 c_int), 2696 2697 ("clang_getCanonicalCursor", 2698 [Cursor], 2699 Cursor, 2700 Cursor.from_cursor_result), 2701 2702 ("clang_getCanonicalType", 2703 [Type], 2704 Type, 2705 Type.from_result), 2706 2707 ("clang_getCompletionAvailability", 2708 [c_void_p], 2709 c_int), 2710 2711 ("clang_getCompletionBriefComment", 2712 [c_void_p], 2713 _CXString), 2714 2715 ("clang_getCompletionChunkCompletionString", 2716 [c_void_p, c_int], 2717 c_object_p), 2718 2719 ("clang_getCompletionChunkKind", 2720 [c_void_p, c_int], 2721 c_int), 2722 2723 ("clang_getCompletionChunkText", 2724 [c_void_p, c_int], 2725 _CXString), 2726 2727 ("clang_getCompletionPriority", 2728 [c_void_p], 2729 c_int), 2730 2731 ("clang_getCString", 2732 [_CXString], 2733 c_char_p), 2734 2735 ("clang_getCursor", 2736 [TranslationUnit, SourceLocation], 2737 Cursor), 2738 2739 ("clang_getCursorDefinition", 2740 [Cursor], 2741 Cursor, 2742 Cursor.from_result), 2743 2744 ("clang_getCursorDisplayName", 2745 [Cursor], 2746 _CXString, 2747 _CXString.from_result), 2748 2749 ("clang_getCursorExtent", 2750 [Cursor], 2751 SourceRange), 2752 2753 ("clang_getCursorLexicalParent", 2754 [Cursor], 2755 Cursor, 2756 Cursor.from_cursor_result), 2757 2758 ("clang_getCursorLocation", 2759 [Cursor], 2760 SourceLocation), 2761 2762 ("clang_getCursorReferenced", 2763 [Cursor], 2764 Cursor, 2765 Cursor.from_result), 2766 2767 ("clang_getCursorReferenceNameRange", 2768 [Cursor, c_uint, c_uint], 2769 SourceRange), 2770 2771 ("clang_getCursorSemanticParent", 2772 [Cursor], 2773 Cursor, 2774 Cursor.from_cursor_result), 2775 2776 ("clang_getCursorSpelling", 2777 [Cursor], 2778 _CXString, 2779 _CXString.from_result), 2780 2781 ("clang_getCursorType", 2782 [Cursor], 2783 Type, 2784 Type.from_result), 2785 2786 ("clang_getCursorUSR", 2787 [Cursor], 2788 _CXString, 2789 _CXString.from_result), 2790 2791# ("clang_getCXTUResourceUsage", 2792# [TranslationUnit], 2793# CXTUResourceUsage), 2794 2795 ("clang_getCXXAccessSpecifier", 2796 [Cursor], 2797 c_uint), 2798 2799 ("clang_getDeclObjCTypeEncoding", 2800 [Cursor], 2801 _CXString, 2802 _CXString.from_result), 2803 2804 ("clang_getDiagnostic", 2805 [c_object_p, c_uint], 2806 c_object_p), 2807 2808 ("clang_getDiagnosticCategory", 2809 [Diagnostic], 2810 c_uint), 2811 2812 ("clang_getDiagnosticCategoryName", 2813 [c_uint], 2814 _CXString, 2815 _CXString.from_result), 2816 2817 ("clang_getDiagnosticFixIt", 2818 [Diagnostic, c_uint, POINTER(SourceRange)], 2819 _CXString, 2820 _CXString.from_result), 2821 2822 ("clang_getDiagnosticLocation", 2823 [Diagnostic], 2824 SourceLocation), 2825 2826 ("clang_getDiagnosticNumFixIts", 2827 [Diagnostic], 2828 c_uint), 2829 2830 ("clang_getDiagnosticNumRanges", 2831 [Diagnostic], 2832 c_uint), 2833 2834 ("clang_getDiagnosticOption", 2835 [Diagnostic, POINTER(_CXString)], 2836 _CXString, 2837 _CXString.from_result), 2838 2839 ("clang_getDiagnosticRange", 2840 [Diagnostic, c_uint], 2841 SourceRange), 2842 2843 ("clang_getDiagnosticSeverity", 2844 [Diagnostic], 2845 c_int), 2846 2847 ("clang_getDiagnosticSpelling", 2848 [Diagnostic], 2849 _CXString, 2850 _CXString.from_result), 2851 2852 ("clang_getElementType", 2853 [Type], 2854 Type, 2855 Type.from_result), 2856 2857 ("clang_getEnumConstantDeclUnsignedValue", 2858 [Cursor], 2859 c_ulonglong), 2860 2861 ("clang_getEnumConstantDeclValue", 2862 [Cursor], 2863 c_longlong), 2864 2865 ("clang_getEnumDeclIntegerType", 2866 [Cursor], 2867 Type, 2868 Type.from_result), 2869 2870 ("clang_getFile", 2871 [TranslationUnit, c_char_p], 2872 c_object_p), 2873 2874 ("clang_getFileName", 2875 [File], 2876 _CXString), # TODO go through _CXString.from_result? 2877 2878 ("clang_getFileTime", 2879 [File], 2880 c_uint), 2881 2882 ("clang_getIBOutletCollectionType", 2883 [Cursor], 2884 Type, 2885 Type.from_result), 2886 2887 ("clang_getIncludedFile", 2888 [Cursor], 2889 File, 2890 File.from_cursor_result), 2891 2892 ("clang_getInclusions", 2893 [TranslationUnit, callbacks['translation_unit_includes'], py_object]), 2894 2895 ("clang_getInstantiationLocation", 2896 [SourceLocation, POINTER(c_object_p), POINTER(c_uint), POINTER(c_uint), 2897 POINTER(c_uint)]), 2898 2899 ("clang_getLocation", 2900 [TranslationUnit, File, c_uint, c_uint], 2901 SourceLocation), 2902 2903 ("clang_getLocationForOffset", 2904 [TranslationUnit, File, c_uint], 2905 SourceLocation), 2906 2907 ("clang_getNullCursor", 2908 None, 2909 Cursor), 2910 2911 ("clang_getNumArgTypes", 2912 [Type], 2913 c_uint), 2914 2915 ("clang_getNumCompletionChunks", 2916 [c_void_p], 2917 c_int), 2918 2919 ("clang_getNumDiagnostics", 2920 [c_object_p], 2921 c_uint), 2922 2923 ("clang_getNumElements", 2924 [Type], 2925 c_longlong), 2926 2927 ("clang_getNumOverloadedDecls", 2928 [Cursor], 2929 c_uint), 2930 2931 ("clang_getOverloadedDecl", 2932 [Cursor, c_uint], 2933 Cursor, 2934 Cursor.from_cursor_result), 2935 2936 ("clang_getPointeeType", 2937 [Type], 2938 Type, 2939 Type.from_result), 2940 2941 ("clang_getRange", 2942 [SourceLocation, SourceLocation], 2943 SourceRange), 2944 2945 ("clang_getRangeEnd", 2946 [SourceRange], 2947 SourceLocation), 2948 2949 ("clang_getRangeStart", 2950 [SourceRange], 2951 SourceLocation), 2952 2953 ("clang_getResultType", 2954 [Type], 2955 Type, 2956 Type.from_result), 2957 2958 ("clang_getSpecializedCursorTemplate", 2959 [Cursor], 2960 Cursor, 2961 Cursor.from_cursor_result), 2962 2963 ("clang_getTemplateCursorKind", 2964 [Cursor], 2965 c_uint), 2966 2967 ("clang_getTokenExtent", 2968 [TranslationUnit, Token], 2969 SourceRange), 2970 2971 ("clang_getTokenKind", 2972 [Token], 2973 c_uint), 2974 2975 ("clang_getTokenLocation", 2976 [TranslationUnit, Token], 2977 SourceLocation), 2978 2979 ("clang_getTokenSpelling", 2980 [TranslationUnit, Token], 2981 _CXString, 2982 _CXString.from_result), 2983 2984 ("clang_getTranslationUnitCursor", 2985 [TranslationUnit], 2986 Cursor, 2987 Cursor.from_result), 2988 2989 ("clang_getTranslationUnitSpelling", 2990 [TranslationUnit], 2991 _CXString, 2992 _CXString.from_result), 2993 2994 ("clang_getTUResourceUsageName", 2995 [c_uint], 2996 c_char_p), 2997 2998 ("clang_getTypeDeclaration", 2999 [Type], 3000 Cursor, 3001 Cursor.from_result), 3002 3003 ("clang_getTypedefDeclUnderlyingType", 3004 [Cursor], 3005 Type, 3006 Type.from_result), 3007 3008 ("clang_getTypeKindSpelling", 3009 [c_uint], 3010 _CXString, 3011 _CXString.from_result), 3012 3013 ("clang_hashCursor", 3014 [Cursor], 3015 c_uint), 3016 3017 ("clang_isAttribute", 3018 [CursorKind], 3019 bool), 3020 3021 ("clang_isConstQualifiedType", 3022 [Type], 3023 bool), 3024 3025 ("clang_isCursorDefinition", 3026 [Cursor], 3027 bool), 3028 3029 ("clang_isDeclaration", 3030 [CursorKind], 3031 bool), 3032 3033 ("clang_isExpression", 3034 [CursorKind], 3035 bool), 3036 3037 ("clang_isFileMultipleIncludeGuarded", 3038 [TranslationUnit, File], 3039 bool), 3040 3041 ("clang_isFunctionTypeVariadic", 3042 [Type], 3043 bool), 3044 3045 ("clang_isInvalid", 3046 [CursorKind], 3047 bool), 3048 3049 ("clang_isPODType", 3050 [Type], 3051 bool), 3052 3053 ("clang_isPreprocessing", 3054 [CursorKind], 3055 bool), 3056 3057 ("clang_isReference", 3058 [CursorKind], 3059 bool), 3060 3061 ("clang_isRestrictQualifiedType", 3062 [Type], 3063 bool), 3064 3065 ("clang_isStatement", 3066 [CursorKind], 3067 bool), 3068 3069 ("clang_isTranslationUnit", 3070 [CursorKind], 3071 bool), 3072 3073 ("clang_isUnexposed", 3074 [CursorKind], 3075 bool), 3076 3077 ("clang_isVirtualBase", 3078 [Cursor], 3079 bool), 3080 3081 ("clang_isVolatileQualifiedType", 3082 [Type], 3083 bool), 3084 3085 ("clang_parseTranslationUnit", 3086 [Index, c_char_p, c_void_p, c_int, c_void_p, c_int, c_int], 3087 c_object_p), 3088 3089 ("clang_reparseTranslationUnit", 3090 [TranslationUnit, c_int, c_void_p, c_int], 3091 c_int), 3092 3093 ("clang_saveTranslationUnit", 3094 [TranslationUnit, c_char_p, c_uint], 3095 c_int), 3096 3097 ("clang_tokenize", 3098 [TranslationUnit, SourceRange, POINTER(POINTER(Token)), POINTER(c_uint)]), 3099 3100 ("clang_visitChildren", 3101 [Cursor, callbacks['cursor_visit'], py_object], 3102 c_uint), 3103 3104 ("clang_Cursor_getNumArguments", 3105 [Cursor], 3106 c_int), 3107 3108 ("clang_Cursor_getArgument", 3109 [Cursor, c_uint], 3110 Cursor, 3111 Cursor.from_result), 3112 3113 ("clang_Cursor_isBitField", 3114 [Cursor], 3115 bool), 3116 3117 ("clang_Type_getAlignOf", 3118 [Type], 3119 c_longlong), 3120 3121 ("clang_Type_getOffsetOf", 3122 [Type, c_char_p], 3123 c_longlong), 3124 3125 ("clang_Type_getSizeOf", 3126 [Type], 3127 c_ulonglong), 3128] 3129 3130class LibclangError(Exception): 3131 def __init__(self, message): 3132 self.m = message 3133 3134 def __str__(self): 3135 return self.m 3136 3137def register_function(lib, item, ignore_errors): 3138 # A function may not exist, if these bindings are used with an older or 3139 # incompatible version of libclang.so. 3140 try: 3141 func = getattr(lib, item[0]) 3142 except AttributeError as e: 3143 msg = str(e) + ". Please ensure that your python bindings are "\ 3144 "compatible with your libclang.so version." 3145 if ignore_errors: 3146 return 3147 raise LibclangError(msg) 3148 3149 if len(item) >= 2: 3150 func.argtypes = item[1] 3151 3152 if len(item) >= 3: 3153 func.restype = item[2] 3154 3155 if len(item) == 4: 3156 func.errcheck = item[3] 3157 3158def register_functions(lib, ignore_errors): 3159 """Register function prototypes with a libclang library instance. 3160 3161 This must be called as part of library instantiation so Python knows how 3162 to call out to the shared library. 3163 """ 3164 3165 def register(item): 3166 return register_function(lib, item, ignore_errors) 3167 3168 map(register, functionList) 3169 3170class Config: 3171 library_path = None 3172 library_file = None 3173 compatibility_check = True 3174 loaded = False 3175 3176 @staticmethod 3177 def set_library_path(path): 3178 """Set the path in which to search for libclang""" 3179 if Config.loaded: 3180 raise Exception("library path must be set before before using " \ 3181 "any other functionalities in libclang.") 3182 3183 Config.library_path = path 3184 3185 @staticmethod 3186 def set_library_file(filename): 3187 """Set the exact location of libclang""" 3188 if Config.loaded: 3189 raise Exception("library file must be set before before using " \ 3190 "any other functionalities in libclang.") 3191 3192 Config.library_file = filename 3193 3194 @staticmethod 3195 def set_compatibility_check(check_status): 3196 """ Perform compatibility check when loading libclang 3197 3198 The python bindings are only tested and evaluated with the version of 3199 libclang they are provided with. To ensure correct behavior a (limited) 3200 compatibility check is performed when loading the bindings. This check 3201 will throw an exception, as soon as it fails. 3202 3203 In case these bindings are used with an older version of libclang, parts 3204 that have been stable between releases may still work. Users of the 3205 python bindings can disable the compatibility check. This will cause 3206 the python bindings to load, even though they are written for a newer 3207 version of libclang. Failures now arise if unsupported or incompatible 3208 features are accessed. The user is required to test himself if the 3209 features he is using are available and compatible between different 3210 libclang versions. 3211 """ 3212 if Config.loaded: 3213 raise Exception("compatibility_check must be set before before " \ 3214 "using any other functionalities in libclang.") 3215 3216 Config.compatibility_check = check_status 3217 3218 @CachedProperty 3219 def lib(self): 3220 lib = self.get_cindex_library() 3221 register_functions(lib, not Config.compatibility_check) 3222 Config.loaded = True 3223 return lib 3224 3225 def get_filename(self): 3226 if Config.library_file: 3227 return Config.library_file 3228 3229 import platform 3230 name = platform.system() 3231 3232 if name == 'Darwin': 3233 file = 'libclang.dylib' 3234 elif name == 'Windows': 3235 file = 'libclang.dll' 3236 else: 3237 file = 'libclang.so' 3238 3239 if Config.library_path: 3240 file = Config.library_path + '/' + file 3241 3242 return file 3243 3244 def get_cindex_library(self): 3245 try: 3246 library = cdll.LoadLibrary(self.get_filename()) 3247 except OSError as e: 3248 msg = str(e) + ". To provide a path to libclang use " \ 3249 "Config.set_library_path() or " \ 3250 "Config.set_library_file()." 3251 raise LibclangError(msg) 3252 3253 return library 3254 3255 def function_exists(self, name): 3256 try: 3257 getattr(self.lib, name) 3258 except AttributeError: 3259 return False 3260 3261 return True 3262 3263def register_enumerations(): 3264 for name, value in clang.enumerations.TokenKinds: 3265 TokenKind.register(value, name) 3266 3267conf = Config() 3268register_enumerations() 3269 3270__all__ = [ 3271 'Config', 3272 'CodeCompletionResults', 3273 'CompilationDatabase', 3274 'CompileCommands', 3275 'CompileCommand', 3276 'CursorKind', 3277 'Cursor', 3278 'Diagnostic', 3279 'File', 3280 'FixIt', 3281 'Index', 3282 'SourceLocation', 3283 'SourceRange', 3284 'TokenKind', 3285 'Token', 3286 'TranslationUnitLoadError', 3287 'TranslationUnit', 3288 'TypeKind', 3289 'Type', 3290] 3291