[libclang] Add CXBinaryOperatorKind and CXUnaryOperatorKind (implements 29138)

[MineGame159]

Summary

Adds 2 new functions to the C libclang api for retrieving operator kinds for binary and unary operators from cursors. Also adds 2 functions for retrieving the spelling of the new enums. This differential implements #29138.

[MineGame159]

ping?

[aaron.ballman]

Thank you for the additions! This should have some amount of test coverage added to clang/unittests/libclang/LibclangTest.cpp and a release note.

clang/tools/libclang/CIndex.cpp

9611

Instead of implementing this manually, I think this should do:

return cxstring::createRef(BinaryOperator::getOpcodeStr(kind - 1));

(Similar for unary operators, may need casts to compile properly).

9688

Please spell out the type.

9690–9694

Similar for unary operators.

[MineGame159]

Implemented requested changes

[MineGame159]

I kinda thought the undefined reference error is just something I broke on my machine but guess not. Don't really know what can cause it since it can link to other functions from there and the function exists.

[vedgy]

In D150910#4405536, @MineGame159 wrote:

I kinda thought the undefined reference error is just something I broke on my machine but guess not. Don't really know what can cause it since it can link to other functions from there and the function exists.

I suspect the reason for the failed build is that you haven't updated clang/tools/libclang/libclang.map. Also CINDEX_VERSION_MINOR in clang/include/clang-c/Index.h needs to be incremented, unless it has been incremented in the targeted LLVM release version already. See e.g. cc929590ad305f0d068709c7c7999f5fc6118dc9.

[MineGame159]

I have added the new functions into the file and now it successfully compiles the test. (but fails when running it - EDIT: guess I broke my dev env somehow)

Also checked and made sure that CINDEX_VERSION_MINOR was already incremented in LLVM 17.
Another thing I am not sure is which naming convention I should be using. Some functions in the C api use clang_getCursorBinaryOperatorKind and others clang_Cursor_getBinaryOperatorKind.

[aaron.ballman]

In D150910#4406296, @MineGame159 wrote:

I have added the new functions into the file and now it successfully compiles the test. (but fails when running it - EDIT: guess I broke my dev env somehow)

Also checked and made sure that CINDEX_VERSION_MINOR was already incremented in LLVM 17.
Another thing I am not sure is which naming convention I should be using. Some functions in the C api use clang_getCursorBinaryOperatorKind and others clang_Cursor_getBinaryOperatorKind.

The style you're using currently is fine.

clang/docs/ReleaseNotes.rst

731

clang/tools/libclang/CIndex.cpp

9620–9624

Sorry, I was unclear before. :-) Our style guide is to not use auto unless the type is spelled out explicitly in the RHS of the assignment (basically, use auto when it lets you avoid repeating the type name). So these uses with dyn_cast (and friends) should use auto, while a call like getCursorExpr() should spell out the type explicitly.

9640

clang/unittests/libclang/LibclangTest.cpp

1143

1160

[aaron.ballman]

LGTM! Do you need me to commit on your behalf? If so, what name and email address would you like me to use for patch attribution?

[MineGame159]

In D150910#4408585, @aaron.ballman wrote:

LGTM! Do you need me to commit on your behalf? If so, what name and email address would you like me to use for patch attribution?

Yeah, this is my first contribution, thanks. My name can be MineGame159 and email [e-mail].

clang/docs/ReleaseNotes.rst

 - Deprecated two functions ``clang_CXIndex_setGlobalOptions`` and
   ``clang_CXIndex_setInvocationEmissionPathOption`` in favor of the new
   function ``clang_createIndexWithOptions`` in order to improve thread safety.
 
 - Added check in ``clang_getFieldDeclBitWidth`` for whether a bit-field
   has an evaluable bit width. Fixes undefined behavior when called on a
   bit-field whose width depends on a template parameter.
 
+- Added ``CXBinaryOperatorKind`` and ``CXUnaryOperatorKind``.
+  (`#29138 <https://github.com/llvm/llvm-project/issues/29138>`_)
+
 Static Analyzer
 ---------------
 - Fix incorrect alignment attribute on the this parameter of certain
   non-complete destructors when using the Microsoft ABI.
   (`#60465 <https://github.com/llvm/llvm-project/issues/60465>`_)
 
 .. _release-notes-sanitizers:
 

