18 SWIG and Modula-3

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

18.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. The Modula-3 generator was already useful for interfacing to the PLPlot library.

18.2 Preliminaries

18.2.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 used Critical Mass' cm3.

18.2.2 Additional Commandline Options

There some experimental command line options that prevent SWIG from generating interface files. Instead files are emitted that may assist writing SWIG interface files.
Modula-3 specific options
-generateconst <file> Disable generation of interfaces and wrappers. Instead generate code for computing numeric values of constants.
-generaterename <file> Disable generation of interfaces and wrappers. Instead generate suggestions for %rename.
-generatetypemap <file> Disable generation of interfaces and wrappers. Instead generate templates for some basic typemaps.

18.3 Modula-3 typemaps

18.3.1 Inputs and outputs

Each C procedure has a bunch of inputs and outputs. Aside from global variables inputs are passed as call arguments, outputs are updated reference arguments and the function value. Each C type can have several typemaps that apply only in case the types are used as input argument, as output argument, or as return value. A further typemap may specify the direction that is used for certain parameters.

18.3.2 Exceptions

Modula-3 provides another possibility of an output of a function: exceptions. Any piecec 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 an Modula-3 exception. The RAISES clause is controlled by typemaps with the except extension.

18.3.3 Subranges, Enumerations, Sets

18.3.4 Objects

18.3.5 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} =
    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;