Automatic extraction of C APIs from header files using libclang
Project description
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>',
}
# 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 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 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>'],
...
],
'variadic': true, # only present if function is variadic
# 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 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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for c_api_extract-0.5.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 375784e3fd73ed418153c46cd9fd05a66eb9b49ba2597f92ad17b8fa8b86560f |
|
MD5 | 8ab7d2dcaa6812b7d214e694c93f4349 |
|
BLAKE2b-256 | 14b00b24f818e52e2652f62234c16e53fafae76eb656961bd5f9c2fbde41bd1f |