Add Cursor.get_reference_name_range to clang python binding.

[arthurp]

Summary

Add a python method to Cursor to access clang_getCursorReferenceNameRange
which was already included in the C function list of the python binding.
Also add required constants and a test.

This revision only changes the python binding and does not touch the
underlying C code at all.

[arthurp]

This is my first new revision here, and I guessed on the review based solely on resent reviews of related code. Please correct me as needed. Thanks.

[ilya-biryukov]

Hi Arthur,

Sorry for the late response.
I'm not the maintainer of the Python bindings and I'm not sure who is.

Maybe ask on Discord or cfe-dev mailing list?

clang/bindings/python/clang/cindex.py

 
 class Cursor(Structure):
     """
     The Cursor class represents a reference to an element within the AST. It
     acts as a kind of iterator.
     """
     _fields_ = [("_kind_id", c_int), ("xdata", c_int), ("data", c_void_p * 3)]
 
+    # Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the range.
+    NAME_RANGE_WANT_QUALIFIER = 0x1
+
+    # Include the explicit template arguments, e.g. <int> in x.f<int>, in the range.
+    NAME_RANGE_WANT_TEMPLATE_ARGS = 0x2
+
+    # If the name is non-contiguous, return the full spanning range.
+    # Non-contiguous names occur in Objective-C when a selector with two or
+    # more parameters is used, or in C++ when using an operator:
+    #
+    #   [object doSomething:here withValue:there]; // Objective-C
+    #   return some_vector[1]; // C++
+    NAME_RANGE_WANT_SINGLE_PIECE = 0x4
+
     @staticmethod
     def from_location(tu, location):
         # We store a reference to the TU in the instance so the TU won't get
         # collected before the cursor.
         cursor = conf.lib.clang_getCursor(tu, location)
         cursor._tu = tu
 
         return cursor
class Cursor(Structure):
     def get_template_argument_value(self, num):
         """Returns the value of the indicated arg as a signed 64b integer."""
         return conf.lib.clang_Cursor_getTemplateArgumentValue(self, num)
 
     def get_template_argument_unsigned_value(self, num):
         """Returns the value of the indicated arg as an unsigned 64b integer."""
         return conf.lib.clang_Cursor_getTemplateArgumentUnsignedValue(self, num)
 
+    def get_reference_name_range(self, name_flags, piece_index):
+        """Return the source range covering the reference at this cursor, if applicable.
+
+        name_flags is a bitset of the three independent flags: NAME_RANGE_WANT_QUALIFIER,
+        NAME_RANGE_WANT_TEMPLATE_ARGS, NAME_RANGE_WANT_SINGLE_PIECE.
+
+        piece_index identifies a piece of the overall reference. For contiguous names
+        or when passing the flag NAME_RANGE_WANT_SINGLE_PIECE, only one piece with index
+        0 is available. When the NAME_RANGE_WANT_SINGLE_PIECE flag is not passed for a
+        non-contiguous names, this index can be used to retrieve the individual pieces
+        of the name.
+        """
+        return conf.lib.clang_getCursorReferenceNameRange(self, name_flags, piece_index)
+
     def get_children(self):
         """Return an iterator for accessing the children of this cursor."""
 
         # FIXME: Expose iteration from CIndex, PR6125.
         def visitor(child, parent, children):
             # FIXME: Document this assertion in API.
             # FIXME: There should just be an isNull method.
             assert child != conf.lib.clang_getNullCursor()

clang/bindings/python/tests/cindex/test_cursor.py

 import os
 from clang.cindex import Config
 if 'CLANG_LIBRARY_PATH' in os.environ:
     Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
 
 import ctypes
 import gc
 import unittest
 
 from clang.cindex import AvailabilityKind
 from clang.cindex import CursorKind
+from clang.cindex import Cursor
 from clang.cindex import TemplateArgumentKind
 from clang.cindex import TranslationUnit
 from clang.cindex import TypeKind
+from clang.cindex import SourceRange
+from clang.cindex import SourceLocation
 from .util import get_cursor
