jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clean up the Modula-3 docs a bit. Refocus the introduction on matters that

Browse source 
people reading it will actually want to know.


git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@12043 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Olly Betts 2010-05-23 04:58:40 +00:00
commit a363a0361b
1 changed files with 35 additions and 158 deletions
Download patch file Download diff file Expand all files Collapse all files

193
Doc/Manual/Modula3.html
View file

@ -11,10 +11,7 @@
<ul> <ul>
<li><a href="#Modula3_modula3_overview">Overview</a> <li><a href="#Modula3_modula3_overview">Overview</a>
<ul> <ul>
<li><a href="#Modula3_whyscripting">Why not scripting ?</a> <li><a href="#Modula3_motivation">Motivation</a>
<li><a href="#Modula3_whymodula3">Why Modula-3 ?</a>
<li><a href="#Modula3_whycpp">Why C / C++ ?</a>
<li><a href="#Modula3_whyswig">Why SWIG ?</a>
</ul> </ul>
<li><a href="#Modula3_conception">Conception</a> <li><a href="#Modula3_conception">Conception</a>
<ul> <ul>
@ -49,7 +46,7 @@
<p> <p>
This chapter describes SWIG's support of This chapter describes SWIG's support of
<a href="http://www.m3.org/">Modula-3</a>. <a href="http://modula3.org/">Modula-3</a>.
You should be familiar with the You should be familiar with the
<a href="SWIG.html#SWIG">basics</a> <a href="SWIG.html#SWIG">basics</a>
of SWIG, of SWIG,
@ -59,14 +56,18 @@ especially
<H2><a name="Modula3_modula3_overview"></a>24.1 Overview</H2> <H2><a name="Modula3_modula3_overview"></a>24.1 Overview</H2>
<p>
Modula-3 is a compiled language in the tradition of Niklaus Wirth's Modula 2,
which is in turn a successor to Pascal.
</p>
<p> <p>
The Modula-3 support is very basic and highly experimental! SWIG's Modula-3 support is currently 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.
Don't rely on any feature, incompatible changes are likely in the future! Don't rely on any feature, incompatible changes are likely in the future!
The Modula-3 generator was already useful for interfacing However, the Modula-3 generator was already useful for interfacing
to the libraries to the libraries:
</p> </p>
<ol> <ol>
@ -78,130 +79,33 @@ PLPlot
<li> <li>
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/fftw/"> <a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/fftw/">
FFTW FFTW
</a> . </a>
</li> </li>
</ol> </ol>
<H3><a name="Modula3_motivation"></a>24.1.3 Motivation</H3>
<p> <p>
I took some more time to explain Although it is possible to write Modula-3 code that performs as well as C/C++
why I think it's right what I'm doing. most existing libraries are not written in Modula-3 but in C or C++, and
So the introduction got a bit longer than it should ... ;-) even libraries in other languages may provide C header files.
</p>
<H3><a name="Modula3_whyscripting"></a>24.1.1 Why not scripting ?</H3>
<p>
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.
</p> </p>
<p> <p>
Besides C, C++, Cluster (a Modula derivate for Amiga computers) Fortunately Modula-3 can call C functions, but you have to write Modula-3
I evaluated several scripting like languages in the past: interfaces to them, and to make things comfortable you will also need
Different dialects of BASIC, wrappers that convert between high-level features of Modula-3 (garbage
Perl, ARexx (a variant of Rexx for Amiga computers), collecting, exceptions) and the explicit tracking of allocated memory and
shell scripts. exception codes used by C APIs.
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.
</p>
<H3><a name="Modula3_whymodula3"></a>24.1.2 Why Modula-3 ?</H3>
<p>
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.
</p> </p>
<p> <p>
On the one hand Modula-3 can be safe SWIG converts C headers to Modula-3 interfaces for you, and using typemaps
(but probably less efficient) in normal modules you can pass <tt>TEXT</tt>s or open arrays, and convert error return codes
while providing much static and dynamic safety. into exceptions.
On the other hand you can write efficient
but less safe code in the style of C
within <tt>UNSAFE</tt> modules.
</p> </p>
<p> <p>
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.
</p>
<H3><a name="Modula3_whycpp"></a>24.1.3 Why C / C++ ?</H3>
<p>
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.
</p>
<H3><a name="Modula3_whyswig"></a>24.1.4 Why SWIG ?</H3>
<p>
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.
</p>
<p>
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 <tt>TEXT</tt>s
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 If the library API is ill designed
writing appropriate typemaps can be still time-consuming. writing appropriate typemaps can be still time-consuming.
E.g. C programmers are very creative to work-around E.g. C programmers are very creative to work-around
@ -211,47 +115,20 @@ otherwise you lose static safety and consistency.
</p> </p>
<p> <p>
Without SWIG you would probably never consider trying to call C++ libraries
But you have still a problem: from Modula-3, but with SWIG this is becomes feasible.
C library interfaces are often ill. SWIG can generate C wrappers to C++ functions and object methods
They lack for certain information that may throw exceptions, and then wrap these C wrappers for Module-3.
because C compilers wouldn't care about. To make it complete you can then hide the C interface with Modula-3 classes and
You should integrate detailed type information exceptions.
by adding <tt>typedef</tt>s and <tt>const</tt>s
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 <b>good</b> SWIG interfaces
is very costly and it will only amortise
when considering evolving libraries.
</p>
<p>
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.
</p> </p>
<p> <p>
Although SWIG does the best it can do SWIG allows you to call C and C++ libraries from Modula-3 (even with call back
it can only serve as a one-way strategy. functions), but it doesn't allow you to easily integrate a Module-3 module into
That means you can use C++ libraries a C/C++ project.
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.
</p> </p>
<H2><a name="Modula3_conception"></a>24.2 Conception</H2> <H2><a name="Modula3_conception"></a>24.2 Conception</H2>
@ -259,7 +136,7 @@ integrate Modula-3 code into a C / C++ project.
<p> <p>
Modula-3 has an integrated support for calling C functions. Modula-3 has integrated support for calling C functions.
This is also extensively used by the standard Modula-3 libraries This is also extensively used by the standard Modula-3 libraries
to call OS functions. to call OS functions.
The Modula-3 part of SWIG and the corresponding SWIG library The Modula-3 part of SWIG and the corresponding SWIG library
@ -417,7 +294,7 @@ with a C interface.
<p> <p>
Here's a scheme of how the function calls to Modula-3 wrappers Here's a scheme of how the function calls to Modula-3 wrappers
a redirected to C library functions: are redirected to C library functions:
</p> </p>
<table summary="Modula-3 C++ library"> <table summary="Modula-3 C++ library">
@ -1058,8 +935,8 @@ where almost everything is generated by a typemap:
<ul> <ul>
<li> <li>
The Modula-3 part of SWIG doesn't try to generate nicely formatted code. The Modula-3 part of SWIG doesn't try to generate nicely formatted code.
Use <tt>m3pp</tt> to postprocess the Modula files, If you need to read the generated code, use <tt>m3pp</tt> to postprocess the
it does a very good job here. Modula files.
</li> </li>
</ul> </ul>