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
* **No C preprocessor substitution support implemented**. 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
* See `cxxheaderparser.preprocessor` for how to use
* 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
Raw data
{
"_id": null,
"home_page": "https://github.com/robotpy/cxxheaderparser",
"name": "cxxheaderparser",
"maintainer": "RobotPy Development Team",
"docs_url": null,
"requires_python": ">= 3.6",
"maintainer_email": "robotpy@googlegroups.com",
"keywords": "c++ header parser ply",
"author": "Dustin Spicuzza",
"author_email": "dustin@virtualroadside.com",
"download_url": "https://files.pythonhosted.org/packages/ca/ca/a3e7d3ae24ee8870decfd469242d612943626977d7a852648a7a53f6bc38/cxxheaderparser-1.3.1.tar.gz",
"platform": "Platform Independent",
"description": "cxxheaderparser\n===============\n\nA pure python C++ header parser that parses C++ headers in a mildly naive\nmanner that allows it to handle many C++ constructs, including many modern\n(C++11 and beyond) features.\n\nThis is a complete rewrite of the `CppHeaderParser` library. `CppHeaderParser`\nis really useful for some tasks, but it's implementation is a truly terrible\nugly hack built on top of other terrible hacks. This rewrite tries to learn\nfrom `CppHeaderParser` and leave its ugly baggage behind.\n\nGoals:\n\n* Parse syntatically valid C++ and provide a useful (and documented!) pure\n python API to work with the parsed data\n* Process incomplete headers (doesn't need to process includes)\n* Provide enough information for binding generators to wrap C++ code\n* Handle common C++ features, but it may struggle with obscure or overly\n complex things (feel free to make a PR to fix it!)\n\nNon-goals:\n\n* **Does not produce a full AST**, use Clang if you need that\n* **Not intended to validate C++**, which means this will not reject all\n invalid C++ headers! Use a compiler if you need that\n* **No C preprocessor substitution support implemented**. If you are parsing\n headers that contain macros, you should preprocess your code using the\n excellent pure python preprocessor [pcpp](https://github.com/ned14/pcpp)\n or your favorite compiler\n * See `cxxheaderparser.preprocessor` for how to use\n* Probably won't be able to parse most IOCCC entries\n\nThere are two APIs available:\n\n* A visitor-style interface to build up your own custom data structures \n* A simple visitor that stores everything in a giant data structure\n\nLive Demo\n---------\n\nA pyodide-powered interactive demo is at https://robotpy.github.io/cxxheaderparser/\n\nDocumentation\n-------------\n\nDocumentation can be found at https://cxxheaderparser.readthedocs.io\n\nInstall\n-------\n\nRequires Python 3.6+, no non-stdlib dependencies if using Python 3.7+.\n\n```\npip install cxxheaderparser\n```\n\nUsage\n-----\n\nTo see a dump of the data parsed from a header:\n\n```\n# pprint format\npython -m cxxheaderparser myheader.h\n\n# JSON format\npython -m cxxheaderparser --mode=json myheader.h\n\n# dataclasses repr format\npython -m cxxheaderparser --mode=repr myheader.h\n\n# dataclasses repr format (formatted with black)\npython -m cxxheaderparser --mode=brepr myheader.h\n```\n\nSee the documentation for anything more complex.\n\nBugs\n----\n\nThis should handle even complex C++ code with few problems, but there are\nalmost certainly weird edge cases that it doesn't handle. Additionally,\nnot all C++17/20 constructs are supported yet (but contributions welcome!).\n\nIf you find an bug, we encourage you to submit a pull request! New\nchanges will only be accepted if there are tests to cover the change you\nmade (and if they don\u2019t break existing tests).\n\nAuthor\n------\n\ncxxheaderparser was created by Dustin Spicuzza\n\nCredit\n------\n\n* Partially derived from and inspired by the `CppHeaderParser` project\n originally developed by Jashua Cloutier\n* An embedded version of PLY is used for lexing tokens\n* Portions of the lexer grammar and other ideas were derived from pycparser\n* The source code is liberally sprinkled with comments containing C++ parsing\n grammar mostly derived from the [Hyperlinked C++ BNF Grammar](https://www.nongnu.org/hcb/)\n* cppreference.com has been invaluable for understanding many of the weird\n quirks of C++, and some of the unit tests use examples from there\n* [Compiler Explorer](godbolt.org) has been invaluable for validating my \n understanding of C++ by allowing me to quickly type in quirky C++\n constructs to see if they actually compile\n\nLicense\n-------\n\nBSD License\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Parse C++ header files and generate a data structure representing the class",
"version": "1.3.1",
"project_urls": {
"Homepage": "https://github.com/robotpy/cxxheaderparser"
},
"split_keywords": [
"c++",
"header",
"parser",
"ply"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "478c58a2124b53b08d165fdee4c1d6d0cae17a3464d25ec5ac3615be6a1b6dd9",
"md5": "2dc894557bdfecffce245df9ae4f79c9",
"sha256": "9b63f317c9b052dca5989ffb12577bc9e2b40ca9e1c9a872e2094aeff4124297"
},
"downloads": -1,
"filename": "cxxheaderparser-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2dc894557bdfecffce245df9ae4f79c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">= 3.6",
"size": 57915,
"upload_time": "2024-01-12T23:58:07",
"upload_time_iso_8601": "2024-01-12T23:58:07.339518Z",
"url": "https://files.pythonhosted.org/packages/47/8c/58a2124b53b08d165fdee4c1d6d0cae17a3464d25ec5ac3615be6a1b6dd9/cxxheaderparser-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cacaa3e7d3ae24ee8870decfd469242d612943626977d7a852648a7a53f6bc38",
"md5": "38a536c2a054e4c02bf79f56f5328821",
"sha256": "493576ccc2e3c87b3d10df59685cfb2acd6fe761fec9e2892e066756acfcb556"
},
"downloads": -1,
"filename": "cxxheaderparser-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "38a536c2a054e4c02bf79f56f5328821",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">= 3.6",
"size": 90686,
"upload_time": "2024-01-12T23:58:08",
"upload_time_iso_8601": "2024-01-12T23:58:08.415002Z",
"url": "https://files.pythonhosted.org/packages/ca/ca/a3e7d3ae24ee8870decfd469242d612943626977d7a852648a7a53f6bc38/cxxheaderparser-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-12 23:58:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "robotpy",
"github_project": "cxxheaderparser",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cxxheaderparser"
}
JSON
