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

merge from trunk

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2009-sploving@11821 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Baozeng Ding 2010-01-11 00:59:12 +00:00
commit d8a371808a
190 changed files with 5425 additions and 2040 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Doc/Manual/Allegrocl.html
View file

@ -14,7 +14,7 @@
<ul>
<li><a href="#Allegrocl_nn2">Basics</a>
<ul>
<li><a href="#Allegrocl_nn3">Running Swig</a>
<li><a href="#Allegrocl_nn3">Running SWIG</a>
<li><a href="#Allegrocl_nn4">Command Line Options</a>
<li><a href="#Allegrocl_nn5">Inserting user code into generated files</a>
</ul>
@ -138,7 +138,7 @@ to it.
<H2><a name="Allegrocl_nn2"></a>17.1 Basics</H2>
<H3><a name="Allegrocl_nn3"></a>17.1.1 Running Swig</H3>
<H3><a name="Allegrocl_nn3"></a>17.1.1 Running SWIG</H3>
<p>

2
Doc/Manual/Arguments.html
View file

@ -30,8 +30,6 @@
<b>Disclaimer: This chapter is under construction.</b>
<p>
In Chapter 3, SWIG's treatment of basic datatypes and pointers was
described. In particular, primitive types such as <tt>int</tt> and

47
Doc/Manual/CSharp.html
View file

@ -55,7 +55,7 @@ The PInvoke interface has been chosen over Microsoft's Managed C++ interface as
PInvoke is part of the ECMA/ISO C# specification.
It is also better suited for robust production environments due to the Managed C++ flaw called the
<a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_vstechart/html/vcconMixedDLLLoadingProblem.asp">Mixed DLL Loading Problem</a>.
Swig C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using
SWIG C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using
<a href="http://www.mono-project.com/">Mono</a> and <a href="http://www.dotgnu.org/pnet.html">Portable.NET</a>.
</p>
@ -249,7 +249,9 @@ public static extern IntPtr function(string jarg1);
<p>
Support for type attributes.
The 'imtype' and 'cstype' typemaps can have an optional <tt>inattributes</tt> and <tt>outattributes</tt> typemap attribute.
There are C# attributes and typemap attributes, don't get confused!!
The 'imtype' typemap can also have an optional <tt>directorinattributes</tt> and <tt>directoroutattributes</tt>
typemap attribute which attaches to director delegates, an implementation detail of directors, see <a href="#csharp_directors_implementation">directors implementation</a>.
Note that there are C# attributes and typemap attributes, don't get confused between the two!!
The C# attributes specified in these typemap attributes are generated wherever the type is used in the C# wrappers.
These can be used to specify any C# attribute associated with a C/C++ type, but are more typically used for the C# <tt>MarshalAs</tt> attribute.
For example:
@ -293,11 +295,16 @@ These attributes are associated with the C/C++ parameter type or return type, wh
the attribute features and typemaps covered next.
Note that all these different C# attributes can be combined so that a method has more than one attribute.
</p>
<p>
The <tt>directorinattributes</tt> and <tt>directoroutattributes</tt> typemap attribute are attached to the delegates in the director class, for example, the SwigDelegateBase_0
</p>
</li>
<li>
<p>
Support for attaching C# attributes to wrapped methods and variables.
Support for attaching C# attributes to wrapped methods, variables and enum values.
This is done using the <tt>%csattributes</tt> feature, see <a href="Customization.html#features">%feature directives</a>.
Note that C# attributes are attached to proxy classes and enums using the <tt>csattributes</tt> typemap.
For example, imagine we have a custom attribute class, <tt>ThreadSafeAttribute</tt>, for labelling thread safety.
@ -344,6 +351,38 @@ they can be added using the 'csvarin' and 'csvarout' typemaps respectively.
Note that the type used for the property is specified in the 'cstype' typemap.
If the 'out' attribute exists in this typemap, then the type used is from the 'out' attribute.
</p>
<p>
An example for attaching attributes to the enum and enum values is shown below.
</p>
<div class="code">
<pre>
%typemap(csattributes) Couleur "[System.ComponentModel.Description(\"Colours\")]"
%csattributes Rouge "[System.ComponentModel.Description(\"Red\")]"
%csattributes Vert "[System.ComponentModel.Description(\"Green\")]"
%inline %{
enum Couleur { Rouge, Orange, Vert };
%}
</pre>
</div>
<p>
which will result in the following C# enum:
</p>
<div class="code">
<pre>
[System.ComponentModel.Description("Colours")]
public enum Couleur {
[System.ComponentModel.Description("Red")]
Rouge,
Orange,
[System.ComponentModel.Description("Green")]
Vert
}
</pre>
</div>
</li>
<li>
@ -948,7 +987,7 @@ without setting the <tt>canthrow</tt> attribute you will get a warning message s
<div class="code">
<pre>
example.i:21: Warning(845): Unmanaged code contains a call to a SWIG_CSharpSetPendingException
example.i:21: Warning 845: Unmanaged code contains a call to a SWIG_CSharpSetPendingException
method and C# code does not handle pending exceptions via the canthrow attribute.
</pre>
</div>

24
Doc/Manual/Contents.html
View file

@ -346,10 +346,11 @@
<li><a href="Typemaps.html#Typemaps_pattern_matching">Pattern matching rules</a>
<ul>
<li><a href="Typemaps.html#Typemaps_nn17">Basic matching rules</a>
<li><a href="Typemaps.html#Typemaps_nn18">Typedef reductions</a>
<li><a href="Typemaps.html#Typemaps_typedef_reductions">Typedef reductions</a>
<li><a href="Typemaps.html#Typemaps_nn19">Default typemaps</a>
<li><a href="Typemaps.html#Typemaps_mixed_default">Mixed default typemaps</a>
<li><a href="Typemaps.html#Typemaps_nn20">Multi-arguments typemaps</a>
<li><a href="Typemaps.html#Typemaps_debugging_search">Debugging typemap pattern matching</a>
</ul>
<li><a href="Typemaps.html#Typemaps_nn21">Code generation rules</a>
<ul>
@ -383,7 +384,7 @@
<li><a href="Typemaps.html#Typemaps_nn40">Typemaps for arrays</a>
<li><a href="Typemaps.html#Typemaps_nn41">Implementing constraints with typemaps</a>
</ul>
<li><a href="Typemaps.html#Typemaps_nn43">Typemaps for multiple languages</a>
<li><a href="Typemaps.html#Typemaps_nn43">Typemaps for multiple target languages</a>
<li><a href="Typemaps.html#Typemaps_optimal">Optimal code generation when returning by value</a>
<li><a href="Typemaps.html#Typemaps_multi_argument_typemaps">Multi-argument typemaps</a>
<li><a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>
@ -537,7 +538,7 @@
<ul>
<li><a href="Allegrocl.html#Allegrocl_nn2">Basics</a>
<ul>
<li><a href="Allegrocl.html#Allegrocl_nn3">Running Swig</a>
<li><a href="Allegrocl.html#Allegrocl_nn3">Running SWIG</a>
<li><a href="Allegrocl.html#Allegrocl_nn4">Command Line Options</a>
<li><a href="Allegrocl.html#Allegrocl_nn5">Inserting user code into generated files</a>
</ul>
@ -1280,9 +1281,6 @@
<li><a href="Python.html#Python_nn47">Simple pointers</a>
<li><a href="Python.html#Python_nn48">Unbounded C Arrays</a>
<li><a href="Python.html#Python_nn49">String handling</a>
<li><a href="Python.html#Python_nn50">Arrays</a>
<li><a href="Python.html#Python_nn51">String arrays</a>
<li><a href="Python.html#Python_nn52">STL wrappers</a>
</ul>
<li><a href="Python.html#Python_nn53">Typemaps</a>
<ul>
@ -1581,7 +1579,7 @@
<li><a href="Extending.html#Extending_nn31">Writing a Language Module</a>
<ul>
<li><a href="Extending.html#Extending_nn32">Execution model</a>
<li><a href="Extending.html#Extending_nn33">Starting out</a>
<li><a href="Extending.html#Extending_starting_out">Starting out</a>
<li><a href="Extending.html#Extending_nn34">Command line options</a>
<li><a href="Extending.html#Extending_nn35">Configuration and preprocessing</a>
<li><a href="Extending.html#Extending_nn36">Entry point to code generation</a>
@ -1590,16 +1588,18 @@
<li><a href="Extending.html#Extending_nn39">Configuration files</a>
<li><a href="Extending.html#Extending_nn40">Runtime support</a>
<li><a href="Extending.html#Extending_nn41">Standard library files</a>
<li><a href="Extending.html#Extending_nn42">Examples and test cases</a>
<li><a href="Extending.html#Extending_nn42">User examples</a>
<li><a href="Extending.html#Extending_test_suite">Test driven development and the test-suite</a>
<ul>
<li><a href="Extending.html#Extending_running_test_suite">Running the test-suite</a>
</ul>
<li><a href="Extending.html#Extending_nn43">Documentation</a>
<li><a href="Extending.html#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
<li><a href="Extending.html#Extending_coding_style_guidelines">Coding style guidelines</a>
</ul>
<li><a href="Extending.html#Extending_nn44">Typemaps</a>
<ul>
<li><a href="Extending.html#Extending_nn45">Proxy classes</a>
</ul>
<li><a href="Extending.html#Extending_debugging_options">Debugging Options</a>
<li><a href="Extending.html#Extending_nn46">Guide to parse tree nodes</a>
<li><a href="Extending.html#Extending_further_info">Further Development Information</a>
</ul>
</div>
<!-- INDEX -->

