[libclang] Add support for querying cursor availability

[jklaehn]

Summary

This patch allows checking the availability of cursors through libclang and clang.cindex (Python).
This e.g. allows to check whether a C++ member function has been marked as deleted.

[jbcoe]

bindings/python/tests/cindex/test_cursor.py

399 ↗

(On Diff #112020)

Can you add tests for the other AvailabilityKinds?

[jklaehn]

Added test for AvailabilityKind.DEPRECATED. NOT_ACCESSIBLE is never returned by clang_getCursorAvailability but only only used in CodeCompletionResult.

[jbcoe]

bindings/python/tests/cindex/test_cursor.py

407 ↗

(On Diff #116456)

It might be better to use a user-defined function that is explicitly deprecated rather than relying on 3rd party standard includes deprecating things for you.

[jklaehn]

Use user-defined function for test of AvailabilityKind.DEPRECATED.

[jbcoe]

LGTM

Would you like me to commit this for you?

[jklaehn]

In D36973#893851, @jbcoe wrote:

LGTM

Would you like me to commit this for you?

Yes, that would be great!

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

def storage_class(self):
         cursor.
         """
         if not hasattr(self, '_storage_class'):
             self._storage_class = conf.lib.clang_Cursor_getStorageClass(self)
 
         return StorageClass.from_id(self._storage_class)
 
     @property
+    def availability(self):
+        """
+        Retrieves the availability of the entity pointed at by the cursor.
+        """
+        if not hasattr(self, '_availability'):
+            self._availability = conf.lib.clang_getCursorAvailability(self)
+
+        return AvailabilityKind.from_id(self._availability)
+
+    @property
     def access_specifier(self):
         """
         Retrieves the access specifier (if any) of the entity pointed at by the
         cursor.
         """
         if not hasattr(self, '_access_specifier'):
             self._access_specifier = conf.lib.clang_getCXXAccessSpecifier(self)
 

 StorageClass.NONE = StorageClass(1)
 StorageClass.EXTERN = StorageClass(2)
 StorageClass.STATIC = StorageClass(3)
 StorageClass.PRIVATEEXTERN = StorageClass(4)
 StorageClass.OPENCLWORKGROUPLOCAL = StorageClass(5)
 StorageClass.AUTO = StorageClass(6)
 StorageClass.REGISTER = StorageClass(7)
 
+### Availability Kinds ###
+
+class AvailabilityKind(BaseEnumeration):
+    """
+    Describes the availability of an entity.
+    """
+
+    # The unique kind objects, indexed by id.
+    _kinds = []
+    _name_map = None
+
+    def __repr__(self):
+        return 'AvailabilityKind.%s' % (self.name,)
+
+AvailabilityKind.AVAILABLE = AvailabilityKind(0)
+AvailabilityKind.DEPRECATED = AvailabilityKind(1)
+AvailabilityKind.NOT_AVAILABLE = AvailabilityKind(2)
+AvailabilityKind.NOT_ACCESSIBLE = AvailabilityKind(3)
 
 ### C++ access specifiers ###
 
 class AccessSpecifier(BaseEnumeration):
     """
     Describes the access of a C++ class member
     """
 
#  [CXTUResourceUsage]),
    [_CXString],
    c_interop_string,
    c_interop_string.to_python_string),
 
   ("clang_getCursor",
    [TranslationUnit, SourceLocation],
    Cursor),
 
+  ("clang_getCursorAvailability",
+   [Cursor],
+   c_int),
+
   ("clang_getCursorDefinition",
    [Cursor],
    Cursor,
    Cursor.from_result),
 
   ("clang_getCursorDisplayName",
    [Cursor],
    _CXString,

 def register_enumerations():
     for name, value in clang.enumerations.TokenKinds:
         TokenKind.register(value, name)
 
 conf = Config()
 register_enumerations()
 
 __all__ = [
+    'AvailabilityKind',
     'Config',
     'CodeCompletionResults',
     'CompilationDatabase',
     'CompileCommands',
     'CompileCommand',
     'CursorKind',
     'Cursor',
     'Diagnostic',

cfe/trunk/bindings/python/tests/cindex/test_cursor.py

 import ctypes
 import gc
 
+from clang.cindex import AvailabilityKind
 from clang.cindex import CursorKind
 from clang.cindex import TemplateArgumentKind
 from clang.cindex import TranslationUnit
 from clang.cindex import TypeKind
 from .util import get_cursor
 from .util import get_cursors
 from .util import get_tu
 

 def test_result_type():
     tu = get_tu('int foo();')
     foo = get_cursor(tu, 'foo')
 
     assert foo is not None
     t = foo.result_type
     assert t.kind == TypeKind.INT
 
+def test_availability():
+    tu = get_tu('class A { A(A const&) = delete; };', lang='cpp')
+
+    # AvailabilityKind.AVAILABLE
+    cursor = get_cursor(tu, 'A')
+    assert cursor.kind == CursorKind.CLASS_DECL
+    assert cursor.availability == AvailabilityKind.AVAILABLE
+
+    # AvailabilityKind.NOT_AVAILABLE
+    cursors = get_cursors(tu, 'A')
+    for c in cursors:
+        if c.kind == CursorKind.CONSTRUCTOR:
+            assert c.availability == AvailabilityKind.NOT_AVAILABLE
+            break
+    else:
+        assert False, "Could not find cursor for deleted constructor"
+
+    # AvailabilityKind.DEPRECATED
+    tu = get_tu('void test() __attribute__((deprecated));', lang='cpp')
+    cursor = get_cursor(tu, 'test')
+    assert cursor.availability == AvailabilityKind.DEPRECATED
+
+    # AvailabilityKind.NOT_ACCESSIBLE is only used in the code completion results
+
 def test_get_tokens():
     """Ensure we can map cursors back to tokens."""
     tu = get_tu('int foo(int i);')
     foo = get_cursor(tu, 'foo')
 
     tokens = list(foo.get_tokens())
     assert len(tokens) == 6
     assert tokens[0].spelling == 'int'