Implement libclang API functions for retrieving the lexical and

semantic parents of the given cursor.

llvm-svn: 114587

clang/include/clang-c/Index.h

@@ -1351,6 +1351,73 @@ CINDEX_LINKAGE enum CXLanguageKind {
  */
 CINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor);
 
+  
+/**
+ * \brief Determine the semantic parent of the given cursor.
+ *
+ * The semantic parent of a cursor is the cursor that semantically contains
+ * the given \p cursor. For many declarations, the lexical and semantic parents
+ * are equivalent (the lexical parent is returned by 
+ * \c clang_getCursorLexicalParent()). They diverge when declarations or
+ * definitions are provided out-of-line. For example:
+ *
+ * \code
+ * class C {
+ *  void f();
+ * };
+ *
+ * void C::f() { }
+ * \endcode
+ *
+ * In the out-of-line definition of \c C::f, the semantic parent is the 
+ * the class \c C, of which this function is a member. The lexical parent is
+ * the place where the declaration actually occurs in the source code; in this
+ * case, the definition occurs in the translation unit. In general, the 
+ * lexical parent for a given entity can change without affecting the semantics
+ * of the program, and the lexical parent of different declarations of the
+ * same entity may be different. Changing the semantic parent of a declaration,
+ * on the other hand, can have a major impact on semantics, and redeclarations
+ * of a particular entity should all have the same semantic context.
+ *
+ * In the example above, both declarations of \c C::f have \c C as their
+ * semantic context, while the lexical context of the first \c C::f is \c C
+ * and the lexical context of the second \c C::f is the translation unit.
+ */
+CINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor);
+
+/**
+ * \brief Determine the lexical parent of the given cursor.
+ *
+ * The lexical parent of a cursor is the cursor in which the given \p cursor
+ * was actually written. For many declarations, the lexical and semantic parents
+ * are equivalent (the semantic parent is returned by 
+ * \c clang_getCursorSemanticParent()). They diverge when declarations or
+ * definitions are provided out-of-line. For example:
+ *
+ * \code
+ * class C {
+ *  void f();
+ * };
+ *
+ * void C::f() { }
+ * \endcode
+ *
+ * In the out-of-line definition of \c C::f, the semantic parent is the 
+ * the class \c C, of which this function is a member. The lexical parent is
+ * the place where the declaration actually occurs in the source code; in this
+ * case, the definition occurs in the translation unit. In general, the 
+ * lexical parent for a given entity can change without affecting the semantics
+ * of the program, and the lexical parent of different declarations of the
+ * same entity may be different. Changing the semantic parent of a declaration,
+ * on the other hand, can have a major impact on semantics, and redeclarations
+ * of a particular entity should all have the same semantic context.
+ *
+ * In the example above, both declarations of \c C::f have \c C as their
+ * semantic context, while the lexical context of the first \c C::f is \c C
+ * and the lexical context of the second \c C::f is the translation unit.
+ */
+CINDEX_LINKAGE CXCursor clang_getCursorLexicalParent(CXCursor cursor);
+  
 /**
  * @}
  */

clang/tools/libclang/CIndex.cpp

@@ -4018,6 +4018,36 @@ CXLanguageKind clang_getCursorLanguage(CXCursor cursor) {
 
   return CXLanguage_Invalid;
 }
+  
+CXCursor clang_getCursorSemanticParent(CXCursor cursor) {
+  if (clang_isDeclaration(cursor.kind)) {
+    if (Decl *D = getCursorDecl(cursor)) {
+      DeclContext *DC = D->getDeclContext();
+      return MakeCXCursor(cast<Decl>(DC), getCursorASTUnit(cursor));
+    }
+  }
+  
+  if (clang_isStatement(cursor.kind) || clang_isExpression(cursor.kind)) {
+    if (Decl *D = getCursorDecl(cursor))
+      return MakeCXCursor(D, getCursorASTUnit(cursor));
+  }
+  
+  return clang_getNullCursor();
+}
+
+CXCursor clang_getCursorLexicalParent(CXCursor cursor) {
+  if (clang_isDeclaration(cursor.kind)) {
+    if (Decl *D = getCursorDecl(cursor)) {
+      DeclContext *DC = D->getLexicalDeclContext();
+      return MakeCXCursor(cast<Decl>(DC), getCursorASTUnit(cursor));
+    }
+  }
+
+  // FIXME: Note that we can't easily compute the lexical context of a 
+  // statement or expression, so we return nothing.
+  return clang_getNullCursor();
+}
+
 } // end: extern "C"
 
 

clang/tools/libclang/libclang.darwin.exports

@@ -45,10 +45,12 @@ _clang_getCursorExtent
 _clang_getCursorKind
 _clang_getCursorKindSpelling
 _clang_getCursorLanguage
+_clang_getCursorLexicalParent
 _clang_getCursorLinkage
 _clang_getCursorLocation
 _clang_getCursorReferenced
 _clang_getCursorResultType
+_clang_getCursorSemanticParent
 _clang_getCursorSpelling
 _clang_getCursorType
 _clang_getCursorUSR

clang/tools/libclang/libclang.exports

@@ -45,10 +45,12 @@ clang_getCursorExtent
 clang_getCursorKind
 clang_getCursorKindSpelling
 clang_getCursorLanguage
+clang_getCursorLexicalParent
 clang_getCursorLinkage
 clang_getCursorLocation
 clang_getCursorReferenced
 clang_getCursorResultType
+clang_getCursorSemanticParent
 clang_getCursorSpelling
 clang_getCursorType
 clang_getCursorUSR