clang API Documentation

Enumerations | Functions
Cross-referencing in the AST
libclang: C Interface to Clang
Collaboration diagram for Cross-referencing in the AST:

Enumerations

enum  CXObjCPropertyAttrKind {
  CXObjCPropertyAttr_noattr = 0x00, CXObjCPropertyAttr_readonly = 0x01, CXObjCPropertyAttr_getter = 0x02, CXObjCPropertyAttr_assign = 0x04,
  CXObjCPropertyAttr_readwrite = 0x08, CXObjCPropertyAttr_retain = 0x10, CXObjCPropertyAttr_copy = 0x20, CXObjCPropertyAttr_nonatomic = 0x40,
  CXObjCPropertyAttr_setter = 0x80, CXObjCPropertyAttr_atomic = 0x100, CXObjCPropertyAttr_weak = 0x200, CXObjCPropertyAttr_strong = 0x400,
  CXObjCPropertyAttr_unsafe_unretained = 0x800
}
 Property attributes for a CXCursor_ObjCPropertyDecl. More...
enum  CXObjCDeclQualifierKind {
  CXObjCDeclQualifier_None = 0x0, CXObjCDeclQualifier_In = 0x1, CXObjCDeclQualifier_Inout = 0x2, CXObjCDeclQualifier_Out = 0x4,
  CXObjCDeclQualifier_Bycopy = 0x8, CXObjCDeclQualifier_Byref = 0x10, CXObjCDeclQualifier_Oneway = 0x20
}
 'Qualifiers' written next to the return and parameter types in Objective-C method declarations. More...

Functions

CINDEX_LINKAGE CXString clang_getCursorUSR (CXCursor)
 Retrieve a Unified Symbol Resolution (USR) for the entity referenced by the given cursor.
CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass (const char *class_name)
 Construct a USR for a specified Objective-C class.
CINDEX_LINKAGE CXString clang_constructUSR_ObjCCategory (const char *class_name, const char *category_name)
 Construct a USR for a specified Objective-C category.
CINDEX_LINKAGE CXString clang_constructUSR_ObjCProtocol (const char *protocol_name)
 Construct a USR for a specified Objective-C protocol.
CINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar (const char *name, CXString classUSR)
 Construct a USR for a specified Objective-C instance variable and the USR for its containing class.
CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod (const char *name, unsigned isInstanceMethod, CXString classUSR)
 Construct a USR for a specified Objective-C method and the USR for its containing class.
CINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty (const char *property, CXString classUSR)
 Construct a USR for a specified Objective-C property and the USR for its containing class.
CINDEX_LINKAGE CXString clang_getCursorSpelling (CXCursor)
 Retrieve a name for the entity referenced by this cursor.
CINDEX_LINKAGE CXSourceRange clang_Cursor_getSpellingNameRange (CXCursor, unsigned pieceIndex, unsigned options)
 Retrieve a range for a piece that forms the cursors spelling name. Most of the times there is only one range for the complete spelling but for Objective-C methods and Objective-C message expressions, there are multiple pieces for each selector identifier.
CINDEX_LINKAGE CXString clang_getCursorDisplayName (CXCursor)
 Retrieve the display name for the entity referenced by this cursor.
CINDEX_LINKAGE CXCursor clang_getCursorReferenced (CXCursor)
 For a cursor that is a reference, retrieve a cursor representing the entity that it references.
CINDEX_LINKAGE CXCursor clang_getCursorDefinition (CXCursor)
 For a cursor that is either a reference to or a declaration of some entity, retrieve a cursor that describes the definition of that entity.
CINDEX_LINKAGE unsigned clang_isCursorDefinition (CXCursor)
 Determine whether the declaration pointed to by this cursor is also a definition of that entity.
CINDEX_LINKAGE CXCursor clang_getCanonicalCursor (CXCursor)
 Retrieve the canonical cursor corresponding to the given cursor.
CINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex (CXCursor)
 If the cursor points to a selector identifier in an Objective-C method or message expression, this returns the selector index.
CINDEX_LINKAGE int clang_Cursor_isDynamicCall (CXCursor C)
 Given a cursor pointing to a C++ method call or an Objective-C message, returns non-zero if the method/message is "dynamic", meaning:
