Clang API Reference

Free and convert a CXString to String. Note this function will free the given CXString so ensure it is not called twice.

annotateTokens(tu::TranslationUnit, tokens, token_num, cursors)

Annotate the given set of tokens by providing cursors for each token that can be mapped to a specific entity within the abstract syntax tree.

ast_file(mod::CLModule) -> CLFile

Given a module, return the module file where the provided module object came from.

children(cursor::CXCursor) -> Vector{CXCursor}
children(cursor::CLCursor) -> Vector{CLCursor}

Return immediate cursors of the given cursor.

fields(ty::CXType) -> Vector{CXCursor}
fields(ty::CLType) -> Vector{CLCursor}

Return a child cursor vector of the given cursor.

file(c::CLCursor) -> CLFile

Return the file referenced by the input cursor.

file_line_column(CLCursor) -> (CLFile, Int, Int)

Return file, line and column number.

full_name(mod::CLModule)

Given a module, return the full name of the module, e.g. "std.vector".

getAddressSpace(t::Union{CXType,CLType})

Returns the address space of the given type. Wrapper for libclang's clang_getAddressSpace.

getAlignOf(t::CXType) -> Int
getAlignOf(t::CLType) -> Int

Return the alignment of a type in bytes as per C++[expr.alignof] standard.

It returns a minus number for layout errors, please convert the result to a CXTypeLayoutError to see what the error is.

getArgType(t::CXType, i::Unsigned) -> CXType
getArgType(t::Union{CLFunctionNoProto,CLFunctionProto}, i::Integer) -> CLType

Return the type of a parameter of a function type. Wrapper for libclang's clang_getArgType.

getArgument(c::CXCursor, i::Integer) -> CXCursor
getArgument(c::Union{CLFunctionDecl,CLCXXMethod,CLConstructor,CLFunctionTemplate}, i::Integer) -> CLCursor

Return the argument cursor of a function or method.

getArguments(c::Union{BlockCommand, InlineCommand}) -> Vector{String}

Return the arguments of a command.

getAsHTML(c::Union{CXComment, FullComment})

Convert a comment into an HTML fragment. Check libclang's documentation for more details.

getAsString(c::Union{CXComment, HTMLStartTag, HTMLEndTag})

Convert an HTML tag to its string representation.

getAsXML(c::Union{CXComment, FullComment})

Convert a comment into an XML document.

getAttributes(c::Union{CXComment, HTMLStartTag}) -> Vector{Pair{String, String}}

Return the attributes of an HTML tag.

getCanonicalCursor(c::CXCursor) -> CXCursor
getCanonicalCursor(c::CLCursor) -> CLCursor

Return the getCanonicalCursor cursor corresponding to the given cursor.

getCanonicalType(t::CXType) -> CXType
getCanonicalType(t::CLType) -> CLType

Return the canonical type for a CXType.

Clang's type system explicitly models typedefs and all the ways a specific type can be represented. The canonical type is the underlying type with all the "sugar" removed. For example, if 'T' is a typedef for 'int', the canonical type for 'T' would be 'int'. Wrapper for libclang's clang_getCanonicalType.

getCommandName(c::InlineCommand) -> String
getCommandName(c::BlockCommand) -> String

Return the command name of a command, e.g. "brief" for \brief blah.

getCompileCommands(db::CLCompilationDatabase, file::AbstractString)

Get all compile commands for a file given its complete path.

getCompileCommands(db::CLCompilationDatabase)

Get all compile commands from a compilation database.

getCursorDefinition(c::CXCursor) -> CXCursor
getCursorDefinition(c::CLCursor) -> CLCursor

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.

getCursorExtent(c::Union{CXCursor,CLCursor}) -> CXSourceRange

Return 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 within 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).

getCursorLanguage(c::Union{CXCursor,CLCursor}) -> CXLanguageKind

Return the language of the entity referred to by a given cursor. Return CXLanguage_Invalid if the input cursor is not a decl. Note that, this function has limitations, for example, it cannot distinguish C++ structs from C structs, in both cases, it returns CXLanguage_C.

