clang 20.0.0git
Typedefs | Enumerations | Functions
Cross-referencing in the AST

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. More...

Collaboration diagram for Cross-referencing in the AST:

Typedefs

typedef void * CXPrintingPolicy
 Opaque pointer representing a policy that controls pretty printing for clang_getCursorPrettyPrinted.
 

Enumerations

enum  CXPrintingPolicyProperty {
  CXPrintingPolicy_Indentation , CXPrintingPolicy_SuppressSpecifiers , CXPrintingPolicy_SuppressTagKeyword , CXPrintingPolicy_IncludeTagDefinition ,
  CXPrintingPolicy_SuppressScope , CXPrintingPolicy_SuppressUnwrittenScope , CXPrintingPolicy_SuppressInitializers , CXPrintingPolicy_ConstantArraySizeAsWritten ,
  CXPrintingPolicy_AnonymousTagLocations , CXPrintingPolicy_SuppressStrongLifetime , CXPrintingPolicy_SuppressLifetimeQualifiers , CXPrintingPolicy_SuppressTemplateArgsInCXXConstructors ,
  CXPrintingPolicy_Bool , CXPrintingPolicy_Restrict , CXPrintingPolicy_Alignof , CXPrintingPolicy_UnderscoreAlignof ,
  CXPrintingPolicy_UseVoidForZeroParams , CXPrintingPolicy_TerseOutput , CXPrintingPolicy_PolishForDeclaration , CXPrintingPolicy_Half ,
  CXPrintingPolicy_MSWChar , CXPrintingPolicy_IncludeNewlines , CXPrintingPolicy_MSVCFormatting , CXPrintingPolicy_ConstantsAsWritten ,
  CXPrintingPolicy_SuppressImplicitBase , CXPrintingPolicy_FullyQualifiedName , CXPrintingPolicy_LastProperty = CXPrintingPolicy_FullyQualifiedName
}
 Properties for the printing policy. More...
 
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 , CXObjCPropertyAttr_class = 0x1000
}
 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.
 
CINDEX_LINKAGE unsigned clang_PrintingPolicy_getProperty (CXPrintingPolicy Policy, enum CXPrintingPolicyProperty Property)
 Get a property value for the given printing policy.
 
CINDEX_LINKAGE void clang_PrintingPolicy_setProperty (CXPrintingPolicy Policy, enum CXPrintingPolicyProperty Property, unsigned Value)
 Set a property value for the given printing policy.
 
CINDEX_LINKAGE CXPrintingPolicy clang_getCursorPrintingPolicy (CXCursor)
 Retrieve the default policy for the cursor.
 
CINDEX_LINKAGE void clang_PrintingPolicy_dispose (CXPrintingPolicy Policy)
 Release a printing policy.
 
CINDEX_LINKAGE CXString clang_getCursorPrettyPrinted (CXCursor Cursor, CXPrintingPolicy Policy)
 Pretty print declarations.
 
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 or property reference, or C++ method call, 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.
 
CINDEX_LINKAGE CXString clang_Cursor_getObjCPropertyGetterName (CXCursor C)
 Given a cursor that represents a property declaration, return the name of the method that implements the getter.
 
CINDEX_LINKAGE CXString clang_Cursor_getObjCPropertySetterName (CXCursor C)
 Given a cursor that represents a property declaration, return the name of the method that implements the setter, if any.
 
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.
 
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".
 
CINDEX_LINKAGE unsigned clang_Cursor_isVariadic (CXCursor C)
 Returns non-zero if the given cursor is a variadic function or method.
 
CINDEX_LINKAGE unsigned clang_Cursor_isExternalSymbol (CXCursor C, CXString *language, CXString *definedIn, unsigned *isGenerated)
 Returns non-zero if the given cursor points to a symbol marked with external_source_symbol attribute.
 
CINDEX_LINKAGE CXSourceRange clang_Cursor_getCommentRange (CXCursor C)
 Given a cursor that represents a declaration, return the associated comment's source range.
 
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.
 

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.

