Skip to main content

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>',
}

# 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

c_api_extract-0.7.0.tar.gz (8.0 kB view hashes)

Uploaded source

Built Distribution

c_api_extract-0.7.0-py3-none-any.whl (7.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page