Use clang-ast-dump as a replacement of show-clang-ast

[TravisCardwell]

A show-clang-ast command was implemented in the hs-bindgen executable. It displayed information from the Element representations of the Clang AST.

Example Usage

$ cabal run hs-bindgen -- show-clang-ast -i hs-bindgen/examples/comments.h
Element {elementName = UserProvided "S4", elementLocation = "<hs-bindgen/examples/comments.h:4:1-18:2>", elementKind = "StructDecl", elementTypeKind = "Record", elementRawComment = "/**\n * A struct with a Doxygen comment\n */", elementIsAnonymous = False, elementIsDefinition = True}
|
+- Element {elementName = UserProvided "a", elementLocation = "<hs-bindgen/examples/comments.h:8:5-8:11>", elementKind = "FieldDecl", elementTypeKind = "Char_S", elementRawComment = "/**\n     * A field preceded by a Doxygen comment\n     */", elementIsAnonymous = False, elementIsDefinition = True}
|
+- Element {elementName = UserProvided "b", elementLocation = "<hs-bindgen/examples/comments.h:10:5-10:10>", elementKind = "FieldDecl", elementTypeKind = "Int", elementRawComment = "/**< A field followed by a Doxygen comment */", elementIsAnonymous = False, elementIsDefinition = True}
|
`- Element {elementName = UserProvided "c", elementLocation = "<hs-bindgen/examples/comments.h:17:5-17:12>", elementKind = "FieldDecl", elementTypeKind = "Float", elementRawComment = "/**\n     * A field that refers to another field\n     *\n     * See also @ref S4::a\n     */", elementIsAnonymous = False, elementIsDefinition = True}

A separate clang-ast-dump utility aims to aid with development. It traverses the Clang AST directly, displaying results from Clang function calls. The goal is to provide low-level information about the AST, which helps implementing the translation between Clang types and our Haskell types.

It looks like show-clang-ast has already been removed. The clang-ast-dump utility was initially developed to understand the Clang documentation AST (#26), currently in the doxygen branch. It should be useful as we continue to develop support for more C features, however, so we should go ahead and make it the official replacement of show-clang-ast.

Note that the Clang ast-dump command is also useful, but it is not as detailed.

Example Usage

$ clang -Xclang -ast-dump hs-bindgen/examples/comments.h
TranslationUnitDecl 0x5603cb1de988 <<invalid sloc>> <invalid sloc>
|-TypedefDecl 0x5603cb1df1b8 <<invalid sloc>> <invalid sloc> implicit __int128_t '__int128'
| `-BuiltinType 0x5603cb1def50 '__int128'
|-TypedefDecl 0x5603cb1df228 <<invalid sloc>> <invalid sloc> implicit __uint128_t 'unsigned __int128'
| `-BuiltinType 0x5603cb1def70 'unsigned __int128'
|-TypedefDecl 0x5603cb1df530 <<invalid sloc>> <invalid sloc> implicit __NSConstantString 'struct __NSConstantString_tag'
| `-RecordType 0x5603cb1df300 'struct __NSConstantString_tag'
|   `-Record 0x5603cb1df280 '__NSConstantString_tag'
|-TypedefDecl 0x5603cb1df5d8 <<invalid sloc>> <invalid sloc> implicit __builtin_ms_va_list 'char *'
| `-PointerType 0x5603cb1df590 'char *'
|   `-BuiltinType 0x5603cb1dea30 'char'
|-TypedefDecl 0x5603cb1df8d0 <<invalid sloc>> <invalid sloc> implicit __builtin_va_list 'struct __va_list_tag[1]'
| `-ConstantArrayType 0x5603cb1df870 'struct __va_list_tag[1]' 1
|   `-RecordType 0x5603cb1df6b0 'struct __va_list_tag'
|     `-Record 0x5603cb1df630 '__va_list_tag'
`-RecordDecl 0x5603cb23ec00 <hs-bindgen/examples/comments.h:4:1, line:18:1> line:4:8 struct S4 definition
  |-FullComment 0x5603cb23eef0 <line:2:3, col:34>
  | `-ParagraphComment 0x5603cb23eec0 <col:3, col:34>
  |   `-TextComment 0x5603cb23ee90 <col:3, col:34> Text=" A struct with a Doxygen comment"
  |-FieldDecl 0x5603cb23ecd8 <line:8:5, col:10> col:10 a 'char'
  | `-FullComment 0x5603cb23efc0 <line:6:7, col:44>
  |   `-ParagraphComment 0x5603cb23ef90 <col:7, col:44>
  |     `-TextComment 0x5603cb23ef60 <col:7, col:44> Text=" A field preceded by a Doxygen comment"
  |-FieldDecl 0x5603cb23ed40 <line:10:5, col:9> col:9 b 'int'
  | `-FullComment 0x5603cb23f090 <col:16, col:54>
  |   `-ParagraphComment 0x5603cb23f060 <col:16, col:54>
  |     `-TextComment 0x5603cb23f030 <col:16, col:54> Text=" A field followed by a Doxygen comment "
  `-FieldDecl 0x5603cb23ee00 <line:17:5, col:11> col:11 c 'float'
    `-FullComment 0x5603cb23f220 <line:13:7, line:16:5>
      |-ParagraphComment 0x5603cb23f130 <line:13:7, col:43>
      | `-TextComment 0x5603cb23f100 <col:7, col:43> Text=" A field that refers to another field"
      `-ParagraphComment 0x5603cb23f1f0 <line:15:7, line:16:5>
        |-TextComment 0x5603cb23f150 <line:15:7, col:16> Text=" See also "
        |-InlineCommandComment 0x5603cb23f190 <col:17, col:20> Name="ref" RenderNormal Arg[0]="S4::a"
        `-TextComment 0x5603cb23f1b0 <line:16:1, col:5> Text="     "

[TravisCardwell]

Currently, clang-ast-dump is implemented in a separate package (with the same name).

Should we add it to hs-bindgen or keep it as a separate package?

[edsko]

Let's make it an executable in hs-bindgen-libclang.