+from .util import get_subcursor_by_path
 from .util import get_cursors
 from .util import get_tu
 
 
 kInput = """\
 struct s0 {
   int a;
   int b;

 kTemplateArgTest = """\
         template <int kInt, typename T, bool kBool>
         void foo();
 
         template<>
         void foo<-7, float, true>();
     """
 
+kCPPReferenceNameRangeTest = """\
+void baz();
+
+class C {
+public:
+    void foo();
+    template <typename T>
+    void bar(T v) { }
+    int operator[](int i) { return i; }
+};
+
+void ref1() {
+    baz();
+}
+
+void ref2() {
+    C x;
+    x.C::foo();
+}
+
+void ref3() {
+    C x;
+    x.bar<const char*>("str");
+}
+
+void ref4() {
+    C x;
+    x[1];
+}
+    """
+
 class TestCursor(unittest.TestCase):
     def test_get_children(self):
         tu = get_tu(kInput)
 
         it = tu.cursor.get_children()
         tu_nodes = list(it)
 
         self.assertEqual(len(tu_nodes), 3)
def test_referenced(self):
         tu = get_tu('void foo(); void bar() { foo(); }')
         foo = get_cursor(tu, 'foo')
         bar = get_cursor(tu, 'bar')
         for c in bar.get_children():
             if c.kind == CursorKind.CALL_EXPR:
                 self.assertEqual(c.referenced.spelling, foo.spelling)
                 break
 
+    def test_get_reference_name_range(self):
+        tu = get_tu(kCPPReferenceNameRangeTest, lang='cpp')
+
+        c = get_subcursor_by_path(get_cursor(tu, 'ref1'), 0, 0)
+        self.assertEqual(c.get_reference_name_range(0, 0),
+                         tu.get_extent("t.cpp", ((12, 5), (12, 10))))
+
+        c = get_subcursor_by_path(get_cursor(tu, 'ref2'), 0, 1)
+        self.assertEqual(c.get_reference_name_range(Cursor.NAME_RANGE_WANT_QUALIFIER, 0),
+                         tu.get_extent("t.cpp", ((17, 5), (17, 15))))
+
+        c = get_subcursor_by_path(get_cursor(tu, 'ref3'), 0, 1)
+        self.assertEqual(c.get_reference_name_range(Cursor.NAME_RANGE_WANT_TEMPLATE_ARGS, 0),
+                         tu.get_extent("t.cpp", ((22, 5), (22, 30))))
+
+        c = get_subcursor_by_path(get_cursor(tu, 'ref4'), 0, 1)
+        self.assertEqual(c.get_reference_name_range(0, 0),
+                         tu.get_extent("t.cpp", ((27, 6), (27, 7))))
+        self.assertEqual(c.get_reference_name_range(0, 1),
+                         tu.get_extent("t.cpp", ((27, 8), (27, 9))))
+        self.assertEqual(c.get_reference_name_range(Cursor.NAME_RANGE_WANT_SINGLE_PIECE, 0),
+                         tu.get_extent("t.cpp", ((27, 6), (27, 9))))
+
+
     def test_mangled_name(self):
         kInputForMangling = """\
         int foo(int, int);
         """
         tu = get_tu(kInputForMangling, lang='cpp')
         foo = get_cursor(tu, 'foo')
 
         # Since libclang does not link in targets, we cannot pass a triple to it
         # and force the target. To enable this test to pass on all platforms, accept
         # all valid manglings.
         # [c-index-test handles this by running the source through clang, emitting
         #  an AST file and running libclang on that AST file]
         self.assertIn(foo.mangled_name, ('_Z3fooii', '__Z3fooii', '?foo@@YAHHH', '?foo@@YAHHH@Z'))

clang/bindings/python/tests/cindex/util.py

def get_cursor(source, spelling):
     root_cursor = source if isinstance(source, Cursor) else source.cursor
 
     for cursor in root_cursor.walk_preorder():
         if cursor.spelling == spelling:
             return cursor
 
     return None
 
+
+def get_subcursor_by_path(cursor, *path):
+    """Obtain a cursor by following the path provided from cursor.
+
+    path is a series of ints specifying which child to select.
+    """
+
+    if path:
+        return get_subcursor_by_path(list(cursor.get_children())[path[0]], *path[1:])
+    else:
+        return cursor
+
 def get_cursors(source, spelling):
     """Obtain all cursors from a source object with a specific spelling.
 
     This provides a convenient search mechanism to find all cursors with
     specific spelling within a source. The first argument can be either a
     TranslationUnit or Cursor instance.
 
     If no cursors are found, an empty list is returned.

 
 
 skip_if_no_fspath = unittest.skipUnless(HAS_FSPATH,
                                         "Requires file system path protocol / Python 3.6+")
 
 __all__ = [
     'get_cursor',
     'get_cursors',
+    'get_subcursor_by_path',
     'get_tu',
     'skip_if_no_fspath',
     'str_to_path',
 ]