clang/include/clang-c/Index.h

  *
  * \returns a non-zero value if the traversal was terminated
  * prematurely by the visitor returning \c CXFieldVisit_Break.
  */
 CINDEX_LINKAGE unsigned clang_Type_visitFields(CXType T, CXFieldVisitor visitor,
                                                CXClientData client_data);
 
 /**
+ * Describes the kind of binary operators.
+ */
+enum CXBinaryOperatorKind {
+  /** This value describes cursors which are not binary operators. */
+  CXBinaryOperator_Invalid,
+  /** C++ Pointer - to - member operator. */
+  CXBinaryOperator_PtrMemD,
+  /** C++ Pointer - to - member operator. */
+  CXBinaryOperator_PtrMemI,
+  /** Multiplication operator. */
+  CXBinaryOperator_Mul,
+  /** Division operator. */
+  CXBinaryOperator_Div,
+  /** Remainder operator. */
+  CXBinaryOperator_Rem,
+  /** Addition operator. */
+  CXBinaryOperator_Add,
+  /** Subtraction operator. */
+  CXBinaryOperator_Sub,
+  /** Bitwise shift left operator. */
+  CXBinaryOperator_Shl,
+  /** Bitwise shift right operator. */
+  CXBinaryOperator_Shr,
+  /** C++ three-way comparison (spaceship) operator. */
+  CXBinaryOperator_Cmp,
+  /** Less than operator. */
+  CXBinaryOperator_LT,
+  /** Greater than operator. */
+  CXBinaryOperator_GT,
+  /** Less or equal operator. */
+  CXBinaryOperator_LE,
+  /** Greater or equal operator. */
+  CXBinaryOperator_GE,
+  /** Equal operator. */
+  CXBinaryOperator_EQ,
+  /** Not equal operator. */
+  CXBinaryOperator_NE,
+  /** Bitwise AND operator. */
+  CXBinaryOperator_And,
+  /** Bitwise XOR operator. */
+  CXBinaryOperator_Xor,
+  /** Bitwise OR operator. */
+  CXBinaryOperator_Or,
+  /** Logical AND operator. */
+  CXBinaryOperator_LAnd,
+  /** Logical OR operator. */
+  CXBinaryOperator_LOr,
+  /** Assignment operator. */
+  CXBinaryOperator_Assign,
+  /** Multiplication assignment operator. */
+  CXBinaryOperator_MulAssign,
+  /** Division assignment operator. */
+  CXBinaryOperator_DivAssign,
+  /** Remainder assignment operator. */
+  CXBinaryOperator_RemAssign,
+  /** Addition assignment operator. */
+  CXBinaryOperator_AddAssign,
+  /** Subtraction assignment operator. */
+  CXBinaryOperator_SubAssign,
+  /** Bitwise shift left assignment operator. */
+  CXBinaryOperator_ShlAssign,
+  /** Bitwise shift right assignment operator. */
+  CXBinaryOperator_ShrAssign,
+  /** Bitwise AND assignment operator. */
+  CXBinaryOperator_AndAssign,
+  /** Bitwise XOR assignment operator. */
+  CXBinaryOperator_XorAssign,
+  /** Bitwise OR assignment operator. */
+  CXBinaryOperator_OrAssign,
+  /** Comma operator. */
+  CXBinaryOperator_Comma
+};
+
+/**
+ * Retrieve the spelling of a given CXBinaryOperatorKind.
+ */
+CINDEX_LINKAGE CXString
+clang_getBinaryOperatorKindSpelling(enum CXBinaryOperatorKind kind);
+
+/**
+ * Retrieve the binary operator kind of this cursor.
+ *
+ * If this cursor is not a binary operator then returns Invalid.
+ */
+CINDEX_LINKAGE enum CXBinaryOperatorKind
+clang_getCursorBinaryOperatorKind(CXCursor cursor);
+
+/**
+ * Describes the kind of unary operators.
+ */
+enum CXUnaryOperatorKind {
+  /** This value describes cursors which are not unary operators. */
+  CXUnaryOperator_Invalid,
+  /** Postfix increment operator. */
+  CXUnaryOperator_PostInc,
+  /** Postfix decrement operator. */
+  CXUnaryOperator_PostDec,
+  /** Prefix increment operator. */
+  CXUnaryOperator_PreInc,
+  /** Prefix decrement operator. */
+  CXUnaryOperator_PreDec,
+  /** Address of operator. */
+  CXUnaryOperator_AddrOf,
+  /** Dereference operator. */
+  CXUnaryOperator_Deref,
+  /** Plus operator. */
+  CXUnaryOperator_Plus,
+  /** Minus operator. */
+  CXUnaryOperator_Minus,
+  /** Not operator. */
+  CXUnaryOperator_Not,
+  /** LNot operator. */
+  CXUnaryOperator_LNot,
+  /** "__real expr" operator. */
+  CXUnaryOperator_Real,
+  /** "__imag expr" operator. */
+  CXUnaryOperator_Imag,
+  /** __extension__ marker operator. */
+  CXUnaryOperator_Extension,
+  /** C++ co_await operator. */
+  CXUnaryOperator_Coawait
+};
+
+/**
+ * Retrieve the spelling of a given CXUnaryOperatorKind.
+ */
+CINDEX_LINKAGE CXString
+clang_getUnaryOperatorKindSpelling(enum CXUnaryOperatorKind kind);
+
+/**
+ * Retrieve the unary operator kind of this cursor.
+ *
+ * If this cursor is not a unary operator then returns Invalid.
+ */
+CINDEX_LINKAGE enum CXUnaryOperatorKind
+clang_getCursorUnaryOperatorKind(CXCursor cursor);
+
+/**
  * @}
  */
 
 /**
  * @}
  */
 
 LLVM_CLANG_C_EXTERN_C_END
 
 #endif

