|
Detailed Description
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.
To avoid namespace pollution, data types are prefixed with "CX" and functions are prefixed with "clang_".
Typedef Documentation
| typedef void* CXClientData |
| typedef void* CXIndex |
| typedef struct CXTranslationUnitImpl* CXTranslationUnit |
Enumeration Type Documentation
| enum CXAvailabilityKind |
Describes the availability of a particular entity, which indicates whether the use of this entity will result in a warning or error due to it being deprecated or unavailable.
- Enumerator:
| enum CXCursorKind |
Describes the kind of entity that a cursor refers to.
- Enumerator:
CXCursor_UnexposedDecl A declaration whose specific kind is not exposed via this interface.
Unexposed declarations have the same operations as any other kind of declaration; one can extract their location information, spelling, find their definitions, etc. However, the specific kind of the declaration is not reported.
CXCursor_StructDecl A C or C++ struct.
CXCursor_UnionDecl A C or C++ union.
CXCursor_ClassDecl A C++ class.
CXCursor_EnumDecl An enumeration.
CXCursor_FieldDecl A field (in C) or non-static data member (in C++) in a struct, union, or C++ class.
CXCursor_EnumConstantDecl An enumerator constant.
CXCursor_FunctionDecl A function.
CXCursor_VarDecl A variable.
CXCursor_ParmDecl A function or method parameter.
CXCursor_ObjCInterfaceDecl An Objective-C @interface.
CXCursor_ObjCCategoryDecl An Objective-C @interface for a category.
CXCursor_ObjCProtocolDecl An Objective-C @protocol declaration.
CXCursor_ObjCPropertyDecl An Objective-C @property declaration.
CXCursor_ObjCIvarDecl An Objective-C instance variable.
CXCursor_ObjCInstanceMethodDecl An Objective-C instance method.
CXCursor_ObjCClassMethodDecl An Objective-C class method.
CXCursor_ObjCImplementationDecl An Objective-C @implementation.
CXCursor_ObjCCategoryImplDecl An Objective-C @implementation for a category.
CXCursor_TypedefDecl A typedef.
CXCursor_CXXMethod A C++ class method.
CXCursor_Namespace A C++ namespace.
CXCursor_LinkageSpec A linkage specification, e.g. 'extern "C"'.
CXCursor_Constructor A C++ constructor.
CXCursor_Destructor A C++ destructor.
CXCursor_ConversionFunction A C++ conversion function.
CXCursor_TemplateTypeParameter A C++ template type parameter.
CXCursor_NonTypeTemplateParameter A C++ non-type template parameter.
CXCursor_TemplateTemplateParameter A C++ template template parameter.
CXCursor_FunctionTemplate A C++ function template.
CXCursor_ClassTemplate A C++ class template.
CXCursor_ClassTemplatePartialSpecialization A C++ class template partial specialization.
CXCursor_NamespaceAlias A C++ namespace alias declaration.
CXCursor_UsingDirective A C++ using directive.
CXCursor_UsingDeclaration A C++ using declaration.
CXCursor_TypeAliasDecl A C++ alias declaration.
CXCursor_ObjCSynthesizeDecl An Objective-C @synthesize definition.
CXCursor_ObjCDynamicDecl An Objective-C @dynamic definition.
CXCursor_CXXAccessSpecifier An access specifier.
CXCursor_FirstDecl CXCursor_LastDecl CXCursor_FirstRef CXCursor_ObjCSuperClassRef CXCursor_ObjCProtocolRef CXCursor_ObjCClassRef CXCursor_TypeRef A reference to a type declaration.
A type reference occurs anywhere where a type is named but not declared. For example, given:
typedef unsigned size_type; size_type size;
The typedef is a declaration of size_type (CXCursor_TypedefDecl), while the type of the variable "size" is referenced. The cursor referenced by the type of size is the typedef for size_type.
CXCursor_CXXBaseSpecifier CXCursor_TemplateRef A reference to a class template, function template, template template parameter, or class template partial specialization.
CXCursor_NamespaceRef A reference to a namespace or namespace alias.
CXCursor_MemberRef A reference to a member of a struct, union, or class that occurs in some non-expression context, e.g., a designated initializer.
CXCursor_LabelRef A reference to a labeled statement.
This cursor kind is used to describe the jump to "start_over" in the goto statement in the following example:
start_over: ++counter; goto start_over;A label reference cursor refers to a label statement.
CXCursor_OverloadedDeclRef A reference to a set of overloaded functions or function templates that has not yet been resolved to a specific function or function template.
An overloaded declaration reference cursor occurs in C++ templates where a dependent name refers to a function. For example:
template<typename T> void swap(T&, T&); struct X { ... }; void swap(X&, X&); template<typename T> void reverse(T* first, T* last) { while (first < last - 1) { swap(*first, *--last); ++first; } } struct Y { }; void swap(Y&, Y&);
Here, the identifier "swap" is associated with an overloaded declaration reference. In the template definition, "swap" refers to either of the two "swap" functions declared above, so both results will be available. At instantiation time, "swap" may also refer to other functions found via argument-dependent lookup (e.g., the "swap" function at the end of the example).
The functions
clang_getNumOverloadedDecls()andclang_getOverloadedDecl()can be used to retrieve the definitions referenced by this cursor.CXCursor_VariableRef A reference to a variable that occurs in some non-expression context, e.g., a C++ lambda capture list.
CXCursor_LastRef CXCursor_FirstInvalid CXCursor_InvalidFile CXCursor_NoDeclFound CXCursor_NotImplemented CXCursor_InvalidCode CXCursor_LastInvalid CXCursor_FirstExpr CXCursor_UnexposedExpr An expression whose specific kind is not exposed via this interface.
Unexposed expressions have the same operations as any other kind of expression; one can extract their location information, spelling, children, etc. However, the specific kind of the expression is not reported.
CXCursor_DeclRefExpr An expression that refers to some value declaration, such as a function, variable, or enumerator.
CXCursor_MemberRefExpr An expression that refers to a member of a struct, union, class, Objective-C class, etc.
CXCursor_CallExpr An expression that calls a function.
CXCursor_ObjCMessageExpr An expression that sends a message to an Objective-C object or class.
CXCursor_BlockExpr An expression that represents a block literal.
CXCursor_IntegerLiteral An integer literal.
CXCursor_FloatingLiteral A floating point number literal.
CXCursor_ImaginaryLiteral An imaginary number literal.
CXCursor_StringLiteral A string literal.
CXCursor_CharacterLiteral A character literal.
CXCursor_ParenExpr A parenthesized expression, e.g. "(1)".
This AST node is only formed if full location information is requested.
CXCursor_UnaryOperator This represents the unary-expression's (except sizeof and alignof).
CXCursor_ArraySubscriptExpr [C99 6.5.2.1] Array Subscripting.
CXCursor_BinaryOperator A builtin binary operation expression such as "x + y" or "x <= y".
CXCursor_CompoundAssignOperator Compound assignment such as "+=".
CXCursor_ConditionalOperator The ?: ternary operator.
CXCursor_CStyleCastExpr An explicit cast in C (C99 6.5.4) or a C-style cast in C++ (C++ [expr.cast]), which uses the syntax (Type)expr.
For example: (int)f.
CXCursor_CompoundLiteralExpr [C99 6.5.2.5]
CXCursor_InitListExpr Describes an C or C++ initializer list.
CXCursor_AddrLabelExpr The GNU address of label extension, representing &&label.
CXCursor_StmtExpr This is the GNU Statement Expression extension: ({int X=4; X;})
CXCursor_GenericSelectionExpr Represents a C11 generic selection.
CXCursor_GNUNullExpr Implements the GNU __null extension, which is a name for a null pointer constant that has integral type (e.g., int or long) and is the same size and alignment as a pointer.
The __null extension is typically only used by system headers, which define NULL as __null in C++ rather than using 0 (which is an integer that may not match the size of a pointer).
CXCursor_CXXStaticCastExpr C++'s static_cast<> expression.
CXCursor_CXXDynamicCastExpr C++'s dynamic_cast<> expression.
CXCursor_CXXReinterpretCastExpr C++'s reinterpret_cast<> expression.
CXCursor_CXXConstCastExpr C++'s const_cast<> expression.
CXCursor_CXXFunctionalCastExpr Represents an explicit C++ type conversion that uses "functional" notion (C++ [expr.type.conv]).
Example:
x = int(0.5);
CXCursor_CXXTypeidExpr A C++ typeid expression (C++ [expr.typeid]).
CXCursor_CXXBoolLiteralExpr [C++ 2.13.5] C++ Boolean Literal.
CXCursor_CXXNullPtrLiteralExpr [C++0x 2.14.7] C++ Pointer Literal.
CXCursor_CXXThisExpr Represents the "this" expression in C++.
CXCursor_CXXThrowExpr [C++ 15] C++ Throw Expression.
This handles 'throw' and 'throw' assignment-expression. When assignment-expression isn't present, Op will be null.
CXCursor_CXXNewExpr A new expression for memory allocation and constructor calls, e.g: "new CXXNewExpr(foo)".
CXCursor_CXXDeleteExpr A delete expression for memory deallocation and destructor calls, e.g. "delete[] pArray".
CXCursor_UnaryExpr A unary expression.
CXCursor_ObjCStringLiteral An Objective-C string literal i.e. "foo".
CXCursor_ObjCEncodeExpr An Objective-C @encode expression.
CXCursor_ObjCSelectorExpr An Objective-C @selector expression.
CXCursor_ObjCProtocolExpr An Objective-C @protocol expression.
CXCursor_ObjCBridgedCastExpr An Objective-C "bridged" cast expression, which casts between Objective-C pointers and C pointers, transferring ownership in the process.
NSString *str = (__bridge_transfer NSString *)CFCreateString();
CXCursor_PackExpansionExpr Represents a C++0x pack expansion that produces a sequence of expressions.
A pack expansion expression contains a pattern (which itself is an expression) followed by an ellipsis. For example:
template<typename F, typename ...Types> void forward(F f, Types &&...args) { f(static_cast<Types&&>(args)...); }
CXCursor_SizeOfPackExpr Represents an expression that computes the length of a parameter pack.
template<typename ...Types> struct count { static const unsigned value = sizeof...(Types); };
CXCursor_LambdaExpr CXCursor_ObjCBoolLiteralExpr Objective-c Boolean Literal.
CXCursor_ObjCSelfExpr Represents the "self" expression in an Objective-C method.
CXCursor_LastExpr CXCursor_FirstStmt CXCursor_UnexposedStmt A statement whose specific kind is not exposed via this interface.
Unexposed statements have the same operations as any other kind of statement; one can extract their location information, spelling, children, etc. However, the specific kind of the statement is not reported.
CXCursor_LabelStmt A labelled statement in a function.
This cursor kind is used to describe the "start_over:" label statement in the following example:
start_over: ++counter;CXCursor_CompoundStmt A group of statements like { stmt stmt }.
This cursor kind is used to describe compound statements, e.g. function bodies.
CXCursor_CaseStmt A case statement.
CXCursor_DefaultStmt A default statement.
CXCursor_IfStmt An if statement.
CXCursor_SwitchStmt A switch statement.
CXCursor_WhileStmt A while statement.
CXCursor_DoStmt A do statement.
CXCursor_ForStmt A for statement.
CXCursor_GotoStmt A goto statement.
CXCursor_IndirectGotoStmt An indirect goto statement.
CXCursor_ContinueStmt A continue statement.
CXCursor_BreakStmt A break statement.
CXCursor_ReturnStmt A return statement.
CXCursor_GCCAsmStmt A GCC inline assembly statement extension.
CXCursor_AsmStmt CXCursor_ObjCAtTryStmt Objective-C's overall @try-@catch-@finally statement.
CXCursor_ObjCAtCatchStmt Objective-C's @catch statement.
CXCursor_ObjCAtFinallyStmt Objective-C's @finally statement.
CXCursor_ObjCAtThrowStmt Objective-C's @throw statement.
CXCursor_ObjCAtSynchronizedStmt Objective-C's @synchronized statement.
CXCursor_ObjCAutoreleasePoolStmt Objective-C's autorelease pool statement.
CXCursor_ObjCForCollectionStmt Objective-C's collection statement.
CXCursor_CXXCatchStmt C++'s catch statement.
CXCursor_CXXTryStmt C++'s try statement.
CXCursor_CXXForRangeStmt C++'s for (* : *) statement.
CXCursor_SEHTryStmt Windows Structured Exception Handling's try statement.
CXCursor_SEHExceptStmt Windows Structured Exception Handling's except statement.
CXCursor_SEHFinallyStmt Windows Structured Exception Handling's finally statement.
CXCursor_MSAsmStmt A MS inline assembly statement extension.
CXCursor_NullStmt The null satement ";": C99 6.8.3p3.
This cursor kind is used to describe the null statement.
CXCursor_DeclStmt Adaptor class for mixing declarations with statements and expressions.
CXCursor_OMPParallelDirective OpenMP parallel directive.
CXCursor_OMPSimdDirective OpenMP simd directive.
CXCursor_OMPForDirective OpenMP for directive.
CXCursor_OMPSectionsDirective OpenMP sections directive.
CXCursor_OMPSectionDirective OpenMP section directive.
CXCursor_OMPSingleDirective OpenMP single directive.
CXCursor_OMPParallelForDirective OpenMP parallel for directive.
CXCursor_OMPParallelSectionsDirective OpenMP parallel sections directive.
CXCursor_OMPTaskDirective OpenMP task directive.
CXCursor_OMPMasterDirective OpenMP master directive.
CXCursor_OMPCriticalDirective OpenMP critical directive.
CXCursor_OMPTaskyieldDirective OpenMP taskyield directive.
CXCursor_OMPBarrierDirective OpenMP barrier directive.
CXCursor_OMPTaskwaitDirective OpenMP taskwait directive.
CXCursor_OMPFlushDirective OpenMP flush directive.
CXCursor_SEHLeaveStmt Windows Structured Exception Handling's leave statement.
CXCursor_OMPOrderedDirective OpenMP ordered directive.
CXCursor_OMPAtomicDirective OpenMP atomic directive.
CXCursor_OMPForSimdDirective OpenMP for simd directive.
CXCursor_OMPParallelForSimdDirective OpenMP parallel for simd directive.
CXCursor_OMPTargetDirective OpenMP target directive.
CXCursor_OMPTeamsDirective OpenMP teams directive.
CXCursor_LastStmt CXCursor_TranslationUnit Cursor that represents the translation unit itself.
The translation unit cursor exists primarily to act as the root cursor for traversing the contents of a translation unit.
CXCursor_FirstAttr CXCursor_UnexposedAttr An attribute whose specific kind is not exposed via this interface.
CXCursor_IBActionAttr CXCursor_IBOutletAttr CXCursor_IBOutletCollectionAttr CXCursor_CXXFinalAttr CXCursor_CXXOverrideAttr CXCursor_AnnotateAttr CXCursor_AsmLabelAttr CXCursor_PackedAttr CXCursor_PureAttr CXCursor_ConstAttr CXCursor_NoDuplicateAttr CXCursor_CUDAConstantAttr CXCursor_CUDADeviceAttr CXCursor_CUDAGlobalAttr CXCursor_CUDAHostAttr CXCursor_CUDASharedAttr CXCursor_LastAttr CXCursor_PreprocessingDirective CXCursor_MacroDefinition CXCursor_MacroExpansion CXCursor_MacroInstantiation CXCursor_InclusionDirective CXCursor_FirstPreprocessing CXCursor_LastPreprocessing CXCursor_ModuleImportDecl A module import declaration.
CXCursor_FirstExtraDecl CXCursor_LastExtraDecl
| enum CXGlobalOptFlags |
- Enumerator:
CXGlobalOpt_None Used to indicate that no special CXIndex options are needed.
CXGlobalOpt_ThreadBackgroundPriorityForIndexing Used to indicate that threads that libclang creates for indexing purposes should use background priority.
Affects clang_indexSourceFile, clang_indexTranslationUnit, clang_parseTranslationUnit, clang_saveTranslationUnit.
CXGlobalOpt_ThreadBackgroundPriorityForEditing Used to indicate that threads that libclang creates for editing purposes should use background priority.
Affects clang_reparseTranslationUnit, clang_codeCompleteAt, clang_annotateTokens
CXGlobalOpt_ThreadBackgroundPriorityForAll Used to indicate that all threads that libclang creates should use background priority.
Function Documentation
| CINDEX_LINKAGE CXIndex clang_createIndex | ( | int | excludeDeclarationsFromPCH, |
| int | displayDiagnostics | ||
| ) |
Provides a shared context for creating translation units.
It provides two options:
- excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" declarations (when loading any new translation units). A "local" declaration is one that belongs in the translation unit itself and not in a precompiled header that was used by the translation unit. If zero, all declarations will be enumerated.
Here is an example:
// excludeDeclsFromPCH = 1, displayDiagnostics=1 Idx = clang_createIndex(1, 1); // IndexTest.pch was produced with the following command: // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); // This will load all the symbols from 'IndexTest.pch' clang_visitChildren(clang_getTranslationUnitCursor(TU), TranslationUnitVisitor, 0); clang_disposeTranslationUnit(TU); // This will load all the symbols from 'IndexTest.c', excluding symbols // from 'IndexTest.pch'. char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" }; TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args, 0, 0); clang_visitChildren(clang_getTranslationUnitCursor(TU), TranslationUnitVisitor, 0); clang_disposeTranslationUnit(TU);
This process of creating the 'pch', loading it separately, and using it (via -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks (which gives the indexer the same performance benefit as the compiler).
Gets the general options associated with a CXIndex.
- Returns:
- A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that are associated with the given CXIndex object.
| CINDEX_LINKAGE void clang_CXIndex_setGlobalOptions | ( | CXIndex | , |
| unsigned | options | ||
| ) |
Sets general options associated with a CXIndex.
For example:
CXIndex idx = ...; clang_CXIndex_setGlobalOptions(idx, clang_CXIndex_getGlobalOptions(idx) | CXGlobalOpt_ThreadBackgroundPriorityForIndexing);
- Parameters:
-
options A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags.
| CINDEX_LINKAGE void clang_disposeIndex | ( | CXIndex | index | ) |
Destroy the given index.
The index must not be destroyed until all of the translation units created within that index have been destroyed.