CINDEX_LINKAGE CXType clang_Cursor_getReceiverType (CXCursor C)
 Given a cursor pointing to an Objective-C message, returns the CXType of the receiver.
CINDEX_LINKAGE unsigned clang_Cursor_getObjCPropertyAttributes (CXCursor C, unsigned reserved)
 Given a cursor that represents a property declaration, return the associated property attributes. The bits are formed from CXObjCPropertyAttrKind.
CINDEX_LINKAGE unsigned clang_Cursor_getObjCDeclQualifiers (CXCursor C)
 Given a cursor that represents an Objective-C method or parameter declaration, return the associated Objective-C qualifiers for the return type or the parameter respectively. The bits are formed from CXObjCDeclQualifierKind.
CINDEX_LINKAGE unsigned clang_Cursor_isObjCOptional (CXCursor C)
 Given a cursor that represents an Objective-C method or property declaration, return non-zero if the declaration was affected by "@optional". Returns zero if the cursor is not such a declaration or it is "@required".
CINDEX_LINKAGE unsigned clang_Cursor_isVariadic (CXCursor C)
 Returns non-zero if the given cursor is a variadic function or method.
CINDEX_LINKAGE CXSourceRange clang_Cursor_getCommentRange (CXCursor C)
 Given a cursor that represents a declaration, return the associated comment's source range. The range may include multiple consecutive comments with whitespace in between.
CINDEX_LINKAGE CXString clang_Cursor_getRawCommentText (CXCursor C)
 Given a cursor that represents a declaration, return the associated comment text, including comment markers.
CINDEX_LINKAGE CXString clang_Cursor_getBriefCommentText (CXCursor C)
 Given a cursor that represents a documentable entity (e.g., declaration), return the associated \brief paragraph; otherwise return the first paragraph.

Detailed Description

These routines provide the ability to determine references within and across translation units, by providing the names of the entities referenced by cursors, follow reference cursors to the declarations they reference, and associate declarations with their definitions.


Enumeration Type Documentation

'Qualifiers' written next to the return and parameter types in Objective-C method declarations.

Enumerator:
CXObjCDeclQualifier_None 
CXObjCDeclQualifier_In 
CXObjCDeclQualifier_Inout 
CXObjCDeclQualifier_Out 
CXObjCDeclQualifier_Bycopy 
CXObjCDeclQualifier_Byref 
CXObjCDeclQualifier_Oneway 

Definition at line 3595 of file Index.h.

Property attributes for a CXCursor_ObjCPropertyDecl.

Enumerator:
CXObjCPropertyAttr_noattr 
CXObjCPropertyAttr_readonly 
CXObjCPropertyAttr_getter 
CXObjCPropertyAttr_assign 
CXObjCPropertyAttr_readwrite 
CXObjCPropertyAttr_retain 
CXObjCPropertyAttr_copy 
CXObjCPropertyAttr_nonatomic 
CXObjCPropertyAttr_setter 
CXObjCPropertyAttr_atomic 
CXObjCPropertyAttr_weak 
CXObjCPropertyAttr_strong 
CXObjCPropertyAttr_unsafe_unretained 

Definition at line 3565 of file Index.h.


Function Documentation

CINDEX_LINKAGE CXString clang_constructUSR_ObjCCategory ( const char *  class_name,
const char *  category_name 
)

Construct a USR for a specified Objective-C category.

Construct a USR for a specified Objective-C class.

CINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar ( const char *  name,
CXString  classUSR 
)

Construct a USR for a specified Objective-C instance variable and the USR for its containing class.

CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod ( const char *  name,
unsigned  isInstanceMethod,
CXString  classUSR 
)

Construct a USR for a specified Objective-C method and the USR for its containing class.

CINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty ( const char *  property,
CXString  classUSR 
)

Construct a USR for a specified Objective-C property and the USR for its containing class.

CINDEX_LINKAGE CXString clang_constructUSR_ObjCProtocol ( const char *  protocol_name)

Construct a USR for a specified Objective-C protocol.

Given a cursor that represents a documentable entity (e.g., declaration), return the associated \brief paragraph; otherwise return the first paragraph.

