Metadata-Version: 2.4
Name: cxxheaderparser
Version: 1.6.0
Summary: Parse C++ header files and generate a data structure representing the class
Home-page: https://github.com/robotpy/cxxheaderparser
Author: Dustin Spicuzza
Author-email: dustin@virtualroadside.com
Maintainer: RobotPy Development Team
Maintainer-email: robotpy@googlegroups.com
License: BSD
Keywords: c++ header parser ply
Platform: Platform Independent
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: License :: OSI Approved :: BSD License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >= 3.6
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: dataclasses; python_version < "3.7"
Provides-Extra: pcpp
Requires-Dist: pcpp~=1.30; extra == "pcpp"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: platform
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

cxxheaderparser
===============

A pure python C++ header parser that parses C++ headers in a mildly naive
manner that allows it to handle many C++ constructs, including many modern
(C++11 and beyond) features.

This is a complete rewrite of the `CppHeaderParser` library. `CppHeaderParser`
is really useful for some tasks, but it's implementation is a truly terrible
ugly hack built on top of other terrible hacks. This rewrite tries to learn
from `CppHeaderParser` and leave its ugly baggage behind.

Goals:

* Parse syntatically valid C++ and provide a useful (and documented!) pure
  python API to work with the parsed data
* Process incomplete headers (doesn't need to process includes)
* Provide enough information for binding generators to wrap C++ code
* Handle common C++ features, but it may struggle with obscure or overly
  complex things (feel free to make a PR to fix it!)

Non-goals:

* **Does not produce a full AST**, use Clang if you need that
* **Not intended to validate C++**, which means this will not reject all
  invalid C++ headers! Use a compiler if you need that
* **Parser requires a C++ preprocessor**. If you are parsing
  headers that contain macros, you should preprocess your code using the
  excellent pure python preprocessor [pcpp](https://github.com/ned14/pcpp)
  or your favorite compiler
  * We have implemented support for PCPP, GCC, and MSVC -- but it is not enabled
    by default. See the `cxxheaderparser.preprocessor` module for how to enable it.
* Probably won't be able to parse most IOCCC entries

There are two APIs available:

* A visitor-style interface to build up your own custom data structures 
* A simple visitor that stores everything in a giant data structure

Live Demo
---------

A pyodide-powered interactive demo is at https://robotpy.github.io/cxxheaderparser/

Documentation
-------------

Documentation can be found at https://cxxheaderparser.readthedocs.io

Install
-------

Requires Python 3.6+, no non-stdlib dependencies if using Python 3.7+.

```
pip install cxxheaderparser
```

Usage
-----

To see a dump of the data parsed from a header:

```
# pprint format
python -m cxxheaderparser myheader.h

# JSON format
python -m cxxheaderparser --mode=json myheader.h

# dataclasses repr format
python -m cxxheaderparser --mode=repr myheader.h

# dataclasses repr format (formatted with black)
python -m cxxheaderparser --mode=brepr myheader.h
```

See the documentation for anything more complex.

Bugs
----

This should handle even complex C++ code with few problems, but there are
almost certainly weird edge cases that it doesn't handle. Additionally,
not all C++17/20 constructs are supported yet (but contributions welcome!).

If you find an bug, we encourage you to submit a pull request! New
changes will only be accepted if there are tests to cover the change you
made (and if they don’t break existing tests).

Author
------

cxxheaderparser was created by Dustin Spicuzza

Credit
------

* Partially derived from and inspired by the `CppHeaderParser` project
  originally developed by Jashua Cloutier
* An embedded version of PLY is used for lexing tokens
* Portions of the lexer grammar and other ideas were derived from pycparser
* The source code is liberally sprinkled with comments containing C++ parsing
  grammar mostly derived from the [Hyperlinked C++ BNF Grammar](https://www.nongnu.org/hcb/)
* cppreference.com has been invaluable for understanding many of the weird
  quirks of C++, and some of the unit tests use examples from there
* [Compiler Explorer](godbolt.org) has been invaluable for validating my 
  understanding of C++ by allowing me to quickly type in quirky C++
  constructs to see if they actually compile

License
-------

BSD License
