Contents

• Introduction
• Restrictions
• CDL Processing
• Class Definition Language (CDL)
  • Syntax
  • Argument Types
  • Return Types
• Exceptions

The Object Tcl extension is implemented in C++ in such a way as to promote the use and reuse of C++ classes from within Object Tcl scripts.

Object Tcl makes it possible to:

• Create, manipulate and destruct C++ classes from within the Object Tcl domain.
• Create, manipulate and destruct Object Tcl classes, that inherit from C++ classes, from within the C++ domain.
• Inherit Object Tcl classes from built-in C++ classes. Note that the dynamic binding of methods crosses the domain from C++ to Object Tcl and vice versa.
• Pass Object Tcl objects, of a class that inherits from an existing C++ class, into the C++ domain for manipulation and possible destruction.
• Re-implement Object Tcl classes in C++ for performance improvements and access to the more esoteric OS or third party library facilities with minimal effort.

Object Tcl provides an interpreted extension to the C++ language while still maintaining the support for object orientation.

This page describes how C++ classes may be exported to the Object Tcl system for use from Tcl.

There are a few restrictions on the usage of C++ and Object Tcl. These restrictions are described below:

1. C++ makes it possible to have many methods with the same name that can be distinguished by their formal arguments. In C++ this is called overloading. Tcl is weakly typed and it is therefore impossible to disambiguate the methods based on the types of the formal arguments. For this reason method overloading is not supported.

   If a C++ class does have more than one method with a given name and it is to be exported to Object Tcl then the CDL for this class must describe only one of them.

   The most common occurrence of overloading is in class constructors. Only one constructor for a C++ class may be exported to Object Tcl.

2. C++ provides support for defining the behavior of operations upon a class. This is called operator overloading. Object Tcl does not support this. Operators on a C++ class cannot be exported into Object Tcl.

3. As Tcl is weakly typed, with all types represented as strings, then there are restrictions on the parameters and return types that may be passed back and forth between the two domains. The CDL processor is designed in a way to make it easy to build in additional type conversion support.

4. It is not possible to instantiate a C++ class in the C++ domain and then pass it into the Object Tcl domain for manipulation. If an object is to be passed back and forth between the C++ and Object Tcl domains it must be instantiated in the Object Tcl domain. This can be done by calling Tcl_Eval(...,"otclNew class args",...) from C++. Future versions of Object Tcl will attempt to address this issue.

The Object Tcl system includes a CDL processor called "cdl". The CDL processor takes files in the CDL format and generates C++ files that will bind the application's C++ classes into Object Tcl.

The CDL processor takes two arguments: the first is the name of the input file, including suffix, and the second is the output file, including suffix.

Rules can be added to makefiles to automatically take CDL files, with a suitable suffix, and generate C++ files that are then compiled into object files.

The C++ code generated by the CDL processor uses C++ static constructors to facilitate the inclusion of an application's C++ classes into the Object Tcl environment with absolutely no modification of the application code. Only a relink is necessary.

CDL files contain descriptions of the C++ classes that are to be exported to Object Tcl.

Syntax

The CDL processor is based around a Tcl interpreter itself, hence the familiarity of the CDL syntax.

In a CDL file there are two commands:

pass arg

and

class name desc

The pass command takes the rest of the arguments and passes them straight through to the generated C++ file. The pass command is generally used to place #include directives in the generated C++ but it is also useful for placing comments or version identifiers in the C++ files.

The class command is used to describe a C++ class to the Object Tcl system. The name argument is the name of the class and the desc argument is a Tcl script that may use the following commands internally:

constructor args

This command describes the constructor for the C++ class that will be exported to Object Tcl. The args argument is a Tcl script that may use the argument type commands.

method name (-dynamic | -static) args rtn

This command describes an instance method that will be exported to Object Tcl. The name argument is the name of the method; the -dynamic or -static switch indicates whether the method is a C++ virtual method or not. The args argument is a Tcl script that may use the argument type commands, and the rtn argument is a script that may use one of the return type commands.

A C++ virtual method can be exported as -static in which case the dynamic binding will stop at the Object Tcl/C++ interface. This may be of use in some cases as the use of the -dynamic option causes a performance overhead even if the method is not redefined in an Object Tcl subclass.

classMethod name args rtn

This command describes a class method (a C++ static member function) that will be exported to Object Tcl. The name argument is the name of the method. The args argument is a Tcl script that may use the argument type commands, and the rtn argument is a script that may use one of the return type commands.

The arg parameter of the constructor, method and classMethod commands is a Tcl script that can make use of the following commands:

• int
• float
• double
• str
• obref className

The className argument to the obref command specifies the actual class expected by the C++ method.

The CDL processor is designed to make it easy to support new type conversions between the C++ and the Object Tcl domains.

Return Types

The rtn parameter of the method and classMethod commands is a Tcl script that can make use of the following commands:

• int
• float
• double
• str
• obref className

The className argument to the obref command specifies the actual class returned by the C++ method.

As with argument types, the CDL processor is designed to make it easy to add new type conversions between C++ and the Object Tcl domains.

Dynamic binding of methods makes it possible for a C++ method invocation to result in the execution of a method described in Tcl. It is quite possible for the Tcl to be incorrect and generate an exception.

It is possible to catch exceptions in three ways.

General exception handler

By default, any exception in a Tcl method body invoked from the C++ domain will result in the error being reported to stdout and the application terminating with an error status.

Object exception handler in Tcl

It is possible to implement an instance method called otclErrorMethod on an Object Tcl class. This method will be called on any Tcl exception that occurs when a method is invoked from C++.

The otclErrorMethod takes two parameters. The first parameter is the name of the method that caused the exception; the second is the error message generated by the exception.

Object exception handler in C++

It is possible to implement an instance method called otclErrorMethod on a C++ class in the same manner as for Object Tcl classes described above. This method must be exported to the Object Tcl system via the CDL description and it must take two arguments, both of which are of type char *.