C Interface Generator

Generation of C language header files defining the interface to a library is performed using python and an XML schema. The XML schema describes the interface to be generated by the python script.

Schema

The schema is designed to follow as closely as possible the C language syntax which it is generating.

The schema is defined as an XML document which takes the form.

<?xml version="1.0"?>
<interface>
    <!-- xml elements describing the API interface -->
</interface>

Ordering of tags within the <interface></interface> tags are preserved.

Include Directive

To insert an include directive into the header use the include tag. By default the angle bracket form is generated although this can also be specified explicitly; this is done using the form attribute which can be set to either angle outputting the angle bracket form or quote producing the quotation mark form.

<include>stddef.h</include>
<include form="angle">stdint.h</include>
<include form="quote">myheader.h</include>

Will result in the following include directive being generated.

#include <stddef.h>
#include <stdint.h>
#include "myheader.h"

Macro Definitions

Insertion of macro definition is done using the define tag which comes in three forms. For the first form only the macro name is required, use the value tag to if a value is required; function like macros can be created using the param tag with a name.

<define>HAVE_FEATURE</define>
<define>PI<value>3.14</value></define>
<define>UNUSED<param>VARIABLE</param><value>(void)VARIABLE;</value></define>
<define>ASSERT<param>CONDITION</param><param>MESSAGE</param>
  <value>if (CONDITION) {
fprintf(stderr, MESSAGE);
abort();
}</value></define>

Will generate the following macro definitions.

#define TAG
#define PI 3.14
#define UNUSED(VARIABLE) (void)VARIABLE;
#define ASSERT(CONDITION, MESSAGE) \
  if (CONDITION) { \
    fprintf(stderr, MESSAGE); \
    abort(); \
  }

Note that new lines in multi line value tags will be escaped automatically.

Structures

Introducing structures is done using the struct tag which can be used to describe forward declarations, empty structures, and structures with member objects. Providing only the structure name as the text to the struct tag will result in a forward declaration; an empty body tag results in an empty structure, finally using the body tag with a number of nested member tags containing optional name text and a mandatory type tag produces a structure with member objects.

<struct>forward_t</struct>
<struct>empty_t<member></member></struct>
<struct>position_t<body>
  <member>x<type>float</type></member>
  <member>y<type>float</type></member>
</body></struct>

This outputs the following set of structure output.

struct forward_decl_t;
struct empty_t {};
struct position_t {
  float x;
  float y;
};

Enumerations

Generation of enumerations is done using the enum tag, this is functionally equivalent to a structure with nested member objects. An

<enum>positions<body>
    <constant>CENTER</constant>
    <constant>LEFT<value>-1</value></constant>
    <constant>RIGHT<value>1</value></constant>
</body></enum>
<enum><body>
    <constant>SUCCESS</constant>
    <constant>FAILURE</constant>
</body></enum>

Will generate the following C code.

enum positions {
  CENTER,
  LEFT = -1,
  RIGHT = 1
};
enum {
  SUCCESS,
  FAILURE
};

Functions

<function>nop<return>void</return></function>
<function>foo<return>uint32_t</return>
  <param>count<type>uint32_t</type></param>
</function>
<function>main<return>int</return>
  <param>argc<type>int</type></param>
  <param>argv<type>char **</type></param>
</function>

void nop();
uint32_t foo(uint32_t count);
int main(int argc, char ** argv);

Licence - MIT

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

kbenzie / api-generator