Complete bindings to the entire llvm3.4 libclang API about libclang

[sethfowler]

I've used a quick script to generate a list of functions that are exported by Index.h but aren't imported by the generated FFI.hs. This is a superset of the bindings we need to complete; a lot of these already have bindings but they're just handled specially in some way.

• clang_BlockCommandComment_getArgText
• clang_BlockCommandComment_getCommandName
• clang_BlockCommandComment_getNumArgs
• clang_BlockCommandComment_getParagraph
• clang_CXIndex_getGlobalOptions
• clang_Comment_getChild
• clang_Comment_getKind
• clang_Comment_getNumChildren
• clang_Comment_isWhitespace
• clang_Cursor_getArgument
• clang_Cursor_getBaseExpression
• clang_Cursor_getBriefCommentText
• clang_Cursor_getCommentRange
• clang_Cursor_getModule
• clang_Cursor_getNumArguments
• clang_Cursor_getObjCDeclQualifiers
• clang_Cursor_getObjCPropertyAttributes
• clang_Cursor_getObjCSelectorIndex
• clang_Cursor_getParsedComment
• clang_Cursor_getRawCommentText
• clang_Cursor_getReceiverType
• clang_Cursor_getSpellingNameRange
• clang_Cursor_getTranslationUnit
• clang_Cursor_isBitField
• clang_Cursor_isDynamicCall
• clang_Cursor_isNull
• clang_Cursor_isObjCOptional
• clang_Cursor_isVariadic
• clang_FullComment_getAsHTML
• clang_FullComment_getAsXML
• clang_HTMLStartTagComment_isSelfClosing
• clang_HTMLStartTag_getAttrName
• clang_HTMLStartTag_getAttrValue
• clang_HTMLStartTag_getNumAttrs
• clang_HTMLTagComment_getAsString
• clang_HTMLTagComment_getTagName
• clang_InlineCommandComment_getArgText
• clang_InlineCommandComment_getCommandName
• clang_InlineCommandComment_getNumArgs
• clang_InlineCommandComment_getRenderKind
• clang_InlineContentComment_hasTrailingNewline
• clang_Location_isFromMainFile
• clang_Location_isInSystemHeader
• clang_Module_getASTFile
• clang_Module_getFullName
• clang_Module_getName
• clang_Module_getNumTopLevelHeaders
• clang_Module_getParent
• clang_Module_getTopLevelHeader
• clang_ParamCommandComment_getDirection
• clang_ParamCommandComment_getParamIndex
• clang_ParamCommandComment_getParamName
• clang_ParamCommandComment_isDirectionExplicit
• clang_ParamCommandComment_isParamIndexValid
• clang_Range_isNull
• clang_TParamCommandComment_getDepth
• clang_TParamCommandComment_getIndex
• clang_TParamCommandComment_getParamName
• clang_TParamCommandComment_isParamPositionValid
• clang_TextComment_getText
• clang_Type_getAlignOf
• clang_Type_getCXXRefQualifier
• clang_Type_getClassType
• clang_Type_getOffsetOf
• clang_Type_getSizeOf
• clang_VerbatimBlockLineComment_getText
• clang_VerbatimLineComment_getText
• clang_codeCompleteGetContainerKind
• clang_codeCompleteGetContainerUSR
• clang_codeCompleteGetContexts
• clang_codeCompleteGetObjCSelector
• clang_constructUSR_ObjCIvar
• clang_constructUSR_ObjCMethod
• clang_constructUSR_ObjCProperty
• clang_createTranslationUnitFromSourceFile
• clang_disposeCXPlatformAvailability
• clang_disposeCXTUResourceUsage
• clang_disposeDiagnosticSet
• clang_disposeOverriddenCursors
• clang_equalCursors
• clang_equalRanges
• clang_executeOnThread
• clang_getArrayElementType
• clang_getArraySize
• clang_getCXTUResourceUsage
• clang_getChildDiagnostics
• clang_getCompletionAnnotation
• clang_getCompletionBriefComment
• clang_getCompletionNumAnnotations
• clang_getCompletionParent
• clang_getCursorCompletionString
• clang_getCursorKind
• clang_getCursorPlatformAvailability
• clang_getCursorReferenceNameRange
• clang_getDefinitionSpellingAndExtent
• clang_getDiagnosticCategoryName
• clang_getDiagnosticInSet
• clang_getDiagnosticSetFromTU
• clang_getElementType
• clang_getFieldDeclBitWidth
• clang_getFileLocation
• clang_getFileUniqueID
• clang_getFunctionTypeCallingConv
• clang_getNullCursor
• clang_getNumDiagnosticsInSet
• clang_getNumElements
• clang_getPresumedLocation
• clang_getRemappings
• clang_getRemappingsFromFileList
• clang_getTUResourceUsageName
• clang_isAttribute
• clang_isDeclaration
• clang_isExpression
• clang_isFileMultipleIncludeGuarded
• clang_isInvalid
• clang_isPreprocessing
• clang_isReference
• clang_isStatement
• clang_isTranslationUnit
• clang_isUnexposed
• clang_loadDiagnostics
• clang_parseTranslationUnit
• clang_remap_dispose
• clang_remap_getFilenames
• clang_remap_getNumFiles
• clang_toggleCrashRecovery
• clang_visitChildren
• clang_visitChildrenWithBlock

