/[llvm-project]/cfe/trunk/bindings/python/clang/cindex.py
ViewVC logotype

Contents of /cfe/trunk/bindings/python/clang/cindex.py

Parent Directory Parent Directory | Revision Log Revision Log


Revision 203906 - (show annotations) (download) (as text)
Fri Mar 14 03:39:06 2014 CDT (4 weeks, 5 days ago) by void
File MIME type: text/x-python
File size: 102620 byte(s)
Use the correct symbol for a left bracket.

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

llvm-admin@cs.uiuc.edu
ViewVC Help
Powered by ViewVC 1.1.5