24 SWIG and Modula-3

This chapter describes SWIG's support of Modula-3. You should be familiar with the basics of SWIG, especially typemaps.

24.1 Overview

The Modula-3 support is very basic and highly experimental! Many features are still not designed satisfyingly and I need more discussion about the odds and ends. Don't rely on any feature, incompatible changes are likely in the future! The Modula-3 generator was already useful for interfacing to the libraries

1. PLPlot
2. FFTW .

I took some more time to explain why I think it's right what I'm doing. So the introduction got a bit longer than it should ... ;-)

24.1.1 Why not scripting ?

SWIG started as wrapper from the fast compiled languages C and C++ to high level scripting languages like Python. Although scripting languages are designed to make programming life easier by hiding machine internals from the programmer there are several aspects of today's scripting languages that are unfavourable in my opinion.

Besides C, C++, Cluster (a Modula derivate for Amiga computers) I evaluated several scripting like languages in the past: Different dialects of BASIC, Perl, ARexx (a variant of Rexx for Amiga computers), shell scripts. I found them too inconsistent, too weak in distinguishing types, too weak in encapsulating pieces of code. Eventually I have started several projects in Python because of the fine syntax. But when projects became larger I lost the track. I got convinced that one can not have maintainable code in a language that is not statically typed. In fact the main advantages of scripting languages e.g. matching regular expressions, complex built-in datatypes like lists, dictionaries, are not advantages of the language itself but can be provided by function libraries.

24.1.2 Why Modula-3 ?

Modula-3 is a compiler language in the tradition of Niklaus Wirth's Modula 2, which is in turn a successor of the popular Pascal. I have chosen Modula-3 because of its logical syntax, strong modularization, the type system which is very detailed for machine types compared to other languages. Of course it supports all of the modern games like exceptions, objects, garbage collection, threads. While C++ programmers must control three languages, namely the preprocessor, C and ++, Modula-3 is made in one go and the language definition is really compact.

On the one hand Modula-3 can be safe (but probably less efficient) in normal modules while providing much static and dynamic safety. On the other hand you can write efficient but less safe code in the style of C within UNSAFE modules.

Unfortunately Modula's safety and strength requires more writing than scripting languages do. Today if I want to safe characters I prefer Haskell (similar to OCAML) - it's statically typed, too.

24.1.3 Why C / C++ ?

Although it is no problem to write Modula-3 programs that performs as fast as C most libraries are not written in Modula-3 but in C. Fortunately the binary interface of most function libraries can be addressed by Modula-3. Even more fortunately even non-C libraries may provide C header files. This is where SWIG becomes helpful.

24.1.4 Why SWIG ?

The C headers and the possibility to interface to C libraries still leaves the work for you to write Modula-3 interfaces to them. To make things comfortable you will also need wrappers that convert between high-level features of Modula-3 (garbage collecting, exceptions) and the low level of the C libraries.

SWIG converts C headers to Modula-3 interfaces for you. You could call the C functions without loss of efficiency but it won't be joy because you could not pass TEXTs or open arrays and you would have to process error return codes rather then exceptions. But using some typemaps SWIG will also generate wrappers that bring the whole Modula-3 comfort to you. If the library API is ill designed writing appropriate typemaps can be still time-consuming. E.g. C programmers are very creative to work-around missing data types like (real) enumerations and sets. You should turn such work-arounds back to the Modula-3 way otherwise you lose static safety and consistency.

But you have still a problem: C library interfaces are often ill. They lack for certain information because C compilers wouldn't care about. You should integrate detailed type information by adding typedefs and consts and you should persuade the C library programmer to add this information to his interface. Only this way other language users can benefit from your work and only this way you can easily update your interfaces when a new library version is released. You will realise that writing good SWIG interfaces is very costly and it will only amortise when considering evolving libraries.

Without SWIG you would probably never consider to call C++ libraries from Modula-3. But with SWIG this is worth a consideration. SWIG can write C wrappers to C++ functions and object methods that may throw exceptions. In fact it breaks down C++ libraries to C interfaces which can be in turn called from Modula-3. To make it complete you can hide the C interface with Modula-3 classes and exceptions.

Although SWIG does the best it can do it can only serve as a one-way strategy. That means you can use C++ libraries with Modula-3 (even with call back functions), but it's certainly not possible to smoothly integrate Modula-3 code into a C / C++ project.

24.2 Conception

