clang API Documentation

Functions
Mapping between cursors and source code
libclang: C Interface to Clang
Collaboration diagram for Mapping between cursors and source code:

Functions

CINDEX_LINKAGE CXCursor clang_getCursor (CXTranslationUnit, CXSourceLocation)
 Map a source location to the cursor that describes the entity at that location in the source code.
CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation (CXCursor)
 Retrieve the physical location of the source constructor referenced by the given cursor.
CINDEX_LINKAGE CXSourceRange clang_getCursorExtent (CXCursor)
 Retrieve the physical extent of the source construct referenced by the given cursor.

Detailed Description

Cursors represent a location within the Abstract Syntax Tree (AST). These routines help map between cursors and the physical locations where the described entities occur in the source code. The mapping is provided in both directions, so one can map from source code to the AST and back.


Function Documentation

Map a source location to the cursor that describes the entity at that location in the source code.

clang_getCursor() maps an arbitrary source location within a translation unit down to the most specific cursor that describes the entity at that location. For example, given an expression x + y, invoking clang_getCursor() with a source location pointing to "x" will return the cursor for "x"; similarly for "y". If the cursor points anywhere between "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() will return a cursor referring to the "+" expression.

Returns:
a cursor representing the entity at the given source location, or a NULL cursor if no such entity can be found.

Retrieve the physical extent of the source construct referenced by the given cursor.

The extent of a cursor starts with the file/line/column pointing at the first character within the source construct that the cursor refers to and ends with the last character withinin that source construct. For a declaration, the extent covers the declaration itself. For a reference, the extent covers the location of the reference (e.g., where the referenced entity was actually used).

Retrieve the physical location of the source constructor referenced by the given cursor.

The location of a declaration is typically the location of the name of that declaration, where the name of that declaration would occur if it is unnamed, or some keyword that introduces that particular declaration. The location of a reference is where that reference occurs within the source code.