Given a cursor that represents a declaration, return the associated comment's source range. The range may include multiple consecutive comments with whitespace in between.

Given a cursor that represents an Objective-C method or parameter declaration, return the associated Objective-C qualifiers for the return type or the parameter respectively. The bits are formed from CXObjCDeclQualifierKind.

Given a cursor that represents a property declaration, return the associated property attributes. The bits are formed from CXObjCPropertyAttrKind.

Parameters:
reservedReserved for future use, pass 0.

If the cursor points to a selector identifier in an Objective-C method or message expression, this returns the selector index.

After getting a cursor with clang_getCursor, this can be called to determine if the location points to a selector identifier.

Returns:
The selector index if the cursor is an Objective-C method or message expression and the cursor is pointing to a selector identifier, or -1 otherwise.

Given a cursor that represents a declaration, return the associated comment text, including comment markers.

Given a cursor pointing to an Objective-C message, returns the CXType of the receiver.

Retrieve a range for a piece that forms the cursors spelling name. Most of the times there is only one range for the complete spelling but for Objective-C methods and Objective-C message expressions, there are multiple pieces for each selector identifier.

Parameters:
pieceIndexthe index of the spelling name piece. If this is greater than the actual number of pieces, it will return a NULL (invalid) range.
optionsReserved.

Given a cursor pointing to a C++ method call or an Objective-C message, returns non-zero if the method/message is "dynamic", meaning:

For a C++ method: the call is virtual. For an Objective-C message: the receiver is an object instance, not 'super' or a specific class.

If the method/message is "static" or the cursor does not point to a method/message, it will return zero.

Given a cursor that represents an Objective-C method or property declaration, return non-zero if the declaration was affected by "@optional". Returns zero if the cursor is not such a declaration or it is "@required".

Returns non-zero if the given cursor is a variadic function or method.

Retrieve the canonical cursor corresponding to the given cursor.

In the C family of languages, many kinds of entities can be declared several times within a single translation unit. For example, a structure type can be forward-declared (possibly multiple times) and later defined:

 struct X;
 struct X;
 struct X {
   int member;
 };

The declarations and the definition of X are represented by three different cursors, all of which are declarations of the same underlying entity. One of these cursor is considered the "canonical" cursor, which is effectively the representative for the underlying entity. One can determine if two cursors are declarations of the same underlying entity by comparing their canonical cursors.

Returns:
The canonical cursor for the entity referred to by the given cursor.

For a cursor that is either a reference to or a declaration of some entity, retrieve a cursor that describes the definition of that entity.

Some entities can be declared multiple times within a translation unit, but only one of those declarations can also be a definition. For example, given:

  int f(int, int);
  int g(int x, int y) { return f(x, y); }
  int f(int a, int b) { return a + b; }
  int f(int, int);

there are three declarations of the function "f", but only the second one is a definition. The clang_getCursorDefinition() function will take any cursor pointing to a declaration of "f" (the first or fourth lines of the example) or a cursor referenced that uses "f" (the call to "f' inside "g") and will return a declaration cursor pointing to the definition (the second "f" declaration).

If given a cursor for which there is no corresponding definition, e.g., because there is no definition of that entity within this translation unit, returns a NULL cursor.

Retrieve the display name for the entity referenced by this cursor.

The display name contains extra information that helps identify the cursor, such as the parameters of a function or template or the arguments of a class template specialization.

For a cursor that is a reference, retrieve a cursor representing the entity that it references.

Reference cursors refer to other entities in the AST. For example, an Objective-C superclass reference cursor refers to an Objective-C class. This function produces the cursor for the Objective-C class from the cursor for the superclass reference. If the input cursor is a declaration or definition, it returns that declaration or definition unchanged. Otherwise, returns the NULL cursor.

Retrieve a name for the entity referenced by this cursor.

Retrieve a Unified Symbol Resolution (USR) for the entity referenced by the given cursor.

A Unified Symbol Resolution (USR) is a string that identifies a particular entity (function, class, variable, etc.) within a program. USRs can be compared across translation units to determine, e.g., when references in one translation refer to an entity defined in another translation unit.

Determine whether the declaration pointed to by this cursor is also a definition of that entity.