[sethfowler]

Nice, with the comment-functions branch pushed we are at about the halfway mark.

[sethfowler]

I checked off clang_executeOnThread without creating a binding for it. This seems purely intended for internal debugging uses by the libclang developers.

[sethfowler]

Right now I have difficulty envisioning much benefit coming from clang_getCXTUResourceUsage and friends. It's not clear to me that this information is actionable. I'll happily add bindings for this if someone needs it, but for now I've decided to check this off, along with clang_getTUResourceUsageName and clang_disposeCXTUResourceUsage.

[sethfowler]

I pulled out the bindings that involve visitors (and thus require some new cbits code) into a separate list here:

• clang_IndexAction_create
• clang_IndexAction_dispose
• clang_findIncludesInFile
• clang_findIncludesInFileWithBlock
• clang_findReferencesInFile
• clang_findReferencesInFileWithBlock
• clang_indexLoc_getCXSourceLocation
• clang_indexLoc_getFileLocation
• clang_indexSourceFile
• clang_indexTranslationUnit
• clang_index_getCXXClassDeclInfo
• clang_index_getClientContainer
• clang_index_getClientEntity
• clang_index_getIBOutletCollectionAttrInfo
• clang_index_getObjCCategoryDeclInfo
• clang_index_getObjCContainerDeclInfo
• clang_index_getObjCInterfaceDeclInfo
• clang_index_getObjCPropertyDeclInfo
• clang_index_getObjCProtocolRefListInfo
• clang_index_isEntityObjCContainerKind
• clang_index_setClientContainer
• clang_index_setClientEntity

These require a bit more work and thought than the other bindings, so I'll tackle them last.

[sethfowler]

Wow, I hoped to get more done this morning, but the binding for clang_getCursorPlatformAvailability was more difficult than some entire modules! Talk about an FFI-unfriendly function.

[sethfowler]

clang_getDefinitionSpellingAndExtent is a debugging function that doesn't actually add any functionality. I've decided not to add a binding for it.

[sethfowler]

Alright. As of dbd7476, the entire first list has bindings. We're now missing only the new visitor functions.

[ghorn]

👍

[sethfowler]

So I just read the documentation for the libclang "high level API", which consists of the clang_index_* functions that don't have bindings yet. Relevant docs are here and here.

I'm not convinced that bindings to this API are useful for this library. This API doesn't appear to add any new functionality, and it relies very, very heavily on callbacks, which means the performance of a naive binding will be poor.

We could use the same approach that we use for getChildren and getDescendants and collect all of the results, then return them to Haskell in a single list. This would boil down to adding getDeclarations, getReferences, and possibly getDeclarationsAndReferences (to avoid the double traversal you'd need otherwise). We should just have these return a list of cursors, and allow users to extract whatever information they need from those cursors. I don't think we should even implement these under the hood using the "high level API", because it's inherently an inefficient API.

[sethfowler]

OK, I executed the plan in my previous comment. I'm now going to call this issue closed.