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