clang/include/clang/AST/OperationKinds.def

 // Convert a pointer to a different address space.
 CAST_OPERATION(AddressSpaceConversion)
 
 // Convert an integer initializer to an OpenCL sampler.
 CAST_OPERATION(IntToOCLSampler)
 
 //===- Binary Operations  -------------------------------------------------===//
 // Operators listed in order of precedence.
-// Note that additions to this should also update the StmtVisitor class and
-// BinaryOperator::getOverloadedOperator.
+// Note that additions to this should also update the StmtVisitor class,
+// BinaryOperator::getOverloadedOperator and CXBinaryOperatorKind enum.
 
 // [C++ 5.5] Pointer-to-member operators.
 BINARY_OPERATION(PtrMemD, ".*")
 BINARY_OPERATION(PtrMemI, "->*")
 // [C99 6.5.5] Multiplicative operators.
 BINARY_OPERATION(Mul, "*")
 BINARY_OPERATION(Div, "/")
 BINARY_OPERATION(Rem, "%")

 BINARY_OPERATION(AndAssign, "&=")
 BINARY_OPERATION(XorAssign, "^=")
 BINARY_OPERATION(OrAssign, "|=")
 // [C99 6.5.17] Comma operator.
 BINARY_OPERATION(Comma, ",")
 
 
 //===- Unary Operations ---------------------------------------------------===//
-// Note that additions to this should also update the StmtVisitor class and
-// UnaryOperator::getOverloadedOperator.
+// Note that additions to this should also update the StmtVisitor class,
+// UnaryOperator::getOverloadedOperator and CXUnaryOperatorKind enum.
 
 // [C99 6.5.2.4] Postfix increment and decrement
 UNARY_OPERATION(PostInc, "++")
 UNARY_OPERATION(PostDec, "--")
 // [C99 6.5.3.1] Prefix increment and decrement
 UNARY_OPERATION(PreInc, "++")
 UNARY_OPERATION(PreDec, "--")
 // [C99 6.5.3.2] Address and indirection

clang/tools/libclang/CIndex.cpp

 #include "CXSourceLocation.h"
 #include "CXString.h"
 #include "CXTranslationUnit.h"
 #include "CXType.h"
 #include "CursorVisitor.h"
 #include "clang-c/FatalErrorHandler.h"
 #include "clang/AST/Attr.h"
 #include "clang/AST/DeclObjCCommon.h"
+#include "clang/AST/Expr.h"
+#include "clang/AST/ExprCXX.h"
 #include "clang/AST/Mangle.h"
 #include "clang/AST/OpenMPClause.h"
+#include "clang/AST/OperationKinds.h"
 #include "clang/AST/StmtVisitor.h"
 #include "clang/Basic/Diagnostic.h"
 #include "clang/Basic/DiagnosticCategories.h"
 #include "clang/Basic/DiagnosticIDs.h"
 #include "clang/Basic/Stack.h"
 #include "clang/Basic/TargetInfo.h"
 #include "clang/Basic/Version.h"
 #include "clang/Frontend/ASTUnit.h"
#endif
   OS << llvm::format("%7.4f] ", TR.getWallTime() - sBeginTR.getWallTime());
   OS << Msg << '\n';
 
   if (Trace) {
     llvm::sys::PrintStackTrace(OS);
     OS << "--------------------------------------------------\n";
   }
 }
