ctopy(1) Manual Page

ctopy [-d] [-h 'hintfile'] [-c 'class'] [-s 'token'] [-t 'type']

ctopy filters C on standard output to Pythn on standard output. Tjhe translation is fast, crude, and incomplete - but a useful start.

This tool automates the parts of translating C source code to Python source code that are difficult for a human but easy for a machine. This allows a human programmer to concentrate on the parts of the translation that actually require human attention.

ctopy uses regular expressions rather than actually parsing the C, so it is easily confused by syntactically invalid C or even irregular indentation styles. On the other hand, this approach makes it easier to preserve the location of comments.

ctopy relies on the fact that C and Python have fundamentally similar constant and expression syntax; the only parts of C expressions that don’t map over in a completely trivial way are ?: and comma expressions. These will be passed through unaltered. Exception: passing a comma expression as an argument to a C library function call may confuse ctopy into translating the function call incorrectly.

ctopy also relies on the fact that C is normally indented in a way that indicates its block structure. It expects code to be indented in one of the canonical (K&R or Berkeley/C+) styles. Running it on GNU-style code is not recommended, the staitcase block delimiter may confuse it. To avoid problems, run your code through indent(1) before handing it to copy; +indent -orig or indent -kr should produce good results.

Finally, ctopy relies on the fact that C and Python have several control structures that are both syntactically and semantically similar. It translates if/else, while, and do/while (the termination clause in each do/while will require re-indenting). It doesn’t try to translate switch/case statements.

ctopy will translate C for loops that map directly to a Python loop of the form "for var in range(maxval)" or "for var in range(minval, maxval)", where minval and maxval may be expressions. More complex loops it will pass through unaltered. It recognizes C idioms for looping forever and translates those into "while True:".

ctopy throws away all type information and removes all variable declarations that don’t have initializers. It maps the C '→' operator as well as the C '.' operator to Python '.'; this works because in Python all non-scalars are passed by reference. The C99 boolean constants 'true' and 'false' are mapped to Python 'True' and 'False'

ctopy does not translate C structure and union declarations. It cannot tell the member declarations in these from variable declarations, and will try to remove them. Nor will ctopy translate most structure initializations correctly. Important exception: it can translate one-dimensional array initializers containing only scalars into Python tuples.

ctopy does translate preprocessor defines and certain simple uses of enum types into Python. It also translates preprocessor macros with arguments into Python functions. Preprocessor macros that expand to syntactically invalid C fragments will be heedlessly translated into broken Python.

ctopy knows a large number of mappings between C library headers and Python standard library modules, and applies them. Where possible, it translates C library functions to equivalent Python standard library calls. It emits warnings to standard error when calling conventions don’t match.

You can give ctopy hints. A hint may be a line in a file pulled in by the -h option, or tokens in a source file comment beginning with '$ctopy'. Available hints are as follows:

The -d option enables debugging messages that are probably only of interest to ctopy developers.

Eric S. Raymond <esr@snark.thyrsus.com>. See ESR’s home page at <ulink http://www.catb.org/~esr/ for updates and other resources.

It ought to translate structures to classes.