Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Python wrapper for the Clang C++ preprocessor and parser.
C++ Python
Latest commit 4bb5131 @axw Update

I am no longer developing cmonster; please see the fork at


cmonster is a Python wrapper for the Clang C++ parser.

As well as providing standard preprocessing/parsing capabilities, cmonster adds support for:

  • Inline Python macros;
  • Programmatic #include handling; and
  • (Currently rudimentary) source-to-source translation.


There's no proper documentation yet; I'll get to it eventually. In the mean time...

Inline Python macros

You can define inline Python macros like so:

py_def(function_name(arg1, arg2, *args, **kwdargs))
    return [list_of_tokens]

Python macros must return a string, which will be tokenized, or a sequence of tokens (e.g. some combination of the input arguments). Python macros are used exactly the same as ordinary macros. e.g.

    return "".join(reversed(str(token)))
int main() {
    printf("%s\n", REVERSED("Hello, World!"));
    return 0;

Source-to-source translation

Source-to-source translation involves parsing a C++ file, generating an AST; then traversing the AST, and making modifications in a rewriter. The rewriter object maintains a history of changes, and can eventually be told to dump the modified file to a stream.

For example, here's a snippet of Python code that shows how to make an insertion at the top of each top-level function declaration's body:

import cmonster
import cmonster.ast
import sys

# Create a parser, and a rewriter. Parse the code.
parser = cmonster.Parser(filename)
ast = parser.parse()
rewriter = cmonster.Rewriter(ast)

# For each top-level function declaration, insert a statement at the top of
# its body.
for decl in ast.translation_unit.declarations:
    if decl.location.in_main_file and \
       isinstance(decl, cmonster.ast.FunctionDecl):
        insertion_loc = decl.body[0]
        rewriter.insert(insertion_loc, 'printf("Tada!\\n");\n')

# Finally, dump the result.


cmonster requires Python 3.2, LLVM/Clang 3.0, so first ensure you have them installed. To build and install cmonster from source, you will also need to install Cython.

Now you can use easy_install to install cmonster, like so: easy_install cmonster. This will download and install a prebuilt binary distribution of cmonster.

If you wish to build cmonster yourself, either pull down the git repository, or grab the source distribution from cmonster's PyPI page. When building, make sure you have LLVM 3.0's llvm-config in your execution path. To verify this, run llvm-config --version; you should expect to see 3.0 output. To build from source, simply run python3.2 install.

Something went wrong with that request. Please try again.