Python Wrapper

Annotation of C-code to feed the Python and Matlab wrapper generator

In TiGL we use our own bindings generator to create interfaces to MATLAB and python. As the function declarations in the c-header files can be quite ambigous, we use our own annotation scheme to clarify the meaning of the variables.

Consider following function:

doSomething(char* text)

The role of the variable text is not clear here. It could be an input or an output variable. There are two options, to clarify this:

1. Make it "const char **" to state, that text is an input variable
2. Use the annotation inside a comment section. If text is an input variable place following code before the function declaration:

/*#annotate in: 0#*/

If text is an output variable, use

/*#annotate out: 0#*/

The zero states, that the 0-th variable (we start counting from 0) is an input.

Of course, you can mix the annotations if you have multiple input and outputs.

Consider the function

myFunction(char* intext1, char* intext2, char** outtext3, char** outtext4)

Here, one could use the annotation

# annotate in: 0,1 out: 2M,3 #

The additonal argument M says, that the output string outtext3 is manually allocated before entering the function. If you ommit that, the wrapper assumes that the variable is allocated inside the function.

Lets have a look at a real word example:

TiglReturnCode tiglComponentIntersectionPoints(TiglCPACSConfigurationHandle cpacsHandle,
                                               const char*  componentUidOne,
                                               const char*  componentUidTwo,
                                               int lineID,
                                               const double* etaArray,
                                               int numberOfPoints,
                                               double* pointXArray,
                                               double* pointYArray,
                                               double* pointZArray);

The annotation for this code is

/* #annotate in: 4A(5) out: 6AM(5), 7AM(5), 8AM(5)# */

Here, the first 4 arguments aren't annotated as their roles are unambigous. The variable etaArray is explicitly states as an array by adding "A" after the variable index. The number in brackets denote the size of the array, i.e. the size of the etaArray is defined by the 5-th variable (numberOfPoints). The output arrays pointXArray, pointZArray are also marked as manually allocated arrays - i.e. the arrays are allocated before entering. Again, the size of the arrays is also marked up - all arrays have a size specified by the arguemtn numberOfPoints.

General Syntax

/* # annotate in: index[A][M][(sizeindex)] out: index[A][M][(sizeindex)] # */

• Optional arguments are given in square brackets
• There is no need to annotate all variables, the generator makes some default assumptions
• Meanings of the annotations:
  • A = Array
  • M = Manually allocated
  • (index) = Annotation of an array size. Index is the index of the argument that contains the array size