Typedef Documentation

◆ CXPrintingPolicy

typedef void* CXPrintingPolicy

Opaque pointer representing a policy that controls pretty printing for clang_getCursorPrettyPrinted.

Definition at line 4064 of file Index.h.

Enumeration Type Documentation

◆ CXObjCDeclQualifierKind

'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 4305 of file Index.h.

◆ CXObjCPropertyAttrKind

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 
CXObjCPropertyAttr_class 

Definition at line 4262 of file Index.h.

◆ CXPrintingPolicyProperty

Properties for the printing policy.

See clang::PrintingPolicy for more information.

Enumerator
CXPrintingPolicy_Indentation 
CXPrintingPolicy_SuppressSpecifiers 
CXPrintingPolicy_SuppressTagKeyword 
CXPrintingPolicy_IncludeTagDefinition 
CXPrintingPolicy_SuppressScope 
CXPrintingPolicy_SuppressUnwrittenScope 
CXPrintingPolicy_SuppressInitializers 
CXPrintingPolicy_ConstantArraySizeAsWritten 
CXPrintingPolicy_AnonymousTagLocations 
CXPrintingPolicy_SuppressStrongLifetime 
CXPrintingPolicy_SuppressLifetimeQualifiers 
CXPrintingPolicy_SuppressTemplateArgsInCXXConstructors 
CXPrintingPolicy_Bool 
CXPrintingPolicy_Restrict 
CXPrintingPolicy_Alignof 
CXPrintingPolicy_UnderscoreAlignof 
CXPrintingPolicy_UseVoidForZeroParams 
CXPrintingPolicy_TerseOutput 
CXPrintingPolicy_PolishForDeclaration 
CXPrintingPolicy_Half 
CXPrintingPolicy_MSWChar 
CXPrintingPolicy_IncludeNewlines 
CXPrintingPolicy_MSVCFormatting 
CXPrintingPolicy_ConstantsAsWritten 
CXPrintingPolicy_SuppressImplicitBase 
CXPrintingPolicy_FullyQualifiedName 
CXPrintingPolicy_LastProperty 

Definition at line 4071 of file Index.h.

Function Documentation

◆ clang_constructUSR_ObjCCategory()

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

Construct a USR for a specified Objective-C category.

◆ clang_constructUSR_ObjCClass()

CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass ( const char *  class_name)

Construct a USR for a specified Objective-C class.

◆ clang_constructUSR_ObjCIvar()

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.

◆ clang_constructUSR_ObjCMethod()

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.

◆ clang_constructUSR_ObjCProperty()

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.

◆ clang_constructUSR_ObjCProtocol()

CINDEX_LINKAGE CXString clang_constructUSR_ObjCProtocol ( const char *  protocol_name)

Construct a USR for a specified Objective-C protocol.

◆ clang_Cursor_getBriefCommentText()

CINDEX_LINKAGE CXString clang_Cursor_getBriefCommentText ( CXCursor  C)

Given a cursor that represents a documentable entity (e.g., declaration), return the associated.

◆ clang_Cursor_getCommentRange()

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.

◆ clang_Cursor_getObjCDeclQualifiers()

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.

◆ clang_Cursor_getObjCPropertyAttributes()

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.

Parameters
reservedReserved for future use, pass 0.

◆ clang_Cursor_getObjCPropertyGetterName()

CINDEX_LINKAGE CXString clang_Cursor_getObjCPropertyGetterName ( CXCursor  C)

Given a cursor that represents a property declaration, return the name of the method that implements the getter.

◆ clang_Cursor_getObjCPropertySetterName()

CINDEX_LINKAGE CXString clang_Cursor_getObjCPropertySetterName ( CXCursor  C)

Given a cursor that represents a property declaration, return the name of the method that implements the setter, if any.

◆ clang_Cursor_getObjCSelectorIndex()

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.

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.