getCursorLexicalParent(c::CXCursor) -> CXCursor
getCursorLexicalParent(c::CLCursor) -> CLCursor

Return the lexical parent of the given cursor. Please checkout libclang's doc to know more.

getCursorLinkage(c::Union{CXCursor,CLCursor}) -> CXLinkageKind

Return the linkage of the entity referred to by a given cursor.

getCursorLocation(c::Union{CXCursor,CLCursor}) -> CXSourceLocation

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

getCursorReferenced(c::CXCursor) -> CXCursor
getCursorReferenced(c::CLCursor) -> CLCursor

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

getCursorResultType(c::CXCursor) -> CXType
getCursorResultType(c::Union{CLFunctionDecl,CLCXXMethod}) -> CLType

Return the return type associated with a given cursor. This only returns a valid type if the cursor refers to a function or method.

getCursorResultType(t::CXType) -> CXType
getCursorResultType(t::Union{CLFunctionNoProto,CLFunctionProto}) -> CLType

Return the return type associated with a function type. Wrapper for libclang's clang_getResultType.

getCursorSemanticParent(c::CXCursor) -> CXCursor
getCursorSemanticParent(c::CLCursor) -> CLCursor

Return the semantic parent of the given cursor. Please checkout libclang's doc to know more.

getCursorType(c::CXCursor) -> CXType
getCursorType(c::CLCursor) -> CLType

Return the type of a CXCursor (if any). To get the cursor from a type, see getTypeDeclaration.

getDeclObjCTypeEncoding(C::CXCursor)::CXString
getDeclObjCTypeEncoding(C::CLCursor)::String

Returns the Objective-C type encoding for the specified declaration. Wrapper for libclang's clang_getDeclObjCTypeEncoding.

getDirection(c::Union{CXComment, ParamCommand})

Return the parameter passing direction ([in], [out], [in,out]) or missing if the direction is not specified.

getElementType(t::CXType) -> CXType
getElementType(t::Union{CLVector,CLConstantArray,CLIncompleteArray,CLVariableArray,CLDependentSizedArray,CLComplex}) -> CLType

Return the element type of an array, complex, or vector type. Wrapper for libclang's clang_getElementType.

getEnumDeclIntegerType(c::CLEnumDecl) -> CLType

Retrieve the integer type of an enum declaration.

getFieldDeclBitWidth(c::CLFieldDecl) -> Int

Return the bit width of a bit field declaration as an integer.

getFunctionTypeCallingConv(t::Union{CXType,CLFunctionNoProto,CLFunctionProto}) -> CXCallingConv

Return the calling convention associated with a function type. Wrapper for libclang's clang_getFunctionTypeCallingConv.

getIncludedFile(c::Union{CXCursor,CLCursor}) -> CXFile

Return the file that is included by the given inclusion directive cursor.

getIndex(c::Union{CXComment, ParamCommand})

Return zero-based parameter index in function prototype or missing if the parameter is invalid.

getNamedType(t::CXType) -> CXType
getNamedType(t::CLElaborated) -> CLType

Return the type named by the qualified-id. Wrapper for libclang's clang_Type_getNamedType.

getNullCursor() -> CXCursor

Return the "NULL" CXCursor.

getNumArguments(t::Union{CXType,CLFunctionNoProto,CLFunctionProto}) -> Int

Return the number of non-variadic parameters associated with a function type. Wrapper for libclang's clang_getNumArgTypes.

getNumArguments(c::Union{CXCursor,CLCursor}) -> Int

Return the number of non-variadic arguments associated with a given cursor.

getNumElements(t::Union{CXType,CLVector,CLConstantArray,CLIncompleteArray,CLVariableArray,CLDependentSizedArray}) -> Int

Return the number of elements of an array or vector type. Wrapper for libclang's clang_getNumElements.

getNumObjCProtocolRefs(T::Union{CXType, CLType})::Cuint

Retrieve the number of protocol references associated with an ObjC object/id.

If the type is not an ObjC object, 0 is returned.

