c_api_extract.py
Automatic extraction of C APIs from header files using Python and clang. Exports struct, union, enum, typedefs, static variables and function definitions to a JSON file content.
Installing
c_api_extract is available on PyPI and may be installed using pip
:
$ pip install c-api-extract
Usage
Using the command line interface:
$ c_api_extract <input> [-i <include_pattern>...] [options] [-- <clang_args>...]
Check out the available options with:
$ c_api_extract -h
Or using Python:
import c_api_extract
# `definitions` follow the same format as output JSON
definitions = c_api_extract.definitions_from_header('header_name.h', ['-Dsome_clang_args', ...])
c_api_extract.py works on a single header file for simplicity.
If you need more than one header processed, create a new one and #include
them.
Output format
Output is a list of definitions, each kind with its format:
# variable definitions
{
'kind': 'var',
'name': '<name>', # variable name
'type': <type spelling or object>, # variable type
# only present if you pass `--source` to c_api_extract
'source': '<verbatim definition source code>',
}
# constant macro definitions
{
'kind': 'const',
'name': '<name>',
'type': <type spelling or object>, # constant type, is always const
}
# enum definitions
{
'kind': 'enum',
'name': '<name>', # enum name, generated for anonymous enums
'type': <type spelling or object>, # enum underlying type, usually "unsigned int"
'values': [ # list of declared names and values
['<name>', <integer value>]
# ...
],
# only present if enum is anonymous
'anonymous': true,
# only present if you pass `--source` to c_api_extract
'source': '<verbatim definition source code>',
}
# struct|union definitions
{
'kind': 'struct' | 'union',
'name': '<name>', # struct|union name, generated for anonymous struct|unions
'spelling': '<spelling>', # Spelling that be used directly in C to refer to type
'fields': [ # list of declared fields, empty for opaque struct|unions
[<type spelling or object>, '<name>'], # name may be "" for nested anonymous structs|unions
...
],
# only present if record is anonymous
'anonymous': true,
# only present if you pass `--source` to c_api_extract
'source': '<verbatim definition source code>',
}
# typedef definitions
{
'kind': 'typedef',
'name': '<name>', # name of the typedef
'type': <type spelling or object>, # underlying type
# only present if you pass `--source` to c_api_extract
'source': '<verbatim definition source code>',
}
# function definitions
{
'kind': 'function',
'name': '<name>', # name of the function
'return_type': <type spelling or object>, # return type
'arguments': [ # list of arguments
[<type spelling or object>, '<name>'],
...
],
# only present if function is variadic
'variadic': true,
# only present if you pass `--source` to c_api_extract
'source': '<verbatim definition source code>',
}
#########################################################
# By default, types are literal strings with the type spelling as provided by clang.
# If you pass `--type-objects`, a JSON/Dict object is used instead with more detailed
# information. Its format is described below:
{
'base': '<unqualified base type spelling>',
# only present if type is a pointer type
'pointer': ['*', ...],
# only present if type is an array type
'array': [<integer size>, '<"*" if incomplete array or pointer type>', ...],
# only present if type is a function pointer type
'function': {<type object>},
# only present if type is a function type
'return_type': {<type object>},
# only present if type is a function type
# notice that function types don't carry argument names
'arguments': [{<type object>}, ...],
# only present if type is a function type and function is variadic
'variadic': true,
# only present if type is a record or enum and record or enum is anonymous
'anonymous': true,
# only present if base type is const qualified
'const': true,
# only present if base type is volatile qualified
'volatile': true,
# only present if base type is restrict qualified
'restrict': true,
# only present if you pass `--size` to c_api_extract
'size': <integer sizeof, may be negative for "void" and incomplete arrays>,
}
TODO
- Add support for constants defined using
#define
- Add docstrings