+
+CXString clang_getBinaryOperatorKindSpelling(enum CXBinaryOperatorKind kind) {
+  return cxstring::createRef(
+      BinaryOperator::getOpcodeStr(static_cast<BinaryOperatorKind>(kind - 1)));
+}
+
+enum CXBinaryOperatorKind clang_getCursorBinaryOperatorKind(CXCursor cursor) {
+  if (clang_isExpression(cursor.kind)) {
+    const Expr *expr = getCursorExpr(cursor);
+
+    if (const auto *op = dyn_cast<BinaryOperator>(expr))
+      return static_cast<CXBinaryOperatorKind>(op->getOpcode() + 1);
+
+    if (const auto *op = dyn_cast<CXXRewrittenBinaryOperator>(expr))
+      return static_cast<CXBinaryOperatorKind>(op->getOpcode() + 1);
+  }
+
+  return CXBinaryOperator_Invalid;
+}
+
+CXString clang_getUnaryOperatorKindSpelling(enum CXUnaryOperatorKind kind) {
+  return cxstring::createRef(
+      UnaryOperator::getOpcodeStr(static_cast<UnaryOperatorKind>(kind - 1)));
+}
+
+enum CXUnaryOperatorKind clang_getCursorUnaryOperatorKind(CXCursor cursor) {
+  if (clang_isExpression(cursor.kind)) {
+    const Expr *expr = getCursorExpr(cursor);
+
+    if (const auto *op = dyn_cast<UnaryOperator>(expr))
+      return static_cast<CXUnaryOperatorKind>(op->getOpcode() + 1);
+  }
+
+  return CXUnaryOperator_Invalid;
+}

clang/tools/libclang/libclang.map

global:
     clang_getSymbolGraphForCursor;
     clang_getSymbolGraphForUSR;
 };
 
 LLVM_17 {
   global:
     clang_CXXMethod_isExplicit;
     clang_createIndexWithOptions;
+    clang_getBinaryOperatorKindSpelling;
+    clang_getCursorBinaryOperatorKind;
+    clang_getUnaryOperatorKindSpelling;
+    clang_getCursorUnaryOperatorKind;
 };
 
 # Example of how to add a new symbol version entry.  If you do add a new symbol
 # version, please update the example to depend on the version you added.
 # LLVM_X {
 # global:
 #   clang_newsymbol;
 # };

clang/unittests/libclang/LibclangTest.cpp

Traverse([&](CXCursor cursor, CXCursor parent) -> CXChildVisitResult {
     }
     return CXChildVisit_Recurse;
   });
   ASSERT_TRUE(typeRefCsr.has_value());
   EXPECT_EQ(fromCXString(clang_getCursorSpelling(*typeRefCsr)),
             "class ns1::Class1");
 }
 
+TEST_F(LibclangParseTest, BinaryOperator) {
+  std::string Main = "main.cpp";
+  WriteFile(Main, "int foo() { return 5 + 9; }");
+  ClangTU = clang_parseTranslationUnit(Index, Main.c_str(), nullptr, 0, nullptr,
+                                       0, TUFlags);
+
+  Traverse([](CXCursor cursor, CXCursor parent) -> CXChildVisitResult {
+    if (cursor.kind == CXCursor_BinaryOperator) {
+      EXPECT_EQ(clang_getCursorBinaryOperatorKind(cursor),
+                CXBinaryOperator_Add);
+      return CXChildVisit_Break;
+    }
+
+    return CXChildVisit_Recurse;
+  });
+}
+
+TEST_F(LibclangParseTest, UnaryOperator) {
+  std::string Main = "main.cpp";
+  WriteFile(Main, "int foo() { int a = 5; return a++; }");
+  ClangTU = clang_parseTranslationUnit(Index, Main.c_str(), nullptr, 0, nullptr,
+                                       0, TUFlags);
+
+  Traverse([](CXCursor cursor, CXCursor parent) -> CXChildVisitResult {
+    if (cursor.kind == CXCursor_UnaryOperator) {
+      EXPECT_EQ(clang_getCursorUnaryOperatorKind(cursor),
+                CXUnaryOperator_PostInc);
+      return CXChildVisit_Break;
+    }
+
+    return CXChildVisit_Recurse;
+  });
+}
+
 class LibclangRewriteTest : public LibclangParseTest {
 public:
   CXRewriter Rew = nullptr;
   std::string Filename;
   CXFile File = nullptr;
 
   void SetUp() override {
     LibclangParseTest::SetUp();