getNumObjCTypeArgs(T::Union{CXType, CLType})::Cuint

Retrieve the number of type arguments associated with an ObjC object.

If the type is not an ObjC object, 0 is returned.

getObjCEncoding(T::CXType) -> String
getObjCEncoding(T::CLType) -> String

Returns the Objective-C type encoding for the specified Type. Wrapper for libclang's clang_Type_getObjCEncoding.

getObjCObjectBaseType(T::CXType) -> CXType
getObjCObjectBaseType(T::CLType) -> CLType

Retrieves the base type of the ObjCObjectType. If the type is not an ObjC object, an invalid type is returned. Wrapper for libclang's clang_Type_getObjCObjectBaseType.

getObjCPropertyAttributes(c, reserved)::Cuint

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

Arguments

• reserved: Reserved for future use, pass 0.

getObjCPropertyGetterName(C)::String

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

getObjCPropertySetterName(c)::String

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

getObjCProtocolDecl(T::CXType, i) -> CLCursor
getObjCProtocolDecl(T::CLType, i) -> CXCursor

Retrieve the decl for a protocol reference for an ObjC object/id.

If the type is not an ObjC object or there are not enough protocol references, an invalid cursor is returned.

getObjCTypeArg(T::CXType, i) -> CXType
getObjCTypeArg(T::CLType, i) -> CLType

Retrieve a type argument associated with an ObjC object.

If the type is not an ObjC or the index is not valid, an invalid type is returned.

getOffsetOf(t::CXType, s) -> Int
getOffsetOf(t::CLType, s::AbstractString) -> Int

Return the offset of a field named S in a record of type T in bits as it would be returned by offsetof as per C++11[18.2p4].

It returns a minus number for layout errors, please convert the result to a CXTypeLayoutError to see what the error is.

getOffsetOfField(c::Union{CXCursor,CLCursor}) -> Int

Return the offset of the field represented by the cursor in bits as it would be returned by offsetof as per C++11[18.2p4]. It returns a minus number for layout errors, please convert the result to a CXTypeLayoutError to see what the error is.

getParagraph(c::CXComment)
getParagraph(c::BlockCommand)

Return the paragraph argument of a given command.

getParamName(c::ParamCommand) -> String

Return the name of a parameter.

getParsedComment(c::CXCursor) -> CXComment
getParsedComment(c::CLCursor) -> CLComment

Return the parsed AST of doxygen comment associated with the given node.

getPointeeType(t::CXType) -> CXType
getPointeeType(t::CLType) -> CLType

Return the type of the pointee for pointer types. Wrapper for libclang's clang_getPointeeType.

getRenderKind(c::Union{CXComment, InlineCommand}) -> CXCommentInlineCommandRenderKind

Return the most appropriate rendering mode, chosen on command semantics in Doxygen.

getSizeOf(t::CXType) -> Int
getSizeOf(t::CLType) -> Int

Return the size of a type in bytes as per C++[expr.sizeof] standard,

It returns a minus number for layout errors, please convert the result to a CXTypeLayoutError to see what the error is.

getSourceCode(cursor::Union{CXCursor, CLCursor}) -> String

Get source code for the cursor.

getTagName(c::Union{CXComment, HTMLStartTag, HTMLEndTag})

Return the tag name of a HTML tag.

getText(c::Text) -> String
getText(c::VerbatimBlockLine) -> String
getText(c::VerbatimLine) -> String

Get the text content assiciated with the node.

getTokenExtent(tu::Union{CXTranslationUnit,TranslationUnit}, t::Union{CXToken,CLToken}) -> CXSourceRange

Return a source range that covers the given token.

getTokenLocation(tu::Union{CXTranslationUnit,TranslationUnit}, t::Union{CXToken,CLToken}) -> CXSourceLocation

Return the source location of the given token.

getTranslationUnit(c::Union{CXCursor,CLCursor}) -> CXTranslationUnit

Returns the translation unit that a cursor originated from.

getTranslationUnitCursor(tu::TranslationUnit) -> CLCursor
getTranslationUnitCursor(tu::CXTranslationUnit) -> CXCursor