17
Doc/Manual/Customization.html
View file

@ -53,6 +53,21 @@ The <tt>%exception</tt> directive allows you to define a general purpose excepti
handler. For example, you can specify the following:
</p>
<div class="code"><pre>
%exception {
try {
$action
}
catch (RangeError) {
... handle error ...
}
}
</pre></div>
<p>
How the exception is handled depends on the target language, for example, Python:
</p>
<div class="code"><pre>
%exception {
try {
@ -60,7 +75,7 @@ handler. For example, you can specify the following:
}
catch (RangeError) {
PyErr_SetString(PyExc_IndexError,"index out-of-bounds");
return NULL;
SWIG_fail;
}
}
</pre></div>

310
Doc/Manual/Extending.html
View file

@ -48,7 +48,7 @@
<li><a href="#Extending_nn31">Writing a Language Module</a>
<ul>
<li><a href="#Extending_nn32">Execution model</a>
<li><a href="#Extending_nn33">Starting out</a>
<li><a href="#Extending_starting_out">Starting out</a>
<li><a href="#Extending_nn34">Command line options</a>
<li><a href="#Extending_nn35">Configuration and preprocessing</a>
<li><a href="#Extending_nn36">Entry point to code generation</a>
@ -57,16 +57,18 @@
<li><a href="#Extending_nn39">Configuration files</a>
<li><a href="#Extending_nn40">Runtime support</a>
<li><a href="#Extending_nn41">Standard library files</a>
<li><a href="#Extending_nn42">Examples and test cases</a>
<li><a href="#Extending_nn42">User examples</a>
<li><a href="#Extending_test_suite">Test driven development and the test-suite</a>
<ul>
<li><a href="#Extending_running_test_suite">Running the test-suite</a>
</ul>
<li><a href="#Extending_nn43">Documentation</a>
<li><a href="#Extending_prerequisites">Prerequisites for adding a new language module to the SWIG distribution</a>
<li><a href="#Extending_coding_style_guidelines">Coding style guidelines</a>
</ul>
<li><a href="#Extending_nn44">Typemaps</a>
<ul>
<li><a href="#Extending_nn45">Proxy classes</a>
</ul>
<li><a href="#Extending_debugging_options">Debugging Options</a>
<li><a href="#Extending_nn46">Guide to parse tree nodes</a>
<li><a href="#Extending_further_info">Further Development Information</a>
</ul>
</div>
<!-- INDEX -->
@ -2471,7 +2473,7 @@ the parsing of command line options, all aspects of code generation are controll
different methods of the <tt>Language</tt> that must be defined by your module.
</p>
<H3><a name="Extending_nn33"></a>35.10.2 Starting out</H3>
<H3><a name="Extending_starting_out"></a>35.10.2 Starting out</H3>
<p>
@ -2602,24 +2604,24 @@ void Language::main(int argc, char *argv[]) {
} else {
Swig_arg_error();
}
} else if (strcmp(argv[i],"-globals") == 0) {
if (argv[i+1]) {
global_name = NewString(argv[i+1]);
Swig_mark_arg(i);
Swig_mark_arg(i+1);
i++;
} else {
Swig_arg_error();
}
} else if ( (strcmp(argv[i],"-proxy") == 0)) {
proxy_flag = 1;
Swig_mark_arg(i);
} else if (strcmp(argv[i],"-keyword") == 0) {
use_kw = 1;
Swig_mark_arg(i);
} else if (strcmp(argv[i],"-help") == 0) {
fputs(usage,stderr);
}
} else if (strcmp(argv[i],"-globals") == 0) {
if (argv[i+1]) {
global_name = NewString(argv[i+1]);
Swig_mark_arg(i);
Swig_mark_arg(i+1);
i++;
} else {
Swig_arg_error();
}
} else if ( (strcmp(argv[i],"-proxy") == 0)) {
proxy_flag = 1;
Swig_mark_arg(i);
} else if (strcmp(argv[i],"-keyword") == 0) {
use_kw = 1;
Swig_mark_arg(i);
} else if (strcmp(argv[i],"-help") == 0) {
fputs(usage,stderr);
}
...
}
}
@ -3053,7 +3055,7 @@ but without the typemaps, there is still work to do.
<!-- please report bugs in this section to ttn -->
<p>
At the time of this writing, SWIG supports nearly a dozen languages,
At the time of this writing, SWIG supports nearly twenty languages,
which means that for continued sanity in maintaining the configuration
files, the language modules need to follow some conventions. These are
outlined here along with the admission that, yes it is ok to violate
@ -3225,7 +3227,7 @@ The following are the minimum that are usually supported:
Please copy these and modify for any new language.
</p>
<H3><a name="Extending_nn42"></a>35.10.11 Examples and test cases</H3>
<H3><a name="Extending_nn42"></a>35.10.11 User examples</H3>
<p>
@ -3254,7 +3256,226 @@ during this process, see the section on <a href="#n37a">configuration
files</a>.
</p>
<H3><a name="Extending_nn43"></a>35.10.12 Documentation</H3>
<H3><a name="Extending_test_suite"></a>35.10.12 Test driven development and the test-suite</H3>
<p>
A test driven development approach is central to the improvement and development of SWIG.
Most modifications to SWIG are accompanied by additional regression tests and checking all
tests to ensure that no regressions have been introduced.
</p>
<p>
The regression testing is carried out by the SWIG <i>test-suite</i>.
The test-suite consists of numerous testcase interface files in the <tt>Examples/test-suite</tt> directory
as well as target language specific runtime tests in the <tt>Examples/test-suite/[lang]</tt> directory.
When a testcase is run, it will execute the following steps for each testcase:
</p>
<ol>
<li>Execute SWIG passing it the testcase interface file.</li>
<li>Compile the resulting generated C/C++ code with either the C or C++ compiler into object files.</li>
<li>Link the object files into a dynamic library (dll/shared object).</li>
<li>Compile any generated and any runtime test target language code with the target language compiler, if the target language supports compilation. This step thus does not apply to the interpreted languages.</li>
<li>Execute a runtime test if one exists.</li>
</ol>
<p>
For example, the <i>ret_by_value</i> testcase consists of two components.
The first component is the <tt>Examples/test-suite/ret_by_value.i</tt> interface file.
The name of the SWIG module <b>must</b> always be the name of the testcase, so the <tt>ret_by_value.i</tt> interface file thus begins with:
</p>
<div class="code">
<pre>
%module ret_by_value
</pre>
</div>
<p>
The testcase code will then follow the module declaration,
usually within a <tt>%inline %{ ... %}</tt> section for the majority of the tests.
</p>
<p>
The second component is the optional runtime tests.
Any runtime tests are named using the following convention: <tt>[testcase]_runme.[ext]</tt>,
where <tt>[testcase]</tt> is the testcase name and <tt>[ext]</tt> is the normal extension for the target language file.
In this case, the Java and Python target languages implement a runtime test, so their files are respectively,
<tt>Examples/test-suite/java/ret_by_value_runme.java</tt> and
<tt>Examples/test-suite/python/ret_by_value_runme.py</tt>.
</p>
<p>
The goal of the test-suite is to test as much as possible in a <b>silent</b> manner.
This way any SWIG or compiler errors or warnings are easily visible.
Should there be any warnings, changes must be made to either fix them (preferably) or suppress them.
Compilation or runtime errors result in a testcase failure and will be immediately visible.
It is therefore essential that the runtime tests are written in a manner that displays nothing to stdout/stderr on success
but error/exception out with an error message on stderr on failure.
</p>
<H4><a name="Extending_running_test_suite"></a>35.10.12.1 Running the test-suite</H4>
<p>
In order for the test-suite to work for a particular target language, the language must be correctly detected
and configured during the configure stage so that the correct Makefiles are generated.
Most development occurs on Linux, so usually it is a matter of installing the development packages for the target language
and simply configuring as outlined <a href="#Extending_starting_out">earlier</a>.
</p>
<p>
If when running the test-suite commands that follow, you get a message that the test was skipped, it indicates that the
configure stage is missing information in order to compile and run everything for that language.
</p>
<p>
The test-suite can be run in a number of ways.
The first group of commands are for running multiple testcases in one run and should be executed in the top level directory.
To run the entire test-suite (can take a long time):
</p>
<div class="shell"><pre>
make -k check-test-suite
</pre></div>
<p>
To run the test-suite just for target language [lang], replace [lang] with one of csharp, java, perl5, python, ruby, tcl etc:
</p>
<div class="shell"><pre>
make check-[lang]-test-suite
</pre></div>
<p>
Note that if a runtime test is available, a message "(with run test)" is displayed when run. For example:
</p>
<div class="shell"><pre>
$ make check-python-test-suite
checking python test-suite
checking testcase argcargvtest (with run test) under python
checking testcase python_autodoc under python
checking testcase python_append (with run test) under python
checking testcase callback (with run test) under python
</pre></div>
<p>
The files generated on a previous run can be deleted using the clean targets, either the whole test-suite or for a particular language:
</p>
<div class="shell"><pre>
make clean-test-suite
make clean-[lang]-test-suite
</pre></div>
<p>
The test-suite can be run in a <i>partialcheck</i> mode where just SWIG is executed, that is, the compile,
link and running of the testcases is not performed.
Note that the partialcheck does not require the target language to be correctly configured and detected and unlike the other test-suite make targets, is never skipped. Once again, either all the languages can be executed or just a chosen language:
</p>
<div class="shell"><pre>
make partialcheck-test-suite
make partialcheck-[lang]-test-suite
</pre></div>
<p>
If your computer has more than one CPU, you are strongly advised to use parallel make to speed up the execution speed.
This can be done with any of the make targets that execute more than one testcase.
For example, a dual core processor can efficiently use 2 parallel jobs:
</p>
<div class="shell"><pre>
make -j2 check-test-suite
make -j2 check-python-test-suite
make -j2 partialcheck-java-test-suite
</pre></div>
<p>
The second group of commands are for running individual testcases and should be executed in the appropriate
target language directory, <tt>Examples/test-suite/[lang]</tt>.
Testcases can contain either C or C++ code and when one is written, a decision must be made as to which of these input
languages is to be used.
Replace <tt>[testcase]</tt> in the commands below with the name of the testcase.
</p>
<p>
For a C language testcase, add the testcase under the C_TEST_CASES list in <tt>Examples/test-suite/common.mk</tt> and
execute individually as:
</p>
<div class="shell"><pre>
make -s [testcase].ctest
</pre></div>
<p>
For a C++ language testcase, add the testcase under the CPP_TEST_CASES list in <tt>Examples/test-suite/common.mk</tt> and
execute individually as:
</p>
<div class="shell"><pre>
make -s [testcase].cpptest
</pre></div>
<p>
A third category of tests are C++ language testcases testing multiple modules (the %import directive).
These require more than one shared library (dll/shared object) to be built and so are separated out from the normal C++ testcases.
Add the testcase under the MULTI_CPP_TEST_CASES list in <tt>Examples/test-suite/common.mk</tt> and
execute individually as:
</p>
<div class="shell"><pre>
make -s [testcase].multicpptest
</pre></div>
<p>
To delete the generated files, execute:
</p>
<div class="shell"><pre>
make -s [testcase].clean
</pre></div>
<p>
If you would like to see the exact commands being executed, drop the -s option:
</p>
<div class="shell"><pre>
make [testcase].ctest
make [testcase].cpptest
make [testcase].multicpptest
</pre></div>
<p>
Some real examples of each:
</p>
<div class="shell"><pre>
make -s ret_by_value.clean
make -s ret_by_value.ctest
make -s bools.cpptest
make -s imports.multicpptest
</pre></div>
<p>
Advanced usage of the test-suite facilitates running tools on some of the five stages.
The make variables <tt>SWIGTOOL</tt> and <tt>RUNTOOL</tt> are used to specify a tool to respectively, invoke SWIG
and the execution of the runtime test.
You are advised to view the <tt>Examples/test-suite/common.mk</tt> file for details but for a short summary,
the classic usage is to use <a href="http://valgrind.org/">Valgrind</a> for memory checking.
For example, checking for memory leaks when running the runtime test in the target language interpreter:
</p>
<div class="shell"><pre>
make ret_by_value.ctest RUNTOOL="valgrind --leak-check=full"
</pre></div>
<p>
This will probably make more sense if you look at the output of the above as it will show the exact commands being executed.
SWIG can be analyzed for bad memory accesses using:
</p>
<div class="shell"><pre>
make ret_by_value.ctest SWIGTOOL="valgrind --tool=memcheck --trace-children=yes"
</pre></div>
<H3><a name="Extending_nn43"></a>35.10.13 Documentation</H3>
<p>
@ -3286,7 +3507,7 @@ Some topics that you'll want to be sure to address include:
if available.
</ul>
<H3><a name="Extending_prerequisites"></a>35.10.13 Prerequisites for adding a new language module to the SWIG distribution</H3>
<H3><a name="Extending_prerequisites"></a>35.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3>
<p>
@ -3343,7 +3564,7 @@ should be added should there be an area not already covered by
the existing tests.
</p>
<H3><a name="Extending_coding_style_guidelines"></a>35.10.14 Coding style guidelines</H3>
<H3><a name="Extending_coding_style_guidelines"></a>35.10.15 Coding style guidelines</H3>
<p>
@ -3367,11 +3588,29 @@ The generated C/C++ code should also follow this style as close as possible. How
should be avoided as unlike the SWIG developers, users will never have consistent tab settings.
</p>
<H2><a name="Extending_nn44"></a>35.11 Typemaps</H2>
<H2><a name="Extending_debugging_options"></a>35.11 Debugging Options</H2>
<H3><a name="Extending_nn45"></a>35.11.1 Proxy classes</H3>
<p>
There are various command line options which can aid debugging a SWIG interface as well as debugging the development of a language module. These are as follows:
</p>
<div class="shell"><pre>
-debug-classes - Display information about the classes found in the interface
-debug-module &lt;n&gt; - Display module parse tree at stages 1-4, &lt;n&gt; is a csv list of stages
-debug-symtabs - Display symbol tables information
-debug-symbols - Display target language symbols in the symbol tables
-debug-csymbols - Display C symbols in the symbol tables
-debug-tags - Display information about the tags found in the interface
-debug-template - Display information for debugging templates
-debug-top &lt;n&gt; - Display entire parse tree at stages 1-4, &lt;n&gt; is a csv list of stages
-debug-typedef - Display information about the types and typedefs in the interface
-debug-typemap - Display information for debugging typemaps
</pre></div>
<p>
The complete list of command line options for SWIG are available by running <tt>swig -help</tt>.
</p>
<H2><a name="Extending_nn46"></a>35.12 Guide to parse tree nodes</H2>
@ -3781,6 +4020,13 @@ extern "X" { ... } declaration.
</pre>
</div>
<H2><a name="Extending_further_info"></a>35.13 Further Development Information</H2>
<p>
There is further documentation available on the internals of SWIG, API documentation and debugging information.
This is shipped with SWIG in the <tt>Doc/Devel</tt> directory.
</P>

