Metadata-Version: 1.2
Name: c-api-extract
Version: 0.5.0
Summary: Automatic extraction of C APIs from header files using libclang
Home-page: https://github.com/gilzoide/c_api_extract-py
Author: gilzoide
Author-email: gilzoide@gmail.com
License: Unlicense
Project-URL: Source, https://github.com/gilzoide/c_api_extract-py
Project-URL: Tracker, https://github.com/gilzoide/c_api_extract-py/issues
Description: 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.
        
        .. _Python: http://python.org/
        .. _clang: https://pypi.org/project/clang/
        
        
        Installing
        ----------
        **c_api_extract** is available on PyPI_ and may be installed using ``pip``::
        
          $ pip install c-api-extract
        
        .. _PyPI: https://pypi.org/project/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:
        
        .. code:: 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:
        
        .. code:: python
        
          # variable definitions
          {
            'kind': 'var',
            'name': '<name>',         # variable name
            'type': {<type object>},  # type object
            # 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 object>},  # enum underlying type, normally `{"base": "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 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 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 object>},  # return type
            'arguments': [                   # list of arguments
              [{<type 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>',
          }
        
          #########################################################
          # All type objects use the following structure:
          {
            '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
        
Keywords: c header clang
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Public Domain
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Compilers