Return the cursor that represents the given translation unit.

getTypeDeclaration(t::CXType) -> CXCursor
getTypeDeclaration(t::CLType) -> CLCursor

Return the cursor for the declaration of the given type. To get the type of the cursor, see getCursorType. Wrapper for libclang's clang_getTypeDeclaration.

getTypedefDeclUnderlyingType(c::CLTypedefDecl) -> CLType

Return the underlying type of a typedef declaration.

getTypedefName(t::Union{CXType,CLType}) -> String

Return the typedef name of the given type. Wrapper for libclang's clang_getTypedefName.

get_elaborated_cursor(ty::CLType) -> CLCursor
get_elaborated_cursor(ty::CXType) -> CXCursor

Return the cursor of the elaborated type that is referenced by the input type. The input type can be a pointer/array. This function returns clang_getNullCursor if the input type is not refer to an elaborated type.

get_file_line_column(c::Union{CXCursor,CLCursor}) -> (String, Int, Int)

Return file name, line and column number.

get_filename(file::CXFile) -> String

Return the complete file and path name of the given file.

get_filename(c::Union{CXCursor,CLCursor}) -> String

Return the complete file and path name of the given file referenced by the input cursor.

get_function_args(cursor::CLCursor) -> Vector{CLCursor}

Return function arguments for a given cursor.

get_module(tu::TranslationUnit, file::CLFile) -> CLModule

Given a CLFile header file, return the module that contains it, if one exists.

hasAttrs(c::Union{CXCursor,CLCursor}) -> Bool

Determine whether the given cursor has any attributes.

has_elaborated_reference(ty::CLType) -> Bool
has_elaborated_reference(ty::CXType) -> Bool

Return true if the type is an elaborated type or the type indirectly refers to an elaborated type.

has_elaborated_tag_reference(ty::CLType) -> Bool
has_elaborated_tag_reference(ty::CXType) -> Bool

Return true if the type is an elaborated tag type or the type indirectly refers to an elaborated tag type.

has_function_reference(ty::CLType) -> Bool
has_function_reference(ty::CXType) -> Bool

Return true if the type is a function or the type indirectly refers to a function.

isAnonymous(c::Union{CXCursor,CLCursor}) -> Bool

Return true if the given cursor represents an anonymous record declaration(C++).

isAttribute(k::CXcursorKind) -> Bool
isAttribute(c::CLCursor) -> Bool

Return true if the given cursor kind represents an attribute.

isBitField(c::Union{CXCursor,CLCursor}) -> Bool

Return true if the cursor specifies a Record member that is a bitfield.

isConstQualifiedType(t::Union{CXType,CLType}) -> Bool

Determine whether a CXType has the "const" qualifier set, without looking through typedefs that may have added "const" at a different level. Wrapper for libclang's clang_isConstQualifiedType.

isCursorDefinition(c::Union{CXCursor,CLCursor}) -> Bool

Return true if the declaration pointed to by this cursor is also a definition of that entity.

isDeclaration(k::CXcursorKind) -> Bool
isDeclaration(c::CLCursor) -> Bool

Return true if the given cursor kind represents a declaration.

isExpression(k::CXcursorKind) -> Bool
isExpression(c::CLCursor) -> Bool

Return true if the given cursor kind represents an expression.

isFunctionInlined(c::Union{CXCursor,CLCursor}) -> Bool

Determine whether a CXCursor that is a function declaration, is an inline declaration.

isInvalid(k::CXcursorKind) -> Bool
isInvalid(c::CLCursor) -> Bool

Return true if the given cursor kind represents an valid cursor.

isInvalid(t::CXType) -> Bool
isInvalid(t::CLType) -> Bool

Return true if the type is a valid type.

isInvalidDeclaration(x::CXcursorKind) -> Bool

Return true if the given declaration is invalid. A declaration is invalid if it could not be parsed successfully.

isMacroBuiltin(c::Union{CXCursor,CLCursor}) -> Bool

Determine whether a CXCursor that is a macro, is a builtin one.