4
Doc/Manual/Guile.html
View file

@ -814,7 +814,7 @@ Produces the following code at the top of the generated GOOPS guile-module
<code>Module-primitive.scm</code> (with <i>primitive</i> replaced with whatever is given with the <code>-primsuffix</code>
argument. The code to load the <code>.so</code> library should be located in the <code>%scheme</code> directive,
which will then be added to the scmstub file.
Swig will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
SWIG will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autoload path for guile, the
<code>%goops</code> directive can be empty. Otherwise, the <code>%goops</code> directive should contain
whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p>
@ -848,7 +848,7 @@ Produces the following code at the top of the generated GOOPS guile-module
</li>
<li><p><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file.
Swig will also automatically generate the line <code>(use-modules
SWIG will also automatically generate the line <code>(use-modules
(<i>Package</i> <i>Module-primitive</i>))</code> into the GOOPS guile-module. Again the <code>%goops</code>
directive should contain whatever code is needed to get that module loaded into guile.</p>

2
Doc/Manual/Introduction.html
View file

@ -334,7 +334,7 @@ major features include:
<p>
Currently, the only major C++ feature not supported is nested classes--a limitation
that will be removed in a future release.
that should be removed in a future release, but has some workarounds for the moment.
</p>
<p>

2
Doc/Manual/Java.html
View file

@ -1772,7 +1772,7 @@ If declarations such as these appear, you will get a warning message like this:
<div class="code">
<pre>
example.i:12: Warning(515): Overloaded method spam(unsigned short) ignored.
example.i:12: Warning 515: Overloaded method spam(unsigned short) ignored.
Method spam(int) at example.i:11 used.
</pre>
</div>

9
Doc/Manual/Library.html
View file

@ -667,7 +667,7 @@ in order for this to work.
</p>
<p>
<b><tt>char *cdata(void *ptr, int nbytes)</tt></b>
<b><tt>const char *cdata(void *ptr, size_t nbytes)</tt></b>
</p>
<div class="indent"><p>
@ -676,7 +676,7 @@ pointer.
</p></div>
<p>
<b><tt>void memmove(void *ptr, char *s)</tt></b>
<b><tt>void memmove(void *ptr, const char *s)</tt></b>
</p>
<div class="indent"><p>
@ -890,7 +890,10 @@ char *foo();
</div>
<p>
This will release the result.
This will release the result if the appropriate target language support is available.
SWIG provides the appropriate "newfree" typemap for <tt>char *</tt> so that the memory is released,
however, you may need to provide your own "newfree" typemap for other types.
See <a href="Customization.html#ownership">Object ownership and %newobject</a> for more details.
</p>
<H3><a name="Library_nn12"></a>8.3.4 cstring.i</H3>

4
Doc/Manual/Lua.html
View file

@ -684,8 +684,8 @@ void foo(Bar &amp;b);
If declarations such as these appear, you will get a warning message like this:
</p>
<div class="shell"><pre>
example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
at example.i:11.
example.i:12: Warning 509: Overloaded method spam(short) effectively ignored,
example.i:11: Warning 509: as it is shadowed by spam(int).
</pre></div>
<p>
To fix this, you either need to ignore or rename one of the methods. For example:

2
Doc/Manual/Modules.html
View file

@ -138,7 +138,7 @@ base class's methods. Typically you will get a warning when the module name is m
</p>
<div class="shell"> <pre>
derived_module.i:8: Warning(401): Base class 'base' ignored - unknown module name for base. Either import
derived_module.i:8: Warning 401: Base class 'base' ignored - unknown module name for base. Either import
the appropriate module interface file or specify the name of the module in the %import directive.
</pre></div>

2
Doc/Manual/Perl5.html
View file

@ -112,7 +112,7 @@ options are found near the end of the chapter.
<p>
To build a Perl5 module, run Swig using the <tt>-perl</tt> option as
To build a Perl5 module, run SWIG using the <tt>-perl</tt> option as
follows :
</p>

6
Doc/Manual/Php.html
View file

@ -48,10 +48,6 @@
<p>
<b>Caution: This chapter (and module!) is still under construction</b>
</p>
<p>
SWIG supports generating wrappers for PHP5. Support for PHP4 has been removed
as of SWIG 1.3.37. The PHP developers are no longer making new PHP4 releases,
@ -105,7 +101,7 @@ also contain PHP5 class wrappers.
</p>
<p>
Swig can generate PHP extensions from C++ libraries as well when
SWIG can generate PHP extensions from C++ libraries as well when
given the <tt>-c++</tt> option. The support for C++ is discussed in
more detail in <a href="#Php_nn2_6">section 27.2.6</a>.
</p>

2
Doc/Manual/Preprocessor.html
View file

@ -102,8 +102,6 @@ by SWIG when it is parsing the interface:
<div class="code"><pre>
SWIG Always defined when SWIG is processing a file
SWIGIMPORTED Defined when SWIG is importing a file with <tt>%import</tt>
SWIGMAC Defined when running SWIG on the Macintosh
SWIGWIN Defined when running SWIG under Windows
SWIG_VERSION Hexadecimal number containing SWIG version,
such as 0x010311 (corresponding to SWIG-1.3.11).

22
Doc/Manual/Python.html
View file

@ -69,9 +69,6 @@
<li><a href="#Python_nn47">Simple pointers</a>
<li><a href="#Python_nn48">Unbounded C Arrays</a>
<li><a href="#Python_nn49">String handling</a>
<li><a href="#Python_nn50">Arrays</a>
<li><a href="#Python_nn51">String arrays</a>
<li><a href="#Python_nn52">STL wrappers</a>
</ul>
<li><a href="#Python_nn53">Typemaps</a>
<ul>
@ -1137,7 +1134,7 @@ simply represented as opaque values using an especial python container object:
<div class="targetlang"><pre>
&gt;&gt;&gt; print f
&lt;Swig Object at _08a71808_p_FILE&gt;
&lt;Swig Object of type 'FILE *' at 0xb7d6f470&gt;
</pre></div>
<p>
@ -1147,7 +1144,7 @@ dereference the pointer from Python. Of course, that isn't much of a concern in
</p>
<p>
In older versions of Swig (1.3.22 or older), pointers were represented
In older versions of SWIG (1.3.22 or older), pointers were represented
using a plain string object. If you have an old package that still
requires that representation, or you just feel nostalgic, you can
always retrieve it by casting the pointer object to a string:
@ -1171,7 +1168,7 @@ integer:
<p>
However, the inverse operation is not possible, i.e., you can't build
a Swig pointer object from a raw integer value.
a SWIG pointer object from a raw integer value.
</p>
<p>
@ -1713,8 +1710,8 @@ If declarations such as these appear, you will get a warning message like this:
<div class="shell">
<pre>
example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
at example.i:11.
example.i:12: Warning 509: Overloaded method spam(short) effectively ignored,
example.i:11: Warning 509: as it is shadowed by spam(int).
</pre>
</div>
@ -3854,15 +3851,6 @@ If you need to return binary data, you might use the
also be used to extra binary data from arbitrary pointers.
</p>
<H3><a name="Python_nn50"></a>31.7.5 Arrays</H3>
<H3><a name="Python_nn51"></a>31.7.6 String arrays</H3>
<H3><a name="Python_nn52"></a>31.7.7 STL wrappers</H3>
<H2><a name="Python_nn53"></a>31.8 Typemaps</H2>

12
Doc/Manual/Ruby.html
View file

@ -1559,7 +1559,7 @@ you'll see a warning message like: </p>
<div class="code shell">
<pre>example.i:5: Warning(802): Warning for Derived: Base Base2 ignored.<br>Multiple inheritance is not supported in Ruby.<br></pre>
<pre>example.i:5: Warning 802: Warning for Derived: Base Base2 ignored.<br>Multiple inheritance is not supported in Ruby.<br></pre>
@ -1810,7 +1810,11 @@ message like this: </p>
<div class="code shell">
<pre>example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)<br>at example.i:11.<br> </pre>
<pre>
example.i:12: Warning 509: Overloaded method spam(short) effectively ignored,
example.i:11: Warning 509: as it is shadowed by spam(int).
<br>
</pre>
@ -7097,7 +7101,7 @@ being created. </div>
with Ruby objects. The following functions may prove to be useful.
(These functions plus many more can be found in <a href="http://www.rubycentral.com/book"><em>Programming
Ruby</em></a>, by David Thomas and Andrew Hunt.)&nbsp;</p>
<p>In addition, we list equivalent functions that Swig defines, which
<p>In addition, we list equivalent functions that SWIG defines, which
provide a language neutral conversion (these functions are defined for
each swig language supported). &nbsp;If you are trying to create a swig
file that will work under multiple languages, it is recommended you
@ -7123,7 +7127,7 @@ across multiple languages.</p>
<tbody>
<tr>
<th style="font-weight: bold;">RUBY</th>
<th style="font-weight: bold;">Swig</th>
<th style="font-weight: bold;">SWIG</th>
<td></td>
</tr>
<tr>

94
Doc/Manual/SWIG.html
View file

@ -330,10 +330,13 @@ currently supported:
</p>
<ul>
<li>Non-conventional type declarations.
<li>
<p>
Non-conventional type declarations.
For example, SWIG does not support declarations such as the following
(even though this is legal C):
</p>
<div class="code">
<pre>
/* Non-conventional placement of storage specifier (extern) */
@ -355,15 +358,19 @@ if you're feeling particularly obfuscated, you can certainly break SWIG (althoug
</p>
</li>
<li>Running SWIG on C++ source files (what would appear in a .C or .cxx file)
is not recommended. Even though SWIG can parse C++ class declarations,
it ignores declarations that are decoupled from their
original class definition (the declarations are parsed, but a lot of warning
messages may be generated). For example:
<li>
<p>
Running SWIG on C++ source files (the code in a .C, .cpp or .cxx file) is not recommended.
The usual approach is to feed SWIG header files for parsing C++ definitions and declarations.
The main reason is if SWIG parses a scoped definition or declaration (as is normal for C++ source files),
it is ignored, unless a declaration for the symbol was parsed earlier.
For example
</p>
<div class="code">
<pre>
/* Not supported by SWIG */
/* bar not wrapped unless foo has been defined and
the declaration of bar within foo has already been parsed */
int foo::bar(int) {
... whatever ...
}
@ -371,9 +378,12 @@ int foo::bar(int) {
</div>
</li>
<li>Certain advanced features of C++ such as nested classes
are not yet supported. Please see the section on using SWIG
with C++ for more information.
<li>
<p>
Certain advanced features of C++ such as nested classes
are not yet fully supported. Please see the C++ <a href="SWIGPlus.html#SWIGPlus_nested_classes">Nested classes</a> section
for more information.
</p>
</ul>
<p>
@ -787,6 +797,12 @@ In this case, the pointer <tt>e</tt> can change---it's only the value
being pointed to that is read-only.
</p>
<p>
Please note that for const parameters or return types used in a function, SWIG pretty much ignores
the fact that these are const, see the section on <a href="SWIGPlus.html#SWIGPlus_const">const-correctness</a>
for more information.
</p>
<p>
<b>Compatibility Note:</b> One reason for changing SWIG to handle
<tt>const</tt> declarations as read-only variables is that there are
@ -2489,7 +2505,7 @@ instead of a method. To do this, you might write some code like this:
// Now supply the implementation of the Vector_magnitude_get function
%{
const double Vector_magnitude_get(Vector *v) {
return (const double) return sqrt(v-&gt;x*v-&gt;x+v-&gt;y*v-&gt;y+v-&gt;z*v-&gt;z);
return (const double) sqrt(v-&gt;x*v-&gt;x+v-&gt;y*v-&gt;y+v-&gt;z*v-&gt;z);
}
%}
@ -2502,41 +2518,53 @@ of the object.
</p>
<p>
A similar technique can also be used to work with problematic data members.
A similar technique can also be used to work with data members that you want to process.
For example, consider this interface:
</p>
<div class="code">
<pre>
struct Person {
char name[50];
...
}
typedef struct {
char name[50];
...
} Person;
</pre>
</div>
<p>
By default, the <tt>name</tt> attribute is read-only because SWIG does not
normally know how to modify arrays. However, you can rewrite the interface
as follows to change this:
Say you wanted to ensure <tt>name</tt> was always upper case, you can rewrite
the interface as follows to ensure this occurs whenever a name is read or written to:
</p>
<div class="code">
<pre>
struct Person {
%extend {
char *name;
}
...
typedef struct {
%extend {
char name[50];
}
...
} Person;
%{
#include &lt;string.h&gt;
#include &lt;ctype.h&gt;
void make_upper(char *name) {
char *c;
for (c = name; *c; ++c)
*c = (char)toupper((int)*c);
}
// Specific implementation of set/get functions
%{
/* Specific implementation of set/get functions forcing capitalization */
char *Person_name_get(Person *p) {
return p-&gt;name;
make_upper(p-&gt;name);
return p-&gt;name;
}
void Person_name_set(Person *p, char *val) {
strncpy(p-&gt;name,val,50);
strncpy(p-&gt;name,val,50);
make_upper(p-&gt;name);
}
%}
</pre>
@ -2546,7 +2574,7 @@ void Person_name_set(Person *p, char *val) {
Finally, it should be stressed that even though <tt>%extend</tt>
can be used to add new data members, these new members can not require
the allocation of additional storage in the object (e.g., their values must
be entirely synthesized from existing attributes of the structure).
be entirely synthesized from existing attributes of the structure or obtained elsewhere).
</p>
<p>
@ -2629,10 +2657,16 @@ $o-&gt;{intRep}-&gt;{ivalue} = 7 # Change value of o.intRep.ivalue
</pre></div>
<p>
If you have a lot nested structure declarations, it is
If you have a lot of nested structure declarations, it is
advisable to double-check them after running SWIG. Although,
there is a good chance that they will work, you may have to
modify the interface file in certain cases.
</p>
<p>
Finally, note that nesting is handled differently in C++ mode,
see <a href="SWIGPlus.html#SWIGPlus_nested_classes">Nested classes</a>.
</p>
<H3><a name="SWIG_nn39"></a>5.5.8 Other things to note about structure wrapping</H3>

154
Doc/Manual/SWIGPlus.html
View file

@ -56,7 +56,7 @@
<li><a href="#SWIGPlus_nn34">Smart pointers and operator-&gt;()</a>
<li><a href="#SWIGPlus_nn35">Using declarations and inheritance</a>
<li><a href="#SWIGPlus_nested_classes">Nested classes</a>
<li><a href="#SWIGPlus_nn37">A brief rant about const-correctness</a>
<li><a href="#SWIGPlus_const">A brief rant about const-correctness</a>
<li><a href="#SWIGPlus_nn42">Where to go for more information</a>
</ul>
</div>
@ -1616,7 +1616,7 @@ warning message like this:
<div class="shell">
<pre>
example.i:18: Warning(401): Nothing known about base class 'Foo'. Ignored.
example.i:18: Warning 401: Nothing known about base class 'Foo'. Ignored.
</pre>
</div>
@ -2031,7 +2031,8 @@ Therefore, when SWIG encounters this situation, it may generate a warning messag
<div class="shell">
<pre>
example.i:4: Warning(509): Overloaded foo(long) is shadowed by foo(int) at example.i:3.
example.i:4: Warning 509: Overloaded method foo(long) effectively ignored,
example.i:3: Warning 509: as it is shadowed by foo(int).
</pre>
</div>
@ -2041,7 +2042,8 @@ or for statically typed languages like Java:
<div class="shell">
<pre>
example.i:4: Warning(516): Overloaded method foo(long) ignored. Method foo(int)
example.i:4: Warning 516: Overloaded method foo(long) ignored,
example.i:3: Warning 516: using foo(int) instead.
at example.i:3 used.
</pre>
</div>
@ -2091,7 +2093,7 @@ When wrapping an overloaded function, there is a chance that you will get an err
<div class="shell">
<pre>
example.i:3: Warning(467): Overloaded foo(int) not supported (no type checking
example.i:3: Warning 467: Overloaded foo(int) not supported (no type checking
rule for 'int').
</pre>
</div>
@ -3246,22 +3248,39 @@ public:
</div>
<p>
SWIG should be able to handle most simple uses of partial specialization. However, it may fail
to match templates properly in more complicated cases. For example, if you have this code,
SWIG supports both template explicit specialization and partial specialization. Consider:
</p>
<div class="code">
<pre>
template&lt;class T1, class T2&gt; class Foo&lt;T1, T2 *&gt; { };
template&lt;class T1, class T2&gt; class Foo { }; // (1) primary template
template&lt;&gt; class Foo&lt;double *, int *&gt; { }; // (2) explicit specialization
template&lt;class T1, class T2&gt; class Foo&lt;T1, T2 *&gt; { }; // (3) partial specialization
</pre>
</div>
<p>
SWIG isn't able to match it properly for instantiations like <tt>Foo&lt;int *, int *&gt;</tt>.
This problem is not due to parsing, but due to the fact that SWIG does not currently implement all
of the C++ argument deduction rules.
SWIG is able to properly match explicit instantiations:
</p>
<div class="code">
<pre>
<tt>Foo&lt;double *, int *&gt;</tt> // explicit specialization matching (2)
</pre>
</div>
<p>
SWIG implements template argument deduction so that the following partial specialization examples work just like they would with a C++ compiler:
</p>
<div class="code">
<pre>
<tt>Foo&lt;int *, int *&gt;</tt> // partial specialization matching (3)
<tt>Foo&lt;int *, const int *&gt;</tt> // partial specialization matching (3)
<tt>Foo&lt;int *, int **&gt;</tt> // partial specialization matching (3)
</pre>
</div>
<p>
Member function templates are supported. The underlying principle is the same
as for normal templates--SWIG can't create a wrapper unless you provide
@ -3471,7 +3490,7 @@ instead:
<p>
In this case, the default and conversion constructors have the same
name. Hence, Swig will overload them and define an unique visible
name. Hence, SWIG will overload them and define an unique visible
constructor, that will dispatch the proper call depending on the argument
type.
</p>
@ -4678,37 +4697,50 @@ public:
<p>
There is limited support for nested structs and unions when wrapping C code, see <a href="SWIG.html#SWIG_nested_structs">Nested structures</a> for further details.
However, there is no nested class/struct/union support when wrapping C++ code (using the -c++ commandline option).
This may be added at a future date, however, until then some of the following workarounds can be applied.
There is some support for nested structs and unions when wrapping C code,
see <a href="SWIG.html#SWIG_nested_structs">Nested structures</a> for further details.
The added complexity of C++ compared to C means this approach does not work well for
C++ code (when using the -c++ command line option).
For C++, a nested class is treated much like an opaque pointer, so anything useful within the nested class, such as its
methods and variables, are not accessible from the target language.
True nested class support may be added to SWIG in the future, however,
until then some of the following workarounds can be applied to improve the situation.
</p>
<p>
It might be possible to use partial class information. Since
SWIG does not need the entire class specification to work, conditional
compilation can be used to comment out the problematic nested class definition, you might do this:
It might be possible to use partial class information as often you can accept that the nested class is not needed,
especially if it is not actually used in any methods you need from the target language.
Imagine you are wrapping the following <tt>Outer</tt> class which contains a nested class <tt>Inner</tt>.
The easiest thing to do is turn a blind eye to the warning that SWIG generates, or simply suppress it:
</p>
<div class="code">
<pre>
class Foo {
%warnfilter(SWIGWARN_PARSE_NAMED_NESTED_CLASS) Outer::Inner;
class Outer {
public:
#ifndef SWIG
class Bar {
public:
...
};
#endif
Foo();
~Foo();
...
class Inner {
public:
...
};
Inner getInner();
void useInner(const Inner&amp; inner);
...
};
</pre>
</div>
<p>
The next workaround assumes you cannot modify the source code as was done above and it provides a solution for methods that use nested class types.
Imagine we are wrapping the <tt>Outer</tt> class which contains a nested class <tt>Inner</tt>:
Note that if <tt>Inner</tt> can be used as an opaque type, the default wrapping approach suffices.
For example, if the nested class does not need to be created from the target language, but can be obtained via a method
call, such as the <tt>getInner()</tt> method above, the returned value can then be passed around, such as passed into the
<tt>useInner()</tt> method.
</p>
<p>
With some more effort the above situation can be improved somewhat and a nested class can be constructed and used
from the target language much like any other non-nested class. Assuming we have the <tt>Outer</tt> class in a header file:
</p>
<div class="code">
@ -4721,14 +4753,18 @@ public:
int var;
Inner(int v = 0) : var(v) {}
};
void method(Inner inner);
Inner getInner();
void useInner(const Inner&amp; inner);
};
</pre>
</div>
<p>
The following interface file works around SWIG nested class limitations by redefining the nested class as a global class.
A typedef for the compiler is also required in order for the generated wrappers to compile.
The following interface file works around the nested class limitations by redefining the nested class as a global class.
A typedef for the compiler and the <tt>nestedworkaround</tt>
<a href="Customization.html#Customization_feature_flags">feature flag</a> is also required in
order for the generated wrappers to compile. This flag simply removes all the type information from SWIG, so SWIG treats
the nested class as if it had not been parsed at all.
</p>
<div class="code">
@ -4736,9 +4772,6 @@ A typedef for the compiler is also required in order for the generated wrappers
// File : example.i
%module example
// Suppress SWIG warning
#pragma SWIG nowarn=SWIGWARN_PARSE_NESTED_CLASS
// Redefine nested class in global scope in order for SWIG to generate
// a proxy class. Only SWIG parses this definition.
class Inner {
@ -4747,25 +4780,64 @@ class Inner {
Inner(int v = 0) : var(v) {}
};
%nestedworkaround Outer::Inner;
%{
#include "outer.h"
%}
%include "outer.h"
// We've fooled SWIG into thinking that Inner is a global class, so now we need
// to trick the C++ compiler into understanding this apparent global type.
%{
// SWIG thinks that Inner is a global class, so we need to trick the C++
// compiler into understanding this so called global type.
typedef Outer::Inner Inner;
%}
</pre>
</div>
<p>
The downside to this approach is having to maintain two definitions of <tt>Inner</tt>, the real one and the one in the interface file that SWIG parses.
The downside to this approach is a more complex interface file and having to maintain two definitions of <tt>Inner</tt>,
the real one and the one in the interface file that SWIG parses.
However, the upside is that all the methods/variables in the nested class are available from the target language
as a proxy class is generated instead of treating the nested class as an opaque type.
The proxy class can be constructed from the target language and passed into any methods accepting the nested class.
Also note that the original header file is parsed unmodified.
</p>
<H2><a name="SWIGPlus_nn37"></a>6.27 A brief rant about const-correctness</H2>
<p>
Finally, conditional compilation can be used as a workaround to comment out nested class definitions in the actual headers,
assuming you are able to modify them.
</p>
<div class="code">
<pre>
// File outer.h
class Outer {
public:
#ifndef SWIG
class Inner {
public:
...
};
#endif
...
};
</pre>
</div>
<p>
This workaround used to be common when SWIG could not deal with nested classes particulary well.
This should just be a last resort for unusual corner cases now as SWIG can parse nested classes and even handle nested template classes fairly well.
</p>
<p>
<b>Compatibility Note:</b> SWIG-1.3.40 and earlier versions did not have the <tt>nestedworkaround</tt> feature
and the generated code resulting from parsing nested classes did not always compile.
Nested class warnings could also not be suppressed using %warnfilter.
</p>
<H2><a name="SWIGPlus_const"></a>6.27 A brief rant about const-correctness</H2>
<p>

2
Doc/Manual/Sections.html
View file

@ -6,7 +6,7 @@
<body bgcolor="#ffffff">
<H1><a name="Sections"></a>SWIG-1.3 Development Documentation</H1>
Last update : SWIG-1.3.40 (in progress)
Last update : SWIG-1.3.41 (in progress)
<H2>Sections</H2>

4
Doc/Manual/Tcl.html
View file

@ -1502,8 +1502,8 @@ If declarations such as these appear, you will get a warning message like this:
<div class="code">
<pre>
example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
at example.i:11.
example.i:12: Warning 509: Overloaded method spam(short) effectively ignored,
example.i:11: Warning 509: as it is shadowed by spam(int).
</pre>
</div>

267
Doc/Manual/Typemaps.html
View file

@ -31,10 +31,11 @@
<li><a href="#Typemaps_pattern_matching">Pattern matching rules</a>
<ul>
<li><a href="#Typemaps_nn17">Basic matching rules</a>
<li><a href="#Typemaps_nn18">Typedef reductions</a>
<li><a href="#Typemaps_typedef_reductions">Typedef reductions</a>
<li><a href="#Typemaps_nn19">Default typemaps</a>
<li><a href="#Typemaps_mixed_default">Mixed default typemaps</a>
<li><a href="#Typemaps_nn20">Multi-arguments typemaps</a>
<li><a href="#Typemaps_debugging_search">Debugging typemap pattern matching</a>
</ul>
<li><a href="#Typemaps_nn21">Code generation rules</a>
<ul>
@ -68,7 +69,7 @@
<li><a href="#Typemaps_nn40">Typemaps for arrays</a>
<li><a href="#Typemaps_nn41">Implementing constraints with typemaps</a>
</ul>
<li><a href="#Typemaps_nn43">Typemaps for multiple languages</a>
<li><a href="#Typemaps_nn43">Typemaps for multiple target languages</a>
<li><a href="#Typemaps_optimal">Optimal code generation when returning by value</a>
<li><a href="#Typemaps_multi_argument_typemaps">Multi-argument typemaps</a>
<li><a href="#runtime_type_checker">The run-time type checker</a>
@ -88,10 +89,6 @@
<p>
<b>Disclaimer: This chapter is under construction!</b>
</p>
<H2><a name="Typemaps_nn2"></a>10.1 Introduction</H2>
@ -230,14 +227,17 @@ At first glance, this code will look a little confusing.
However, there is really not much to it. The first typemap (the "in"
typemap) is used to convert a value from the target language to C. The second
typemap (the "out" typemap) is used to convert in the other
direction. The content of each typemap is a small fragment of C code
that is inserted directly into the SWIG generated wrapper functions. Within
this code, a number of special variables prefixed with a $ are expanded. These are
really just placeholders for C variables that are generated in the course
direction. The content of each typemap is a small fragment of code
that is inserted directly into the SWIG generated wrapper functions.
The code is usually C or C++ code which will be generated into the C/C++ wrapper functions.
Note that this isn't always the case as some target language modules allow target language
code within the typemaps which gets generated into target language specific files.
Within this code, a number of special variables prefixed with a $ are expanded. These are
really just placeholders for C/C++ variables that are generated in the course
of creating the wrapper function. In this case, <tt>$input</tt> refers to an
input object that needs to be converted to C and <tt>$result</tt>
input object that needs to be converted to C/C++ and <tt>$result</tt>
refers to an object that is going to be returned by a wrapper
function. <tt>$1</tt> refers to a C variable that has the same type as
function. <tt>$1</tt> refers to a C/C++ variable that has the same type as
specified in the typemap declaration (an <tt>int</tt> in this
example).
</p>
@ -681,8 +681,9 @@ these methods is described later.
</p>
<p>
<em>modifiers</em> is an optional comma separated list of <tt>name="value"</tt> values. These
are sometimes to attach extra information to a typemap and is often target-language dependent.
<em>modifiers</em> is an optional comma separated list of <tt>name="value"</tt> values.
These are sometimes to attach extra information to a typemap and is often target-language dependent.
They are also known as typemap attributes.
</p>
<p>
@ -1091,7 +1092,7 @@ void F(int x[1000]); // int [ANY] rule (typemap 5)
</pre>
</div>
<H3><a name="Typemaps_nn18"></a>10.3.2 Typedef reductions</H3>
<H3><a name="Typemaps_typedef_reductions"></a>10.3.2 Typedef reductions</H3>
<p>
@ -1246,6 +1247,26 @@ is rather esoteric--there's little practical reason to write a typemap quite lik
to confuse your coworkers even more.
</p>
<p>
As a point of clarification, it is worth emphasizing that typedef matching is a typedef <b>reduction</b> process only, that is, SWIG does not search for every single possible typedef.
Given a type in a declaration, it will only reduce the type, it won't build it up looking for typedefs.
For example, given the type <tt>Struct</tt>, the typemap below will not be used for the <tt>aStruct</tt> parameter,
because <tt>Struct</tt> is fully reduced:
</p>
<div class="code">
<pre>
struct Struct {...};
typedef Struct StructTypedef;
%typemap(in) StructTypedef {
...
}
void go(Struct aStruct);
</pre>
</div>
<H3><a name="Typemaps_nn19"></a>10.3.3 Default typemaps</H3>
@ -1383,7 +1404,7 @@ Expect to see them being used more and more within the various libraries in late
</p>
<H3><a name="Typemaps_nn20"></a>10.3.5 Multi-arguments typemaps</H3>
<H3><a name="Typemaps_multi_argument_typemaps"></a>10.3.5 Multi-arguments typemaps</H3>
<p>
@ -1413,6 +1434,205 @@ but all subsequent arguments must match exactly.
</p>
<H3><a name="Typemaps_debugging_search"></a>10.3.6 Debugging typemap pattern matching</H3>
<p>
There are two useful debug command line options available for debugging typemaps, <tt>-debug-tmsearch</tt> and <tt>-debug-tmused</tt>.
</p>
<p>
The <tt>-debug-tmsearch</tt> option is a verbose option for debugging typemap searches.
This can be very useful for watching the pattern matching process in action and for debugging which typemaps are used.
The option displays all the typemaps and types that are looked for until a successful pattern match is made.
As the display includes searches for each and every type needed for wrapping, the amount of information displayed can be large.
Normally you would manually search through the displayed information for the particular type that you are interested in.
</p>
<p>
For example, consider some of the code used in the <a href="#Typemaps_typedef_reductions">Typedef reductions</a> section already covered:
</p>
<div class="code">
<pre>
typedef int Integer;
typedef Integer Row4[4];
void foo(Row4 rows[10]);
</pre>
</div>
<p>
A sample of the debugging output is shown below for the "in" typemap:
</p>
<div class="shell">
<pre>
swig -perl -debug-tmsearch example.i
...
example.h:3: Searching for a suitable 'in' typemap for: Row4 rows[10]
Looking for: Row4 rows[10]
Looking for: Row4 [10]
Looking for: Row4 rows[ANY]
Looking for: Row4 [ANY]
Looking for: Integer rows[10][4]
Looking for: Integer [10][4]
Looking for: Integer rows[ANY][ANY]
Looking for: Integer [ANY][ANY]
Looking for: int rows[10][4]
Looking for: int [10][4]
Looking for: int rows[ANY][ANY]
Looking for: int [ANY][ANY]
Looking for: SWIGTYPE rows[ANY][ANY]
Looking for: SWIGTYPE [ANY][ANY]
Looking for: SWIGTYPE rows[ANY][]
Looking for: SWIGTYPE [ANY][]
Looking for: SWIGTYPE *rows[ANY]
Looking for: SWIGTYPE *[ANY]
Looking for: SWIGTYPE rows[ANY]
Looking for: SWIGTYPE [ANY]
Looking for: SWIGTYPE rows[]
Looking for: SWIGTYPE []
Using: %typemap(in) SWIGTYPE []
...
</pre>
</div>
<p>
showing that the best default match supplied by SWIG is the <tt>SWIGTYPE []</tt> typemap.
As the example shows, the successful match displays just the typemap method name and type in this format: <tt>%typemap(method) type</tt>.
This information might meet your debugging needs, however, you might want to analyze further.
If you next invoke SWIG with the <tt>-E</tt> option to display the preprocessed output, and search for this particular typemap,
you'll find the full typemap contents (example shown below for Python):
</p>
<div class="code">
<pre>
%typemap(in, noblock=1) SWIGTYPE [] (void *argp = 0, int res = 0) {
res = SWIG_ConvertPtr($input, &amp;argp,$descriptor, $disown | 0 );
if (!SWIG_IsOK(res)) {
SWIG_exception_fail(SWIG_ArgError(res), "in method '" "$symname" "', argument " "$argnum"" of type '" "$type""'");
}
$1 = ($ltype)(argp);
}
</pre>
</div>
<p>
The generated code for the <tt>foo</tt> wrapper will then contain the snippets of the typemap with the special variables expanded.
The rest of this chapter will need reading though to fully understand all of this, however, the relevant parts of the generated code for the above typemap can be seen below:
</p>
<div class="code">
<pre>
SWIGINTERN PyObject *_wrap_foo(PyObject *SWIGUNUSEDPARM(self), PyObject *args) {
...
void *argp1 = 0 ;
int res1 = 0 ;
...
res1 = SWIG_ConvertPtr(obj0, &amp;argp1,SWIGTYPE_p_a_4__int, 0 | 0 );
if (!SWIG_IsOK(res1)) {
SWIG_exception_fail(SWIG_ArgError(res1), "in method '" "foo" "', argument " "1"" of type '" "int [10][4]""'");
}
arg1 = (int (*)[4])(argp1);
...
}
</pre>
</div>
<p>
Searches for multi-argument typemaps are not mentioned unless a matching multi-argument typemap does actually exist.
For example, the output for the code in the <a href="#Typemaps_multi_argument_typemaps">previous section</a> is as follows:
</p>
<div class="shell">
<pre>
...
example.h:39: Searching for a suitable 'in' typemap for: char *buffer
Looking for: char *buffer
Multi-argument typemap found...
Using: %typemap(in) (char *buffer,int len)
...
</pre>
</div>
<p>
The second option for debugging is <tt>-debug-tmused</tt> and this displays the typemaps used.
This option is a less verbose version of the <tt>-debug-tmsearch</tt> option as it only displays each successfully found typemap on a separate single line.
The output displays the type, and name if present, the typemap method in brackets and then the actual typemap used.
Below is the output for the example code at the start of this section on debugging.
</p>
<div class="shell">
<pre>
$ swig -perl -debug-tmused example.i
example.h:3: Typemap for Row4 rows[10] (in) : %typemap(in) SWIGTYPE []
example.h:3: Typemap for Row4 rows[10] (typecheck) : %typemap(typecheck) SWIGTYPE *
example.h:3: Typemap for Row4 rows[10] (freearg) : %typemap(freearg) SWIGTYPE []
example.h:3: Typemap for void foo (out) : %typemap(out) void
</pre>
</div>
<p>
Now, consider the following interface file:
</p>
<div class="code">
<pre>
%module example
%{
void set_value(const char* val) {}
%}
%typemap(check) char *NON_NULL {
if (!$1) {
/* ... error handling ... */
}
}
%apply SWIGTYPE * { const char* val, const char* another_value } // use default pointer handling instead of strings
%typemap(check) const char* val = char* NON_NULL;
%typemap(arginit, noblock=1) const char* val {
$1 = "";
}
void set_value(const char* val);
</pre>
</div>
<p>
and the output debug:
</p>
<div class="shell">
<pre>
swig -perl5 -debug-tmused example.i
example.i:21: Typemap for char const *val (arginit) : %typemap(arginit) char const *val
example.i:21: Typemap for char const *val (in) : %apply SWIGTYPE * { char const *val }
example.i:21: Typemap for char const *val (typecheck) : %apply SWIGTYPE * { char const *val }
example.i:21: Typemap for char const *val (check) : %typemap(check) char const *val = char *NON_NULL
example.i:21: Typemap for char const *val (freearg) : %apply SWIGTYPE * { char const *val }
example.i:21: Typemap for void set_value (out) : %typemap(out) void
</pre>
</div>
<p>
The following observations about what is displayed can be noted (the same applies for <tt>-debug-tmsearch</tt>):
<li>
The relevant typemap is shown, but for typemap copying, the appropriate <tt>%typemap</tt> or <tt>%apply</tt> is displayed, for example, the "check" and "in" typemaps.
</li>
<li>
The typemap modifiers are not shown, eg the <tt>noblock=1</tt> modifier in the "arginit" typemap.
</li>
<li>
The exact <tt>%apply</tt> statement might look different to what is in the actual code. For example, the <tt>const char* another_value</tt> is not shown as it is not relevant here.
Also the types may be displayed slightly differently - <tt>char const *</tt> and not <tt>const char*</tt>.
</li>
</p>
<H2><a name="Typemaps_nn21"></a>10.4 Code generation rules</H2>
@ -2686,12 +2906,12 @@ rather than blindly passing values to the underlying C/C++ program.</p>
Note: A more advanced constraint checking system is in development. Stay tuned.
</p>
<H2><a name="Typemaps_nn43"></a>10.7 Typemaps for multiple languages</H2>
<H2><a name="Typemaps_nn43"></a>10.7 Typemaps for multiple target languages</H2>
<p>
The code within typemaps is usually language dependent,
however, many languages support the same typemaps.
however, many target languages support the same typemaps.
In order to distinguish typemaps across different languages, the preprocessor should be used.
For example, the "in" typemap for Perl and Ruby could be written as:
</p>
@ -2873,8 +3093,8 @@ SWIG can detect when the "optimal" attribute cannot be used and will ignore it a
<div class="targetlang">
<pre>
example.i:28: Warning(474): Method XX::create() usage of the optimal attribute in the out
typemap at example.i:14 ignored as the following cannot be used to generate optimal code:
example.i:28: Warning 474: Method XX::create() usage of the optimal attribute ignored
example.i:14: Warning 474: in the out typemap as the following cannot be used to generate optimal code:
try {
result = XX::create();
} catch(const std::exception &amp;e) {
@ -2895,8 +3115,8 @@ In fact SWIG attempts to detect this and will issue a warning something like:
<div class="targetlang">
<pre>
example.i:21: Warning(475): Multiple calls to XX::create() might be generated due to
optimal attribute usage in the out typemap at example.i:7.
example.i:21: Warning 475: Multiple calls to XX::create() might be generated due to optimal attribute usage in
example.i:7: Warning 475: the out typemap.
</pre>
</div>
@ -3201,7 +3421,7 @@ language modules.</li>
<p>
The run-time type checker is used by many, but not all, of SWIG's supported target languages.
The run-time type checker features
are not required and are thus not used for strongly typed languages such as Java and C#.
are not required and are thus not used for statically typed languages such as Java and C#.
The scripting and scheme based languages rely on it and it forms
a critical part of SWIG's operation for these languages.
</p>
@ -4060,6 +4280,7 @@ numerous examples. You should look at these files to get a feel
for how to define typemaps of your own.
Some of the language modules support additional typemaps and further
information is available in the individual chapters for each target language.
There you may also find more hands-on practical examples.
</p>
</body>

20
Doc/Manual/Varargs.html
View file

@ -270,21 +270,37 @@ traceprintf(arg1, NULL);
<p>
Arguably, this approach seems to defeat the whole point of variable length arguments. However,
this actually provides enough support for many simple kinds of varargs functions to still be useful. For
instance, you could make function calls like this (in Python):
this actually provides enough support for many simple kinds of varargs functions to still be useful, however it does come with a caveat.
For instance, you could make function calls like this (in Python):
</p>
<div class="targetlang">
<pre>
&gt;&gt;&gt; traceprintf("Hello World")
&gt;&gt;&gt; traceprintf("Hello %s. Your number is %d\n" % (name, num))
&gt;&gt;&gt; traceprintf("Your result is 90%%.")
</pre>
</div>
<p>
Notice how string formatting is being done in Python instead of C.
The caveat is the strings passed must be safe to use in C though.
For example if name was to contain a "%" it should be double escaped in order to avoid unpredictable
behaviour:
</p>
<div class="targetlang">
<pre>
&gt;&gt;&gt; traceprintf("Your result is 90%.\n") # unpredictable behaviour
&gt;&gt;&gt; traceprintf("Your result is 90%%.\n") # good
</pre>
</div>
<p>
Read on for further solutions.
</p>
<H2><a name="Varargs_nn5"></a>13.4 Argument replacement using %varargs</H2>

30
Doc/Manual/Warnings.html
View file

@ -44,8 +44,8 @@ During compilation, SWIG may generate a variety of warning messages. For exampl
<div class="shell">
<pre>
example.i:16: Warning(501): Overloaded declaration ignored. bar(double)
example.i:15: Warning(501): Previous declaration is bar(int)
example.i:16: Warning 501: Overloaded declaration ignored. bar(double)
example.i:15: Warning 501: Previous declaration is bar(int)
</pre>
</div>
@ -344,7 +344,7 @@ These can be overridden using command line options, for example:
$ swig -python -Fstandard example.i
example.i:4: Syntax error in input.
$ swig -python -Fmicrosoft example.i
example.i(4): Syntax error in input.
example.i(4) : Syntax error in input.
</pre></div>
<H2><a name="Warnings_nn9"></a>14.9 Warning number reference</H2>
@ -399,18 +399,20 @@ example.i(4): Syntax error in input.
<li>308. Namespace alias '<em>name</em>' not allowed here. Assuming '<em>name</em>'
<li>309. [private | protected] inheritance ignored.
<li>310. Template '<em>name</em>' was already wrapped as '<em>name</em>' (ignored)
<li>311. Template partial specialization not supported.
<li>312. Nested classes not currently supported (ignored).
<li>312. Unnamed nested class not currently supported (ignored).
<li>313. Unrecognized extern type "<em>name</em>" (ignored).
<li>314. '<em>identifier</em>' is a <em>lang</em> keyword.
<li>315. Nothing known about '<em>identifier</em>'.
<li>316. Repeated %module directive.
<li>317. Specialization of non-template '<em>name</em>'.
<li>318. Instantiation of template <em>name</em> is ambiguous. Using <em>templ</em> at <em>file</em>:<em>line</em>
<li>318. Instantiation of template '<em>name</em>' is ambiguous, instantiation <em>templ</em> used, instantiation <em>templ</em> ignored.
<li>319. No access specifier given for base class <em>name</em> (ignored).
<li>320. Explicit template instantiation ignored.
<li>321. <em>identifier</em> conflicts with a built-in name.
<li>322. Redundant redeclaration of '<em>name</em>'.
<li>323. Recursive scope inheritance of '<em>name</em>'.
<li>324. Named nested template instantiations not supported. Processing as if no name was given to %template().
<li>325. Nested class not currently supported (<em>name</em> ignored).
<li>350. operator new ignored.
<li>351. operator delete ignored.
<li>352. operator+ ignored.
@ -482,8 +484,8 @@ example.i(4): Syntax error in input.
<li>469. No or improper directorin typemap defined for <em>type</em>
<li>470. Thread/reentrant unsafe wrapping, consider returning by value instead.
<li>471. Unable to use return type <em>type</em> in director method
<li>474. Method <em>method</em> usage of the optimal attribute in the out typemap at <em>file</em>:<em>line</em> ignored as the following cannot be used to generate optimal code: <em>code</em>
<li>475. Multiple calls to <em>method</em> might be generated due to optimal attribute usage in the out typemap at <em>file</em>:<em>line</em>.
<li>474. Method <em>method</em> usage of the optimal attribute ignored in the out typemap as the following cannot be used to generate optimal code: <em>code</em>
<li>475. Multiple calls to <em>method</em> might be generated due to optimal attribute usage in the out typemap.
</ul>
@ -492,22 +494,22 @@ example.i(4): Syntax error in input.
<ul>
<li>501. Overloaded declaration ignored. <em>decl</em>
<li>502. Overloaded constructor ignored. <em>decl</em>
<li>501. Overloaded declaration ignored. <em>decl</em>. Previous declaration is <em>decl</em>.
<li>502. Overloaded constructor ignored. <em>decl</em>. Previous declaration is <em>decl</em>.
<li>503. Can't wrap '<em>identifier</em>' unless renamed to a valid identifier.
<li>504. Function <em>name</em> must have a return type.
<li>505. Variable length arguments discarded.
<li>506. Can't wrap varargs with keyword arguments enabled.
<li>507. Adding native function <em>name</em> not supported (ignored).
<li>508. Declaration of '<em>name</em>' shadows declaration accessible via operator-&gt;() at <em>file:line</em>.
<li>509. Overloaded <em>declaration</em> is shadowed by <em>declaration</em> at <em>file</em>:<em>line</em>.
<li>508. Declaration of '<em>name</em>' shadows declaration accessible via operator-&gt;(), previous declaration of'<em>declaration</em>'.
<li>509. Overloaded method <em>declaration</em> effectively ignored, as it is shadowed by <em>declaration</em>.
<li>510. Friend function '<em>name</em>' ignored.
<li>511. Can't use keyword arguments with overloaded functions.
<li>512. Overloaded <em>declaration</em> const ignored. Non-const method at <em>file</em>:<em>line</em> used.
<li>512. Overloaded method <em>declaration</em> ignored, using non-const method <em>declaration</em> instead.
<li>513. Can't generate wrappers for unnamed struct/class.
<li>514.
<li>515.
<li>516. Overloaded method <em>declaration</em> ignored. Method <em>declaration</em> at <em>file</em>:<em>line</em> used.
<li>516. Overloaded method <em>declaration</em> ignored, using <em>declaration</em> instead.
<li>517.
<li>518. Portability warning: File <em>file1</em> will be overwritten by <em>file2</em> on case insensitive filesystems such as Windows' FAT32 and NTFS unless the class/module name is renamed.
<li>519. %template() contains no name. Template method ignored: <em>declaration</em>