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