codekingpro/portable-devtools

1Metadata-Version: 2.42Name: pycparser3Version: 3.04Summary: C parser in Python5Author-email: Eli Bendersky <eliben@gmail.com>6Maintainer-email: Eli Bendersky <eliben@gmail.com>7License-Expression: BSD-3-Clause8Project-URL: Homepage, https://github.com/eliben/pycparser9Classifier: Development Status :: 5 - Production/Stable10Classifier: Programming Language :: Python :: 311Classifier: Programming Language :: Python :: 3.1012Classifier: Programming Language :: Python :: 3.1113Classifier: Programming Language :: Python :: 3.1214Classifier: Programming Language :: Python :: 3.1315Classifier: Programming Language :: Python :: 3.1416Requires-Python: >=3.1017Description-Content-Type: text/x-rst18License-File: LICENSE19Dynamic: license-file20 21===============22pycparser v3.0023===============24 25 26.. image:: https://github.com/eliben/pycparser/workflows/pycparser-tests/badge.svg27  :align: center28  :target: https://github.com/eliben/pycparser/actions29 30----31 32.. contents::33    :backlinks: none34 35.. sectnum::36 37Introduction38============39 40What is pycparser?41------------------42 43**pycparser** is a parser for the C language, written in pure Python. It is a44module designed to be easily integrated into applications that need to parse45C source code.46 47What is it good for?48--------------------49 50Anything that needs C code to be parsed. The following are some uses for51**pycparser**, taken from real user reports:52 53* C code obfuscator54* Front-end for various specialized C compilers55* Static code checker56* Automatic unit-test discovery57* Adding specialized extensions to the C language58 59One of the most popular uses of **pycparser** is in the `cffi60<https://cffi.readthedocs.io/en/latest/>`_ library, which uses it to parse the61declarations of C functions and types in order to auto-generate FFIs.62 63**pycparser** is unique in the sense that it's written in pure Python - a very64high level language that's easy to experiment with and tweak. To people familiar65with Lex and Yacc, **pycparser**'s code will be simple to understand. It also66has no external dependencies (except for a Python interpreter), making it very67simple to install and deploy.68 69Which version of C does pycparser support?70------------------------------------------71 72**pycparser** aims to support the full C99 language (according to the standard73ISO/IEC 9899). Some features from C11 are also supported, and patches to support74more are welcome.75 76**pycparser** supports very few GCC extensions, but it's fairly easy to set77things up so that it parses code with a lot of GCC-isms successfully. See the78`FAQ <https://github.com/eliben/pycparser/wiki/FAQ>`_ for more details.79 80What grammar does pycparser follow?81-----------------------------------82 83**pycparser** very closely follows the C grammar provided in Annex A of the C9984standard (ISO/IEC 9899).85 86How is pycparser licensed?87--------------------------88 89`BSD license <https://github.com/eliben/pycparser/blob/master/LICENSE>`_.90 91Contact details92---------------93 94For reporting problems with **pycparser** or submitting feature requests, please95open an `issue <https://github.com/eliben/pycparser/issues>`_, or submit a96pull request.97 98 99Installing100==========101 102Prerequisites103-------------104 105**pycparser** is being tested with modern versions of Python on106Linux, macOS and Windows. See `the CI dashboard <https://github.com/eliben/pycparser/actions/workflows/ci.yml>`__107for details.108 109**pycparser** has no external dependencies.110 111Installation process112--------------------113 114The recommended way to install **pycparser** is with ``pip``::115 116    > pip install pycparser117 118Using119=====120 121Interaction with the C preprocessor122-----------------------------------123 124In order to be compilable, C code must be preprocessed by the C preprocessor -125``cpp``. A compatible ``cpp`` handles preprocessing directives like ``#include`` and126``#define``, removes comments, and performs other minor tasks that prepare the C127code for compilation.128 129For all but the most trivial snippets of C code **pycparser**, like a C130compiler, must receive preprocessed C code in order to function correctly. If131you import the top-level ``parse_file`` function from the **pycparser** package,132it will interact with ``cpp`` for you, as long as it's in your PATH, or you133provide a path to it.134 135Note also that you can use ``gcc -E`` or ``clang -E`` instead of ``cpp``. See136the ``using_gcc_E_libc.py`` example for more details. Windows users can download137and install a binary build of Clang for Windows `from this website138<http://llvm.org/releases/download.html>`_.139 140What about the standard C library headers?141------------------------------------------142 143C code almost always ``#include``\s various header files from the standard C144library, like ``stdio.h``. While (with some effort) **pycparser** can be made to145parse the standard headers from any C compiler, it's much simpler to use the146provided "fake" standard includes for C11 in ``utils/fake_libc_include``. These147are standard C header files that contain only the bare necessities to allow148valid parsing of the files that use them. As a bonus, since they're minimal, it149can significantly improve the performance of parsing large C files.150 151The key point to understand here is that **pycparser** doesn't really care about152the semantics of types. It only needs to know whether some token encountered in153the source is a previously defined type. This is essential in order to be able154to parse C correctly.155 156See `this blog post157<https://eli.thegreenplace.net/2015/on-parsing-c-type-declarations-and-fake-headers>`_158for more details.159 160Note that the fake headers are not included in the ``pip`` package nor installed161via the package build (`#224 <https://github.com/eliben/pycparser/issues/224>`_).162 163Basic usage164-----------165 166Take a look at the |examples|_ directory of the distribution for a few examples167of using **pycparser**. These should be enough to get you started. Please note168that most realistic C code samples would require running the C preprocessor169before passing the code to **pycparser**; see the previous sections for more170details.171 172.. |examples| replace:: ``examples``173.. _examples: examples174 175 176Advanced usage177--------------178 179The public interface of **pycparser** is well documented with comments in180``pycparser/c_parser.py``. For a detailed overview of the various AST nodes181created by the parser, see ``pycparser/_c_ast.cfg``.182 183There's also a `FAQ available here <https://github.com/eliben/pycparser/wiki/FAQ>`_.184In any case, you can always drop me an `email <eliben@gmail.com>`_ for help.185 186 187Modifying188=========189 190There are a few points to keep in mind when modifying **pycparser**:191 192* The code for **pycparser**'s AST nodes is automatically generated from a193  configuration file - ``_c_ast.cfg``, by ``_ast_gen.py``. If you modify the AST194  configuration, make sure to re-generate the code. This can be done by running195  the ``_ast_gen.py`` script (from the repository root or the196  ``pycparser`` directory).197* Read the docstring in the constructor of the ``CParser`` class for details198  on configuration and compatibility arguments.199 200 201Package contents202================203 204Once you unzip the ``pycparser`` package, you'll see the following files and205directories:206 207README.rst:208  This README file.209 210LICENSE:211  The pycparser license212 213setup.py:214  Legacy installation script (build metadata lives in ``pyproject.toml``).215 216pyproject.toml:217  Package metadata and build configuration.218 219examples/:220  A directory with some examples of using **pycparser**221 222pycparser/:223  The **pycparser** module source code.224 225tests/:226  Unit tests.227 228utils/fake_libc_include:229  Minimal standard C library include files that should allow to parse any C code.230  Note that these headers now include C11 code, so they may not work when the231  preprocessor is configured to an earlier C standard (like ``-std=c99``).232 233utils/internal/:234  Internal utilities for my own use. You probably don't need them.235 236 237Contributors238============239 240Some people have contributed to **pycparser** by opening issues on bugs they've241found and/or submitting patches. The list of contributors is in the CONTRIBUTORS242file in the source distribution. After **pycparser** moved to Github I stopped243updating this list because Github does a much better job at tracking244contributions.245