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 libraries PLPlot and FFTW .
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.
| C library support integrated in Modula-3 | ||
|---|---|---|
| Pragma <* EXTERNAL *> | Precedes a declaration of a PROCEDURE that is implemented in an external library instead of a Modula-3 implemenation. | |
| Pragma <* CALLBACK *> | Precedes a declaration of a PROCEDURE that should be called by external library code. | |
| Module Ctypes | Contains Modula-3 types that match some basic C type. | |
| Module M3toC | Contains routines that convert between Modula-3's TEXT type and C's char * type. | |
In each run of SWIG the Modula-3 part generates several files:
| ModuleRaw.i3 | Declaration of types that are equivalent to those of the C library, EXTERNAL of the C library functions |
| ModuleRaw.m3 | Almost empty. |
| Module.i3 | Declaration of comfortable wrappers to the C library functions. |
| Module.m3 | Implementation of the wrappers that convert between Modula-3 and C types, check for validity of values, hand-over resource management to the garbage collector using WeakRefs and raises exceptions. |
| m3makefile | Add the modules above to the Modula-3 project and specify the name of the Modula-3 wrapper library to be generated. Today I'm not sure if it is a good idea to create a m3makefile in each run, because SWIG must be started for each Modula-3 module it creates. Thus the m3makefile is overwritten each time. :-( |
|
Modula-3 wrapper Module.i3 generated by Modula-3 part of SWIG |
||
|
| v |
||
|
Modula-3 interface to C ModuleRaw.i3 generated by Modula-3 part of SWIG |
--> | C library |
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:|
Modula-3 wrapper Module.i3 generated by Modula-3 part of SWIG |
C++ library | |
|
| v |
^ | |
|
|
Modula-3 interface to C ModuleRaw.i3 generated by Modula-3 part of SWIG |
--> |
C interface to C++ module_wrap.cxx generated by the SWIG core |
Wrapping C++ libraries arises additional problems:
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.
I have still no good conception how one can split C library interfaces into type oriented interfaces. I.e. 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. Thus Modules in Modula-3 are a kind of static classes.
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).
| Modula-3 specific options | |
|---|---|
| -generateconst <file> |
Disable generation of interfaces and wrappers.
Instead write code for computing numeric values of constants
to the specified file.
C code may contain several constant definitions written as preprocessor macros. Other language modules of SWIG use compute-once-use-readonly variables or functions to wrap such definitions. All of them can invoke C code dynamically for computing the macro values. But if one wants to turn them into Modula-3 integer constants, enumerations or set types, the value of these expressions has to be known statically. Although definitions like (1 << FLAG_MAXIMIZEWINDOW) must be considered as good C style they are hard to convert to Modula-3 since the value computation can use every feature of C. Thus I implemented these switch to extract all constant definitions and write a C program that output the values of them. It works for numeric constants only and treats all of them as double. Future versions may generate a C++ program that can detect the type of the macros by overloaded output functions. Then strings can also be processable. |
| -generaterename <file> |
Disable generation of interfaces and wrappers.
Instead generate suggestions for %rename.
C libraries use a naming style that is neither homogenous nor similar to that of Modula-3. C function names often contain a prefix denoting the library and some name components separated by underscores or capitalization changes. To get library interfaces that are really Modula-3 like you should rename the function names with the %rename directive. This switch outputs a list of such directives with a name suggestion generated by a simple heuristic. |
| -generatetypemap <file> | Disable generation of interfaces and wrappers. Instead generate templates for some basic typemaps. |
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 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.
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 Module.i3 or the ModuleRaw.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:
| Typemap | Example | Description |
|---|---|---|
| m3wrapargvar | $1: Ptr := $1_name; | Declaration of some variables needed for temporary results. |
| m3wrapargraw | ORD($1_name) | The expression that should be passed as argument to the raw Modula-3 interface function. |
| m3wrapargdir | out | Referential arguments can be used for input, output, update. ??? |
| m3wrapinmode | READONLY | One of Modula-3 parameter modes VALUE (or empty), VAR, READONLY |
| m3wrapinname | New name of the input argument. | |
| m3wrapintype | Modula-3 type of the input argument. | |
| m3wrapindefault | Default value of the input argument | |
| m3wrapinconv | $1 := M3toC.SharedTtoS($1_name); | Statement for converting the Modula-3 input value to C compliant value. |
| m3wrapincheck | IF Text.Length($1_name) > 10 THEN RAISE E("str too long"); END; | Check the integrity of the input value. |
| m3wrapoutname | Name of the RECORD field to be used for returning multiple values. This applies to referential output arguments that shall be turned into return values. | |
| m3wrapouttype | Type of the value that is returned instead of a referential output argument. | |
| m3wrapoutconv | ||
| m3wrapoutcheck | ||
| m3wrapretraw | ||
| m3wrapretname | ||
| m3wraprettype | ||
| m3wrapretvar | ||
| m3wrapretconv | ||
| m3wrapretcheck | ||
| m3wrapfreearg | M3toC.FreeSharedS(str,arg1); | Free resources that were temporarily used in the wrapper. Since this step should never be skipped, SWIG will put it in the FINALLY branch of a TRY .. FINALLY structure. |
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;
%}
| unsafe | %pragma(modula3) unsafe="true"; | Mark the raw interface modules as UNSAFE. This will be necessary in many cases. |
| library | %pragma(modula3) library="m3fftw"; | Specifies the library name for the wrapper library to be created. It should be distinct from the name of the library to be wrapped. |
(* %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;