◆ clang_Cursor_getRawCommentText()

CINDEX_LINKAGE CXString clang_Cursor_getRawCommentText ( CXCursor  C)

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

◆ clang_Cursor_getReceiverType()

CINDEX_LINKAGE CXType clang_Cursor_getReceiverType ( CXCursor  C)

Given a cursor pointing to an Objective-C message or property reference, or C++ method call, returns the CXType of the receiver.

◆ clang_Cursor_getSpellingNameRange()

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.

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.

◆ clang_Cursor_isDynamicCall()

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:

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.

◆ clang_Cursor_isExternalSymbol()

CINDEX_LINKAGE unsigned clang_Cursor_isExternalSymbol ( CXCursor  C,
CXString language,
CXString definedIn,
unsigned isGenerated 
)

Returns non-zero if the given cursor points to a symbol marked with external_source_symbol attribute.

Parameters
languageIf non-NULL, and the attribute is present, will be set to the 'language' string from the attribute.
definedInIf non-NULL, and the attribute is present, will be set to the 'definedIn' string from the attribute.
isGeneratedIf non-NULL, and the attribute is present, will be set to non-zero if the 'generated_declaration' is set in the attribute.

◆ clang_Cursor_isObjCOptional()

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".

◆ clang_Cursor_isVariadic()

CINDEX_LINKAGE unsigned clang_Cursor_isVariadic ( CXCursor  C)

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

◆ clang_getCanonicalCursor()

CINDEX_LINKAGE CXCursor clang_getCanonicalCursor ( CXCursor  )

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;
};
#define X(type, name)
Definition: Value.h:143

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.

◆ clang_getCursorDefinition()

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.

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);
__device__ __2f16 b

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.

◆ clang_getCursorDisplayName()

CINDEX_LINKAGE CXString clang_getCursorDisplayName ( CXCursor  )

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.

◆ clang_getCursorPrettyPrinted()

CINDEX_LINKAGE CXString clang_getCursorPrettyPrinted ( CXCursor  Cursor,
CXPrintingPolicy  Policy 
)

Pretty print declarations.

Parameters
CursorThe cursor representing a declaration.
PolicyThe policy to control the entities being printed. If NULL, a default policy is used.
Returns
The pretty printed declaration or the empty string for other cursors.

◆ clang_getCursorPrintingPolicy()

CINDEX_LINKAGE CXPrintingPolicy clang_getCursorPrintingPolicy ( CXCursor  )

Retrieve the default policy for the cursor.

The policy should be released after use with clang_PrintingPolicy_dispose.

◆ clang_getCursorReferenced()

CINDEX_LINKAGE CXCursor clang_getCursorReferenced ( CXCursor  )

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.

◆ clang_getCursorSpelling()

CINDEX_LINKAGE CXString clang_getCursorSpelling ( CXCursor  )

Retrieve a name for the entity referenced by this cursor.

◆ clang_getCursorUSR()

CINDEX_LINKAGE CXString clang_getCursorUSR ( CXCursor  )

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.

◆ clang_isCursorDefinition()

CINDEX_LINKAGE unsigned clang_isCursorDefinition ( CXCursor  )

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

◆ clang_PrintingPolicy_dispose()

CINDEX_LINKAGE void clang_PrintingPolicy_dispose ( CXPrintingPolicy  Policy)

Release a printing policy.

◆ clang_PrintingPolicy_getProperty()

CINDEX_LINKAGE unsigned clang_PrintingPolicy_getProperty ( CXPrintingPolicy  Policy,
enum CXPrintingPolicyProperty  Property 
)

Get a property value for the given printing policy.

◆ clang_PrintingPolicy_setProperty()

CINDEX_LINKAGE void clang_PrintingPolicy_setProperty ( CXPrintingPolicy  Policy,
enum CXPrintingPolicyProperty  Property,
unsigned  Value 
)

Set a property value for the given printing policy.