24.2.1 Interfaces to C libraries

Modula-3 has an integrated support for calling C functions. This is also extensively used by the standard Modula-3 libraries to call OS functions. The Modula-3 part of SWIG and the corresponding SWIG library modula3.swg contain code that uses these features. Because of the built-in support there is no need for calling the SWIG kernel to generate wrappers written in C. All conversion and argument checking can be done in Modula-3 and the interfacing is quite efficient. All you have to do is to write pieces of Modula-3 code that SWIG puts together.

In each run of SWIG the Modula-3 part generates several files:

Here's a scheme of how the function calls to Modula-3 wrappers are redirected to C library functions:

I have still no good conception how one can split C library interfaces into type oriented interfaces. A Module in Modula-3 represents an Abstract DataType (or call it a static classes, i.e. a class without virtual methods). E.g. if you have a principal type, say Database, it is good Modula-3 style to set up one Module with the name Database where the database type is declared with the name T and where all functions are declared that operates on it.

The normal operation of SWIG is to generate a fixed set of files per call. To generate multiple modules one has to write one SWIG interface (different SWIG interfaces can share common data) per module. Identifiers belonging to a different module may ignored (%ignore) and the principal type must be renamed (%typemap).

24.2.2 Interfaces to C++ libraries

Interfaces to C++ files are much more complicated and there are some more design decisions that are not made, yet. Modula-3 has no support for C++ functions but C++ compilers should support generating C++ functions with a C interface.

Here's a scheme of how the function calls to Modula-3 wrappers a redirected to C library functions:

Wrapping C++ libraries arises additional problems:

• Is it sensible to wrap C++ classes with Modula-3 classes?
• How to find the wrapping Modula-3 class for a class pointer that is returned by a C++ routine?
• How to deal with multiple inheritance which was neglected for Modula-3 for good reasons?
• Is it possible to sub-class C++ classes with Modula-3 code? This issue is addressed by directors, a feature that was experimentally added to some Language modules like Java and Python.
• How to manage storage with the garbage collector of Modula-3? Support for %newobject and %typemap(newfree) isn't implemented, yet. What's about resources that are managed by the garbage collector but shall be passed back to the storage management of the C++ library? This is a general issue which is not solved in a satisfying fashion as far as I know.
• How to turn C++ exceptions into Modula-3 exceptions? There's also no support for %exception, yet.

Be warned: There is no C++ library I wrote a SWIG interface for, so I'm not sure if this is possible or sensible, yet.

24.3 Preliminaries

24.3.1 Compilers

There are different Modula-3 compilers around: cm3, pm3, ezm3, Klagenfurth Modula-3, Cambridge Modula-3. SWIG itself does not contain compiler specific code but the library file modula3.swg may do so. For testing examples I use Critical Mass cm3.

24.3.2 Additional Commandline Options

There are some experimental command line options that prevent SWIG from generating interface files. Instead files are emitted that may assist you when writing SWIG interface files.

24.4 Modula-3 typemaps

24.4.1 Inputs and outputs

Each C procedure has a bunch of inputs and outputs. Inputs are passed as function arguments, outputs are updated referential arguments and the function value.

Each C type can have several typemaps that apply only in case if a type is used for an input argument, for an output argument, or for a return value. A further typemap may specify the direction that is used for certain parameters. I have chosen this separation in order to be able to write general typemaps for the typemap library modula3.swg . In the library code the final usage of the type is not known. Using separate typemaps for each possible use allows appropriate definitions for each case. If these pre-definitions are fine then the direction of the function parameter is the only hint the user must give.

The typemaps specific to Modula-3 have a common name scheme: A typemap name starts with "m3", followed by "raw" or "wrap" depending on whether it controls the generation of the ModuleRaw.i3 or the Module.i3, respectively. It follows an "in" for typemaps applied to input argument, "out" for output arguments, "arg" for all kind of arguments, "ret" for returned values.

The main task of SWIG is to build wrapper function, i.e. functions that convert values between C and Modula-3 and call the corresponding C function. Modula-3 wrapper functions generated by SWIG consist of the following parts:

• Generate PROCEDURE signature.
• Declare local variables.
• Convert input values from Modula-3 to C.
• Check for input value integrity.
• Call the C function.
• Check returned values, e.g. error codes.
• Convert and write back values into Modula-3 records.
• Free temporary storage.
• Return values.

24.4.2 Subranges, Enumerations, Sets

