Introduction

Extract QT and KDE interface information from cpp headers

History

SMOKE in KDE has been proved to be a very useful tool, which generates grogrammatic level interface dictionary for making binding. While from the personal point of view, I still prefer more readability regarding output. One can also patch the result somehow in each phase to introduce new features for following process.

Goal

mainly for making QT/KDE language bindings. Myself is a Perl fan, so it is designed to make perl bindings. While it can also be used for other purpose as you like.

API sync up between perl and C/C++ is a hard topic. Most of the binding projects on CPAN have to perform manual update on underlying C/C++ API change. While for very large library like Qt, the maintenance cost is too high. Thus I am trying to have an automated way to archive this. There are similar toolkit to address the topic, one great well-known is swig.

Purpose here is more in-scope and specific. Only for Qt4.

Parse, Parse, Parse

This module is an example use of the most famous parse tool Parse::RecDescent. A big engine works in Conway's way ;-) which is also regarded as standard rule-based regex engine prototype in Perl6.

I am trying to make it be a GOOD example ;-)

This is the resource page of Parse::RecDescent. There I learned nearly all I've known about that module. You should have some basic knowledge on generic parse ( type 3, LR, regular, descent etc.).

The grammar I developed in this module is a little different from standard C++ parser in gcc. As a top-down style, it will not, say, 'down' so deeply ;-) since we are not compiling something. What required here is just necessary interface information.

Output, Production, YAML

QT4_Sample_01

QT4_Sample_02

KDE3_Sample_01

KDE3_Sample_02

As seen, the production of parser is programmatic. I choose YAML as the output format in order to gain another half cup of readability. One might notice the production qualities of different parse rules are different. Some is detailed enough and others are still draft. For instance, the function name could be furtherly splitted into return type, name and parameters. The idea here is 'DO ONE THING AND DO IT WELL'. I'd also like to keep the stability of parse output spec. One can post-process the production of parser into more purpose-specific level.

Example Use

See my PerlQT4 binding page

Pitfall

This parser is specially designed for QT4/KDE C++ headers.

As known, parsing is a dark magic ;-|

Output Spec

Roughly speaking, a YAML-ish IDL.

NOTE: DEPRECATED !!! See online docu instead.

# NOTE: field such as name/variable might be optional

# a QT/KDE-specific macro/property
---
   - type    : macro
   - subtype : 1/2/3
               [ subtype 1 has no parameter, subtype 2 has just one, subtype 3 has > 1. ]
   - name    : [ macro/property name ]
   - value   : [ the parameter(s) of macro which is of subtype 2/3 ]

# a typedef line
---
   - type     : typedef
   - value    : [ content of typedef, could be of enum/class/struct/union/simple type. ]
                [ will be a complete hashref entry in case of enum/class/struct/union, 
                  refer to spec of those types below.                                  ]

# a standard C++ one-line comment
# multiline style comment (/* */) is stripped by C++ preprocessor
---
   - type : comment
   - value: [ content of comment line without '#' ]

# an enum entry
---
   - type     : enum
   - name     : [ enum name                                               ]
                [ possibly with prefix such as macro or other C++ keyword ]
   - value    : [ arrayref of the enum value list ]
   - variable : [ declared variables ] 

# a template class/struct/enum/function declaration
---
   - type     : template
   - body     : [ template body                                  ]
                [ an arrayref of all possible code blocks inside ]
   - typename : [ template type/class declaration ]

# an extern reference declaration
# C/function/expression/class/struct/union/enum 
---
   - type    : extern
   - subtype : C/class/struct/union/enum/function/expression
   - body    : [ an arrayref of all code blocks inside ]

# an namespace declaration
---
   - type : namespace
   - name : [ namespace name ] 
   - body : [ an arrayref of all code blocks inside ] 

# a complete class/struct/union declaration
# they are treated as a similar way
---
   - type     : class/struct/union
   - name     : [ class/struct/union name                                 ] 
                [ possibly with prefix such as macro or other C++ keyword ]
   - body     : [ class/struct/union body unless a forward declaration                ]
                [ an arrayref of all code blocks inside                               ]
                [ class visibility and QT signal/slot keywords are standalone entries ]
   - property : [ an arrayref of properties (friend etc.) ]
   - inheritance : [ class inheritance declaration ] 
   - variable    : [ declared variables ] 

# a class accessibility entry
# this includes both class visibility keywords (public/private/protected) 
# and QT-specific signal/slot keywords (Q_SIGNALS/Q_SLOTS)
# future might have KDE-specific ones
# here takes another type name to differentiate with visibility
---
   - type : accessibility
   - value: [ accessibility keyword name ]

# a complete function declaration
---
   - type     : function
   - name     : [ function name                                           ]
                [ possibly with prefix such as macro or other C++ keyword ]
   - property : [ c++/QT/KDE-specific keywords (const and like)           ] 
   - parameter: 
       - name    : [ parameter name with type               ]
                   [ could be a hashref of another 
                     { name => '', parameter => [] } entry 
                     for recursive function pointer such as 
                     int ((*signal)(int))(int)              ]
         type    : simple/fpointer/template
         default : [default value declared                  ]
       ...

# a code expression entry
---
   - type : expression
   - value: [ expression body ]

Bugs

version

bug

0.01	bin/format_qtedi_production has serious bug on formatting complex function parameter such as raw function pointer, array, default string value which contains comma, constructor default value, or template class reference

Reference Link

• CPAN page