From: Eric S. Raymond Date: Fri, 20 Oct 2006 17:16:11 +0000 (+0000) Subject: Initial revision of manual page X-Git-Tag: 1.0 X-Git-Url: http://thyrsus.com/gitweb/?a=commitdiff_plain;h=b08b01414c00f4a723b20c4d8725b8cb7f88e4e2;p=ctopy.git Initial revision of manual page --- diff --git a/ctopy.xml b/ctopy.xml new file mode 100644 index 0000000..fbb237f --- /dev/null +++ b/ctopy.xml @@ -0,0 +1,134 @@ + + + +ctopy +1 +Oct 20 2006 + + +ctopy +a quick and dirty C to Python translator) + + + + + ctopy + + + + +DESCRIPTION + +ctopy 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. To avoid problems, +run your code through +indent1 +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: + + + +type <name> +Treat <name> as a scalar type, not requiring +initialization except by first assignment. + + +class <name> +Treat name as a class; variables of this type +must be initialized by calling the class's contructor +and assigning the returned value to the variable. + + +stringify <name> +When this name occurs surrounded by word boundaries, +put string quotes around it. Useful for translating enumerated-type +values into string literals, which Python has as a first-class +type. + + +printflike <name> +declarates that a function is like printf; its string +arguments containing, if any, should be treated like printf formats +and their arg lists replaced with % followed by a tuple containing the +args. + + + + +AUTHORS +Eric S. Raymond <esr@snark.thyrsus.com>. See ESR's home +page at http://www.catb.org/~esr/ for +updates and other resources. + + +BUGS + + + +