What is xctocc?

xctocc reads ``.xc'' script files and generates ``.cc'' C++ files. An ``.xc'' file contains descriptions of C++ classes and functions; this information is similar to the information in a header file, but xctocc needs more specific information about parameter types and how to bundle and unbundle complex types.

Here is an example C++ header file ``points.h'':

  class IntPoint 
  {
    protected:
      int pointtype;
      int first, second;
    public:
      IntPoint(int first = 0, int second = 0);
      int First(void);
      int Second(void);
      int operator==(IntPoint *other);
  };

  class ColorIntPoint : public IntPoint
  {
    private:
      int colorid;
    public:
      ColorIntPoint(int first = 0, int second = 0, char *color = "white");
      ColorIntPoint(char *color);
      char *Color(void);
      int operator==(IntPoint *other);

      int colorbad; // Set to TRUE if the color doesn't really exist
  };

  // Dynamic type values:
  enum {
    PlainType,
    ColorType
  };

  // Color management:
  int LookupColorId(char *name);
  char *ColorNameFromId(int id);

  enum {
    WhiteColor,
    BlackColor,
    RedColor,
    GreenColor,
    BlueColor
  };

This header defines two classes: IntPoint and ColorIntPoint. Dynamic type information is stored in the pointtype member. In addition to the classes, there are two global functions.

Here is a script ``points.xc'' that generates glue code for these class and function definitions:

  #include "points.h"

  @BOOLEAN int
  @CLASSSUFFIX "%"
  @IDFIELD pointtype

  @HEADER

  @CLASSBASE IntPoint "int-point"
  @CLASSID PlainType

  @CREATOR (int=0,int=0)

  @ "first" : int First()
  @ "second" : int Second()
  @ "equal?" : bool operator==(IntPoint!)

  @END

  @CLASSBASE ColorIntPoint "color-int-point" : "int-point"
  @CLASSID ColorType

  @CREATOR (int=0,int=0,string="white")
  @CREATOR ()

  @ "color" : string Color()
  @ "equal?" : int operator==(IntPoint!)

  @IVAR r "color-bad" : bool colorbad

  @END

  @GLOBAL Colors

  @ "lookup-color-id" : int LookupColorId(string);
  @ "color-name-from-id" : string ColorNameFromId(int);

  @CONSTANT "const-white-color" : int WhiteColor
  @CONSTANT "const-black-color" : int WhiteColor
  @CONSTANT "const-red-color" : int RedColor
  @CONSTANT "const-green-color" : int GreenColor
  @CONSTANT "const-blue-color" : int BlueColor

  @END

• #include@#include The first line of this script includes the header file ``points.h''; the C++ glue code will need this header file for the class definitions, constant declarations, and global function prototypes. This line will be copied through to the C++ file, because it doesn't start with ``@''.
• The next three lines are configuration.
  • @BOOLEAN @BOOLEAN determines how the MzScheme boolean type should be interpreted in C++; in the script, booleans are designated by the type bool bool.
  • @CLASSSUFFIX @CLASSSUFFIX sets the string to be used at the end of a class name in MzScheme. This is ``%'' by convention.
  • @IDFIELD @IDFIELD specifies where to find dynamic class type information; in this case, the type is stored in the pointtype member. Dynamic type information is not required, but its presence allows more accurate C++-to-Scheme value bundling.
• The @HEADER @HEADER command specifies where to insert #include statements for header files that are needed/generated by the glue code.
• The first class (IntPoint) is defined in this script with the @CLASSBASE @CLASSBASE statement. The Scheme name for this class will be int-point%. The dynamic type value for this class is PlainType, as indicated by the @CLASSID @CLASSID statement.
• The @CREATOR @CREATOR declaration prototypes the constructor so that objects in the class IntPoint can be created from Scheme. The construction (or ``object intialization function'', in MzScheme) takes two integer arguments, which can be defaulted to 0.
• The IntPoint class has three other methods, which will be called first, second, and equal? in Scheme. Note that the type of the parameter of operator== is IntPoint!; the ``!'' indicates that the parameter is an object, passed by pointer.
• The @END @END command causes the glue code for this class to be generated, based on all the statmentes between @CLASSBASE and @END.
• The declaration of ColorIntPoint is similar. Here, there are two ways to call the constructor, so there are two @CREATOR statements. Also, note that a Scheme superclass is specified in the @CLASSBASE statement.
• Note that the type string is used for the color name instead of char*. This is because char* in C++ could mean:
  • A null-ternimated string
  • A pointer to a single character
  • A pointer to a fixed-length array of characters
  • A string or NULL
  • A pointer to a character of NULL
  • A pointer to an array or NULL
  In xctocc, these types must all be distingushed so that the proper glue code can be generated.
• The colorbad member is publically available; this member is made accessible in Scheme withthe @IVAR @IVAR statement. The ``r'' indicates that this variable is read-only; a Scheme method get-color-bad will be generated, but not set-color-bad.
• Global functions are declared together after a @GLOBAL statment, similar to methods within a class. The name supplied with @GLOBAL @GLOBAL is needed for intialization.
• Constant values are defined with @CONSTANT @CONSTANT. Note that the type for the color values must be specified as int, even through they are really declared by an enum statement.

If all class definitions were as simple as these, then xctocc would be a reasonably good (though poorly implemented) tool. Unfortunately, the presence of ``complications'' occurs more often in real C++ class libraries than was anticipated in the initial design for xctocc. Thus, the xctocc scripting language has turned into a monsterous jumble of switches and special cases. Still, until someone writes a replacement, using xctocc is typically simpler and more reliable than writing the glue code by hand.