isMacroFunctionLike(c::Union{CXCursor,CLCursor}) -> Bool

Determine whether a CXCursor that is a macro, is function like.

isNull(c::Union{CXCursor,CLCursor}) -> Bool

Return true if cursor is null.

isPODType(t::Union{CXType,CLType}) -> Bool

Return true if the CXType is a plain old data type. Wrapper for libclang's clang_isPODType.

isPreprocessing(k::CXcursorKind) -> Bool
isPreprocessing(c::CLCursor) -> Bool

Return true if the given cursor kind represents a preprocessing element, such as a preprocessor directive or macro instantiation.

isReference(k::CXcursorKind) -> Bool
isReference(c::CLCursor) -> Bool

Return true if the given cursor kind represents a simple reference. Note that other kinds of cursors (such as expressions) can also refer to other cursors. Use getCursorReferenced to determine whether a particular cursor refers to another entity.

isRestrictQualifiedType(t::Union{CXType,CLType}) -> Bool

Determine whether a CXType has the "restrict" qualifier set, without looking through typedefs that may have added "restrict" at a different level. Wrapper for libclang's clang_isRestrictQualifiedType.

isSelfClosing(c::Union{CXComment, HTMLStartTag})

Return whether a tag is self-closing (for example, <br />).

isStatement(k::CXcursorKind) -> Bool
isStatement(c::CLCursor) -> Bool

Return true if the given cursor kind represents a statement.

isTranslationUnit(k::CXcursorKind) -> Bool
isTranslationUnit(c::CLCursor) -> Bool

Return true if the given cursor kind represents a translation unit.

isUnexposed(k::CXcursorKind) -> Bool

Return true if the given cursor kind represents a currently unexposed piece of the AST (e.g., CXCursor_UnexposedStmt).

isVariadic(c::Union{CXCursor,CLCursor}) -> Bool

Return true if the given cursor is a variadic function or method.

isVariadic(t::Union{CXType,CLType}) -> Bool

Return true if the CXType is a variadic function type. Wrapper for libclang's clang_isFunctionTypeVariadic.

isVirtualBase(c::Union{CXCursor,CLCursor}) -> Bool

Return true if the base class specified by the cursor with kind CX_CXXBaseSpecifier is virtual.

isVolatileQualifiedType(t::Union{CXType,CLType}) -> Bool

Determine whether a CXType has the "volatile" qualifier set, without looking through typedefs that may have added "volatile" at a different level. Wrapper for libclang's clang_isVolatileQualifiedType.

isWhiteSpace(c::Union{CXComment, CLComment}) -> Bool

Return whether a CXParagraph or CXText is contains only white space. Return false for other kinds of comment.

is_forward_declaration(x::CLCursor) -> Bool

Return true if the cursor is a forward declaration. Reference: https://joshpeterson.github.io/identifying-a-forward-declaration-with-libclang

is_inclusion_directive(x::CLCursor) -> Bool

Return true if the cursor is an inclusion directive.

is_system(mod::CLModule)

Given a module, return whether it is a system one.

is_typedef_anon(current::CLCursor, next::CLCursor) -> Bool

Return true if the current cursor is a typedef anonymous struct/enum.

kind(c::CLCursor) -> CXCursorKind

Return the kind of the given cursor. Note this method directly reads CXCursor's kind field, which won't invoke additional clang_getCursorKind function calls.

kind(c::Union{CXComment, CXComment}) -> CXCommentKind

Return the kind of a comment.

kind(c::CXCursor) -> CXCursorKind

Return the kind of the given cursor.

kind(t::CXToken) -> CXTokenKind
kind(t::CLToken) -> CXTokenKind

Return the kind of the given token.

kind(t::CXType) -> CXTypeKind
kind(t::CLType) -> CXTypeKind

Return the kind of the given type.

name(file::CLFile) -> String

Return the complete file and path name of the given file.

name(mod::CLModule)

Given a module, return the name of the module, e.g. for the 'std.vector' sub-module it will return "vector".

name(c::Union{CXCursor,CLCursor}) -> String

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