Subranges, enumerations, and sets are machine oriented types that make Modula very strong and expressive compared with the type systems of many other languages.

• Subranges are used for statically restricted choices of integers.
• Enumerations are used for named choices.
• Sets are commonly used for flag (option) sets.

Using them extensively makes Modula code very safe and readable.

C supports enumerations, too, but they are not as safe as the ones of Modula. Thus they are abused for many things: For named choices, for integer constant definitions, for sets. To make it complete every way of defining a value in C (#define, const int, enum) is somewhere used for defining something that must be handled completely different in Modula-3 (INTEGER, enumeration, SET).

I played around with several %features and %pragmas that split the task up into converting the C bit patterns (integer or bit set) into Modula-3 bit patterns (integer or bit set) and change the type as requested. See the corresponding example in the Examples/modula3/enum/example.i file. This is quite messy and not satisfying. So the best what you can currently do is to rewrite constant definitions manually. Though this is a tedious work that I'd like to automate.

24.4.3 Objects

Declarations of C++ classes are mapped to OBJECT types while it is tried to retain the access hierarchy "public - protected - private" using partial revelation. Though the example in Examples/modula3/class/example.i is not really useful, yet.

24.4.4 Imports

Pieces of Modula-3 code provided by typemaps may contain identifiers from foreign modules. If the typemap m3wrapinconv for blah * contains code using the function M3toC.SharedTtoS you may declare %typemap("m3wrapinconv:import") blah * %{M3toC%}. Then the module M3toC is imported if the m3wrapinconv typemap for blah * is used at least once. Use %typemap("m3wrapinconv:import") blah * %{MyConversions AS M3toC%} if you need module renaming. Unqualified import is not supported.

It is cumbersome to add this typemap to each piece of Modula-3 code. It is especially useful when writing general typemaps for the typemap library modula3.swg . For a monolithic module you might be better off if you add the imports directly:

%insert(m3rawintf) %{
IMPORT M3toC;
%}

24.4.5 Exceptions

Modula-3 provides another possibility of an output of a function: exceptions.

Any piece of Modula-3 code that SWIG inserts due to a typemap can raise an exception. This way you can also convert an error code from a C function into a Modula-3 exception.

The RAISES clause is controlled by typemaps with the throws extension. If the typemap m3wrapinconv for blah * contains code that may raise the exceptions OSError.E you should declare %typemap("m3wrapinconv:throws") blah * %{OSError.E%}.

24.4.6 Example

The generation of wrappers in Modula-3 needs very fine control to take advantage of the language features. Here is an example of a generated wrapper where almost everything is generated by a typemap:

         (* %relabel  m3wrapinmode m3wrapinname m3wrapintype  m3wrapindefault *)
  PROCEDURE Name     (READONLY       str       :    TEXT    :=      ""       )
              (* m3wrapoutcheck:throws *)
     : NameResult RAISES {E} =
    CONST
      arg1name = "str";                  (* m3wrapargconst *)
    VAR
      arg0   : C.char_star;              (* m3wrapretvar *)
      arg1   : C.char_star;              (* m3wrapargvar *)
      arg2   : C.int;
      result : RECORD
           (*m3wrapretname  m3wraprettype*)
                 unixPath : TEXT;
           (*m3wrapoutname  m3wrapouttype*)
                 checksum : CARDINAL;
               END;
    BEGIN
      TRY
        arg1 := M3toC.SharedTtoS(str);   (* m3wrapinconv *)
        IF Text.Length(arg1) > 10 THEN   (* m3wrapincheck *)
          RAISE E("str too long");
        END;
 (* m3wrapretraw           m3wrapargraw *)
        arg0 := MessyToUnix  (arg1,   arg2);
        result.unixPath := M3toC.CopyStoT(arg0);  (* m3wrapretconv *)
        result.checksum := arg2;         (* m3wrapoutconv *)
        IF result.checksum = 0 THEN      (* m3wrapoutcheck *)
          RAISE E("invalid checksum");
        END;
      FINALLY
        M3toC.FreeSharedS(str,arg1);     (* m3wrapfreearg *)
      END;
    END Name;

24.5 More hints to the generator

24.5.1 Features

24.5.2 Pragmas

24.6 Remarks

• The Modula-3 part of SWIG doesn't try to generate nicely formatted code. Use m3pp to postprocess the Modula files, it does a very good job here.