[PATCH] D153738: Add LibClang guide
manuel5975p accepted this revision. manuel5975p added a comment. This revision is now accepted and ready to land. Thanks a lot for carefully going through this. I will dispose of the documentation for CXType after accepting. Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D153738/new/ https://reviews.llvm.org/D153738 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[PATCH] D153738: Add LibClang guide
manuel5975p updated this revision to Diff 537443.
manuel5975p marked 9 inline comments as done.
manuel5975p added a comment.
Incorporate Aaron Ballman's corrections
Repository:
rG LLVM Github Monorepo
CHANGES SINCE LAST ACTION
https://reviews.llvm.org/D153738/new/
https://reviews.llvm.org/D153738
Files:
clang/docs/LibClang.rst
Index: clang/docs/LibClang.rst
===
--- /dev/null
+++ clang/docs/LibClang.rst
@@ -0,0 +1,344 @@
+.. role:: raw-html(raw)
+:format: html
+
+Libclang tutorial
+
+The C Interface to Clang provides a relatively small API that exposes facilities for parsing source code into an abstract syntax tree (AST), loading already-parsed ASTs, traversing the AST, associating physical source locations with elements within the AST, and other facilities that support Clang-based development tools.
+This C interface to Clang will never provide all of the information representation stored in Clang's C++ AST, nor should it: the intent is to maintain an API that is relatively stable from one release to the next, providing only the basic functionality needed to support development tools.
+The entire C interface of libclang is available in the file `Index.h`_
+
+Essential types overview
+-
+
+All types of libclang are prefixed with ``CX``
+
+CXIndex
+~~~
+An Index that consists of a set of translation units that would typically be linked together into an executable or library.
+
+CXTranslationUnit
+~
+A single translation unit, which resides in an index.
+
+CXCursor
+~
+A cursor representing a pointer to some element in the abstract syntax tree of a translation unit.
+
+
+Code example
+
+
+.. code-block:: cpp
+
+ // file.hpp
+ struct foo{
+int bar;
+int* bar_pointer;
+ };
+.. code-block:: cpp
+
+ #include
+ #include
+
+ int main(){
+CXIndex index = clang_createIndex(0, 0); //Create index
+CXTranslationUnit unit = clang_parseTranslationUnit(
+ index,
+ "file.hpp", nullptr, 0,
+ nullptr, 0,
+ CXTranslationUnit_None); //Parse "file.hpp"
+
+
+if (unit == nullptr){
+ std::cerr << "Unable to parse translation unit. Quitting.\n";
+ return 0;
+}
+CXCursor cursor = clang_getTranslationUnitCursor(unit); //Obtain a cursor at the root of the translation unit
+ }
+
+Visiting elements of an AST
+~~~
+The elements of an AST can be recursively visited with pre-order traversal with ``clang_visitChildren``.
+
+.. code-block:: cpp
+
+ clang_visitChildren(
+cursor, //Root cursor
+[](CXCursor current_cursor, CXCursor parent, CXClientData client_data){
+
+ CXString current_display_name = clang_getCursorDisplayName(current_cursor);
+ //Allocate a CXString representing the name of the current cursor
+
+ std::cout << "Visiting element " << clang_getCString(current_display_name) << "\n";
+ //Print the char* value of current_display_name
+
+ clang_disposeString(current_display_name);
+ //Since clang_getCursorDisplayName allocates a new CXString, it must be freed. This applies
+ //to all functions returning a CXString
+
+ return CXChildVisit_Recurse;
+
+
+}, //CXCursorVisitor: a function pointer
+nullptr //client_data
+);
+
+The return value of ``CXCursorVisitor``, the callable argument of ``clang_visitChildren``, can return of of the three:
+
+#. ``CXChildVisit_Break``: Terminates the cursor traversal
+
+#. ``CXChildVisit_Continue``: Continues the cursor traversal with the next sibling of the cursor just visited, without visiting its children.
+
+#. ``CXChildVisit_Recurse``: Recursively traverse the children of this cursor, using the same visitor and client data
+
+The expected output of that program is
+
+.. code-block::
+
+ Visiting element foo
+ Visiting element bar
+ Visiting element bar_pointer
+
+
+Extracting information from a Cursor
+
+.. The following functions take a ``CXCursor`` as an argument and return associated information.
+
+
+
+Extracting the Cursor kind
+""
+
+``CXCursorKind clang_getCursorKind(CXCursor)`` Describes the kind of entity that a cursor refers to. Example values:
+
+- ``CXCursor_StructDecl``: A C or C++ struct.
+- ``CXCursor_FieldDecl``: A field in a struct, union, or C++ class.
+- ``CXCursor_CallExpr``: An expression that calls a function
+
+
+Extracting the Cursor type
+""
+``CXType clang_getCursorType(CXCursor)``: Retrieve the type of a CXCursor (if any).
+
+``CXType`` is a struct with two members:
+
+.. code-block:: cpp
+
+ typedef struct {
+enum CXTypeKind kind;
+void *data[2];
+ } CXType;
+
+Example values for ``CXTypeKind kind``
+
+- ``CXType_Invalid``: Represents an invalid type (e.g., where no type is available)
+- ``CXType_Pointer``: A pointer to another type
+
[PATCH] D153738: Add LibClang guide
manuel5975p updated this revision to Diff 538333.
Repository:
rG LLVM Github Monorepo
CHANGES SINCE LAST ACTION
https://reviews.llvm.org/D153738/new/
https://reviews.llvm.org/D153738
Files:
clang/docs/LibClang.rst
Index: clang/docs/LibClang.rst
===
--- /dev/null
+++ clang/docs/LibClang.rst
@@ -0,0 +1,364 @@
+.. role:: raw-html(raw)
+:format: html
+
+Libclang tutorial
+=
+The C Interface to Clang provides a relatively small API that exposes facilities for parsing source code into an abstract syntax tree (AST), loading already-parsed ASTs, traversing the AST, associating physical source locations with elements within the AST, and other facilities that support Clang-based development tools.
+This C interface to Clang will never provide all of the information representation stored in Clang's C++ AST, nor should it: the intent is to maintain an API that is relatively stable from one release to the next, providing only the basic functionality needed to support development tools.
+The entire C interface of libclang is available in the file `Index.h`_
+
+Essential types overview
+-
+
+All types of libclang are prefixed with ``CX``
+
+CXIndex
+~~~
+An Index that consists of a set of translation units that would typically be linked together into an executable or library.
+
+CXTranslationUnit
+~
+A single translation unit, which resides in an index.
+
+CXCursor
+
+A cursor representing a pointer to some element in the abstract syntax tree of a translation unit.
+
+
+Code example
+
+
+.. code-block:: cpp
+
+ // file.cpp
+ struct foo{
+int bar;
+int* bar_pointer;
+ };
+
+.. code-block:: cpp
+
+ #include
+ #include
+
+ int main(){
+CXIndex index = clang_createIndex(0, 0); //Create index
+CXTranslationUnit unit = clang_parseTranslationUnit(
+ index,
+ "file.cpp", nullptr, 0,
+ nullptr, 0,
+ CXTranslationUnit_None); //Parse "file.cpp"
+
+
+if (unit == nullptr){
+ std::cerr << "Unable to parse translation unit. Quitting.\n";
+ return 0;
+}
+CXCursor cursor = clang_getTranslationUnitCursor(unit); //Obtain a cursor at the root of the translation unit
+ }
+
+Visiting elements of an AST
+~~~
+The elements of an AST can be recursively visited with pre-order traversal with ``clang_visitChildren``.
+
+.. code-block:: cpp
+
+ clang_visitChildren(
+cursor, //Root cursor
+[](CXCursor current_cursor, CXCursor parent, CXClientData client_data){
+
+ CXString current_display_name = clang_getCursorDisplayName(current_cursor);
+ //Allocate a CXString representing the name of the current cursor
+
+ std::cout << "Visiting element " << clang_getCString(current_display_name) << "\n";
+ //Print the char* value of current_display_name
+
+ clang_disposeString(current_display_name);
+ //Since clang_getCursorDisplayName allocates a new CXString, it must be freed. This applies
+ //to all functions returning a CXString
+
+ return CXChildVisit_Recurse;
+
+
+}, //CXCursorVisitor: a function pointer
+nullptr //client_data
+);
+
+The return value of ``CXCursorVisitor``, the callable argument of ``clang_visitChildren``, can return one of the three:
+
+#. ``CXChildVisit_Break``: Terminates the cursor traversal
+
+#. ``CXChildVisit_Continue``: Continues the cursor traversal with the next sibling of the cursor just visited, without visiting its children.
+
+#. ``CXChildVisit_Recurse``: Recursively traverse the children of this cursor, using the same visitor and client data
+
+The expected output of that program is
+
+.. code-block::
+
+ Visiting element foo
+ Visiting element bar
+ Visiting element bar_pointer
+
+
+Extracting information from a Cursor
+
+.. The following functions take a ``CXCursor`` as an argument and return associated information.
+
+
+
+Extracting the Cursor kind
+""
+
+``CXCursorKind clang_getCursorKind(CXCursor)`` Describes the kind of entity that a cursor refers to. Example values:
+
+- ``CXCursor_StructDecl``: A C or C++ struct.
+- ``CXCursor_FieldDecl``: A field in a struct, union, or C++ class.
+- ``CXCursor_CallExpr``: An expression that calls a function.
+
+
+Extracting the Cursor type
+""
+``CXType clang_getCursorType(CXCursor)``: Retrieve the type of a CXCursor (if any).
+
+A ``CXType`` represents a complete C++ type, including qualifiers and pointers. It has a member field ``CXTypeKind kind`` and additional opaque data.
+
+Example values for ``CXTypeKind kind``
+
+- ``CXType_Invalid``: Represents an invalid type (e.g., where no type is available)
+- ``CXType_Pointer``: A pointer to another type
+- ``CXType_Int``: Regular ``int``
+- ``CXType_Elaborated``: Represents a type that was referred to using an elaborated type k
[PATCH] D153738: Add LibClang guide
manuel5975p added a comment. I guess manuel5975p (manuel.wink...@gmx.ch) would be nice Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D153738/new/ https://reviews.llvm.org/D153738 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[PATCH] D153738: Add LibClang guide
manuel5975p created this revision.
manuel5975p added a reviewer: aaron.ballman.
manuel5975p added projects: clang, clang-c.
Herald added a project: All.
manuel5975p requested review of this revision.
Herald added a subscriber: cfe-commits.
Add a libclang .rst file with some code examples, going over the most important
types and functions of libclang.
Repository:
rG LLVM Github Monorepo
https://reviews.llvm.org/D153738
Files:
clang/docs/LibClang.rst
Index: clang/docs/LibClang.rst
===
--- /dev/null
+++ clang/docs/LibClang.rst
@@ -0,0 +1,344 @@
+.. role:: raw-html(raw)
+:format: html
+
+Libclang tutorial
+
+The C Interface to Clang provides a relatively small API that exposes facilities for parsing source code into an abstract syntax tree (AST), loading already-parsed ASTs, traversing the AST, associating physical source locations with elements within the AST, and other facilities that support Clang-based development tools.
+This C interface to Clang will never provide all of the information representation stored in Clang's C++ AST, nor should it: the intent is to maintain an API that is relatively stable from one release to the next, providing only the basic functionality needed to support development tools.
+The entire C interface of libclang is available in the file `Index.h`_
+
+Essential types overview
+-
+
+All types of libclang are prefixed with ``CX``
+
+CXIndex
+~~~
+An Index that consists of a set of translation units that would typically be linked together into an executable or library.
+
+CXTranslationUnit
+~
+A single translation unit, which resides in an index.
+
+CXCursor
+~
+A cursor representing a pointer to some element in the abstract syntax tree of a translation unit.
+
+
+Code example
+
+
+.. code-block:: cpp
+
+ // file.hpp
+ struct foo{
+int bar;
+int* bar_pointer;
+ };
+.. code-block:: cpp
+
+ #include
+ #include
+
+ int main(){
+CXIndex index = clang_createIndex(0, 0); //Create index
+CXTranslationUnit unit = clang_parseTranslationUnit(
+ index,
+ "file.hpp", nullptr, 0,
+ nullptr, 0,
+ CXTranslationUnit_None); //Parse "file.hpp"
+
+
+if (unit == nullptr){
+ std::cerr << "Unable to parse translation unit. Quitting.\n";
+ return 0;
+}
+CXCursor cursor = clang_getTranslationUnitCursor(unit); //Obtain a cursor at the root of the translation unit
+ }
+
+Visiting elements of an AST
+~~~
+The elements of an AST can be recursively visited with pre-order traversal with ``clang_visitChildren``.
+
+.. code-block:: cpp
+
+ clang_visitChildren(
+cursor, //Root cursor
+[](CXCursor current_cursor, CXCursor parent, CXClientData client_data){
+
+ CXString current_display_name = clang_getCursorDisplayName(current_cursor);
+ //Allocate a CXString representing the name of the current cursor
+
+ std::cout << "Visiting element " << clang_getCString(current_display_name) << "\n";
+ //Print the char* value of current_display_name
+
+ clang_disposeString(current_display_name);
+ //Since clang_getCursorDisplayName allocates a new CXString, it must be freed. This applies
+ //to all functions returning a CXString
+
+ return CXChildVisit_Recurse;
+
+
+}, //CXCursorVisitor: a function pointer
+nullptr //client_data
+);
+
+The return value of ``CXCursorVisitor``, the callable argument of ``clang_visitChildren``, can return of of the three:
+
+#. ``CXChildVisit_Break``: Terminates the cursor traversal
+
+#. ``CXChildVisit_Continue``: Continues the cursor traversal with the next sibling of the cursor just visited, without visiting its children.
+
+#. ``CXChildVisit_Recurse``: Recursively traverse the children of this cursor, using the same visitor and client data
+
+The expected output of that program is
+
+.. code-block::
+
+ Visiting element foo
+ Visiting element bar
+ Visiting element bar_pointer
+
+
+Extracting information from a Cursor
+
+.. The following functions take a ``CXCursor`` as an argument and return associated information.
+
+
+
+Extracting the Cursor kind
+""
+
+``CXCursorKind clang_getCursorKind(CXCursor)`` Describes the kind of entity that a cursor refers to. Example values:
+
+- ``CXCursor_StructDecl``: A C or C++ struct.
+- ``CXCursor_FieldDecl``: A field in a struct, union, or C++ class.
+- ``CXCursor_CallExpr``: An expression that calls a function
+
+
+Extracting the Cursor type
+""
+``CXType clang_getCursorType(CXCursor)``: Retrieve the type of a CXCursor (if any).
+
+``CXType`` is a struct with two members:
+
+.. code-block:: cpp
+
+ typedef struct {
+enum CXTypeKind kind;
+void *data[2];
+ } CXType;
+
+Example values for ``CXTypeKind kind``
+
+- ``CXType_I
