c2nim User's manual

Author: Andreas Rumpf
Version: 0.9.2

Introduction

"Ich bin der König aller Blinden. Glaubt ihr wirklich ihr selbst könnt sehen? Kniet euch alle nieder in den Dreck, bis ich befehle aufzustehen."

c2nim is a tool to translate Ansi C code to Nimrod. The output is human-readable Nimrod code that is meant to be tweaked by hand after the translation process. c2nim is no real compiler!

c2nim is preliminary meant to translate C header files. Because of this, the preprocessor is part of the parser. For example:

#define abc 123
#define xyz 789

Is translated into:

const
  abc* = 123
  xyz* = 789

c2nim is meant to translate fragments of C code and thus does not follow include files. c2nim cannot parse all of Ansi C and many constructs cannot be represented in Nimrod: for example duff's device cannot be translated to Nimrod.

Preprocessor support

Even though the translation process is not perfect, it is often the case that the translated Nimrod code does not need any tweaking by hand. In other cases it may be preferable to modify the input file instead of the generated Nimrod code so that c2nim can parse it properly. c2nim's preprocessor defines the symbol C2NIM that can be used to mark code sections:

#ifndef C2NIM
  // C2NIM should ignore this prototype:
  int fprintf(FILE* f, const char* frmt, ...);
#endif

The C2NIM symbol is only recognized in #ifdef and #ifndef constructs! #if defined(C2NIM) does not work.

c2nim processes #ifdef C2NIM and #ifndef C2NIM directives, but other #if[def] directives are translated into Nimrod's when construct:

#ifdef DEBUG
#  define OUT(x) printf("%s\n", x)
#else
#  define OUT(x)
#endif

Is translated into:

when defined(debug):
  template OUT*(x: expr): expr =
    printf("%s\x0A", x)
else:
  template OUT*(x: expr): stmt =
    nil

As can been seen from the example, C's macros with parameters are mapped to Nimrod's templates. This mapping is the best one can do, but it is of course not accurate: Nimrod's templates operate on syntax trees whereas C's macros work on the token level. c2nim cannot translate any macro that contains the ## token concatenation operator.

c2nim's preprocessor supports special directives that affect how the output is generated. They should be put into a #ifdef C2NIM section so that ordinary C compilers ignore them.

#skipinclude directive

Note: There is also a --skipinclude command line option that can be used for the same purpose.

By default, c2nim translates an #include that is not followed by < (like in #include <stdlib>) to a Nimrod import statement. This directive tells c2nim to just skip any #include.

#stdcall and #cdecl directives

Note: There are also --stdcall and --cdecl command line options that can be used for the same purpose.

These directives tell c2nim that it should annotate every proc (or proc type) with the stdcall / cdecl calling convention.

#dynlib directive

Note: There is also a --dynlib command line option that can be used for the same purpose.

This directive tells c2nim that it should annotate every proc that resulted from a C function prototype with the dynlib pragma:

#ifdef C2NIM
#  dynlib iupdll
#  cdecl
#  if defined(windows)
#    define iupdll "iup.dll"
#  elif defined(macosx)
#    define iupdll "libiup.dylib"
#  else
#    define iupdll "libiup.so"
#  endif
#endif

int IupConvertXYToPos(PIhandle ih, int x, int y);

Is translated to:

when defined(windows):
  const iupdll* = "iup.dll"
elif defined(macosx):
  const iupdll* = "libiup.dylib"
else:
  const iupdll* = "libiup.so"

proc IupConvertXYToPos*(ih: PIhandle, x: cint, y: cint): cint {.
  importc: "IupConvertXYToPos", cdecl, dynlib: iupdll.}

Note how the example contains extra C code to declare the iupdll symbol in the generated Nimrod code.

#header directive

Note: There is also a --header command line option that can be used for the same purpose.

The #header directive tells c2nim that it should annotate every proc that resulted from a C function prototype and every exported variable and type with the header pragma:

#ifdef C2NIM
#  header "iup.h"
#endif

int IupConvertXYToPos(PIhandle ih, int x, int y);

Is translated to:

proc IupConvertXYToPos*(ih: PIhandle, x: cint, y: cint): cint {.
  importc: "IupConvertXYToPos", header: "iup.h".}

The #header and the #dynlib directives are mutually exclusive. A binding that uses dynlib is much more preferable over one that uses header! The Nimrod compiler might drop support for the header pragma in the future as it cannot work for backends that do not generate C code.

#prefix and #suffix directives

Note: There are also --prefix and --suffix command line options that can be used for the same purpose.

c2nim does not do any name mangling by default. However the #prefix and #suffix directives can be used to strip prefixes and suffixes from the identifiers in the C code:

#ifdef C2NIM
#  prefix Iup
#  dynlib dllname
#  cdecl
#endif

int IupConvertXYToPos(PIhandle ih, int x, int y);

Is translated to:

proc ConvertXYToPos*(ih: PIhandle, x: cint, y: cint): cint {.
  importc: "IupConvertXYToPos", cdecl, dynlib: dllname.}

#mangle directive

Even more sophisticated name mangling can be achieved by the #mangle directive: It takes a PEG pattern and format string that specify how the identifier should be converted:

#mangle "'GTK_'{.*}" "TGtk$1"

For convenience the PEG pattern and the replacement can be single identifiers too, there is no need to quote them:

#mangle ssize_t  int
// is short for:
#mangle "'ssize_t'" "int"

#private directive

By default c2nim marks every top level identifier (proc name, variable, etc.) as exported (the export marker is * in Nimrod). With the #private directive identifiers can be marked as private so that the resulting Nimrod module does not export them. The #private directive takes a PEG pattern:

#private "@('_'!.)" // all identifiers ending in '_' are private

Note: The pattern refers to the original C identifiers, not to the resulting identifiers after mangling!

#skipcomments directive

Note: There is also a --skipcomments command line option that can be used for the same purpose.

The #skipcomments directive can be put into the C code to make c2nim ignore comments and not copy them into the generated Nimrod file.

#typeprefixes directive

Note: There is also a --typeprefixes command line option that can be used for the same purpose.

The #typeprefixes directive can be put into the C code to make c2nim generate the T or P prefix for every defined type.

#def directive

Often C code contains special macros that affect the declaration of a function prototype but confuse c2nim's parser:

// does not parse!
EXTERN(int) f(void);
EXTERN(int) g(void);

Instead of removing EXTERN() from the input source file (which cannot be done reliably even with a regular expression!), one can tell c2nim that EXPORT is a macro that should be expanded by c2nim too:

#ifdef C2NIM
#  def EXTERN(x) static x
#endif
// parses now!
EXTERN(int) f(void);
EXTERN(int) g(void);

#def is very similar to C's #define, so in general the macro definition can be copied and pasted into a #def directive.

Limitations

Generated: 2013-05-21 09:55:04 UTC