modula3: documented some of the conceptions and typemaps, added anchors to modules I refer to
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@5951 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
amigalemming
parent
2b4f480f34
commit
8e3942823f
6 changed files with 605 additions and 47 deletions
|
|
@ -610,18 +610,27 @@
|
||||||
<!-- INDEX -->
|
<!-- INDEX -->
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="Modula3.html#n2">Overview</a>
|
<li><a href="Modula3.html#n2">Overview</a>
|
||||||
<li><a href="Modula3.html#n3">Preliminaries</a>
|
<li><a href="Modula3.html#n3">Conception</a>
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="Modula3.html#n4">Compilers</a>
|
<li><a href="Modula3.html#n4">Interfaces to C libraries</a>
|
||||||
<li><a href="Modula3.html#n5">Additional Commandline Options</a>
|
<li><a href="Modula3.html#n5">Interfaces to C++ libraries</a>
|
||||||
|
<li><a href="Modula3.html#n6">No plan?</a>
|
||||||
</ul>
|
</ul>
|
||||||
<li><a href="Modula3.html#n6">Modula-3 typemaps</a>
|
<li><a href="Modula3.html#n7">Preliminaries</a>
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="Modula3.html#n7">Inputs and outputs</a>
|
<li><a href="Modula3.html#n8">Compilers</a>
|
||||||
<li><a href="Modula3.html#n8">Exceptions</a>
|
<li><a href="Modula3.html#n9">Additional Commandline Options</a>
|
||||||
<li><a href="Modula3.html#n9">Subranges, Enumerations, Sets</a>
|
</ul>
|
||||||
<li><a href="Modula3.html#n10">Objects</a>
|
<li><a href="Modula3.html#n10">Modula-3 typemaps</a>
|
||||||
<li><a href="Modula3.html#n11">Example</a>
|
<ul>
|
||||||
|
<li><a href="Modula3.html#n11">Inputs and outputs</a>
|
||||||
|
<li><a href="Modula3.html#n12">Subranges, Enumerations, Sets</a>
|
||||||
|
<li><a href="Modula3.html#n13">Objects</a>
|
||||||
|
<li><a href="Modula3.html#n14">Imports</a>
|
||||||
|
<li><a href="Modula3.html#n15">Exceptions</a>
|
||||||
|
<li><a href="Modula3.html#n16">Pragmas</a>
|
||||||
|
<li><a href="Modula3.html#n17">Example</a>
|
||||||
|
<li><a href="Modula3.html#n18">Remarks</a>
|
||||||
</ul>
|
</ul>
|
||||||
</ul>
|
</ul>
|
||||||
<!-- INDEX -->
|
<!-- INDEX -->
|
||||||
|
|
|
||||||
|
|
@ -31,6 +31,7 @@ describes some of these customization techniques. First, a discussion
|
||||||
of exception handling is presented. Then, a more general-purpose
|
of exception handling is presented. Then, a more general-purpose
|
||||||
customization mechanism known as "features" is described.
|
customization mechanism known as "features" is described.
|
||||||
|
|
||||||
|
<a name="exception">
|
||||||
<a name="n2"></a><H2>9.1 Exception handling with %exception</H2>
|
<a name="n2"></a><H2>9.1 Exception handling with %exception</H2>
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -396,6 +397,7 @@ Since the <tt>SWIG_exception()</tt> function is defined at the C-level
|
||||||
it can be used elsewhere in SWIG. This includes typemaps and helper
|
it can be used elsewhere in SWIG. This includes typemaps and helper
|
||||||
functions.
|
functions.
|
||||||
|
|
||||||
|
<a name="ownership">
|
||||||
<a name="n8"></a><H2>9.2 Object ownership and %newobject</H2>
|
<a name="n8"></a><H2>9.2 Object ownership and %newobject</H2>
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -8,18 +8,27 @@
|
||||||
<!-- INDEX -->
|
<!-- INDEX -->
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="#n2">Overview</a>
|
<li><a href="#n2">Overview</a>
|
||||||
<li><a href="#n3">Preliminaries</a>
|
<li><a href="#n3">Conception</a>
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="#n4">Compilers</a>
|
<li><a href="#n4">Interfaces to C libraries</a>
|
||||||
<li><a href="#n5">Additional Commandline Options</a>
|
<li><a href="#n5">Interfaces to C++ libraries</a>
|
||||||
|
<li><a href="#n6">No plan?</a>
|
||||||
</ul>
|
</ul>
|
||||||
<li><a href="#n6">Modula-3 typemaps</a>
|
<li><a href="#n7">Preliminaries</a>
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="#n7">Inputs and outputs</a>
|
<li><a href="#n8">Compilers</a>
|
||||||
<li><a href="#n8">Exceptions</a>
|
<li><a href="#n9">Additional Commandline Options</a>
|
||||||
<li><a href="#n9">Subranges, Enumerations, Sets</a>
|
</ul>
|
||||||
<li><a href="#n10">Objects</a>
|
<li><a href="#n10">Modula-3 typemaps</a>
|
||||||
<li><a href="#n11">Example</a>
|
<ul>
|
||||||
|
<li><a href="#n11">Inputs and outputs</a>
|
||||||
|
<li><a href="#n12">Subranges, Enumerations, Sets</a>
|
||||||
|
<li><a href="#n13">Objects</a>
|
||||||
|
<li><a href="#n14">Imports</a>
|
||||||
|
<li><a href="#n15">Exceptions</a>
|
||||||
|
<li><a href="#n16">Pragmas</a>
|
||||||
|
<li><a href="#n17">Example</a>
|
||||||
|
<li><a href="#n18">Remarks</a>
|
||||||
</ul>
|
</ul>
|
||||||
</ul>
|
</ul>
|
||||||
<!-- INDEX -->
|
<!-- INDEX -->
|
||||||
|
|
@ -42,11 +51,15 @@ The Modula-3 support is very basic and highly experimental!
|
||||||
Many features are still not designed satisfyingly
|
Many features are still not designed satisfyingly
|
||||||
and I need more discussion about the odds and ends.
|
and I need more discussion about the odds and ends.
|
||||||
The Modula-3 generator was already useful for interfacing
|
The Modula-3 generator was already useful for interfacing
|
||||||
to the
|
to the libraries
|
||||||
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/plplot/">
|
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/plplot/">
|
||||||
PLPlot
|
PLPlot
|
||||||
</a>
|
</a>
|
||||||
library.
|
and
|
||||||
|
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/fftw/">
|
||||||
|
FFTW
|
||||||
|
</a>
|
||||||
|
.
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
<p>
|
<p>
|
||||||
|
|
@ -213,12 +226,255 @@ but it's certainly not possible to smoothly
|
||||||
integrate Modula-3 code into a C / C++ project.
|
integrate Modula-3 code into a C / C++ project.
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
<a name="conception"></a>
|
||||||
|
<a name="n3"></a><H2>18.2 Conception</H2>
|
||||||
|
|
||||||
|
|
||||||
|
<a name="cinterface"></a>
|
||||||
|
<a name="n4"></a><H3>18.2.1 Interfaces to C libraries</H3>
|
||||||
|
|
||||||
|
|
||||||
|
<p>
|
||||||
|
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
|
||||||
|
<a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
|
||||||
|
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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<table border>
|
||||||
|
<tr><th colspan=2>C library support integrated in Modula-3<th></tr>
|
||||||
|
<tr>
|
||||||
|
<td>Pragma <tt><* EXTERNAL *></tt></td>
|
||||||
|
<td>Precedes a declaration of a PROCEDURE that is implemented
|
||||||
|
in an external library instead of a Modula-3 implemenation.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Pragma <tt><* CALLBACK *></tt></td>
|
||||||
|
<td>Precedes a declaration of a PROCEDURE that should be called
|
||||||
|
by external library code.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Module <tt>Ctypes</tt></td>
|
||||||
|
<td>Contains Modula-3 types that match some basic C type.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Module <tt>M3toC</tt></td>
|
||||||
|
<td>Contains routines that convert between Modula-3's <tt>TEXT</tt> type
|
||||||
|
and C's <tt>char *</tt> type.</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
In each run of SWIG the Modula-3 part
|
||||||
|
generates several files:
|
||||||
|
</p>
|
||||||
|
<table border>
|
||||||
|
<tr>
|
||||||
|
<td>Module<tt>Raw.i3</tt></td>
|
||||||
|
<td>Declaration of types that are equivalent to those of the C library,
|
||||||
|
<tt>EXTERNAL</tt> of the C library functions</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Module<tt>Raw.m3</tt></td>
|
||||||
|
<td>Almost empty.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Module<tt>.i3</tt></td>
|
||||||
|
<td>Declaration of comfortable wrappers to the C library functions.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Module<tt>.m3</tt></td>
|
||||||
|
<td>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 <tt>WeakRef</tt>s
|
||||||
|
and raises exceptions.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><tt>m3makefile</tt></td>
|
||||||
|
<td>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 <tt>m3makefile</tt> in each run,
|
||||||
|
because SWIG must be started for each Modula-3 module it creates.
|
||||||
|
Thus the m3makefile is overwritten each time. :-(
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
Here's a scheme of how the function calls to Modula-3 wrappers
|
||||||
|
a redirected to C library functions:
|
||||||
|
<table>
|
||||||
|
<tr>
|
||||||
|
<td align=center>
|
||||||
|
Modula-3 wrapper<br>
|
||||||
|
Module<tt>.i3</tt><br>
|
||||||
|
generated by Modula-3 part of SWIG
|
||||||
|
</td>
|
||||||
|
<td></td>
|
||||||
|
<td align=center></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td align=center>
|
||||||
|
<!-- pre tag overrides centering -->
|
||||||
|
|<br>
|
||||||
|
v
|
||||||
|
</td>
|
||||||
|
<td></td>
|
||||||
|
<td align=center></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td align=center>
|
||||||
|
Modula-3 interface to C<br>
|
||||||
|
Module<tt>Raw.i3</tt><br>
|
||||||
|
generated by Modula-3 part of SWIG
|
||||||
|
</td>
|
||||||
|
<td>--></td>
|
||||||
|
<td align=center>
|
||||||
|
C library
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
|
||||||
|
<a name="cppinterface"></a>
|
||||||
|
<a name="n5"></a><H3>18.2.2 Interfaces to C++ libraries</H3>
|
||||||
|
|
||||||
|
|
||||||
|
<p>
|
||||||
|
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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
Here's a scheme of how the function calls to Modula-3 wrappers
|
||||||
|
a redirected to C library functions:
|
||||||
|
<table>
|
||||||
|
<tr>
|
||||||
|
<td align=center>
|
||||||
|
Modula-3 wrapper<br>
|
||||||
|
Module<tt>.i3</tt><br>
|
||||||
|
generated by Modula-3 part of SWIG
|
||||||
|
</td>
|
||||||
|
<td></td>
|
||||||
|
<td align=center>C++ library</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td align=center>
|
||||||
|
<!-- pre tag overrides centering -->
|
||||||
|
|<br>
|
||||||
|
v
|
||||||
|
</td>
|
||||||
|
<td></td>
|
||||||
|
<td align=center>
|
||||||
|
^<br>
|
||||||
|
|
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td align=center>
|
||||||
|
Modula-3 interface to C<br>
|
||||||
|
Module<tt>Raw.i3</tt><br>
|
||||||
|
generated by Modula-3 part of SWIG
|
||||||
|
</td>
|
||||||
|
<td>--></td>
|
||||||
|
<td align=center>
|
||||||
|
C interface to C++<br>
|
||||||
|
module<tt>_wrap.cxx</tt><br>
|
||||||
|
generated by the SWIG core
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Wrapping C++ libraries arises additional problems:
|
||||||
|
<ul>
|
||||||
|
<li>
|
||||||
|
Is it sensible to wrap C++ class with Modula-3 classes?
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
How to find the wrapping Modula-3 class
|
||||||
|
for a class pointer that is returned by a C++ routine?
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
How to deal with multiple inheritance
|
||||||
|
which was neglected for Modula-3 for good reasons?
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
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
|
||||||
|
<a href=Java.html#java_directors>Java</a> and
|
||||||
|
<a href=Python.html#directors>Python</a>.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
How to manage storage with the garbage collector of Modula-3?
|
||||||
|
Support for
|
||||||
|
<a href="Customization.html#ownership">
|
||||||
|
<tt>%newobject</tt> and <tt>%typemap(newfree)</tt></a>
|
||||||
|
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.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
How to turn C++ exceptions into Modula-3 exceptions?
|
||||||
|
There's also no support for
|
||||||
|
<a href="Customization.html#exception">
|
||||||
|
<tt>%exception</tt></a>, yet.
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<a name="cppinterface"></a>
|
||||||
|
<a name="n6"></a><H3>18.2.3 No plan?</H3>
|
||||||
|
|
||||||
|
|
||||||
|
<p>
|
||||||
|
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 <tt>Database</tt>,
|
||||||
|
it is good Modula-3 style to set up one Module with the name <tt>Database</tt>
|
||||||
|
where the database type is declared with the name <tt>T</tt>
|
||||||
|
and where all functions are declared that operates on it.
|
||||||
|
Thus Modules in Modula-3 are a kind of static classes.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
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 (<tt>%ignore</tt>)
|
||||||
|
and the principal type must be renamed (<tt>%typemap</tt>).
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
<a name="preliminaries"></a>
|
<a name="preliminaries"></a>
|
||||||
<a name="n3"></a><H2>18.2 Preliminaries</H2>
|
<a name="n7"></a><H2>18.3 Preliminaries</H2>
|
||||||
|
|
||||||
|
|
||||||
<a name="compilers"></a>
|
<a name="compilers"></a>
|
||||||
<a name="n4"></a><H3>18.2.1 Compilers</H3>
|
<a name="n8"></a><H3>18.3.1 Compilers</H3>
|
||||||
|
|
||||||
|
|
||||||
There are different Modula-3 compilers around:
|
There are different Modula-3 compilers around:
|
||||||
|
|
@ -227,16 +483,17 @@ SWIG itself does not contain compiler specific code
|
||||||
but the library file
|
but the library file
|
||||||
<a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
|
<a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
|
||||||
may do so.
|
may do so.
|
||||||
For testing examples I used Critical Mass' cm3.
|
For testing examples I used Critical Mass cm3.
|
||||||
|
|
||||||
|
|
||||||
<a name="commandline"></a>
|
<a name="commandline"></a>
|
||||||
<a name="n5"></a><H3>18.2.2 Additional Commandline Options</H3>
|
<a name="n9"></a><H3>18.3.2 Additional Commandline Options</H3>
|
||||||
|
|
||||||
|
|
||||||
There some experimental command line options
|
There are some experimental command line options
|
||||||
that prevent SWIG from generating interface files.
|
that prevent SWIG from generating interface files.
|
||||||
Instead files are emitted that may assist
|
Instead files are emitted that may assist you
|
||||||
writing SWIG interface files.
|
when writing SWIG interface files.
|
||||||
|
|
||||||
<table>
|
<table>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -247,7 +504,33 @@ writing SWIG interface files.
|
||||||
<td>-generateconst <file></td>
|
<td>-generateconst <file></td>
|
||||||
<td>
|
<td>
|
||||||
Disable generation of interfaces and wrappers.
|
Disable generation of interfaces and wrappers.
|
||||||
Instead generate code for computing numeric values of constants.
|
Instead write code for computing numeric values of constants
|
||||||
|
to the specified file.
|
||||||
|
<br>
|
||||||
|
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 <tt>(1 << FLAG_MAXIMIZEWINDOW)</tt>
|
||||||
|
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.
|
||||||
|
<br>
|
||||||
|
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.
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
|
|
||||||
|
|
@ -255,7 +538,17 @@ Instead generate code for computing numeric values of constants.
|
||||||
<td>-generaterename <file></td>
|
<td>-generaterename <file></td>
|
||||||
<td>
|
<td>
|
||||||
Disable generation of interfaces and wrappers.
|
Disable generation of interfaces and wrappers.
|
||||||
Instead generate suggestions for %rename.
|
Instead generate suggestions for <tt>%rename</tt>.
|
||||||
|
<br>
|
||||||
|
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 <tt>%rename</tt> directive.
|
||||||
|
This switch outputs a list of such directives
|
||||||
|
with a name suggestion generated by a simple heuristic.
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
|
|
||||||
|
|
@ -269,51 +562,291 @@ Instead generate templates for some basic typemaps.
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
<a name="typemaps"></a>
|
<a name="typemaps"></a>
|
||||||
<a name="n6"></a><H2>18.3 Modula-3 typemaps</H2>
|
<a name="n10"></a><H2>18.4 Modula-3 typemaps</H2>
|
||||||
|
|
||||||
|
|
||||||
<a name="inoutparam"></a>
|
<a name="inoutparam"></a>
|
||||||
<a name="n7"></a><H3>18.3.1 Inputs and outputs</H3>
|
<a name="n11"></a><H3>18.4.1 Inputs and outputs</H3>
|
||||||
|
|
||||||
|
|
||||||
|
<p>
|
||||||
Each C procedure has a bunch of inputs and outputs.
|
Each C procedure has a bunch of inputs and outputs.
|
||||||
Aside from global variables
|
Inputs are passed as function arguments,
|
||||||
inputs are passed as call arguments,
|
outputs are updated referential arguments and
|
||||||
outputs are updated reference arguments and
|
|
||||||
the function value.
|
the function value.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
Each C type can have several typemaps
|
Each C type can have several typemaps
|
||||||
that apply only in case the types are used
|
that apply only in case the types are used
|
||||||
as input argument, as output argument,
|
as input argument, as output argument,
|
||||||
or as return value.
|
or as return value.
|
||||||
A further typemap may specify
|
A further typemap may specify
|
||||||
the direction that is used for certain parameters.
|
the direction that is used for certain parameters.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
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<tt>.i3</tt> or the Module<tt>Raw.i3</tt>, 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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
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:
|
||||||
|
<ul>
|
||||||
|
<li>Generate <tt>PROCEDURE</tt> signature.</li>
|
||||||
|
<li>Declare local variables.</li>
|
||||||
|
<li>Convert input values from Modula-3 to C.</li>
|
||||||
|
<li>Check for input value integrity.</li>
|
||||||
|
<li>Call the C function.</li>
|
||||||
|
<li>Check returned values, e.g. error codes.</li>
|
||||||
|
<li>Convert and write back values into Modula-3 records.</li>
|
||||||
|
<li>Free temporary storage.</li>
|
||||||
|
<li>Return values.</li>
|
||||||
|
</ul>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<table border>
|
||||||
|
<tr>
|
||||||
|
<th>Typemap</th>
|
||||||
|
<th>Example</th>
|
||||||
|
<th>Description</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapargvar</td>
|
||||||
|
<td><tt>$1: Ptr := $1_name;</tt></td>
|
||||||
|
<td>
|
||||||
|
Declaration of some variables needed for temporary results.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapargraw</td>
|
||||||
|
<td><tt>ORD($1_name)</tt></td>
|
||||||
|
<td>
|
||||||
|
The expression that should be passed as argument to the raw Modula-3 interface function.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapargdir</td>
|
||||||
|
<td><tt>out</tt></td>
|
||||||
|
<td>
|
||||||
|
Referential arguments can be used for input, output, update.
|
||||||
|
???
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapinmode</td>
|
||||||
|
<td><tt>READONLY</tt></td>
|
||||||
|
<td>
|
||||||
|
One of Modula-3 parameter modes
|
||||||
|
<tt>VALUE</tt> (or empty),
|
||||||
|
<tt>VAR</tt>,
|
||||||
|
<tt>READONLY</tt>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapinname</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
New name of the input argument.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapintype</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
Modula-3 type of the input argument.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapindefault</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
Default value of the input argument
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapinconv</td>
|
||||||
|
<td><tt>$1 := M3toC.SharedTtoS($1_name);</tt></td>
|
||||||
|
<td>
|
||||||
|
Statement for converting the Modula-3 input value to C compliant value.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapincheck</td>
|
||||||
|
<td><tt>IF Text.Length($1_name) > 10 THEN RAISE E("str too long"); END;</tt></td>
|
||||||
|
<td>
|
||||||
|
Check the integrity of the input value.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapoutname</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
Name of the <tt>RECORD</tt> field to be used for returning multiple values.
|
||||||
|
This applies to referential output arguments that shall be turned
|
||||||
|
into return values.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapouttype</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
Type of the value that is returned instead of a referential output argument.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapoutconv</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapoutcheck</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapretraw</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapretname</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wraprettype</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapretvar</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapretconv</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapretcheck</td>
|
||||||
|
<td><tt></tt></td>
|
||||||
|
<td>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>m3wrapfreearg</td>
|
||||||
|
<td><tt>M3toC.FreeSharedS(str,arg1);</tt></td>
|
||||||
|
<td>
|
||||||
|
Free resources that were temporarily used in the wrapper.
|
||||||
|
Since this step should never be skipped,
|
||||||
|
SWIG will put it in the <tt>FINALLY</tt> branch
|
||||||
|
of a <tt>TRY .. FINALLY</tt> structure.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
|
||||||
|
<a name="ordinals"></a>
|
||||||
|
<a name="n12"></a><H3>18.4.2 Subranges, Enumerations, Sets</H3>
|
||||||
|
|
||||||
|
|
||||||
|
<a name="class"></a>
|
||||||
|
<a name="n13"></a><H3>18.4.3 Objects</H3>
|
||||||
|
|
||||||
|
|
||||||
|
<a name="imports"></a>
|
||||||
|
<a name="n14"></a><H3>18.4.4 Imports</H3>
|
||||||
|
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Pieces of Modula-3 code provided by typemaps
|
||||||
|
may contain identifiers from foreign modules.
|
||||||
|
If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt>
|
||||||
|
contains code using the function <tt>M3toC.SharedTtoS</tt>
|
||||||
|
you may declare <tt>%typemap("m3wrapinconv:import") blah * %{M3toC%}</tt>.
|
||||||
|
Then the module <tt>M3toC</tt> is imported
|
||||||
|
if the <tt>m3wrapinconv</tt> typemap for <tt>blah *</tt>
|
||||||
|
is used at least once.
|
||||||
|
Use <tt>%typemap("m3wrapinconv:import") blah * %{MyConversions AS M3toC%}</tt>
|
||||||
|
if you need module renaming.
|
||||||
|
Unqualified import is not supported.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
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
|
||||||
|
<a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
|
||||||
|
.
|
||||||
|
For a monolithic module you might be better off
|
||||||
|
if you add the imports directly:
|
||||||
|
<pre>
|
||||||
|
%insert(m3rawintf) %{
|
||||||
|
IMPORT M3toC;
|
||||||
|
%}
|
||||||
|
</pre>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
<a name="exceptions"></a>
|
<a name="exceptions"></a>
|
||||||
<a name="n8"></a><H3>18.3.2 Exceptions</H3>
|
<a name="n15"></a><H3>18.4.5 Exceptions</H3>
|
||||||
|
|
||||||
|
|
||||||
Modula-3 provides another possibility
|
Modula-3 provides another possibility
|
||||||
of an output of a function: exceptions.
|
of an output of a function: exceptions.
|
||||||
|
|
||||||
Any piecec of Modula-3 code that SWIG inserts
|
Any piece of Modula-3 code that SWIG inserts
|
||||||
due to a typemap can raise an exception.
|
due to a typemap can raise an exception.
|
||||||
This way you can also convert an error code
|
This way you can also convert an error code
|
||||||
from a C function into an Modula-3 exception.
|
from a C function into an Modula-3 exception.
|
||||||
|
|
||||||
The <tt>RAISES</tt> clause is controlled
|
The <tt>RAISES</tt> clause is controlled
|
||||||
by typemaps with the <tt>except</tt> extension.
|
by typemaps with the <tt>except</tt> extension.
|
||||||
|
If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt>
|
||||||
|
contains code that may raise the exceptions <tt>OSError.E</tt>
|
||||||
|
you should declare
|
||||||
|
<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>.
|
||||||
|
|
||||||
<a name="ordinals"></a>
|
<a name="swig_pragmas"></a>
|
||||||
<a name="n9"></a><H3>18.3.3 Subranges, Enumerations, Sets</H3>
|
<a name="n16"></a><H3>18.4.6 Pragmas</H3>
|
||||||
|
|
||||||
|
|
||||||
<a name="class"></a>
|
<table border>
|
||||||
<a name="n10"></a><H3>18.3.4 Objects</H3>
|
<tr>
|
||||||
|
<td>unsafe</td>
|
||||||
|
<td><tt>%pragma(modula3) unsafe="true";</tt></td>
|
||||||
|
<td>Mark the raw interface modules as <tt>UNSAFE</tt>.
|
||||||
|
This will be necessary in many cases.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>library</td>
|
||||||
|
<td><tt>%pragma(modula3) library="m3fftw";</tt></td>
|
||||||
|
<td>Specifies the library name for the wrapper library to be created.
|
||||||
|
It should be distinct from the name of the library to be wrapped.</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<a name="typemap_example"></a>
|
||||||
<a name="typemap_examlpe"></a>
|
<a name="n17"></a><H3>18.4.7 Example</H3>
|
||||||
<a name="n11"></a><H3>18.3.5 Example</H3>
|
|
||||||
|
|
||||||
|
|
||||||
The generation of wrappers in Modula-3 needs very fine control
|
The generation of wrappers in Modula-3 needs very fine control
|
||||||
|
|
@ -355,6 +888,17 @@ where almost everything is generated by a typemap:
|
||||||
END Name;
|
END Name;
|
||||||
</pre></blockquote>
|
</pre></blockquote>
|
||||||
|
|
||||||
|
<a name="remarks"></a>
|
||||||
|
<a name="n18"></a><H3>18.4.8 Remarks</H3>
|
||||||
|
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>
|
||||||
|
The Modula-3 part of SWIG doesn't try to generate nicely formatted code.
|
||||||
|
Use <tt>m3pp</tt> to postprocess the Modula files,
|
||||||
|
it does a very good job here.
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
</body>
|
</body>
|
||||||
</html>
|
</html>
|
||||||
|
|
@ -1909,6 +1909,7 @@ of static member functions. In Python-2.2, they can be accessed via the
|
||||||
class itself. In Python-2.1 and earlier, they have to be accessed as a global
|
class itself. In Python-2.1 and earlier, they have to be accessed as a global
|
||||||
function or through an instance (see the earlier section).
|
function or through an instance (see the earlier section).
|
||||||
|
|
||||||
|
<a name="directors">
|
||||||
<a name="n32"></a><H2>22.5 Cross language polymorphism (experimental)</H2>
|
<a name="n32"></a><H2>22.5 Cross language polymorphism (experimental)</H2>
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -96,6 +96,8 @@ char cvsroot_modula3_cxx[] =
|
||||||
- Is there a function that creates a C representation of a SWIG type string?
|
- Is there a function that creates a C representation of a SWIG type string?
|
||||||
|
|
||||||
ToDo:
|
ToDo:
|
||||||
|
- create WeakRefs only for resources returned by function marked with %newobject
|
||||||
|
-> part of output conversion
|
||||||
- clean typemap conception
|
- clean typemap conception
|
||||||
- should a multi-typemap for m3wrapouttype skip the corresponding input parameters?
|
- should a multi-typemap for m3wrapouttype skip the corresponding input parameters?
|
||||||
when yes - How to handle inout-arguments? In this case like in-argument.
|
when yes - How to handle inout-arguments? In this case like in-argument.
|
||||||
|
|
@ -3431,7 +3433,7 @@ MODULA3 ():
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/* Create local variables e.g. for converted input values. */
|
/* Declare local variables e.g. for converted input values. */
|
||||||
{
|
{
|
||||||
String *tm = getMappedTypeNew (n, "m3wrapretvar", "", false);
|
String *tm = getMappedTypeNew (n, "m3wrapretvar", "", false);
|
||||||
if (tm != NIL) {
|
if (tm != NIL) {
|
||||||
|
|
@ -3461,7 +3463,7 @@ MODULA3 ():
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/* Converted input values from Modula 3 to C. */
|
/* Convert input values from Modula 3 to C. */
|
||||||
{
|
{
|
||||||
Parm *p = l;
|
Parm *p = l;
|
||||||
while (p != NIL) {
|
while (p != NIL) {
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue