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