parent_module(mod::CLModule) -> CLModule

Given a module, return the parent of a sub-module or NULL if the given module is top-level, e.g. for 'std.vector' it will return the 'std' module.

parse_header(
    index::Index,
    header::AbstractString,
    args::Vector{String}=[],
    flags=CXTranslationUnit_None,
) -> TranslationUnit

Return the TranslationUnit for a given header. This is the main entry point for parsing.

Arguments

• header::AbstractString: the header file to parse.
• index::Index: CXIndex pointer (pass to avoid re-allocation).
• args::Vector{String}: compiler switches as string array, eg: ["-x", "c++", "-fno-elide-type"].
• flags: bitwise OR of CXTranslationUnit_Flags.

Consider using parse_header(::Function) to ensure that the TranslationUnit is kept alive while in use.

See also parse_headers.

parse_header(f::Function, ...)

Do-method wrapper around parse_header(::Index) that will ensure that the TranslationUnit object stays alive while f() is running, e.g.:

index = Index()
parse_header(index, "foo.h") do tu
    @show length(children(tu))
end

parse_headers(
    index::Index,
    headers::Vector{String},
    args::Vector{String}=[],
    flags=CXTranslationUnit_None,
) -> Vector{TranslationUnit}

Return a TranslationUnit vector for the given headers.

Consider using parse_headers(::Function) to ensure that the TranslationUnit's are kept alive while in use.

See also parse_header.

parse_headers(f::Function, ...)

Do-method wrapper around parse_headers(::Index) that will ensure that all the TranslationUnit objects stays alive while f() is running, e.g.:

index = Index()
parse_headers(index, ["foo.h", "bar.h"]) do tus
    @show length(tus)
end

Remove FirstXX and LastXX from enumerations.

search(cursors::Vector{CLCursor}, ismatch::Function) -> Vector{CLCursor}

Return vector of CLCursors that match predicate. ismatch is a function that accepts a CLCursor argument.

spelling(kind::CXTypeKind) -> String

Return the spelling of a given CXTypeKind.

spelling(tu::TranslationUnit, t::CLToken) -> String
spelling(tu::TranslationUnit, t::CXToken) -> String
spelling(tu::CXTranslationUnit, t::CXToken) -> String

Return the spelling of the given token. The spelling of a token is the textual representation of that token, e.g., the text of an identifier or keyword.

spelling(tu::TranslationUnit) -> String

Return the original translation unit source file name.

spelling(c::Union{CXCursor,CLCursor}) -> String

Return a name for the entity referenced by this cursor.

spelling(t::Union{CXType,CLType}) -> String

Pretty-print the underlying type using the rules of the language of the translation unit from which it came. If the type is invalid, an empty string is returned. Wrapper for libclang's clang_getTypeSpelling.

tokenize(c::Union{CXCursor,CLCursor}) -> TokenList

Return a TokenList from the given cursor.

toplevel_headers(tu::TranslationUnit, mod::CLModule)

Given a module, return all top level headers associated with the module.

unique_id(file::CLFile) -> CXFileUniqueID

Return the unique id of the given file.

value(c::CLCursor) -> Integer

Return the integer value of an enum constant declaration.

CLCompilationDatabase(path::AbstractString)

Creates a compilation database from the database found in directory path.

CLCompileCommand

Represents a command to compile the specific file. Call getDirection, getArguments and getArguments to get its attributes.

Index(exclude_decls_from_PCH, display_diagnostics)

Provide a shared context for creating translation units.

Arguments

• exclude_decls_from_PCH: whether we only want to see "local" declarations (that did not come from a previous precompiled header). If false, we want to see all declarations.
• display_diagnostics: whether to display diagnostics.

TokenList

Tokenizer accessor.

TranslationUnit(idx, source, args)
TranslationUnit(idx, source, args, unsavedFiles, options)
TranslationUnit(f::Function, ...)

Parse the given source file and the translation unit corresponding to that file. The function argument f for the do-constructor will be passed a single TranslationUnit object that will not be GC'd while f() runs.