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