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

Merge branch 'master' into C

Browse source
This commit is contained in:
Vadim Zeitlin 2016-04-08 15:35:32 +02:00
commit 7c402ad148
2760 changed files with 114689 additions and 39303 deletions
Download patch file Download diff file Expand all files Collapse all files

788
Doc/Devel/cpp11.html Normal file
View file

@ -0,0 +1,788 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE></TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.0 (Unix)">
<META NAME="CREATED" CONTENT="20090712;16061100">
<META NAME="CHANGED" CONTENT="20090817;17311900">
<META NAME="Podatek 1" CONTENT="">
<META NAME="Podatek 2" CONTENT="">
<META NAME="Podatek 3" CONTENT="">
<META NAME="Podatek 4" CONTENT="">
<STYLE TYPE="text/css">
<!--
@page { margin: 2cm }
H1 { margin-bottom: 0.21cm }
H1.western { font-family: "Liberation Serif", serif }
H1.cjk { font-family: "DejaVu Sans" }
H1.ctl { font-family: "DejaVu Sans" }
P { margin-bottom: 0.21cm }
H2 { margin-bottom: 0.21cm }
A:link { so-language: zxx }
-->
</STYLE>
</HEAD>
<BODY LANG="en-US" DIR="LTR">
<H1 CLASS="western"><U>C++0x/C++11 support for SWIG</U></H1>
<H1 CLASS="western">Summary</H1>
<P>This is a technical overview of the C++0x/C++11 support for the Swig.
This area of Swig is a work in progress. Initial C++0x/C++11 support for
Swig was written during the Google Summer of Code 2009 period by
Matevž Jekovec.</P>
<H1 CLASS="western">SVN branch</H1>
<P>branches/gsoc2009-matevz</P>
<H1 CLASS="western">New C++11 features status</H1>
<P>Wikipedia article: <A HREF="http://en.wikipedia.org/wiki/C++0x">http://en.wikipedia.org/wiki/C%2B%2B0x</A>
</P>
<H2>Rvalue reference and move semantics [done]</H2>
<P>The Rvalues are used in practice to speed up the move operations
on different containers.</P>
<P>In the following example, we want to swap the given elements:</P>
<PRE>template &lt;class T&gt; swap(T&amp; a, T&amp; b) {
T tmp(a); // now we have two copies of a
a = b; // now we have two copies of b
b = tmp; // now we have two copies of tmp (aka a)
}</PRE><P>
This can now be solved using the new function std::move():</P>
<PRE>template &lt;class T&gt; swap(T&amp; a, T&amp; b) {
T tmp(std::move(a));
a = std::move(b);
b = std::move(tmp);
}</PRE><P STYLE="margin-bottom: 0cm">
For the move function to take effect, user needs to reimplement the
move constructor (taking ClassType&amp;&amp; as an argument) and
operator=(ClassType&amp;&amp;):</P>
<PRE>class MyClass {
MyClass(MyClass&amp;&amp; p) : ptr(p.ptr) {p.ptr = 0;}
MyClass&amp; operator=(MyClass&amp;&amp; p) {
std::swap(ptr, p.ptr);
return *this;
}
};</PRE><P>
In practice, the Rvalues are used for temporaries (when passing the
result of one function as an argument to another).</P>
<P>Done: Added type&amp;&amp; to Swig parser. Added testcase
cpp11_rvalue_reference.i. Operator &amp;&amp; is treated the same as
operator &amp;. R11450</P>
<P STYLE="margin-bottom: 0cm">Article:
<A HREF="http://www.artima.com/cppsource/rvalue.html">http://www.artima.com/cppsource/rvalue.html</A></P>
<H2>Generalized constant expressions [done]</H2>
<P>In C++11 you can define functions as constant expressions.
Functions need to return constant value in form &quot;return expr&quot;,
where expr is a constant expression.
</P>
<P>A keyword &quot;constexpr&quot; is introduced for this. eg.:
constexpr int getNumber() { return 5; } const int MY_CONSTANT =
getNumber();
</P>
<P>Constants are treated as normal variables in interpreted languages
because they are not compiled into the executable. Java &quot;final&quot;
constants are defined runtime as well. C++ constants need to be
declared in the header file and defined in the implementation file,
so swig doesn't need to know about the constant values when parsing
the header file.
</P>
<P>Done: Added the “constexpr “ keyword to Swig. Added testcase
cpp11_constexpr. R11322</P>
<P>Problem: No compilers were known to support constexpr yet, so the
testcase was temporarily commented out in common.mk.
</P>
<H2>Extern template [done]</H2>
<P>Extern template forces the GCC compiler to not instantiate the
template in the translation unit at that time. It's a feature
specifically aimed at compilers to speed up the compilation process.
</P>
<P>Done: Added support for 'extern template class
std::vector&lt;MyClass&gt;;'. Added testcase cpp11_template_explicit.
R11385 , R11386</P>
<H2>Initializer lists [done]</H2>
<P>Initializer list is a new type in standard library:
std::initializer_list&lt;T&gt;. New symbols {} are introduced for the
initializer lists.
</P>
<P>One can now use:
</P>
<PRE> class A {
public:
A( std::initializer_list&lt;int&gt; );
};
A a1 = {1,2,3,4};</PRE><P>
Languages like Java, C# and Python already support direct creation of
lists natively.</P>
<P>Problem: initializer_list cannot be treated as an ordinary list.
The constructor containing initializer_list can only be accessed by
assigning the value using the {} brackets. I also don't think there
is a simple way to convert an ordinary list or a vector to the
initializer_list.</P>
<P>Done: Ignored the constructor having initializer_list as its
argument. Show warning to the user. Added testcase
cpp11_initializer_list. R11450</P>
<P>Article:
<A HREF="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1919.pdf">http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1919.pdf</A></P>
<H2>Uniform initialization [done]</H2>
<P>The new C++11 standard will allow the following:</P>
<PRE>struct IdString {
std::string name;
int identifier;
};
IdString GetString() {
return {&quot;SomeName&quot;, 4}; //Note the lack of explicit type.
}</PRE><P>
The feature works exactly as it did now for POD types only (eg. int
a[] = {1,2,3};). The following declarations are the same in the new
C++11:</P>
<PRE>IdString str1 = {„SomeName“, 4};
IdString str2{„SomeName“, 4};</PRE><P>
The new way of using uniform initialization allows the following:</P>
<PRE>struct BasicStruct {
int x;
double y;
};
struct AltStruct {
AltStruct(int x, double y) : x_{x}, y_{y} {}
private:
int x_;
double y_;
};
BasicStruct var1{5, 3.2}; // only fills the struct components
AltStruct var2{2, 4.3}; // calls the constructor</PRE><P>
The new syntax is specific to C++. Java, C# and scripting languages
do not support this behaviour, but always need constructors. They
support {} brackets for declaration of arrays as C does + they add
support for creation of arrays on-the-fly (what C++11 introduced with
this feature and more).</P>
<P>Done: Added syntax for {} member initialization in class
constructor. Added testcase cpp11_uniform_initialization. R11413</P>
<H2>Type inference [partially done]</H2>
<P>A new keyword 'auto' is introduced in C++11:</P>
<PRE>auto a1 = 100;
auto a2 = myFunc();</PRE><P>
The type of a1 and a2 is automatically determined according to the
initialization value during the semantic phase of the compiler.</P>
<P>Another macro 'decltype()' is introduced. The macro takes the
concrete object as an argument and returns its type. User could use
this as:</P>
<PRE>int i = 100;
decltype(i) j = 200; // decltype(i) = int</PRE><P STYLE="margin-bottom: 0cm">
Calling operators are allowed as well:</P>
<PRE STYLE="margin-bottom: 0.5cm">decltype(i+j) k = 300;</PRE><P>
Done: Added support for decltype() syntax. Test cases for normal
decltype members and alternate function members work fine. Currently
only syntax in form decltype(variable name) work. No support for
custom expresions eg. decltype(i+j) yet. R11525</P>
<P>TODO: William proposed to support the hidden variables as well
(ones not parsed by Swig and added to symbol table). This also allows
Swig to parse custom expressions like decltype(i+j). The idea is to
introduce a new SwigType for this.</P>
<H2>Range-based for-loop [ignored]</H2>
<P>This feature is always present inside the implementation block
only.
</P>
<H2>Lambda functions and expressions [done]</H2>
<P>C++11 introduces lambda functions defined as:</P>
<PRE STYLE="margin-bottom: 0.5cm">[](int x, int y) -&gt; int { return x + y; }</PRE><P>
If the lambda function contains a single return statement only or the
function doesn't return any type, the return type '-&gt;' can be
omitted. Lambda functions are function objects.</P>
<P>The following example prints the number of items stored in a list:</P>
<PRE>std::vector&lt;int&gt; someList;
int total = 0;
std::for_each( someList.begin(), someList.end(), [&amp;total](int x) {total += x} );
std::cout &lt;&lt; total;</PRE><P>
Parameters inside the [] are the visible parameters of the lambda
functions. These can be &amp; (references), = (copies), variable name
(variable copy), &amp;variable name (variable reference) or this
(copy of the current object).</P>
<P>Lambda functions can be stored using:</P>
<PRE STYLE="margin-bottom: 0.5cm">auto myLambdaFunc = [this]() { this-&gt;SomePrivateMemberFunction() };</PRE><P>
Proposal: Lambda functions are most commonly used inside the function
block to quickly define how the sort, find and similar functions
should work (the other way would be overriding a class – the Java
style). The latest GCC does not support lambda functions yet so it is
difficult to test the feature once implemented. I would implement the
syntax support for this feature, but produce no wrapper code. Lambda
functions still work inside the function block though.</P>
<P>Article:
<A HREF="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2550.pdf">http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2550.pdf</A></P>
<P>Done: Added syntax support for the lambda functions. Added
testcase cpp11_lambda_functions.i. R11491, R11492</P>
<H2>Alternate function syntax [done]</H2>
<P>The problem with decltype() is that the parameters need to be
defined before the decltype. The following syntax is not valid,
because lhs and rhs hasn't been defined at the time of decltype:</P>
<PRE>template&lt; typename LHS, typename RHS&gt;
decltype(lhs+rhs) AddingFunc(const LHS &amp;lhs, const RHS &amp;rhs) {return lhs + rhs;} //Not legal C++11</PRE><P>
The solution C++11 offers is the combination of the 'auto' keyword
before and '-&gt; rettype' after the function declaration:</P>
<PRE>template&lt; typename LHS, typename RHS&gt;
auto AddingFunc(const LHS &amp;lhs, const RHS &amp;rhs) -&gt; decltype(lhs+rhs) {return lhs + rhs;}</PRE><P>
The new syntax only makes the job for the C++ compilers easier when
parsing such functions. The new syntax can be used for ordinary
functions as well:</P>
<PRE>struct SomeStruct {
auto FuncName(int x, int y) -&gt; int;
};
auto SomeStruct::FuncName(int x, int y) -&gt; int {
return x + y;
}</PRE><P>
Done: Added support for the 'auto' return type. Added support for the
'-&gt; type' after the funtion declaration. Added testcases
cpp11_alternate_function_syntax.i and
cpp11_alternate_function_syntax_runme.py. R11414</P>
<H2>Concepts, Axioms [ignored]</H2>
<P>In C++ there is a common problem when you use a template in the
class which doesn't support all the operations the functions in the
class actually do on the type. Compiler errors are usually very long
and unreadable. C++11 adds support for the &quot;concepts&quot;. The
idea is to define what operations and attributes should the template
have. In contrast to class inheritance and polimorphism, all lookups
are done in compile-time.
</P>
<P>Basic syntax (note LessThanComparable<A HREF="http://www.dabeaz.com/cgi-bin/wiki.pl?action=change1&amp;id=LessThanComparable">?</A>
instead of &quot;class&quot; or &quot;typename&quot;):
</P>
<PRE> template&lt;LessThanComparable<A HREF="http://www.dabeaz.com/cgi-bin/wiki.pl?action=change1&amp;id=LessThanComparable">?</A> T&gt;
const T&amp; min(const T &amp;x, const T &amp;y) {
return y &lt; x ? y : x;
}</PRE><P>
Extended syntax (requires conditions are separated with &amp;&amp;,
|| or !):
</P>
<PRE> template&lt; typename T&gt; requires LessThanComparable<A HREF="http://www.dabeaz.com/cgi-bin/wiki.pl?action=change1&amp;id=LessThanComparable">?</A>&lt;T&gt;
const T&amp; min(const T &amp;x, const T &amp;y) {
return y &lt; x ? y : x;
}</PRE><P>
Definition of the concepts:
</P>
<PRE> concept LessThanComparable<A HREF="http://www.dabeaz.com/cgi-bin/wiki.pl?action=change1&amp;id=LessThanComparable">?</A>&lt; typename T &gt; {
bool operator&lt;(T,T);
requires GreaterThanComparable<A HREF="http://www.dabeaz.com/cgi-bin/wiki.pl?action=change1&amp;id=GreaterThanComparable">?</A>&lt;T&gt;;
typename value_type;
typename reference;
};</PRE><P>
Concept maps allow usage of a specific type:
</P>
<PRE> template&lt; typename T&gt;
concept_map InputIterator<A HREF="http://www.dabeaz.com/cgi-bin/wiki.pl?action=change1&amp;id=InputIterator">?</A>&lt;T*&gt; {
typedef T value_type ;
typedef T&amp; reference ;
typedef T* pointer ;
typedef std::ptrdiff_t difference_type ;
};</PRE><P>
Concept maps can act as mini-types, with function definitions and
other constructs commonly associated with classes:
</P>
<PRE> concept Stack&lt; typename X&gt; {
typename value_type;
void push(X&amp;, const value_type&amp;);
void pop(X&amp;);
value_type top(const X&amp;);
bool empty(const X&amp;);
};
template&lt; typename T&gt;
concept_map Stack&lt;std::vector&lt;T&gt; &gt; {
typedef T value_type;
void push(std::vector&lt;T&gt;&amp; v, const T&amp; x) { v.push_back(x); }
void pop(std::vector&lt;T&gt;&amp; v) { v.pop_back(); }
T top(const std::vector&lt;T&gt;&amp; v) { return v.back(); }
bool empty(const std::vector&lt;T&gt;&amp; v) { return v.empty(); }
};</PRE><P>
Axioms are a facility pertaining to concepts supplied by C++11 to
express the semantic properties of concepts. For example, the concept
Semigroup can be defined with an axiom Associativity as:
</P>
<PRE> concept Semigroup&lt; typename Op, typename T&gt; : CopyConstructible<A HREF="http://www.dabeaz.com/cgi-bin/wiki.pl?action=change1&amp;id=CopyConstructible">?</A>&lt;T&gt; {
T operator()(Op, T, T);
axiom Associativity(Op op, T x, T y, T z) {
op(x, op(y, z)) == op(op(x, y), z);
}
};</PRE><P>
Axioms are more like hints to the compiler to speed-up the process of
compilation.
</P>
<P>Ignored: Concepts and axioms were removed from the C++11 standard.
</P>
<H2>Object construction improvement [done]</H2>
<P>This feature allows classes constructors to call other
constructors with different arguments (similar to Java and C#
behaviour).
</P>
<P>The syntax is as follows:
</P>
<PRE> class SomeType {
int number;
public:
SomeType(int newNumber) : number(newNumber) {}
SomeType() : SomeType(42) {}
};</PRE><P>
Also when using the inheritance, the feature introduces inheritance
of all superclass constructors without being defined separately in
the inherited class:
</P>
<PRE> class BaseClass {
public:
BaseClass(int iValue);
};
class DerivedClass: public BaseClass {
public:
using BaseClass::BaseClass; // Adds DerivedClass(int) constructor
};</PRE><P>
Swig already correctly parses and produces the correct wrapper for
the “using” keyword.</P>
<P>Done: Added testcase cpp11_constructors.i which covers both
constructor delegation and constructor inheritance. R11532</P>
<P>Problem: Constructor delegation and constructor inheritance is not
supported by any compiler yet, so it's impossible to try and test
this feature.</P>
<H2>Null pointer constant [done]</H2>
<P>nullptr is part of the standard library.
</P>
<P>It's defined as typedef decltype(nullptr) nullptr_t;
</P>
<P>nullptr_t is defined in &lt;cstddef&gt;.
</P>
<P>As far as the C++ is compatible with 0 as the pointer value, swig
values will work for the C++. And the other way around, nullptr
behaves as the ordinary pointer (false, if empty, true, if not
empty), so it's ok for swig to compare it.</P>
<P>Done: Written a testcase cpp11_null_pointer_constant.i and
cpp11_null_pointer_constant_runme.py to prove the nullptr
functionality. R11484</P>
<H2>Strongly typed enumerations [partially done]</H2>
<P>C++11 introduces a new syntax for strongly typed enum declaration:
</P>
<PRE> enum class Enumeration {
Val1,
Val2,
Val3 = 100,
Val4 /* = 101 */
};</PRE><P>
Typing if (Val4 == 101) will result in compilation error.
</P>
<P>The enum itself can now be explicitely of type int, long, unsigned
int etc.:
</P>
<PRE STYLE="margin-bottom: 0.5cm"> enum class Enum2 : unsigned int {Val1, Val2};</PRE><P>
And it can be forward declared as well:
</P>
<PRE> enum Enum1; //Illegal in C++ and C++11; no size is explicitly specified.
enum Enum2 : unsigned int; //Legal in C++11.
enum class Enum3; //Legal in C++11, because enum class declarations have a default type of &quot;int&quot;.
enum class Enum4: unsigned int; //Legal C++11.
enum Enum2 : unsigned short; //Illegal in C++11, because Enum2 was previously declared with a different type.</PRE><P>
Done: Added syntax 'enum class Name' and forward declarators 'enum
Name : inherited type' or 'enum class Name : inherited type' in
R11449.</P>
<P>TODO: Add semantic support for enum elements not clashing with
enum elements in other enum classes. See cpp11_strongly_typed_enums.i
warnings.</P>
<P>Problem: Swig currently doesn't support nested classes. This
feature should be implemented using a new nested class when using
“enum class” with a single anonymous “enum {elements}”
element inside. For example:</P>
<PRE STYLE="margin-bottom: 0.5cm">class A { enum class EA { a,b,c,d }; };</PRE><P>
should be mapped to</P>
<PRE STYLE="margin-bottom: 0.5cm">class A { class EA { enum {a,b,c,d}; }; };</PRE><H2>
Angle bracket [done]</H2>
<P>Support for right angled brackets was implemented using the
following article as a base:
<A HREF="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1757.html">http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1757.html</A>
</P>
<P>Done: Added support for angle brackets. Used the preferred
&quot;Approach 1&quot;. Added a testcase named
cpp11_template_double_brackets. R11245</P>
<H2>Explicit conversion operators [done]</H2>
<P>This is used when converting one type to another (eg. if
(myObject) {}, where myObject is your custom class converted to
bool).
</P>
<P>Requires both operator and function overloading which is not
supported in any target language (eg. python, php).
</P>
<P>Done: Swig already supports the keyword &quot;explicit&quot; for
function types as well. Added test case
cpp11_explicit_conversion_operators. R11323</P>
<H2>Template typedefs [partially done]</H2>
<P>The new C++11 will allow creation of wrapper around the template.
For example, if we want to do this:</P>
<PRE>template&lt; typename first, typename second, int third&gt;
class SomeType;
template&lt; typename second&gt;
typedef SomeType&lt;OtherType, second, 5&gt; TypedefName; //Illegal in C++</PRE><P>
This is still illegal! But we can now use the new syntax for
achieving the same effect:</P>
<PRE>template&lt; typename first, typename second, int third&gt;
class SomeType;
template&lt; typename second&gt;
using TypedefName = SomeType&lt;OtherType, second, 5&gt;;</PRE><P>
Here we created a new wrapper TypedefName taking one template
argument &lt;second&gt; which creates a type SomeType&lt;OtherType,
second, 5&gt;. OtherType and 5 are predefined here and hidden from
the user – the user only uses TypedefName type.</P>
<P>The same goes for the following example:</P>
<PRE>typedef void (*PFD)(double); // Old style
using PF = void (*)(double); // New introduced syntax</PRE><P>
Swig supports parsing typedefs for templates as well for example:</P>
<PRE STYLE="margin-bottom: 0.5cm">typedef List&lt;int&gt; intList;</PRE><P>
Done: Expanded support for the new 'using' syntax and template
aliasing. Added testcase cpp11_template_typedefs. R11533</P>
<P>TODO: Make Swig aware of the newly defined typedef. The TYPEDEF
keyword is part of the storage_class rule and type+declarator (see
c_decl rule) is the right part of the definition – for example void
(*PFD)(double) cannot be transformed to void *(double) easily. To
fully support the new 'using' form, we'll probably have to change the
type, type_right rules and declarator, direct_declarator,
notso_direct_declarator etc., which is PITA.</P>
<H2>Unrestricted unions [done]</H2>
<P>C++ currently offers usage of unions for types with trivial
constructors only. The new C++11 standard allows usage of types with
non-trivial constructors as well:</P>
<PRE> struct point {
point() {}
point(int x, int y): x_(x), y_(y) {}
int x_, y_;
};
union P {
int z;
double w;
point p; // Illegal in C++; point has a non-trivial constructor. However, this is legal in C++11.
} p1;</PRE><P>
Swig already parses the given syntax.</P>
<P>Done: Added testcase cpp11_unrestricted_unions. R11435, R11447</P>
<P>Problem: GCC doesn't support unrestricted unions yet so there is
no way to actually test, if it works.</P>
<H2>Variadic templates [partially done]</H2>
<P>The new C++11 offers the following syntax:</P>
<PRE STYLE="margin-bottom: 0.5cm">template&lt;typename... Values&gt; class tuple;</PRE><P>
This can be used for example:</P>
<PRE STYLE="margin-bottom: 0.5cm">class tuple&lt;int, std::vector&lt;int&gt;, std::map&lt;std::string, std::vector&lt;int&gt;&gt;&gt; someInstanceName;</PRE><P>
The ... is used in two cases. One is in the template header where it
marks on the left the keywords 'typename' or 'class' and a type name
on the right. The second case is usually in the function block to
decompose typename on the left of the ... . For example:</P>
<PRE>void printf(const char *s) {
while (*s) {
if (*s == '%' &amp;&amp; *(++s) != '%')
throw std::runtime_error(&quot;invalid format string: missing arguments&quot;);
std::cout &lt;&lt; *s++;
}
}
template&lt;typename T, typename... Args&gt;
void printf(const char* s, T value, Args... args) { // recursive action – split previous args to value + args
while (*s) {
if (*s == '%' &amp;&amp; *(++s) != '%') {
std::cout &lt;&lt; value;
printf(*s ? ++s : s, args...); // call even when *s == 0 to detect extra arguments
return;
}
std::cout &lt;&lt; *s++;
}
throw std::logic_error(&quot;extra arguments provided to printf&quot;);
}</PRE><P>
The tricky part is that variadic templates can unpack actually
anywhere – including the class inheritance :(</P>
<PRE>template &lt;typename... BaseClasses&gt; class ClassName : public BaseClasses... {
public:
ClassName (BaseClasses&amp;&amp;... baseClasses) : BaseClasses(baseClasses)... {}
}</PRE><P>
A new extension to sizeof is also introduced with this feature. The
... after sizeof returns number of arguments:</P>
<PRE>template&lt;typename ...Args&gt; struct SomeStruct {
static const int size = sizeof...(Args);
}
// SomeStruct&lt;Type1, Type2&gt;::size is 2 and SomeStruct&lt;&gt;::size is 0</PRE><P>
Done: Added syntax support for 'typename' or 'class' + ... + id.
Added testcase cpp11_variadic_templates. R11458</P>
<P>Done: Added syntax support for BaseClass + ..., type + ... + id in
parameters and baseclass + ... for intializers after constructor.
Extended Swig syntax to support sizeof...(Args). R11467</P>
<P>Done: Fixed %template to support variadic number of templates.</P>
<P>TODO: Only (if present) first variadically defined argument is
currently used in %template directive. The next ones are ignored.</P>
<H2>New string literals [partially done]</H2>
<P>Beside the implementation, the new C++11 Unicode and custom
delimeter constants can occur in templates in the header file.
</P>
<P>Done: Added symbols 'u', 'u8' and 'U' to mark the beginning of the
UTF string. Also added test case cpp11_raw_string_literals. R11327</P>
<P>Done: Added R&quot;DELIMITER[, ]DELIMITER&quot; for a custom
delimiter for the beginning/end of the string. R11328</P>
<P>TODO: Fix the Swig's C++ preprocessor bug when parsing an odd
number of “ inside the string brackets. See
Source/Preprocessor/cpp.c.</P>
<H2>User-defined literals [partially done]</H2>
<P>C++ has different suffix literals. eg. 12.5f marks the number 12.5
as float.
</P>
<P>C++11 allows user to define his own suffix for the strings always
starting with the underscore (_). eg. int a = &quot;hello&quot;_mySuffix;
</P>
<P>The syntax is similar to other operator overloading functions:
</P>
<PRE STYLE="margin-bottom: 0.5cm"> OutputType operator &quot;&quot; _mySuffix(const char * string_values);</PRE><P>
The null terminated const char* is the string between the &quot;&quot;.
The _mySuffix is the name of the suffix operator. And the OutputType
is the outputType the operator returns.
</P>
<P>Other forms are:
</P>
<PRE> OutputType operator &quot;&quot; _mySuffix(const char * string_values, size_t num_chars);
OutputType operator &quot;&quot; _mySuffix(const wchar_t * string_values, size_t num_chars);
OutputType operator &quot;&quot; _mySuffix(const char16_t * string_values, size_t num_chars);
OutputType operator &quot;&quot; _mySuffix(const char32_t * string_values, size_t num_chars);
OutputType operator &quot;&quot; _mySuffix(int value); /* cooked version - ie. atoi() of string */</PRE><P>
Another possibility is to use variadic templates:
</P>
<PRE> template&lt;char...&gt; OutputType operator &quot;&quot; _mySuffix();
OutputType someVariable = &quot;1234&quot;_mySuffix;</PRE><P>
This instantiates the literal processing function as
operator&quot;&quot;_Suffix&lt;'1', '2', '3', '4'&gt;. In this form,
there is no terminating null character to the string. The main
purpose to doing this is to use C++11's constexpr keyword and the
compiler to allow the literal to be transformed entirely at compile
time, assuming OutputType is a constexpr-constructable and copyable
type, and the literal processing function is a constexpr function.</P>
<P>Article:
<A HREF="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2765.pdf">http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2765.pdf</A></P>
<P>Done: Added syntax support for userdefined literals. Added
testcase cpp11_userdefined_literals.i. R11494</P>
<P>TODO: %rename doesn't parse operator”” yet.</P>
<H2>Thread-local storage [done]
</H2>
<P>New C++11 introduces keyword &quot;thread_local&quot; which marks
the following variable dynamically located depending on the current
thread when using the address-of (&amp;) operator.
</P>
<P>Syntax:
</P>
<PRE> struct A {
thread_local int val;
};</PRE><P>
Done: Add &quot;thread_local&quot; keyword to Swig. Added testcase
cpp11_thread_local. R11393</P>
<H2>Defaulting/deleting of standard functions on C++ objects [done]</H2>
<P>C++ automatically creates default constructor with empty
parameters, copy constructor, operator= and destructor for any class.
Sometimes user wants to explicitly remove one of them or enable them
(eg. default constructor with empty parameters doesn't work any more,
if any other constructor is defined).
</P>
<P>Words &quot;default&quot; and &quot;delete&quot; are introduced.
The syntax is similar to declaration of pure virtual function:
</P>
<PRE> struct NonCopyable {
NonCopyable &amp; operator=(const NonCopyable&amp;) = delete; /* Removes operator= */
NonCopyable(const NonCopyable&amp;) = delete; /* Removed copy constructor */
NonCopyable() = default; /* Explicitly allows the empty constructor */
void *operator new(std::size_t) = delete; /* Removes new NonCopyable */
};</PRE><P>
User has the ability by using keyword delete to disallow calling of
the standard functions brought by C++ itself.
</P>
<PRE> struct A1 {
void f(int i);
void f(double i) = delete; /* Don't cast double to int. Compiler returns an error */
};
struct A2 {
void f(int i);
template&lt;class T&gt; void f(T) = delete; /* Only accept int */
};</PRE><P>
Ignored: Swig already parses the keywords &quot;= delete&quot; and &quot;=
default&quot;. These keywords are used for built-in functions (copy
constructor, operator= etc.), which are ignored by Swig anyway.</P>
<P>Done: Added testcase cpp11_default_delete. R11535</P>
<H2>Type long long int [done]</H2>
<P>Type long long int is an integer type that has at least 64 useful
bits. C99 added it to its standard, but the C++ didn't adopt it until
C++11. Most C++ compilers supported it though.
</P>
<P>Done: Swig already parses the C code including the long long type.
</P>
<H2>Static assertions [done]</H2>
<P>static_assert() can be used at class scope as well eg.:
</P>
<PRE> template &lt;typename T&gt;
struct Check {
static_assert(sizeof(int) &lt;= sizeof(T), &quot;not big enough&quot;);
};</PRE><P>
Done: Added syntax support for &quot;static_assert()&quot;. Added
test case cpp11_static_assert. R11369</P>
<H2>Allow sizeof to work on members of classes without an explicit
object [done]</H2>
<P>C++11 allows calls of sizeof to concrete objects as well:
</P>
<PRE> struct A { int member; };
sizeof(A::member); //Does not work with C++03. Okay with C++11</PRE><P>
This kind of syntax is already supported by Swig.</P>
<P>Done: Added testcase cpp11_sizeof_objects. R11538
</P>
<H2>Threading facilities [ignored]</H2>
<P>C++11 will add the following classes to the standard library:
</P>
<PRE> * std::thread
* std::mutex, std::recursive_mutex
* std::condition_variable, std::condition_variable_any
* std::lock_guard, std::unique_lock
* std::packaged_task</PRE><P>
Ignored: No changes to the language itself is made.
</P>
<H2>Tuple types [TODO]</H2>
<P>Tuple is array of various types. C++11 introduced this feature
using variadic templates. Tuple is defined as:</P>
<PRE STYLE="margin-bottom: 0.5cm">template &lt;class ...Types&gt; class tuple;</PRE><P>
Constructor is automatically generated filling the tuple elements.
get&lt;X&gt; function is introduced to get the Xth element in the
tuple.</P>
<PRE>typedef tuple&lt; int, double, long &amp;, const char * &gt; test_tuple ;
long lengthy = 12 ;
test_tuple proof( 18, 6.5, lengthy, &quot;Ciao!&quot; ) ;
lengthy = get&lt;0&gt;(proof) ; // Assign to 'lengthy' the value 18.
get&lt;3&gt;(proof) = &quot; Beautiful!&quot; ; // Modify the tuple’s fourth element.</PRE><P>
Tuples can be copied to each other, if all the elements are copiable:</P>
<PRE>typedef tuple&lt; int , double, string &gt; tuple_1 t1 ;
typedef tuple&lt; char, short , const char * &gt; tuple_2 t2( 'X', 2, &quot;Hola!&quot; ) ;
t1 = t2 ; // Ok, first two elements can be converted,
// the third one can be constructed from a 'const char *'.</PRE><P>
TODO: Implement wrappers for the tuplet&lt;&gt; class.</P>
<H2>Hash tables [TODO]</H2>
<P>C++11 introduces the &quot;unordered&quot; version of existing
types, which in practice work faster than the linear types:
</P>
<PRE> - unordered set
- unordered multiset
- unordered map
- unordered multimap</PRE><P>
Swig should use the &quot;unordered&quot; types exactly the same as
the original linear types.</P>
<P>Problem: Unordered types do not contain exactly same members as
ordered ones (eg. _Hashtable_iterator does not offer operator--() and
constructor with compare function which is required). So simply
aliasing unordered classes to ordered ones doesn't work.</P>
<P>TODO: Implement wrappers for unordered_ types. Initial work is
already done in Lib/std/unordered_*.i files.</P>
<H2>Regular expressions [ignored]</H2>
<P>Two new classes are introduced in C++11: basic_regex and
match_results. Both are defined in regex header file.
</P>
<P>Ignored: The new feature extends the standardy library only. No
changes to Swig needed.
</P>
<H2>General-purpose smart pointers [done]</H2>
<P>This feature deprecates auto_ptr and adds shared_ptr, weak_ptr and
unique_ptr to the standard library.
</P>
<P>This feature only adds the smart pointers to the standard library
and doesn't effect the C++ syntax.</P>
<P>Done: Added test case which uses all three smart pointers in the
class. R11394</P>
<P>Problem: GCC standard library doesn't contain the new smart
pointers yet.
</P>
<H2>Extensible random number facility [ignored]</H2>
<P>This feature standardize the pseudo random number algorithm
(currently, the random number generator was dependent on the
platform/compiler). It adds functions linear_congruential,
subtract_with_carry and mersenne_twister and symbols
uniform_int_distribution, bernoulli_distribution,
geometric_distribution, poisson_distribution, binomial_distribution,
uniform_real_distribution, exponential_distribution,
normal_distribution and gamma_distribution to the standard library.
</P>
<P>Ignored: The new feature extends the standardy library only. No
changes to Swig needed.
</P>
<H2>Wrapper reference [ignored]</H2>
<P>This feature adds ref and cref classes to the standard library
(#include &lt;utility&gt;) usually used in tempalte functions.
</P>
<P>Ignored: The new feature extends the standardy library only. No
changes to Swig needed.
</P>
<H2>Polymorphous wrappers for function objects [done]</H2>
<P>Two features are introduced:
</P>
<UL>
<LI><P>The function template wrapper:
</P>
</UL>
<PRE STYLE="margin-bottom: 0.5cm"> function&lt;int ( int, int )&gt; pF;</PRE>
<UL>
<LI><P>and the function object:
</P>
</UL>
<PRE> struct Test {
bool operator()( short x, short y );
};</PRE><P>
Swig already supports the two.</P>
<P>Done: Added a runtime testcase for function objects
cpp11_function_objects. R11419.</P>
<H2>Type traits for metaprogramming [ignored]</H2>
<P>C++11 adds a new header file &lt;type_traits&gt; which includes
helper functions to determine the template type while initializing
the object at compile time.
</P>
<P>Swig already supports the following code:
</P>
<PRE> template&lt; int B, int N &gt;
struct Pow {
// recursive call and recombination.
enum{ value = B*Pow&lt; B, N-1 &gt;::value };
};
template&lt; int B &gt; struct Pow&lt; B, 0 &gt; // <EM>N == 0</EM> condition of termination.
{
enum{ value = 1 };
};
int quartic_of_three = Pow&lt; 3, 4 &gt;::value ;</PRE><P>
Functions is_convertible, is_integral, is_integral_const etc. are
part of the new header:
</P>
<PRE>// First way of operating.
template&lt; bool B &gt; struct algorithm {
template&lt; class T1, class T2 &gt; int do_it( T1 &amp;, T2 &amp; ) { /*...*/ }
};
// Second way of operating.
template&lt;&gt; struct algorithm&lt;true&gt; {
template&lt; class T1, class T2 &gt; int do_it( T1, T2 ) { /*...*/ }
};
// Instantiating 'elaborate' will automatically instantiate the correct way to operate.
template&lt; class T1, class T2 &gt; int elaborate( T1 A, T2 B ) {
// Use the second way only if 'T1' is an integer and if 'T2' is
// in floating point, otherwise use the first way.
return algorithm&lt; is_integral&lt;T1&gt;::value &amp;&amp; is_floating_point&lt;T2&gt;::value &gt;::do_it( A, B );
}</PRE><P>
Swig correctly parses the syntax for template&lt;bool&gt;,
template&lt;class T&gt; and template&lt;&gt;.
</P>
<P>Ignored: Swig requires explicitly defined template class
(%template directive) to export it to the target language.</P>
<H2>Uniform method for computing return type of function objects
[partially done]</H2>
<P>The template function is introduced: std::result_of() which
depends on decltype:
</P>
<PRE>template&lt; class Obj &gt;
class calculus_ver2 {
public:
template&lt; class Arg &gt;
typename std::result_of&lt;Obj(Arg)&gt;::type operator()( Arg&amp; a ) const {
return member(a);
}
private:
Obj member;
};</PRE><P>
Swig correctly parses the result_of class.</P>
<P>TODO: The return type (the result_of::type member) is not
calculated by Swig. This needs a much more complex semantic parser.</P>
<P>Done: Added testcase cpp11_result_of. R11534</P>
</BODY>
</HTML>

28
Doc/Devel/engineering.html
View file

@ -25,7 +25,7 @@
<li><a name="i8" href="#8">8. Naming Conventions</a>
<li><a name="i9" href="#9">9. Visibility</a>
<li><a name="i10" href="#10">10. Miscellaneous Coding Guidelines</a>
<li><a name="i11" href="#11">11. SVN Tagging Conventions</a>
<li><a name="i11" href="#11">11. Git Tagging Conventions</a>
</ul>
<a name="1" href="#i1">
@ -119,8 +119,8 @@ are case-insensitive on Windows so this convention will prevent you from inadver
creating two files that differ in case-only.
<p>
Each file should include a short abstract, license information and
a SVN revision tag like this:
Each file should include a short abstract and license information
like this:
<blockquote>
<pre>
@ -137,8 +137,6 @@ a SVN revision tag like this:
* This file defines ...
* ----------------------------------------------------------------------------- */
static char cvs[] = "&#36Id&#36";
#include "swig.h"
/* Declarations */
@ -159,12 +157,6 @@ static int avariable;
</pre>
</blockquote>
The SVN revision tag should be placed into a static string as shown
above mangled with the name of the file.
This adds the revision information to the SWIG executable and
makes it possible to extract version information from a raw binary
(sometimes useful in debugging).
<p>
As a general rule, files start to get unmanageable once they exceed
about 2000 lines. Files larger than this should be broken up into
@ -379,10 +371,10 @@ making your changes.
These are largely covered in the main documentation in the Extending.html file.
<a name="11" href="#i11">
<h2>11. SVN Tagging Conventions</h2>
<h2>11. Git Tagging Conventions</h2>
</a>
Use <tt>svn tag</tt> to declare some set of file revisions as related in some
Use <tt>git tag</tt> to declare some set of file revisions as related in some
symbolic way. This eases reference, retrieval and manipulation of these files
later. At the moment (2001/01/16 14:02:53), the conventions are very simple;
let's hope they stay that way!
@ -390,10 +382,10 @@ let's hope they stay that way!
<p>
There are two types of tags, internal (aka personal) and external.
Internal tags are used by SWIG developers primarily, whereas external
tags are used when communicating with people w/ anonymous svn access.
tags are used when communicating with people w/ anonymous git access.
<ul>
<li> Internal tags should start with the developer name and a hyphen.
<li> External tags should start with "v-".
<li> External tags should start with "rel-".
</ul>
That's all there is to it. Some example tags:
@ -402,10 +394,8 @@ That's all there is to it. Some example tags:
<li> ttn-pre-xml-patch
<li> ttn-post-xml-patch
<li> ttn-going-on-vacation-so-dutifully-tagging-now
<li> v-1-3-a37-fixes-bug-2432
<li> v-1-3-a37-fixes-bug-2433
<li> v-1-3-a37-fixes-bug-2432-again
<li> v-1-3-a37-release
<li> rel-1.3.40
<li> rel-2.0.9
</ul>
<hr>

33
Doc/Devel/internals.html
View file

@ -42,6 +42,7 @@
<li><a name="i7" href="#7">7. Debugging SWIG</a>
<ul>
<li><a name="i7.1" href="#7.1">7.1 Debugging DOH Types The Hard Way</a>
<li><a name="i7.2" href="#7.2">7.2 Debugging DOH memory allocation problems</a>
</ul>
</ul>
@ -346,7 +347,7 @@ Delete(a); /* Destroy a */
All objects are referenced counted and given a reference count of 1 when initially created. The
<tt>Delete()</tt> function only destroys an object when the reference count reaches zero. When
an object is placed in a list or hash table, it's reference count is automatically increased. For example:
an object is placed in a list or hash table, its reference count is automatically increased. For example:
<blockquote>
<pre>
@ -843,7 +844,7 @@ Returns a type object corresponding to the type string produced by the Swig_cloc
<li><tt>char *Swig_clocal_deref(DataType *t, char *name)</tt><br>
This function is the inverse of the <tt>clocal()</tt> function. Given a type and a name,
it produces a string containing the code needed to cast/convert the type produced by
<tt>Swig_clocal()</tt> back into it's original type.
<tt>Swig_clocal()</tt> back into its original type.
<p>
<li><tt>char *Swig_clocal_assign(DataType *t, char *name)</tt><br>
@ -1179,6 +1180,34 @@ Either <br>
</ul>
<a name="7.2" href="#i7.2">
<h3>7.2 Debugging DOH memory allocation problems</h3>
</a>
<p>
The DOH objects are reference counted and use pools for memory allocation.
The implementation is in <tt>memory.c</tt>. When there are memory corruption problems,
various memory allocator tools are normally used to diagnose problems. These can be used
on SWIG and can be very useful. However, they won't necessarily find use of stale DOH objects,
that is, DOH objects
that are used after they have been deleted. This is because the DOH memory allocator
grabs a chunk of memory from the C memory allocator and manages the usage internally.
Stale DOH object usage can be checked for by defining <tt>DOH_DEBUG_MEMORY_POOLS</tt> in
<tt>memory.c</tt>. If an attempt to use an object is made after the reference count is
zero, an assertion is triggered instead of quietly re-using the stale object...
</p>
<blockquote>
<pre>
swig: DOH/memory.c:91: DohCheck: Assertion `!DOH_object_already_deleted' failed.
</pre>
</blockquote>
<p>
This can be memory intensive as previously used memory in the pool is not re-used so is
only recommended for diagnosing memory corruption problems.
</p>
<hr>
Copyright (C) 1999-2010 SWIG Development Team.

2
Doc/Devel/tree.html
View file

@ -185,7 +185,7 @@ this function merely records that those attributes did not exist in the original
<blockquote>
This function is similar to <tt>Swig_save()</tt> except that adds additional attribute checking. There are different interpretations
of the attribute names. A name of "attr" merely requests that the function check for the presence of an attribute. If the attribute is missing, SWIG will exit with a failed assertion. An attribute name of "?attr" specifies that the attribute "attr" is optional and
that it's old value must be saved (if any). An attribute name of "*attr" specifies that the attribute is required and that
that its old value must be saved (if any). An attribute name of "*attr" specifies that the attribute is required and that
its value must be saved. The saving of attributes is performed in the same manner as with <tt>Swig_save()</tt>. Here is an example:
<pre>

366
Doc/Manual/Allegrocl.html
View file

@ -1,14 +1,14 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Hand-written HTML -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Allegro Common Lisp</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Allegrocl"></a>17 SWIG and Allegro Common Lisp</H1>
<H1><a name="Allegrocl">18 SWIG and Allegro Common Lisp</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -135,10 +135,10 @@ be unhappy to see some enterprising folk use this work to add
to it.
</p>
<H2><a name="Allegrocl_nn2"></a>17.1 Basics</H2>
<H2><a name="Allegrocl_nn2">18.1 Basics</a></H2>
<H3><a name="Allegrocl_nn3"></a>17.1.1 Running SWIG</H3>
<H3><a name="Allegrocl_nn3">18.1.1 Running SWIG</a></H3>
<p>
@ -360,7 +360,7 @@ need to link in the Allegro shared library. The library you create from
the C++ wrapper will be what you then load into Allegro CL.
</p>
<H3><a name="Allegrocl_nn4"></a>17.1.2 Command Line Options</H3>
<H3><a name="Allegrocl_nn4">18.1.2 Command Line Options</a></H3>
<p>
@ -373,21 +373,21 @@ swig -allegrocl [ options ] filename
-identifier-converter [name] - Binds the variable swig:*swig-identifier-convert*
in the generated .cl file to <tt>name</tt>.
This function is used to generate symbols
for the lisp side of the interface.
This function is used to generate symbols
for the lisp side of the interface.
-cwrap - [default] Generate a .cxx file containing C wrapper function when
wrapping C code. The interface generated is similar to what is
done for C++ code.
done for C++ code.
-nocwrap - Explicitly turn off generation of .cxx wrappers for C code. Reasonable
for modules with simple interfaces. Can not handle all legal enum
and constant constructs, or take advantage of SWIG customization features.
and constant constructs, or take advantage of SWIG customization features.
-isolate - With this command-line argument, all lisp helper functions are defined
in a unique package named <tt>swig.&lt;module-name&gt;</tt> rather than
<tt>swig</tt>. This prevents conflicts when the module is
intended to be used with other swig generated interfaces that may,
for instance, make use of different identifier converters.
<tt>swig</tt>. This prevents conflicts when the module is
intended to be used with other swig generated interfaces that may,
for instance, make use of different identifier converters.
</pre>
</div>
@ -396,7 +396,7 @@ See <a href="#Allegrocl_nn47">Section 17.5 Identifier converter
functions</a> for more details.
</p>
<H3><a name="Allegrocl_nn5"></a>17.1.3 Inserting user code into generated files</H3>
<H3><a name="Allegrocl_nn5">18.1.3 Inserting user code into generated files</a></H3>
<p>
@ -436,7 +436,7 @@ Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
</p>
<H2><a name="Allegrocl_nn6"></a>17.2 Wrapping Overview</H2>
<H2><a name="Allegrocl_nn6">18.2 Wrapping Overview</a></H2>
<p>
@ -446,7 +446,7 @@ New users to SWIG are encouraged to read
interested in generating an interface to C++.
</p>
<H3><a name="Allegrocl_nn7"></a>17.2.1 Function Wrapping</H3>
<H3><a name="Allegrocl_nn7">18.2.1 Function Wrapping</a></H3>
<p>
@ -472,7 +472,7 @@ interested in generating an interface to C++.
| Foreign Code | What we're generating an interface to.
|______________|
|
|
|
_______v______
| | (foreign side)
| Wrapper code | extern "C" wrappers calling C++
@ -484,22 +484,22 @@ interested in generating an interface to C++.
| FFI Layer | Low level lisp interface. ff:def-foreign-call,
|______________| ff:def-foreign-variable
|
+----------------------------
+----------------------------
_______v______ _______v______
| | | | (lisp side)
| Defuns | | Defmethods | wrapper for overloaded
|______________| |______________| functions or those with
(lisp side) | defaulted arguments
Wrapper for non-overloaded |
functions and methods _______v______
| | (lisp side)
| Defuns | dispatch function
|______________| to overloads based
on arity
Wrapper for non-overloaded |
functions and methods _______v______
| | (lisp side)
| Defuns | dispatch function
|______________| to overloads based
on arity
</pre>
</div>
<H3><a name="Allegrocl_nn8"></a>17.2.2 Foreign Wrappers</H3>
<H3><a name="Allegrocl_nn8">18.2.2 Foreign Wrappers</a></H3>
<p>
@ -512,7 +512,7 @@ interested in generating an interface to C++.
typemap.
</p>
<H3><a name="Allegrocl_nn9"></a>17.2.3 FFI Wrappers</H3>
<H3><a name="Allegrocl_nn9">18.2.3 FFI Wrappers</a></H3>
<p>
@ -593,7 +593,7 @@ char *xxx();
ff:def-foreign-call's.
</p>
<H3><a name="Allegrocl_nn10"></a>17.2.4 Non-overloaded Defuns</H3>
<H3><a name="Allegrocl_nn10">18.2.4 Non-overloaded Defuns</a></H3>
<p>
@ -606,7 +606,7 @@ char *xxx();
this function can be manipulated via the <tt>lout</tt> typemap.
</p>
<H3><a name="Allegrocl_nn11"></a>17.2.5 Overloaded Defuns</H3>
<H3><a name="Allegrocl_nn11">18.2.5 Overloaded Defuns</a></H3>
<p>
@ -622,7 +622,7 @@ char *xxx();
can be manipulated via the <tt>lout</tt> typemap.
</p>
<H3><a name="Allegrocl_nn12"></a>17.2.6 What about constant and variable access?</H3>
<H3><a name="Allegrocl_nn12">18.2.6 What about constant and variable access?</a></H3>
<p>
@ -635,7 +635,7 @@ char *xxx();
into the foreign module.
</p>
<H3><a name="Allegrocl_nn13"></a>17.2.7 Object Wrapping</H3>
<H3><a name="Allegrocl_nn13">18.2.7 Object Wrapping</a></H3>
<p>
@ -657,7 +657,7 @@ char *xxx();
foreign function interface.
</p>
<H2><a name="Allegrocl_nn14"></a>17.3 Wrapping Details</H2>
<H2><a name="Allegrocl_nn14">18.3 Wrapping Details</a></H2>
<p>
@ -665,7 +665,7 @@ char *xxx();
translated into lisp.
</p>
<H3><a name="Allegrocl_nn15"></a>17.3.1 Namespaces</H3>
<H3><a name="Allegrocl_nn15">18.3.1 Namespaces</a></H3>
<p>
@ -742,13 +742,13 @@ namespace car {
function such as <tt>(car '(1 2 3)</tt>.
</p>
<H3><a name="Allegrocl_nn16"></a>17.3.2 Constants</H3>
<H3><a name="Allegrocl_nn16">18.3.2 Constants</a></H3>
<p>
Constants, as declared by the preprocessor #define macro or SWIG
<tt>%constant</tt> directive, are included in SWIGs parse tree
<tt>%constant</tt> directive, are included in SWIG's parse tree
when it can be determined that they are, or could be reduced to,
a literal value. Such values are translated into defconstant
forms in the generated lisp wrapper when the -nocwrap command-line
@ -799,11 +799,11 @@ namespace car {
</pre>
</div>
<p>
Users are cautioned to get to know their constants before use, or
not use the <tt>-nocwrap</tt> command-line option.
Users are cautioned to get to know their constants before use, or
not use the <tt>-nocwrap</tt> command-line option.
</p>
<H3><a name="Allegrocl_nn17"></a>17.3.3 Variables</H3>
<H3><a name="Allegrocl_nn17">18.3.3 Variables</a></H3>
<p>
@ -881,13 +881,13 @@ globalvar&gt; (globalvar.nnn::glob_float)
</pre>
</div>
<H3><a name="Allegrocl_nn18"></a>17.3.4 Enumerations</H3>
<H3><a name="Allegrocl_nn18">18.3.4 Enumerations</a></H3>
<p>
In C, an enumeration value is an integer value, while in C++ an
enumeration value is implicitly convertible to an integer value,
but can also be distinguished by it's enum type. For each enum
but can also be distinguished by its enum type. For each enum
declaration a def-foreign-type is generated, assigning the enum
a default type of :int. Users may adjust the foreign type of
enums via SWIG <tt>typemaps</tt>.
@ -901,13 +901,13 @@ globalvar&gt; (globalvar.nnn::glob_float)
of it not being necessary to probe into foreign space to retrieve enum
values. When generating a .cxx wrapper file, a more general solution is
employed. A wrapper variable is created in the module_wrap.cxx file, and
a ff:def-foreign-variable call is generated to retrieve it's value into lisp.
a ff:def-foreign-variable call is generated to retrieve its value into lisp.
</p>
<p>For example, the following header file
<div class="code">enum.h:
<pre>
enum COL { RED, GREEN, BLUE };
enum COL { RED, GREEN, BLUE };
enum FOO { FOO1 = 10, FOO2, FOO3 };
</pre>
</div>
@ -957,7 +957,7 @@ EXPORT const int ACL_ENUM___FOO3__SWIG_0 = FOO3;
</pre>
</div>
<H3><a name="Allegrocl_nn19"></a>17.3.5 Arrays</H3>
<H3><a name="Allegrocl_nn19">18.3.5 Arrays</a></H3>
<p>
@ -1105,10 +1105,10 @@ namespace BAR {
</pre>
</div>
<H3><a name="Allegrocl_nn20"></a>17.3.6 Classes and Structs and Unions (oh my!)</H3>
<H3><a name="Allegrocl_nn20">18.3.6 Classes and Structs and Unions (oh my!)</a></H3>
<H4><a name="Allegrocl_nn21"></a>17.3.6.1 CLOS wrapping of</H4>
<H4><a name="Allegrocl_nn21">18.3.6.1 CLOS wrapping of</a></H4>
<p>
@ -1118,12 +1118,12 @@ namespace BAR {
function that returns an object (or pointer/reference) of C/C++
type <tt>X</tt>, the wrapping defun (or defmethod) on the Lisp
side will automatically wrap the pointer returned in an instance
of the apropriate class. This makes it much easier to write and
of the appropriate class. This makes it much easier to write and
debug code than if pointers were passed around as a jumble of
integer values.
</p>
<H4><a name="Allegrocl_nn22"></a>17.3.6.2 CLOS Inheritance</H4>
<H4><a name="Allegrocl_nn22">18.3.6.2 CLOS Inheritance</a></H4>
<p>
@ -1131,12 +1131,12 @@ namespace BAR {
inheritance of the classes in foreign code, with the
ff:foreign-pointer class at its root. ff:foreign-pointer is a thin
wrapper for pointers that is made available by the foreign function
interface. It's key benefit is that it may be passed as an argument
interface. Its key benefit is that it may be passed as an argument
to any ff:def-foreign-call that is expecting a pointer as the
parameter.
</p>
<H4><a name="Allegrocl_nn23"></a>17.3.6.3 Member fields and functions</H4>
<H4><a name="Allegrocl_nn23">18.3.6.3 Member fields and functions</a></H4>
<p>
@ -1152,7 +1152,7 @@ namespace BAR {
the interface does nothing for <tt>friend</tt> directives,
</p>
<H4><a name="Allegrocl_nn24"></a>17.3.6.4 Why not directly access C++ classes using foreign types?</H4>
<H4><a name="Allegrocl_nn24">18.3.6.4 Why not directly access C++ classes using foreign types?</a></H4>
<p>
@ -1170,34 +1170,34 @@ namespace BAR {
use the more robust wrapper functions.
</p>
<H3><a name="Allegrocl_nn25"></a>17.3.7 Templates</H3>
<H3><a name="Allegrocl_nn25">18.3.7 Templates</a></H3>
<H4><a name="Allegrocl_nn26"></a>17.3.7.1 Generating wrapper code for templates</H4>
<H4><a name="Allegrocl_nn26">18.3.7.1 Generating wrapper code for templates</a></H4>
<p>
SWIG provides support for dealing with templates, but by
default, it will not generate any member variable or function
wrappers for templated classes. In order to create these
wrappers, you need to explicitly tell SWIG to instantiate
them. This is done via the
<a href="SWIGPlus.html#SWIGPlus_nn30"><tt>%template</tt></a>
directive.
</p>
<p>
SWIG provides support for dealing with templates, but by
default, it will not generate any member variable or function
wrappers for templated classes. In order to create these
wrappers, you need to explicitly tell SWIG to instantiate
them. This is done via the
<a href="SWIGPlus.html#SWIGPlus_nn30"><tt>%template</tt></a>
directive.
</p>
<H4><a name="Allegrocl_nn27"></a>17.3.7.2 Implicit Template instantiation</H4>
<H4><a name="Allegrocl_nn27">18.3.7.2 Implicit Template instantiation</a></H4>
<p>
While no wrapper code is generated for accessing member
variables, or calling member functions, type code is generated
to include these templated classes in the foreign-type and CLOS
class schema.
</p>
<p>
While no wrapper code is generated for accessing member
variables, or calling member functions, type code is generated
to include these templated classes in the foreign-type and CLOS
class schema.
</p>
<H3><a name="Allegrocl_nn28"></a>17.3.8 Typedef, Templates, and Synonym Types</H3>
<H3><a name="Allegrocl_nn28">18.3.8 Typedef, Templates, and Synonym Types</a></H3>
<p>
@ -1243,7 +1243,7 @@ int zzz(A *inst = 0); /* return inst-&gt;x + inst-&gt;y */
definition, we generate a form that expands to:
</p>
<div class="targetlang">
<tt>(setf (find-class &lt;synonym&gt;) &lt;primary&gt;)</tt>
<tt>(setf (find-class &lt;synonym&gt;) &lt;primary&gt;)</tt>
</div>
<p>
The result is that all references to synonym types in foreign
@ -1277,7 +1277,7 @@ synonym&gt;
</pre>
</div>
<H4><a name="Allegrocl_nn29"></a>17.3.8.1 Choosing a primary type</H4>
<H4><a name="Allegrocl_nn29">18.3.8.1 Choosing a primary type</a></H4>
<p>
@ -1285,20 +1285,20 @@ synonym&gt;
criteria from a set of synonym types.
</p>
<ul>
<li>
If a synonym type has a class definition, it is the primary type.
</li>
<li>
If a synonym type is a class template and has been explicitly
instantiated via <tt>%template</tt>, it is the primary type.
</li>
<li>
For all other sets of synonymous types, the synonym which is
parsed first becomes the primary type.
</li>
<li>
If a synonym type has a class definition, it is the primary type.
</li>
<li>
If a synonym type is a class template and has been explicitly
instantiated via <tt>%template</tt>, it is the primary type.
</li>
<li>
For all other sets of synonymous types, the synonym which is
parsed first becomes the primary type.
</li>
</ul>
<H3><a name="Allegrocl_nn30"></a>17.3.9 Function overloading/Parameter defaulting</H3>
<H3><a name="Allegrocl_nn30">18.3.9 Function overloading/Parameter defaulting</a></H3>
<p>
@ -1461,7 +1461,7 @@ overload&gt;
</pre>
</div>
<H3><a name="Allegrocl_nn31"></a>17.3.10 Operator wrapping and Operator overloading</H3>
<H3><a name="Allegrocl_nn31">18.3.10 Operator wrapping and Operator overloading</a></H3>
<p>
@ -1472,68 +1472,68 @@ overload&gt;
<pre>
/* name conversion for overloaded operators. */
#ifdef __cplusplus
%rename(__add__) *::operator+;
%rename(__pos__) *::operator+();
%rename(__pos__) *::operator+() const;
%rename(__add__) *::operator+;
%rename(__pos__) *::operator+();
%rename(__pos__) *::operator+() const;
%rename(__sub__) *::operator-;
%rename(__neg__) *::operator-() const;
%rename(__neg__) *::operator-();
%rename(__sub__) *::operator-;
%rename(__neg__) *::operator-() const;
%rename(__neg__) *::operator-();
%rename(__mul__) *::operator*;
%rename(__deref__) *::operator*();
%rename(__deref__) *::operator*() const;
%rename(__mul__) *::operator*;
%rename(__deref__) *::operator*();
%rename(__deref__) *::operator*() const;
%rename(__div__) *::operator/;
%rename(__mod__) *::operator%;
%rename(__logxor__) *::operator^;
%rename(__logand__) *::operator&amp;;
%rename(__logior__) *::operator|;
%rename(__lognot__) *::operator~();
%rename(__lognot__) *::operator~() const;
%rename(__div__) *::operator/;
%rename(__mod__) *::operator%;
%rename(__logxor__) *::operator^;
%rename(__logand__) *::operator&amp;;
%rename(__logior__) *::operator|;
%rename(__lognot__) *::operator~();
%rename(__lognot__) *::operator~() const;
%rename(__not__) *::operator!();
%rename(__not__) *::operator!() const;
%rename(__not__) *::operator!();
%rename(__not__) *::operator!() const;
%rename(__assign__) *::operator=;
%rename(__assign__) *::operator=;
%rename(__add_assign__) *::operator+=;
%rename(__sub_assign__) *::operator-=;
%rename(__mul_assign__) *::operator*=;
%rename(__div_assign__) *::operator/=;
%rename(__mod_assign__) *::operator%=;
%rename(__sub_assign__) *::operator-=;
%rename(__mul_assign__) *::operator*=;
%rename(__div_assign__) *::operator/=;
%rename(__mod_assign__) *::operator%=;
%rename(__logxor_assign__) *::operator^=;
%rename(__logand_assign__) *::operator&amp;=;
%rename(__logior_assign__) *::operator|=;
%rename(__lshift__) *::operator&lt;&lt;;
%rename(__lshift__) *::operator&lt;&lt;;
%rename(__lshift_assign__) *::operator&lt;&lt;=;
%rename(__rshift__) *::operator&gt;&gt;;
%rename(__rshift__) *::operator&gt;&gt;;
%rename(__rshift_assign__) *::operator&gt;&gt;=;
%rename(__eq__) *::operator==;
%rename(__ne__) *::operator!=;
%rename(__lt__) *::operator&lt;;
%rename(__gt__) *::operator&gt;;
%rename(__lte__) *::operator&lt;=;
%rename(__gte__) *::operator&gt;=;
%rename(__eq__) *::operator==;
%rename(__ne__) *::operator!=;
%rename(__lt__) *::operator&lt;;
%rename(__gt__) *::operator&gt;;
%rename(__lte__) *::operator&lt;=;
%rename(__gte__) *::operator&gt;=;
%rename(__and__) *::operator&amp;&amp;;
%rename(__or__) *::operator||;
%rename(__and__) *::operator&amp;&amp;;
%rename(__or__) *::operator||;
%rename(__preincr__) *::operator++();
%rename(__postincr__) *::operator++(int);
%rename(__predecr__) *::operator--();
%rename(__postdecr__) *::operator--(int);
%rename(__preincr__) *::operator++();
%rename(__postincr__) *::operator++(int);
%rename(__predecr__) *::operator--();
%rename(__postdecr__) *::operator--(int);
%rename(__comma__) *::operator,();
%rename(__comma__) *::operator,() const;
%rename(__comma__) *::operator,();
%rename(__comma__) *::operator,() const;
%rename(__member_ref__) *::operator-&gt;;
%rename(__member_func_ref__) *::operator-&gt;*;
%rename(__funcall__) *::operator();
%rename(__aref__) *::operator[];
%rename(__funcall__) *::operator();
%rename(__aref__) *::operator[];
</pre>
</div>
@ -1607,28 +1607,28 @@ opoverload&gt;
</pre>
</div>
<H3><a name="Allegrocl_nn32"></a>17.3.11 Varargs</H3>
<H3><a name="Allegrocl_nn32">18.3.11 Varargs</a></H3>
<p>
Variable length argument lists are not supported, by default. If
such a function is encountered, a warning will generated to
stderr. Varargs are supported via the SWIG <tt>%vararg</tt>
stderr. Varargs are supported via the SWIG <tt>%varargs</tt>
directive. This directive allows you to specify a (finite)
argument list which will be inserted into the wrapper in place
of the variable length argument indicator. As an example,
consider the function <tt>printf()</tt>. It's declaration would
consider the function <tt>printf()</tt>. Its declaration would
appear as follows:
</p>
<p>
See the following section
on <a href="Varargs.html#Varargs">Variable Length arguments</a>
provides examples on how <tt>%vararg</tt> can be used, along
provides examples on how <tt>%varargs</tt> can be used, along
with other ways such functions can be wrapped.
</p>
<H3><a name="Allegrocl_nn33"></a>17.3.12 C++ Exceptions</H3>
<H3><a name="Allegrocl_nn33">18.3.12 C++ Exceptions</a></H3>
<p>
@ -1640,7 +1640,7 @@ opoverload&gt;
implemented.
</p>
<H3><a name="Allegrocl_nn34"></a>17.3.13 Pass by value, pass by reference</H3>
<H3><a name="Allegrocl_nn34">18.3.13 Pass by value, pass by reference</a></H3>
<p>
@ -1652,7 +1652,7 @@ opoverload&gt;
newly defined types.
</p>
<H2><a name="Allegrocl_nn35"></a>17.4 Typemaps</H2>
<H2><a name="Allegrocl_nn35">18.4 Typemaps</a></H2>
<p>
@ -1663,7 +1663,7 @@ opoverload&gt;
on <a href="Typemaps.html#Typemaps">Typemaps</a> for more information.
</p>
<H3><a name="Allegrocl_nn36"></a>17.4.1 Code Generation in the C++ Wrapper</H3>
<H3><a name="Allegrocl_nn36">18.4.1 Code Generation in the C++ Wrapper</a></H3>
@ -1693,7 +1693,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn37"></a>17.4.1.1 IN Typemap</H4>
<H4><a name="Allegrocl_nn37">18.4.1.1 IN Typemap</a></H4>
<p>
@ -1728,14 +1728,14 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn38"></a>17.4.1.2 OUT Typemap</H4>
<H4><a name="Allegrocl_nn38">18.4.1.2 OUT Typemap</a></H4>
<p>
The <tt>out</tt> typemap is used to generate code to form the
return value of the wrapper from the return value of the wrapped
function. This code is placed in the &lt;convert and bind result to lresult&gt;
section of the above code diagram. It's default mapping is as follows:
section of the above code diagram. Its default mapping is as follows:
</p>
<div class="code">
@ -1752,13 +1752,13 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn39"></a>17.4.1.3 CTYPE Typemap</H4>
<H4><a name="Allegrocl_nn39">18.4.1.3 CTYPE Typemap</a></H4>
<p>
This typemap is not used for code generation, but purely for the
transformation of types in the parameter list of the wrapper function.
It's primary use is to handle by-value to by-reference conversion in the
Its primary use is to handle by-value to by-reference conversion in the
wrappers parameter list. Its default settings are:
</p>
@ -1784,7 +1784,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
these <a href="Typemaps.html#Typemaps_nn25">common typemaps</a> here.
</p>
<H3><a name="Allegrocl_nn40"></a>17.4.2 Code generation in Lisp wrappers</H3>
<H3><a name="Allegrocl_nn40">18.4.2 Code generation in Lisp wrappers</a></H3>
<p>
@ -1803,7 +1803,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
<a href="#Allegrocl_nn15">16.3.1 Namespaces</a> for details.
</p>
<H4><a name="Allegrocl_nn41"></a>17.4.2.1 LIN Typemap</H4>
<H4><a name="Allegrocl_nn41">18.4.2.1 LIN Typemap</a></H4>
<p>
@ -1821,32 +1821,32 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
<p>The LIN typemap accepts the following <tt>$variable</tt> references.
</p>
<ul>
<li><tt>$in</tt> - expands to the name of the parameter being
applied to this typemap
</li>
<li><tt>$out</tt> - expands to the name of the local variable
assigned to this typemap
</li>
<li><tt>$in_fftype</tt> - the foreign function type of the C type.</li>
<li><tt>$*in_fftype</tt> - the foreign function type of the C type
with one pointer removed. If there is no pointer, then $*in_fftype
is the same as $in_fftype.
</li>
<li><tt>$body</tt> - very important. Instructs SWIG where
subsequent code generation steps should be inserted into the
current typemap. Leaving out a <tt>$body</tt> reference
will result in lisp wrappers that do very little by way of
calling into foreign code. Not recommended.
</li>
<li><tt>$in</tt> - expands to the name of the parameter being
applied to this typemap
</li>
<li><tt>$out</tt> - expands to the name of the local variable
assigned to this typemap
</li>
<li><tt>$in_fftype</tt> - the foreign function type of the C type.</li>
<li><tt>$*in_fftype</tt> - the foreign function type of the C type
with one pointer removed. If there is no pointer, then $*in_fftype
is the same as $in_fftype.
</li>
<li><tt>$body</tt> - very important. Instructs SWIG where
subsequent code generation steps should be inserted into the
current typemap. Leaving out a <tt>$body</tt> reference
will result in lisp wrappers that do very little by way of
calling into foreign code. Not recommended.
</li>
</ul>
<div class="code">
<pre>
%typemap(lin) SWIGTYPE "(cl:let (($out $in))\n $body)";
%typemap(lin) SWIGTYPE "(cl:let (($out $in))\n $body)";
</pre>
</div>
<H4><a name="Allegrocl_nn42"></a>17.4.2.2 LOUT Typemap</H4>
<H4><a name="Allegrocl_nn42">18.4.2.2 LOUT Typemap</a></H4>
<p>
@ -1858,17 +1858,17 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
<p>The LOUT typemap uses the following $variable
</p>
<ul>
<li><tt>$lclass</tt> - Expands to the CLOS class that
represents foreign-objects of the return type matching this
typemap.
</li>
<li><tt>$body</tt> - Same as for the LIN map. Place this
variable where you want the foreign-function call to occur.
</li>
<li><tt>$ldestructor</tt> - Expands to the symbol naming the destructor for this
class ($lclass) of object. Allows you to insert finalization or automatic garbage
collection into the wrapper code (see default mappings below).
</li>
<li><tt>$lclass</tt> - Expands to the CLOS class that
represents foreign-objects of the return type matching this
typemap.
</li>
<li><tt>$body</tt> - Same as for the LIN map. Place this
variable where you want the foreign-function call to occur.
</li>
<li><tt>$ldestructor</tt> - Expands to the symbol naming the destructor for this
class ($lclass) of object. Allows you to insert finalization or automatic garbage
collection into the wrapper code (see default mappings below).
</li>
</ul>
<div class="code">
@ -1889,7 +1889,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn43"></a>17.4.2.3 FFITYPE Typemap</H4>
<H4><a name="Allegrocl_nn43">18.4.2.3 FFITYPE Typemap</a></H4>
@ -1939,7 +1939,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn44"></a>17.4.2.4 LISPTYPE Typemap</H4>
<H4><a name="Allegrocl_nn44">18.4.2.4 LISPTYPE Typemap</a></H4>
<p>
@ -1959,7 +1959,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H4><a name="Allegrocl_nn45"></a>17.4.2.5 LISPCLASS Typemap</H4>
<H4><a name="Allegrocl_nn45">18.4.2.5 LISPCLASS Typemap</a></H4>
<p>
@ -1983,7 +1983,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H3><a name="Allegrocl_nn46"></a>17.4.3 Modifying SWIG behavior using typemaps</H3>
<H3><a name="Allegrocl_nn46">18.4.3 Modifying SWIG behavior using typemaps</a></H3>
<p>
@ -2017,10 +2017,10 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</pre>
</div>
<H2><a name="Allegrocl_nn47"></a>17.5 Identifier Converter functions</H2>
<H2><a name="Allegrocl_nn47">18.5 Identifier Converter functions</a></H2>
<H3><a name="Allegrocl_nn48"></a>17.5.1 Creating symbols in the lisp environment</H3>
<H3><a name="Allegrocl_nn48">18.5.1 Creating symbols in the lisp environment</a></H3>
<p>
@ -2041,11 +2041,11 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
of arguments.
</p>
<H3><a name="Allegrocl_nn49"></a>17.5.2 Existing identifier-converter functions</H3>
<H3><a name="Allegrocl_nn49">18.5.2 Existing identifier-converter functions</a></H3>
<p>Two basic identifier routines have been defined.
<H4><a name="Allegrocl_nn50"></a>17.5.2.1 identifier-convert-null</H4>
<H4><a name="Allegrocl_nn50">18.5.2.1 identifier-convert-null</a></H4>
<p>
@ -2054,7 +2054,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
strings, from which a symbol will be created.
</p>
<H4><a name="Allegrocl_nn51"></a>17.5.2.2 identifier-convert-lispify</H4>
<H4><a name="Allegrocl_nn51">18.5.2.2 identifier-convert-lispify</a></H4>
<p>
@ -2063,7 +2063,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
same symbol transformations.
</p>
<H4><a name="Allegrocl_nn52"></a>17.5.2.3 Default identifier to symbol conversions</H4>
<H4><a name="Allegrocl_nn52">18.5.2.3 Default identifier to symbol conversions</a></H4>
<p>
@ -2072,7 +2072,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
default naming conventions.
</p>
<H3><a name="Allegrocl_nn53"></a>17.5.3 Defining your own identifier-converter</H3>
<H3><a name="Allegrocl_nn53">18.5.3 Defining your own identifier-converter</a></H3>
<p>
@ -2093,7 +2093,7 @@ foreign environment.
<p>
The :type keyword argument provides more information on the type of
identifier. It's value is a symbol. This allows the
identifier. Its value is a symbol. This allows the
identifier-converter to apply different heuristics when mapping
different types of identifiers to symbols. SWIG will generate calls
to your identifier-converter using the following types.
@ -2123,12 +2123,12 @@ scope in the specified class.
<p>
The :arity keyword argument only appears in swig:swig-defmethod forms
generated for overloaded functions. It's value is an integer
generated for overloaded functions. Its value is an integer
indicating the number of arguments passed to the routine indicated by
this identifier.
</p>
<H3><a name="Allegrocl_nn54"></a>17.5.4 Instructing SWIG to use a particular identifier-converter</H3>
<H3><a name="Allegrocl_nn54">18.5.4 Instructing SWIG to use a particular identifier-converter</a></H3>
<p>

83
Doc/Manual/Android.html
View file

@ -1,11 +1,12 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Android</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Android"></a>18 SWIG and Android</H1>
<H1><a name="Android">19 SWIG and Android</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -15,7 +16,9 @@
<li><a href="#Android_examples_intro">Examples introduction</a>
<li><a href="#Android_example_simple">Simple C example</a>
<li><a href="#Android_example_class">C++ class example</a>
<li><a href="#Android_examples_other">Other examples</a>
</ul>
<li><a href="#Android_stl">C++ STL</a>
</ul>
</div>
<!-- INDEX -->
@ -28,24 +31,24 @@ This chapter describes SWIG's support of Android.
<H2><a name="Android_overview"></a>18.1 Overview</H2>
<H2><a name="Android_overview">19.1 Overview</a></H2>
<p>
The Android chapter is fairly short as support for Android is the same as for Java, where the Java Native Interface (JNI) is
used to call from Android Java into C or C++ compiled code.
Everything in the <a href="Java.html">Java chapter</a> applies to generating code for access from Android Java code.
Everything in the <a href="Java.html#Java">Java chapter</a> applies to generating code for access from Android Java code.
This chapter contains a few Android specific notes and examples.
</p>
<H2><a name="Android_examples"></a>18.2 Android examples</H2>
<H2><a name="Android_examples">19.2 Android examples</a></H2>
<H3><a name="Android_examples_intro"></a>18.2.1 Examples introduction</H3>
<H3><a name="Android_examples_intro">19.2.1 Examples introduction</a></H3>
<p>
The examples require the the <a href="http://developer.android.com/sdk/index.html">Android SDK</a> and <a href="http://developer.android.com/sdk/ndk/index.html">Android NDK</a> which can be installed as per instructions in the links.
The examples require the <a href="http://developer.android.com/sdk/index.html">Android SDK</a> and <a href="http://developer.android.com/tools/sdk/ndk/index.html">Android NDK</a> which can be installed as per instructions in the links.
The Eclipse version is not required for these examples as just the command line tools are used (shown for Linux as the host, but Windows will be very similar, if not identical in most places).
Add the SDK tools and NDK tools to your path and create a directory somewhere for your Android projects (adjust PATH as necessary to where you installed the tools):
</p>
@ -54,7 +57,7 @@ Add the SDK tools and NDK tools to your path and create a directory somewhere fo
<pre>
$ export PATH=$HOME/android/android-sdk-linux_x86/tools:$HOME/android/android-sdk-linux_x86/platform-tools:$HOME/android/android-ndk-r6b:$PATH
$ mkdir AndroidApps
$ cd AnrdoidApps
$ cd AndroidApps
</pre>
</div>
@ -74,7 +77,7 @@ $ android list targets
The following examples are shipped with SWIG under the Examples/android directory and include a Makefile to build and install each example.
</p>
<H3><a name="Android_example_simple"></a>18.2.2 Simple C example</H3>
<H3><a name="Android_example_simple">19.2.2 Simple C example</a></H3>
<p>
@ -207,7 +210,7 @@ When complete your device should be listed in those attached, something like:
<pre>
$ adb devices
List of devices attached
A32-6DBE0001-9FF80000-015D62C3-02018028 device
A32-6DBE0001-9FF80000-015D62C3-02018028 device
</pre>
</div>
@ -219,7 +222,7 @@ This means you are now ready to install the application...
<pre>
$ adb install bin/SwigSimple-debug.apk
95 KB/s (4834 bytes in 0.049s)
pkg: /data/local/tmp/SwigSimple-debug.apk
pkg: /data/local/tmp/SwigSimple-debug.apk
Success
</pre>
</div>
@ -396,7 +399,7 @@ Run the app again and this time you will see the output pictured below, showing
<center><img src="android-simple.png" alt="Android screenshot of SwigSimple example"></center>
<H3><a name="Android_example_class"></a>18.2.3 C++ class example</H3>
<H3><a name="Android_example_class">19.2.3 C++ class example</a></H3>
<p>
@ -433,11 +436,11 @@ public:
}
virtual ~Shape() {
nshapes--;
};
}
double x, y;
void move(double dx, double dy);
virtual double area(void) = 0;
virtual double perimeter(void) = 0;
virtual double area() = 0;
virtual double perimeter() = 0;
static int nshapes;
};
@ -445,18 +448,18 @@ class Circle : public Shape {
private:
double radius;
public:
Circle(double r) : radius(r) { };
virtual double area(void);
virtual double perimeter(void);
Circle(double r) : radius(r) { }
virtual double area();
virtual double perimeter();
};
class Square : public Shape {
private:
double width;
public:
Square(double w) : width(w) { };
virtual double area(void);
virtual double perimeter(void);
Square(double w) : width(w) { }
virtual double area();
virtual double perimeter();
};
</pre>
</div>
@ -480,19 +483,19 @@ void Shape::move(double dx, double dy) {
int Shape::nshapes = 0;
double Circle::area(void) {
double Circle::area() {
return M_PI*radius*radius;
}
double Circle::perimeter(void) {
double Circle::perimeter() {
return 2*M_PI*radius;
}
double Square::area(void) {
double Square::area() {
return width*width;
}
double Square::perimeter(void) {
double Square::perimeter() {
return 4*width;
}
</pre>
@ -744,6 +747,36 @@ Run the app to see the result of calling the C++ code from Java:
<center><img src="android-class.png" alt="Android screenshot of SwigClass example"></center>
<H3><a name="Android_examples_other">19.2.4 Other examples</a></H3>
<p>
The Examples/android directory contains further examples which can be run and installed in a similar manner to the previous two examples.
</p>
<p>
Note that the 'extend' example is demonstrates the directors feature.
Normally C++ exception handling and the STL is not available by default in the version of g++ shipped with Android, but this example turns these features on as described in the next section.
</p>
<H2><a name="Android_stl">19.3 C++ STL</a></H2>
<p>
Should the C++ Standard Template Library (STL) be required, an <tt>Application.mk</tt> file needs to be created
in the same directory as the <tt>Android.mk</tt> directory containing information about the STL to use.
See the NDK documentation in the $NDKROOT/docs folder especially CPLUSPLUS-SUPPORT.html.
Below is an example of the <tt>Application.mk</tt> file to make the STLport static library available for use:
</p>
<div class="code">
<pre>
# File: Application.mk
APP_STL := gnustl_static
</pre>
</div>
</body>
</html>

35
Doc/Manual/Arguments.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Argument Handling</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Arguments"></a>9 Argument Handling</H1>
<H1><a name="Arguments">10 Argument Handling</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -42,7 +43,7 @@ return multiple values through the arguments of a function. This chapter
describes some of the techniques for doing this.
</p>
<H2><a name="Arguments_nn2"></a>9.1 The typemaps.i library</H2>
<H2><a name="Arguments_nn2">10.1 The typemaps.i library</a></H2>
<p>
@ -50,7 +51,7 @@ This section describes the <tt>typemaps.i</tt> library file--commonly used to
change certain properties of argument conversion.
</p>
<H3><a name="Arguments_nn3"></a>9.1.1 Introduction</H3>
<H3><a name="Arguments_nn3">10.1.1 Introduction</a></H3>
<p>
@ -59,7 +60,7 @@ Suppose you had a C function like this:
<div class="code"><pre>
void add(double a, double b, double *result) {
*result = a + b;
*result = a + b;
}
</pre></div>
@ -194,7 +195,7 @@ else. To clear a typemap, the <tt>%clear</tt> directive should be used. For e
</pre>
</div>
<H3><a name="Arguments_nn4"></a>9.1.2 Input parameters</H3>
<H3><a name="Arguments_nn4">10.1.2 Input parameters</a></H3>
<p>
@ -203,7 +204,7 @@ input value:
</p>
<div class="code"><pre>
int *INPUT
int *INPUT
short *INPUT
long *INPUT
unsigned int *INPUT
@ -220,7 +221,7 @@ function:
<div class="code"><pre>
double add(double *a, double *b) {
return *a+*b;
return *a+*b;
}
</pre></div>
@ -247,7 +248,7 @@ When the function is used in the scripting language interpreter, it will work li
result = add(3,4)
</pre></div>
<H3><a name="Arguments_nn5"></a>9.1.3 Output parameters</H3>
<H3><a name="Arguments_nn5">10.1.3 Output parameters</a></H3>
<p>
@ -272,7 +273,7 @@ These methods can be used as shown in an earlier example. For example, if you ha
<div class="code"><pre>
void add(double a, double b, double *c) {
*c = a+b;
*c = a+b;
}
</pre></div>
@ -314,7 +315,7 @@ iresult, dresult = foo(3.5, 2)
</pre>
</div>
<H3><a name="Arguments_nn6"></a>9.1.4 Input/Output parameters</H3>
<H3><a name="Arguments_nn6">10.1.4 Input/Output parameters</a></H3>
<p>
@ -338,7 +339,7 @@ A C function that uses this might be something like this:</p>
<div class="code"><pre>
void negate(double *x) {
*x = -(*x);
*x = -(*x);
}
</pre></div>
@ -379,7 +380,7 @@ rather than directly overwriting the value of the original input object.
SWIG. Backwards compatibility is preserved, but deprecated.
</p>
<H3><a name="Arguments_nn7"></a>9.1.5 Using different names</H3>
<H3><a name="Arguments_nn7">10.1.5 Using different names</a></H3>
<p>
@ -413,7 +414,7 @@ Typemap declarations are lexically scoped so a typemap takes effect from the poi
file or a matching <tt>%clear</tt> declaration.
</p>
<H2><a name="Arguments_nn8"></a>9.2 Applying constraints to input values</H2>
<H2><a name="Arguments_nn8">10.2 Applying constraints to input values</a></H2>
<p>
@ -423,7 +424,7 @@ insure that a value is positive, or that a pointer is non-NULL. This
can be accomplished including the <tt>constraints.i</tt> library file.
</p>
<H3><a name="Arguments_nn9"></a>9.2.1 Simple constraint example</H3>
<H3><a name="Arguments_nn9">10.2.1 Simple constraint example</a></H3>
<p>
@ -449,7 +450,7 @@ the arguments violate the constraint condition, a scripting language
exception will be raised. As a result, it is possible to catch bad
values, prevent mysterious program crashes and so on.</p>
<H3><a name="Arguments_nn10"></a>9.2.2 Constraint methods</H3>
<H3><a name="Arguments_nn10">10.2.2 Constraint methods</a></H3>
<p>
@ -465,7 +466,7 @@ NONNULL Non-NULL pointer (pointers only).
</pre></div>
<H3><a name="Arguments_nn11"></a>9.2.3 Applying constraints to new datatypes</H3>
<H3><a name="Arguments_nn11">10.2.3 Applying constraints to new datatypes</a></H3>
<p>

474
Doc/Manual/CCache.html Normal file
View file

@ -0,0 +1,474 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>ccache-swig(1) manpage</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="CCache">17 Using SWIG with ccache - ccache-swig(1) manpage</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#CCache_nn2">NAME</a>
<li><a href="#CCache_nn3">SYNOPSIS</a>
<li><a href="#CCache_nn4">DESCRIPTION</a>
<li><a href="#CCache_nn5">OPTIONS SUMMARY</a>
<li><a href="#CCache_nn6">OPTIONS</a>
<li><a href="#CCache_nn7">INSTALLATION</a>
<li><a href="#CCache_nn8">EXTRA OPTIONS</a>
<li><a href="#CCache_nn9">ENVIRONMENT VARIABLES</a>
<li><a href="#CCache_nn10">CACHE SIZE MANAGEMENT</a>
<li><a href="#CCache_nn11">CACHE COMPRESSION</a>
<li><a href="#CCache_nn12">HOW IT WORKS</a>
<li><a href="#CCache_nn13">USING CCACHE WITH DISTCC</a>
<li><a href="#CCache_nn14">SHARING A CACHE</a>
<li><a href="#CCache_nn15">HISTORY</a>
<li><a href="#CCache_nn16">DIFFERENCES FROM COMPILERCACHE</a>
<li><a href="#CCache_nn17">CREDITS</a>
<li><a href="#CCache_nn18">AUTHOR</a>
</ul>
</div>
<!-- INDEX -->
<p>
<H2><a name="CCache_nn2">17.1 NAME</a></H2>
<p>
ccache-swig - a fast compiler cache
<p>
<H2><a name="CCache_nn3">17.2 SYNOPSIS</a></H2>
<p>
ccache-swig [OPTION]
<p>
ccache-swig &lt;compiler&gt; [COMPILER OPTIONS]
<p>
&lt;compiler&gt; [COMPILER OPTIONS]
<p>
<H2><a name="CCache_nn4">17.3 DESCRIPTION</a></H2>
<p>
ccache-swig is a compiler cache. It speeds up re-compilation of C/C++/SWIG code
by caching previous compiles and detecting when the same compile is
being done again. ccache-swig is ccache plus support for SWIG. ccache
and ccache-swig are used interchangeably in this document.
<p>
<H2><a name="CCache_nn5">17.4 OPTIONS SUMMARY</a></H2>
<p>
Here is a summary of the options to ccache-swig.
<p>
<pre>
-s show statistics summary
-z zero statistics
-c run a cache cleanup
-C clear the cache completely
-F &lt;n&gt; set maximum files in cache
-M &lt;n&gt; set maximum size of cache (use G, M or K)
-h this help page
-V print version number
</pre>
<p>
<H2><a name="CCache_nn6">17.5 OPTIONS</a></H2>
<p>
These options only apply when you invoke ccache as "ccache-swig". When
invoked as a compiler none of these options apply. In that case your
normal compiler options apply and you should refer to your compilers
documentation.
<p>
<dl>
<p><dt><strong><strong>-h</strong></strong><dd> Print a options summary page
<p>
<p><dt><strong><strong>-s</strong></strong><dd> Print the current statistics summary for the cache. The
statistics are stored spread across the subdirectories of the
cache. Using "ccache-swig -s" adds up the statistics across all
subdirectories and prints the totals.
<p>
<p><dt><strong><strong>-z</strong></strong><dd> Zero the cache statistics.
<p>
<p><dt><strong><strong>-V</strong></strong><dd> Print the ccache version number
<p>
<p><dt><strong><strong>-c</strong></strong><dd> Clean the cache and re-calculate the cache file count and
size totals. Normally the -c option should not be necessary as ccache
keeps the cache below the specified limits at runtime and keeps
statistics up to date on each compile. This option is mostly useful
if you manually modify the cache contents or believe that the cache
size statistics may be inaccurate.
<p>
<p><dt><strong><strong>-C</strong></strong><dd> Clear the entire cache, removing all cached files.
<p>
<p><dt><strong><strong>-F &lt;maxfiles&gt;</strong></strong><dd> This sets the maximum number of files allowed in
the cache. The value is stored inside the cache directory and applies
to all future compiles. Due to the way the value is stored the actual
value used is always rounded down to the nearest multiple of 16.
<p>
<p><dt><strong><strong>-M &lt;maxsize&gt;</strong></strong><dd> This sets the maximum cache size. You can specify
a value in gigabytes, megabytes or kilobytes by appending a G, M or K
to the value. The default is gigabytes. The actual value stored is
rounded down to the nearest multiple of 16 kilobytes.
<p>
</dl>
<p>
<H2><a name="CCache_nn7">17.6 INSTALLATION</a></H2>
<p>
There are two ways to use ccache. You can either prefix your compile
commands with "ccache-swig" or you can create a symbolic link between
ccache-swig and the names of your compilers. The first method is most
convenient if you just want to try out ccache or wish to use it for
some specific projects. The second method is most useful for when you
wish to use ccache for all your compiles.
<p>
To install for usage by the first method just copy ccache-swig to somewhere
in your path.
<p>
To install for the second method do something like this:
<pre>
cp ccache-swig /usr/local/bin/
ln -s /usr/local/bin/ccache-swig /usr/local/bin/gcc
ln -s /usr/local/bin/ccache-swig /usr/local/bin/g++
ln -s /usr/local/bin/ccache-swig /usr/local/bin/cc
ln -s /usr/local/bin/ccache-swig /usr/local/bin/swig
</pre>
This will work as long as /usr/local/bin comes before the path to gcc
(which is usually in /usr/bin). After installing you may wish to run
"which gcc" to make sure that the correct link is being used.
<p>
Note! Do not use a hard link, use a symbolic link. A hardlink will
cause "interesting" problems.
<p>
<H2><a name="CCache_nn8">17.7 EXTRA OPTIONS</a></H2>
<p>
When run as a compiler front end ccache usually just takes the same
command line options as the compiler you are using. The only exception
to this is the option '--ccache-skip'. That option can be used to tell
ccache that the next option is definitely not a input filename, and
should be passed along to the compiler as-is.
<p>
The reason this can be important is that ccache does need to parse the
command line and determine what is an input filename and what is a
compiler option, as it needs the input filename to determine the name
of the resulting object file (among other things). The heuristic
ccache uses in this parse is that any string on the command line that
exists as a file is treated as an input file name (usually a C
file). By using --ccache-skip you can force an option to not be
treated as an input file name and instead be passed along to the
compiler as a command line option.
<p>
<H2><a name="CCache_nn9">17.8 ENVIRONMENT VARIABLES</a></H2>
<p>
ccache uses a number of environment variables to control operation. In
most cases you won't need any of these as the defaults will be fine.
<p>
<dl>
<p>
<p><dt><strong><strong>CCACHE_DIR</strong></strong><dd> the CCACHE_DIR environment variable specifies
where ccache will keep its cached compiler output. The default is
"$HOME/.ccache".
<p>
<p><dt><strong><strong>CCACHE_TEMPDIR</strong></strong><dd> the CCACHE_TEMPDIR environment variable specifies
where ccache will put temporary files. The default is the same as
CCACHE_DIR. Note that the CCACHE_TEMPDIR path must be on the same
filesystem as the CCACHE_DIR path, so that renames of files between
the two directories can work.
<p>
<p><dt><strong><strong>CCACHE_LOGFILE</strong></strong><dd> If you set the CCACHE_LOGFILE environment
variable then ccache will write some log information on cache hits
and misses in that file. This is useful for tracking down problems.
<p>
<p><dt><strong><strong>CCACHE_VERBOSE</strong></strong><dd> If you set the CCACHE_VERBOSE environment
variable then ccache will display on stdout all the compiler invocations
that it makes. This can useful for debugging unexpected problems.
<p>
<p><dt><strong><strong>CCACHE_PATH</strong></strong><dd> You can optionally set CCACHE_PATH to a colon
separated path where ccache will look for the real compilers. If you
don't do this then ccache will look for the first executable matching
the compiler name in the normal PATH that isn't a symbolic link to
ccache itself.
<p>
<p><dt><strong><strong>CCACHE_CC</strong></strong><dd> You can optionally set CCACHE_CC to force the name
of the compiler to use. If you don't do this then ccache works it out
from the command line.
<p>
<p><dt><strong><strong>CCACHE_PREFIX</strong></strong><dd> This option adds a prefix to the command line
that ccache runs when invoking the compiler. Also see the section
below on using ccache with distcc.
<p>
<p><dt><strong><strong>CCACHE_DISABLE</strong></strong><dd> If you set the environment variable
CCACHE_DISABLE then ccache will just call the real compiler,
bypassing the cache completely.
<p>
<p><dt><strong><strong>CCACHE_READONLY</strong></strong><dd> the CCACHE_READONLY environment variable
tells ccache to attempt to use existing cached object files, but not
to try to add anything new to the cache. If you are using this because
your CCACHE_DIR is read-only, then you may find that you also need to
set CCACHE_TEMPDIR as otherwise ccache will fail to create the
temporary files.
<p>
<p><dt><strong><strong>CCACHE_CPP2</strong></strong><dd> If you set the environment variable CCACHE_CPP2
then ccache will not use the optimisation of avoiding the 2nd call to
the pre-processor by compiling the pre-processed output that was used
for finding the hash in the case of a cache miss. This is primarily a
debugging option, although it is possible that some unusual compilers
will have problems with the intermediate filename extensions used in
this optimisation, in which case this option could allow ccache to be
used.
<p>
<p><dt><strong><strong>CCACHE_NOCOMPRESS</strong></strong><dd> If you set the environment variable
CCACHE_NOCOMPRESS then there is no compression used on files that go
into the cache. However, this setting has no effect on how files are
retrieved from the cache, compressed results will still be usable.
<p>
<p><dt><strong><strong>CCACHE_NOSTATS</strong></strong><dd> If you set the environment variable
CCACHE_NOSTATS then ccache will not update the statistics files on
each compile.
<p>
<p><dt><strong><strong>CCACHE_NLEVELS</strong></strong><dd> The environment variable CCACHE_NLEVELS allows
you to choose the number of levels of hash in the cache directory. The
default is 2. The minimum is 1 and the maximum is 8.
<p>
<p><dt><strong><strong>CCACHE_HARDLINK</strong></strong><dd> If you set the environment variable
CCACHE_HARDLINK then ccache will attempt to use hard links from the
cache directory when creating the compiler output rather than using a
file copy. Using hard links is faster, but can confuse programs like
'make' that rely on modification times. Hard links are never made for
compressed cache files.
<p>
<p><dt><strong><strong>CCACHE_RECACHE</strong></strong><dd> This forces ccache to not use any cached
results, even if it finds them. New results are still cached, but
existing cache entries are ignored.
<p>
<p><dt><strong><strong>CCACHE_UMASK</strong></strong><dd> This sets the umask for ccache and all child
processes (such as the compiler). This is mostly useful when you wish
to share your cache with other users. Note that this also affects the
file permissions set on the object files created from your
compilations.
<p>
<p><dt><strong><strong>CCACHE_HASHDIR</strong></strong><dd> This tells ccache to hash the current working
directory when calculating the hash that is used to distinguish two
compiles. This prevents a problem with the storage of the current
working directory in the debug info of a object file, which can lead
ccache to give a cached object file that has the working directory in
the debug info set incorrectly. This option is off by default as the
incorrect setting of this debug info rarely causes problems. If you
strike problems with gdb not using the correct directory then enable
this option.
<p>
<p><dt><strong><strong>CCACHE_UNIFY</strong></strong><dd> If you set the environment variable CCACHE_UNIFY
then ccache will use the C/C++ unifier when hashing the pre-processor
output if -g is not used in the compile. The unifier is slower than a
normal hash, so setting this environment variable loses a little bit
of speed, but it means that ccache can take advantage of not
recompiling when the changes to the source code consist of
reformatting only. Note that using CCACHE_UNIFY changes the hash, so
cached compiles with CCACHE_UNIFY set cannot be used when
CCACHE_UNIFY is not set and vice versa. The reason the unifier is off
by default is that it can give incorrect line number information in
compiler warning messages.
<p>
<p><dt><strong><strong>CCACHE_EXTENSION</strong></strong><dd> Normally ccache tries to automatically
determine the extension to use for intermediate C pre-processor files
based on the type of file being compiled. Unfortunately this sometimes
doesn't work, for example when using the aCC compiler on HP-UX. On
systems like this you can use the CCACHE_EXTENSION option to override
the default. On HP-UX set this environment variable to "i" if you use
the aCC compiler.
<p>
<p><dt><strong><strong>CCACHE_STRIPC</strong></strong><dd> If you set the environment variable
CCACHE_STRIPC then ccache will strip the -c option when invoking
the preprocessor. This option is primarily for the Sun Workshop
C++ compiler as without this option an unwarranted warning is displayed:
CC: Warning: "-E" redefines product from "object" to "source (stdout)"
when -E and -c is used together.
<p>
<p><dt><strong><strong>CCACHE_SWIG</strong></strong><dd> When using SWIG as the compiler and it does not
have 'swig' in the executable name, then the CCACHE_SWIG environment
variable needs to be set in order for ccache to work correctly with
SWIG. The use of CCACHE_CPP2 is also recommended for SWIG due to some
preprocessor quirks, however, use of CCACHE_CPP2 can often be skipped
-- check your generated code with and without this option set. Known
problems are using preprocessor directives within %inline blocks and
the use of '#pragma SWIG'.
<p>
</dl>
<p>
<H2><a name="CCache_nn10">17.9 CACHE SIZE MANAGEMENT</a></H2>
<p>
By default ccache has a one gigabyte limit on the cache size and no
maximum number of files. You can set a different limit using the
"ccache -M" and "ccache -F" options, which set the size and number of
files limits.
<p>
When these limits are reached ccache will reduce the cache to 20%
below the numbers you specified in order to avoid doing the cache
clean operation too often.
<p>
<H2><a name="CCache_nn11">17.10 CACHE COMPRESSION</a></H2>
<p>
By default on most platforms ccache will compress all files it puts
into the cache
using the zlib compression. While this involves a negligible
performance slowdown, it significantly increases the number of files
that fit in the cache. You can turn off compression setting the
CCACHE_NOCOMPRESS environment variable.
<p>
<H2><a name="CCache_nn12">17.11 HOW IT WORKS</a></H2>
<p>
The basic idea is to detect when you are compiling exactly the same
code a 2nd time and use the previously compiled output. You detect
that it is the same code by forming a hash of:
<p>
<ul>
<li> the pre-processor output from running the compiler with -E
<li> the command line options
<li> the real compilers size and modification time
<li> any stderr output generated by the compiler
</ul>
<p>
These are hashed using md4 (a strong hash) and a cache file is formed
based on that hash result. When the same compilation is done a second
time ccache is able to supply the correct compiler output (including
all warnings etc) from the cache.
<p>
ccache has been carefully written to always produce exactly the same
compiler output that you would get without the cache. If you ever
discover a case where ccache changes the output of your compiler then
please let me know.
<p>
<H2><a name="CCache_nn13">17.12 USING CCACHE WITH DISTCC</a></H2>
<p>
distcc is a very useful program for distributing compilation across a
range of compiler servers. It is often useful to combine distcc with
ccache, so that compiles that are done are sped up by distcc, but that
ccache avoids the compile completely where possible.
<p>
To use distcc with ccache I recommend using the CCACHE_PREFIX
option. You just need to set the environment variable CCACHE_PREFIX to
'distcc' and ccache will prefix the command line used with the
compiler with the command 'distcc'.
<p>
<H2><a name="CCache_nn14">17.13 SHARING A CACHE</a></H2>
<p>
A group of developers can increase the cache hit rate by sharing a
cache directory. The hard links however cause unwanted side effects,
as all links to a cached file share the file's modification timestamp.
This results in false dependencies to be triggered by timestamp-based
build systems whenever another user links to an existing
file. Typically, users will see that their libraries and binaries are
relinked without reason. To share a cache without side effects, the
following conditions need to be met:
<p>
<ul>
<li> Use the same <strong>CCACHE_DIR</strong> environment variable setting
<li> Unset the <strong>CCACHE_HARDLINK</strong> environment variable
<li> Make sure everyone sets the CCACHE_UMASK environment variable
to 002, this ensures that cached files are accessible to everyone in
the group.
<li> Make sure that all users have write permission in the entire
cache directory (and that you trust all users of the shared cache).
<li> Make sure that the setgid bit is set on all directories in the
cache. This tells the filesystem to inherit group ownership for new
directories. The command "chmod g+s `find $CCACHE_DIR -type d`" might
be useful for this.
<li> Set <strong>CCACHE_NOCOMPRESS</strong> for all users, if there are users with
versions of ccache that do not support compression.
</ul>
<p>
<H2><a name="CCache_nn15">17.14 HISTORY</a></H2>
<p>
ccache was inspired by the compilercache shell script script written
by Erik Thiele and I would like to thank him for an excellent piece of
work. See
<a href="http://www.erikyyy.de/compilercache/">http://www.erikyyy.de/compilercache/</a>
for the Erik's scripts.
ccache-swig is a port of the original ccache with support added for use
with SWIG.
<p>
I wrote ccache because I wanted to get a bit more speed out of a
compiler cache and I wanted to remove some of the limitations of the
shell-script version.
<p>
<H2><a name="CCache_nn16">17.15 DIFFERENCES FROM COMPILERCACHE</a></H2>
<p>
The biggest differences between Erik's compilercache script and ccache
are:
<ul>
<li> ccache is written in C, which makes it a bit faster (calling out to
external programs is mostly what slowed down the scripts).
<li> ccache can automatically find the real compiler
<li> ccache keeps statistics on hits/misses
<li> ccache can do automatic cache management
<li> ccache can cache compiler output that includes warnings. In many
cases this gives ccache a much higher cache hit rate.
<li> ccache can handle a much wider ranger of compiler options
<li> ccache avoids a double call to cpp on a cache miss
</ul>
<p>
<H2><a name="CCache_nn17">17.16 CREDITS</a></H2>
<p>
Thanks to the following people for their contributions to ccache
<ul>
<li> Erik Thiele for the original compilercache script
<li> Luciano Rocha for the idea of compiling the pre-processor output
to avoid a 2nd cpp pass
<li> Paul Russell for many suggestions and the debian packaging
</ul>
<p>
<H2><a name="CCache_nn18">17.17 AUTHOR</a></H2>
<p>
ccache was written by Andrew Tridgell
<a href="http://samba.org/~tridge/">http://samba.org/~tridge/</a>.
ccache was adapted to create ccache-swig for use with SWIG by William Fulton.
<p>
If you wish to report a problem or make a suggestion then please email
the SWIG developers on the swig-devel mailing list, see
<a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a>
<p>
ccache is released under the GNU General Public License version 2 or
later. Please see the file COPYING for license details.
<p>
</body>
</html>

1184
Doc/Manual/CPlusPlus11.html Normal file
View file

File diff suppressed because it is too large Load diff

351
Doc/Manual/CSharp.html
View file

@ -1,15 +1,20 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and C#</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="CSharp"></a>19 SWIG and C#</H1>
<H1><a name="CSharp">20 SWIG and C#</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#CSharp_introduction">Introduction</a>
<ul>
<li><a href="#CSharp_introduction_swig2_compatibility">SWIG 2 Compatibility</a>
<li><a href="#CSharp_commandline">Additional command line options</a>
</ul>
<li><a href="#CSharp_differences_java">Differences to the Java module</a>
<li><a href="#CSharp_void_pointers">Void pointers</a>
<li><a href="#CSharp_arrays">C# Arrays</a>
@ -31,13 +36,14 @@
<li><a href="#CSharp_directors_implementation">Directors implementation</a>
<li><a href="#CSharp_director_caveats">Director caveats</a>
</ul>
<li><a href="#CSharp_multiple_modules">Multiples modules</a>
<li><a href="#CSharp_multiple_modules">Multiple modules</a>
<li><a href="#CSharp_typemap_examples">C# Typemap examples</a>
<ul>
<li><a href="#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="#CSharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="#CSharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a>
<li><a href="#CSharp_date_properties">A date example demonstrating marshalling of C# properties</a>
<li><a href="#CSharp_date_pre_post_directors">Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a>
<li><a href="#CSharp_partial_classes">Turning wrapped classes into partial classes</a>
<li><a href="#CSharp_extending_proxy_class">Extending proxy classes with additional C# code</a>
<li><a href="#CSharp_enum_underlying_type">Underlying type for enums</a>
@ -48,7 +54,7 @@
<H2><a name="CSharp_introduction"></a>19.1 Introduction</H2>
<H2><a name="CSharp_introduction">20.1 Introduction</a></H2>
<p>
@ -65,10 +71,70 @@ SWIG C# works equally well on non-Microsoft operating systems such as Linux, Sol
<p>
To get the most out of this chapter an understanding of interop is required.
The <a href="http://msdn.microsoft.com">Microsoft Developer Network (MSDN)</a> has a good reference guide in a section titled "Interop Marshaling".
Monodoc, available from the Mono project, has a very useful section titled <a href="http://www.mono-project.com/Interop_with_Native_Libraries">Interop with native libraries</a>.
Monodoc, available from the Mono project, has a very useful section titled <a href="http://www.mono-project.com/docs/advanced/pinvoke/">Interop with native libraries</a>.
</p>
<H2><a name="CSharp_differences_java"></a>19.2 Differences to the Java module</H2>
<H3><a name="CSharp_introduction_swig2_compatibility">20.1.1 SWIG 2 Compatibility</a></H3>
<p>
In order to minimize name collisions between names generated based on input to SWIG and names used in the generated code from the .NET framework, SWIG 3 fully qualifies the use of all .NET types. Furthermore, SWIG 3 avoids <tt>using</tt> directives in generated code. This breaks backwards compatibility with typemaps, pragmas, etc written for use with SWIG 2 that assume the presence of <tt>using System;</tt> or <tt>using System.Runtime.InteropServices;</tt> directives in the intermediate class imports, module imports, or proxy imports. SWIG 3 supports backwards compatibility though the use of the <tt>SWIG2_CSHARP</tt> macro. If <tt>SWIG2_CSHARP</tt> is defined, SWIG 3 generates <tt>using</tt> directives in the intermediate class, module class, and proxy class code similar to those generated by SWIG 2. This can be done without modifying any of the input code by passing the <tt>-DSWIG2_CSHARP</tt> commandline parameter when executing <tt>swig</tt>.
</p>
<H3><a name="CSharp_commandline">20.1.2 Additional command line options</a></H3>
<p>
The following table lists the additional commandline options available for the C# module. They can also be seen by using:
</p>
<div class="code"><pre>
swig -csharp -help
</pre></div>
<table summary="C# specific options">
<tr>
<th>C# specific options</th>
</tr>
<tr>
<td>-dllimport &lt;dl&gt;</td>
<td>Override DllImport attribute name to &lt;dl&gt;</td>
</tr>
<tr>
<td>-namespace &lt;nm&gt;</td>
<td>Generate wrappers into C# namespace &lt;nm&gt;</td>
</tr>
<tr>
<td>-noproxy</td>
<td>Generate the low-level functional interface instead of proxy classes</td>
</tr>
<tr>
<td>-oldvarnames</td>
<td>Old intermediary method names for variable wrappers</td>
</tr>
<tr>
<td>-outfile &lt;file&gt;</td>
<td>Write all C# into a single &lt;file&gt; located in the output directory
</td>
</tr>
</table>
<p>
The -outfile option combines all the generated C# code into a single output file instead of creating multiple C# files.
The default, when this option is not provided, is to generate separate .cs files for the module class,
intermediary class and each of the generated proxy and type wrapper classes.
Note that the file extension (.cs) will not be automatically added and needs to be provided.
Due to possible compiler limits it is not advisable to use <tt>-outfile</tt> for large projects.
</p>
<H2><a name="CSharp_differences_java">20.2 Differences to the Java module</a></H2>
<p>
@ -167,6 +233,7 @@ javabody -&gt; csbody
javafinalize -&gt; csfinalize
javadestruct -&gt; csdestruct
javadestruct_derived -&gt; csdestruct_derived
javainterfacecode -&gt; csinterfacecode
</pre></div>
</li>
@ -190,6 +257,20 @@ csattributes C# attributes for attaching to proxy classes/enums
</li>
<li>
<p>Additional typemap attributes:</p>
<p>
The "null" attribute in the "out" typemap can be specified to provide a value for <tt>$null</tt> to expand into for wrapped functions that return non-void. Normally the default value of <tt>0</tt> is used.
For example this is needed if you change the return type to void:
</p>
<div class="code"><pre>
%typemap(ctype) Status "void"
%typemap(out, null="") Status { ... }
</pre></div>
</li>
<li>
<p>Feature equivalent names:</p>
<div class="code"><pre>
@ -220,6 +301,9 @@ $*javaclassname -&gt; $*csclassname
$javaclazzname -&gt; $csclazzname
$javainput -&gt; $csinput
$jnicall -&gt; $imcall
$javainterfacename -&gt; $csinterfacename
$&amp;javainterfacename -&gt; $&amp;csinterfacename
$*javainterfacename -&gt; $*csinterfacename
</pre></div>
</li>
@ -227,10 +311,12 @@ $jnicall -&gt; $imcall
<p>
Unlike the "javain" typemap, the "csin" typemap does not support the 'pgcpp' attribute as the C# module does not have a premature garbage collection prevention parameter.
The "csin" typemap supports additional optional attributes called 'cshin' and 'terminator'.
The "csdirectorin" typemap supports additional optional attributes called 'terminator'.
The 'cshin' attribute should contain the parameter type and name whenever a <a href="Java.html#Java_constructor_helper_function">constructor helper function</a> is generated due to the 'pre' or 'post' attributes.
The 'terminator' attribute normally just contains a closing brace for when the 'pre' attribute contains an opening brace, such as when a C# <tt>using</tt> or <tt>fixed</tt> block is started.
Note that 'pre', 'post', 'terminator' and 'cshin' attributes are not used for marshalling the property set.
Please see the <a href="#CSharp_date_marshalling">Date marshalling example</a> and <a href="#CSharp_date_properties">Date marshalling of properties example</a> for further understanding of these "csin" applicable attributes.
Please see the <a href="#CSharp_date_pre_post_directors">Date marshalling director example</a> for further understanding of the "csdirectorin" attributes.
</p>
</li>
@ -245,7 +331,7 @@ An example shows that <tt>char *</tt> could be marshalled in different ways,
<div class="code">
<pre>
%typemap(imtype, out="IntPtr") char * "string"
%typemap(imtype, out="global::System.IntPtr") char * "string"
char * function(char *);
</pre>
</div>
@ -256,7 +342,7 @@ The output type is thus IntPtr and the input type is string. The resulting inter
<div class="code">
<pre>
public static extern IntPtr function(string jarg1);
public static extern global::System.IntPtr function(string jarg1);
</pre>
</div>
@ -277,8 +363,8 @@ For example:
<div class="code">
<pre>
%typemap(imtype,
inattributes="[MarshalAs(UnmanagedType.LPStr)]",
outattributes="[return: MarshalAs(UnmanagedType.LPStr)]") const char * "String"
inattributes="[global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]",
outattributes="[return: global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]") const char * "String"
const char * GetMsg() {}
void SetMsg(const char *msg) {}
@ -293,12 +379,12 @@ The intermediary class will then have the marshalling as specified by everything
<pre>
class examplePINVOKE {
...
[DllImport("example", EntryPoint="CSharp_GetMsg")]
[return: MarshalAs(UnmanagedType.LPStr)]
[global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_GetMsg")]
[return: global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]
public static extern String GetMsg();
[DllImport("example", EntryPoint="CSharp_SetMsg")]
public static extern void SetMsg([MarshalAs(UnmanagedType.LPStr)]String jarg1);
[global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_SetMsg")]
public static extern void SetMsg([global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]String jarg1);
}
</pre>
</div>
@ -351,7 +437,7 @@ will generate a C# proxy class:
<div class="code">
<pre>
[ThreadSafe]
public class AClass : IDisposable {
public class AClass : global::System.IDisposable {
...
[ThreadSafe(false)]
public AClass(double a) ...
@ -375,9 +461,9 @@ An example for attaching attributes to the enum and enum values is shown below.
<div class="code">
<pre>
%typemap(csattributes) Couleur "[System.ComponentModel.Description(\"Colours\")]"
%csattributes Rouge "[System.ComponentModel.Description(\"Red\")]"
%csattributes Vert "[System.ComponentModel.Description(\"Green\")]"
%typemap(csattributes) Couleur "[global::System.ComponentModel.Description(\"Colours\")]"
%csattributes Rouge "[global::System.ComponentModel.Description(\"Red\")]"
%csattributes Vert "[global::System.ComponentModel.Description(\"Green\")]"
%inline %{
enum Couleur { Rouge, Orange, Vert };
%}
@ -390,12 +476,12 @@ which will result in the following C# enum:
<div class="code">
<pre>
[System.ComponentModel.Description("Colours")]
[global::System.ComponentModel.Description("Colours")]
public enum Couleur {
[System.ComponentModel.Description("Red")]
[global::System.ComponentModel.Description("Red")]
Rouge,
Orange,
[System.ComponentModel.Description("Green")]
[global::System.ComponentModel.Description("Green")]
Vert
}
</pre>
@ -465,7 +551,7 @@ Windows users can also get the examples working using a
<a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> environment for automatic configuration of the example makefiles.
Any one of the three C# compilers (Portable.NET, Mono or Microsoft) can be detected from within a Cygwin or Mingw environment if installed in your path.
<H2><a name="CSharp_void_pointers"></a>19.3 Void pointers</H2>
<H2><a name="CSharp_void_pointers">20.3 Void pointers</a></H2>
<p>
@ -483,7 +569,7 @@ void * f(void *v);
</pre>
</div>
<H2><a name="CSharp_arrays"></a>19.4 C# Arrays</H2>
<H2><a name="CSharp_arrays">20.4 C# Arrays</a></H2>
<p>
@ -495,7 +581,7 @@ with one of the following three approaches; namely the SWIG C arrays library, P/
pinned arrays.
</p>
<H3><a name="CSharp_arrays_swig_library"></a>19.4.1 The SWIG C arrays library</H3>
<H3><a name="CSharp_arrays_swig_library">20.4.1 The SWIG C arrays library</a></H3>
<p>
@ -532,7 +618,7 @@ example.print_array(c.cast()); // Pass to C
</div>
<H3><a name="CSharp_arrays_pinvoke_default_array_marshalling"></a>19.4.2 Managed arrays using P/Invoke default array marshalling</H3>
<H3><a name="CSharp_arrays_pinvoke_default_array_marshalling">20.4.2 Managed arrays using P/Invoke default array marshalling</a></H3>
<p>
@ -601,9 +687,9 @@ marshalling for the arrays:
<div class="code">
<pre>
[DllImport("example", EntryPoint="CSharp_myArrayCopy")]
public static extern void myArrayCopy([In, MarshalAs(UnmanagedType.LPArray)]int[] jarg1,
[Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
[global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_myArrayCopy")]
public static extern void myArrayCopy([global::System.Runtime.InteropServices.In, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg1,
[global::System.Runtime.InteropServices.Out, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
int jarg3);
</pre>
</div>
@ -651,15 +737,15 @@ and intermediary class method
<div class="code">
<pre>
[DllImport("example", EntryPoint="CSharp_myArraySwap")]
public static extern void myArraySwap([In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg1,
[In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
[global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_myArraySwap")]
public static extern void myArraySwap([global::System.Runtime.InteropServices.In, global::System.Runtime.InteropServices.Out, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg1,
[global::System.Runtime.InteropServices.In, global::System.Runtime.InteropServices.Out, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
int jarg3);
</pre>
</div>
<H3><a name="CSharp_arrays_pinning"></a>19.4.3 Managed arrays using pinning</H3>
<H3><a name="CSharp_arrays_pinning">20.4.3 Managed arrays using pinning</a></H3>
<p>
@ -726,7 +812,7 @@ As a result, we get the following method in the module class:
fixed ( int *swig_ptrTo_sourceArray = sourceArray ) {
fixed ( int *swig_ptrTo_targetArray = targetArray ) {
{
examplePINVOKE.myArrayCopy((IntPtr)swig_ptrTo_sourceArray, (IntPtr)swig_ptrTo_targetArray,
examplePINVOKE.myArrayCopy((global::System.IntPtr)swig_ptrTo_sourceArray, (global::System.IntPtr)swig_ptrTo_targetArray,
nitems);
}
}
@ -747,14 +833,14 @@ example - the method is expecting an IntPtr as the parameter type.
<div class="code">
<pre>
[DllImport("example", EntryPoint="CSharp_myArrayCopy")]
public static extern void myArrayCopy(IntPtr jarg1, IntPtr jarg2, int jarg3);
[global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_myArrayCopy")]
public static extern void myArrayCopy(global::System.IntPtr jarg1, global::System.IntPtr jarg2, int jarg3);
</pre>
</div>
<H2><a name="CSharp_exceptions"></a>19.5 C# Exceptions</H2>
<H2><a name="CSharp_exceptions">20.5 C# Exceptions</a></H2>
<p>
@ -851,11 +937,11 @@ set so should only be used when a C# exception is not created.
</p>
<H3><a name="CSharp_exception_example_check_typemap"></a>19.5.1 C# exception example using "check" typemap</H3>
<H3><a name="CSharp_exception_example_check_typemap">20.5.1 C# exception example using "check" typemap</a></H3>
<p>
Lets say we have the following simple C++ method:
Let's say we have the following simple C++ method:
</p>
@ -1033,7 +1119,7 @@ method and C# code does not handle pending exceptions via the canthrow attribute
Actually it will issue this warning for any function beginning with <tt>SWIG_CSharpSetPendingException</tt>.
</P>
<H3><a name="CSharp_exception_example_percent_exception"></a>19.5.2 C# exception example using %exception</H3>
<H3><a name="CSharp_exception_example_percent_exception">20.5.2 C# exception example using %exception</a></H3>
<p>
@ -1048,6 +1134,7 @@ try {
$action
} catch (std::out_of_range e) {
SWIG_CSharpSetPendingException(SWIG_CSharpApplicationException, e.what());
return $null;
}
%}
@ -1098,7 +1185,7 @@ The managed code generated does check for the pending exception as mentioned ear
</pre>
</div>
<H3><a name="CSharp_exception_example_exception_specifications"></a>19.5.3 C# exception example using exception specifications</H3>
<H3><a name="CSharp_exception_example_exception_specifications">20.5.3 C# exception example using exception specifications</a></H3>
<p>
@ -1155,7 +1242,7 @@ SWIGEXPORT void SWIGSTDCALL CSharp_evensonly(int jarg1) {
Multiple catch handlers are generated should there be more than one exception specifications declared.
</p>
<H3><a name="CSharp_custom_application_exception"></a>19.5.4 Custom C# ApplicationException example</H3>
<H3><a name="CSharp_custom_application_exception">20.5.4 Custom C# ApplicationException example</a></H3>
<p>
@ -1203,7 +1290,7 @@ the C# code can be generated into the intermediary class using the <tt>imclassco
static CustomExceptionDelegate customDelegate =
new CustomExceptionDelegate(SetPendingCustomException);
[DllImport("$dllimport", EntryPoint="CustomExceptionRegisterCallback")]
[global::System.Runtime.InteropServices.DllImport("$dllimport", EntryPoint="CustomExceptionRegisterCallback")]
public static extern
void CustomExceptionRegisterCallback(CustomExceptionDelegate customCallback);
@ -1247,7 +1334,7 @@ The boiler plate code above must be used in addition to a handcrafted <tt>Custom
<div class="code">
<pre>
// Custom C# Exception
class CustomApplicationException : System.ApplicationException {
class CustomApplicationException : global::System.ApplicationException {
public CustomApplicationException(string message)
: base(message) {
}
@ -1289,7 +1376,7 @@ try {
</pre>
</div>
<H2><a name="CSharp_directors"></a>19.6 C# Directors</H2>
<H2><a name="CSharp_directors">20.6 C# Directors</a></H2>
<p>
@ -1302,7 +1389,7 @@ The following sections provide information on the C# director implementation and
However, the <a href="Java.html#Java_directors">Java directors</a> section should also be read in order to gain more insight into directors.
</p>
<H3><a name="CSharp_directors_example"></a>19.6.1 Directors example</H3>
<H3><a name="CSharp_directors_example">20.6.1 Directors example</a></H3>
<p>
@ -1423,7 +1510,7 @@ CSharpDerived - UIntMethod(123)
</pre>
</div>
<H3><a name="CSharp_directors_implementation"></a>19.6.2 Directors implementation</H3>
<H3><a name="CSharp_directors_implementation">20.6.2 Directors implementation</a></H3>
<p>
@ -1440,20 +1527,17 @@ Below is the generated C# <tt>Base</tt> director class.
<div class="code">
<pre>
using System;
using System.Runtime.InteropServices;
public class Base : IDisposable {
private HandleRef swigCPtr;
public class Base : global::System.IDisposable {
private global::System.Runtime.InteropServices.HandleRef swigCPtr;
protected bool swigCMemOwn;
internal Base(IntPtr cPtr, bool cMemoryOwn) {
internal Base(global::System.IntPtr cPtr, bool cMemoryOwn) {
swigCMemOwn = cMemoryOwn;
swigCPtr = new HandleRef(this, cPtr);
swigCPtr = new global::System.Runtime.InteropServices.HandleRef(this, cPtr);
}
internal static HandleRef getCPtr(Base obj) {
return (obj == null) ? new HandleRef(null, IntPtr.Zero) : obj.swigCPtr;
internal static global::System.Runtime.InteropServices.HandleRef getCPtr(Base obj) {
return (obj == null) ? new global::System.Runtime.InteropServices.HandleRef(null, global::System.IntPtr.Zero) : obj.swigCPtr;
}
~Base() {
@ -1462,12 +1546,12 @@ public class Base : IDisposable {
public virtual void Dispose() {
lock(this) {
if(swigCPtr.Handle != IntPtr.Zero &amp;&amp; swigCMemOwn) {
if(swigCPtr.Handle != global::System.IntPtr.Zero &amp;&amp; swigCMemOwn) {
swigCMemOwn = false;
examplePINVOKE.delete_Base(swigCPtr);
}
swigCPtr = new HandleRef(null, IntPtr.Zero);
GC.SuppressFinalize(this);
swigCPtr = new global::System.Runtime.InteropServices.HandleRef(null, global::System.IntPtr.Zero);
global::System.GC.SuppressFinalize(this);
}
}
@ -1494,7 +1578,7 @@ public class Base : IDisposable {
examplePINVOKE.Base_director_connect(swigCPtr, swigDelegate0, swigDelegate1);
}
private bool SwigDerivedClassHasMethod(string methodName, Type[] methodTypes) {
private bool SwigDerivedClassHasMethod(string methodName, global::System.global::System.Type[] methodTypes) {
System.Reflection.MethodInfo methodInfo = this.GetType().GetMethod(methodName, methodTypes);
bool hasDerivedMethod = methodInfo.DeclaringType.IsSubclassOf(typeof(Base));
return hasDerivedMethod;
@ -1504,18 +1588,18 @@ public class Base : IDisposable {
return UIntMethod(x);
}
private void SwigDirectorBaseBoolMethod(IntPtr b, bool flag) {
private void SwigDirectorBaseBoolMethod(global::System.IntPtr b, bool flag) {
BaseBoolMethod(new Base(b, false), flag);
}
internal delegate uint SwigDelegateBase_0(uint x);
internal delegate void SwigDelegateBase_1(IntPtr b, bool flag);
internal delegate void SwigDelegateBase_1(global::System.IntPtr b, bool flag);
private SwigDelegateBase_0 swigDelegate0;
private SwigDelegateBase_1 swigDelegate1;
private static Type[] swigMethodTypes0 = new Type[] { typeof(uint) };
private static Type[] swigMethodTypes1 = new Type[] { typeof(Base), typeof(bool) };
private static global::System.Type[] swigMethodTypes0 = new global::System.Type[] { typeof(uint) };
private static global::System.Type[] swigMethodTypes1 = new global::System.Type[] { typeof(Base), typeof(bool) };
}
</pre>
</div>
@ -1609,7 +1693,7 @@ void SwigDirector_Base::BaseBoolMethod(Base const &amp;b, bool flag) {
</pre>
</div>
<H3><a name="CSharp_director_caveats"></a>19.6.3 Director caveats</H3>
<H3><a name="CSharp_director_caveats">20.6.3 Director caveats</a></H3>
<p>
@ -1657,11 +1741,11 @@ However, a call from C# to <tt>CSharpDefaults.DefaultMethod()</tt> will of cours
should pass the call on to <tt>CSharpDefaults.DefaultMethod(int)</tt>using the C++ default value, as shown above.
</p>
<H2><a name="CSharp_multiple_modules"></a>19.7 Multiples modules</H2>
<H2><a name="CSharp_multiple_modules">20.7 Multiple modules</a></H2>
<p>
When using <a href="Modules.html">multiple modules</a> it is is possible to compile each SWIG generated wrapper
When using <a href="Modules.html#Modules">multiple modules</a> it is is possible to compile each SWIG generated wrapper
into a different assembly.
However, by default the generated code may not compile if
generated classes in one assembly use generated classes in another assembly.
@ -1692,7 +1776,7 @@ the <tt>[System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrows
if you don't want users to easily stumble upon these so called 'internal workings' of the wrappers.
</p>
<H2><a name="CSharp_typemap_examples"></a>19.8 C# Typemap examples</H2>
<H2><a name="CSharp_typemap_examples">20.8 C# Typemap examples</a></H2>
This section includes a few examples of typemaps. For more examples, you
@ -1700,7 +1784,7 @@ might look at the files "<tt>csharp.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
<H3><a name="CSharp_memory_management_member_variables"></a>19.8.1 Memory management when returning references to member variables</H3>
<H3><a name="CSharp_memory_management_member_variables">20.8.1 Memory management when returning references to member variables</a></H3>
<p>
@ -1738,9 +1822,9 @@ and the following usage from C# after running the code through SWIG:
Wheel wheel = new Bike(10).getWheel();
Console.WriteLine("wheel size: " + wheel.size);
// Simulate a garbage collection
System.GC.Collect();
System.GC.WaitForPendingFinalizers();
Console.WriteLine("wheel size: " + wheel.size);
global::System.GC.Collect();
global::System.GC.WaitForPendingFinalizers();
global::System.Console.WriteLine("wheel size: " + wheel.size);
</pre>
</div>
@ -1778,9 +1862,9 @@ is called using the following typemaps.
// of dangling C++ pointer. Intended for methods that return pointers or
// references to a member variable.
%typemap(csout, excode=SWIGEXCODE) Wheel&amp; getWheel {
IntPtr cPtr = $imcall;$excode
global::System.IntPtr cPtr = $imcall;$excode
$csclassname ret = null;
if (cPtr != IntPtr.Zero) {
if (cPtr != global::System.IntPtr.Zero) {
ret = new $csclassname(cPtr, $owner);
ret.addReference(this);
}
@ -1796,7 +1880,7 @@ The code in the second typemap constitutes the bulk of the code in the generated
<div class="code">
<pre>
public class Wheel : IDisposable {
public class Wheel : global::System.IDisposable {
...
// Ensure that the GC doesn't collect any Bike instance set from C#
private Bike bikeReference;
@ -1805,12 +1889,12 @@ public class Wheel : IDisposable {
}
}
public class Bike : IDisposable {
public class Bike : global::System.IDisposable {
...
public Wheel getWheel() {
IntPtr cPtr = examplePINVOKE.Bike_getWheel(swigCPtr);
global::System.IntPtr cPtr = examplePINVOKE.Bike_getWheel(swigCPtr);
Wheel ret = null;
if (cPtr != IntPtr.Zero) {
if (cPtr != global::System.IntPtr.Zero) {
ret = new Wheel(cPtr, false);
ret.addReference(this);
}
@ -1824,7 +1908,7 @@ public class Bike : IDisposable {
Note the <tt>addReference</tt> call.
</p>
<H3><a name="CSharp_memory_management_objects"></a>19.8.2 Memory management for objects passed to the C++ layer</H3>
<H3><a name="CSharp_memory_management_objects">20.8.2 Memory management for objects passed to the C++ layer</a></H3>
<p>
@ -1887,9 +1971,9 @@ In order to understand why, consider a garbage collection occuring...
container.setElement(element);
Console.WriteLine("element.value: " + container.getElement().value);
// Simulate a garbage collection
System.GC.Collect();
System.GC.WaitForPendingFinalizers();
Console.WriteLine("element.value: " + container.getElement().value);
global::System.GC.Collect();
global::System.GC.WaitForPendingFinalizers();
global::System.Console.WriteLine("element.value: " + container.getElement().value);
</pre>
</div>
@ -1901,14 +1985,14 @@ One solution is to add in the appropriate references in the C# layer...
<div class="code">
<pre>
public class Container : IDisposable {
public class Container : global::System.IDisposable {
...
// Ensure that the GC doesn't collect any Element set from C#
// as the underlying C++ class stores a shallow copy
private Element elementReference;
private HandleRef getCPtrAndAddReference(Element element) {
private global::System.Runtime.InteropServices.HandleRef getCPtrAndAddReference(Element element) {
elementReference = element;
return Element.getCPtr(element);
}
@ -1934,7 +2018,7 @@ The 'cscode' typemap simply adds in the specified code into the C# proxy class.
// Ensure that the GC doesn't collect any Element set from C#
// as the underlying C++ class stores a shallow copy
private Element elementReference;
private HandleRef getCPtrAndAddReference(Element element) {
private global::System.Runtime.InteropServices.HandleRef getCPtrAndAddReference(Element element) {
elementReference = element;
return Element.getCPtr(element);
}
@ -1943,7 +2027,7 @@ The 'cscode' typemap simply adds in the specified code into the C# proxy class.
</div>
<H3><a name="CSharp_date_marshalling"></a>19.8.3 Date marshalling using the csin typemap and associated attributes</H3>
<H3><a name="CSharp_date_marshalling">20.8.3 Date marshalling using the csin typemap and associated attributes</a></H3>
<p>
@ -1983,7 +2067,7 @@ First let's look at the code that is generated by default, where the C# proxy cl
<div class="code">
<pre>
public class Action : IDisposable {
public class Action : global::System.IDisposable {
...
public Action(CDate dateIn, CDate dateOut)
: this(examplePINVOKE.new_Action(CDate.getCPtr(dateIn), CDate.getCPtr(dateOut)), true) {
@ -2040,13 +2124,13 @@ The typemaps to achieve this are shown below.
<div class="code">
<pre>
%typemap(cstype) const CDate&amp; "System.DateTime"
%typemap(cstype) const CDate &amp; "System.DateTime"
%typemap(csin,
pre=" CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);"
) const CDate &amp;
"$csclassname.getCPtr(temp$csinput)"
%typemap(cstype) CDate&amp; "out System.DateTime"
%typemap(cstype) CDate &amp; "out System.DateTime"
%typemap(csin,
pre=" CDate temp$csinput = new CDate();",
post=" $csinput = new System.DateTime(temp$csinput.getYear(),"
@ -2064,7 +2148,7 @@ The resulting generated proxy code in the <tt>Action</tt> class follows:
<div class="code">
<pre>
public class Action : IDisposable {
public class Action : global::System.IDisposable {
...
public int doSomething(System.DateTime dateIn, out System.DateTime dateOut) {
CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
@ -2082,7 +2166,7 @@ public class Action : IDisposable {
}
}
static private IntPtr SwigConstructAction(System.DateTime dateIn, out System.DateTime dateOut) {
static private global::System.IntPtr SwigConstructAction(System.DateTime dateIn, out System.DateTime dateOut) {
CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
CDate tempdateOut = new CDate();
try {
@ -2229,7 +2313,7 @@ public class example {
</pre>
</div>
<H3><a name="CSharp_date_properties"></a>19.8.4 A date example demonstrating marshalling of C# properties</H3>
<H3><a name="CSharp_date_properties">20.8.4 A date example demonstrating marshalling of C# properties</a></H3>
<p>
@ -2257,7 +2341,7 @@ Console.WriteLine("Important date: " + importantDate);
</div>
<p>
When SWIG wraps a variable that is a class/struct/union, it is wrapped using a pointer to the type for the reasons given in <a href="SWIG.html#SWIG_structure_data_members">Stucture data members</a>.
When SWIG wraps a variable that is a class/struct/union, it is wrapped using a pointer to the type for the reasons given in <a href="SWIG.html#SWIG_structure_data_members">Structure data members</a>.
The typemap type required is thus <tt>CDate *</tt>. Given that the previous section already designed <tt>CDate *</tt> typemaps, we'll use those same typemaps plus the 'csvarin' and 'csvarout' typemaps.
<div class="code">
@ -2282,8 +2366,8 @@ The typemap type required is thus <tt>CDate *</tt>. Given that the previous sect
%typemap(csvarout, excode=SWIGEXCODE2) CDate * %{
/* csvarout typemap code */
get {
IntPtr cPtr = $imcall;
CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, $owner);$excode
global::System.IntPtr cPtr = $imcall;
CDate tempDate = (cPtr == global::System.IntPtr.Zero) ? null : new CDate(cPtr, $owner);$excode
return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
0, 0, 0);
} %}
@ -2305,8 +2389,8 @@ public class example {
}
/* csvarout typemap code */
get {
IntPtr cPtr = examplePINVOKE.ImportantDate_get();
CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, false);
global::System.IntPtr cPtr = examplePINVOKE.ImportantDate_get();
CDate tempDate = (cPtr == global::System.IntPtr.Zero) ? null : new CDate(cPtr, false);
return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
0, 0, 0);
}
@ -2329,8 +2413,69 @@ Some points to note:
<li>The 'csin' typemap has 'pre', 'post' and 'cshin' attributes, and these are all ignored in the property set. The code in these attributes must instead be replicated within the 'csvarin' typemap. The line creating the <tt>temp$csinput</tt> variable is such an example; it is identical to what is in the 'pre' attribute.
</ul>
<H3><a name="CSharp_date_pre_post_directors">20.8.5 Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a></H3>
<H3><a name="CSharp_partial_classes"></a>19.8.5 Turning wrapped classes into partial classes</H3>
<p>
The 'pre' and 'post' attributes in the "csdirectorin" typemap act like the attributes of the same name in the "csin" typemap.
For example if we modify the <a href="#CSharp_date_marshalling">Date marshalling example</a> like this:
</p>
<div class="code"><pre>
class CDate {
...
void setYear(int);
void setMonth(int);
void setDay(int);
};
struct Action {
virtual void someCallback(CDate &amp;date);
virtual ~Action();
...
};
</pre></div>
<p>
and declare <tt>%feature ("director")</tt> for the <tt>Action</tt> class, we would have to define additional
marshalling rules for <tt>CDate &amp;</tt> parameter. The typemap may look like this:
</p>
<div class="code"><pre>
%typemap(csdirectorin,
pre="System.DateTime temp$iminput = new System.DateTime();",
post="CDate temp2$iminput = new CDate($iminput, false);\n"
"temp2$iminput.setYear(tempdate.Year);\n"
"temp2$iminput.setMonth(tempdate.Month);\n"
"temp2$iminput.setDay(tempdate.Day);"
) CDate &amp;date "out temp$iminput"
</pre></div>
<p>
The generated proxy class code will then contain the following wrapper for calling user-overloaded <tt>someCallback()</tt>:
</p>
<div class="code"><pre>
...
private void SwigDirectorsomeCallback(global::System.IntPtr date) {
System.DateTime tempdate = new System.DateTime();
try {
someCallback(out tempdate);
} finally {
// we create a managed wrapper around the existing C reference, just for convenience
CDate temp2date = new CDate(date, false);
temp2date.setYear(tempdate.Year);
temp2date.setMonth(tempdate.Month);
temp2date.setDay(tempdate.Day);
}
}
...
</pre></div>
<p>
Pay special attention to the memory management issues, using these attributes.
</p>
<H3><a name="CSharp_partial_classes">20.8.6 Turning wrapped classes into partial classes</a></H3>
<p>
@ -2354,7 +2499,7 @@ The default C# proxy class generated is:
<div class="code">
<pre>
public class ExtendMe : IDisposable {
public class ExtendMe : global::System.IDisposable {
...
public int Part1() {
...
@ -2390,7 +2535,7 @@ The C# proxy class becomes a partial class:
<div class="code">
<pre>
public partial class ExtendMe : IDisposable {
public partial class ExtendMe : global::System.IDisposable {
...
public int Part1() {
...
@ -2405,7 +2550,7 @@ You can then of course declare another part of the partial class elsewhere, for
<div class="code">
<pre>
public partial class ExtendMe : IDisposable {
public partial class ExtendMe : global::System.IDisposable {
public int Part2() {
return 2;
}
@ -2430,7 +2575,7 @@ demonstrating that the class contains methods calling both unmanaged code - <tt>
The following example is an alternative approach to adding managed code to the generated proxy class.
</p>
<H3><a name="CSharp_extending_proxy_class"></a>19.8.6 Extending proxy classes with additional C# code</H3>
<H3><a name="CSharp_extending_proxy_class">20.8.7 Extending proxy classes with additional C# code</a></H3>
<p>
@ -2457,7 +2602,7 @@ The generated C# proxy class will instead be:
<div class="code">
<pre>
public class ExtendMe : IDisposable {
public class ExtendMe : global::System.IDisposable {
...
public int Part3() {
return 3;
@ -2469,7 +2614,7 @@ public class ExtendMe : IDisposable {
</pre>
</div>
<H3><a name="CSharp_enum_underlying_type"></a>19.8.7 Underlying type for enums</H3>
<H3><a name="CSharp_enum_underlying_type">20.8.8 Underlying type for enums</a></H3>
<P>

86
Doc/Manual/Chicken.html
View file

@ -1,14 +1,14 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Hand-written HTML -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Chicken</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Chicken"></a>20 SWIG and Chicken</H1>
<H1><a name="Chicken">21 SWIG and Chicken</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -55,10 +55,10 @@
</p>
<ol>
<li>generates portable C code</li>
<li>includes a customizable interpreter</li>
<li>links to C libraries with a simple Foreign Function Interface</li>
<li>supports full tail-recursion and first-class continuations</li>
<li>generates portable C code</li>
<li>includes a customizable interpreter</li>
<li>links to C libraries with a simple Foreign Function Interface</li>
<li>supports full tail-recursion and first-class continuations</li>
</ol>
<p>
@ -72,7 +72,7 @@
</p>
<H2><a name="Chicken_nn2"></a>20.1 Preliminaries</H2>
<H2><a name="Chicken_nn2">21.1 Preliminaries</a></H2>
<p>
@ -89,7 +89,7 @@
directory for the basic steps to run SWIG CHICKEN.
</p>
<H3><a name="Chicken_nn3"></a>20.1.1 Running SWIG in C mode</H3>
<H3><a name="Chicken_nn3">21.1.1 Running SWIG in C mode</a></H3>
<p>
@ -98,7 +98,7 @@
</p>
<div class="shell">
<pre>% swig -chicken example.i</pre>
<pre>% swig -chicken example.i</pre>
</div>
<p>
@ -122,7 +122,7 @@
object files and linked into your project.
</p>
<H3><a name="Chicken_nn4"></a>20.1.2 Running SWIG in C++ mode</H3>
<H3><a name="Chicken_nn4">21.1.2 Running SWIG in C++ mode</a></H3>
<p>
@ -131,7 +131,7 @@
</p>
<div class="shell">
<pre>% swig -chicken -c++ example.i</pre>
<pre>% swig -chicken -c++ example.i</pre>
</div>
<p>
@ -142,7 +142,7 @@
</p>
<div class="shell">
<pre>% chicken example.scm -output-file oexample.c</pre>
<pre>% chicken example.scm -output-file oexample.c</pre>
</div>
<p>
@ -151,10 +151,10 @@
object files and linked into your project.
</p>
<H2><a name="Chicken_nn5"></a>20.2 Code Generation</H2>
<H2><a name="Chicken_nn5">21.2 Code Generation</a></H2>
<H3><a name="Chicken_nn6"></a>20.2.1 Naming Conventions</H3>
<H3><a name="Chicken_nn6">21.2.1 Naming Conventions</a></H3>
<p>
@ -170,16 +170,16 @@
<tt>%rename</tt> SWIG directive in the SWIG interface file.
</p>
<H3><a name="Chicken_nn7"></a>20.2.2 Modules</H3>
<H3><a name="Chicken_nn7">21.2.2 Modules</a></H3>
<p>
The name of the module must be declared one of two ways:
<ul>
<li>Placing <tt>%module example</tt> in the SWIG interface
file.</li>
<li>Using <tt>-module example</tt> on the SWIG command
line.</li>
<li>Placing <tt>%module example</tt> in the SWIG interface
file.</li>
<li>Using <tt>-module example</tt> on the SWIG command
line.</li>
</ul>
<p>
@ -189,10 +189,10 @@
<p>
CHICKEN will be able to access the module using the <code>(declare
(uses <i>modulename</i>))</code> CHICKEN Scheme form.
(uses <i>modulename</i>))</code> CHICKEN Scheme form.
</p>
<H3><a name="Chicken_nn8"></a>20.2.3 Constants and Variables</H3>
<H3><a name="Chicken_nn8">21.2.3 Constants and Variables</a></H3>
<p>
@ -200,10 +200,10 @@
the interface file:
</p>
<ol>
<li><code>#define MYCONSTANT1 ...</code></li>
<li><code>%constant int MYCONSTANT2 = ...</code></li>
<li><code>const int MYCONSTANT3 = ...</code></li>
<li><code>enum { MYCONSTANT4 = ... };</code></li>
<li><code>#define MYCONSTANT1 ...</code></li>
<li><code>%constant int MYCONSTANT2 = ...</code></li>
<li><code>const int MYCONSTANT3 = ...</code></li>
<li><code>enum { MYCONSTANT4 = ... };</code></li>
</ol>
<p>
@ -229,7 +229,7 @@
for info on how to apply the %feature.
</p>
<H3><a name="Chicken_nn9"></a>20.2.4 Functions</H3>
<H3><a name="Chicken_nn9">21.2.4 Functions</a></H3>
<p>
@ -248,7 +248,7 @@
parameters). The return values can then be accessed with <code>(call-with-values)</code>.
</p>
<H3><a name="Chicken_nn10"></a>20.2.5 Exceptions</H3>
<H3><a name="Chicken_nn10">21.2.5 Exceptions</a></H3>
<p>The SWIG chicken module has support for exceptions thrown from
@ -290,16 +290,16 @@
</pre></div>
<H2><a name="Chicken_nn11"></a>20.3 TinyCLOS</H2>
<H2><a name="Chicken_nn11">21.3 TinyCLOS</a></H2>
<p>
The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:
"Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a
metaobject protocol. The implementation is even simpler than
the simple CLOS found in `The Art of the Metaobject Protocol,'
weighing in at around 850 lines of code, including (some)
comments and documentation."
"Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a
metaobject protocol. The implementation is even simpler than
the simple CLOS found in `The Art of the Metaobject Protocol,'
weighing in at around 850 lines of code, including (some)
comments and documentation."
</p>
<p>
@ -333,7 +333,7 @@
</p>
<H2><a name="Chicken_nn12"></a>20.4 Linkage</H2>
<H2><a name="Chicken_nn12">21.4 Linkage</a></H2>
<p>
@ -354,7 +354,7 @@
</p>
<H3><a name="Chicken_nn13"></a>20.4.1 Static binary or shared library linked at compile time</H3>
<H3><a name="Chicken_nn13">21.4.1 Static binary or shared library linked at compile time</a></H3>
<p>We can easily use csc to build a static binary.</p>
@ -395,7 +395,7 @@ in which case the test script does not need to be linked with example.so. The t
be run with <tt>csi</tt>.
</p>
<H3><a name="Chicken_nn14"></a>20.4.2 Building chicken extension libraries</H3>
<H3><a name="Chicken_nn14">21.4.2 Building chicken extension libraries</a></H3>
<p>Building a shared library like in the above section only works if the library
@ -453,7 +453,7 @@ distributed and used by anyone, even if SWIG is not installed.</p>
<p>See the <tt>Examples/chicken/egg</tt> directory in the SWIG source for an example that builds
two eggs, one using the first method and one using the second method.</p>
<H3><a name="Chicken_nn15"></a>20.4.3 Linking multiple SWIG modules with TinyCLOS</H3>
<H3><a name="Chicken_nn15">21.4.3 Linking multiple SWIG modules with TinyCLOS</a></H3>
<p>Linking together multiple modules that share type information using the <code>%import</code>
@ -477,7 +477,7 @@ with <code>(declare (uses ...))</code>.
To create an extension library or an egg, just create a <tt>module_load.scm</tt> file that <code>(declare (uses ...))</code>
all the modules.</p>
<H2><a name="Chicken_nn16"></a>20.5 Typemaps</H2>
<H2><a name="Chicken_nn16">21.5 Typemaps</a></H2>
<p>
@ -486,7 +486,7 @@ all the modules.</p>
<code>Lib/chicken/chicken.swg</code>.
</p>
<H2><a name="Chicken_nn17"></a>20.6 Pointers</H2>
<H2><a name="Chicken_nn17">21.6 Pointers</a></H2>
<p>
@ -519,7 +519,7 @@ all the modules.</p>
type. flags is either zero or SWIG_POINTER_DISOWN (see below).
</p>
<H3><a name="Chicken_collection"></a>20.6.1 Garbage collection</H3>
<H3><a name="Chicken_collection">21.6.1 Garbage collection</a></H3>
<p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a
@ -550,7 +550,7 @@ all the modules.</p>
must be called manually.
</p>
<H2><a name="Chicken_nn18"></a>20.7 Unsupported features and known problems</H2>
<H2><a name="Chicken_nn18">21.7 Unsupported features and known problems</a></H2>
<ul>
@ -560,7 +560,7 @@ all the modules.</p>
<a href="SWIGPlus.html#SWIGPlus_default_args">%feature(compactdefaultargs)</a>.</li>
</ul>
<H3><a name="Chicken_nn19"></a>20.7.1 TinyCLOS problems with Chicken version &lt;= 1.92</H3>
<H3><a name="Chicken_nn19">21.7.1 TinyCLOS problems with Chicken version &lt;= 1.92</a></H3>
<p>In Chicken versions equal to or below 1.92, TinyCLOS has a limitation such that generic methods do not properly work on methods

361
Doc/Manual/Contents.html
View file

@ -1,10 +1,12 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>SWIG Users Manual</TITLE>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</HEAD>
<BODY BGCOLOR="#ffffff">
<H1><a name="Contents"></a>SWIG Users Manual</H1>
<p>
@ -16,13 +18,23 @@
<ul>
<li><a href="Preface.html#Preface_nn2">Introduction</a>
<li><a href="Preface.html#Preface_nn4">SWIG Versions</a>
<li><a href="Preface.html#Preface_license">SWIG License</a>
<li><a href="Preface.html#Preface_nn5">SWIG resources</a>
<li><a href="Preface.html#Preface_nn6">Prerequisites</a>
<li><a href="Preface.html#Preface_nn7">Organization of this manual</a>
<li><a href="Preface.html#Preface_nn8">How to avoid reading the manual</a>
<li><a href="Preface.html#Preface_nn9">Backwards compatibility</a>
<li><a href="Preface.html#Preface_release_notes">Release notes</a>
<li><a href="Preface.html#Preface_nn10">Credits</a>
<li><a href="Preface.html#Preface_nn11">Bug reports</a>
<li><a href="Preface.html#Preface_installation">Installation</a>
<ul>
<li><a href="Preface.html#Preface_windows_installation">Windows installation</a>
<li><a href="Preface.html#Preface_unix_installation">Unix installation</a>
<li><a href="Preface.html#Preface_osx_installation">Macintosh OS X installation</a>
<li><a href="Preface.html#Preface_testing">Testing</a>
<li><a href="Preface.html#Preface_examples">Examples</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -132,8 +144,8 @@
<li><a href="SWIG.html#SWIG_nn10">Basic Type Handling</a>
<li><a href="SWIG.html#SWIG_nn11">Global Variables</a>
<li><a href="SWIG.html#SWIG_nn12">Constants</a>
<li><a href="SWIG.html#SWIG_nn13">A brief word about <tt>const</tt></a>
<li><a href="SWIG.html#SWIG_nn14">A cautionary tale of <tt>char *</tt></a>
<li><a href="SWIG.html#SWIG_nn13">A brief word about const</a>
<li><a href="SWIG.html#SWIG_nn14">A cautionary tale of char *</a>
</ul>
<li><a href="SWIG.html#SWIG_nn15">Pointers and complex objects</a>
<ul>
@ -148,7 +160,7 @@
<li><a href="SWIG.html#SWIG_nn22">Passing structures by value</a>
<li><a href="SWIG.html#SWIG_nn23">Return by value</a>
<li><a href="SWIG.html#SWIG_nn24">Linking to structure variables</a>
<li><a href="SWIG.html#SWIG_nn25">Linking to <tt>char *</tt></a>
<li><a href="SWIG.html#SWIG_nn25">Linking to char *</a>
<li><a href="SWIG.html#SWIG_nn26">Arrays</a>
<li><a href="SWIG.html#SWIG_readonly_variables">Creating read-only variables</a>
<li><a href="SWIG.html#SWIG_rename_ignore">Renaming and ignoring declarations</a>
@ -252,7 +264,61 @@
</div>
<!-- INDEX -->
<h3><a href="Preprocessor.html#Preprocessor">7 Preprocessing</a></h3>
<h3><a href="CPlusPlus11.html#CPlusPlus11">7 SWIG and C++11</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="CPlusPlus11.html#CPlusPlus11_introduction">Introduction</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_core_language_changes">Core language changes</a>
<ul>
<li><a href="CPlusPlus11.html#CPlusPlus11_rvalue_reference_and_move_semantics">Rvalue reference and move semantics</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_generalized_constant_expressions">Generalized constant expressions</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_extern_template">Extern template</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_initializer_lists">Initializer lists</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_uniform_initialization">Uniform initialization</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_type_inference">Type inference</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_range_based_for_loop">Range-based for-loop</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_lambda_functions_and_expressions">Lambda functions and expressions</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_alternate_function_syntax">Alternate function syntax</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_object_construction_improvement">Object construction improvement</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_explicit_overrides_final">Explicit overrides and final</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_null_pointer_constant">Null pointer constant</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_strongly_typed_enumerations">Strongly typed enumerations</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_double_angle_brackets">Double angle brackets</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_explicit_conversion_operators">Explicit conversion operators</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_alias_templates">Alias templates</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_unrestricted_unions">Unrestricted unions</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_variadic_templates">Variadic templates</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_new_string_literals">New string literals</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_user_defined_literals">User-defined literals</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_thread_local_storage">Thread-local storage</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_defaulted_deleted">Explicitly defaulted functions and deleted functions</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_type_long_long_int">Type long long int</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_static_assertions">Static assertions</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_sizeof">Allow sizeof to work on members of classes without an explicit object</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_noexcept">Exception specifications and noexcept</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_alignment">Control and query object alignment</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_attributes">Attributes</a>
</ul>
<li><a href="CPlusPlus11.html#CPlusPlus11_standard_library_changes">Standard library changes</a>
<ul>
<li><a href="CPlusPlus11.html#CPlusPlus11_threading_facilities">Threading facilities</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_tuple_types">Tuple types</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_hash_tables">Hash tables</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_regular_expressions">Regular expressions</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_general_purpose_smart_pointers">General-purpose smart pointers</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_extensible_random_number_facility">Extensible random number facility</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_wrapper_reference">Wrapper reference</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_polymorphous_wrappers_for_function_objects">Polymorphous wrappers for function objects</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_type_traits_for_metaprogramming">Type traits for metaprogramming</a>
<li><a href="CPlusPlus11.html#CPlusPlus11_uniform_method_for_computing_return_type_of_function_objects">Uniform method for computing return type of function objects</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Preprocessor.html#Preprocessor">8 Preprocessing</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -275,7 +341,7 @@
</div>
<!-- INDEX -->
<h3><a href="Library.html#Library">8 SWIG library</a></h3>
<h3><a href="Library.html#Library">9 SWIG library</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -301,6 +367,7 @@
<li><a href="Library.html#Library_std_vector">std::vector</a>
<li><a href="Library.html#Library_stl_exceptions">STL exceptions</a>
<li><a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a>
<li><a href="Library.html#Library_std_auto_ptr">auto_ptr smart pointer</a>
</ul>
<li><a href="Library.html#Library_nn16">Utility Libraries</a>
<ul>
@ -310,7 +377,7 @@
</div>
<!-- INDEX -->
<h3><a href="Arguments.html#Arguments">9 Argument Handling</a></h3>
<h3><a href="Arguments.html#Arguments">10 Argument Handling</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -333,7 +400,7 @@
</div>
<!-- INDEX -->
<h3><a href="Typemaps.html#Typemaps">10 Typemaps</a></h3>
<h3><a href="Typemaps.html#Typemaps">11 Typemaps</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -376,6 +443,8 @@
<li><a href="Typemaps.html#Typemaps_special_macro_descriptor">$descriptor(type)</a>
<li><a href="Typemaps.html#Typemaps_special_macro_typemap">$typemap(method, typepattern)</a>
</ul>
<li><a href="Typemaps.html#Typemaps_special_variable_attributes">Special variables and typemap attributes</a>
<li><a href="Typemaps.html#Typemaps_special_variables_and_macros">Special variables combined with special variable macros</a>
</ul>
<li><a href="Typemaps.html#Typemaps_nn25">Common typemap methods</a>
<ul>
@ -413,7 +482,7 @@
<li><a href="Typemaps.html#Typemaps_runtime_type_checker_usage">Usage</a>
</ul>
<li><a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a>
<li><a href="Typemaps.html#Typemaps_nn48">More about <tt>%apply</tt> and <tt>%clear</tt></a>
<li><a href="Typemaps.html#Typemaps_nn48">More about %apply and %clear</a>
<li><a href="Typemaps.html#Typemaps_nn47">Passing data between typemaps</a>
<li><a href="Typemaps.html#Typemaps_nn52">C++ "this" pointer</a>
<li><a href="Typemaps.html#Typemaps_nn51">Where to go for more information?</a>
@ -421,7 +490,7 @@
</div>
<!-- INDEX -->
<h3><a href="Customization.html#Customization">11 Customization Features</a></h3>
<h3><a href="Customization.html#Customization">12 Customization Features</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -449,7 +518,7 @@
</div>
<!-- INDEX -->
<h3><a href="Contract.html#Contract">12 Contracts</a></h3>
<h3><a href="Contract.html#Contract">13 Contracts</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -462,7 +531,7 @@
</div>
<!-- INDEX -->
<h3><a href="Varargs.html#Varargs">13 Variable Length Arguments</a></h3>
<h3><a href="Varargs.html#Varargs">14 Variable Length Arguments</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -480,7 +549,7 @@
</div>
<!-- INDEX -->
<h3><a href="Warnings.html#Warnings">14 Warning Messages</a></h3>
<h3><a href="Warnings.html#Warnings">15 Warning Messages</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -508,7 +577,7 @@
</div>
<!-- INDEX -->
<h3><a href="Modules.html#Modules">15 Working with Modules</a></h3>
<h3><a href="Modules.html#Modules">16 Working with Modules</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -524,7 +593,7 @@
</div>
<!-- INDEX -->
<h3><a href="CCache.html#CCache">16 Using SWIG with ccache - ccache-swig(1) manpage</a></h3>
<h3><a href="CCache.html#CCache">17 Using SWIG with ccache - ccache-swig(1) manpage</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -550,7 +619,7 @@
</div>
<!-- INDEX -->
<h3><a href="Allegrocl.html#Allegrocl">17 SWIG and Allegro Common Lisp</a></h3>
<h3><a href="Allegrocl.html#Allegrocl">18 SWIG and Allegro Common Lisp</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -634,7 +703,7 @@
</div>
<!-- INDEX -->
<h3><a href="Android.html#Android">18 SWIG and Android</a></h3>
<h3><a href="Android.html#Android">19 SWIG and Android</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -645,17 +714,23 @@
<li><a href="Android.html#Android_examples_intro">Examples introduction</a>
<li><a href="Android.html#Android_example_simple">Simple C example</a>
<li><a href="Android.html#Android_example_class">C++ class example</a>
<li><a href="Android.html#Android_examples_other">Other examples</a>
</ul>
<li><a href="Android.html#Android_stl">C++ STL</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="CSharp.html#CSharp">19 SWIG and C#</a></h3>
<h3><a href="CSharp.html#CSharp">20 SWIG and C#</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="CSharp.html#CSharp_introduction">Introduction</a>
<ul>
<li><a href="CSharp.html#CSharp_introduction_swig2_compatibility">SWIG 2 Compatibility</a>
<li><a href="CSharp.html#CSharp_commandline">Additional command line options</a>
</ul>
<li><a href="CSharp.html#CSharp_differences_java">Differences to the Java module</a>
<li><a href="CSharp.html#CSharp_void_pointers">Void pointers</a>
<li><a href="CSharp.html#CSharp_arrays">C# Arrays</a>
@ -677,13 +752,14 @@
<li><a href="CSharp.html#CSharp_directors_implementation">Directors implementation</a>
<li><a href="CSharp.html#CSharp_director_caveats">Director caveats</a>
</ul>
<li><a href="CSharp.html#CSharp_multiple_modules">Multiples modules</a>
<li><a href="CSharp.html#CSharp_multiple_modules">Multiple modules</a>
<li><a href="CSharp.html#CSharp_typemap_examples">C# Typemap examples</a>
<ul>
<li><a href="CSharp.html#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="CSharp.html#CSharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="CSharp.html#CSharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a>
<li><a href="CSharp.html#CSharp_date_properties">A date example demonstrating marshalling of C# properties</a>
<li><a href="CSharp.html#CSharp_date_pre_post_directors">Date example demonstrating the 'pre' and 'post' typemap attributes for directors</a>
<li><a href="CSharp.html#CSharp_partial_classes">Turning wrapped classes into partial classes</a>
<li><a href="CSharp.html#CSharp_extending_proxy_class">Extending proxy classes with additional C# code</a>
<li><a href="CSharp.html#CSharp_enum_underlying_type">Underlying type for enums</a>
@ -692,7 +768,7 @@
</div>
<!-- INDEX -->
<h3><a href="Chicken.html#Chicken">20 SWIG and Chicken</a></h3>
<h3><a href="Chicken.html#Chicken">21 SWIG and Chicken</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -730,7 +806,7 @@
</div>
<!-- INDEX -->
<h3><a href="D.html#D">21 SWIG and D</a></h3>
<h3><a href="D.html#D">22 SWIG and D</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -747,13 +823,13 @@
<li><a href="D.html#D_code_injection_typemaps">Code injection typemaps</a>
<li><a href="D.html#D_special_variables">Special variable macros</a>
</ul>
<li><a href="D.html#D_features"><tt>%feature</tt>s</a>
<li><a href="D.html#D_features">D and %feature</a>
<li><a href="D.html#D_pragmas">Pragmas</a>
<li><a href="D.html#D_exceptions">D Exceptions</a>
<li><a href="D.html#D_directors">D Directors</a>
<li><a href="D.html#D_other_features">Other features</a>
<ul>
<li><a href="D.html#D_nspace">Extended namespace support (<tt>nspace</tt>)</a>
<li><a href="D.html#D_nspace">Extended namespace support (nspace)</a>
<li><a href="D.html#D_native_pointer_support">Native pointer support</a>
<li><a href="D.html#D_operator_overloading">Operator overloading</a>
<li><a href="D.html#D_test_suite">Running the test-suite</a>
@ -764,16 +840,17 @@
</div>
<!-- INDEX -->
<h3><a href="Go.html#Go">22 SWIG and Go</a></h3>
<h3><a href="Go.html#Go">23 SWIG and Go</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Go.html#Go_overview">Overview</a>
<li><a href="Go.html#Go_examples">Examples</a>
<li><a href="Go.html#Go_running_swig">Running SWIG with Go</a>
<ul>
<li><a href="Go.html#Go_commandline">Additional Commandline Options</a>
<li><a href="Go.html#Go_outputs">Go Output Files</a>
<li><a href="Go.html#Go_commandline">Go-specific Commandline Options</a>
<li><a href="Go.html#Go_outputs">Generated Wrapper Files</a>
</ul>
<li><a href="Go.html#Go_basic_tour">A tour of basic C/C++ wrapping</a>
<ul>
@ -783,25 +860,38 @@
<li><a href="Go.html#Go_enumerations">Go Enumerations</a>
<li><a href="Go.html#Go_classes">Go Classes</a>
<ul>
<li><a href="Go.html#Go_class_memory">Go Class Memory Management</a>
<li><a href="Go.html#Go_class_inheritance">Go Class Inheritance</a>
</ul>
<li><a href="Go.html#Go_templates">Go Templates</a>
<li><a href="Go.html#Go_director_classes">Go Director Classes</a>
<ul>
<li><a href="Go.html#Go_director_example_cpp_code">Example C++ code</a>
<li><a href="Go.html#Go_director_enable">Enable director feature</a>
<li><a href="Go.html#Go_director_ctor_dtor">Constructor and destructor</a>
<li><a href="Go.html#Go_director_overriding">Override virtual methods</a>
<li><a href="Go.html#Go_director_base_methods">Call base methods</a>
<li><a href="Go.html#Go_director_subclass">Subclass via embedding</a>
<li><a href="Go.html#Go_director_finalizer">Memory management with runtime.SetFinalizer</a>
<li><a href="Go.html#Go_director_foobargo_class">Complete FooBarGo example class</a>
</ul>
<li><a href="Go.html#Go_primitive_type_mappings">Default Go primitive type mappings</a>
<li><a href="Go.html#Go_output_arguments">Output arguments</a>
<li><a href="Go.html#Go_adding_additional_code">Adding additional go code</a>
<li><a href="Go.html#Go_typemaps">Go typemaps</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Guile.html#Guile">23 SWIG and Guile</a></h3>
<h3><a href="Guile.html#Guile">24 SWIG and Guile</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Guile.html#Guile_nn1">Supported Guile Versions</a>
<li><a href="Guile.html#Guile_nn2">Meaning of "Module"</a>
<li><a href="Guile.html#Guile_nn3">Using the SCM or GH Guile API</a>
<li><a href="Guile.html#Guile_nn3">Old GH Guile API</a>
<li><a href="Guile.html#Guile_nn4">Linkage</a>
<ul>
<li><a href="Guile.html#Guile_nn5">Simple Linkage</a>
@ -814,8 +904,7 @@
<li><a href="Guile.html#Guile_nn11">Typemaps</a>
<li><a href="Guile.html#Guile_nn12">Representation of pointers as smobs</a>
<ul>
<li><a href="Guile.html#Guile_nn13">GH Smobs</a>
<li><a href="Guile.html#Guile_nn14">SCM Smobs</a>
<li><a href="Guile.html#Guile_nn14">Smobs</a>
<li><a href="Guile.html#Guile_nn15">Garbage Collection</a>
</ul>
<li><a href="Guile.html#Guile_nn16">Exception Handling</a>
@ -830,7 +919,7 @@
</div>
<!-- INDEX -->
<h3><a href="Java.html#Java">24 SWIG and Java</a></h3>
<h3><a href="Java.html#Java">25 SWIG and Java</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -878,6 +967,10 @@
<li><a href="Java.html#Java_namespaces">C++ namespaces</a>
<li><a href="Java.html#Java_templates">C++ templates</a>
<li><a href="Java.html#Java_smart_pointers">C++ Smart Pointers</a>
<ul>
<li><a href="Java.html#Java_smart_pointers_shared_ptr">The shared_ptr Smart Pointer</a>
<li><a href="Java.html#Java_smart_pointers_generic">Generic Smart Pointers</a>
</ul>
</ul>
<li><a href="Java.html#Java_further_details">Further details on the generated Java classes</a>
<ul>
@ -904,6 +997,7 @@
<li><a href="Java.html#Java_proper_enums_classes">Proper Java enum classes</a>
<li><a href="Java.html#Java_typeunsafe_enums_classes">Type unsafe enum classes</a>
</ul>
<li><a href="Java.html#Java_interfaces">Interfaces</a>
</ul>
<li><a href="Java.html#Java_directors">Cross language polymorphism using directors</a>
<ul>
@ -912,6 +1006,8 @@
<li><a href="Java.html#Java_directors_overhead">Overhead and code bloat</a>
<li><a href="Java.html#Java_directors_example">Simple directors example</a>
<li><a href="Java.html#Java_directors_threading">Director threading issues</a>
<li><a href="Java.html#Java_directors_performance">Director performance tuning</a>
<li><a href="Java.html#Java_exceptions_from_directors">Java exceptions from directors</a>
</ul>
<li><a href="Java.html#Java_allprotected">Accessing protected members</a>
<li><a href="Java.html#Java_common_customization">Common customization features</a>
@ -973,7 +1069,49 @@
</div>
<!-- INDEX -->
<h3><a href="Lisp.html#Lisp">25 SWIG and Common Lisp</a></h3>
<h3><a href="Javascript.html#Javascript">26 SWIG and Javascript</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Javascript.html#Javascript_overview">Overview</a>
<li><a href="Javascript.html#Javascript_preliminaries">Preliminaries</a>
<ul>
<li><a href="Javascript.html#Javascript_running_swig">Running SWIG</a>
<li><a href="Javascript.html#Javascript_running_tests_examples">Running Tests and Examples</a>
<li><a href="Javascript.html#Javascript_known_issues">Known Issues</a>
</ul>
<li><a href="Javascript.html#Javascript_integration">Integration</a>
<ul>
<li><a href="Javascript.html#Javascript_node_extensions">Creating node.js Extensions</a>
<ul>
<li><a href="Javascript.html#Javascript_troubleshooting">Troubleshooting</a>
</ul>
<li><a href="Javascript.html#Javascript_embedded_webkit">Embedded Webkit</a>
<ul>
<li><a href="Javascript.html#Javascript_osx">Mac OS X</a>
<li><a href="Javascript.html#Javascript_gtk">GTK</a>
</ul>
<li><a href="Javascript.html#Javascript_applications_webkit">Creating Applications with node-webkit</a>
</ul>
<li><a href="Javascript.html#Javascript_examples">Examples</a>
<ul>
<li><a href="Javascript.html#Javascript_simple_example">Simple</a>
<li><a href="Javascript.html#Javascript_class_example">Class</a>
</ul>
<li><a href="Javascript.html#Javascript_implementation">Implementation</a>
<ul>
<li><a href="Javascript.html#Javascript_source_code">Source Code</a>
<li><a href="Javascript.html#Javascript_code_templates">Code Templates</a>
<li><a href="Javascript.html#Javascript_emitter">Emitter</a>
<li><a href="Javascript.html#Javascript_emitter_states">Emitter states</a>
<li><a href="Javascript.html#Javascript_jsc_exceptions">Handling Exceptions in JavascriptCore</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Lisp.html#Lisp">27 SWIG and Common Lisp</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -996,7 +1134,7 @@
</div>
<!-- INDEX -->
<h3><a href="Lua.html#Lua">26 SWIG and Lua</a></h3>
<h3><a href="Lua.html#Lua">28 SWIG and Lua</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1015,8 +1153,11 @@
<li><a href="Lua.html#Lua_nn9">Functions</a>
<li><a href="Lua.html#Lua_nn10">Global variables</a>
<li><a href="Lua.html#Lua_nn11">Constants and enums</a>
<ul>
<li><a href="Lua.html#Lua_nn13">Constants/enums and classes/structures</a>
</ul>
<li><a href="Lua.html#Lua_nn12">Pointers</a>
<li><a href="Lua.html#Lua_nn13">Structures</a>
<li><a href="Lua.html#Lua_structures">Structures</a>
<li><a href="Lua.html#Lua_nn14">C++ classes</a>
<li><a href="Lua.html#Lua_nn15">C++ inheritance</a>
<li><a href="Lua.html#Lua_nn16">Pointers, references, values, and arrays</a>
@ -1027,17 +1168,23 @@
<li><a href="Lua.html#Lua_nn21">C++ templates</a>
<li><a href="Lua.html#Lua_nn22">C++ Smart Pointers</a>
<li><a href="Lua.html#Lua_nn23">C++ Exceptions</a>
<li><a href="Lua.html#Lua_namespaces">Namespaces </a>
<ul>
<li><a href="Lua.html#Lua_nn27">Compatibility Note </a>
<li><a href="Lua.html#Lua_nn29">Names </a>
<li><a href="Lua.html#Lua_nn30">Inheritance </a>
</ul>
</ul>
<li><a href="Lua.html#Lua_nn24">Typemaps</a>
<ul>
<li><a href="Lua.html#Lua_nn25">What is a typemap?</a>
<li><a href="Lua.html#Lua_nn26">Using typemaps</a>
<li><a href="Lua.html#Lua_nn27">Typemaps and arrays</a>
<li><a href="Lua.html#Lua_nn28">Typemaps and pointer-pointer functions</a>
<li><a href="Lua.html#Lua_typemap_arrays">Typemaps and arrays</a>
<li><a href="Lua.html#Lua_typemaps_ptr_ptr_functions">Typemaps and pointer-pointer functions</a>
</ul>
<li><a href="Lua.html#Lua_nn29">Writing typemaps</a>
<li><a href="Lua.html#Lua_writing_typemaps">Writing typemaps</a>
<ul>
<li><a href="Lua.html#Lua_nn30">Typemaps you can write</a>
<li><a href="Lua.html#Lua_typemaps_write">Typemaps you can write</a>
<li><a href="Lua.html#Lua_nn31">SWIG's Lua-C API</a>
</ul>
<li><a href="Lua.html#Lua_nn32">Customization of your Bindings</a>
@ -1055,7 +1202,7 @@
</div>
<!-- INDEX -->
<h3><a href="Modula3.html#Modula3">27 SWIG and Modula-3</a></h3>
<h3><a href="Modula3.html#Modula3">29 SWIG and Modula-3</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1093,7 +1240,7 @@
</div>
<!-- INDEX -->
<h3><a href="Mzscheme.html#Mzscheme">28 SWIG and MzScheme/Racket</a></h3>
<h3><a href="Mzscheme.html#Mzscheme">30 SWIG and MzScheme/Racket</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1105,7 +1252,7 @@
</div>
<!-- INDEX -->
<h3><a href="Ocaml.html#Ocaml">29 SWIG and Ocaml</a></h3>
<h3><a href="Ocaml.html#Ocaml">31 SWIG and Ocaml</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1145,10 +1292,10 @@
<li><a href="Ocaml.html#Ocaml_nn24">Overriding Methods in Ocaml</a>
<li><a href="Ocaml.html#Ocaml_nn25">Director Usage Example</a>
<li><a href="Ocaml.html#Ocaml_nn26">Creating director objects</a>
<li><a href="Ocaml.html#Ocaml_nn27">Typemaps for directors, <tt>directorin, directorout, directorargout</tt></a>
<li><a href="Ocaml.html#Ocaml_nn28"><tt>directorin</tt> typemap</a>
<li><a href="Ocaml.html#Ocaml_nn29"><tt>directorout</tt> typemap</a>
<li><a href="Ocaml.html#Ocaml_nn30"><tt>directorargout</tt> typemap</a>
<li><a href="Ocaml.html#Ocaml_nn27">Typemaps for directors, directorin, directorout, directorargout</a>
<li><a href="Ocaml.html#Ocaml_nn28">typemap</a>
<li><a href="Ocaml.html#Ocaml_nn29">directorout typemap</a>
<li><a href="Ocaml.html#Ocaml_nn30">directorargout typemap</a>
</ul>
<li><a href="Ocaml.html#Ocaml_nn31">Exceptions</a>
</ul>
@ -1156,7 +1303,7 @@
</div>
<!-- INDEX -->
<h3><a href="Octave.html#Octave">30 SWIG and Octave</a></h3>
<h3><a href="Octave.html#Octave">32 SWIG and Octave</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1182,6 +1329,10 @@
<li><a href="Octave.html#Octave_nn19">Class extension with %extend</a>
<li><a href="Octave.html#Octave_nn20">C++ templates</a>
<li><a href="Octave.html#Octave_nn21">C++ Smart Pointers</a>
<ul>
<li><a href="Octave.html#Octave_smart_pointers_shared_ptr">The shared_ptr Smart Pointer</a>
<li><a href="Octave.html#Octave_smart_pointers_generic">Generic Smart Pointers</a>
</ul>
<li><a href="Octave.html#Octave_nn22">Directors (calling Octave from C++ code)</a>
<li><a href="Octave.html#Octave_nn23">Threads</a>
<li><a href="Octave.html#Octave_nn24">Memory management</a>
@ -1192,7 +1343,7 @@
</div>
<!-- INDEX -->
<h3><a href="Perl5.html#Perl5">31 SWIG and Perl5</a></h3>
<h3><a href="Perl5.html#Perl5">33 SWIG and Perl5</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1255,11 +1406,20 @@
<li><a href="Perl5.html#Perl5_nn46">Modifying the proxy methods</a>
</ul>
<li><a href="Perl5.html#Perl5_nn47">Adding additional Perl code</a>
<li><a href="Perl5.html#Perl5_directors">Cross language polymorphism</a>
<ul>
<li><a href="Perl5.html#Perl5_nn48">Enabling directors</a>
<li><a href="Perl5.html#Perl5_nn49">Director classes</a>
<li><a href="Perl5.html#Perl5_nn50">Ownership and object destruction</a>
<li><a href="Perl5.html#Perl5_nn51">Exception unrolling</a>
<li><a href="Perl5.html#Perl5_nn52">Overhead and code bloat</a>
<li><a href="Perl5.html#Perl5_nn53">Typemaps</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Php.html#Php">32 SWIG and PHP</a></h3>
<h3><a href="Php.html#Php">34 SWIG and PHP</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1278,10 +1438,11 @@
<li><a href="Php.html#Php_nn2_5">Pointers and References</a>
<li><a href="Php.html#Php_nn2_6">Structures and C++ classes</a>
<ul>
<li><a href="Php.html#Php_nn2_6_1">Using <tt>-noproxy</tt></a>
<li><a href="Php.html#Php_nn2_6_1">Using -noproxy</a>
<li><a href="Php.html#Php_nn2_6_2">Constructors and Destructors</a>
<li><a href="Php.html#Php_nn2_6_3">Static Member Variables</a>
<li><a href="Php.html#Php_nn2_6_4">Static Member Functions</a>
<li><a href="Php.html#Php_nn2_6_5">Specifying Implemented Interfaces</a>
</ul>
<li><a href="Php.html#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a>
</ul>
@ -1299,7 +1460,7 @@
</div>
<!-- INDEX -->
<h3><a href="Pike.html#Pike">33 SWIG and Pike</a></h3>
<h3><a href="Pike.html#Pike">35 SWIG and Pike</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1323,7 +1484,7 @@
</div>
<!-- INDEX -->
<h3><a href="Python.html#Python">34 SWIG and Python</a></h3>
<h3><a href="Python.html#Python">36 SWIG and Python</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1356,6 +1517,10 @@
<li><a href="Python.html#Python_nn25">C++ namespaces</a>
<li><a href="Python.html#Python_nn26">C++ templates</a>
<li><a href="Python.html#Python_nn27">C++ Smart Pointers</a>
<ul>
<li><a href="Python.html#Python_smart_pointers_shared_ptr">The shared_ptr Smart Pointer</a>
<li><a href="Python.html#Python_smart_pointers_generic">Generic Smart Pointers</a>
</ul>
<li><a href="Python.html#Python_nn27a">C++ reference counted objects</a>
</ul>
<li><a href="Python.html#Python_nn28">Further details on the Python class interface</a>
@ -1392,6 +1557,7 @@
<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_default_args">Default arguments</a>
</ul>
<li><a href="Python.html#Python_nn53">Typemaps</a>
<ul>
@ -1423,17 +1589,25 @@
<li><a href="Python.html#Python_nn71">%feature("docstring")</a>
</ul>
<li><a href="Python.html#Python_nn72">Python Packages</a>
<ul>
<li><a href="Python.html#Python_modulepackage">Setting the Python package</a>
<li><a href="Python.html#Python_absrelimports">Absolute and relative imports</a>
<li><a href="Python.html#Python_absimport">Enforcing absolute import semantics</a>
<li><a href="Python.html#Python_importfrominit">Importing from __init__.py</a>
</ul>
<li><a href="Python.html#Python_python3support">Python 3 Support</a>
<ul>
<li><a href="Python.html#Python_nn74">Function annotation</a>
<li><a href="Python.html#Python_nn75">Buffer interface</a>
<li><a href="Python.html#Python_nn76">Abstract base classes</a>
<li><a href="Python.html#Python_nn77">Byte string output conversion</a>
<li><a href="Python.html#Python_2_unicode">Python 2 Unicode</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="R.html#R">35 SWIG and R</a></h3>
<h3><a href="R.html#R">37 SWIG and R</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1449,7 +1623,7 @@
</div>
<!-- INDEX -->
<h3><a href="Ruby.html#Ruby">36 SWIG and Ruby</a></h3>
<h3><a href="Ruby.html#Ruby">38 SWIG and Ruby</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1485,6 +1659,10 @@
<li><a href="Ruby.html#Ruby_C_STL_Functors">C++ STL Functors</a>
<li><a href="Ruby.html#Ruby_C_Iterators">C++ STL Iterators</a>
<li><a href="Ruby.html#Ruby_nn24">C++ Smart Pointers</a>
<ul>
<li><a href="Ruby.html#Ruby_smart_pointers_shared_ptr">The shared_ptr Smart Pointer</a>
<li><a href="Ruby.html#Ruby_smart_pointers_generic">Generic Smart Pointers</a>
</ul>
<li><a href="Ruby.html#Ruby_nn25">Cross-Language Polymorphism</a>
<ul>
<li><a href="Ruby.html#Ruby_nn26">Exception Unrolling</a>
@ -1514,9 +1692,9 @@
<li><a href="Ruby.html#Ruby_Placement_of_typemaps">Placement of typemaps</a>
<li><a href="Ruby.html#Ruby_nn39">Ruby typemaps</a>
<ul>
<li><a href="Ruby.html#Ruby_in_typemap">&nbsp;"in" typemap</a>
<li><a href="Ruby.html#Ruby_in_typemap">"in" typemap</a>
<li><a href="Ruby.html#Ruby_typecheck_typemap">"typecheck" typemap</a>
<li><a href="Ruby.html#Ruby_out_typemap">&nbsp;"out" typemap</a>
<li><a href="Ruby.html#Ruby_out_typemap">"out" typemap</a>
<li><a href="Ruby.html#Ruby_arginit_typemap">"arginit" typemap</a>
<li><a href="Ruby.html#Ruby_default_typemap">"default" typemap</a>
<li><a href="Ruby.html#Ruby_check_typemap">"check" typemap</a>
@ -1583,7 +1761,76 @@
</div>
<!-- INDEX -->
<h3><a href="Tcl.html#Tcl">37 SWIG and Tcl</a></h3>
<h3><a href="Scilab.html#Scilab">39 SWIG and Scilab</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Scilab.html#Scilab_preliminaries">Preliminaries</a>
<li><a href="Scilab.html#Scilab_running_swig">Running SWIG</a>
<ul>
<li><a href="Scilab.html#Scilab_running_swig_generating_module">Generating the module</a>
<li><a href="Scilab.html#Scilab_running_swig_building_module">Building the module</a>
<li><a href="Scilab.html#Scilab_running_swig_loading_module">Loading the module</a>
<li><a href="Scilab.html#Scilab_running_swig_using_module">Using the module</a>
<li><a href="Scilab.html#Scilab_running_swig_options">Scilab command line options</a>
</ul>
<li><a href="Scilab.html#Scilab_wrapping">A basic tour of C/C++ wrapping</a>
<ul>
<li><a href="Scilab.html#Scilab_wrapping_overview">Overview</a>
<li><a href="Scilab.html#Scilab_wrapping_identifiers">Identifiers</a>
<li><a href="Scilab.html#Scilab_wrapping_functions">Functions</a>
<ul>
<li><a href="Scilab.html#Scilab_nn13">Argument passing</a>
<li><a href="Scilab.html#Scilab_nn14">Multiple output arguments</a>
</ul>
<li><a href="Scilab.html#Scilab_wrapping_global_variables">Global variables</a>
<li><a href="Scilab.html#Scilab_wrapping_constants_and_enums">Constants and enumerations</a>
<ul>
<li><a href="Scilab.html#Scilab_wrapping_constants">Constants</a>
<li><a href="Scilab.html#Scilab_wrapping_enums">Enumerations</a>
</ul>
<li><a href="Scilab.html#Scilab_wrapping_pointers">Pointers</a>
<ul>
<li><a href="Scilab.html#Scilab_wrapping_pointers_pointer_adresses">Utility functions</a>
<li><a href="Scilab.html#Scilab_wrapping_pointers_null_pointers">Null pointers</a>
</ul>
<li><a href="Scilab.html#Scilab_wrapping_structs">Structures</a>
<li><a href="Scilab.html#Scilab_wrapping_cpp_classes">C++ classes</a>
<li><a href="Scilab.html#Scilab_wrapping_cpp_inheritance">C++ inheritance</a>
<li><a href="Scilab.html#Scilab_wrapping_pointers_references_values_arrays">Pointers, references, values, and arrays</a>
<li><a href="Scilab.html#Scilab_wrapping_cpp_templates">C++ templates</a>
<li><a href="Scilab.html#Scilab_wrapping_cpp_operators">C++ operators</a>
<li><a href="Scilab.html#Scilab_wrapping_cpp_namespaces">C++ namespaces</a>
<li><a href="Scilab.html#Scilab_wrapping_cpp_exceptions">C++ exceptions</a>
<li><a href="Scilab.html#Scilab_wrapping_cpp_stl">C++ STL</a>
</ul>
<li><a href="Scilab.html#Scilab_typemaps">Type mappings and libraries</a>
<ul>
<li><a href="Scilab.html#Scilab_typemaps_primitive_types">Default primitive type mappings</a>
<li><a href="Scilab.html#Scilab_typemaps_non-primitive_types">Default type mappings for non-primitive types</a>
<li><a href="Scilab.html#Scilab_typemaps_arrays">Arrays</a>
<li><a href="Scilab.html#Scilab_typemaps_pointer-to-pointers">Pointer-to-pointers</a>
<li><a href="Scilab.html#Scilab_typemaps_matrices">Matrices</a>
<li><a href="Scilab.html#Scilab_typemaps_stl">STL</a>
</ul>
<li><a href="Scilab.html#Scilab_module_initialization">Module initialization</a>
<li><a href="Scilab.html#Scilab_building_modes">Building modes</a>
<ul>
<li><a href="Scilab.html#Scilab_building_modes_nobuilder_mode">No-builder mode</a>
<li><a href="Scilab.html#Scilab_building_modes_builder_mode">Builder mode</a>
</ul>
<li><a href="Scilab.html#Scilab_generated_scripts">Generated scripts</a>
<ul>
<li><a href="Scilab.html#Scilab_generated_scripts_builder_script">Builder script</a>
<li><a href="Scilab.html#Scilab_generated_scripts_loader_script">Loader script</a>
</ul>
<li><a href="Scilab.html#Scilab_other_resources">Other resources</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Tcl.html#Tcl">40 SWIG and Tcl</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1649,7 +1896,7 @@
</div>
<!-- INDEX -->
<h3><a href="Extending.html#Extending">38 Extending SWIG to support new languages</a></h3>
<h3><a href="Extending.html#Extending">41 Extending SWIG to support new languages</a></h3>
<!-- INDEX -->
<div class="sectiontoc">

13
Doc/Manual/Contract.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Contract Checking</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Contract"></a>12 Contracts</H1>
<H1><a name="Contract">13 Contracts</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -38,7 +39,7 @@ When one of the rules is violated by a script, a runtime exception is
generated rather than having the program continue to execute.
</p>
<H2><a name="Contract_nn2"></a>12.1 The %contract directive</H2>
<H2><a name="Contract_nn2">13.1 The %contract directive</a></H2>
<p>
@ -94,7 +95,7 @@ RuntimeError: Contract violation: require: (arg1&gt;=0)
</pre>
</div>
<H2><a name="Contract_nn3"></a>12.2 %contract and classes</H2>
<H2><a name="Contract_nn3">13.2 %contract and classes</a></H2>
<p>
@ -173,7 +174,7 @@ specified for the derived class all must hold. In the above example,
this means that both the arguments to <tt>Spam::bar</tt> must be positive.
</p>
<H2><a name="Contract_nn4"></a>12.3 Constant aggregation and %aggregate_check</H2>
<H2><a name="Contract_nn4">13.3 Constant aggregation and %aggregate_check</a></H2>
<p>
@ -262,7 +263,7 @@ Regrettably, there is no automatic way to perform similar checks with enums valu
release.
</p>
<H2><a name="Contract_nn5"></a>12.4 Notes</H2>
<H2><a name="Contract_nn5">13.4 Notes</a></H2>
<p>

148
Doc/Manual/Customization.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Customization Features</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Customization"></a>11 Customization Features</H1>
<H1><a name="Customization">12 Customization Features</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -45,7 +46,7 @@ of exception handling is presented. Then, a more general-purpose
customization mechanism known as "features" is described.
</p>
<H2><a name="Customization_exception"></a>11.1 Exception handling with %exception</H2>
<H2><a name="Customization_exception">12.1 Exception handling with %exception</a></H2>
<p>
@ -100,7 +101,7 @@ for exception handling. That directive is deprecated--<tt>%exception</tt>
provides the same functionality, but is substantially more flexible.
</p>
<H3><a name="Customization_nn3"></a>11.1.1 Handling exceptions in C code</H3>
<H3><a name="Customization_nn3">12.1.1 Handling exceptions in C code</a></H3>
<p>
@ -115,16 +116,18 @@ static char error_message[256];
static int error_status = 0;
void throw_exception(char *msg) {
strncpy(error_message,msg,256);
error_status = 1;
strncpy(error_message,msg,256);
error_status = 1;
}
void clear_exception() {
error_status = 0;
error_status = 0;
}
char *check_exception() {
if (error_status) return error_message;
else return NULL;
if (error_status)
return error_message;
else
return NULL;
}
</pre></div>
@ -136,13 +139,13 @@ To use these functions, functions simply call
<div class="code"><pre>
double inv(double x) {
if (x != 0) return 1.0/x;
else {
throw_exception("Division by zero");
return 0;
}
if (x != 0)
return 1.0/x;
else {
throw_exception("Division by zero");
return 0;
}
}
</pre></div>
<p>
@ -151,12 +154,12 @@ as the following (shown for Perl5) :</p>
<div class="code"><pre>
%exception {
char *err;
clear_exception();
$action
if ((err = check_exception())) {
croak(err);
}
char *err;
clear_exception();
$action
if ((err = check_exception())) {
croak(err);
}
}
</pre></div>
@ -166,7 +169,7 @@ Each target language has its own approach to creating a runtime error/exception
and for Perl it is the <tt>croak</tt> method shown above.
</p>
<H3><a name="Customization_nn4"></a>11.1.2 Exception handling with longjmp()</H3>
<H3><a name="Customization_nn4">12.1.2 Exception handling with longjmp()</a></H3>
<p>
@ -206,8 +209,10 @@ Now, within a C program, you can do the following :</p>
<div class="code"><pre>
double inv(double x) {
if (x) return 1.0/x;
else throw(DivisionByZero);
if (x)
return 1.0/x;
else
throw(DivisionByZero);
}
</pre></div>
@ -221,17 +226,17 @@ Finally, to create a SWIG exception handler, write the following :</p>
%}
%exception {
try {
$action
} catch(RangeError) {
croak("Range Error");
} catch(DivisionByZero) {
croak("Division by zero");
} catch(OutOfMemory) {
croak("Out of memory");
} finally {
croak("Unknown exception");
}
try {
$action
} catch(RangeError) {
croak("Range Error");
} catch(DivisionByZero) {
croak("Division by zero");
} catch(OutOfMemory) {
croak("Out of memory");
} finally {
croak("Unknown exception");
}
}
</pre></div>
@ -240,7 +245,7 @@ Note: This implementation is only intended to illustrate the general idea. To m
modify it to handle nested <tt>try</tt> declarations.
</p>
<H3><a name="Customization_nn5"></a>11.1.3 Handling C++ exceptions</H3>
<H3><a name="Customization_nn5">12.1.3 Handling C++ exceptions</a></H3>
<p>
@ -249,17 +254,17 @@ Handling C++ exceptions is also straightforward. For example:
<div class="code"><pre>
%exception {
try {
$action
} catch(RangeError) {
croak("Range Error");
} catch(DivisionByZero) {
croak("Division by zero");
} catch(OutOfMemory) {
croak("Out of memory");
} catch(...) {
croak("Unknown exception");
}
try {
$action
} catch(RangeError) {
croak("Range Error");
} catch(DivisionByZero) {
croak("Division by zero");
} catch(OutOfMemory) {
croak("Out of memory");
} catch(...) {
croak("Unknown exception");
}
}
</pre></div>
@ -275,7 +280,7 @@ class OutOfMemory {};
</pre>
</div>
<H3><a name="Customization_allowexcept"></a>11.1.4 Exception handlers for variables</H3>
<H3><a name="Customization_allowexcept">12.1.4 Exception handlers for variables</a></H3>
<p>
@ -300,7 +305,7 @@ The <tt>%allowexception</tt> feature works like any other feature and so can be
</pre>
</div>
<H3><a name="Customization_nn6"></a>11.1.5 Defining different exception handlers</H3>
<H3><a name="Customization_nn6">12.1.5 Defining different exception handlers</a></H3>
<p>
@ -319,7 +324,7 @@ critical pieces of code. For example:
<div class="code"><pre>
%exception {
... your exception handler ...
... your exception handler ...
}
/* Define critical operations that can throw exceptions here */
@ -437,7 +442,7 @@ declarations. However, it never really worked that well and the new
%exception directive is much better.
</p>
<H3><a name="Customization_exception_special_variables"></a>11.1.6 Special variables for %exception</H3>
<H3><a name="Customization_exception_special_variables">12.1.6 Special variables for %exception</a></H3>
<p>
@ -454,6 +459,11 @@ variables are replaced with.
<td>The actual operation to be performed (a function call, method invocation, variable access, etc.)</td>
</tr>
<tr>
<td>$name</td>
<td>The C/C++ symbol name for the function.</td>
</tr>
<tr>
<td>$symname</td>
<td>The symbol name used internally by SWIG</td>
@ -479,6 +489,16 @@ variables are replaced with.
<td>The fully qualified C/C++ declaration of the method being wrapped including the return type</td>
</tr>
<tr>
<td>$parentclassname</td>
<td>The parent class name (if any) for a method.</td>
</tr>
<tr>
<td>$parentclasssymname</td>
<td>The target language parent class name (if any) for a method.</td>
</tr>
</table>
<p>
@ -525,14 +545,14 @@ Below shows the expansions for the 1st of the overloaded <tt>something</tt> wrap
</pre></div>
<H3><a name="Customization_nn7"></a>11.1.7 Using The SWIG exception library</H3>
<H3><a name="Customization_nn7">12.1.7 Using The SWIG exception library</a></H3>
<p>
The <tt>exception.i</tt> library file provides support for creating
language independent exceptions in your interfaces. To use it, simply
put an "<tt>%include exception.i</tt>" in your interface file. This
creates a function<tt> SWIG_exception()</tt> that can be used to raise
provides a function <tt>SWIG_exception()</tt> that can be used to raise
common scripting language exceptions in a portable manner. For example :</p>
<div class="code"><pre>
@ -577,12 +597,10 @@ SWIG_NullReferenceError
</pre></div>
<p>
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
functions.
The <tt>SWIG_exception()</tt> function can also be used in typemaps.
</p>
<H2><a name="Customization_ownership"></a>11.2 Object ownership and %newobject</H2>
<H2><a name="Customization_ownership">12.2 Object ownership and %newobject</a></H2>
<p>
@ -739,7 +757,7 @@ char *strdup(const char *s);
The results might not be what you expect.
</p>
<H2><a name="Customization_features"></a>11.3 Features and the %feature directive</H2>
<H2><a name="Customization_features">12.3 Features and the %feature directive</a></H2>
<p>
@ -821,7 +839,7 @@ The following are all equivalent:
The syntax in the first variation will generate the <tt>{ }</tt> delimiters used whereas the other variations will not.
</p>
<H3><a name="Customization_feature_attributes"></a>11.3.1 Feature attributes</H3>
<H3><a name="Customization_feature_attributes">12.3.1 Feature attributes</a></H3>
<p>
@ -862,7 +880,7 @@ In the following example, <tt>MyExceptionClass</tt> is the name of the Java clas
Further details can be obtained from the <a href="Java.html#Java_exception_handling">Java exception handling</a> section.
</p>
<H3><a name="Customization_feature_flags"></a>11.3.2 Feature flags</H3>
<H3><a name="Customization_feature_flags">12.3.2 Feature flags</a></H3>
<p>
@ -960,7 +978,7 @@ in the <tt>swig.swg</tt> Library file. The following shows the alternative synta
The concept of clearing features is discussed next.
</p>
<H3><a name="Customization_clearing_features"></a>11.3.3 Clearing features</H3>
<H3><a name="Customization_clearing_features">12.3.3 Clearing features</a></H3>
<p>
@ -1053,7 +1071,7 @@ The three macros below show this for the "except" feature:
</pre>
</div>
<H3><a name="Customization_features_default_args"></a>11.3.4 Features and default arguments</H3>
<H3><a name="Customization_features_default_args">12.3.4 Features and default arguments</a></H3>
<p>
@ -1069,7 +1087,7 @@ For example:
<div class="code">
<pre>
%feature("except") void hello(int i=0, double d=0.0) { ... }
%feature("except") hello(int i=0, double d=0.0) { ... }
void hello(int i=0, double d=0.0);
</pre>
</div>
@ -1092,7 +1110,7 @@ If the default arguments are not specified in the feature:
<div class="code">
<pre>
%feature("except") void hello(int i, double d) { ... }
%feature("except") hello(int i, double d) { ... }
void hello(int i=0, double d=0.0);
</pre>
</div>
@ -1128,7 +1146,7 @@ specifying or not specifying default arguments in a feature is not applicable as
in SWIG-1.3.23 when the approach to wrapping methods with default arguments was changed.
</p>
<H3><a name="Customization_features_example"></a>11.3.5 Feature example</H3>
<H3><a name="Customization_features_example">12.3.5 Feature example</a></H3>
<p>

72
Doc/Manual/D.html
View file

@ -1,4 +1,4 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and D</title>
@ -6,7 +6,7 @@
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="D"></a>21 SWIG and D</H1>
<H1><a name="D">22 SWIG and D</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -22,13 +22,13 @@
<li><a href="#D_code_injection_typemaps">Code injection typemaps</a>
<li><a href="#D_special_variables">Special variable macros</a>
</ul>
<li><a href="#D_features"><tt>%feature</tt>s</a>
<li><a href="#D_features">D and %feature</a>
<li><a href="#D_pragmas">Pragmas</a>
<li><a href="#D_exceptions">D Exceptions</a>
<li><a href="#D_directors">D Directors</a>
<li><a href="#D_other_features">Other features</a>
<ul>
<li><a href="#D_nspace">Extended namespace support (<tt>nspace</tt>)</a>
<li><a href="#D_nspace">Extended namespace support (nspace)</a>
<li><a href="#D_native_pointer_support">Native pointer support</a>
<li><a href="#D_operator_overloading">Operator overloading</a>
<li><a href="#D_test_suite">Running the test-suite</a>
@ -41,7 +41,7 @@
<H2><a name="D_introduction"></a>21.1 Introduction</H2>
<H2><a name="D_introduction">22.1 Introduction</a></H2>
<p>From the <a href="http://www.digitalmars.com/d/">D Programming Language</a> web site: <em>D is a systems programming language. Its focus is on combining the power and high performance of C and C++ with the programmer productivity of modern languages like Ruby and Python. [...] The D language is statically typed and compiles directly to machine code.</em> As such, it is not very surprising that D is able to directly <a href="http://www.digitalmars.com/d/1.0/interfaceToC.html">interface with C libraries</a>. Why would a SWIG module for D be needed then in the first place?</p>
@ -50,10 +50,10 @@
<p>While these issues can be worked around relatively easy by hand-coding a thin wrapper layer around the C library in question, there is another issue where writing wrapper code per hand is not feasible: C++ libraries. D did not support interfacing to C++ in version 1 at all, and even if <tt>extern(C++)</tt> has been added to D2, the support is still very limited, and a custom wrapper layer is still required in many cases. </p>
<p>To help addressing these issues, the SWIG C# module has been forked to support D. Is has evolved quite a lot since then, but there are still many similarities, so if you do not find what you are looking for on this page, it might be worth having a look at the chapter on <a href="CSharp.html">C#</a> (and also on <a href="Java.html">Java</a>, since the C# module was in turn forked from it).</p>
<p>To help addressing these issues, the SWIG C# module has been forked to support D. Is has evolved quite a lot since then, but there are still many similarities, so if you do not find what you are looking for on this page, it might be worth having a look at the chapter on <a href="CSharp.html#CSharp">C#</a> (and also on <a href="Java.html#Java">Java</a>, since the C# module was in turn forked from it).</p>
<H2><a name="D_command_line_invocation"></a>21.2 Command line invocation</H2>
<H2><a name="D_command_line_invocation">22.2 Command line invocation</a></H2>
<p>To activate the D module, pass the <tt>-d</tt> option to SWIG at the command line. The same standard command line switches as with any other language module are available, plus the following D specific ones:</p>
@ -64,7 +64,7 @@
<p>By default, SWIG generates code for D1/Tango. Use the <tt>-d2</tt> flag to target D2/Phobos instead.</p>
</dd>
<dt id="D_splitproxy"><tt>-splitproxy</tt></dt>
<dt><a name="D_splitproxy"></a><tt>-splitproxy</tt></dt>
<dd>
<p>By default, SWIG generates two D modules: the <em>proxy</em> module, named like the source module (either specified via the <tt>%module</tt> directive or via the <tt>module</tt> command line switch), which contains all the proxy classes, functions, enums, etc., and the <em>intermediary</em> module (named like the proxy module, but suffixed with <tt>_im</tt>), which contains all the <tt>extern(C)</tt> function declarations and other private parts only used internally by the proxy module.</p>
<p>If the split proxy mode is enabled by passing this switch at the command line, all proxy classes and enums are emitted to their own D module instead. The main proxy module only contains free functions and constants in this case.</p>
@ -83,10 +83,10 @@
</dl>
<H2><a name="D_typemaps"></a>21.3 Typemaps</H2>
<H2><a name="D_typemaps">22.3 Typemaps</a></H2>
<H3><a name="D_typemap_name_comparison"></a>21.3.1 C# &lt;-&gt; D name comparison</H3>
<H3><a name="D_typemap_name_comparison">22.3.1 C# &lt;-&gt; D name comparison</a></H3>
<p>If you already know the SWIG C# module, you might find the following name comparison table useful:</p>
@ -112,7 +112,7 @@
</pre></div>
<H3><a name="D_ctype_imtype_dtype"></a>21.3.2 ctype, imtype, dtype</H3>
<H3><a name="D_ctype_imtype_dtype">22.3.2 ctype, imtype, dtype</a></H3>
<p>Mapping of types between the C/C++ library, the C/C++ library wrapper exposing the C functions, the D wrapper module importing these functions and the D proxy code.</p>
@ -120,26 +120,26 @@
<p>The <tt>ctype</tt> typemap is used to determine the types to use in the C wrapper functions. The types from the <tt>imtype</tt> typemap are used in the extern(C) declarations of these functions in the intermediary D module. The <tt>dtype</tt> typemap contains the D types used in the D proxy module/class.</p>
<H3><a name="D_in_out_directorin_direcetorout"></a>21.3.3 in, out, directorin, directorout</H3>
<H3><a name="D_in_out_directorin_direcetorout">22.3.3 in, out, directorin, directorout</a></H3>
<p>Used for converting between the types for C/C++ and D when generating the code for the wrapper functions (on the C++ side).</p>
<p>The code from the <tt>in</tt> typemap is used to convert arguments to the C wrapper function to the type used in the wrapped code (<tt>ctype</tt>->original C++ type), the <tt>out</tt> typemap is utilized to convert values from the wrapped code to wrapper function return types (original C++ type-><tt>ctype</tt>).</p>
<p>The code from the <tt>in</tt> typemap is used to convert arguments to the C wrapper function to the type used in the wrapped code (<tt>ctype</tt>-&gt;original C++ type), the <tt>out</tt> typemap is utilized to convert values from the wrapped code to wrapper function return types (original C++ type-&gt;<tt>ctype</tt>).</p>
<p>The <tt>directorin</tt> typemap is used to convert parameters to the type used in the D director callback function, its return value is processed by <tt>directorout</tt> (see below).</p>
<H3><a name="D_din_dout_ddirectorin_ddirectorout"></a>21.3.4 din, dout, ddirectorin, ddirectorout</H3>
<H3><a name="D_din_dout_ddirectorin_ddirectorout">22.3.4 din, dout, ddirectorin, ddirectorout</a></H3>
<p>Typemaps for code generation in D proxy and type wrapper classes.</p>
<p id="D_din">The <tt>din</tt> typemap is used for converting function parameter types from the type used in the proxy module or class to the type used in the intermediary D module (the <a href="D.html#D_dinput"><tt>$dinput</tt></a> macro is replaced). To inject further parameter processing code before or after the call to the intermediary layer, the <tt>pre</tt>, <tt>post</tt> and <tt>terminator</tt> attributes can be used (please refer to the <a href="CSharp.html#CSharp_date_marshalling">C# date marshalling example</a> for more information on these).</p>
<p><a name="D_din"></a>The <tt>din</tt> typemap is used for converting function parameter types from the type used in the proxy module or class to the type used in the intermediary D module (the <a href="D.html#D_dinput">$dinput</a> macro is replaced). To inject further parameter processing code before or after the call to the intermediary layer, the <tt>pre</tt>, <tt>post</tt> and <tt>terminator</tt> attributes can be used (please refer to the <a href="CSharp.html#CSharp_date_marshalling">C# date marshalling example</a> for more information on these).</p>
<p id="D_dout">The <tt>dout</tt> typemap is used for converting function return values from the return type used in the intermediary D module to the type returned by the proxy function. The <tt>$excode</tt> special variable in <tt>dout</tt> typemaps is replaced by the <tt>excode</tt> typemap attribute code if the method can throw any exceptions from unmanaged code, otherwise by nothing (the <a href="D.html#D_imcall"><tt>$imcall</tt> and <tt>$owner</tt></a> macros are replaced).</p>
<p><a name="D_dout"></a>The <tt>dout</tt> typemap is used for converting function return values from the return type used in the intermediary D module to the type returned by the proxy function. The <tt>$excode</tt> special variable in <tt>dout</tt> typemaps is replaced by the <tt>excode</tt> typemap attribute code if the method can throw any exceptions from unmanaged code, otherwise by nothing (the <a href="D.html#D_imcall"><tt>$imcall</tt> and <tt>$owner</tt></a> macros are replaced).</p>
<p id="D_ddirectorinout">The code from the <tt>ddirectorin</tt> and <tt>ddirectorout</tt> typemaps is used for conversion in director callback functions. Arguments are converted to the type used in the proxy class method they are calling by using the code from <tt>ddirectorin</tt>, the proxy class method return value is converted to the type the C++ code expects via the <tt>ddirectorout</tt> typemap (the <a href="D.html#D_dpcall"><tt>$dcall</tt> and <tt>$winput</tt></a> macros are replaced).</p>
<p><a name="D_ddirectorinout"></a>The code from the <tt>ddirectorin</tt> and <tt>ddirectorout</tt> typemaps is used for conversion in director callback functions. Arguments are converted to the type used in the proxy class method they are calling by using the code from <tt>ddirectorin</tt>, the proxy class method return value is converted to the type the C++ code expects via the <tt>ddirectorout</tt> typemap (the <a href="D.html#D_dpcall"><tt>$dcall</tt> and <tt>$winput</tt></a> macros are replaced).</p>
<p>The full chain of type conversions when a director callback is invoked looks like this:</p>
@ -157,13 +157,13 @@
dtype DClass.method(dtype a)</pre></div>
<H3><a name="D_typecheck_typemaps"></a>21.3.5 typecheck typemaps</H3>
<H3><a name="D_typecheck_typemaps">22.3.5 typecheck typemaps</a></H3>
<p>Because, unlike many scripting languages supported by SWIG, D does not need any dynamic dispatch helper to access an overloaded function, the purpose of these is merely to issue a warning for overloaded C++ functions that cannot be overloaded in D (as more than one C++ type maps to a single D type).</p>
<H3><a name="D_code_injection_typemaps"></a>21.3.6 Code injection typemaps</H3>
<H3><a name="D_code_injection_typemaps">22.3.6 Code injection typemaps</a></H3>
<p>These typemaps are used for generating the skeleton of proxy classes for C++ types.</p>
@ -172,10 +172,10 @@
<p>Using <tt>dcode</tt> and <tt>dimports</tt>, you can specify additional D code which will be emitted into the class body respectively the imports section of the D module the class is written to.</p>
<p id="D_class_code_typemaps"><tt>dconstructor</tt>, <tt>ddestructor</tt>, <tt>ddispose</tt> and <tt>ddispose_derived</tt> are used to generate the class constructor, destructor and <tt>dispose()</tt> method, respectively. The auxiliary code for handling the pointer to the C++ object is stored in <tt>dbody</tt> and <tt>dbody_derived</tt>. You can override them for specific types.</p>
<p><a name="D_class_code_typemaps"></a><tt>dconstructor</tt>, <tt>ddestructor</tt>, <tt>ddispose</tt> and <tt>ddispose_derived</tt> are used to generate the class constructor, destructor and <tt>dispose()</tt> method, respectively. The auxiliary code for handling the pointer to the C++ object is stored in <tt>dbody</tt> and <tt>dbody_derived</tt>. You can override them for specific types.</p>
<H3><a name="D_special_variables"></a>21.3.7 Special variable macros</H3>
<H3><a name="D_special_variables">22.3.7 Special variable macros</a></H3>
<p>The standard SWIG special variables are available for use within typemaps as described in the <a href="Typemaps.html#Typemaps">Typemaps documentation</a>, for example <tt>$1</tt>, <tt>$input</tt>, <tt>$result</tt> etc.</p>
@ -197,7 +197,7 @@
<dt><tt>$null</tt></dt>
<dd><p>In code inserted into the generated C/C++ wrapper functions, this variable is replaced by either <tt>0</tt> or nothing at all, depending on whether the function has a return value or not. It can be used to bail out early e.g. in case of errors (<tt>return $null;</tt>).</p></dd>
<dt id="D_dinput"><tt>$dinput</tt> (C#: <tt>$csinput</tt>)</dt>
<dt><a name="D_dinput"></a><tt>$dinput</tt> (C#: <tt>$csinput</tt>)</dt>
<dd>
<p>This variable is used in <tt><a href="D.html#D_din">din</a></tt> typemaps and is replaced by the expression which is to be passed to C/C++.</p>
<p>For example, this input</p>
@ -214,7 +214,7 @@ void foo(SomeClass arg) {
example_im.foo(SomeClass.getCPointer(arg));
}</pre></div></dd>
<dt id="D_imcall"><tt>$imcall</tt> and <tt>$owner</tt> (C#: <tt>$imcall</tt>)</dt>
<dt><a name="D_imcall"></a><tt>$imcall</tt> and <tt>$owner</tt> (C#: <tt>$imcall</tt>)</dt>
<dd>
<p>These variables are used in <tt><a href="D.html#D_dout">dout</a></tt> typemaps. <tt>$imcall</tt> contains the call to the intermediary module which provides the value to be used, and <tt>$owner</tt> signals if the caller is responsible for managing the object lifetime (that is, if the called method is a constructor or has been marked via <tt>%newobject</tt>).</p>
<p>Consider the following example:</p>
@ -243,7 +243,7 @@ SomeClass bar() {
</dd>
<dt><tt>$dcall</tt> and <tt>$winput</tt> (C#: <tt>$cscall</tt>, <tt>$iminput</tt>)</dt>
<dd id="D_dpcall"><p>These variables are used in the director-specific typemaps <a href="D.html#D_ddirectorinout"><tt>ddirectorin</tt></a> and <a href="D.html#D_ddirectorinout"><tt>ddirectorout</tt></a>. They are more or less the reverse of the <tt>$imcall</tt> and <tt>$dinput</tt> macros: <tt>$dcall</tt> contains the invocation of the D proxy method of which the return value is to be passed back to C++, <tt>$winput</tt> contains the parameter value from C++.</p></dd>
<dd><a name="D_dpcall"></a><p>These variables are used in the director-specific typemaps <a href="D.html#D_ddirectorinout"><tt>ddirectorin</tt></a> and <a href="D.html#D_ddirectorinout"><tt>ddirectorout</tt></a>. They are more or less the reverse of the <tt>$imcall</tt> and <tt>$dinput</tt> macros: <tt>$dcall</tt> contains the invocation of the D proxy method of which the return value is to be passed back to C++, <tt>$winput</tt> contains the parameter value from C++.</p></dd>
<dt><tt>$excode</tt></dt>
<dd><p>This variable is used in <tt>dout</tt> and <tt>dconstructor</tt> typemaps and is filled with the contents of the <tt>excode</tt> typemap attribute if an exception could be thrown from the C++ side. See the <a href="CSharp.html#CSharp_exceptions">C# documentation</a> for details.</p></dd>
@ -263,7 +263,7 @@ SomeClass bar() {
</pre></div>
</dd>
<dt id="D_importtype"><tt>$importtype(SomeDType)</tt></dt>
<dt><a name="D_importtype"></a><tt>$importtype(SomeDType)</tt></dt>
<dd>
<p>This macro is used in the <tt>dimports</tt> typemap if a dependency on another D type generated by SWIG is added by a custom typemap.</p>
<p>Consider the following code snippet:</p>
@ -295,7 +295,7 @@ $importtype(AnotherInterface)
</dl>
<H2><a name="D_features"></a>21.4 <tt>%feature</tt>s</H2>
<H2><a name="D_features">22.4 D and %feature</a></H2>
<p>The D module defines a number of directives which modify the <a href="Customization.html#Customization_features">SWIG features</a> set globally or for a specific declaration:</p>
@ -325,7 +325,7 @@ struct A {
</dl>
<H2><a name="D_pragmas"></a>21.5 Pragmas</H2>
<H2><a name="D_pragmas">22.5 Pragmas</a></H2>
<p>There are a few SWIG pragmas specific to the D module, which you can use to influence the D code SWIG generates:</p>
@ -364,7 +364,7 @@ struct A {
</dl>
<H2><a name="D_exceptions"></a>21.6 D Exceptions</H2>
<H2><a name="D_exceptions">22.6 D Exceptions</a></H2>
<p>Out of the box, C++ exceptions are fundamentally incompatible to their equivalent in the D world and cannot simply be propagated to a calling D method. There is, however, an easy way to solve this problem: Just catch the exception in the C/C++ wrapper layer, pass the contents to D, and make the wrapper code rethrow the exception in the D world.</p>
@ -374,7 +374,7 @@ struct A {
<p>As this feature is implemented in exactly the same way it is for C#, please see the <a href="CSharp.html#CSharp_exceptions">C# documentation</a> for a more detailed explanation.</p>
<H2><a name="D_directors"></a>21.7 D Directors</H2>
<H2><a name="D_directors">22.7 D Directors</a></H2>
<p>When the directors feature is activated, SWIG generates extra code on both the C++ and the D side to enable cross-language polymorphism. Essentially, this means that if you subclass a proxy class in D, C++ code can access any overridden virtual methods just as if you created a derived class in C++.</p>
@ -383,16 +383,16 @@ struct A {
</p>
<H2><a name="D_other_features"></a>21.8 Other features</H2>
<H2><a name="D_other_features">22.8 Other features</a></H2>
<H3><a name="D_nspace"></a>21.8.1 Extended namespace support (<tt>nspace</tt>)</H3>
<H3><a name="D_nspace">22.8.1 Extended namespace support (nspace)</a></H3>
<p>By default, SWIG flattens all C++ namespaces into a single target language namespace, but as for Java and C#, the <a href="SWIGPlus.html#SWIGPlus_nspace"><tt>nspace</tt></a> feature is supported for D. If it is active, C++ namespaces are mapped to D packages/modules. Note, however, that like for the other languages, <em>free</em> variables and functions are not supported yet; currently, they are all allows written to the main proxy D module.</p>
<H3><a name="D_native_pointer_support"></a>21.8.2 Native pointer support</H3>
<H3><a name="D_native_pointer_support">22.8.2 Native pointer support</a></H3>
<p>Contrary to many of the scripting languages supported by SWIG, D fully supports C-style pointers. The D module thus includes a custom mechanism to wrap C pointers directly as D pointers where applicable, that is, if the type that is pointed to is represented the same in C and D (on the bit-level), dubbed a <em>primitive type</em> below.</p>
@ -404,7 +404,7 @@ struct A {
<p>To determine if a type should be considered primitive, the <tt>cprimitive</tt> attribute on its <tt>dtype</tt> attribute is used. For example, the <tt>dtype</tt> typemap for <tt>float</tt> has <tt>cprimitive="1"</tt>, so the code from the <tt>nativepointer</tt> attribute is taken into account e.g. for <tt>float **</tt> or the function pointer <tt>float (*)(float *)</tt>.</p>
<H3><a name="D_operator_overloading"></a>21.8.3 Operator overloading</H3>
<H3><a name="D_operator_overloading">22.8.3 Operator overloading</a></H3>
<p>The D module comes with basic operator overloading support for both D1 and D2. There are, however, a few limitations arising from conceptual differences between C++ and D:</p>
@ -416,7 +416,7 @@ struct A {
<p>There are also some cases where the operators can be translated to D, but the differences in the implementation details are big enough that a rather involved scheme would be required for automatic wrapping them, which has not been implemented yet. This affects, for example, the array subscript operator, <tt>[]</tt>, in combination with assignments - while <tt>operator []</tt> in C++ simply returns a reference which is then written to, D resorts to a separate <tt>opIndexAssign</tt> method -, or implicit casting (which was introduced in D2 via <tt>alias this</tt>). Despite the lack of automatic support, manually handling these cases should be perfectly possible.</p>
<H3><a name="D_test_suite"></a>21.8.4 Running the test-suite</H3>
<H3><a name="D_test_suite">22.8.4 Running the test-suite</a></H3>
<p>As with any other language, the SWIG test-suite can be built for D using the <tt>*-d-test-suite</tt> targets of the top-level Makefile. By default, D1 is targeted, to build it with D2, use the optional <tt>D_VERSION</tt> variable, e.g. <tt>make check-d-test-suite D_VERSION=2</tt>.</p>
@ -424,14 +424,14 @@ struct A {
<p>Note: If you want to use GDC on Linux or another platform which requires you to link <tt>libdl</tt> for dynamically loading the shared library, you might have to add <tt>-ldl</tt> manually to the <tt>d_compile</tt> target in <tt>Examples/Makefile</tt>, because GDC does not currently honor the <tt>pragma(lib,...)</tt> statement.</p>
<H2><a name="D_typemap_examples"></a>21.9 D Typemap examples</H2>
<H2><a name="D_typemap_examples">22.9 D Typemap examples</a></H2>
<p>There are no D-specific typemap examples yet. However, with the above <a href="D.html#D_typemap_name_comparison">name comparison table</a>, you should be able to get an idea what can be done by looking at the <a href="CSharp.html#CSharp_typemap_examples">corresponding C# section</a>.</p>
<H2><a name="D_planned_features"></a>21.10 Work in progress and planned features</H2>
<H2><a name="D_planned_features">22.10 Work in progress and planned features</a></H2>
<p>There are a couple of features which are not implemented yet, but would be very useful and might be added in the near future:</p>

143
Doc/Manual/Extending.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Extending SWIG to support new languages</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Extending"></a>38 Extending SWIG to support new languages</H1>
<H1><a name="Extending">41 Extending SWIG to support new languages</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -75,7 +76,7 @@
<H2><a name="Extending_nn2"></a>38.1 Introduction</H2>
<H2><a name="Extending_nn2">41.1 Introduction</a></H2>
<p>
@ -91,7 +92,7 @@ Also, this chapter is not meant to be a hand-holding tutorial. As a starting po
you should probably look at one of SWIG's existing modules.
</p>
<H2><a name="Extending_nn3"></a>38.2 Prerequisites</H2>
<H2><a name="Extending_nn3">41.2 Prerequisites</a></H2>
<p>
@ -121,7 +122,7 @@ obvious, but almost all SWIG directives as well as the low-level generation of
wrapper code are driven by C++ datatypes.
</p>
<H2><a name="Extending_nn4"></a>38.3 The Big Picture</H2>
<H2><a name="Extending_nn4">41.3 The Big Picture</a></H2>
<p>
@ -158,7 +159,7 @@ role in making the system work. For example, both typemaps and declaration anno
based on pattern matching and interact heavily with the underlying type system.
</p>
<H2><a name="Extending_nn5"></a>38.4 Execution Model</H2>
<H2><a name="Extending_nn5">41.4 Execution Model</a></H2>
<p>
@ -203,7 +204,7 @@ latter stage of compilation.
The next few sections briefly describe some of these stages.
</p>
<H3><a name="Extending_nn6"></a>38.4.1 Preprocessing</H3>
<H3><a name="Extending_nn6">41.4.1 Preprocessing</a></H3>
<p>
@ -284,7 +285,7 @@ been expanded as well as everything else that goes into the low-level
construction of the wrapper code.
</p>
<H3><a name="Extending_nn7"></a>38.4.2 Parsing</H3>
<H3><a name="Extending_nn7">41.4.2 Parsing</a></H3>
<p>
@ -385,7 +386,7 @@ returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
arguments).
</p>
<H3><a name="Extending_nn8"></a>38.4.3 Parse Trees</H3>
<H3><a name="Extending_nn8">41.4.3 Parse Trees</a></H3>
<p>
@ -640,7 +641,7 @@ $ swig -c++ -python -debug-module 4 example.i
</pre>
</div>
<H3><a name="Extending_nn9"></a>38.4.4 Attribute namespaces</H3>
<H3><a name="Extending_nn9">41.4.4 Attribute namespaces</a></H3>
<p>
@ -659,7 +660,7 @@ that matches the name of the target language. For example, <tt>python:foo</tt>
<tt>perl:foo</tt>.
</p>
<H3><a name="Extending_nn10"></a>38.4.5 Symbol Tables</H3>
<H3><a name="Extending_nn10">41.4.5 Symbol Tables</a></H3>
<p>
@ -750,7 +751,7 @@ example.i:5. Previous declaration is foo_i(int )
</pre>
</div>
<H3><a name="Extending_nn11"></a>38.4.6 The %feature directive</H3>
<H3><a name="Extending_nn11">41.4.6 The %feature directive</a></H3>
<p>
@ -806,7 +807,7 @@ For example, the exception code above is simply
stored without any modifications.
</p>
<H3><a name="Extending_nn12"></a>38.4.7 Code Generation</H3>
<H3><a name="Extending_nn12">41.4.7 Code Generation</a></H3>
<p>
@ -928,7 +929,7 @@ public :
The role of these functions is described shortly.
</p>
<H3><a name="Extending_nn13"></a>38.4.8 SWIG and XML</H3>
<H3><a name="Extending_nn13">41.4.8 SWIG and XML</a></H3>
<p>
@ -941,7 +942,7 @@ internal data structures, it may be useful to keep XML in the back of
your mind as a model.
</p>
<H2><a name="Extending_nn14"></a>38.5 Primitive Data Structures</H2>
<H2><a name="Extending_nn14">41.5 Primitive Data Structures</a></H2>
<p>
@ -987,7 +988,7 @@ typedef Hash Typetab;
</pre>
</div>
<H3><a name="Extending_nn15"></a>38.5.1 Strings</H3>
<H3><a name="Extending_nn15">41.5.1 Strings</a></H3>
<p>
@ -1128,7 +1129,7 @@ Returns the number of replacements made (if any).
</div>
<H3><a name="Extending_nn16"></a>38.5.2 Hashes</H3>
<H3><a name="Extending_nn16">41.5.2 Hashes</a></H3>
<p>
@ -1205,7 +1206,7 @@ Returns the list of hash table keys.
</div>
<H3><a name="Extending_nn17"></a>38.5.3 Lists</H3>
<H3><a name="Extending_nn17">41.5.3 Lists</a></H3>
<p>
@ -1294,7 +1295,7 @@ If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt>
and is used to create a String object.
</div>
<H3><a name="Extending_nn18"></a>38.5.4 Common operations</H3>
<H3><a name="Extending_nn18">41.5.4 Common operations</a></H3>
The following operations are applicable to all datatypes.
@ -1349,7 +1350,7 @@ objects and report errors.
Gets the line number associated with <tt>x</tt>.
</div>
<H3><a name="Extending_nn19"></a>38.5.5 Iterating over Lists and Hashes</H3>
<H3><a name="Extending_nn19">41.5.5 Iterating over Lists and Hashes</a></H3>
To iterate over the elements of a list or a hash table, the following functions are used:
@ -1394,7 +1395,7 @@ for (j = First(j); j.item; j= Next(j)) {
</div>
<H3><a name="Extending_nn20"></a>38.5.6 I/O</H3>
<H3><a name="Extending_nn20">41.5.6 I/O</a></H3>
Special I/O functions are used for all internal I/O. These operations
@ -1500,12 +1501,11 @@ Create a File object wrapper around an existing <tt>FILE *</tt> object.
</div>
<p>
<b><tt>int Close(String_or_FILE *f)</tt></b>
There's no explicit function to close a file, just call <tt>Delete(f)</tt> -
this decreases the reference count, and the file will be closed when the
reference count reaches zero.
</p>
<div class="indent">
<p>Closes a file. Has no effect on strings.</p>
<p>
The use of the above I/O functions and strings play a critical role in SWIG. It is
common to see small code fragments of code generated using code like this:
@ -1529,9 +1529,7 @@ Printf(f, "%s\n", s);
Similarly, the preprocessor and parser all operate on string-files.
</p>
</div>
<H2><a name="Extending_nn21"></a>38.6 Navigating and manipulating parse trees</H2>
<H2><a name="Extending_nn21">41.6 Navigating and manipulating parse trees</a></H2>
Parse trees are built as collections of hash tables. Each node is a hash table in which
@ -1665,7 +1663,7 @@ Deletes a node from the parse tree. Deletion reconnects siblings and properly u
the parent so that sibling nodes are unaffected.
</div>
<H2><a name="Extending_nn22"></a>38.7 Working with attributes</H2>
<H2><a name="Extending_nn22">41.7 Working with attributes</a></H2>
<p>
@ -1782,7 +1780,7 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after
function.
</div>
<H2><a name="Extending_nn23"></a>38.8 Type system</H2>
<H2><a name="Extending_nn23">41.8 Type system</a></H2>
<p>
@ -1791,7 +1789,7 @@ pointers, references, and pointers to members. A detailed discussion of
type theory is impossible here. However, let's cover the highlights.
</p>
<H3><a name="Extending_nn24"></a>38.8.1 String encoding of types</H3>
<H3><a name="Extending_nn24">41.8.1 String encoding of types</a></H3>
<p>
@ -1892,7 +1890,7 @@ make the final type, the two parts are just joined together using
string concatenation.
</p>
<H3><a name="Extending_nn25"></a>38.8.2 Type construction</H3>
<H3><a name="Extending_nn25">41.8.2 Type construction</a></H3>
<p>
@ -2061,7 +2059,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is
<tt>ty</tt> is unmodified.
</div>
<H3><a name="Extending_nn26"></a>38.8.3 Type tests</H3>
<H3><a name="Extending_nn26">41.8.3 Type tests</a></H3>
<p>
@ -2148,7 +2146,7 @@ Checks if <tt>ty</tt> is a varargs type.
Checks if <tt>ty</tt> is a templatized type.
</div>
<H3><a name="Extending_nn27"></a>38.8.4 Typedef and inheritance</H3>
<H3><a name="Extending_nn27">41.8.4 Typedef and inheritance</a></H3>
<p>
@ -2250,7 +2248,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype
will consist only of primitive typenames.
</div>
<H3><a name="Extending_nn28"></a>38.8.5 Lvalues</H3>
<H3><a name="Extending_nn28">41.8.5 Lvalues</a></H3>
<p>
@ -2287,7 +2285,7 @@ Literal y; // type = 'Literal', ltype='p.char'
</pre>
</div>
<H3><a name="Extending_nn29"></a>38.8.6 Output functions</H3>
<H3><a name="Extending_nn29">41.8.6 Output functions</a></H3>
<p>
@ -2349,7 +2347,7 @@ SWIG, but is most commonly associated with type-descriptor objects
that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>).
</div>
<H2><a name="Extending_nn30"></a>38.9 Parameters</H2>
<H2><a name="Extending_nn30">41.9 Parameters</a></H2>
<p>
@ -2448,7 +2446,7 @@ included. Used to emit prototypes.
Returns the number of required (non-optional) arguments in <tt>p</tt>.
</div>
<H2><a name="Extending_nn31"></a>38.10 Writing a Language Module</H2>
<H2><a name="Extending_nn31">41.10 Writing a Language Module</a></H2>
<p>
@ -2463,7 +2461,7 @@ describes the creation of a minimal Python module. You should be able to extra
this to other languages.
</p>
<H3><a name="Extending_nn32"></a>38.10.1 Execution model</H3>
<H3><a name="Extending_nn32">41.10.1 Execution model</a></H3>
<p>
@ -2473,7 +2471,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_starting_out"></a>38.10.2 Starting out</H3>
<H3><a name="Extending_starting_out">41.10.2 Starting out</a></H3>
<p>
@ -2581,7 +2579,7 @@ that activates your module. For example, <tt>swig -python foo.i</tt>. The
messages from your new module should appear.
</p>
<H3><a name="Extending_nn34"></a>38.10.3 Command line options</H3>
<H3><a name="Extending_nn34">41.10.3 Command line options</a></H3>
<p>
@ -2640,7 +2638,7 @@ to mark the option as valid. If you forget to do this, SWIG will terminate wit
unrecognized command line option error.
</p>
<H3><a name="Extending_nn35"></a>38.10.4 Configuration and preprocessing</H3>
<H3><a name="Extending_nn35">41.10.4 Configuration and preprocessing</a></H3>
<p>
@ -2689,7 +2687,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file
<tt>python.swg</tt>.
</p>
<H3><a name="Extending_nn36"></a>38.10.5 Entry point to code generation</H3>
<H3><a name="Extending_nn36">41.10.5 Entry point to code generation</a></H3>
<p>
@ -2747,7 +2745,7 @@ int Python::top(Node *n) {
</pre>
</div>
<H3><a name="Extending_nn37"></a>38.10.6 Module I/O and wrapper skeleton</H3>
<H3><a name="Extending_nn37">41.10.6 Module I/O and wrapper skeleton</a></H3>
<!-- please report bugs in this section to mgossage -->
@ -2761,8 +2759,8 @@ Within SWIG wrappers, there are five main sections. These are (in order)
<li>begin: This section is a placeholder for users to put code at the beginning of the C/C++ wrapper file.
<li>runtime: This section has most of the common SWIG runtime code.
<li>header: This section holds declarations and inclusions from the .i file.
<li>wrapper: This section holds all the wrappering code.
<li>init: This section holds the module initalisation function
<li>wrapper: This section holds all the wrapper code.
<li>init: This section holds the module initialisation function
(the entry point for the interpreter).
</ul>
<p>
@ -2832,7 +2830,6 @@ int Python::top(Node *n) {
Delete(f_header);
Delete(f_wrappers);
Delete(f_init);
Close(f_begin);
Delete(f_begin);
return SWIG_OK;
@ -2896,7 +2893,7 @@ functionWrapper : void Shape_y_set(Shape *self,double y)
</pre>
</div>
<H3><a name="Extending_nn38"></a>38.10.7 Low-level code generators</H3>
<H3><a name="Extending_nn38">41.10.7 Low-level code generators</a></H3>
<!-- please report bugs in this section to mgossage -->
@ -2975,7 +2972,7 @@ There are a lot of issues to address.
<div class="code">
<pre>
virtual int functionWrapper(Node *n) {
/* get useful atributes */
/* get useful attributes */
String *name = Getattr(n,"sym:name");
SwigType *type = Getattr(n,"type");
ParmList *parms = Getattr(n,"parms");
@ -3005,7 +3002,7 @@ virtual int functionWrapper(Node *n) {
/* write typemaps(in) */
....
/* write constriants */
/* write constraints */
....
/* Emit the function call */
@ -3050,7 +3047,7 @@ but without the typemaps, there is still work to do.
</p>
<H3><a name="Extending_configuration_files"></a>38.10.8 Configuration files</H3>
<H3><a name="Extending_configuration_files">41.10.8 Configuration files</a></H3>
<!-- please report bugs in this section to ttn -->
@ -3101,7 +3098,7 @@ As you can see, most usages are direct.
<dl>
<dt> <b>configure.in</b>
<dt> <b>configure.ac</b>
<dd> This file is processed by
<p>
@ -3194,7 +3191,7 @@ politely displays the ignoring language message.
</dl>
<H3><a name="Extending_nn40"></a>38.10.9 Runtime support</H3>
<H3><a name="Extending_nn40">41.10.9 Runtime support</a></H3>
<p>
@ -3203,7 +3200,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g.
the SWIG files that implement those functions.
</p>
<H3><a name="Extending_nn41"></a>38.10.10 Standard library files</H3>
<H3><a name="Extending_nn41">41.10.10 Standard library files</a></H3>
<p>
@ -3222,7 +3219,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>38.10.11 User examples</H3>
<H3><a name="Extending_nn42">41.10.11 User examples</a></H3>
<p>
@ -3251,7 +3248,7 @@ during this process, see the section on <a href="#Extending_configuration_files"
files</a>.
</p>
<H3><a name="Extending_test_suite"></a>38.10.12 Test driven development and the test-suite</H3>
<H3><a name="Extending_test_suite">41.10.12 Test driven development and the test-suite</a></H3>
<p>
@ -3310,7 +3307,7 @@ It is therefore essential that the runtime tests are written in a manner that di
but error/exception out with an error message on stderr on failure.
</p>
<H4><a name="Extending_running_test_suite"></a>38.10.12.1 Running the test-suite</H4>
<H4><a name="Extending_running_test_suite">41.10.12.1 Running the test-suite</a></H4>
<p>
@ -3350,10 +3347,10 @@ Note that if a runtime test is available, a message "(with run test)" is display
<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
checking python testcase argcargvtest (with run test)
checking python testcase python_autodoc
checking python testcase python_append (with run test)
checking python testcase callback (with run test)
</pre></div>
<p>
@ -3496,7 +3493,13 @@ The syntax for setting environment variables varies from one shell to the next,
make ret_by_value.ctest SWIG_FEATURES="-debug-tmsearch"
</pre></div>
<H3><a name="Extending_nn43"></a>38.10.13 Documentation</H3>
<p>
There is also a special 'errors' test-suite which is a set of regression tests checking SWIG warning and error messages.
It can be run in the same way as the other language test-suites, replacing [lang] with errors, such as <tt>make check-errors-test-suite</tt>.
The test cases used and the way it works is described in <tt>Examples/test-suite/errors/Makefile.in</tt>.
</p>
<H3><a name="Extending_nn43">41.10.13 Documentation</a></H3>
<p>
@ -3528,7 +3531,7 @@ Some topics that you'll want to be sure to address include:
if available.
</ul>
<H3><a name="Extending_prerequisites"></a>38.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3>
<H3><a name="Extending_prerequisites">41.10.14 Prerequisites for adding a new language module to the SWIG distribution</a></H3>
<p>
@ -3536,7 +3539,7 @@ If you wish for a new language module to be distributed with SWIG,
which we encourage for all popular languages, there are a few requirements.
While we appreciate that getting all aspects of a new language working
won't happen at the outset, there are a set of minimum requirements before
a module can be committed into the SVN repository for distribution with future
a module can be committed into the official Github repository for distribution with future
versions of SWIG. The following are really a summary of this whole section with
details being outlined earlier on.
</p>
@ -3551,7 +3554,7 @@ details being outlined earlier on.
a runtime test, see for example <tt>Examples/python/class</tt>.
</li>
<li>
Modify <tt>configure.in</tt>, <tt>Makefile.in</tt> and <tt>Examples/Makefile.in</tt> to run
Modify <tt>configure.ac</tt>, <tt>Makefile.in</tt> and <tt>Examples/Makefile.in</tt> to run
these examples. Please make sure that if the new language is not
installed properly on a box, <tt>make -k check</tt> should still work by
skipping the tests and examples for the new language module.
@ -3578,14 +3581,14 @@ details being outlined earlier on.
</ol>
<p>
Once accepted into SVN, development efforts should concentrate on
Once accepted into the official Git repository, development efforts should concentrate on
getting the entire test-suite to work with plenty of runtime tests.
Runtime tests should be for existing testcases and new test cases
should be added should there be an area not already covered by
the existing tests.
</p>
<H3><a name="Extending_coding_style_guidelines"></a>38.10.15 Coding style guidelines</H3>
<H3><a name="Extending_coding_style_guidelines">41.10.15 Coding style guidelines</a></H3>
<p>
@ -3609,7 +3612,7 @@ 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_debugging_options"></a>38.11 Debugging Options</H2>
<H2><a name="Extending_debugging_options">41.11 Debugging Options</a></H2>
<p>
@ -3636,7 +3639,7 @@ There are various command line options which can aid debugging a SWIG interface
The complete list of command line options for SWIG are available by running <tt>swig -help</tt>.
</p>
<H2><a name="Extending_nn46"></a>38.12 Guide to parse tree nodes</H2>
<H2><a name="Extending_nn46">41.12 Guide to parse tree nodes</a></H2>
<p>
@ -4044,7 +4047,7 @@ extern "X" { ... } declaration.
</pre>
</div>
<H2><a name="Extending_further_info"></a>38.13 Further Development Information</H2>
<H2><a name="Extending_further_info">41.13 Further Development Information</a></H2>
<p>

1139
Doc/Manual/Go.html
View file

File diff suppressed because it is too large Load diff

214
Doc/Manual/Guile.html
View file

@ -1,19 +1,20 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Hand-written HTML -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Guile</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Guile"></a>23 SWIG and Guile</H1>
<H1><a name="Guile">24 SWIG and Guile</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Guile_nn1">Supported Guile Versions</a>
<li><a href="#Guile_nn2">Meaning of "Module"</a>
<li><a href="#Guile_nn3">Using the SCM or GH Guile API</a>
<li><a href="#Guile_nn3">Old GH Guile API</a>
<li><a href="#Guile_nn4">Linkage</a>
<ul>
<li><a href="#Guile_nn5">Simple Linkage</a>
@ -26,8 +27,7 @@
<li><a href="#Guile_nn11">Typemaps</a>
<li><a href="#Guile_nn12">Representation of pointers as smobs</a>
<ul>
<li><a href="#Guile_nn13">GH Smobs</a>
<li><a href="#Guile_nn14">SCM Smobs</a>
<li><a href="#Guile_nn14">Smobs</a>
<li><a href="#Guile_nn15">Garbage Collection</a>
</ul>
<li><a href="#Guile_nn16">Exception Handling</a>
@ -47,7 +47,21 @@
<p>
This section details guile-specific support in SWIG.
<H2><a name="Guile_nn2"></a>23.1 Meaning of "Module"</H2>
<H2><a name="Guile_nn1">24.1 Supported Guile Versions</a></H2>
<p>
SWIG works with Guile versions 1.8.x and 2.0.x. Support for version
1.6.x has been dropped. The last version of SWIG that still works with
Guile version 1.6.x is SWIG 2.0.9.
<p>
Note that starting with guile 2.0, the guile sources can be compiled for
improved performance. This is currently not tested with swig
so your mileage may vary. To be safe set environment variable
GUILE_AUTO_COMPILE to 0 when using swig generated guile code.
<H2><a name="Guile_nn2">24.2 Meaning of "Module"</a></H2>
<p>
@ -55,55 +69,18 @@ There are three different concepts of "module" involved, defined
separately for SWIG, Guile, and Libtool. To avoid horrible confusion,
we explicitly prefix the context, e.g., "guile-module".
<H2><a name="Guile_nn3"></a>23.2 Using the SCM or GH Guile API</H2>
<H2><a name="Guile_nn3">24.3 Old GH Guile API</a></H2>
<p>The guile module can currently export wrapper files that use the guile GH interface or the
SCM interface. This is controlled by an argument passed to swig. The "-gh" argument causes swig
to output GH code, and the "-scm" argument causes swig to output SCM code. Right now the "-scm" argument
is the default. The "-scm" wrapper generation assumes a guile version &gt;= 1.6 and has several advantages over
the "-gh" wrapper generation including garbage collection and GOOPS support.
The "-gh" wrapper generation can be used for older versions of guile.
The guile GH wrapper code generation is depreciated and the
SCM interface is the default. The SCM and GH interface differ greatly in how they store
pointers and have completely different run-time code. See below for more info.
<p>The GH interface to guile is deprecated. Read more about why in the
<p>Guile 1.8 and older could be interfaced using two different api's, the SCM
or the GH API. The GH interface to guile is deprecated. Read more about why in the
<a href="http://www.gnu.org/software/guile/docs/docs-1.6/guile-ref/GH.html#GH">Guile manual</a>.
The idea of the GH interface was to provide a high level API that other languages and projects
could adopt. This was a good idea, but didn't pan out well for general development. But for the
specific, minimal uses that the SWIG typemaps put the GH interface to use is ideal for
using a high level API. So even though the GH interface is depreciated, SWIG will continue to use
the GH interface and provide mappings from the GH interface to whatever API we need.
We can maintain this mapping where guile failed because SWIG uses a small subset of all the GH functions
which map easily. All the guile typemaps like typemaps.i and std_vector.i
will continue to use the GH functions to do things like create lists of values, convert strings to
integers, etc. Then every language module will define a mapping between the GH interface and
whatever custom API the language uses. This is currently implemented by the guile module to use
the SCM guile API rather than the GH guile API.
For example, here are some of the current mapping file for the SCM API</p>
<div class="code"><pre>
<p>Support for the guile GH wrapper code generation has been dropped from SWIG. The last
version of SWIG that can still generate guile GH wrapper code is 2.0.9. Please
use that version if you really need the GH wrapper code.
#define gh_append2(a, b) scm_append(scm_listify(a, b, SCM_UNDEFINED))
#define gh_apply(a, b) scm_apply(a, b, SCM_EOL)
#define gh_bool2scm SCM_BOOL
#define gh_boolean_p SCM_BOOLP
#define gh_car SCM_CAR
#define gh_cdr SCM_CDR
#define gh_cons scm_cons
#define gh_double2scm scm_make_real
...
</pre></div>
<p>This file is parsed by SWIG at wrapper generation time, so every reference to a gh_ function is replaced
by a scm_ function in the wrapper file. Thus the gh_ function calls will never be seen in the wrapper;
the wrapper will look exactly like it was generated
for the specific API. Currently only the guile language module has created a mapping policy from gh_ to scm_,
but there is no reason other languages (like mzscheme or chicken) couldn't also use this.
If that happens, there is A LOT less code duplication in the standard typemaps.</p>
<H2><a name="Guile_nn4"></a>23.3 Linkage</H2>
<H2><a name="Guile_nn4">24.4 Linkage</a></H2>
<p>
@ -111,7 +88,7 @@ Guile support is complicated by a lack of user community cohesiveness,
which manifests in multiple shared-library usage conventions. A set of
policies implementing a usage convention is called a <b>linkage</b>.
<H3><a name="Guile_nn5"></a>23.3.1 Simple Linkage</H3>
<H3><a name="Guile_nn5">24.4.1 Simple Linkage</a></H3>
<p>
@ -134,7 +111,7 @@ libraries into Guile.</p>
<div class="targetlang">
<pre>
(define-module (my module))
(define my-so (dynamic-link "./example.so"))
(define my-so (dynamic-link "./libexample.so"))
(dynamic-call "SWIG_init" my-so) ; make SWIG bindings
;; Scheme definitions can go here
</pre>
@ -147,7 +124,17 @@ and <code>dynamic-call</code>:
<div class="targetlang">
<pre>
(load-extension "./example.so" "SWIG_init")
(load-extension "./libexample.so" "SWIG_init")
</pre>
</div>
<p>
A more portable approach would be to drop the shared library extension:
</p>
<div class="targetlang">
<pre>
(load-extension "./libexample" "SWIG_init")
</pre>
</div>
@ -171,8 +158,8 @@ following module-system hack:
<div class="targetlang">
<pre>
(module-map (lambda (sym var)
(module-export! (current-module) (list sym)))
(current-module))
(module-export! (current-module) (list sym)))
(current-module))
</pre>
</div>
@ -190,7 +177,7 @@ information by including a directive like this in the interface file:
<div class="code">
<pre>
%scheme %{ (load-extension "./example.so" "SWIG_init") %}
%scheme %{ (load-extension "./libexample.so" "SWIG_init") %}
</pre>
</div>
@ -206,7 +193,7 @@ placed between the <code>define-module</code> form and the
<code>SWIG_init</code> via a preprocessor define to avoid symbol
clashes. For this case, however, passive linkage is available.
<H3><a name="Guile_nn6"></a>23.3.2 Passive Linkage</H3>
<H3><a name="Guile_nn6">24.4.2 Passive Linkage</a></H3>
<p>Passive linkage is just like simple linkage, but it generates an
@ -216,12 +203,12 @@ package name (see below).
<p>You should use passive linkage rather than simple linkage when you
are using multiple modules.
<H3><a name="Guile_nn7"></a>23.3.3 Native Guile Module Linkage</H3>
<H3><a name="Guile_nn7">24.4.3 Native Guile Module Linkage</a></H3>
<p>SWIG can also generate wrapper code that does all the Guile module
declarations on its own if you pass it the <code>-Linkage
module</code> command-line option. This requires Guile 1.5.0 or later.
module</code> command-line option.
<p>The module name is set with the <code>-package</code> and
<code>-module</code> command-line options. Suppose you want to define
@ -244,7 +231,7 @@ shared libraries into Guile; all bindings are automatically put in
newly created Guile modules.
<div class="targetlang">
<pre>
(define my-so (dynamic-link "./foo.so"))
(define my-so (dynamic-link "./libfoo"))
;; create new module and put bindings there:
(dynamic-call "scm_init_my_modules_foo_module" my-so)
</pre>
@ -252,12 +239,12 @@ newly created Guile modules.
Newer Guile versions have a shorthand procedure for this:
<div class="targetlang">
<pre>
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
(load-extension "./libfoo.so" "scm_init_my_modules_foo_module")
</pre>
</div>
</ul>
<H3><a name="Guile_nn8"></a>23.3.4 Old Auto-Loading Guile Module Linkage</H3>
<H3><a name="Guile_nn8">24.4.4 Old Auto-Loading Guile Module Linkage</a></H3>
<p>Guile used to support an autoloading facility for object-code
@ -283,7 +270,7 @@ option, SWIG generates an exported module initialization function with
an appropriate name.
<H3><a name="Guile_nn9"></a>23.3.5 Hobbit4D Linkage</H3>
<H3><a name="Guile_nn9">24.4.5 Hobbit4D Linkage</a></H3>
<p>
@ -308,7 +295,7 @@ my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very
experimental; the (hobbit4d link) conventions are not well understood.
</p>
<H2><a name="Guile_nn10"></a>23.4 Underscore Folding</H2>
<H2><a name="Guile_nn10">24.5 Underscore Folding</a></H2>
<p>
@ -320,7 +307,7 @@ complained so far.
<code>%rename</code> to specify the Guile name of the wrapped
functions and variables (see CHANGES).
<H2><a name="Guile_nn11"></a>23.5 Typemaps</H2>
<H2><a name="Guile_nn11">24.6 Typemaps</a></H2>
<p>
@ -412,7 +399,7 @@ constant will appear as a scheme variable. See
<a href="Customization.html#Customization_features">Features and the %feature directive</a>
for info on how to apply the %feature.</p>
<H2><a name="Guile_nn12"></a>23.6 Representation of pointers as smobs</H2>
<H2><a name="Guile_nn12">24.7 Representation of pointers as smobs</a></H2>
<p>
@ -433,7 +420,7 @@ representing the expected pointer type. See also
If the Scheme object passed was not a SWIG smob representing a compatible
pointer, a <code>wrong-type-arg</code> exception is raised.
<H3><a name="Guile_nn13"></a>23.6.1 GH Smobs</H3>
<H3><a name="Guile_nn14">24.7.1 Smobs</a></H3>
<p>
@ -444,44 +431,19 @@ mangled type name. As Guile allows registering user types, so-called
implemented now. The details will be discussed in the following.
</p>
<p> A smob is a cons cell where the lower half of the CAR contains the smob type
tag, while the upper half of the CAR and the whole CDR are available. Every
module creates its own smob type in the clientdata field of the module. So the
lower 16 bits of the car of the smob store the tag and the upper 16 bits store
the index this type is in the array. We can then, given a smob, find its
swig_type_info struct by using the tag (lower 16 bits of car) to find which
module this type is in (since each tag is unique for the module). Then we use
the upper 16 bits to index into the array of types attached to this module.
Looking up the module from the tag is worst case O(# of modules) but average
case O(1). This is because the modules are stored in a circularly linked list,
and when we start searching the modules for the tag, we start looking with the
module that the function doing the lookup is in. SWIG_Guile_ConvertPtr() takes
as its first argument the swig_module_info * of the calling function, which is
where we start comparing tags. Most types will be looked up in the same module
that created them, so the first module we check will most likely be correct.
Once we have a swig_type_info structure, we loop through the linked list of
casts, using pointer comparisons.</p>
<H3><a name="Guile_nn14"></a>23.6.2 SCM Smobs</H3>
<p>The SCM interface (using the "-scm" argument to swig) uses swigrun.swg.
The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig".
<p>The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig".
The swig smob is used for non-garbage collected smobs, while the collected_swig smob is used as described
below. Each smob has the same format, which is a double cell created by SCM_NEWSMOB2()
The first word of data is the pointer to the object and the second word of data is the swig_type_info *
structure describing this type. This is a lot easier than the GH interface above because we can store
a pointer to the type info structure right in the type. With the GH interface, there was not enough
room in the smob to store two whole words of data so we needed to store part of the "swig_type_info address"
in the smob tag. If a generated GOOPS module has been loaded, smobs will be wrapped by the corresponding
GOOPS class.</p>
structure describing this type. If a generated GOOPS module has been loaded, smobs will be wrapped by
the corresponding GOOPS class.</p>
<H3><a name="Guile_nn15"></a>23.6.3 Garbage Collection</H3>
<H3><a name="Guile_nn15">24.7.2 Garbage Collection</a></H3>
<p>Garbage collection is a feature of the new SCM interface, and it is automatically included
if you pass the "-scm" flag to swig. Thus the swig garbage collection support requires guile &gt;1.6.
<p>Garbage collection is a feature of Guile since version 1.6. As SWIG now requires Guile &gt; 1.8,
it is automatically included.
Garbage collection works like this. Every swig_type_info structure stores in its clientdata field a pointer
to the destructor for this type. The destructor is the generated wrapper around the delete function.
So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for
@ -491,7 +453,7 @@ is exactly like described in <a href="Customization.html#Customization_ownership
Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and
the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
<H2><a name="Guile_nn16"></a>23.7 Exception Handling</H2>
<H2><a name="Guile_nn16">24.8 Exception Handling</a></H2>
<p>
@ -500,16 +462,16 @@ mapping:
<div class="code">
<pre>
MAP(SWIG_MemoryError, "swig-memory-error");
MAP(SWIG_IOError, "swig-io-error");
MAP(SWIG_RuntimeError, "swig-runtime-error");
MAP(SWIG_IndexError, "swig-index-error");
MAP(SWIG_TypeError, "swig-type-error");
MAP(SWIG_DivisionByZero, "swig-division-by-zero");
MAP(SWIG_OverflowError, "swig-overflow-error");
MAP(SWIG_SyntaxError, "swig-syntax-error");
MAP(SWIG_ValueError, "swig-value-error");
MAP(SWIG_SystemError, "swig-system-error");
MAP(SWIG_MemoryError, "swig-memory-error");
MAP(SWIG_IOError, "swig-io-error");
MAP(SWIG_RuntimeError, "swig-runtime-error");
MAP(SWIG_IndexError, "swig-index-error");
MAP(SWIG_TypeError, "swig-type-error");
MAP(SWIG_DivisionByZero, "swig-division-by-zero");
MAP(SWIG_OverflowError, "swig-overflow-error");
MAP(SWIG_SyntaxError, "swig-syntax-error");
MAP(SWIG_ValueError, "swig-value-error");
MAP(SWIG_SystemError, "swig-system-error");
</pre>
</div>
@ -517,14 +479,13 @@ mapping:
The default when not specified here is to use "swig-error".
See Lib/exception.i for details.
<H2><a name="Guile_nn17"></a>23.8 Procedure documentation</H2>
<H2><a name="Guile_nn17">24.9 Procedure documentation</a></H2>
<p>If invoked with the command-line option <code>-procdoc
<var>file</var></code>, SWIG creates documentation strings for the
generated wrapper functions, describing the procedure signature and
return value, and writes them to <var>file</var>. You need Guile 1.4
or later to make use of the documentation files.
return value, and writes them to <var>file</var>.
<p>SWIG can generate documentation strings in three formats, which are
selected via the command-line option <code>-procdocformat
@ -553,7 +514,7 @@ like this:
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
details.
<H2><a name="Guile_nn18"></a>23.9 Procedures with setters</H2>
<H2><a name="Guile_nn18">24.10 Procedures with setters</a></H2>
<p>For global variables, SWIG creates a single wrapper procedure
@ -581,7 +542,7 @@ struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get
pointer)</code> and <code>(<var>struct-member</var>-set pointer
value)</code> are <em>not</em> generated.
<H2><a name="Guile_nn19"></a>23.10 GOOPS Proxy Classes</H2>
<H2><a name="Guile_nn19">24.11 GOOPS Proxy Classes</a></H2>
<p>SWIG can also generate classes and generic functions for use with
@ -589,10 +550,7 @@ Guile's Object-Oriented Programming System (GOOPS). GOOPS is a
sophisticated object system in the spirit of the Common Lisp Object
System (CLOS).
<p>GOOPS support is
only available with the new SCM interface (enabled with the
<code>-scm</code> command-line option of SWIG). To enable GOOPS
support, pass the <code>-proxy</code> argument to
<p>To enable GOOPS support, pass the <code>-proxy</code> argument to
swig. This will export the GOOPS wrapper definitions into the
<code><i>module</i>.scm</code> file in the directory specified by -outdir or the
current directory. GOOPS support requires either passive or module linkage.</p>
@ -730,7 +688,7 @@ Notice that &lt;Foo&gt; is used before it is defined. The fix is to just put th
<code>%import "foo.h"</code> before the <code>%inline</code> block.
</p>
<H3><a name="Guile_nn20"></a>23.10.1 Naming Issues</H3>
<H3><a name="Guile_nn20">24.11.1 Naming Issues</a></H3>
<p>As you can see in the example above, there are potential naming conflicts. The default exported
@ -767,7 +725,7 @@ guile-modules. For example,</p>
(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
</pre></div>
<H3><a name="Guile_nn21"></a>23.10.2 Linking</H3>
<H3><a name="Guile_nn21">24.11.2 Linking</a></H3>
<p>The guile-modules generated above all need to be linked together. GOOPS support requires
@ -787,10 +745,10 @@ and might conflict with names from the GOOPS guile-module (see above). Pass the
argument to solve this problem. If the <code>-exportprimitive</code> option is passed to SWIG the
<code>(export ...)</code> code that would be exported into the scmstub file is exported at the bottom
of the generated GOOPS guile-module.
The <code>%goops</code> directive should contain code to load the .so library.
The <code>%goops</code> directive should contain code to load the shared library.
<div class="code"><pre>
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
%goops %{ (load-extension "./libfoo.so" "scm_init_my_modules_foo_module") %}
</pre></div>
<p>
@ -802,7 +760,7 @@ Produces the following code at the top of the generated GOOPS guile-module
(define-module (my modules foo))
;; %goops directive goes here
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
(load-extension "./libfoo.so" "scm_init_my_modules_foo_module")
(use-modules (oop goops) (Swig common))
</pre></div>
@ -810,7 +768,7 @@ Produces the following code at the top of the generated GOOPS guile-module
<li><p><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be
<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,
argument. The code to load the shared 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>
into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autoload path for guile, the
@ -818,7 +776,7 @@ into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autolo
whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p>
<div class="targetlang"><pre>
%scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
%scheme %{ (load-extension "./libfoo.so" "scm_init_my_modules_foo_module") %}
// only include the following definition if (my modules foo) cannot
// be loaded automatically
%goops %{
@ -851,7 +809,7 @@ SWIG will also automatically generate the line <code>(use-modules
directive should contain whatever code is needed to get that module loaded into guile.</p>
<div class="code"><pre>
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
%goops %{ (load-extension "./libfoo.so" "scm_init_my_modules_foo_module") %}
</pre></div>
<p>
@ -862,7 +820,7 @@ Produces the following code at the top of the generated GOOPS guile-module
(define-module (my modules foo))
;; %goops directive goes here (if any)
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
(load-extension "./libfoo.so" "scm_init_my_modules_foo_module")
(use-modules (oop goops) (Swig common))
(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc

75
Doc/Manual/Introduction.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Introduction</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Introduction"></a>2 Introduction</H1>
<H1><a name="Introduction">2 Introduction</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -31,14 +32,14 @@
<H2><a name="Introduction_nn2"></a>2.1 What is SWIG?</H2>
<H2><a name="Introduction_nn2">2.1 What is SWIG?</a></H2>
<p>
SWIG is a software development tool that simplifies the task of
interfacing different languages to C and C++ programs. In a
nutshell, SWIG is a compiler that takes C/C++ declarations and creates
the wrappers needed to access those declarations from other languages including
the wrappers needed to access those declarations from other languages
including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally
requires no modifications to existing code and can often be used to
build a usable interface in only a few minutes. Possible applications
@ -49,7 +50,7 @@ of SWIG include:
<li>Building interpreted interfaces to existing C programs.
<li>Rapid prototyping and application development.
<li>Interactive debugging.
<li>Reengineering or refactoring of legacy software into a scripting language components.
<li>Reengineering or refactoring of legacy software into scripting language components.
<li>Making a graphical user interface (using Tk for example).
<li>Testing of C libraries and programs (using scripts).
<li>Building high performance C modules for scripting languages.
@ -71,7 +72,7 @@ small; especially the research and development work that is commonly found
in scientific and engineering projects. However, nowadays SWIG is known to be used in many
large open source and commercial projects.
<H2><a name="Introduction_nn3"></a>2.2 Why use SWIG?</H2>
<H2><a name="Introduction_nn3">2.2 Why use SWIG?</a></H2>
<p>
@ -98,7 +99,7 @@ of other libraries).
<li>Testing is time consuming (the compile/debug cycle).
<li>Not easy to reconfigure or customize without recompilation.
<li>Modularization can be tricky.
<li>Security concerns (buffer overflow for instance).
<li>Security concerns (buffer overflows for instance).
</ul>
<p>
To address these limitations, many programmers have arrived at the
@ -143,7 +144,7 @@ it provides a wide variety of customization features that let you change almost
every aspect of the language bindings. This is the main reason why SWIG has such a large
user manual ;-).
<H2><a name="Introduction_nn4"></a>2.3 A SWIG example</H2>
<H2><a name="Introduction_nn4">2.3 A SWIG example</a></H2>
<p>
@ -157,14 +158,16 @@ following C code:
double My_variable = 3.0;
/* Compute factorial of n */
int fact(int n) {
if (n &lt;= 1) return 1;
else return n*fact(n-1);
int fact(int n) {
if (n &lt;= 1)
return 1;
else
return n*fact(n-1);
}
/* Compute n mod m */
int my_mod(int n, int m) {
return(n % m);
return(n % m);
}
</pre></div>
@ -174,7 +177,7 @@ variable <tt>My_variable</tt> from Tcl. You start by making a SWIG
interface file as shown below (by convention, these files carry a .i
suffix) :
<H3><a name="Introduction_nn5"></a>2.3.1 SWIG interface file</H3>
<H3><a name="Introduction_nn5">2.3.1 SWIG interface file</a></H3>
<div class="code"><pre>
@ -199,7 +202,7 @@ module that will be created by SWIG. The <tt>%{ %}</tt> block
provides a location for inserting additional code, such as C header
files or additional C declarations, into the generated C wrapper code.
<H3><a name="Introduction_nn6"></a>2.3.2 The swig command</H3>
<H3><a name="Introduction_nn6">2.3.2 The swig command</a></H3>
<p>
@ -221,8 +224,7 @@ unix &gt; <b>tclsh</b>
7.5
%
</pre></div>
<p>
<p>
The <tt>swig</tt> command produced a new file called
<tt>example_wrap.c</tt> that should be compiled along with the
<tt>example.c</tt> file. Most operating systems and scripting
@ -233,7 +235,7 @@ and variables declared in the SWIG interface. A look at the file
<tt>example_wrap.c</tt> reveals a hideous mess. However, you
almost never need to worry about it.
<H3><a name="Introduction_nn7"></a>2.3.3 Building a Perl5 module</H3>
<H3><a name="Introduction_nn7">2.3.3 Building a Perl5 module</a></H3>
<p>
@ -244,8 +246,8 @@ any changes type the following (shown for Solaris):
<div class="shell"><pre>
unix &gt; <b>swig -perl5 example.i</b>
unix &gt; <b>gcc -c example.c example_wrap.c \
-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
unix &gt; <b>ld -G example.o example_wrap.o -o example.so</b> # This is for Solaris
-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
unix &gt; <b>ld -G example.o example_wrap.o -o example.so</b> # This is for Solaris
unix &gt; <b>perl5.003
use example;
print example::fact(4), "\n";
@ -259,7 +261,7 @@ unix &gt;
</pre></div>
<H3><a name="Introduction_nn8"></a>2.3.4 Building a Python module</H3>
<H3><a name="Introduction_nn8">2.3.4 Building a Python module</a></H3>
<p>
@ -283,7 +285,7 @@ Type "copyright", "credits" or "license" for more information.
7.5
</pre></div>
<H3><a name="Introduction_nn9"></a>2.3.5 Shortcuts</H3>
<H3><a name="Introduction_nn9">2.3.5 Shortcuts</a></H3>
<p>
@ -296,7 +298,7 @@ SWIG on the C header file and specifying a module name as follows
<div class="shell"><pre>
unix &gt; <b>swig -perl5 -module example example.h</b>
unix &gt; <b>gcc -c example.c example_wrap.c \
-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
unix &gt; <b>ld -G example.o example_wrap.o -o example.so</b>
unix &gt; <b>perl5.003
use example;
@ -309,7 +311,7 @@ print $example::My_variable + 4.5, "\n";
7.5
</pre></div>
<H2><a name="Introduction_nn10"></a>2.4 Supported C/C++ language features</H2>
<H2><a name="Introduction_nn10">2.4 Supported C/C++ language features</a></H2>
<p>
@ -334,8 +336,7 @@ major features include:
</ul>
<p>
Currently, the only major C++ feature not supported is nested classes--a limitation
that should be removed in a future release, but has some workarounds for the moment.
Most of C++11 is also supported. Details are in the <a href="CPlusPlus11.html#CPlusPlus11">C++11</a> section.
</p>
<p>
@ -345,11 +346,11 @@ not only parses C++, it implements the full C++ type system and it is
able to understand C++ semantics. SWIG generates its wrappers with
full knowledge of this information. As a result, you will find SWIG
to be just as capable of dealing with nasty corner cases as it is in
wrapping simple C++ code. In fact, SWIG is able handle C++ code that
wrapping simple C++ code. In fact, SWIG is able to handle C++ code that
stresses the very limits of many C++ compilers.
<H2><a name="Introduction_nn11"></a>2.5 Non-intrusive interface building</H2>
<H2><a name="Introduction_nn11">2.5 Non-intrusive interface building</a></H2>
<p>
@ -361,7 +362,7 @@ interface and reuse the code in other applications. It is also
possible to support different types of interfaces depending on the application.
</p>
<H2><a name="Introduction_build_system"></a>2.6 Incorporating SWIG into a build system</H2>
<H2><a name="Introduction_build_system">2.6 Incorporating SWIG into a build system</a></H2>
<p>
@ -384,12 +385,12 @@ for further information on this and other Autoconf macros.
</p>
<p>
There is growing support for SWIG in some build tools, for example <a href="http://www.cmake.org">CMake</a>
There is growing support for SWIG in some build tools, for example <a href="http://cmake.org">CMake</a>
is a cross-platform, open-source build manager with built in support for SWIG. CMake can detect the SWIG executable
and many of the target language libraries for linking against.
CMake knows how to build shared libraries and loadable modules on many different operating systems.
This allows easy cross platform SWIG development. It also can generate the custom commands necessary for
driving SWIG from IDE's and makefiles. All of this can be done from a single cross platform input file.
This allows easy cross platform SWIG development. It can also generate the custom commands necessary for
driving SWIG from IDEs and makefiles. All of this can be done from a single cross platform input file.
The following example is a CMake input file for creating a python wrapper for the SWIG interface file, example.i:
</p>
@ -419,7 +420,7 @@ which will invoke SWIG and compile the generated C++ files into _example.so (UNI
For other target languages on Windows a dll, instead of a .pyd file, is usually generated.
</p>
<H2><a name="Introduction_nn12"></a>2.7 Hands off code generation</H2>
<H2><a name="Introduction_nn12">2.7 Hands off code generation</a></H2>
<p>
@ -432,7 +433,7 @@ it allows others to forget about the low-level implementation
details.
</p>
<H2><a name="Introduction_nn13"></a>2.8 SWIG and freedom</H2>
<H2><a name="Introduction_nn13">2.8 SWIG and freedom</a></H2>
<p>
@ -449,7 +450,7 @@ to work with complicated and unusual C/C++ applications.
<p>
Ironically, the freedom that SWIG provides is countered by an
extremely conservative approach to code generation. At it's core, SWIG
extremely conservative approach to code generation. At its core, SWIG
tries to distill even the most advanced C++ code down to a small
well-defined set of interface building techniques based on ANSI C
programming. Because of this, you will find that SWIG interfaces can
@ -458,6 +459,12 @@ be used on any platform. Again, this is an important part of staying out
of the programmer's way----the last thing any developer wants to do is
to spend their time debugging the output of a tool that relies on
non-portable or unreliable programming features.
Dependencies are often a source of incompatibilities and problems and so
additional third party libraries are not used in the generated code.
SWIG will also generally avoid generating code that introduces a dependency
on the C++ Standard Template Library (STL).
SWIG will generate code that depends on the C libraries though.
</p>
</body>
</html>

1056
Doc/Manual/Java.html
View file

File diff suppressed because it is too large Load diff

999
Doc/Manual/Javascript.html Normal file
View file

@ -0,0 +1,999 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<link rel="stylesheet" type="text/css" href="./style.css">
<title></title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body>
<H1><a name="Javascript">26 SWIG and Javascript</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Javascript_overview">Overview</a>
<li><a href="#Javascript_preliminaries">Preliminaries</a>
<ul>
<li><a href="#Javascript_running_swig">Running SWIG</a>
<li><a href="#Javascript_running_tests_examples">Running Tests and Examples</a>
<li><a href="#Javascript_known_issues">Known Issues</a>
</ul>
<li><a href="#Javascript_integration">Integration</a>
<ul>
<li><a href="#Javascript_node_extensions">Creating node.js Extensions</a>
<ul>
<li><a href="#Javascript_troubleshooting">Troubleshooting</a>
</ul>
<li><a href="#Javascript_embedded_webkit">Embedded Webkit</a>
<ul>
<li><a href="#Javascript_osx">Mac OS X</a>
<li><a href="#Javascript_gtk">GTK</a>
</ul>
<li><a href="#Javascript_applications_webkit">Creating Applications with node-webkit</a>
</ul>
<li><a href="#Javascript_examples">Examples</a>
<ul>
<li><a href="#Javascript_simple_example">Simple</a>
<li><a href="#Javascript_class_example">Class</a>
</ul>
<li><a href="#Javascript_implementation">Implementation</a>
<ul>
<li><a href="#Javascript_source_code">Source Code</a>
<li><a href="#Javascript_code_templates">Code Templates</a>
<li><a href="#Javascript_emitter">Emitter</a>
<li><a href="#Javascript_emitter_states">Emitter states</a>
<li><a href="#Javascript_jsc_exceptions">Handling Exceptions in JavascriptCore</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>This chapter describes SWIG's support of Javascript. It does not cover SWIG basics, but only information that is specific to this module.</p>
<H2><a name="Javascript_overview">26.1 Overview</a></H2>
<p>Javascript is a prototype-based scripting language that is dynamic, weakly typed and has first-class functions. Its arguably the most popular language for web development.
Javascript has gone beyond being a browser-based scripting language and with <a href="http://nodejs.org">node.js</a>, it is also used as a backend development language.</p>
<p>Native Javascript extensions can be used for applications that embed a web-browser view or that embed a Javascript engine (such as <em>node.js</em>). Extending a general purpose web-browser is not possible as this would be a severe security issue.</p>
<p>SWIG Javascript currently supports <strong>JavascriptCore</strong>, the Javascript engine used by <code>Safari/Webkit</code>, and <a href="https://developers.google.com/v8"><strong>v8</strong></a>, which is used by <code>Chromium</code> and <code>node.js</code>.</p>
<p><a href="http://www.webkit.org/">WebKit</a> is a modern browser implementation available as open-source which can be embedded into an application.
With <a href="https://github.com/rogerwang/node-webkit">node-webkit</a> there is a platform which uses Google's <code>Chromium</code> as Web-Browser widget and <code>node.js</code> for javascript extensions.
</p>
<H2><a name="Javascript_preliminaries">26.2 Preliminaries</a></H2>
<H3><a name="Javascript_running_swig">26.2.1 Running SWIG</a></H3>
<p>Suppose that you defined a SWIG module such as the following:</p>
<div class="code">
<pre>
%module example
%{
#include "example.h"
%}
int gcd(int x, int y);
extern double Foo;</pre>
</div>
<p>To build a Javascript module, run SWIG using the <code>-javascript</code> option and a desired target engine <code>-jsc</code>, <code>-v8</code>, or <code>-node</code>. The generator for <code>node</code> is essentially delegating to the <code>v8</code> generator and adds some necessary preprocessor definitions.</p>
<div class="shell">
<pre>
$ swig -javascript -jsc example.i</pre>
</div>
<p>If building a C++ extension, add the -c++ option:</p>
<div class="shell">
<pre>
$ swig -c++ -javascript -jsc example.i</pre>
</div>
<p>The V8 code that SWIG generates should work with most versions from 3.11.10 up to 3.29.14 and later.</p>
<p>The API headers for V8 &gt;= 4.3.0 define constants which SWIG can use to
determine the V8 version it is compiling for. For versions &lt; 4.3.0, you
need to specify the V8 version when running SWIG. This is specified as a hex
constant, but the constant is read as pairs of decimal digits, so for V8
3.25.30 use constant 0x032530. This scheme can't represent components &gt; 99,
but this constant is only useful for V8 &lt; 4.3.0, and no V8 versions from
that era had a component &gt; 99. For example:</p>
<div class="shell">
<pre>
$ swig -c++ -javascript -v8 -DV8_VERSION=0x032530 example.i</pre>
</div>
<p>If you're targetting V8 &gt;= 4.3.0, you would just run swig like so:</p>
<div class="shell">
<pre>
$ swig -c++ -javascript -v8 example.i</pre>
</div>
<p>This creates a C/C++ source file <code>example_wrap.c</code> or <code>example_wrap.cxx</code>. The generated C source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application to create an extension module.</p>
<p>The name of the wrapper file is derived from the name of the input file. For example, if the input file is <code>example.i</code>, the name of the wrapper file is <code>example_wrap.c</code>. To change this, you can use the -o option. The wrapped module will export one function which must be called to register the module with the Javascript interpreter. For example, if your module is named <code>example</code> the corresponding initializer for JavascriptCore would be</p>
<div class="code">
<pre>
bool example_initialize(JSGlobalContextRef context, JSObjectRef *exports)</pre>
</div>
<p>and for v8:</p>
<div class="code">
<pre>
void example_initialize(v8::Handle&lt;v8::Object&gt; exports)</pre>
</div>
<p>
<b>Note</b>: be aware that <code>v8</code> has a C++ API, and thus, the generated modules must be compiled as C++.
</p>
<H3><a name="Javascript_running_tests_examples">26.2.2 Running Tests and Examples</a></H3>
<p>The configuration for tests and examples currently supports Linux and Mac only and not MinGW (Windows) yet.</p>
<p>The default interpreter is <code>node.js</code> as it is available on all platforms and convenient to use.</p>
<p>Running the examples with JavascriptCore requires <code>libjavascriptcoregtk-1.0</code> to be installed, e.g., under Ubuntu with</p>
<div class="shell">
<pre>
$ sudo apt-get install libjavascriptcoregtk-1.0-dev</pre>
</div>
<p>Running with <code>V8</code> requires <code>libv8</code>:</p>
<div class="shell">
<pre>
$ sudo apt-get install libv8-dev</pre>
</div>
<p>Examples can be run using</p>
<div class="shell">
<pre>
$ make check-javascript-examples ENGINE=jsc</pre>
</div>
<p><code>ENGINE</code> can be <code>node</code>, <code>jsc</code>, or <code>v8</code>.</p>
<p>The test-suite can be run using</p>
<div class="shell">
<pre>
$ make check-javascript-test-suite ENGINE=jsc</pre>
</div>
<p>You can specify a specific <code>V8</code> version for running the examples and tests</p>
<div class="shell">
<pre>
$ make check-javascript-examples V8_VERSION=0x032530 ENGINE=v8</pre>
</div>
<H3><a name="Javascript_known_issues">26.2.3 Known Issues</a></H3>
<p>At the moment, the Javascript generators pass all tests syntactically, i.e., the generated source code compiles. However, there are still remaining runtime issues.</p>
<ul>
<li><p>Default optional arguments do not work for all targeted interpreters</p></li>
<li><p>Multiple output arguments do not work for JSC</p></li>
<li><p>C89 incompatibily: the JSC generator might still generate C89 violating code</p></li>
<li><p><code>long long</code> is not supported</p></li>
<li><p><code>%native</code> is not supported</p></li>
<li><p>Javascript callbacks are not supported</p></li>
<li><p><code>instanceOf</code> does not work under JSC</p></li>
</ul>
<p>The primary development environment has been Linux (Ubuntu 12.04). Windows and Mac OS X have been tested sporadically. Therefore, the generators might have more issues on those platforms. Please report back any problem you observe to help us improving this module quickly.</p>
<H2><a name="Javascript_integration">26.3 Integration</a></H2>
<p>This chapter gives a short introduction how to use a native Javascript extension: as a <code>node.js</code> module, and as an extension for an embedded Webkit.</p>
<H3><a name="Javascript_node_extensions">26.3.1 Creating node.js Extensions</a></H3>
<p>To install <code>node.js</code> you can download an installer from their <a href="https://launchpad.net/~chris-lea/+archive/node.js">web-site</a> for Mac OS X and Windows. For Linux you can either build the source yourself and run <code>sudo checkinstall</code> or keep to the (probably stone-age) packaged version. For Ubuntu there is a <a href="https://launchpad.net/~chris-lea/+archive/ubuntu/node.js/">PPA</a> available.</p>
<div class="shell">
<pre>
$ sudo add-apt-repository ppa:chris-lea/node.js
$ sudo apt-get update
$ sudo apt-get install nodejs</pre>
</div>
<p>As <code>v8</code> is written in C++ and comes as a C++ library it is crucial to compile your module using the same compiler flags as used for building v8. To make things easier, <code>node.js</code> provides a build tool called <code>node-gyp</code>.</p>
<p>You have to install it using <code>npm</code>:</p>
<div class="shell">
<pre>
$ sudo npm install -g node-gyp</pre>
</div>
<p><code>node-gyp</code> expects a configuration file named <code>binding.gyp</code> which is basically in JSON format and conforms to the same format that is used with Google's build-tool <code>gyp</code>.</p>
<p><code>binding.gyp</code>:</p>
<div class="code">
<pre>
{
"targets": [
{
"target_name": "example",
"sources": [ "example.cxx", "example_wrap.cxx" ]
}
]
}</pre>
</div>
<p>First create the wrapper using SWIG:</p>
<div class="shell">
<pre>
$ swig -javascript -node -c++ example.i</pre>
</div>
<p>Then run <code>node-gyp build</code> to actually create the module:</p>
<div class="shell">
<pre>
$ node-gyp build</pre>
</div>
<p>This will create a <code>build</code> folder containing the native module. To use the extension you need to 'require' it in your Javascript source file:</p>
<div class="code">
<pre>
require("./build/Release/example")</pre>
</div>
<p>A more detailed explanation is given in the <a href="#Javascript_examples">Examples</a> section.</p>
<H4><a name="Javascript_troubleshooting">26.3.1.1 Troubleshooting</a></H4>
<ul>
<li><em>'module' object has no attribute 'script_main'</em></li>
</ul>
<p>This error happens when <code>gyp</code> is installed as a distribution package. It seems to be outdated. Removing it resolves the problem.</p>
<div class="shell">
<pre>
$ sudo apt-get remove gyp</pre>
</div>
<H3><a name="Javascript_embedded_webkit">26.3.2 Embedded Webkit</a></H3>
<p>Webkit is pre-installed on Mac OS X and available as a library for GTK.</p>
<H4><a name="Javascript_osx">26.3.2.1 Mac OS X</a></H4>
<p>There is general information about programming with WebKit on <a href="https://developer.apple.com/library/mac/documentation/cocoa/conceptual/DisplayWebContent/DisplayWebContent.html">Apple Developer Documentation</a>. Details about <code>Cocoa</code> programming are not covered here.</p>
<p>An integration of a native extension 'example' would look like this:</p>
<div class="code">
<pre>
#import "appDelegate.h"
extern bool example_initialize(JSGlobalContextRef context, JSObjectRef* exports);
@implementation ExampleAppDelegate
@synthesize webView;
- (void)addGlobalObject:(JSContextRef) context:(NSString *)objectName:(JSObjectRef) theObject {
JSObjectRef global = JSContextGetGlobalObject(context);
JSStringRef objectJSName = JSStringCreateWithCFString( (CFStringRef) objectName )
if ( objectJSName != NULL ) {
JSObjectSetProperty(context, global, objectJSName, theObject, kJSPropertyAttributeReadOnly, NULL);
JSStringRelease( objectJSName );
}
}
- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
// Start a webview with the bundled index.html file
NSString *path = [[NSBundle mainBundle] bundlePath];
NSString *url = [NSString stringWithFormat: @"file://%@/Contents/Assets/index.html", path];
WebFrame *webframe = [webView mainFrame];
JSGlobalContextRef context = [webframe globalContext];
JSObjectRef example;
example_initialize(context, &amp;example);
[self addGlobalObject:context:@"example":example]
JSObjectSetProperty(context, global, JSStringRef propertyName, example, JSPropertyAttributes attributes, NULL);
[ [webView mainFrame] loadRequest:
[NSURLRequest requestWithURL: [NSURL URLWithString:url] ]
];
}
@end</pre>
</div>
<H4><a name="Javascript_gtk">26.3.2.2 GTK</a></H4>
<p>There is general information about programming GTK at <a href="https://developer.gnome.org/gtk2/">GTK documentation</a> and in the <a href="https://developer.gnome.org/gtk-tutorial">GTK tutorial</a>, and for Webkit there is a <a href="http://webkitgtk.org/reference/webkitgtk/stable/index.html">Webkit GTK+ API Reference</a>.</p>
<p>An integration of a native extension 'example' would look like this:</p>
<div class="code">
<pre>
#include &lt;gtk/gtk.h&gt;
#include &lt;webkit/webkit.h&gt;
extern bool example_initialize(JSGlobalContextRef context);
int main(int argc, char* argv[])
{
// Initialize GTK+
gtk_init(&amp;argc, &amp;argv);
...
// Create a browser instance
WebKitWebView *webView = WEBKIT_WEB_VIEW(webkit_web_view_new());
WebFrame *webframe = webkit_web_view_get_main_frame(webView);
JSGlobalContextRef context = webkit_web_frame_get_global_context(webFrame);
JSObjectRef global = JSContextGetGlobalObject(context);
JSObjectRef exampleModule;
example_initialize(context, &amp;exampleModule);
JSStringRef jsName = JSStringCreateWithUTF8CString("example");
JSObjectSetProperty(context, global, jsName, exampleModule, kJSPropertyAttributeReadOnly, NULL);
JSStringRelease(jsName);
...
// Load a web page into the browser instance
webkit_web_view_load_uri(webView, "http://www.webkitgtk.org/");
...
// Run the main GTK+ event loop
gtk_main();
return 0;
}</pre>
</div>
<H3><a name="Javascript_applications_webkit">26.3.3 Creating Applications with node-webkit</a></H3>
<p>To get started with <code>node-webkit</code> there is a very informative set of <a href="https://github.com/rogerwang/node-webkit/wiki">wiki pages</a>.</p>
<p>Similar to <code>node.js</code>, <code>node-webkit</code> is started from command line within a <code>node.js</code> project directory.
Native extensions are created in the very same way as for <code>node.js</code>, except that a customized <code>gyp</code> derivate has to be used: <a href="https://github.com/rogerwang/nw-gyp">nw-gyp</a>.
</p>
<p>
A simple example would have the following structure:
</p>
<div class="code">
<pre>
- package.json
- app.html
- app.js
- node_modules
/ example
... (as known from node.js)
</pre>
</div>
<p>
The configuration file essentially conforms to <code>node.js</code> syntax.
It has some extras to configure <code>node-webkit</code>. See the <a href="https://github.com/rogerwang/node-webkit/wiki/Manifest-format">Manifest</a> specification for more details.
</p>
<p>
<code>package.json</code>:
</p>
<div class="code">
<pre>
{
"name": "example",
"main": "app.html",
"window": {
"show": true,
"width": 800,
"height": 600
}
}</pre>
</div>
<p>
The <code>'main'</code> property of <code>package.json</code> specifies a web-page to be rendered in
the main window.</p>
<p>
<code>app.html</code>:
</p>
<div class="code">
<pre>
&lt;html&gt;
&lt;head&gt;
&lt;script src="app.js"&gt;&lt;/script&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;div&gt;
The greatest common divisor of
&lt;span id="x"&gt;&lt;/span&gt; and
&lt;span id="y"&gt;&lt;/span&gt; is
&lt;span id="z"&gt;&lt;/span&gt;.
&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;</pre>
</div>
<p>
As known from <code>node.js</code> one can use <code>require</code> to load javascript modules.
Additionally, <code>node-webkit</code> provides an API that allows to manipulate the window's menu,
open new windows, and many more things.
</p>
<p>
<code>app.js</code>:
</p>
<div class="code">
<pre>window.onload = function() {
var example = require("example");
var x = 18;
var y = 24;
var z = example.gcd(x,y);
document.querySelector('#x').innerHTML = x;
document.querySelector('#y').innerHTML = y;
document.querySelector('#z').innerHTML = z;
};</pre>
</div>
<H2><a name="Javascript_examples">26.4 Examples</a></H2>
<p>Some basic examples are shown here in more detail.</p>
<H3><a name="Javascript_simple_example">26.4.1 Simple</a></H3>
<p>The common example <code>simple</code> looks like this:</p>
<div class="code">
<pre>
/* File : example.i */
%module example
%inline %{
extern int gcd(int x, int y);
extern double Foo;
%}</pre>
</div>
<p>To make this available as a node extension a <code>binding.gyp</code> has to be created:</p>
<div class="code">
<pre>
{
"targets": [
{
"target_name": "example",
"sources": [ "example.cxx", "example_wrap.cxx" ]
}
]
}</pre>
</div>
<p>Then <code>node-gyp</code> is used to build the extension:</p>
<div class="shell">
<pre>
$ node-gyp configure build</pre>
</div>
<p>From a 'nodejs` application the extension would be used like this:</p>
<div class="code">
<pre>
// import the extension via require
var example = require("./build/Release/example");
// calling the global method
var x = 42;
var y = 105;
var g = example.gcd(x,y);
// Accessing the global variable
var f = example.Foo;
example.Foo = 3.1415926;</pre>
</div>
<p>First the module <code>example</code> is loaded from the previously built extension. Global methods and variables are available in the scope of the module.</p>
<p><b>Note</b>: ECMAScript 5, the currently implemented Javascript standard, does not have modules. <code>node.js</code> and other implementations provide this mechanism defined by the <a href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> group. For browsers this is provided by <a href="http://browserify.org">Browserify</a>, for instance.</p>
<H3><a name="Javascript_class_example">26.4.2 Class</a></H3>
<p>The common example <code>class</code> defines three classes, <code>Shape</code>, <code>Circle</code>, and <code>Square</code>:</p>
<div class="code">
<pre>
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
}
double x, y;
void move(double dx, double dy);
virtual double area(void) = 0;
virtual double perimeter(void) = 0;
static int nshapes;
};
class Circle : public Shape {
private:
double radius;
public:
Circle(double r) : radius(r) { }
virtual double area(void);
virtual double perimeter(void);
};
class Square : public Shape {
private:
double width;
public:
Square(double w) : width(w) { }
virtual double area(void);
virtual double perimeter(void);
};</pre>
</div>
<p><code>Circle</code> and <code>Square</code> inherit from <code>Shape</code>. <code>Shape</code> has a static variable <code>nshapes</code>, a function <code>move</code> that can't be overridden (non-virtual), and two abstract functions <code>area</code> and <code>perimeter</code> (pure virtual) that must be overridden by the sub-classes.</p>
<p>A <code>nodejs</code> extension is built the same way as for the <code>simple</code> example.</p>
<p>In Javascript it can be used as follows:</p>
<div class="code">
<pre>
var example = require("./build/Release/example");
// local aliases for convenience
var Shape = example.Shape;
var Circle = example.Circle;
var Square = example.Square;
// creating new instances using the 'new' operator
var c = new Circle(10);
var s = new Square(10);
// accessing a static member
Shape.nshapes;
// accessing member variables
c.x = 20;
c.y = 30;
s.x = -10;
s.y = 5;
// calling some methods
c.area();
c.perimeter();
s.area();
s.perimeter();
// instantiation of Shape is not permitted
new Shape();</pre>
</div>
<p>Running these commands in an interactive node shell results in the following output:</p>
<div class="shell">
<pre>
$ node -i
&amp; var example = require("./build/Release/example");
undefined
&amp; var Shape = example.Shape;
undefined
&amp; var Circle = example.Circle;
undefined
&amp; var Square = example.Square;
undefined
&amp; var c = new Circle(10);
undefined
&amp; var s = new Square(10);
undefined
&amp; Shape.nshapes;
2
&amp; c.x = 20;
20
&amp; c.y = 30;
30
&amp; s.x = -10;
-10
&amp; s.y = 5;
5
&amp; c.area();
314.1592653589793
&amp; c.perimeter();
62.83185307179586
&amp; s.area();
100
&amp; s.perimeter();
40
&amp; c.move(40, 40)
undefined
&amp; c.x
60
&amp; c.y
70
&amp; new Shape()
Error: Class Shape can not be instantiated
at repl:1:2
at REPLServer.self.eval (repl.js:110:21)
at Interface.&lt;anonymous&gt; (repl.js:239:12)
at Interface.EventEmitter.emit (events.js:95:17)
at Interface._onLine (readline.js:202:10)
at Interface._line (readline.js:531:8)
at Interface._ttyWrite (readline.js:760:14)
at ReadStream.onkeypress (readline.js:99:10)
at ReadStream.EventEmitter.emit (events.js:98:17)
at emitKey (readline.js:1095:12)</pre>
</div>
<p>
<b>Note</b>: In ECMAScript 5 there is no concept for classes. Instead each function can be used as a constructor function which is executed by the 'new' operator. Furthermore, during construction the key property <code>prototype</code> of the constructor function is used to attach a prototype instance to the created object. A prototype is essentially an object itself that is the first-class delegate of a class used whenever the access to a property of an object fails. The very same prototype instance is shared among all instances of one type. Prototypal inheritance is explained in more detail on in <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain">Inheritance and the prototype chain</a>, for instance.
</p>
<H2><a name="Javascript_implementation">26.5 Implementation</a></H2>
<p>The Javascript Module implementation has taken a very different approach compared to other language modules in order to support different Javascript interpreters.</p>
<H3><a name="Javascript_source_code">26.5.1 Source Code</a></H3>
<p>The Javascript module is implemented in <code>Source/Modules/javascript.cxx</code>. It dispatches the code generation to a <code>JSEmitter</code> instance, <code>V8Emitter</code> or <code>JSCEmitter</code>. Additionally there are some helpers: <code>Template</code>, for templated code generation, and <code>JSEmitterState</code>, which is used to manage state information during AST traversal. This rough map shall make it easier to find a way through this huge source file:</p>
<div class="code">
<pre>
// module wide defines
#define NAME "name"
...
// ###############################
// # Helper class declarations
class JSEmitterState { ... };
class Template { ... };
// ###############################
// # JSEmitter declaration
class JSEmitter { ... };
// Emitter factory declarations
JSEmitter *swig_javascript_create_JSCEmitter();
JSEmitter *swig_javascript_create_V8Emitter();
// ###############################
// # Javascript module
// Javascript module declaration
class JAVASCRIPT:public Language { ... };
// Javascript module implementation
int JAVASCRIPT::functionWrapper(Node *n) { ... }
...
// Module factory implementation
static Language *new_swig_javascript() { ... }
extern "C" Language *swig_javascript(void) { ... }
// ###############################
// # JSEmitter base implementation
JSEmitter::JSEmitter() { ... }
Template JSEmitter::getTemplate(const String *name) { ... }
...
// ###############################
// # JSCEmitter
// JSCEmitter declaration
class JSCEmitter: public JSEmitter { ... };
// JSCEmitter implementation
JSCEmitter::JSCEmitter() { ... }
void JSCEmitter::marshalInputArgs(Node *n, ParmList *parms, Wrapper *wrapper, MarshallingMode mode, bool is_member, bool is_static) { ... }
...
// JSCEmitter factory
JSEmitter *swig_javascript_create_JSCEmitter() { ... }
// ###############################
// # V8Emitter
// V8Emitter declaration
class V8Emitter: public JSEmitter { ... };
// V8Emitter implementation
V8Emitter::V8Emitter() { ... }
int V8Emitter::initialize(Node *n) { ... }
// V8Emitter factory
JSEmitter *swig_javascript_create_V8Emitter() { ... }
// ###############################
// # Helper implementation (JSEmitterState, Template)
JSEmitterState::JSEmitterState() { ... }
...
Template::Template(const String *code_) { ... }
...</pre>
</div>
<H3><a name="Javascript_code_templates">26.5.2 Code Templates</a></H3>
<p>All generated code is created on the basis of code templates. The templates for <em>JavascriptCore</em> can be found in <code>Lib/javascript/jsc/javascriptcode.swg</code>, for <em>v8</em> in <code>Lib/javascript/v8/javascriptcode.swg</code>.</p>
<p>To track the originating code template for generated code you can run</p>
<div class="shell">
<pre>
$ swig -javascript -jsc -debug-codetemplates</pre>
</div>
<p>which wraps generated code with a descriptive comment</p>
<div class="code">
<pre>
/* begin fragment("template_name") */
...generated code ...
/* end fragment("template_name") */</pre>
</div>
<p>The Template class is used like this:</p>
<div class="code">
<pre>
Template t_register = getTemplate("jsv8_register_static_variable");
t_register.replace("$jsparent", state.clazz(NAME_MANGLED))
.replace("$jsname", state.variable(NAME))
.replace("$jsgetter", state.variable(GETTER))
.replace("$jssetter", state.variable(SETTER))
.trim().
print(f_init_static_wrappers);</pre>
</div>
<p>A code template is registered with the <em>JSEmitter</em> via <code>fragment(name, &quot;template&quot;)</code>, e.g.,</p>
<div class="code">
<pre>
%fragment ("jsc_variable_declaration", "templates")
%{
{"$jsname", $jsgetter, $jssetter, kJSPropertyAttributeNone},
%}</pre>
</div>
<p><code>Template</code> creates a copy of that string and <code>Template::replace</code> uses Swig's <code>Replaceall</code> to replace variables in the template. <code>Template::trim</code> can be used to eliminate leading and trailing whitespaces. <code>Template::print</code> is used to write the final template string to a Swig <code>DOH</code> (based on <code>Printv</code>). All methods allow chaining.</p>
<H3><a name="Javascript_emitter">26.5.3 Emitter</a></H3>
<p>The Javascript module delegates code generation to a <code>JSEmitter</code> instance. The following extract shows the essential interface:</p>
<div class="code">
<pre>
class JSEmitter {
...
/**
* Opens output files and temporary output DOHs.
*/
virtual int initialize(Node *n);
/**
* Writes all collected code into the output file(s).
*/
virtual int dump(Node *n) = 0;
/**
* Cleans up all open output DOHs.
*/
virtual int close() = 0;
...
/**
* Invoked at the beginning of the classHandler.
*/
virtual int enterClass(Node *);
/**
* Invoked at the end of the classHandler.
*/
virtual int exitClass(Node *) {
return SWIG_OK;
}
/**
* Invoked at the beginning of the variableHandler.
*/
virtual int enterVariable(Node *);
/**
* Invoked at the end of the variableHandler.
*/
virtual int exitVariable(Node *) {
return SWIG_OK;
}
/**
* Invoked at the beginning of the functionHandler.
*/
virtual int enterFunction(Node *);
/**
* Invoked at the end of the functionHandler.
*/
virtual int exitFunction(Node *) {
return SWIG_OK;
}
/**
* Invoked by functionWrapper callback after call to Language::functionWrapper.
*/
virtual int emitWrapperFunction(Node *n);
/**
* Invoked from constantWrapper after call to Language::constantWrapper.
**/
virtual int emitConstant(Node *n);
/**
* Registers a given code snippet for a given key name.
*
* This method is called by the fragmentDirective handler
* of the JAVASCRIPT language module.
**/
int registerTemplate(const String *name, const String *code);
/**
* Retrieve the code template registered for a given name.
*/
Template getTemplate(const String *name);
State &amp;getState();
...
}</pre>
</div>
<p>The module calls <code>initialize</code>, <code>dump</code>, and <code>close</code> from within the <code>top</code> method:</p>
<div class="code">
<pre>
int JAVASCRIPT::top(Node *n) {
emitter-&gt;initialize(n);
Language::top(n);
emitter-&gt;dump(n);
emitter-&gt;close();
return SWIG_OK;
}</pre>
</div>
<p>The methods <code>enterClass</code> and <code>exitClass</code> are called from within the <code>classHandler</code> method:</p>
<div class="code">
<pre>
int JAVASCRIPT::classHandler(Node *n) {
emitter-&gt;enterClass(n);
Language::classHandler(n);
emitter-&gt;exitClass(n);
return SWIG_OK;
}</pre>
</div>
<p>In <code>enterClass</code> the emitter stores state information that is necessary when processing class members. In <code>exitClass</code> the wrapper code for the whole class is generated.</p>
<H3><a name="Javascript_emitter_states">26.5.4 Emitter states</a></H3>
<p>For storing information during the AST traversal the emitter provides a <code>JSEmitterState</code> with different slots to store data representing the scopes global, class, function, and variable.</p>
<div class="code">
<pre>
class JSEmitterState {
public:
JSEmitterState();
~JSEmitterState();
DOH *global();
DOH *global(const char* key, DOH *initial = 0);
DOH *clazz(bool reset = false);
DOH *clazz(const char* key, DOH *initial = 0);
DOH *function(bool reset = false);
DOH *function(const char* key, DOH *initial = 0);
DOH *variable(bool reset = false);
DOH *variable(const char* key, DOH *initial = 0);
static int IsSet(DOH *val);
...
};</pre>
</div>
<p>When entering a scope, such as in <code>enterClass</code>, the corresponding state is reset and new data is stored:</p>
<div class="code">
<pre>
state.clazz(RESET);
state.clazz(NAME, Getattr(n, "sym:name"));</pre>
</div>
<p>State information can be retrieved using <code>state.clazz(NAME)</code> or with <code>Getattr</code> on <code>state.clazz()</code> which actually returns a <code>Hash</code> instance.</p>
<H3><a name="Javascript_jsc_exceptions">26.5.5 Handling Exceptions in JavascriptCore</a></H3>
<p>Applications with an embedded JavascriptCore should be able to present detailed exception messages that occur in the Javascript engine. Below is an example derived from code provided by Brian Barnes on how these exception details can be extracted.</p>
<div class="code">
<pre>
void script_exception_to_string(JSContextRef js_context,JSValueRef exception_value_ref,char* return_error_string, int return_error_string_max_length)
{
JSObjectRef exception_object;
JSValueRef value_ref;
JSStringRef jsstring_property_name = NULL;
JSValueRef temporary_exception = NULL;
JSStringRef js_return_string = NULL;
size_t bytes_needed;
char* c_result_string = NULL;
exception_object = JSValueToObject(js_context, exception_value_ref, NULL);
/* source url */
strcpy(return_error_string,&quot;[&quot;);
jsstring_property_name = JSStringCreateWithUTF8CString(&quot;sourceURL&quot;);
value_ref = JSObjectGetProperty(js_context, exception_object, jsstring_property_name, &amp;temporary_exception);
JSStringRelease(jsstring_property_name);
js_return_string = JSValueToStringCopy(js_context, value_ref, NULL);
bytes_needed = JSStringGetMaximumUTF8CStringSize(js_return_string);
c_result_string = (char*)calloc(bytes_needed, sizeof(char));
JSStringGetUTF8CString(js_return_string, c_result_string, bytes_needed);
JSStringRelease(js_return_string);
strncat(return_error_string, c_result_string, return_error_string_max_length-1);
free(c_result_string);
strncat(return_error_string, &quot;:&quot;, return_error_string_max_length-1);
/* line number */
jsstring_property_name = JSStringCreateWithUTF8CString(&quot;line&quot;);
value_ref = JSObjectGetProperty(js_context, exception_object, jsstring_property_name, &amp;temporary_exception);
JSStringRelease(jsstring_property_name);
js_return_string = JSValueToStringCopy(js_context, value_ref, NULL);
bytes_needed = JSStringGetMaximumUTF8CStringSize(js_return_string);
c_result_string = (char*)calloc(bytes_needed, sizeof(char));
JSStringGetUTF8CString(js_return_string, c_result_string, bytes_needed);
JSStringRelease(js_return_string);
strncat(return_error_string, c_result_string, return_error_string_max_length-1);
free(c_result_string);
strncat(return_error_string, &quot;]&quot;, return_error_string_max_length-1);
/* error message */
jsstring_property_name = JSStringCreateWithUTF8CString(&quot;message&quot;);
value_ref = JSObjectGetProperty(js_context, exception_object, jsstring_property_name, &amp;temporary_exception);
JSStringRelease(jsstring_property_name);
if(NULL == value_ref)
{
strncat(return_error_string, &quot;Unknown Error&quot;, return_error_string_max_length-1);
}
else
{
js_return_string = JSValueToStringCopy(js_context, value_ref, NULL);
bytes_needed = JSStringGetMaximumUTF8CStringSize(js_return_string);
c_result_string = (char*)calloc(bytes_needed, sizeof(char));
JSStringGetUTF8CString(js_return_string, c_result_string, bytes_needed);
JSStringRelease(js_return_string);
strncat(return_error_string, c_result_string, return_error_string_max_length-1);
free(c_result_string);
}
}</pre>
</div>
<p>It would be used in the following way:</p>
<div class="code">
<pre>
if(js_exception)
{
char return_error_string[256];
script_exception_to_string(js_context, js_exception, return_error_string, 256);
printf("Compile error is %s", return_error_string);
}</pre>
</div>
</body>
</html>

144
Doc/Manual/Library.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG Library</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Library"></a>8 SWIG library</H1>
<H1><a name="Library">9 SWIG library</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -31,6 +32,7 @@
<li><a href="#Library_std_vector">std::vector</a>
<li><a href="#Library_stl_exceptions">STL exceptions</a>
<li><a href="#Library_std_shared_ptr">shared_ptr smart pointer</a>
<li><a href="#Library_std_auto_ptr">auto_ptr smart pointer</a>
</ul>
<li><a href="#Library_nn16">Utility Libraries</a>
<ul>
@ -58,7 +60,7 @@ Alternative libraries provide similar functionality. Please read this chapter
carefully if you used the old libraries.
</p>
<H2><a name="Library_nn2"></a>8.1 The %include directive and library search path</H2>
<H2><a name="Library_nn2">9.1 The %include directive and library search path</a></H2>
<p>
@ -66,18 +68,19 @@ Library files are included using the <tt>%include</tt> directive.
When searching for files, directories are searched in the following order:
</p>
<ul>
<ol>
<li>The current directory
<li>Directories specified with the <tt>-I</tt> command line option
<li>.<tt>/swig_lib</tt>
<li>SWIG library install location as reported by <tt>swig -swiglib</tt>, for example <tt>/usr/local/share/swig/1.3.30</tt>
<li>On Windows, a directory <tt>Lib</tt> relative to the location of <tt>swig.exe</tt> is also searched.
</ul>
</ol>
<p>
Within each directory, SWIG first looks for a subdirectory corresponding to a target language (e.g., <tt>python</tt>,
<tt>tcl</tt>, etc.). If found, SWIG will search the language specific directory first. This allows
for language-specific implementations of library files.
Within directories mentioned in points 3-5, SWIG first looks for a subdirectory
corresponding to a target language (e.g., <tt>python</tt>, <tt>tcl</tt>, etc.).
If found, SWIG will search the language specific directory first. This allows
for language-specific implementations of library files.
</p>
<p>
@ -89,7 +92,7 @@ Set the environment variable to hold an alternative library directory.
The directories that are searched are displayed when using <tt>-verbose</tt> commandline option.
</p>
<H2><a name="Library_nn3"></a>8.2 C Arrays and Pointers</H2>
<H2><a name="Library_nn3">9.2 C Arrays and Pointers</a></H2>
<p>
@ -101,7 +104,7 @@ pointers as class-like objects. Since these functions provide direct access to
memory, their use is potentially unsafe and you should exercise caution.
</p>
<H3><a name="Library_nn4"></a>8.2.1 cpointer.i</H3>
<H3><a name="Library_nn4">9.2.1 cpointer.i</a></H3>
<p>
@ -317,7 +320,7 @@ In this example, the function <tt>int_to_uint()</tt> would be used to cast type
<b>Note:</b> When working with simple pointers, typemaps can often be used to provide more seamless operation.
</p>
<H3><a name="Library_carrays"></a>8.2.2 carrays.i</H3>
<H3><a name="Library_carrays">9.2.2 carrays.i</a></H3>
<p>
@ -495,7 +498,7 @@ you should consider using a special array object rather than a bare pointer.
used with types of <tt>char</tt> or <tt>char *</tt>.
</p>
<H3><a name="Library_nn6"></a>8.2.3 cmalloc.i</H3>
<H3><a name="Library_nn6">9.2.3 cmalloc.i</a></H3>
<p>
@ -656,7 +659,7 @@ Now, in a script:
</pre>
</div>
<H3><a name="Library_nn7"></a>8.2.4 cdata.i</H3>
<H3><a name="Library_nn7">9.2.4 cdata.i</a></H3>
<p>
@ -758,7 +761,7 @@ char *cdata_<em>name</em>(type* ptr, int nitems)
Clearly they are unsafe.
</p>
<H2><a name="Library_nn8"></a>8.3 C String Handling</H2>
<H2><a name="Library_nn8">9.3 C String Handling</a></H2>
<p>
@ -778,7 +781,7 @@ morality. The modules in this section provide basic functionality
for manipulating raw C strings.
</p>
<H3><a name="Library_nn9"></a>8.3.1 Default string handling</H3>
<H3><a name="Library_nn9">9.3.1 Default string handling</a></H3>
<p>
@ -819,7 +822,7 @@ interpreter and lead to a crash). Furthermore, the default behavior does
not work well with binary data. Instead, strings are assumed to be NULL-terminated.
</p>
<H3><a name="Library_nn10"></a>8.3.2 Passing binary data</H3>
<H3><a name="Library_nn10">9.3.2 Passing binary data</a></H3>
<p>
@ -861,7 +864,7 @@ In the wrapper function, the passed string will be expanded to a pointer and len
The <tt>(char *STRING, int LENGTH)</tt> multi-argument typemap is also available in addition to <tt>(char *STRING, size_t LENGTH)</tt>.
</p>
<H3><a name="Library_nn11"></a>8.3.3 Using %newobject to release memory</H3>
<H3><a name="Library_nn11">9.3.3 Using %newobject to release memory</a></H3>
<p>
@ -902,7 +905,7 @@ however, you may need to provide your own "newfree" typemap for other types.
See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more details.
</p>
<H3><a name="Library_nn12"></a>8.3.4 cstring.i</H3>
<H3><a name="Library_nn12">9.3.4 cstring.i</a></H3>
<p>
@ -1362,7 +1365,7 @@ structure or class instead.
</li>
</ul>
<H2><a name="Library_stl_cpp_library"></a>8.4 STL/C++ Library</H2>
<H2><a name="Library_stl_cpp_library">9.4 STL/C++ Library</a></H2>
<p>
@ -1382,6 +1385,7 @@ The following table shows which C++ classes are supported and the equivalent SWI
<td><b>SWIG Interface library file</b></td>
</tr>
<tr> <td>std::auto_ptr</td> <td>memory</td> <td>std_auto_ptr.i</td> </tr>
<tr> <td>std::deque</td> <td>deque</td> <td>std_deque.i</td> </tr>
<tr> <td>std::list</td> <td>list</td> <td>std_list.i</td> </tr>
<tr> <td>std::map</td> <td>map</td> <td>std_map.i</td> </tr>
@ -1389,7 +1393,8 @@ The following table shows which C++ classes are supported and the equivalent SWI
<tr> <td>std::set</td> <td>set</td> <td>std_set.i</td> </tr>
<tr> <td>std::string</td> <td>string</td> <td>std_string.i</td> </tr>
<tr> <td>std::vector</td> <td>vector</td> <td>std_vector.i</td> </tr>
<tr> <td>std::shared_ptr</td> <td>shared_ptr</td> <td>std_shared_ptr.i</td> </tr>
<tr> <td>std::array</td> <td>array (C++11)</td> <td>std_array.i</td> </tr>
<tr> <td>std::shared_ptr</td> <td>shared_ptr (C++11)</td> <td>std_shared_ptr.i</td> </tr>
</table>
@ -1399,7 +1404,7 @@ Please look for the library files in the appropriate language library directory.
</p>
<H3><a name="Library_std_string"></a>8.4.1 std::string</H3>
<H3><a name="Library_std_string">9.4.1 std::string</a></H3>
<p>
@ -1483,7 +1488,7 @@ void foo(string s, const String &amp;t); // std_string typemaps still applie
</pre>
</div>
<H3><a name="Library_std_vector"></a>8.4.2 std::vector</H3>
<H3><a name="Library_std_vector">9.4.2 std::vector</a></H3>
<p>
@ -1662,7 +1667,7 @@ if you want to make their head explode.
details and the public API exposed to the interpreter vary.
</p>
<H3><a name="Library_stl_exceptions"></a>8.4.3 STL exceptions</H3>
<H3><a name="Library_stl_exceptions">9.4.3 STL exceptions</a></H3>
<p>
@ -1712,13 +1717,28 @@ The <tt>%exception</tt> directive can be used by placing the following code befo
Any thrown STL exceptions will then be gracefully handled instead of causing a crash.
</p>
<H3><a name="Library_std_shared_ptr"></a>8.4.4 shared_ptr smart pointer</H3>
<H3><a name="Library_std_shared_ptr">9.4.4 shared_ptr smart pointer</a></H3>
<p>
Some target languages have support for handling the widely used <tt>boost::shared_ptr</tt> smart pointer.
This smart pointer is also available as <tt>std::tr1::shared_ptr</tt> before it becomes fully standardized as <tt>std::shared_ptr</tt>.
The <tt>boost_shared_ptr.i</tt> library provides support for <tt>boost::shared_ptr</tt> and <tt>std_shared_ptr.i</tt> provides support for <tt>std::shared_ptr</tt>, but if the following macro is defined as shown, it can be used for <tt>std::tr1::shared_ptr</tt>:
Some target languages have support for handling the shared_ptr reference counted smart pointer.
This smart pointer is available in the standard C++11 library as <tt>std::shared_ptr</tt>.
It was also in TR1 as <tt>std::tr1::shared_ptr</tt> before it was fully standardized.
Support for the widely used <tt>boost::shared_ptr</tt> is also available.
</p>
<p>
In order to use <tt>std::shared_ptr</tt>, the <tt>std_shared_ptr.i</tt> library file should be included:
</p>
<div class="code">
<pre>
%include &lt;std_shared_ptr.i&gt;
</pre>
</div>
<p>
The pre-standard <tt>std::tr1::shared_ptr</tt> can be used by including the following macro before including the <tt>std_shared_ptr.i</tt> library file:
</p>
<div class="code">
@ -1728,6 +1748,16 @@ The <tt>boost_shared_ptr.i</tt> library provides support for <tt>boost::shared_p
</pre>
</div>
<p>
In order to use <tt>boost::shared_ptr</tt>, the <tt>boost_shared_ptr.i</tt> library file should be included:
</p>
<div class="code">
<pre>
%include &lt;boost_shared_ptr.i&gt;
</pre>
</div>
<p>
You can only use one of these variants of shared_ptr in your interface file at a time.
and all three variants must be used in conjunction with the <tt>%shared_ptr(T)</tt> macro,
@ -1871,10 +1901,66 @@ Adding the missing <tt>%shared_ptr</tt> macros will fix this:
</pre>
</div>
<H2><a name="Library_nn16"></a>8.5 Utility Libraries</H2>
<p>
<b>Note:</b> There is somewhat limited support for <tt>%shared_ptr</tt> and the director feature
and the degress of success varies among the different target languages.
Please help to improve this support by providing patches with improvements.
</p>
<H3><a name="Library_nn17"></a>8.5.1 exception.i</H3>
<H3><a name="Library_std_auto_ptr">9.4.5 auto_ptr smart pointer</a></H3>
<p>
While <tt>std::auto_ptr</tt> is deprecated in C++11, some existing code may
still be using it, so SWIG provides limited support for this class:
<tt>std_auto_ptr.i</tt> defines the typemaps which apply to the functions
returning objects of this type. Any other use of <tt>std_auto_ptr.i</tt> is not
directly supported.
</p>
<p>
A typical example of use would be
</p>
<div class="code">
<pre>
%include &lt;std_auto_ptr.i&gt;
%auto_ptr(Klass)
%inline %{
class Klass {
public:
// Factory function creating objects of this class:
static std::auto_ptr&lt;Klass&gt; Create(int value) {
return std::auto_ptr&lt;Klass&gt;(new Klass(value));
}
int getValue() const { return m_value; }
private:
DerivedIntValue(int value) : m_value(value) {}
int m_value;
};
%}
</pre>
</div>
<p>
The returned objects can be used naturally from the target language, e.g. from
C#:
</p>
<div class="targetlang">
<pre>
Klass k = Klass.Create(17);
int value = k.getValue();
</pre>
</div>
<H2><a name="Library_nn16">9.5 Utility Libraries</a></H2>
<H3><a name="Library_nn17">9.5.1 exception.i</a></H3>
<p>

128
Doc/Manual/Lisp.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Common Lisp</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Lisp"></a>25 SWIG and Common Lisp</H1>
<H1><a name="Lisp">27 SWIG and Common Lisp</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -41,7 +42,7 @@
Lisp, Common Foreign Function Interface(CFFI), CLisp and UFFI
foreign function interfaces.
</p>
<H2><a name="Lisp_nn2"></a>25.1 Allegro Common Lisp</H2>
<H2><a name="Lisp_nn2">27.1 Allegro Common Lisp</a></H2>
<p>
@ -50,7 +51,7 @@
<a href="Allegrocl.html#Allegrocl">here</a>
</p>
<H2><a name="Lisp_nn3"></a>25.2 Common Foreign Function Interface(CFFI)</H2>
<H2><a name="Lisp_nn3">27.2 Common Foreign Function Interface(CFFI)</a></H2>
<p>
@ -77,7 +78,7 @@ swig -cffi -module <i>module-name</i> <i>file-name</i>
files and the various things which you can do with them.
</p>
<H3><a name="Lisp_nn4"></a>25.2.1 Additional Commandline Options </H3>
<H3><a name="Lisp_nn4">27.2.1 Additional Commandline Options </a></H3>
<p>
@ -118,11 +119,11 @@ swig -cffi -help
</table>
<H3><a name="Lisp_nn5"></a>25.2.2 Generating CFFI bindings</H3>
<H3><a name="Lisp_nn5">27.2.2 Generating CFFI bindings</a></H3>
As we mentioned earlier the ideal way to use SWIG is to use interface
files. To illustrate the use of it, lets assume that we have a
files. To illustrate the use of it, let's assume that we have a
file named <i>test.h</i> with the following C code:
<div class="code"><pre>
@ -219,19 +220,19 @@ The generated SWIG Code will be:
(cl:defconstant x (cl:ash 5 -1))
(cffi:defcstruct bar
(p :short)
(q :short)
(a :char)
(b :char)
(z :pointer)
(n :pointer))
(p :short)
(q :short)
(a :char)
(b :char)
(z :pointer)
(n :pointer))
(cffi:defcvar ("my_struct" my_struct)
:pointer)
(cffi:defcstruct foo
(a :int)
(b :pointer))
(a :int)
(b :pointer))
(cffi:defcfun ("pointer_func" pointer_func) :int
(ClosureFun :pointer)
@ -247,9 +248,9 @@ The generated SWIG Code will be:
(array :pointer))
(cffi:defcenum color
:RED
:BLUE
:GREEN)
:RED
:BLUE
:GREEN)
</pre></div>
<p>
@ -284,9 +285,11 @@ Let's edit the interface file such that the C type "div_t*" is changed
%feature("export");
%feature("inline") lispsort_double;
%feature("intern_function", "my-lispify") lispsort_double;
%feature("export", package="'some-other-package") lispsort_double;
%rename func123 renamed_cool_func;
%ignore "pointer_func";
%include "test.h"
@ -310,12 +313,13 @@ The feature <i>intern_function</i> ensures that all C names are
lispsort_double;</i>, here we are using an additional feature
which allows us to use our lispify function.
</p>
<p>The <i>export</i> feature allows us to export the symbols. The <i>inline</i>
feature declaims the declared function as inline. The <i>rename</i>
directive allows us to change the name(it is useful when
generating C wrapper code for handling overloaded
functions). The <i>ignore</i> directive ignores a certain
declaration.
<p>The <i>export</i> feature allows us to export the symbols. If
the <i>package</i> argument is given, then the symbol will be exported to
the specified Lisp package. The <i>inline</i> feature declaims the
declared function as inline. The <i>rename</i> directive allows us to
change the name(it is useful when generating C wrapper code for handling
overloaded functions). The <i>ignore</i> directive ignores a certain
declaration.
</p>
<p>There are several other things which are possible, to see some
example of usage of SWIG look at the Lispbuilder and wxCL
@ -332,12 +336,12 @@ The feature <i>intern_function</i> ensures that all C names are
(cl:export '#.(swig-lispify "x" 'constant))
(cffi:defcstruct #.(swig-lispify "bar" 'classname)
(#.(swig-lispify "p" 'slotname) :short)
(#.(swig-lispify "q" 'slotname) :short)
(#.(swig-lispify "a" 'slotname) :char)
(#.(swig-lispify "b" 'slotname) :char)
(#.(swig-lispify "z" 'slotname) :pointer)
(#.(swig-lispify "n" 'slotname) :pointer))
(#.(swig-lispify "p" 'slotname) :short)
(#.(swig-lispify "q" 'slotname) :short)
(#.(swig-lispify "a" 'slotname) :char)
(#.(swig-lispify "b" 'slotname) :char)
(#.(swig-lispify "z" 'slotname) :pointer)
(#.(swig-lispify "n" 'slotname) :pointer))
(cl:export '#.(swig-lispify "bar" 'classname))
@ -359,8 +363,8 @@ The feature <i>intern_function</i> ensures that all C names are
(cl:export '#.(swig-lispify "my_struct" 'variable))
(cffi:defcstruct #.(swig-lispify "foo" 'classname)
(#.(swig-lispify "a" 'slotname) :int)
(#.(swig-lispify "b" 'slotname) :pointer))
(#.(swig-lispify "a" 'slotname) :int)
(#.(swig-lispify "b" 'slotname) :pointer))
(cl:export '#.(swig-lispify "foo" 'classname))
@ -381,18 +385,18 @@ The feature <i>intern_function</i> ensures that all C names are
(n :int)
(array :pointer))
(cl:export '#.(my-lispify "lispsort_double" 'function))
(cl:export '#.(my-lispify "lispsort_double" 'function) 'some-other-package)
(cffi:defcenum #.(swig-lispify "color" 'enumname)
#.(swig-lispify "RED" 'enumvalue :keyword)
#.(swig-lispify "BLUE" 'enumvalue :keyword)
#.(swig-lispify "GREEN" 'enumvalue :keyword))
#.(swig-lispify "RED" 'enumvalue :keyword)
#.(swig-lispify "BLUE" 'enumvalue :keyword)
#.(swig-lispify "GREEN" 'enumvalue :keyword))
(cl:export '#.(swig-lispify "color" 'enumname))
</pre></div>
<H3><a name="Lisp_nn6"></a>25.2.3 Generating CFFI bindings for C++ code</H3>
<H3><a name="Lisp_nn6">27.2.3 Generating CFFI bindings for C++ code</a></H3>
<p>This feature to SWIG (for CFFI) is very new and still far from
@ -568,7 +572,7 @@ If you have any questions, suggestions, patches, etc., related to CFFI
module feel free to contact us on the SWIG mailing list, and
also please add a "[CFFI]" tag in the subject line.
<H3><a name="Lisp_nn7"></a>25.2.4 Inserting user code into generated files</H3>
<H3><a name="Lisp_nn7">27.2.4 Inserting user code into generated files</a></H3>
<p>
@ -608,7 +612,7 @@ Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
</p>
<H2><a name="Lisp_nn8"></a>25.3 CLISP</H2>
<H2><a name="Lisp_nn8">27.3 CLISP</a></H2>
<p>
@ -638,7 +642,7 @@ swig -clisp -module <i>module-name</i> <i>file-name</i>
interface file for the CLISP module. The CLISP module tries to
produce code which is both human readable and easily modifyable.
</p>
<H3><a name="Lisp_nn9"></a>25.3.1 Additional Commandline Options </H3>
<H3><a name="Lisp_nn9">27.3.1 Additional Commandline Options </a></H3>
<p>
@ -658,33 +662,33 @@ swig -clisp -help
<td>-extern-all</td>
<td>If this option is given then clisp definitions for all the functions<br/>
and global variables will be created otherwise only definitions for<br/>
externed functions and variables are created.
externed functions and variables are created.
</td>
</tr>
<tr>
<td>-generate-typedef</td>
<td>If this option is given then def-c-type will be used to generate<br/>
shortcuts according to the typedefs in the input.
shortcuts according to the typedefs in the input.
</td>
</tr>
</table>
<H3><a name="Lisp_nn10"></a>25.3.2 Details on CLISP bindings</H3>
<H3><a name="Lisp_nn10">27.3.2 Details on CLISP bindings</a></H3>
<p>
As mentioned earlier the CLISP bindings generated by SWIG may need
some modifications. The clisp module creates a lisp file with
the same name as the module name. This
lisp file contains a 'defpackage' declaration, with the
package name same as the module name. This package uses the
'common-lisp' and 'ffi' packages. Also, package exports all
the functions, structures and variables for which an ffi
binding was generated.<br/>
After generating the defpackage statement, the clisp module also
sets the default language.
some modifications. The clisp module creates a lisp file with
the same name as the module name. This
lisp file contains a 'defpackage' declaration, with the
package name same as the module name. This package uses the
'common-lisp' and 'ffi' packages. Also, package exports all
the functions, structures and variables for which an ffi
binding was generated.<br/>
After generating the defpackage statement, the clisp module also
sets the default language.
<div class="targetlang"><pre>
(defpackage :test
@ -734,18 +738,18 @@ void test123(float x , double y);
(ffi:def-call-out pointer_func
(:name "pointer_func")
(:arguments (ClosureFun (ffi:c-function (:arguments (arg0 (ffi:c-pointer NIL))
(arg1 (ffi:c-pointer NIL))
(arg2 (ffi:c-pointer NIL)))
(:return-type NIL)))
(y ffi:int))
(arg1 (ffi:c-pointer NIL))
(arg2 (ffi:c-pointer NIL)))
(:return-type NIL)))
(y ffi:int))
(:return-type ffi:int)
(:library +library-name+))
(ffi:def-call-out func123
(:name "func123")
(:arguments (x (ffi:c-pointer div_t))
(z (ffi:c-ptr (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100)))
(y (ffi:c-ptr (ffi:c-ptr (ffi:c-array ffi:int (1000 10))))))
(z (ffi:c-ptr (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100)))
(y (ffi:c-ptr (ffi:c-ptr (ffi:c-array ffi:int (1000 10))))))
(:return-type ffi:int)
(:library +library-name+))
@ -753,14 +757,14 @@ void test123(float x , double y);
(ffi:def-call-out lispsort_double
(:name "lispsort_double")
(:arguments (n ffi:int)
(array (ffi:c-ptr DOUBLE-FLOAT)))
(array (ffi:c-ptr DOUBLE-FLOAT)))
(:return-type NIL)
(:library +library-name+))
(ffi:def-call-out test123
(:name "test")
(:arguments (x SINGLE-FLOAT)
(y DOUBLE-FLOAT))
(y DOUBLE-FLOAT))
(:return-type NIL)
(:library +library-name+))
@ -795,7 +799,7 @@ struct bar {
</pre></div>
<H2><a name="Lisp_nn11"></a>25.4 UFFI </H2>
<H2><a name="Lisp_nn11">27.4 UFFI </a></H2>
</body>

396
Doc/Manual/Lua.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Lua</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Lua"></a>26 SWIG and Lua</H1>
<H1><a name="Lua">28 SWIG and Lua</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -24,8 +25,11 @@
<li><a href="#Lua_nn9">Functions</a>
<li><a href="#Lua_nn10">Global variables</a>
<li><a href="#Lua_nn11">Constants and enums</a>
<ul>
<li><a href="#Lua_nn13">Constants/enums and classes/structures</a>
</ul>
<li><a href="#Lua_nn12">Pointers</a>
<li><a href="#Lua_nn13">Structures</a>
<li><a href="#Lua_structures">Structures</a>
<li><a href="#Lua_nn14">C++ classes</a>
<li><a href="#Lua_nn15">C++ inheritance</a>
<li><a href="#Lua_nn16">Pointers, references, values, and arrays</a>
@ -36,17 +40,23 @@
<li><a href="#Lua_nn21">C++ templates</a>
<li><a href="#Lua_nn22">C++ Smart Pointers</a>
<li><a href="#Lua_nn23">C++ Exceptions</a>
<li><a href="#Lua_namespaces">Namespaces </a>
<ul>
<li><a href="#Lua_nn27">Compatibility Note </a>
<li><a href="#Lua_nn29">Names </a>
<li><a href="#Lua_nn30">Inheritance </a>
</ul>
</ul>
<li><a href="#Lua_nn24">Typemaps</a>
<ul>
<li><a href="#Lua_nn25">What is a typemap?</a>
<li><a href="#Lua_nn26">Using typemaps</a>
<li><a href="#Lua_nn27">Typemaps and arrays</a>
<li><a href="#Lua_nn28">Typemaps and pointer-pointer functions</a>
<li><a href="#Lua_typemap_arrays">Typemaps and arrays</a>
<li><a href="#Lua_typemaps_ptr_ptr_functions">Typemaps and pointer-pointer functions</a>
</ul>
<li><a href="#Lua_nn29">Writing typemaps</a>
<li><a href="#Lua_writing_typemaps">Writing typemaps</a>
<ul>
<li><a href="#Lua_nn30">Typemaps you can write</a>
<li><a href="#Lua_typemaps_write">Typemaps you can write</a>
<li><a href="#Lua_nn31">SWIG's Lua-C API</a>
</ul>
<li><a href="#Lua_nn32">Customization of your Bindings</a>
@ -73,14 +83,14 @@ Lua is an extension programming language designed to support general procedural
eLua stands for Embedded Lua (can be thought of as a flavor of Lua) and offers the full implementation of the Lua programming language to the embedded world, extending it with specific features for efficient and portable software embedded development. eLua runs on smaller devices like microcontrollers and provides the full features of the regular Lua desktop version. More information on eLua can be found here: <a href="http://www.eluaproject.net">http://www.eluaproject.net</a>
</p>
<H2><a name="Lua_nn2"></a>26.1 Preliminaries</H2>
<H2><a name="Lua_nn2">28.1 Preliminaries</a></H2>
<p>
The current SWIG implementation is designed to work with Lua 5.0.x, 5.1.x and 5.2.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. It is possible to either static link or dynamic link a Lua module into the interpreter (normally Lua static links its libraries, as dynamic linking is not available on all platforms). SWIG also supports eLua and works with eLua 0.8. SWIG generated code for eLua has been tested on Stellaris ARM Cortex-M3 LM3S and Infineon TriCore.
The current SWIG implementation is designed to work with Lua 5.0.x, 5.1.x and 5.2.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. It is possible to either static link or dynamic link a Lua module into the interpreter (normally Lua static links its libraries, as dynamic linking is not available on all platforms). SWIG also has support for eLua starting from eLua 0.8. Due to substantial changes between SWIG 2.x and SWIG 3.0 and unavailability of testing platform, eLua status was downgraded to 'experimental'.
</p>
<H2><a name="Lua_nn3"></a>26.2 Running SWIG</H2>
<H2><a name="Lua_nn3">28.2 Running SWIG</a></H2>
<p>
@ -128,7 +138,7 @@ $ swig -lua -eluac example.i
The <tt>-elua</tt> option puts all the C function wrappers and variable get/set wrappers in rotables. It also generates a metatable which will control the access to these variables from eLua. It also offers a significant amount of module size compression. On the other hand, the <tt>-eluac</tt> option puts all the wrappers in a single rotable. With this option, no matter how huge the module, it will consume no additional microcontroller SRAM (crass compression). There is a catch though: Metatables are not generated with <tt>-eluac</tt>. To access any value from eLua, one must directly call the wrapper function associated with that value.
</p>
<H3><a name="Lua_commandline"></a>26.2.1 Additional command line options</H3>
<H3><a name="Lua_commandline">28.2.1 Additional command line options</a></H3>
<p>
@ -159,9 +169,17 @@ swig -lua -help
<td>Do not register the module name as a global variable but return the module table from calls to require.</td>
</tr>
<tr>
<td>-no-old-metatable-bindings</td>
<td>Disable backward compatibility: old-style binding names generations and a few other things. Explanations are included in appropriate later sections.</td>
</tr>
<tr>
<td>-squash-bases</td>
<td>Squashes symbols from all inheritance tree of a given class into itself. Emulates pre-SWIG3.0 inheritance. Insignificantly speeds things up, but increases memory consumption.</td>
</tr>
</table>
<H3><a name="Lua_nn4"></a>26.2.2 Compiling and Linking and Interpreter</H3>
<H3><a name="Lua_nn4">28.2.2 Compiling and Linking and Interpreter</a></H3>
<p>
@ -184,8 +202,8 @@ int main(int argc,char* argv[])
return 0;
}
L=lua_open();
luaopen_base(L); // load basic libs (eg. print)
luaopen_example(L); // load the wrapped module
luaopen_base(L); // load basic libs (eg. print)
luaopen_example(L); // load the wrapped module
if (luaL_loadfile(L,argv[1])==0) // load and run the file
lua_pcall(L,0,0,0);
else
@ -232,16 +250,16 @@ LUALIB_API int ( luaopen_mod )(lua_State *L );
More information on building and configuring eLua can be found here: <a href="http://www.eluaproject.net/doc/v0.8/en_building.html">http://www.eluaproject.net/doc/v0.8/en_building.html</a>
</p>
<H3><a name="Lua_nn5"></a>26.2.3 Compiling a dynamic module</H3>
<H3><a name="Lua_nn5">28.2.3 Compiling a dynamic module</a></H3>
<p>
Most, but not all platforms support the dynamic loading of modules (Windows &amp; Linux do). Refer to the Lua manual to determine if your platform supports it. For compiling a dynamically loaded module the same wrapper can be used. The commands will be something like this:
Most, but not all platforms support the dynamic loading of modules (Windows &amp; Linux do). Refer to the Lua manual to determine if your platform supports it. For compiling a dynamically loaded module the same wrapper can be used. Assuming you have code you need to link to in a file called <tt>example.c</tt>, the commands will be something like this:
</p>
<div class="shell"><pre>
$ swig -lua example.i -o example_wrap.c
$ gcc -I/usr/include/lua -c example_wrap.c -o example_wrap.o
$ gcc -c example.c -o example.o
$ gcc -fPIC -I/usr/include/lua -c example_wrap.c -o example_wrap.o
$ gcc -fPIC -c example.c -o example.o
$ gcc -shared -I/usr/include/lua -L/usr/lib/lua example_wrap.o example.o -o example.so
</pre></div>
<p>
@ -300,7 +318,7 @@ Is quite obvious (Go back and consult the Lua documents on how to enable loadlib
<H3><a name="Lua_nn6"></a>26.2.4 Using your module</H3>
<H3><a name="Lua_nn6">28.2.4 Using your module</a></H3>
<p>
@ -318,19 +336,19 @@ $ ./my_lua
&gt;
</pre></div>
<H2><a name="Lua_nn7"></a>26.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Lua_nn7">28.3 A tour of basic C/C++ wrapping</a></H2>
<p>
By default, SWIG tries to build a very natural Lua interface to your C/C++ code. This section briefly covers the essential aspects of this wrapping.
</p>
<H3><a name="Lua_nn8"></a>26.3.1 Modules</H3>
<H3><a name="Lua_nn8">28.3.1 Modules</a></H3>
<p>
The SWIG module directive specifies the name of the Lua module. If you specify `module example', then everything is wrapped into a Lua table 'example' containing all the functions and variables. When choosing a module name, make sure you don't use the same name as a built-in Lua command or standard module name.
</p>
<H3><a name="Lua_nn9"></a>26.3.2 Functions</H3>
<H3><a name="Lua_nn9">28.3.2 Functions</a></H3>
<p>
@ -349,7 +367,10 @@ creates a built-in function <tt>example.fact(n)</tt> that works exactly like you
&gt;
</pre></div>
<p>
To avoid name collisions, SWIG create a Lua table which it keeps all the functions and global variables in. It is possible to copy the functions out of this and into the global environment with the following code. This can easily overwrite existing functions, so this must be used with care.
To avoid name collisions, SWIG create a Lua table which keeps all the functions, constants, classes and global variables in.
It is possible to copy the functions, constants and classes (but not variables) out of this and into the global environment with the following code.
This can easily overwrite existing functions, so this must be used with care.
This option is considered deprecated and will be removed in the near future.
</p>
<div class="targetlang"><pre>
&gt; for k,v in pairs(example) do _G[k]=v end
@ -368,7 +389,7 @@ It is also possible to rename the module with an assignment.
24
</pre></div>
<H3><a name="Lua_nn10"></a>26.3.3 Global variables</H3>
<H3><a name="Lua_nn10">28.3.3 Global variables</a></H3>
<p>
@ -456,7 +477,7 @@ If you have used the <tt>-eluac</tt> option for your eLua module, you will have
In general, functions of the form <tt>"variable_get()"</tt> and <tt>"variable_set()"</tt> are automatically generated by SWIG for use with <tt>-eluac</tt>.
</p>
<H3><a name="Lua_nn11"></a>26.3.4 Constants and enums</H3>
<H3><a name="Lua_nn11">28.3.4 Constants and enums</a></H3>
<p>
@ -490,7 +511,64 @@ If you're using eLua and have used <tt>-elua</tt> or <tt>-eluac</tt> to generate
&gt; print(example.const.SCONST)
Hello World
</pre></div>
<H3><a name="Lua_nn12"></a>26.3.5 Pointers</H3>
<H4><a name="Lua_nn13">28.3.4.1 Constants/enums and classes/structures</a></H4>
<p>
Enums are exported into a class table. For example, given some enums:
</p>
<div class="code"><pre>%module example
enum Days { SUNDAY = 0, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY };
struct Test {
enum { TEST1 = 10, TEST2 = 20 };
#ifdef __cplusplus // There are no static members in C
static const int ICONST = 12;
#endif
};
</pre></div>
<p>
There is a slight difference in behaviour wrapping C and C++ code due to the different scoping rules of C and C++.
The wrapped C++ code is used as follows from Lua code:
</p>
<div class="targetlang"><pre>
&gt; print(example.SUNDAY)
0
&gt; print(example.Test.TEST1)
10
&gt; print(example.Test.ICONST)
12
</pre></div>
<p>Enums within a C struct are in the global namespace and are used as follows from Lua</p>
<div class="targetlang"><pre>
&gt; print(example.SUNDAY)
0
&gt; -- See the difference here
&gt; print(example.TEST1)
10
</pre></div>
<p>
<b>Compatibility Note:</b> Versions of SWIG prior to SWIG-3.0.0 did not generate the class table members above.
There is no change in the C wrappers, but
the following code was the only way to access these constants/enums when wrapping C++ member constants:
</p>
<div class="targetlang"><pre>
&gt; print(example.Test_TEST1)
10
&gt; print(example.Test_ICONST)
12
</pre></div>
<p>
The old-style bindings are still generated in addition to the new ones.
If the <tt>-no-old-metatable-bindings</tt> option is used, then these old-style bindings are not generated.
</p>
<p>
It is worth mentioning, that <tt>example.Test.TEST1</tt> and <tt>example.Test_TEST1</tt> are different entities and changing one does not change the other.
Given the fact that these are constantes and they are not supposed to be changed, it is up to you to avoid such issues.
</p>
<H3><a name="Lua_nn12">28.3.5 Pointers</a></H3>
<p>
@ -528,7 +606,7 @@ Lua enforces the integrity of its userdata, so it is virtually impossible to cor
nil
</pre></div>
<H3><a name="Lua_nn13"></a>26.3.6 Structures</H3>
<H3><a name="Lua_structures">28.3.6 Structures</a></H3>
<p>
@ -551,7 +629,7 @@ is used as follows:
</pre></div>
<p>
Similar access is provided for unions and the data members of C++ classes.<br>
C structures are created using a function <tt>new_Point()</tt>, but for C++ classes are created using just the name <tt>Point()</tt>.
C structures can be created using a function <tt>new_Point()</tt>, and both C structures and C++ classes can be created using just the name <tt>Point()</tt>.
</p>
<p>
If you print out the value of p in the above example, you will see something like this:
@ -632,7 +710,7 @@ For eLua with the <tt>-eluac</tt> option, structure manipulation has to be perfo
In general, functions of the form <tt>"new_struct()"</tt>, <tt>"struct_member_get()"</tt>, <tt>"struct_member_set()"</tt> and <tt>"free_struct()"</tt> are automatically generated by SWIG for each structure defined in C. (Please note: This doesn't apply for modules generated with the <tt>-elua</tt> option)
</p>
<H3><a name="Lua_nn14"></a>26.3.7 C++ classes</H3>
<H3><a name="Lua_nn14">28.3.7 C++ classes</a></H3>
<p>
@ -676,12 +754,12 @@ public:
};
</pre></div>
<p>
In Lua, the static members can be accessed as follows:
In Lua, C++ static members can be accessed as follows:
</p>
<div class="code"><pre>
&gt; example.Spam_foo() -- calling Spam::foo()
&gt; a=example.Spam_bar -- reading Spam::bar
&gt; example.Spam_bar=b -- writing to Spam::bar
&gt; example.Spam.foo() -- calling Spam::foo()
&gt; a=example.Spam.bar -- reading Spam::bar
&gt; example.Spam.bar=b -- writing to Spam::bar
</pre></div>
<p>
It is not (currently) possible to access static members of an instance:
@ -692,7 +770,22 @@ It is not (currently) possible to access static members of an instance:
-- does NOT work
</pre></div>
<H3><a name="Lua_nn15"></a>26.3.8 C++ inheritance</H3>
<p>
<b>Compatibility Note:</b> In versions prior to SWIG-3.0.0 only the following names would work:
</p>
<div class="code"><pre>
&gt; example.Spam_foo() -- calling Spam::foo()
&gt; a=example.Spam_bar -- reading Spam::bar
&gt; example.Spam_bar=b -- writing to Spam::bar
</pre></div>
<p>
Both style names are generated by default now.
However, if the <tt>-no-old-metatable-bindings</tt> option is used, then the backward compatible names are not generated in addition to ordinary ones.
</p>
<H3><a name="Lua_nn15">28.3.8 C++ inheritance</a></H3>
<p>
@ -717,7 +810,7 @@ then the function <tt>spam()</tt> accepts a Foo pointer or a pointer to any clas
<p>
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Lua_nn16"></a>26.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Lua_nn16">28.3.9 Pointers, references, values, and arrays</a></H3>
<p>
@ -748,7 +841,7 @@ Foo spam7();
<p>
then all three functions will return a pointer to some Foo object. Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Lua will release this memory when the return value is garbage collected). The other two are pointers which are assumed to be managed by the C code and so will not be garbage collected.
</p>
<H3><a name="Lua_nn17"></a>26.3.10 C++ overloaded functions</H3>
<H3><a name="Lua_nn17">28.3.10 C++ overloaded functions</a></H3>
<p>
@ -799,7 +892,7 @@ void spam(short);
<p>
or
</p>
<DIV CLASS="CODE"><PRE>VOID FOO(bAR *B);
<div class="code"><pre>void foo(Bar *b);
void foo(Bar &amp;b);
</pre></div>
<p>
@ -834,7 +927,7 @@ Please refer to the "SWIG and C++" chapter for more information about overloadin
<p>
Dealing with the Lua coercion mechanism, the priority is roughly (integers, floats, strings, userdata). But it is better to rename the functions rather than rely upon the ordering.
</p>
<H3><a name="Lua_nn18"></a>26.3.11 C++ operators</H3>
<H3><a name="Lua_nn18">28.3.11 C++ operators</a></H3>
<p>
@ -898,10 +991,10 @@ The current list of operators which can be overloaded (and the alternative funct
<li><tt>__sub__</tt> operator-
<li><tt>__mul__</tt> operator *
<li><tt>__div__</tt> operator/
<li><tt>__neg__</tt> unary minus
<li><tt>__unm__</tt> unary minus
<li><tt>__call__</tt> operator<tt>()</tt> (often used in functor classes)
<li><tt>__pow__</tt> the exponential fn (no C++ equivalent, Lua uses <tt>^</tt>)
<li><tt>__concat__</tt> the concatenation operator (SWIG maps C++'s <tt>~</tt> to Lua's <tt>..</tt>)
<li><tt>__concat__</tt> the concatenation operator (Lua's <tt>..</tt>)
<li><tt>__eq__</tt> operator<tt>==</tt>
<li><tt>__lt__</tt> operator<tt>&lt;</tt>
<li><tt>__le__</tt> operator<tt>&lt;=</tt>
@ -945,8 +1038,30 @@ It is also possible to overload the operator<tt>[]</tt>, but currently this cann
void __setitem__(int i,double d); // i is the index, d is the data
};
</pre></div>
<H3><a name="Lua_nn19"></a>26.3.12 Class extension with %extend</H3>
<p>
C++ operators are mapped to Lua predefined metafunctions. Class inherits from its bases the following list of metafunctions ( thus inheriting the folloging
operators and pseudo-operators):</p>
<ul>
<li><tt>__add__</tt>
<li><tt>__sub__</tt>
<li><tt>__mul__</tt>
<li><tt>__div__</tt>
<li><tt>__unm__</tt>
<li><tt>__mod__</tt>
<li><tt>__call__</tt>
<li><tt>__pow__</tt>
<li><tt>__concat__</tt>
<li><tt>__eq__</tt>
<li><tt>__lt__</tt>
<li><tt>__le__</tt>
<li><tt>__len__</tt>
<li><tt>__getitem__</tt>
<li><tt>__setitem__</tt>
<li><tt>__tostring</tt> used internally by Lua for tostring() function. __str__ is mapped to this function
</ul>
<p>No other lua metafunction is inherited. For example, __gc is not inherited and must be redefined in every class. <tt>__tostring</tt> is subject to a special handling. If absent in class and in class bases, a default one will be provided by SWIG.
</p>
<H3><a name="Lua_nn19">28.3.12 Class extension with %extend</a></H3>
<p>
@ -981,7 +1096,7 @@ Now we extend it with some new code
return tmp;
}
bool operator==(const Complex&amp; c)
{ return ($self-&gt;re()==c.re() &amp;&amp; $self-&gt;im()==c.im();}
{ return ($self-&gt;re()==c.re() &amp;&amp; $self-&gt;im()==c.im());}
};
</pre></div>
<p>
@ -1002,7 +1117,7 @@ true
Extend works with both C and C++ code, on classes and structs. It does not modify the underlying object in any way---the extensions only show up in the Lua interface. The only item to take note of is the code has to use the '$self' instead of 'this', and that you cannot access protected/private members of the code (as you are not officially part of the class).
</p>
<H3><a name="Lua_nn20"></a>26.3.13 Using %newobject to release memory</H3>
<H3><a name="Lua_nn20">28.3.13 Using %newobject to release memory</a></H3>
<p> If you have a function that allocates memory like this,</p>
@ -1026,7 +1141,7 @@ char *foo();
</div>
<p> This will release the allocated memory.</p>
<H3><a name="Lua_nn21"></a>26.3.14 C++ templates</H3>
<H3><a name="Lua_nn21">28.3.14 C++ templates</a></H3>
<p>
@ -1061,7 +1176,7 @@ In Lua:
<p>
Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. Some more complicated examples will appear later.
</p>
<H3><a name="Lua_nn22"></a>26.3.15 C++ Smart Pointers</H3>
<H3><a name="Lua_nn22">28.3.15 C++ Smart Pointers</a></H3>
<p>
@ -1113,7 +1228,7 @@ If you ever need to access the underlying pointer returned by <tt>operator-&gt;(
&gt; f = p:__deref__() -- Returns underlying Foo *
</pre></div>
<H3><a name="Lua_nn23"></a>26.3.16 C++ Exceptions</H3>
<H3><a name="Lua_nn23">28.3.16 C++ Exceptions</a></H3>
<p>
@ -1256,13 +1371,164 @@ and the "<a href="Customization.html#Customization_exception">Exception handling
add exception specification to functions or globally (respectively).
</p>
<H3><a name="Lua_namespaces">28.3.17 Namespaces </a></H3>
<H2><a name="Lua_nn24"></a>26.4 Typemaps</H2>
<p>
Since SWIG-3.0.0 C++ namespaces are supported via the %nspace feature.
</p>
<p> Namespaces are mapped into Lua tables. Each of those tables contains names that were defined within appropriate namespace. Namespaces structure (a.k.a nested namespaces) is preserved. Consider the following C++ code:
</p>
<div class="code"><pre>%module example
%nspace MyWorld::Nested::Dweller;
%nspace MyWorld::World;
int module_function() { return 7; }
int module_variable = 9;
namespace MyWorld {
class World {
public:
World() : world_max_count(9) {}
int create_world() { return 17; }
const int world_max_count; // = 9
};
namespace Nested {
class Dweller {
public:
enum Gender { MALE = 0, FEMALE = 1 };
static int count() { return 19; }
};
}
}
</pre></div>
<p>
Now, from Lua usage is as follows:
</p>
<div class="targetlang"><pre>
&gt; print(example.module_function())
7
&gt; print(example.module_variable)
9
&gt; print(example.MyWorld.World():create_world())
17
&gt; print(example.MyWorld.World.world_max_count)
9
&gt; print(example.MyWorld.Nested.Dweller.MALE)
0
&gt; print(example.MyWorld.Nested.Dweller.count())
19
&gt;
</pre></div>
<H4><a name="Lua_nn27">28.3.17.1 Compatibility Note </a></H4>
<p>
If SWIG is running in a backwards compatible way, i.e. without the <tt>-no-old-metatable-bindings</tt> option, then additional old-style names are generated (notice the underscore):
</p>
<div class="targetlang"><pre>
9
&gt; print(example.MyWorld.Nested.Dweller_MALE)
0
&gt; print(example.MyWorld.Nested.Dweller_count())
11
&gt;
</pre></div>
<H4><a name="Lua_nn29">28.3.17.2 Names </a></H4>
<p> If SWIG is launched without <tt>-no-old-metatable-bindings</tt> option, then it enters backward-compatible mode. While in this mode, it tries
to generate additional names for static functions, class static constants and class enums.
Those names are in a form <tt>$classname_$symbolname</tt> and are added to the scope surrounding the class.
If %nspace is enabled, then class namespace is taken as scope. If there is no namespace, or %nspace is disabled,
then module is considered a class namespace.</p>
<p> Consider the following C++ code </p>
<div class="code"><pre>%module example
%nspace MyWorld::Test;
namespace MyWorld {
class Test {
public:
enum { TEST1 = 10, TEST2 }
static const int ICONST = 12;
};
class Test2 {
public:
enum { TEST3 = 20, TEST4 }
static const int ICONST2 = 23;
}
</pre></div>
<p> When in backward compatible mode, in addition to the usual names, the following ones will be generated (notice the underscore):</p>
<div class="targetlang"><pre>
9
&gt; print(example.MyWorld.Test_TEST1) -- Test has %nspace enabled
10
&gt; print(example.MyWorld.Test_ICONST) -- Test has %nspace enabled
12
&gt; print(example.Test2_TEST3) -- Test2 doesn't have %nspace enabled
20
&gt; print(example.Test2_ICONST2) -- Test2 doesn't have %nspace enabled
23
&gt;
</pre></div>
<p> There is a slight difference with enums when in C mode. As per C standard, enums from C structures are exported to
surrounding scope without any prefixing. Pretending that Test2 is a struct, not class, that would be:</p>
<div class="targetlang"><pre>
&gt; print(example.TEST3) -- NOT Test2_TEST3
20
&gt;
</pre></div>
<H4><a name="Lua_nn30">28.3.17.3 Inheritance </a></H4>
<p> The internal organization of inheritance has changed.
Consider the following C++ code:</p>
<div class="code"><pre>%module example
class Base {
public:
int base_func()
};
class Derived : public Base {
public:
int derived_func()
}
</pre></div>
<p>Lets assume for a moment that class member functions are stored in <tt>.fn</tt> table. Previously, when classes
were exported to Lua during module initialization, for every derived class all service tables <tt>ST(i.e. ".fn")</tt>
were squashed and added to corresponding derived class <tt>ST</tt>: Everything from <tt>.fn</tt> table of class Base
was copied to <tt>.fn</tt> table of class Derived and so on. This was a recursive procedure, so in the end the whole
inheritance tree of derived class was squashed into derived class. </p>
<p> That means that any changes done to class Base after module initialization wouldn't affect class Derived:</p>
<div class="targetlang"><pre>
base = example.Base()
der = example.Derived()
&gt; print(base.base_func)
function: 0x1367940
&gt; getmetatable(base)[".fn"].new_func = function (x) return x -- Adding new function to class Base (to class, not to an instance!)
&gt; print(base.new_func) -- Checking this function
function
&gt; print(der.new_func) -- Wouldn't work. Derived doesn't check Base any more.
nil
&gt;
</pre></div>
<p> This behaviour was changed. Now unless -squash-bases option is provided, Derived store a list of it's bases and if some symbol is not found in it's own service tables
then its bases are searched for it. Option -squash-bases will effectively return old behaviour.
<div class="targetlang"><pre>
&gt; print(der.new_func) -- Now it works
function
&gt;
</pre></div>
<H2><a name="Lua_nn24">28.4 Typemaps</a></H2>
<p>This section explains what typemaps are and how to use them. The default wrapping behaviour of SWIG is enough in most cases. However sometimes SWIG may need a little additional assistance to know which typemap to apply to provide the best wrapping. This section will be explaining how to use typemaps to best effect</p>
<H3><a name="Lua_nn25"></a>26.4.1 What is a typemap?</H3>
<H3><a name="Lua_nn25">28.4.1 What is a typemap?</a></H3>
<p>A typemap is nothing more than a code generation rule that is attached to a specific C datatype. For example, to convert integers from Lua to C, you might define a typemap like this:</p>
@ -1270,8 +1536,8 @@ add exception specification to functions or globally (respectively).
<div class="code"><pre>%module example
%typemap(in) int {
$1 = (int) lua_tonumber(L,$input);
printf("Received an integer : %d\n",$1);
$1 = (int) lua_tonumber(L,$input);
printf("Received an integer : %d\n",$1);
}
%inline %{
extern int fact(int n);
@ -1290,7 +1556,7 @@ Received an integer : 6
720
</pre></div>
<H3><a name="Lua_nn26"></a>26.4.2 Using typemaps</H3>
<H3><a name="Lua_nn26">28.4.2 Using typemaps</a></H3>
<p>There are many ready written typemaps built into SWIG for all common types (int, float, short, long, char*, enum and more), which SWIG uses automatically, with no effort required on your part.</p>
@ -1343,7 +1609,7 @@ void swap(int *sx, int *sy);
<p>Note: C++ references must be handled exactly the same way. However SWIG will automatically wrap a <tt>const int&amp;</tt> as an input parameter (since that it obviously input).</p>
<H3><a name="Lua_nn27"></a>26.4.3 Typemaps and arrays</H3>
<H3><a name="Lua_typemap_arrays">28.4.3 Typemaps and arrays</a></H3>
<p>Arrays present a challenge for SWIG, because like pointers SWIG does not know whether these are input or output values, nor
@ -1359,7 +1625,7 @@ extern void sort_double(double* arr, int len);
to create an array in C/C++ then this can be filled within Lua and passed into the function. It works, but it's a bit tedious.
More details can be found in the <a href="Library.html#Library_carrays">carrays.i</a> documentation.</p>
<p>The second and more intuitive way, would be to pass a Lua table directly into the function, and have SWIG automatically convert between Lua-table and C-array. Within the <tt>&lt;typemaps.i&gt;</tt> file there are typemaps ready written to perform this task. To use them is again a matter of using %appy in the correct manner.</p>
<p>The second and more intuitive way, would be to pass a Lua table directly into the function, and have SWIG automatically convert between Lua-table and C-array. Within the <tt>&lt;typemaps.i&gt;</tt> file there are typemaps ready written to perform this task. To use them is again a matter of using %apply in the correct manner.</p>
<p>The wrapper file below, shows both the use of carrays as well as the use of the typemap to wrap arrays. </p>
@ -1407,7 +1673,7 @@ and Lua tables to be 1..N, (the indexing follows the norm for the language). In
<p>Note: SWIG also can support arrays of pointers in a similar manner.</p>
<H3><a name="Lua_nn28"></a>26.4.4 Typemaps and pointer-pointer functions</H3>
<H3><a name="Lua_typemaps_ptr_ptr_functions">28.4.4 Typemaps and pointer-pointer functions</a></H3>
<p>Several C++ libraries use a pointer-pointer functions to create its objects. These functions require a pointer to a pointer which is then filled with the pointer to the new object. Microsoft's COM and DirectX as well as many other libraries have this kind of function. An example is given below:</p>
@ -1441,7 +1707,7 @@ int Create_Math(iMath** pptr); // its creator (assume it mallocs)
ptr=nil -- the iMath* will be GC'ed as normal
</pre></div>
<H2><a name="Lua_nn29"></a>26.5 Writing typemaps</H2>
<H2><a name="Lua_writing_typemaps">28.5 Writing typemaps</a></H2>
<p>This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the <tt>%typemap</tt> directive. This is an advanced topic that assumes familiarity with the Lua C API as well as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.</p>
@ -1450,7 +1716,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
<p>Before proceeding, you should read the previous section on using typemaps, and look at the existing typemaps found in luatypemaps.swg and typemaps.i. These are both well documented and fairly easy to read. You should not attempt to write your own typemaps until you have read and can understand both of these files (they may well also give you an idea to base your work on).</p>
<H3><a name="Lua_nn30"></a>26.5.1 Typemaps you can write</H3>
<H3><a name="Lua_typemaps_write">28.5.1 Typemaps you can write</a></H3>
<p>There are many different types of typemap that can be written, the full list can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. However the following are the most commonly used ones.</p>
@ -1463,7 +1729,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
(the syntax for the typecheck is different from the typemap, see typemaps for details).</li>
</ul>
<H3><a name="Lua_nn31"></a>26.5.2 SWIG's Lua-C API</H3>
<H3><a name="Lua_nn31">28.5.2 SWIG's Lua-C API</a></H3>
<p>This section explains the SWIG specific Lua-C API. It does not cover the main Lua-C api, as this is well documented and not worth covering.</p>
@ -1512,7 +1778,7 @@ This macro, when called within the context of a SWIG wrapped function, will disp
<div class="indent">
Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.</div>
<H2><a name="Lua_nn32"></a>26.6 Customization of your Bindings</H2>
<H2><a name="Lua_nn32">28.6 Customization of your Bindings</a></H2>
<p>
@ -1521,7 +1787,7 @@ This section covers adding of some small extra bits to your module to add the la
<H3><a name="Lua_nn33"></a>26.6.1 Writing your own custom wrappers</H3>
<H3><a name="Lua_nn33">28.6.1 Writing your own custom wrappers</a></H3>
<p>
@ -1540,7 +1806,7 @@ int native_function(lua_State*L) // my native code
The <tt>%native</tt> directive in the above example, tells SWIG that there is a function <tt>int native_function(lua_State*L);</tt> which is to be added into the module under the name '<tt>my_func</tt>'. SWIG will not add any wrapper for this function, beyond adding it into the function table. How you write your code is entirely up to you.
</p>
<H3><a name="Lua_nn34"></a>26.6.2 Adding additional Lua code</H3>
<H3><a name="Lua_nn34">28.6.2 Adding additional Lua code</a></H3>
<p>
@ -1578,7 +1844,7 @@ Good uses for this feature is adding of new code, or writing helper functions to
See Examples/lua/arrays for an example of this code.
</p>
<H2><a name="Lua_nn35"></a>26.7 Details on the Lua binding</H2>
<H2><a name="Lua_nn35">28.7 Details on the Lua binding</a></H2>
<p>
@ -1589,7 +1855,7 @@ See Examples/lua/arrays for an example of this code.
</i>
</p>
<H3><a name="Lua_nn36"></a>26.7.1 Binding global data into the module.</H3>
<H3><a name="Lua_nn36">28.7.1 Binding global data into the module.</a></H3>
<p>
@ -1649,7 +1915,7 @@ end
<p>
That way when you call '<tt>a=example.Foo</tt>', the interpreter looks at the table 'example' sees that there is no field 'Foo' and calls __index. This will in turn check in '.get' table and find the existence of 'Foo' and then return the value of the C function call 'Foo_get()'. Similarly for the code '<tt>example.Foo=10</tt>', the interpreter will check the table, then call the __newindex which will then check the '.set' table and call the C function 'Foo_set(10)'.
</p>
<H3><a name="Lua_nn37"></a>26.7.2 Userdata and Metatables</H3>
<H3><a name="Lua_nn37">28.7.2 Userdata and Metatables</a></H3>
<p>
@ -1729,7 +1995,7 @@ Note: Both the opaque structures (like the FILE*) and normal wrapped classes/str
<p>
Note: Operator overloads are basically done in the same way, by adding functions such as '__add' &amp; '__call' to the class' metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload.
</p>
<H3><a name="Lua_nn38"></a>26.7.3 Memory management</H3>
<H3><a name="Lua_nn38">28.7.3 Memory management</a></H3>
<p>

46
Doc/Manual/Makefile
View file

@ -9,7 +9,7 @@
# validation.
#
# Additional html validation can be done using the validate target.
# Additional link checking can be done using the linkchecker target.
# Additional link checking can be done using the linkchecker1 and linkchecker2 target.
#
# Note the # and " are escaped
@ -19,31 +19,34 @@ HTMLDOC_OPTIONS = "--book --toclevels 4 --no-numbered --toctitle \"Table of Cont
all: maketoc check generate
maketoc: CCache.html
maketoc:
python maketoc.py
# Use this to regenerate CCache.html should this ever be needed
CCache.html: ../../CCache/ccache.yo
yodl2html -o CCache.html ../../CCache/ccache.yo
# Tabs in the html files will stop the build as wkhtmltopdf does not expand them correctly - replace them with the appropriate number of tabs
# Use htmltidy to warn about some HTML errors. Note that it is not used to clean/tidy the HTML,
# it is just used as a primitive HTML checker.
# CCache.html is generated by yodl2html and has a few insignificant problems, so we don't put it through tidy
check:
tidy -errors --gnu-emacs yes -quiet index.html
tidy -errors --gnu-emacs yes -quiet Sections.html
all=`sed '/^#/d' chapters | grep -v CCache.html`; for a in $$all; do tidy -errors --gnu-emacs yes -quiet $$a; done;
all="index.html Sections.html `sed '/^#/d' chapters | grep -v CCache.html`" && for a in $$all; do echo "Check for tabs $$a" && if grep -P '\t' $$a; then echo "Please delete the tabs from the lines above" && exit 1; fi; done && for a in $$all; do echo "HTML tidy check $$a" && tidy -errors --gnu-emacs yes -quiet $$a; done;
generate: swightml.book swigpdf.book
# Note wkhtmltopdf limitations for generating pdf docs:
# 1) <H1><a name="X"></a>Text</H1> style links don't work and need changing to
# <H1><a name="X">Text</a></H1>
# 2) Tabs in <pre> elements should be expanded to 8 spaces by default, but
# are expanded to just one space and css tab-size is not working.
# 3) <pre> <tt> <code> elements do not always select a fixed-width font - try installing the
# Courier font to fix - these have been added to style.css.
generate: SWIGDocumentation.html
wkhtmltopdf --margin-top 20mm --margin-bottom 20mm --margin-left 10mm --margin-right 10mm --header-font-size 6 --footer-font-size 6 --header-spacing 6 --footer-spacing 6 --header-center '[doctitle]' --footer-left '[subsection]' --footer-right '[page]' SWIGDocumentation.html SWIGDocumentation.pdf
SWIGDocumentation.html: swightml.book
htmldoc --batch swightml.book || true
htmldoc --batch swigpdf.book || true
python fixstyle.py SWIGDocumentation.html
swigpdf.book: chapters Sections.html
echo "#HTMLDOC 1.8.24" > swigpdf.book
echo -t pdf13 -f SWIGDocumentation.pdf $(HTMLDOC_OPTIONS) --stylesheet style.css >> swigpdf.book
echo "Sections.html" >> swigpdf.book
cat chapters >> swigpdf.book
swightml.book: chapters Sections.html
echo "#HTMLDOC 1.8.24" > swightml.book
echo -t html -f SWIGDocumentation.html $(HTMLDOC_OPTIONS) >> swightml.book
@ -52,10 +55,9 @@ swightml.book: chapters Sections.html
maintainer-clean: clean-baks
rm -f swightml.book
rm -f swigpdf.book
rm -f CCache.html
rm -f SWIGDocumentation.html
rm -f SWIGDocumentation.pdf
rm -rf linkchecker-tmp
clean-baks:
rm -f *.bak
@ -69,10 +71,18 @@ test:
validate:
all=`sed '/^#/d' chapters`; for a in $$all; do validate --emacs $$a; done;
# Link checking using linkchecker
linkchecker:
# Link checking using linkchecker of the index.html only file (including anchors)
linkchecker1:
@echo -----------------------------------------------------------------------
@echo Note linkchecker versions prior to 6.1 do not work properly wrt anchors
@echo -----------------------------------------------------------------------
linkchecker --config=./linkchecker.config index.html
linkchecker --config=./linkchecker.config --anchors index.html
# Check for links which don't work including those generated from the individual .html files into SWIGDocumentation.html
linkchecker2:
rm -rf linkchecker-tmp
mkdir linkchecker-tmp
cp SWIGDocumentation.html linkchecker-tmp
cp *.png linkchecker-tmp
(cd linkchecker-tmp && linkchecker --config=../linkchecker.config -F text --no-warnings SWIGDocumentation.html)

51
Doc/Manual/Modula3.html
View file

@ -1,11 +1,12 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Modula-3</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Modula3"></a>27 SWIG and Modula-3</H1>
<H1><a name="Modula3">29 SWIG and Modula-3</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -45,7 +46,7 @@
<p>
This chapter describes SWIG's support of
This chapter describes SWIG's support for
<a href="http://modula3.org/">Modula-3</a>.
You should be familiar with the
<a href="SWIG.html#SWIG">basics</a>
@ -54,7 +55,7 @@ especially
<a href="Typemaps.html#Typemaps">typemaps</a>.
</p>
<H2><a name="Modula3_modula3_overview"></a>27.1 Overview</H2>
<H2><a name="Modula3_modula3_overview">29.1 Overview</a></H2>
<p>
@ -84,7 +85,7 @@ FFTW
</li>
</ol>
<H3><a name="Modula3_motivation"></a>27.1.1 Motivation</H3>
<H3><a name="Modula3_motivation">29.1.1 Motivation</a></H3>
<p>
@ -109,7 +110,7 @@ into exceptions.
<p>
If the library API is ill designed
writing appropriate typemaps can be still time-consuming.
writing appropriate typemaps can still be time-consuming.
E.g. C programmers are very creative to work-around
missing data types like (real) enumerations and sets.
You should turn such work-arounds back to the Modula-3 way
@ -120,21 +121,21 @@ otherwise you lose static safety and consistency.
Without SWIG you would probably never consider trying to call C++ libraries
from Modula-3, but with SWIG this is becomes feasible.
SWIG can generate C wrappers to C++ functions and object methods
that may throw exceptions, and then wrap these C wrappers for Module-3.
that may throw exceptions, and then wrap these C wrappers for Modula-3.
To make it complete you can then hide the C interface with Modula-3 classes and
exceptions.
</p>
<p>
SWIG allows you to call C and C++ libraries from Modula-3 (even with call back
functions), but it doesn't allow you to easily integrate a Module-3 module into
functions), but it doesn't allow you to easily integrate a Modula-3 module into
a C/C++ project.
</p>
<H2><a name="Modula3_conception"></a>27.2 Conception</H2>
<H2><a name="Modula3_conception">29.2 Conception</a></H2>
<H3><a name="Modula3_cinterface"></a>27.2.1 Interfaces to C libraries</H3>
<H3><a name="Modula3_cinterface">29.2.1 Interfaces to C libraries</a></H3>
<p>
@ -283,7 +284,7 @@ and the principal type must be renamed (<tt>%typemap</tt>).
</p>
<H3><a name="Modula3_cppinterface"></a>27.2.2 Interfaces to C++ libraries</H3>
<H3><a name="Modula3_cppinterface">29.2.2 Interfaces to C++ libraries</a></H3>
<p>
@ -384,10 +385,10 @@ There is no C++ library I wrote a SWIG interface for,
so I'm not sure if this is possible or sensible, yet.
</p>
<H2><a name="Modula3_preliminaries"></a>27.3 Preliminaries</H2>
<H2><a name="Modula3_preliminaries">29.3 Preliminaries</a></H2>
<H3><a name="Modula3_compilers"></a>27.3.1 Compilers</H3>
<H3><a name="Modula3_compilers">29.3.1 Compilers</a></H3>
<p>
@ -400,7 +401,7 @@ For testing examples I use Critical Mass cm3.
</p>
<H3><a name="Modula3_commandline"></a>27.3.2 Additional Commandline Options</H3>
<H3><a name="Modula3_commandline">29.3.2 Additional Commandline Options</a></H3>
<p>
@ -477,10 +478,10 @@ Instead generate templates for some basic typemaps.
</tr>
</table>
<H2><a name="Modula3_typemaps"></a>27.4 Modula-3 typemaps</H2>
<H2><a name="Modula3_typemaps">29.4 Modula-3 typemaps</a></H2>
<H3><a name="Modula3_inoutparam"></a>27.4.1 Inputs and outputs</H3>
<H3><a name="Modula3_inoutparam">29.4.1 Inputs and outputs</a></H3>
<p>
@ -694,7 +695,7 @@ consist of the following parts:
</table>
<H3><a name="Modula3_ordinals"></a>27.4.2 Subranges, Enumerations, Sets</H3>
<H3><a name="Modula3_ordinals">29.4.2 Subranges, Enumerations, Sets</a></H3>
<p>
@ -746,7 +747,7 @@ that I'd like to automate.
</p>
<H3><a name="Modula3_class"></a>27.4.3 Objects</H3>
<H3><a name="Modula3_class">29.4.3 Objects</a></H3>
<p>
@ -759,7 +760,7 @@ is not really useful, yet.
</p>
<H3><a name="Modula3_imports"></a>27.4.4 Imports</H3>
<H3><a name="Modula3_imports">29.4.4 Imports</a></H3>
<p>
@ -792,7 +793,7 @@ IMPORT M3toC;
</pre></div>
<H3><a name="Modula3_exceptions"></a>27.4.5 Exceptions</H3>
<H3><a name="Modula3_exceptions">29.4.5 Exceptions</a></H3>
<p>
@ -816,7 +817,7 @@ you should declare
<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>.
</p>
<H3><a name="Modula3_typemap_example"></a>27.4.6 Example</H3>
<H3><a name="Modula3_typemap_example">29.4.6 Example</a></H3>
<p>
@ -863,10 +864,10 @@ where almost everything is generated by a typemap:
</pre></div>
<H2><a name="Modula3_hints"></a>27.5 More hints to the generator</H2>
<H2><a name="Modula3_hints">29.5 More hints to the generator</a></H2>
<H3><a name="Modula3_features"></a>27.5.1 Features</H3>
<H3><a name="Modula3_features">29.5.1 Features</a></H3>
<table border summary="Modula-3 features">
@ -903,7 +904,7 @@ where almost everything is generated by a typemap:
</tr>
</table>
<H3><a name="Modula3_pragmas"></a>27.5.2 Pragmas</H3>
<H3><a name="Modula3_pragmas">29.5.2 Pragmas</a></H3>
<table border summary="Modula-3 pragmas">
@ -926,7 +927,7 @@ where almost everything is generated by a typemap:
</tr>
</table>
<H2><a name="Modula3_remarks"></a>27.6 Remarks</H2>
<H2><a name="Modula3_remarks">29.6 Remarks</a></H2>
<ul>

25
Doc/Manual/Modules.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Working with Modules</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Modules"></a>15 Working with Modules</H1>
<H1><a name="Modules">16 Working with Modules</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -23,7 +24,7 @@
<H2><a name="Modules_introduction"></a>15.1 Modules Introduction</H2>
<H2><a name="Modules_introduction">16.1 Modules Introduction</a></H2>
<p>
@ -77,7 +78,7 @@ where you want to create a collection of modules.
Each module in the collection is created via separate invocations of SWIG.
</p>
<H2><a name="Modules_nn1"></a>15.2 Basics</H2>
<H2><a name="Modules_nn1">16.2 Basics</a></H2>
<p>
@ -130,7 +131,7 @@ public:
<p>To create the wrapper properly, module <tt>derived_module</tt> needs to know about the
<tt>base</tt> class and that its interface is covered in another module. The
line <tt>%import "base_module.i"</tt> lets SWIG know exactly that. Oftentimes
line <tt>%import "base_module.i"</tt> lets SWIG know exactly that. Often
the <tt>.h</tt> file is passed to <tt>%import</tt> instead of the <tt>.i</tt>,
which unfortunately doesn't work for all language modules. For example, Python requires the
name of module that the base class exists in so that the proxy classes can fully inherit the
@ -176,7 +177,7 @@ in parallel from multiple threads as SWIG provides no locking - for more on that
issue, read on.
</p>
<H2><a name="Modules_nn2"></a>15.3 The SWIG runtime code</H2>
<H2><a name="Modules_nn2">16.3 The SWIG runtime code</a></H2>
<p>
@ -242,7 +243,7 @@ can peacefully coexist. So the type structures are separated by the
is empty. Only modules compiled with the same pair will share type information.
</p>
<H2><a name="Modules_external_run_time"></a>15.4 External access to the runtime</H2>
<H2><a name="Modules_external_run_time">16.4 External access to the runtime</a></H2>
<p>As described in <a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>,
@ -250,7 +251,9 @@ the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others s
to be called. Calling these functions from a typemap is supported, since the typemap code
is embedded into the <tt>_wrap.c</tt> file, which has those declarations available. If you need
to call the SWIG run-time functions from another C file, there is one header you need
to include. To generate the header that needs to be included, run the following command:
to include. To generate the header that needs to be included, SWIG can be run in a different
mode via <tt>-external-runtime</tt> to generate the run-time instead of the normal mode of
processing an input interface file. For example:
<div class="shell"><pre>
$ swig -python -external-runtime &lt;filename&gt;
@ -279,7 +282,7 @@ SWIG_TYPE_TABLE to be the same as the module whose types you are trying to
access.
</p>
<H2><a name="Modules_nn4"></a>15.5 A word of caution about static libraries</H2>
<H2><a name="Modules_nn4">16.5 A word of caution about static libraries</a></H2>
<p>
@ -290,7 +293,7 @@ into it. This is very often <b>NOT</b> what you want and it can lead to unexpect
behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries.
</p>
<H2><a name="Modules_nn5"></a>15.6 References</H2>
<H2><a name="Modules_nn5">16.6 References</a></H2>
<p>
@ -298,7 +301,7 @@ Due to the complexity of working with shared libraries and multiple modules, it
an outside reference. John Levine's "Linkers and Loaders" is highly recommended.
</p>
<H2><a name="Modules_nn6"></a>15.7 Reducing the wrapper file size</H2>
<H2><a name="Modules_nn6">16.7 Reducing the wrapper file size</a></H2>
<p>

24
Doc/Manual/Mzscheme.html
View file

@ -1,14 +1,14 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Hand-written HTML -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and MzScheme/Racket</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Mzscheme"></a>28 SWIG and MzScheme/Racket</H1>
<H1><a name="Mzscheme">30 SWIG and MzScheme/Racket</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -24,7 +24,7 @@
<p>
This section contains information on SWIG's support of Racket, formally known as MzScheme.
<H2><a name="MzScheme_nn2"></a>28.1 Creating native structures</H2>
<H2><a name="MzScheme_nn2">30.1 Creating native structures</a></H2>
<p>
@ -56,16 +56,16 @@ Then in scheme, you can use regular struct access procedures like
<div class="code">
<pre>
; suppose a function created a struct foo as
; (define foo (make-diag-cntrs (#x1 #x2 #x3) (make-inspector))
; Then you can do
(format "0x~x" (diag-cntrs-field1 foo))
(format "0x~x" (diag-cntrs-field2 foo))
;etc...
; suppose a function created a struct foo as
; (define foo (make-diag-cntrs (#x1 #x2 #x3) (make-inspector))
; Then you can do
(format "0x~x" (diag-cntrs-field1 foo))
(format "0x~x" (diag-cntrs-field2 foo))
;etc...
</pre>
</div>
<H2><a name="MzScheme_simple"></a>28.2 Simple example</H2>
<H2><a name="MzScheme_simple">30.2 Simple example</a></H2>
<p>
@ -166,7 +166,7 @@ Some points of interest:
<li> The above requests mzc to create an extension using the CGC garbage-collector. The alternative -- the 3m collector -- has generally better performance, but work is still required for SWIG to emit code which is compatible with it.
</ul>
<H2><a name="MzScheme_external_docs"></a>28.3 External documentation</H2>
<H2><a name="MzScheme_external_docs">30.3 External documentation</a></H2>
<p>

429
Doc/Manual/Ocaml.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Ocaml</title>
<title>SWIG and Ocaml</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<a name="n1"></a>
<H1><a name="Ocaml"></a>29 SWIG and Ocaml</H1>
<body bgcolor="#ffffff">
<H1><a name="Ocaml">31 SWIG and Ocaml</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -45,10 +46,10 @@
<li><a href="#Ocaml_nn24">Overriding Methods in Ocaml</a>
<li><a href="#Ocaml_nn25">Director Usage Example</a>
<li><a href="#Ocaml_nn26">Creating director objects</a>
<li><a href="#Ocaml_nn27">Typemaps for directors, <tt>directorin, directorout, directorargout</tt></a>
<li><a href="#Ocaml_nn28"><tt>directorin</tt> typemap</a>
<li><a href="#Ocaml_nn29"><tt>directorout</tt> typemap</a>
<li><a href="#Ocaml_nn30"><tt>directorargout</tt> typemap</a>
<li><a href="#Ocaml_nn27">Typemaps for directors, directorin, directorout, directorargout</a>
<li><a href="#Ocaml_nn28">typemap</a>
<li><a href="#Ocaml_nn29">directorout typemap</a>
<li><a href="#Ocaml_nn30">directorargout typemap</a>
</ul>
<li><a href="#Ocaml_nn31">Exceptions</a>
</ul>
@ -59,74 +60,76 @@
<p>
This chapter describes SWIG's
support of Ocaml. Ocaml is a relatively recent addition to the ML family,
and is a recent addition to SWIG. It's the second compiled, typed
language to be added. Ocaml has widely acknowledged benefits for engineers,
mostly derived from a sophisticated type system, compile-time checking
which eliminates several classes of common programming errors, and good
native performance. While all of this is wonderful, there are well-written
C and C++ libraries that Ocaml users will want to take advantage of as
part of their arsenal (such as SSL and gdbm), as well as their own mature
C and C++ code. SWIG allows this code to be used in a natural, type-safe
way with Ocaml, by providing the necessary, but repetitive glue code
which creates and uses Ocaml values to communicate with C and C++ code.
In addition, SWIG also produces the needed Ocaml source that binds
variants, functions, classes, etc.
This chapter describes SWIG's support of Ocaml.
</p>
<p>
Ocaml is a relatively recent addition to the ML family,
and is a recent addition to SWIG. It's the second compiled, typed
language to be added. Ocaml has widely acknowledged benefits for engineers,
mostly derived from a sophisticated type system, compile-time checking
which eliminates several classes of common programming errors, and good
native performance. While all of this is wonderful, there are well-written
C and C++ libraries that Ocaml users will want to take advantage of as
part of their arsenal (such as SSL and gdbm), as well as their own mature
C and C++ code. SWIG allows this code to be used in a natural, type-safe
way with Ocaml, by providing the necessary, but repetitive glue code
which creates and uses Ocaml values to communicate with C and C++ code.
In addition, SWIG also produces the needed Ocaml source that binds
variants, functions, classes, etc.
</p>
<p>
If you're not familiar with the Objective Caml language, you can visit
<a href="http://www.ocaml.org/">The Ocaml Website</a>.
<a href="http://ocaml.org/">The Ocaml Website</a>.
</p>
<H2><a name="Ocaml_nn2"></a>29.1 Preliminaries</H2>
<H2><a name="Ocaml_nn2">31.1 Preliminaries</a></H2>
<p>
SWIG 1.3 works with Ocaml 3.04 and above. Given the choice,
you should use the latest stable release. The SWIG Ocaml module has
been tested on Linux (x86,PPC,Sparc) and Cygwin on Windows. The
best way to determine whether your system will work is to compile the
examples and test-suite which come with SWIG. You can do this by running
<tt>make check</tt> from the SWIG root directory after installing SWIG.
The Ocaml module has been tested using the system's dynamic linking (the
usual -lxxx against libxxx.so, as well as with Gerd Stolpmann's
<a
href="http://download.camlcity.org/download/">Dl package
</a>. The ocaml_dynamic and ocaml_dynamic_cpp targets in the
SWIG 3.0 works with Ocaml 3.08.3 and above. Given the choice,
you should use the latest stable release. The SWIG Ocaml module has
been tested on Linux (x86,PPC,Sparc) and Cygwin on Windows. The
best way to determine whether your system will work is to compile the
examples and test-suite which come with SWIG. You can do this by running
<tt>make check</tt> from the SWIG root directory after installing SWIG.
The Ocaml module has been tested using the system's dynamic linking (the
usual -lxxx against libxxx.so, as well as with Gerd Stolpmann's
<a href="http://download.camlcity.org/download/">Dl package</a>.
The ocaml_dynamic and ocaml_dynamic_cpp targets in the
file Examples/Makefile illustrate how to compile and link SWIG modules that
will be loaded dynamically. This has only been tested on Linux so far.
</p>
<H3><a name="Ocaml_nn3"></a>29.1.1 Running SWIG</H3>
<H3><a name="Ocaml_nn3">31.1.1 Running SWIG</a></H3>
<p>
The basics of getting a SWIG Ocaml module up and running
can be seen from one of SWIG's example Makefiles, but is also described
here. To build an Ocaml module, run SWIG using the <tt>-ocaml</tt>
option.
The basics of getting a SWIG Ocaml module up and running
can be seen from one of SWIG's example Makefiles, but is also described
here. To build an Ocaml module, run SWIG using the <tt>-ocaml</tt>
option.
</p>
<div class="code">
<pre>
<div class="code">
<pre>
%swig -ocaml example.i
</pre>
</pre>
</div>
<p> This will produce 3 files. The file <tt>example_wrap.c</tt> contains
<p>This will produce 3 files. The file <tt>example_wrap.c</tt> contains
all of the C code needed to build an Ocaml module. To build the module,
you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or
you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or
<tt>ocamlopt</tt> to create the needed .o file. You will need to compile
the resulting .ml and .mli files as well, and do the final link with -custom
(not needed for native link). </p>
<H3><a name="Ocaml_nn4"></a>29.1.2 Compiling the code</H3>
(not needed for native link).</p>
<H3><a name="Ocaml_nn4">31.1.2 Compiling the code</a></H3>
<p>
The O'Caml SWIG module now requires you to compile a module (<tt>Swig</tt>)
The OCaml SWIG module now requires you to compile a module (<tt>Swig</tt>)
separately. In addition to aggregating common SWIG functionality, the Swig
module contains the data structure that represents C/C++ values. This allows
easier data sharing between modules if two or more are combined, because
@ -134,39 +137,40 @@ the type of each SWIG'ed module's c_obj is derived from Swig.c_obj_t. This
also allows SWIG to acquire new conversions painlessly, as well as giving
the user more freedom with respect to custom typing.
Use <tt>ocamlc</tt> or <tt>ocamlopt</tt> to compile your
SWIG interface like:
Use <tt>ocamlc</tt> or <tt>ocamlopt</tt> to compile your SWIG interface like:
</p>
<div class="code">
<pre>
<div class="code">
<pre>
% swig -ocaml -co swig.mli ; swig -ocaml co swig.ml
% ocamlc -c swig.mli ; ocamlc -c swig.ml
% ocamlc -c -ccopt "-I/usr/include/foo" example_wrap.c
% ocamlc -c example.mli
% ocamlc -c example.ml
</pre>
</div>
<p> <tt>ocamlc</tt> is aware of .c files and knows how to handle them. Unfortunately,
it does not know about .cxx, .cc, or .cpp files, so when SWIG is invoked
in C++ mode, you must: </p>
<div class="code">
<pre>
% cp example_wrap.cxx example_wrap.cxx.c<br>% ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c<br>% ...<br>
</pre>
</pre>
</div>
<H3><a name="Ocaml_nn5"></a>29.1.3 The camlp4 module</H3>
<p><tt>ocamlc</tt> is aware of .c files and knows how to handle them. Unfortunately,
it does not know about .cxx, .cc, or .cpp files, so when SWIG is invoked
in C++ mode, you must:</p>
<div class="code">
<pre>
% cp example_wrap.cxx example_wrap.cxx.c
% ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c
% ...
</pre>
</div>
<H3><a name="Ocaml_nn5">31.1.3 The camlp4 module</a></H3>
<p>
The camlp4 module (swigp4.ml -&gt; swigp4.cmo) contains a simple rewriter which
makes C++ code blend more seamlessly with objective caml code. It's use is
makes C++ code blend more seamlessly with objective caml code. Its use is
optional, but encouraged. The source file is included in the Lib/ocaml
directory of the SWIG source distribution. You can checkout this file with
<tt>"swig -ocaml -co swigp4.ml"</tt>. You should compile the file with
directory of the SWIG source distribution. You can checkout this file with
<tt>"swig -ocaml -co swigp4.ml"</tt>. You should compile the file with
<tt>"ocamlc -I `camlp4 -where` -pp 'camlp4o pa_extend.cmo q_MLast.cmo' -c swigp4.ml"</tt>
</p>
@ -192,7 +196,7 @@ a '+= b</td>
<td>
(invoke object) "+=" argument as in<br>
(invoke a) "+=" b<td></tr>
<tr><th colspan=2>Note that because camlp4 always recognizes &lt;&lt;
<tr><th colspan=2>Note that because camlp4 always recognizes &lt;&lt;
and &gt;&gt;, they are replaced by lsl and lsr in operator names.
<tr><td>
<i>'unop</i> object as in<br>
@ -234,21 +238,21 @@ let b = C_string (getenv "PATH")
</td></tr>
</table>
<H3><a name="Ocaml_nn6"></a>29.1.4 Using your module</H3>
<H3><a name="Ocaml_nn6">31.1.4 Using your module</a></H3>
<p>
You can test-drive your module by building a
toplevel ocaml interpreter. Consult the ocaml manual for details.
</p>
<p>
When linking any ocaml bytecode with your module, use the -custom
option to build your functions into the primitive list. This
option is not needed when you build native code.
option to build your functions into the primitive list. This
option is not needed when you build native code.
</p>
<H3><a name="Ocaml_nn7"></a>29.1.5 Compilation problems and compiling with C++</H3>
<H3><a name="Ocaml_nn7">31.1.5 Compilation problems and compiling with C++</a></H3>
<p>
@ -259,7 +263,7 @@ liberal with pointer types may not compile under the C++ compiler.
Most code meant to be compiled as C++ will not have problems.
</p>
<H2><a name="Ocaml_nn8"></a>29.2 The low-level Ocaml/C interface</H2>
<H2><a name="Ocaml_nn8">31.2 The low-level Ocaml/C interface</a></H2>
<p>
@ -273,9 +277,9 @@ In the code as seen by the typemap
writer, there is a value, swig_result, that always contains the
current return data. It is a list, and must be appended with the
caml_list_append function, or with functions and macros provided by
objective caml.<br>
objective caml.
</p>
<div class="code"><pre>
type c_obj =
C_void
@ -299,68 +303,67 @@ type c_obj =
</pre></div>
<p>
A few functions exist which generate and return these:
A few functions exist which generate and return these:
</p>
<ul>
<li>caml_ptr_val receives a c_obj and returns a void *. &nbsp;This
should be used for all pointer purposes.</li>
<li>caml_long_val receives a c_obj and returns a long. &nbsp;This
should be used for most integral purposes.<br>
</li>
<li>caml_val_ptr receives a void * and returns a c_obj.</li>
<li>caml_val_bool receives a C int and returns a c_obj representing
it's bool value.</li>
<li>caml_val_(u)?(char|short|int|long|float|double) receives an
appropriate C value and returns a c_obj representing it.</li>
<li>caml_val_string receives a char * and returns a string value.</li>
<li>caml_val_string_len receives a char * and a length and returns
a string value.</li>
<li>caml_val_obj receives a void * and an object type and returns
a C_obj, which contains a closure giving method access.</li>
<li>caml_ptr_val receives a c_obj and returns a void *. This
should be used for all pointer purposes.</li>
<li>caml_long_val receives a c_obj and returns a long. This
should be used for most integral purposes.</li>
<li>caml_val_ptr receives a void * and returns a c_obj.</li>
<li>caml_val_bool receives a C int and returns a c_obj representing
its bool value.</li>
<li>caml_val_(u)?(char|short|int|long|float|double) receives an
appropriate C value and returns a c_obj representing it.</li>
<li>caml_val_string receives a char * and returns a string value.</li>
<li>caml_val_string_len receives a char * and a length and returns
a string value.</li>
<li>caml_val_obj receives a void * and an object type and returns
a C_obj, which contains a closure giving method access.</li>
</ul>
<p>
Because of this style, a typemap can return any kind of value it
wants from a function. &nbsp;This enables out typemaps and inout typemaps
to work well. &nbsp;The one thing to remember about outputting values
is that you must append them to the return list with swig_result = caml_list_append(swig_result,v).
wants from a function. This enables out typemaps and inout typemaps
to work well. The one thing to remember about outputting values
is that you must append them to the return list with swig_result = caml_list_append(swig_result,v).
</p>
<p>
&nbsp;This function will return a new list that has your element
appended. Upon return to caml space, the fnhelper function
beautifies the result. A list containing a single item degrades to
only that item (i.e. [ C_int 3 ] -&gt; C_int 3), and a list
containing more than one item is wrapped in C_list (i.e. [ C_char
'a' ; C_char 'b' -&gt; C_list [ C_char 'a' ; C_char b
]). &nbsp;This is in order to make return values easier to handle
when functions have only one return value, such as constructors,
and operators. &nbsp;In addition, string, pointer, and object
values are interchangeable with respect to caml_ptr_val, so you can
allocate memory as caml strings and still use the resulting
pointers for C purposes, even using them to construct simple objects
on. Note, though, that foreign C++ code does not respect the garbage
collector, although the SWIG interface does.</p>
This function will return a new list that has your element
appended. Upon return to caml space, the fnhelper function
beautifies the result. A list containing a single item degrades to
only that item (i.e. [ C_int 3 ] -&gt; C_int 3), and a list
containing more than one item is wrapped in C_list (i.e. [ C_char
'a' ; C_char 'b' -&gt; C_list [ C_char 'a' ; C_char b
]). This is in order to make return values easier to handle
when functions have only one return value, such as constructors,
and operators. In addition, string, pointer, and object
values are interchangeable with respect to caml_ptr_val, so you can
allocate memory as caml strings and still use the resulting
pointers for C purposes, even using them to construct simple objects
on. Note, though, that foreign C++ code does not respect the garbage
collector, although the SWIG interface does.</p>
<p>
The wild card type that you can use in lots of different ways is
C_obj. It allows you to wrap any type of thing you like as an
object using the same mechanism that the ocaml module
does. &nbsp;When evaluated in caml_ptr_val, the returned value is
the result of a call to the object's "&amp;" operator, taken as a pointer.
</p>
<p>
You should only construct values using objective caml, or using the
functions caml_val_* functions provided as static functions to a SWIG
ocaml module, as well as the caml_list_* functions. These functions
provide everything a typemap needs to produce values. In addition,
value items pass through directly, but you must make your own type
signature for a function that uses value in this way.
</p>
<p>
The wild card type that you can use in lots of different ways is
C_obj. It allows you to wrap any type of thing you like as an
object using the same mechanism that the ocaml module
does. When evaluated in caml_ptr_val, the returned value is
the result of a call to the object's "&amp;" operator, taken as a pointer.
</p>
<H3><a name="Ocaml_nn9"></a>29.2.1 The generated module</H3>
<p>
You should only construct values using objective caml, or using the
functions caml_val_* functions provided as static functions to a SWIG
ocaml module, as well as the caml_list_* functions. These functions
provide everything a typemap needs to produce values. In addition,
value items pass through directly, but you must make your own type
signature for a function that uses value in this way.
</p>
<H3><a name="Ocaml_nn9">31.2.1 The generated module</a></H3>
<p>
@ -376,7 +379,7 @@ that the keywords are not the same as the C++ ones.
You can introduce extra code into the output wherever you like with SWIG.
These are the places you can introduce code:
<table border="1" summary="Extra code sections">
<tr><td>"header"</td><td>This code is inserted near the beginning of the
<tr><td>"header"</td><td>This code is inserted near the beginning of the
C wrapper file, before any function definitions.</td></tr>
<tr><td>"wrapper"</td><td>This code is inserted in the function definition
section.</td></tr>
@ -385,25 +388,25 @@ file.</td></tr>
<tr><td>"mli"</td><td>This code is inserted into the caml interface file.
Special signatures should be inserted here.
</td></tr>
<tr><td>"ml"</td><td>This code is inserted in the caml code defining the
<tr><td>"ml"</td><td>This code is inserted in the caml code defining the
interface to your C code. Special caml code, as well as any initialization
which should run when the module is loaded may be inserted here.
</td></tr>
</td></tr>
<tr><td>"classtemplate"</td><td>The "classtemplate" place is special because
it describes the output SWIG will generate for class definitions.
</td></tr>
</table>
<H3><a name="Ocaml_nn10"></a>29.2.2 Enums</H3>
<H3><a name="Ocaml_nn10">31.2.2 Enums</a></H3>
<p>
SWIG will wrap enumerations as polymorphic variants in the output
Ocaml code, as above in C_enum.&nbsp; In order to support all
Ocaml code, as above in C_enum. In order to support all
C++-style uses of enums, the function int_to_enum and enum_to_int are
provided for ocaml code to produce and consume these values as
integers. &nbsp;Other than that, correct uses of enums will not have
a problem. &nbsp;Since enum labels may overlap between enums, the
integers. Other than that, correct uses of enums will not have
a problem. Since enum labels may overlap between enums, the
enum_to_int and int_to_enum functions take an enum type label as an
argument. Example:
</p>
@ -416,9 +419,9 @@ enum c_enum_type { a = 1, b, c = 4, d = 8 };
enum c_enum_type { a = 1, b, c = 4, d = 8 };
</pre></div>
<p>
<p>
The output mli contains:
</p>
</p>
<div class="code"><pre>
type c_enum_type = [
@ -435,16 +438,16 @@ type c_enum_tag = [
val int_to_enum c_enum_type -&gt; int -&gt; c_obj
val enum_to_int c_enum_type -&gt; c_obj -&gt; c_obj
</pre>
</div>
</div>
<p>
So it's possible to do this:
So it's possible to do this:
</p>
<div class="code">
<pre>
<div class="code">
<pre>
bash-2.05a$ ocamlmktop -custom enum_test_wrap.o enum_test.cmo -o enum_test_top
bash-2.05a$ ./enum_test_top
bash-2.05a$ ./enum_test_top
Objective Caml version 3.04
# open Enum_test ;;
@ -455,9 +458,9 @@ val x : Enum_test.c_obj = C_enum `a
# int_to_enum `c_enum_type 4 ;;
- : Enum_test.c_obj = C_enum `c
</pre>
</div>
</div>
<H4><a name="Ocaml_nn11"></a>29.2.2.1 Enum typing in Ocaml</H4>
<H4><a name="Ocaml_nn11">31.2.2.1 Enum typing in Ocaml</a></H4>
<p>
@ -470,10 +473,10 @@ functions imported from different modules. You must convert values to master
values using the swig_val function before sharing them with another module.
</p>
<H3><a name="Ocaml_nn12"></a>29.2.3 Arrays</H3>
<H3><a name="Ocaml_nn12">31.2.3 Arrays</a></H3>
<H4><a name="Ocaml_nn13"></a>29.2.3.1 Simple types of bounded arrays</H4>
<H4><a name="Ocaml_nn13">31.2.3.1 Simple types of bounded arrays</a></H4>
<p>
@ -485,7 +488,7 @@ distribution.
<p>
By including "carray.i", you will get access to some macros that help you
create typemaps for array types fairly easily.
create typemaps for array types fairly easily.
</p>
<p>
@ -494,7 +497,7 @@ arrays of simple types with known bounds in your code, but this only works
for arrays whose bounds are completely specified.
</p>
<H4><a name="Ocaml_nn14"></a>29.2.3.2 Complex and unbounded arrays</H4>
<H4><a name="Ocaml_nn14">31.2.3.2 Complex and unbounded arrays</a></H4>
<p>
@ -507,7 +510,7 @@ SWIG can't predict which of these methods will be used in the array,
so you have to specify it for yourself in the form of a typemap.
</p>
<H4><a name="Ocaml_nn15"></a>29.2.3.3 Using an object</H4>
<H4><a name="Ocaml_nn15">31.2.3.3 Using an object</a></H4>
<p>
@ -521,7 +524,7 @@ Consider writing an object when the ending condition of your array is complex,
such as using a required sentinel, etc.
</p>
<H4><a name="Ocaml_nn16"></a>29.2.3.4 Example typemap for a function taking float * and int</H4>
<H4><a name="Ocaml_nn16">31.2.3.4 Example typemap for a function taking float * and int</a></H4>
<p>
@ -541,24 +544,24 @@ into this type of function convenient.
#include &lt;stdio.h&gt;
void printfloats( float *tab, int len ) {
int i;
int i;
for( i = 0; i &lt; len; i++ ) {
printf( "%f ", tab[i] );
}
for( i = 0; i &lt; len; i++ ) {
printf( "%f ", tab[i] );
}
printf( "\n" );
printf( "\n" );
}
%}
%typemap(in) (float *tab, int len) {
int i;
/* $*1_type */
$2 = caml_array_len($input);
$1 = ($*1_type *)malloc( $2 * sizeof( float ) );
for( i = 0; i &lt; $2; i++ ) {
$1[i] = caml_double_val(caml_array_nth($input,i));
}
int i;
/* $*1_type */
$2 = caml_array_len($input);
$1 = ($*1_type *)malloc( $2 * sizeof( float ) );
for( i = 0; i &lt; $2; i++ ) {
$1[i] = caml_double_val(caml_array_nth($input,i));
}
}
void printfloats( float *tab, int len );
@ -572,30 +575,30 @@ void printfloats( float *tab, int len );
</pre></td></tr></table>
<H3><a name="Ocaml_nn17"></a>29.2.4 C++ Classes</H3>
<H3><a name="Ocaml_nn17">31.2.4 C++ Classes</a></H3>
<p>
C++ classes, along with structs and unions are represented by C_obj
(string -&gt; c_obj -&gt; c_obj) wrapped closures. &nbsp;These objects
(string -&gt; c_obj -&gt; c_obj) wrapped closures. These objects
contain a method list, and a type, which allow them to be used like
C++ objects. When passed into typemaps that use pointers, they
degrade to pointers through their "&amp;" method. &nbsp;Every method
degrade to pointers through their "&amp;" method. Every method
an object has is represented as a string in the object's method table,
and each method table exists in memory only once. &nbsp;In addition
and each method table exists in memory only once. In addition
to any other operators an object might have, certain builtin ones are
provided by SWIG: (all of these take no arguments (C_void))
provided by SWIG: (all of these take no arguments (C_void))
</p>
<table summary="SWIG provided operators">
<tr><td>"~"</td><td>Delete this object</td></tr>
<tr><td>"&amp;"</td><td>Return an ordinary C_ptr value representing this
<tr><td>"&amp;"</td><td>Return an ordinary C_ptr value representing this
object's address</td></tr>
<tr><td>"sizeof"</td><td>If enabled with ("sizeof"="1") on the module node,
return the object's size in char.</td></tr>
<tr><td>":methods"</td><td>Returns a list of strings containing the names of
the methods this object contains</td></tr>
<tr><td>":classof"</td><td>Returns the name of the class this object belongs
<tr><td>":classof"</td><td>Returns the name of the class this object belongs
to.</td></tr>
<tr><td>":parents"</td><td>Returns a list of all direct parent classes which
have been wrapped by SWIG.</td></tr>
@ -603,8 +606,8 @@ have been wrapped by SWIG.</td></tr>
indicated parent class. This is mainly used internally by the SWIG module,
but may be useful to client programs.</td></tr>
<tr><td>"[member-variable]"</td><td>Each member variable is wrapped as a
method with an optional parameter.
Called with one argument, the member variable is set to the value of the
method with an optional parameter.
Called with one argument, the member variable is set to the value of the
argument. With zero arguments, the value is returned.
</td></tr>
</table>
@ -615,7 +618,7 @@ the underlying pointer, so using create_[x]_from_ptr alters the
returned value for the same object.
</p>
<H4><a name="Ocaml_nn18"></a>29.2.4.1 STL vector and string Example</H4>
<H4><a name="Ocaml_nn18">31.2.4.1 STL vector and string Example</a></H4>
<p>
@ -637,7 +640,7 @@ length. Instead, use multiple returns, as in the argout_ref example.
%include &lt;stl.i&gt;
namespace std {
%template(StringVector) std::vector &lt; string &gt;;
%template(StringVector) std::vector &lt; string &gt;;
};
%include "example.h"
@ -652,12 +655,12 @@ Since there's a makefile in that directory, the example is easy to build.
<p>
Here's a sample transcript of an interactive session using a string vector
after making a toplevel (make toplevel). This example uses the camlp4
after making a toplevel (make toplevel). This example uses the camlp4
module.
</p>
<div class="code"><pre>
bash-2.05a$ ./example_top
bash-2.05a$ ./example_top
Objective Caml version 3.06
Camlp4 Parsing version 3.06
@ -685,17 +688,17 @@ C_list
- : Example.c_obj = C_void
# x '[1] ;;
- : Example.c_obj = C_string "spam"
# for i = 0 to (x -&gt; size() as int) - 1 do
print_endline ((x '[i to int]) as string)
# for i = 0 to (x -&gt; size() as int) - 1 do
print_endline ((x '[i to int]) as string)
done ;;
foo
bar
baz
- : unit = ()
#
#
</pre></div>
<H4><a name="Ocaml_nn19"></a>29.2.4.2 C++ Class Example</H4>
<H4><a name="Ocaml_nn19">31.2.4.2 C++ Class Example</a></H4>
<p>
@ -703,7 +706,7 @@ Here's a simple example using Trolltech's Qt Library:
</p>
<table border="1" bgcolor="#dddddd" summary="Qt Library example">
<tr><th><center>qt.i</center></th></tr>
<tr><th><center>qt.i</center></th></tr>
<tr><td><pre>
%module qt
%{
@ -712,20 +715,20 @@ Here's a simple example using Trolltech's Qt Library:
%}
class QApplication {
public:
QApplication( int argc, char **argv );
void setMainWidget( QWidget *widget );
void exec();
QApplication( int argc, char **argv );
void setMainWidget( QWidget *widget );
void exec();
};
class QPushButton {
public:
QPushButton( char *str, QWidget *w );
void resize( int x, int y );
void show();
QPushButton( char *str, QWidget *w );
void resize( int x, int y );
void show();
};
</pre></td></tr></table>
<H4><a name="Ocaml_nn20"></a>29.2.4.3 Compiling the example</H4>
<H4><a name="Ocaml_nn20">31.2.4.3 Compiling the example</a></H4>
<div class="code"><pre>
@ -733,9 +736,9 @@ bash-2.05a$ QTPATH=/your/qt/path
bash-2.05a$ for file in swig.mli swig.ml swigp4.ml ; do swig -ocaml -co $file ; done
bash-2.05a$ ocamlc -c swig.mli ; ocamlc -c swig.ml
bash-2.05a$ ocamlc -I `camlp4 -where` -pp "camlp4o pa_extend.cmo q_MLast.cmo" -c swigp4.ml
bash-2.05a$ swig -ocaml -c++ -I$QTPATH/include qt.i
bash-2.05a$ swig -ocaml -c++ -I$QTPATH/include qt.i
bash-2.05a$ mv qt_wrap.cxx qt_wrap.c
bash-2.05a$ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c
bash-2.05a$ ocamlc -c -ccopt -xc++ -ccopt -g -g -ccopt -I$QTPATH/include qt_wrap.c
bash-2.05a$ ocamlc -c qt.mli
bash-2.05a$ ocamlc -c qt.ml
bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
@ -743,11 +746,11 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
-L$QTPATH/lib -cclib -lqt
</pre></div>
<H4><a name="Ocaml_nn21"></a>29.2.4.4 Sample Session</H4>
<H4><a name="Ocaml_nn21">31.2.4.4 Sample Session</a></H4>
<div class="code"><pre>
bash-2.05a$ ./qt_top
bash-2.05a$ ./qt_top
Objective Caml version 3.06
Camlp4 Parsing version 3.06
@ -767,13 +770,13 @@ val hello : Qt.c_obj = C_obj &lt;fun&gt;
<p>
Assuming you have a working installation of QT, you will see a window
containing the string "hi" in a button.
containing the string "hi" in a button.
</p>
<H3><a name="Ocaml_nn22"></a>29.2.5 Director Classes</H3>
<H3><a name="Ocaml_nn22">31.2.5 Director Classes</a></H3>
<H4><a name="Ocaml_nn23"></a>29.2.5.1 Director Introduction</H4>
<H4><a name="Ocaml_nn23">31.2.5.1 Director Introduction</a></H4>
<p>
@ -800,7 +803,7 @@ class foo {
};
</pre></div>
<H4><a name="Ocaml_nn24"></a>29.2.5.2 Overriding Methods in Ocaml</H4>
<H4><a name="Ocaml_nn24">31.2.5.2 Overriding Methods in Ocaml</a></H4>
<p>
@ -828,7 +831,7 @@ In this example, I'll examine the objective caml code involved in providing
an overloaded class. This example is contained in Examples/ocaml/shapes.
</p>
<H4><a name="Ocaml_nn25"></a>29.2.5.3 Director Usage Example</H4>
<H4><a name="Ocaml_nn25">31.2.5.3 Director Usage Example</a></H4>
<table border="1" bgcolor="#dddddd" summary="Director usage example">
@ -845,14 +848,14 @@ let triangle_class pts ob meth args =
"cover" -&gt;
(match args with
C_list [ x_arg ; y_arg ] -&gt;
let xa = x_arg as float
and ya = y_arg as float in
(point_in_triangle pts xa ya) to bool
let xa = x_arg as float
and ya = y_arg as float in
(point_in_triangle pts xa ya) to bool
| _ -&gt; raise (Failure "cover needs two double arguments."))
| _ -&gt; (invoke ob) meth args ;;
let triangle =
new_derived_object
new_derived_object
new_shape
(triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0)))
'() ;;
@ -887,7 +890,7 @@ in a more effortless style in ocaml, while leaving the "engine" part of the
program in C++.
</p>
<H4><a name="Ocaml_nn26"></a>29.2.5.4 Creating director objects</H4>
<H4><a name="Ocaml_nn26">31.2.5.4 Creating director objects</a></H4>
<p>
@ -896,7 +899,7 @@ The definition of the actual object triangle can be described this way:
<div class="code"><pre>
let triangle =
new_derived_object
new_derived_object
new_shape
(triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0)))
'()
@ -904,13 +907,13 @@ let triangle =
<p>
The first argument to <tt>new_derived_object</tt>, new_shape is the method
which returns a shape instance. This function will be invoked with the
which returns a shape instance. This function will be invoked with the
third argument will be appended to the argument list [ C_void ]. In the
example, the actual argument list is sent as (C_list [ C_void ; C_void ]).
The augmented constructor for a director class needs the first argument
to determine whether it is being constructed as a derived object, or as
an object of the indicated type only (in this case <tt>shape</tt>). The
Second argument is a closure that will be added to the final C_obj.
Second argument is a closure that will be added to the final C_obj.
</p>
<p>
@ -928,7 +931,7 @@ object from causing a core dump, as long as the object is destroyed
properly.
</p>
<H4><a name="Ocaml_nn27"></a>29.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<H4><a name="Ocaml_nn27">31.2.5.5 Typemaps for directors, directorin, directorout, directorargout</a></H4>
<p>
@ -939,7 +942,7 @@ well as a function return value in the same way you provide function arguments,
and to receive arguments the same way you normally receive function returns.
</p>
<H4><a name="Ocaml_nn28"></a>29.2.5.6 <tt>directorin</tt> typemap</H4>
<H4><a name="Ocaml_nn28">31.2.5.6 typemap</a></H4>
<p>
@ -950,7 +953,7 @@ code receives when you are called. In general, a simple <tt>directorin</tt> typ
can use the same body as a simple <tt>out</tt> typemap.
</p>
<H4><a name="Ocaml_nn29"></a>29.2.5.7 <tt>directorout</tt> typemap</H4>
<H4><a name="Ocaml_nn29">31.2.5.7 directorout typemap</a></H4>
<p>
@ -961,7 +964,7 @@ for the same type, except when there are special requirements for object
ownership, etc.
</p>
<H4><a name="Ocaml_nn30"></a>29.2.5.8 <tt>directorargout</tt> typemap</H4>
<H4><a name="Ocaml_nn30">31.2.5.8 directorargout typemap</a></H4>
<p>
@ -978,7 +981,7 @@ In the event that you don't specify all of the necessary values, integral
values will read zero, and struct or object returns have undefined results.
</p>
<H3><a name="Ocaml_nn31"></a>29.2.6 Exceptions</H3>
<H3><a name="Ocaml_nn31">31.2.6 Exceptions</a></H3>
<p>

370
Doc/Manual/Octave.html
View file

@ -1,14 +1,15 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Octave</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Octave"></a>30 SWIG and Octave</H1>
<H1><a name="Octave">32 SWIG and Octave</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -33,6 +34,10 @@
<li><a href="#Octave_nn19">Class extension with %extend</a>
<li><a href="#Octave_nn20">C++ templates</a>
<li><a href="#Octave_nn21">C++ Smart Pointers</a>
<ul>
<li><a href="#Octave_smart_pointers_shared_ptr">The shared_ptr Smart Pointer</a>
<li><a href="#Octave_smart_pointers_generic">Generic Smart Pointers</a>
</ul>
<li><a href="#Octave_nn22">Directors (calling Octave from C++ code)</a>
<li><a href="#Octave_nn23">Threads</a>
<li><a href="#Octave_nn24">Memory management</a>
@ -55,18 +60,16 @@ More information can be found at <a href="http://www.gnu.org/software/octave/">O
Also, there are a dozen or so examples in the Examples/octave directory, and hundreds in the test suite (Examples/test-suite and Examples/test-suite/octave).
</p>
<H2><a name="Octave_nn2"></a>30.1 Preliminaries</H2>
<H2><a name="Octave_nn2">32.1 Preliminaries</a></H2>
<p>
The SWIG implemention was first based on Octave 2.9.12, so this is the minimum version required. Testing has only been done on Linux.
As of SWIG 3.0.7, the Octave module is regularly tested with Octave versions 3.2.4, 3.8.1, and 4.0.0.
Use of older Octave versions is not recommended, as these versions are no longer tested with SWIG.
The SWIG runtime exports the function <tt>swig_octave_prereq()</tt> for checking the version of Octave.
</p>
<p>
As of SWIG 2.0.5, the Octave module should work with Octave versions 3.0.5, 3.2.4, and 3.4.0.
</p>
<H2><a name="Octave_nn3"></a>30.2 Running SWIG</H2>
<H2><a name="Octave_nn3">32.2 Running SWIG</a></H2>
<p>
@ -74,7 +77,7 @@ Let's start with a very simple SWIG interface file, example.i:
</p>
<div class="code"><pre>
%module example
%module swigexample
%{
#include "example.h"
%}
@ -95,10 +98,10 @@ The <tt>-c++</tt> option is also required when wrapping C++ code:
<div class="shell"><pre>$ swig -octave -c++ -o example_wrap.cpp example.i </pre></div>
<p>
This creates a C++ source file <tt>example_wrap.cpp</tt>. A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
This creates a C++ source file "example_wrap.cpp". A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
</p>
<H3><a name="Octave_nn4"></a>30.2.1 Command-line options</H3>
<H3><a name="Octave_nn4">32.2.1 Command-line options</a></H3>
<p>
@ -110,21 +113,18 @@ Options specific to the Octave module are:
<pre>$ swig -octave -help
...
Octave Options (available with -octave)
-global - Load all symbols into the global namespace [default]
-globals <em>name</em> - Set <em>name</em> used to access C global variables [default: 'cvar']
- Use '.' to load C global variables into module namespace
-noglobal - Do not load all symbols into the global namespace
Use '.' to load C global variables into module namespace
-opprefix <em>str</em> - Prefix <em>str</em> for global operator functions [default: 'op_']
</pre></div>
<p>
The <em>-global</em> and <em>-noglobal</em> options determine whether the Octave module will load all symbols into the global namespace in addition to the global namespace.
The <em>-globals</em> option sets the name of the variable which is the namespace for C global variables exported by the module.
The special name "." loads C global variables into the module namespace, i.e. alongside C functions and structs exported by the module.
The <em>-opprefix</em> options sets the prefix of the names of global/friend <a href="#Octave_nn18">operator</a> functions.
</p>
<H3><a name="Octave_nn5"></a>30.2.2 Compiling a dynamic module</H3>
<H3><a name="Octave_nn5">32.2.2 Compiling a dynamic module</a></H3>
<p>
@ -138,7 +138,7 @@ $ mkoctfile example_wrap.cpp example.c
</pre></div>
<p>
where example.c is the file containing the gcd() implementation.
where "example.c" is the file containing the gcd() implementation.
</p>
<p>
@ -146,12 +146,12 @@ $ mkoctfile example_wrap.cpp example.c
</p>
<p>
mkoctfile will produce example.oct, which contains the compiled extension module. Loading it into Octave is then a matter of invoking
mkoctfile will produce "swigexample.oct", which contains the compiled extension module. Loading it into Octave is then a matter of invoking
</p>
<div class="targetlang"><pre>octave:1&gt; example</pre></div>
<div class="targetlang"><pre>octave:1&gt; swigexample</pre></div>
<H3><a name="Octave_nn6"></a>30.2.3 Using your module</H3>
<H3><a name="Octave_nn6">32.2.3 Using your module</a></H3>
<p>
@ -160,75 +160,42 @@ Assuming all goes well, you will be able to do this:
</p>
<div class="targetlang"><pre>$ octave -q
octave:1&gt; example
octave:2&gt; example.gcd(4,6)
octave:1&gt; swigexample
octave:2&gt; swigexample.gcd(4,6)
ans = 2
octave:3&gt; example.cvar.Foo
octave:3&gt; swigexample.cvar.Foo
ans = 3
octave:4&gt; example.cvar.Foo=4;
octave:5&gt; example.cvar.Foo
octave:4&gt; swigexample.cvar.Foo=4;
octave:5&gt; swigexample.cvar.Foo
ans = 4 </pre></div>
<H2><a name="Octave_nn7"></a>30.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Octave_nn7">32.3 A tour of basic C/C++ wrapping</a></H2>
<H3><a name="Octave_nn8"></a>30.3.1 Modules</H3>
<H3><a name="Octave_nn8">32.3.1 Modules</a></H3>
<p>
The SWIG module directive specifies the name of the Octave module. If you specify `module example', then in Octave everything in the module will be accessible under "example", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
The SWIG module directive specifies the name of the Octave module. If you specify "module swigexample", then in Octave everything in the module will be accessible under "swigexample", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
</p>
<p>
When Octave is asked to invoke <tt>example</tt>, it will try to find the .m or .oct file that defines the function "example". It will thusly find example.oct, that upon loading will register all of the module's symbols.
When Octave is asked to invoke <tt>swigexample</tt>, it will try to find the ".m" or ".oct" file that defines the function "swigexample". You therefore need to make sure that "swigexample.oct" is in Octave's search path, which can be specified with the environment variable "OCTAVE_PATH".
</p>
<p>
An Octave module takes three options, <em>-global</em>, <em>-noglobal</em>, and <em>-globals</em>, which behave the same as the corresponding swig <a href="#Octave_nn4">command-line options</a>.
Here are some example usages:
To load an Octave module, simply type its name:
</p>
<div class="targetlang"><pre>
octave:1&gt; example -help
usage: example [-global|-noglobal] [-globals &lt;name&gt;]
octave:2&gt; example -global
octave:3&gt; gcd(4,6)
<div class="targetlang"><pre>
octave:1&gt; swigexample;
octave:2&gt; gcd(4,6)
ans = 2
octave:4&gt; cvar.Foo
ans = 3
octave:5&gt; cvar.Foo=4;
octave:6&gt; cvar.Foo
ans = 4
</pre></div>
<br>
<div class="targetlang"><pre>
octave:1&gt; example -noglobal
octave:2&gt; gcd(6,9)
ans = 3
octave:3&gt; cvar.Foo
error: `cvar' undefined near line 3 column 1
octave:3&gt; example.cvar.Foo
ans = 3
</pre></div>
<br>
<div class="targetlang"><pre>
octave:1&gt; example -globals mycvar
octave:2&gt; cvar.Foo
error: `cvar' undefined near line 2 column 1
octave:2&gt; mycvar.Foo
ans = 3
</pre></div>
<p>
It is also possible to rename the module / global variables namespaces with an assignment, as in: <br>
<div class="targetlang"><pre>
octave:1&gt; example
octave:2&gt; c=example;
octave:3&gt; c.gcd(10,4)
ans = 2
octave:4&gt; some_vars = cvar;
octave:5&gt; some_vars.Foo
ans = 3
octave:4&gt; cvar.Foo=4;
octave:5&gt; cvar.Foo
ans = 4
</pre></div>
<p>
@ -238,64 +205,64 @@ If the module is also used in the base context, however, it must first be loaded
<div class="targetlang"><pre>
octave:1&gt; function l = my_lcm(a,b)
&gt; example
&gt; l = abs(a*b)/example.gcd(a,b);
&gt; swigexample
&gt; l = abs(a*b)/swigexample.gcd(a,b);
&gt; endfunction
octave:2&gt; my_lcm(4,6)
ans = 12
octave:3&gt; example.gcd(4,6)
octave:3&gt; swigexample.gcd(4,6)
error: can't perform indexing operations for &lt;unknown type&gt; type
octave:3&gt; example;
octave:4&gt; example.gcd(4,6)
octave:3&gt; swigexample;
octave:4&gt; swigexample.gcd(4,6)
ans = 2
</pre></div>
<H3><a name="Octave_nn9"></a>30.3.2 Functions</H3>
<H3><a name="Octave_nn9">32.3.2 Functions</a></H3>
<p>
Global functions are wrapped as new Octave built-in functions. For example,
</p>
<div class="code"><pre>&#037;module example
<div class="code"><pre>&#037;module swigexample
int fact(int n); </pre></div>
<p>
creates a built-in function <tt>example.fact(n)</tt> that works exactly like you think it does:
creates a built-in function <tt>swigexample.fact(n)</tt> that works exactly like you think it does:
</p>
<div class="targetlang"><pre>octave:1&gt; example.fact(4)
<div class="targetlang"><pre>octave:1&gt; swigexample.fact(4)
24 </pre></div>
<H3><a name="Octave_nn10"></a>30.3.3 Global variables</H3>
<H3><a name="Octave_nn10">32.3.3 Global variables</a></H3>
<p>
Global variables are a little special in Octave. Given a global variable:
</p>
<div class="code"><pre>%module example
<div class="code"><pre>%module swigexample
extern double Foo;
</pre></div>
</pre></div>
<p>
To expose variables, SWIG actually generates two functions, to get and set the value. In this case, Foo_set and Foo_set would be generated. SWIG then automatically calls these functions when you get and set the variable-- in the former case creating a local copy in the interpreter of the C variables, and in the latter case copying an interpreter variables onto the C variable.
</p>
<div class="targetlang"><pre>octave:1&gt; example;
octave:2&gt; c=example.cvar.Foo
<div class="targetlang"><pre>octave:1&gt; swigexample;
octave:2&gt; c=swigexample.cvar.Foo
c = 3
octave:3&gt; example.cvar.Foo=4;
octave:3&gt; swigexample.cvar.Foo=4;
octave:4&gt; c
c = 3
octave:5&gt; example.cvar.Foo
octave:5&gt; swigexample.cvar.Foo
ans = 4</pre></div>
<p>
If a variable is marked with the %immutable directive then any attempts to set this variable will cause an Octave error. Given a global variable:
</p>
<div class="code"><pre>%module example
<div class="code"><pre>%module swigexample
%immutable;
extern double Foo;
%mutable;
@ -305,8 +272,8 @@ extern double Foo;
SWIG will allow the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
</p>
<div class="targetlang"><pre>octave:1&gt; example
octave:2&gt; example.Foo=4
<div class="targetlang"><pre>octave:1&gt; swigexample
octave:2&gt; swigexample.Foo=4
error: attempt to set immutable member variable
error: assignment failed, or no method for `swig_type = scalar'
error: evaluating assignment expression near line 2, column 12 </pre></div>
@ -315,19 +282,19 @@ error: evaluating assignment expression near line 2, column 12 </pre></div>
It is possible to add new functions or variables to the module. This also allows the user to rename/remove existing functions and constants (but not linked variables, mutable or immutable). Therefore users are recommended to be careful when doing so.
</p>
<div class="targetlang"><pre>octave:1&gt; example;
octave:2&gt; example.PI=3.142;
octave:3&gt; example.PI
<div class="targetlang"><pre>octave:1&gt; swigexample;
octave:2&gt; swigexample.PI=3.142;
octave:3&gt; swigexample.PI
ans = 3.1420 </pre></div>
<H3><a name="Octave_nn11"></a>30.3.4 Constants and enums</H3>
<H3><a name="Octave_nn11">32.3.4 Constants and enums</a></H3>
<p>
Because Octave doesn't really have the concept of constants, C/C++ constants are not really constant in Octave. They are actually just a copy of the value into the Octave interpreter. Therefore they can be changed just as any other value. For example given some constants:
</p>
<div class="code"><pre>%module example
<div class="code"><pre>%module swigexample
%constant int ICONST=42;
#define SCONST "Hello World"
enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
@ -337,12 +304,12 @@ enum Days{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
This is 'effectively' converted into the following Octave code:
</p>
<div class="targetlang"><pre>example.ICONST=42
example.SCONST="Hello World"
example.SUNDAY=0
<div class="targetlang"><pre>swigexample.ICONST=42
swigexample.SCONST="Hello World"
swigexample.SUNDAY=0
.... </pre></div>
<H3><a name="Octave_nn12"></a>30.3.5 Pointers</H3>
<H3><a name="Octave_nn12">32.3.5 Pointers</a></H3>
<p>
@ -350,7 +317,7 @@ example.SUNDAY=0
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with incomplete type information. Given a wrapping of the &lt;file.h&gt; interface:
</p>
<div class="code"><pre>%module example
<div class="code"><pre>%module swigexample
FILE *fopen(const char *filename, const char *mode);
int fputs(const char *, FILE *);
int fclose(FILE *);
@ -361,18 +328,18 @@ When wrapped, you will be able to use the functions in a natural way from Octave
</p>
<div class="targetlang"><pre>
octave:1&gt; example;
octave:2&gt; f=example.fopen("w","junk");
octave:3&gt; example.fputs("Hello world",f);
octave:4&gt; example.fclose(f);
octave:1&gt; swigexample;
octave:2&gt; f=swigexample.fopen("w","junk");
octave:3&gt; swigexample.fputs("Hello world",f);
octave:4&gt; swigexample.fclose(f);
</pre></div>
<p>
Simply printing the value of a wrapped C++ type will print it's typename. E.g.,
Simply printing the value of a wrapped C++ type will print its typename. E.g.,
</p>
<div class="targetlang"><pre>octave:1&gt; example;
octave:2&gt; f=example.fopen("junk","w");
<div class="targetlang"><pre>octave:1&gt; swigexample;
octave:2&gt; f=swigexample.fopen("junk","w");
octave:3&gt; f
f =
@ -384,12 +351,12 @@ f =
As the user of the pointer, you are responsible for freeing it, or closing any resources associated with it (just as you would in a C program). This does not apply so strictly to classes and structs (see below).
</p>
<div class="targetlang"><pre>octave:1&gt; example;
octave:2&gt; f=example.fopen("not there","r");
<div class="targetlang"><pre>octave:1&gt; swigexample;
octave:2&gt; f=swigexample.fopen("not there","r");
error: value on right hand side of assignment is undefined
error: evaluating assignment expression near line 2, column 2 </pre></div>
<H3><a name="Octave_nn13"></a>30.3.6 Structures and C++ classes</H3>
<H3><a name="Octave_nn13">32.3.6 Structures and C++ classes</a></H3>
<p>
@ -407,8 +374,8 @@ For each wrapped structure and class, a <tt>swig_ref</tt> will be exposed that h
</p>
<div class="targetlang">
<pre>octave:1&gt; example;
octave:2&gt; p=example.Point();
<pre>octave:1&gt; swigexample;
octave:2&gt; p=swigexample.Point();
octave:3&gt; p.x=3;
octave:4&gt; p.y=5;
octave:5&gt; p.x, p.y
@ -442,9 +409,9 @@ public:
can be used from Octave like this
</p>
<div class="targetlang">
<pre>octave:1&gt; example;
octave:2&gt; p1=example.Point(3,5);
octave:3&gt; p2=example.Point(1,2);
<pre>octave:1&gt; swigexample;
octave:2&gt; p1=swigexample.Point(3,5);
octave:3&gt; p2=swigexample.Point(1,2);
octave:4&gt; p1.distance(p2)
ans = 3.6056
</pre></div>
@ -524,7 +491,7 @@ ans = 1
Depending on the ownership setting of a <tt>swig_ref</tt>, it may call C++ destructors when its reference count goes to zero. See the section on memory management below for details.
</p>
<H3><a name="Octave_nn15"></a>30.3.7 C++ inheritance</H3>
<H3><a name="Octave_nn15">32.3.7 C++ inheritance</a></H3>
<p>
@ -533,7 +500,7 @@ This information contains the full class hierarchy. When an indexing operation (
the tree is walked to find a match in the current class as well as any of its bases. The lookup is then cached in the <tt>swig_ref</tt>.
</p>
<H3><a name="Octave_nn17"></a>30.3.8 C++ overloaded functions</H3>
<H3><a name="Octave_nn17">32.3.8 C++ overloaded functions</a></H3>
<p>
@ -543,7 +510,7 @@ The dispatch function selects which overload to call (if any) based on the passe
<tt>typecheck</tt> typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details.
</p>
<H3><a name="Octave_nn18"></a>30.3.9 C++ operators</H3>
<H3><a name="Octave_nn18">32.3.9 C++ operators</a></H3>
<p>
@ -551,7 +518,7 @@ C++ operator overloading is supported, in a way similar to other modules.
The <tt>swig_ref</tt> type supports all unary and binary operators between itself and all other types that exist in the system at module load time. When an operator is used (where one of the operands is a <tt>swig_ref</tt>), the runtime routes the call to either a member function of the given object, or to a global function whose named is derived from the types of the operands (either both or just the lhs or rhs).
</p>
<p>
For example, if <tt>a</tt> and <tt>b</tt> are SWIG variables in Octave, <tt>a+b</tt> becomes <tt>a.__add(b)</tt>. The wrapper is then free to implement __add to do whatever it wants. A wrapper may define the <tt>__add</tt> function manually, %rename some other function to it, or %rename a C++ operator to it.
For example, if <tt>a</tt> and <tt>b</tt> are SWIG variables in Octave, <tt>a+b</tt> becomes <tt>a.__add__(b)</tt>. The wrapper is then free to implement __add__ to do whatever it wants. A wrapper may define the <tt>__add__</tt> function manually, %rename some other function to it, or %rename a C++ operator to it.
</p>
<p>
By default the C++ operators are renamed to their corresponding Octave operators. So without doing any work, the following interface
@ -578,87 +545,87 @@ assert(c.value==5);
Octave operators are mapped in the following way:
</p>
<div class="code"><pre>
__brace a{args}
__brace_asgn a{args} = rhs
__paren a(args)
__paren_asgn a(args) = rhs
__str generates string rep
__not !a
__uplus +a
__uminus -a
__transpose a.'
__hermitian a'
__incr a++
__decr a--
__add a + b
__sub a - b
__mul a * b
__div a / b
__pow a ^ b
__ldiv a \ b
__lshift a << b
__rshift a >> b
__lt a < b
__le a <= b
__eq a == b
__ge a >= b
__gt a > b
__ne a != b
__el_mul a .* b
__el_div a ./ b
__el_pow a .^ b
__el_ldiv a .\ b
__el_and a &amp; b
__el_or a | b
__brace__ a{args}
__brace_asgn__ a{args} = rhs
__paren__ a(args)
__paren_asgn__ a(args) = rhs
__str__ generates string rep
__not__ !a
__uplus__ +a
__uminus__ -a
__transpose__ a.'
__hermitian__ a'
__incr__ a++
__decr__ a--
__add__ a + b
__sub__ a - b
__mul__ a * b
__div__ a / b
__pow__ a ^ b
__ldiv__ a \ b
__lshift__ a << b
__rshift__ a >> b
__lt__ a < b
__le__ a <= b
__eq__ a == b
__ge__ a >= b
__gt__ a > b
__ne__ a != b
__el_mul__ a .* b
__el_div__ a ./ b
__el_pow__ a .^ b
__el_ldiv__ a .\ b
__el_and__ a &amp; b
__el_or__ a | b
</pre></div>
<p>
On the C++ side, the default mappings are as follows:
</p>
<div class="code"><pre>
%rename(__add) *::operator+;
%rename(__add) *::operator+();
%rename(__add) *::operator+() const;
%rename(__sub) *::operator-;
%rename(__uminus) *::operator-();
%rename(__uminus) *::operator-() const;
%rename(__mul) *::operator*;
%rename(__div) *::operator/;
%rename(__mod) *::operator%;
%rename(__lshift) *::operator<<;
%rename(__rshift) *::operator>>;
%rename(__el_and) *::operator&amp;&amp;;
%rename(__el_or) *::operator||;
%rename(__xor) *::operator^;
%rename(__invert) *::operator~;
%rename(__lt) *::operator<;
%rename(__le) *::operator<=;
%rename(__gt) *::operator>;
%rename(__ge) *::operator>=;
%rename(__eq) *::operator==;
%rename(__ne) *::operator!=;
%rename(__not) *::operator!;
%rename(__incr) *::operator++;
%rename(__decr) *::operator--;
%rename(__paren) *::operator();
%rename(__brace) *::operator[];
%rename(__add__) *::operator+;
%rename(__add__) *::operator+();
%rename(__add__) *::operator+() const;
%rename(__sub__) *::operator-;
%rename(__uminus__) *::operator-();
%rename(__uminus__) *::operator-() const;
%rename(__mul__) *::operator*;
%rename(__div__) *::operator/;
%rename(__mod__) *::operator%;
%rename(__lshift__) *::operator<<;
%rename(__rshift__) *::operator>>;
%rename(__el_and__) *::operator&amp;&amp;;
%rename(__el_or__) *::operator||;
%rename(__xor__) *::operator^;
%rename(__invert__) *::operator~;
%rename(__lt__) *::operator<;
%rename(__le__) *::operator<=;
%rename(__gt__) *::operator>;
%rename(__ge__) *::operator>=;
%rename(__eq__) *::operator==;
%rename(__ne__) *::operator!=;
%rename(__not__) *::operator!;
%rename(__incr__) *::operator++;
%rename(__decr__) *::operator--;
%rename(__paren__) *::operator();
%rename(__brace__) *::operator[];
</pre></div>
<p>
Octave can also utilise friend (i.e. non-member) operators with a simple %rename: see the example in the Examples/octave/operator directory.
</p>
<H3><a name="Octave_nn19"></a>30.3.10 Class extension with %extend</H3>
<H3><a name="Octave_nn19">32.3.10 Class extension with %extend</a></H3>
<p>
The %extend directive works the same as in other modules.
</p>
<p>
You can use it to define special behavior, like for example defining Octave operators not mapped to C++ operators, or defining certain Octave mechanisms such as how an object prints. For example, the <tt>octave_value::{is_string,string_value,print}</tt> functions are routed to a special method <tt>__str</tt> that can be defined inside an %extend.
You can use it to define special behavior, like for example defining Octave operators not mapped to C++ operators, or defining certain Octave mechanisms such as how an object prints. For example, the <tt>octave_value::{is_string,string_value,print}</tt> functions are routed to a special method <tt>__str__</tt> that can be defined inside an %extend.
</p>
<div class="code"><pre>
%extend A {
string __str() {
string __str__() {
stringstream sout;
sout&lt;&lt;$self->value;
return sout.str();
@ -674,10 +641,19 @@ octave:2&gt; a
a = 4
octave:3&gt; printf("%s\n",a);
4
octave:4&gt; a.__str()
octave:4&gt; a.__str__()
4
</pre></div>
<H3><a name="Octave_nn20"></a>30.3.11 C++ templates</H3>
<p>
Similarly, Octave can use the <tt>__float__</tt> method to convert an object to a numeric value.
</p>
<p>
Octave 3.8.0 and later versions will also map unary functions X() to the corresponding <tt>__X__</tt> method, where X includes: abs(), acos(), acosh(), angle(), arg(), asin(), asinh(), atan(), atanh(), cbrt(), ceil(), conj(), cos(), cosh(), dawson(), erf(), erfc(), erfcinv(), erfcx(), erfi(), erfinv(), exp(), expm1(), finite(), fix(), floor(), gamma(), imag(), isalnum(), isalpha(), isascii(), iscntrl(), isdigit(), isgraph(), isinf(), islower(), isna(), isnan(), isprint(), ispunct(), isspace(), isupper(), isxdigit(), lgamma(), log(), log10(), log1p(), log2(), real(), round(), roundb(), signbit(), signum(), sin(), sinh(), sqrt(), tan(), tanh(), toascii(), tolower(), toupper()
</p>
<H3><a name="Octave_nn20">32.3.11 C++ templates</a></H3>
<p>
@ -685,7 +661,7 @@ C++ class and function templates are fully supported as in other modules, in tha
For example, function templates can be instantiated as follows:
</p>
<div class="code"><pre>%module example
<div class="code"><pre>%module swigexample
%inline {
template&lt;class __scalar&gt;
__scalar mul(__scalar a,__scalar b) {
@ -713,7 +689,7 @@ ans = 22 + 46i
Similarly, class templates can be instantiated as in the following example,
</p>
<div class="code"><pre>%module example
<div class="code"><pre>%module swigexample
%include &lt;std_complex.i&gt;
%include &lt;std_string.i&gt;
%inline {
@ -726,7 +702,7 @@ Similarly, class templates can be instantiated as in the following example,
s+=_s;
return *this;
}
std::string __str() const {
std::string __str__() const {
std::stringstream sout;
sout&lt;&lt;s;
return sout.str();
@ -754,14 +730,28 @@ ans =
</pre></div>
<H3><a name="Octave_nn21"></a>30.3.12 C++ Smart Pointers</H3>
<H3><a name="Octave_nn21">32.3.12 C++ Smart Pointers</a></H3>
<H4><a name="Octave_smart_pointers_shared_ptr">32.3.12.1 The shared_ptr Smart Pointer</a></H4>
<p>
The C++11 standard provides <tt>std::shared_ptr</tt> which was derived from the Boost
implementation, <tt>boost::shared_ptr</tt>.
Both of these are available for Octave in the SWIG library and usage is outlined
in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a> library section.
</p>
<H4><a name="Octave_smart_pointers_generic">32.3.12.2 Generic Smart Pointers</a></H4>
<p>
C++ smart pointers are fully supported as in other modules.
</p>
<H3><a name="Octave_nn22"></a>30.3.13 Directors (calling Octave from C++ code)</H3>
<H3><a name="Octave_nn22">32.3.13 Directors (calling Octave from C++ code)</a></H3>
<p>
@ -842,14 +832,14 @@ c-side routine called
octave-side routine called
</pre></div>
<H3><a name="Octave_nn23"></a>30.3.14 Threads</H3>
<H3><a name="Octave_nn23">32.3.14 Threads</a></H3>
<p>
The use of threads in wrapped Director code is not supported; i.e., an Octave-side implementation of a C++ class must be called from the Octave interpreter's thread. Anything fancier (apartment/queue model, whatever) is left to the user. Without anything fancier, this amounts to the limitation that Octave must drive the module... like, for example, an optimization package that calls Octave to evaluate an objective function.
</p>
<H3><a name="Octave_nn24"></a>30.3.15 Memory management</H3>
<H3><a name="Octave_nn24">32.3.15 Memory management</a></H3>
<p>
@ -883,14 +873,14 @@ The %newobject directive may be used to control this behavior for pointers retur
In the case where one wishes for the C++ side to own an object that was created in Octave (especially a Director object), one can use the __disown() method to invert this logic. Then letting the Octave reference count go to zero will not destroy the object, but destroying the object will invalidate the Octave-side object if it still exists (and call destructors of other C++ bases in the case of multiple inheritance/<tt>subclass()</tt>'ing).
</p>
<H3><a name="Octave_nn25"></a>30.3.16 STL support</H3>
<H3><a name="Octave_nn25">32.3.16 STL support</a></H3>
<p>
Various STL library files are provided for wrapping STL containers.
</p>
<H3><a name="Octave_nn26"></a>30.3.17 Matrix typemaps</H3>
<H3><a name="Octave_nn26">32.3.17 Matrix typemaps</a></H3>
<p>

672
Doc/Manual/Perl5.html
View file

File diff suppressed because it is too large Load diff

166
Doc/Manual/Php.html
View file

@ -1,13 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Hand crafted HTML -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and PHP</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Php"></a>32 SWIG and PHP</H1>
<H1><a name="Php">34 SWIG and PHP</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -25,10 +25,11 @@
<li><a href="#Php_nn2_5">Pointers and References</a>
<li><a href="#Php_nn2_6">Structures and C++ classes</a>
<ul>
<li><a href="#Php_nn2_6_1">Using <tt>-noproxy</tt></a>
<li><a href="#Php_nn2_6_1">Using -noproxy</a>
<li><a href="#Php_nn2_6_2">Constructors and Destructors</a>
<li><a href="#Php_nn2_6_3">Static Member Variables</a>
<li><a href="#Php_nn2_6_4">Static Member Functions</a>
<li><a href="#Php_nn2_6_5">Specifying Implemented Interfaces</a>
</ul>
<li><a href="#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a>
</ul>
@ -79,7 +80,7 @@ your extension into php directly, you will need the complete PHP source tree
available.
</p>
<H2><a name="Php_nn1"></a>32.1 Generating PHP Extensions</H2>
<H2><a name="Php_nn1">34.1 Generating PHP Extensions</a></H2>
<p>
@ -113,9 +114,7 @@ more detail in <a href="#Php_nn2_6">section 27.2.6</a>.
<p>
The usual (and recommended) way is to build the extension as a separate
dynamically loaded module (which is supported by all modern operating
systems). You can then specify that this be loaded
automatically in <tt>php.ini</tt> or load it explicitly for any script which
needs it.
systems).
</p>
<p>
@ -126,7 +125,7 @@ and it doesn't play nicely with package system. We don't recommend
this approach, or provide explicit support for it.
</p>
<H3><a name="Php_nn1_1"></a>32.1.1 Building a loadable extension</H3>
<H3><a name="Php_nn1_1">34.1.1 Building a loadable extension</a></H3>
<p>
@ -137,42 +136,59 @@ least work for Linux though):
</p>
<div class="code"><pre>
gcc `php-config --includes` -fpic -c example_wrap.c
gcc -shared example_wrap.o -o example.so
gcc `php-config --includes` -fpic -c example_wrap.c example.c
gcc -shared example_wrap.o example.o -o example.so
</pre></div>
<H3><a name="Php_nn1_3"></a>32.1.2 Using PHP Extensions</H3>
<H3><a name="Php_nn1_3">34.1.2 Using PHP Extensions</a></H3>
<p>
To test the extension from a PHP script, you need to load it first. You
can load it for every script by adding this line the <tt>[PHP]</tt> section of
To test the extension from a PHP script, you first need to tell PHP to
load it. To do this, add a line like this to the <tt>[PHP]</tt> section of
<tt>php.ini</tt>:
</p>
<div class="code"><pre>
extension=/path/to/modulename.so
extension=/path/to/modulename.so
</pre></div>
<p>
Alternatively, you can load it explicitly only for scripts which need it
by adding this line:
If the module is in PHP's default extension directory, you can omit the path.
</p>
<p>
For some SAPIs (for example, the CLI SAPI) you can instead use the
<a href="http://php.net/manual/en/function.dl.php">dl() function</a> to load
an extension at run time, by adding a like like this to the start of each
PHP script which uses your extension:
</p>
<div class="code"><pre>
dl("/path/to/modulename.so"); // Load the module
dl("/path/to/modulename.so"); // Load the module
</pre></div>
<p>
to the start of each PHP file. SWIG also generates a php module, which
attempts to do the <tt>dl()</tt> call for you:
But note that this doesn't work when running PHP through a webserver in PHP5.3
and later - you'll need to use <tt>extension</tt> in <tt>php.ini</tt> as
described above.
</p>
<p>
The PHP module which SWIG generates will also attempt to do the <tt>dl()</tt>
call for you if the extension isn't already loaded:
</p>
<div class="code"><pre>
include("example.php");
include("example.php");
</pre></div>
<H2><a name="Php_nn2"></a>32.2 Basic PHP interface</H2>
<p>
This PHP module also defines the PHP classes for the wrapped API, so you'll
almost certainly want to include it anyway.
</p>
<H2><a name="Php_nn2">34.2 Basic PHP interface</a></H2>
<p>
@ -183,7 +199,7 @@ other symbols unless care is taken to <tt>%rename</tt> them. At present
SWIG doesn't have support for the namespace feature added in PHP 5.3.
</p>
<H3><a name="Php_nn2_1"></a>32.2.1 Constants</H3>
<H3><a name="Php_nn2_1">34.2.1 Constants</a></H3>
<p>
@ -220,9 +236,9 @@ echo "E = " . E . "\n";
<p>
There's one peculiarity of how constants work in PHP which it is useful
to note (this is not specific to SWIG though) - if you try to use an undeclared
constant, PHP will issue a warning and then expand the constant to a string
version of the constant's name. The warning will often be missed though as
if you're using PHP in a webserver, it will probably end up in error.log or
constant, PHP will emit a notice and then expand the constant to a string
version of the constant's name. Unfortunately it is easy to miss the notice
if you're using PHP in a webserver, as it will probably end up in error.log or
similar.
</p>
@ -233,7 +249,7 @@ For example,
<div class="code"><pre>
%module example
#define EASY_TO_MISPELL 0
#define EASY_TO_MISPELL 0
</pre>
</div>
@ -246,9 +262,9 @@ accessed incorrectly in PHP,
include("example.php");
if(EASY_TO_MISPEL) {
....
...
} else {
....
...
}
</pre>
@ -260,7 +276,7 @@ is treated as true by the if test, when the value of the intended constant
would be treated as false!
</p>
<H3><a name="Php_nn2_2"></a>32.2.2 Global Variables</H3>
<H3><a name="Php_nn2_2">34.2.2 Global Variables</a></H3>
<p>
@ -287,7 +303,7 @@ is accessed as follows:
<div class="code"><pre>
include("example.php");
print seki_get();
seki_set( seki_get() * 2); # The C variable is now 4.
seki_set( seki_get() * 2); # The C variable is now 4.
print seki_get();
</pre></div>
@ -309,7 +325,7 @@ undefined.
At this time SWIG does not support custom accessor methods.
</p>
<H3><a name="Php_nn2_3"></a>32.2.3 Functions</H3>
<H3><a name="Php_nn2_3">34.2.3 Functions</a></H3>
<p>
@ -332,7 +348,7 @@ Will be accessed in PHP like this :
include("example.php");
$a = foo(2);
$b = bar(3.5, -1.5);
$c = bar(3.5); # Use default argument for 2nd parameter
$c = bar(3.5); # Use default argument for 2nd parameter
</pre></div>
@ -362,7 +378,7 @@ print $s; # The value of $s was not changed.
-->
<H3><a name="Php_nn2_4"></a>32.2.4 Overloading</H3>
<H3><a name="Php_nn2_4">34.2.4 Overloading</a></H3>
<p>
@ -418,7 +434,7 @@ taking the integer argument.
</p>
-->
<H3><a name="Php_nn2_5"></a>32.2.5 Pointers and References</H3>
<H3><a name="Php_nn2_5">34.2.5 Pointers and References</a></H3>
<p>
@ -503,7 +519,20 @@ echo "The sum $in1 + $in2 = $result\n";
Because PHP has a native concept of reference, it may seem more natural
to the PHP developer to use references to pass pointers. To enable
this, one needs to include <b>phppointers.i</b> which defines the
named typemap REFERENCE.
named typemap REF.
</p>
<p>
Prior to SWIG 3.0, the REF typemaps relied on PHP's call-time
pass-by-reference, which was deprecated in PHP 5.3 and removed in PHP 5.4.
So if you use these REF typemaps, you should ensure that SWIG&ge;3.0 is
used to generate wrappers from your interface file.
</p>
<p>
In case you write your own typemaps, SWIG supports an attribute called
<tt>byref</tt>: if you set that, then SWIG will make sure that the generated
wrapper function will want the input parameter as a reference.
</p>
<div class="code"><pre>
@ -526,7 +555,7 @@ include("example.php");
$in1 = 3;
$in2 = 5;
$result = 0;
add(&amp;$in1,&amp;$in2,&amp;$result);
add($in1,$in2,$result);
echo "The sum $in1 + $in2 = $result\n";
?&gt;
@ -550,7 +579,7 @@ PHP in a number of ways: by using <tt>unset</tt> on an existing
variable, or assigning <tt>NULL</tt> to a variable.
</p>
<H3><a name="Php_nn2_6"></a>32.2.6 Structures and C++ classes</H3>
<H3><a name="Php_nn2_6">34.2.6 Structures and C++ classes</a></H3>
<p>
@ -570,10 +599,10 @@ This interface file
class Vector {
public:
double x,y,z;
Vector();
~Vector();
double magnitude();
double x,y,z;
Vector();
~Vector();
double magnitude();
};
struct Complex {
@ -611,7 +640,7 @@ Would be used in the following way from PHP5:
Member variables and methods are accessed using the <tt>-&gt;</tt> operator.
</p>
<H4><a name="Php_nn2_6_1"></a>32.2.6.1 Using <tt>-noproxy</tt></H4>
<H4><a name="Php_nn2_6_1">34.2.6.1 Using -noproxy</a></H4>
<p>
@ -637,7 +666,7 @@ Complex_im_set($obj,$d);
Complex_im_get($obj);
</pre></div>
<H4><a name="Php_nn2_6_2"></a>32.2.6.2 Constructors and Destructors</H4>
<H4><a name="Php_nn2_6_2">34.2.6.2 Constructors and Destructors</a></H4>
<p>
@ -678,7 +707,7 @@ the programmer can either reassign the variable or call
<tt>unset($v)</tt>
</p>
<H4><a name="Php_nn2_6_3"></a>32.2.6.3 Static Member Variables</H4>
<H4><a name="Php_nn2_6_3">34.2.6.3 Static Member Variables</a></H4>
<p>
@ -693,7 +722,7 @@ returns the current value of the class variable. For example
%module example
class Ko {
static int threats;
static int threats;
};
</pre></div>
@ -705,7 +734,7 @@ would be accessed in PHP as,
<div class="code"><pre>
include("example.php");
echo "There has now been " . Ko::threats() . " threats\n";
echo "There have now been " . Ko::threats() . " threats\n";
</pre></div>
@ -718,10 +747,10 @@ function, e.g.
Ko::threats(10);
echo "There has now been " . Ko::threats() . " threats\n";
echo "There have now been " . Ko::threats() . " threats\n";
</pre></div>
<H4><a name="Php_nn2_6_4"></a>32.2.6.4 Static Member Functions</H4>
<H4><a name="Php_nn2_6_4">34.2.6.4 Static Member Functions</a></H4>
<p>
@ -743,7 +772,25 @@ Ko::threats();
</pre></div>
<H3><a name="Php_nn2_7"></a>32.2.7 PHP Pragmas, Startup and Shutdown code</H3>
<H4><a name="Php_nn2_6_5">34.2.6.5 Specifying Implemented Interfaces</a></H4>
<p>
PHP supports the concept of abstract interfaces which a class can implement.
Since SWIG 3.0.3, you can tell SWIG that a wrapped class (for example
<code>MyIterator</code>) implements the <code>Iterator</code> interface like
so:
</p>
<div class="code"><pre>
%typemap("phpinterfaces") MyIterator "Iterator";
</pre></div>
<p>
If there are multiple interfaces, just list them separated by commas.
</p>
<H3><a name="Php_nn2_7">34.2.7 PHP Pragmas, Startup and Shutdown code</a></H3>
<p>
@ -831,7 +878,7 @@ The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements are very similar but inse
into the request init (PHP_RINIT_FUNCTION) and request shutdown (PHP_RSHUTDOWN_FUNCTION) code respectively.
</p>
<H2><a name="Php_nn3"></a>32.3 Cross language polymorphism</H2>
<H2><a name="Php_nn3">34.3 Cross language polymorphism</a></H2>
<p>
@ -866,7 +913,7 @@ wrapper functions takes care of all the cross-language method routing
transparently.
</p>
<H3><a name="Php_nn3_1"></a>32.3.1 Enabling directors</H3>
<H3><a name="Php_nn3_1">34.3.1 Enabling directors</a></H3>
<p>
@ -895,9 +942,6 @@ globally, to specific classes, and to specific methods, like this:
// generate directors for all virtual methods in class Foo
%feature("director") Foo;
// generate a director for just Foo::bar()
%feature("director") Foo::bar;
</pre>
</div>
@ -958,7 +1002,7 @@ class MyFoo extends Foo {
</div>
<H3><a name="Php_nn3_2"></a>32.3.2 Director classes</H3>
<H3><a name="Php_nn3_2">34.3.2 Director classes</a></H3>
@ -1038,7 +1082,7 @@ so there is no need for the extra overhead involved with routing the
calls through PHP.
</p>
<H3><a name="Php_nn3_3"></a>32.3.3 Ownership and object destruction</H3>
<H3><a name="Php_nn3_3">34.3.3 Ownership and object destruction</a></H3>
<p>
@ -1094,7 +1138,7 @@ In this example, we are assuming that FooContainer will take care of
deleting all the Foo pointers it contains at some point.
</p>
<H3><a name="Php_nn3_4"></a>32.3.4 Exception unrolling</H3>
<H3><a name="Php_nn3_4">34.3.4 Exception unrolling</a></H3>
<p>
@ -1153,7 +1197,7 @@ Swig::DirectorMethodException is thrown, PHP will register the exception
as soon as the C wrapper function returns.
</p>
<H3><a name="Php_nn3_5"></a>32.3.5 Overhead and code bloat</H3>
<H3><a name="Php_nn3_5">34.3.5 Overhead and code bloat</a></H3>
<p>
@ -1186,7 +1230,7 @@ optimized by selectively enabling director methods (using the %feature
directive) for only those methods that are likely to be extended in PHP.
</p>
<H3><a name="Php_nn3_6"></a>32.3.6 Typemaps</H3>
<H3><a name="Php_nn3_6">34.3.6 Typemaps</a></H3>
<p>
@ -1200,7 +1244,7 @@ need to be supported.
</p>
<H3><a name="Php_nn3_7"></a>32.3.7 Miscellaneous</H3>
<H3><a name="Php_nn3_7">34.3.7 Miscellaneous</a></H3>
<p> Director typemaps for STL classes are mostly in place, and hence you

27
Doc/Manual/Pike.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Pike</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Pike"></a>33 SWIG and Pike</H1>
<H1><a name="Pike">35 SWIG and Pike</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -46,10 +47,10 @@ least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
chapter.<br>
</p>
<H2><a name="Pike_nn2"></a>33.1 Preliminaries</H2>
<H2><a name="Pike_nn2">35.1 Preliminaries</a></H2>
<H3><a name="Pike_nn3"></a>33.1.1 Running SWIG</H3>
<H3><a name="Pike_nn3">35.1.1 Running SWIG</a></H3>
<p>
@ -94,7 +95,7 @@ can use the <tt>-o</tt> option:
<div class="code">
<pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
</div>
<H3><a name="Pike_nn4"></a>33.1.2 Getting the right header files</H3>
<H3><a name="Pike_nn4">35.1.2 Getting the right header files</a></H3>
<p>
@ -114,7 +115,7 @@ You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt>
and so on.
</p>
<H3><a name="Pike_nn5"></a>33.1.3 Using your module</H3>
<H3><a name="Pike_nn5">35.1.3 Using your module</a></H3>
<p>
@ -129,10 +130,10 @@ Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
(1) Result: 24
</pre></div>
<H2><a name="Pike_nn6"></a>33.2 Basic C/C++ Mapping</H2>
<H2><a name="Pike_nn6">35.2 Basic C/C++ Mapping</a></H2>
<H3><a name="Pike_nn7"></a>33.2.1 Modules</H3>
<H3><a name="Pike_nn7">35.2.1 Modules</a></H3>
<p>
@ -143,7 +144,7 @@ concerned), SWIG's <tt>%module</tt> directive doesn't really have any
significance.
</p>
<H3><a name="Pike_nn8"></a>33.2.2 Functions</H3>
<H3><a name="Pike_nn8">35.2.2 Functions</a></H3>
<p>
@ -168,7 +169,7 @@ exactly as you'd expect it to:
(1) Result: 24
</pre></div>
<H3><a name="Pike_nn9"></a>33.2.3 Global variables</H3>
<H3><a name="Pike_nn9">35.2.3 Global variables</a></H3>
<p>
@ -197,7 +198,7 @@ will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
(3) Result: 3.141590
</pre></div>
<H3><a name="Pike_nn10"></a>33.2.4 Constants and enumerated types</H3>
<H3><a name="Pike_nn10">35.2.4 Constants and enumerated types</a></H3>
<p>
@ -205,7 +206,7 @@ Enumerated types in C/C++ declarations are wrapped as Pike constants,
not as Pike enums.
</p>
<H3><a name="Pike_nn11"></a>33.2.5 Constructors and Destructors</H3>
<H3><a name="Pike_nn11">35.2.5 Constructors and Destructors</a></H3>
<p>
@ -213,7 +214,7 @@ Constructors are wrapped as <tt>create()</tt> methods, and destructors are
wrapped as <tt>destroy()</tt> methods, for Pike classes.
</p>
<H3><a name="Pike_nn12"></a>33.2.6 Static Members</H3>
<H3><a name="Pike_nn12">35.2.6 Static Members</a></H3>
<p>

272
Doc/Manual/Preface.html
View file

@ -1,31 +1,42 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Preface</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Preface"></a>1 Preface</H1>
<H1><a name="Preface">1 Preface</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Preface_nn2">Introduction</a>
<li><a href="#Preface_nn4">SWIG Versions</a>
<li><a href="#Preface_license">SWIG License</a>
<li><a href="#Preface_nn5">SWIG resources</a>
<li><a href="#Preface_nn6">Prerequisites</a>
<li><a href="#Preface_nn7">Organization of this manual</a>
<li><a href="#Preface_nn8">How to avoid reading the manual</a>
<li><a href="#Preface_nn9">Backwards compatibility</a>
<li><a href="#Preface_release_notes">Release notes</a>
<li><a href="#Preface_nn10">Credits</a>
<li><a href="#Preface_nn11">Bug reports</a>
<li><a href="#Preface_installation">Installation</a>
<ul>
<li><a href="#Preface_windows_installation">Windows installation</a>
<li><a href="#Preface_unix_installation">Unix installation</a>
<li><a href="#Preface_osx_installation">Macintosh OS X installation</a>
<li><a href="#Preface_testing">Testing</a>
<li><a href="#Preface_examples">Examples</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<H2><a name="Preface_nn2"></a>1.1 Introduction</H2>
<H2><a name="Preface_nn2">1.1 Introduction</a></H2>
<p>
@ -48,7 +59,7 @@ has since evolved into a general purpose tool that is used in a wide
variety of applications--in fact almost anything where C/C++ programming
is involved.
<H2><a name="Preface_nn4"></a>1.2 SWIG Versions</H2>
<H2><a name="Preface_nn4">1.2 SWIG Versions</a></H2>
<p>
@ -57,13 +68,26 @@ In the late 1990's, the most stable version of SWIG was release
over a period of 10 years starting from the year 2000. The final version in the 1.3.x
series was 1.3.40, but in truth the 1.3.x series had been stable for many years.
An official stable version was released along with the decision to make SWIG
license changes and this gave rise to version 2.0.0 in 2010. The license was clarified
license changes and this gave rise to version 2.0.0 in 2010.
</p>
<H2><a name="Preface_license">1.3 SWIG License</a></H2>
<p>
The LICENSE file shipped with SWIG in the top level directory contains the SWIG license.
For further insight into the license including the license of SWIG's output code, please visit
the SWIG legal page - <a href="http://www.swig.org/legal.html">http://www.swig.org/legal.html</a>.
</p>
<p>
The license was clarified in version 2.0.0
so that the code that SWIG generated could be distributed
under license terms of the user's choice/requirements and at the same time the SWIG
source was placed under the GNU General Public License version 3.
</p>
<H2><a name="Preface_nn5"></a>1.3 SWIG resources</H2>
<H2><a name="Preface_nn5">1.4 SWIG resources</a></H2>
<p>
@ -93,16 +117,17 @@ SWIG along with information about beta releases and future work.
</p>
<p>
Subversion access to the latest version of SWIG is also available. More information
Git and Subversion access to the latest version of SWIG is also available. More information
about this can be obtained at:
</p>
<div class="shell"><pre>
<a href="http://www.swig.org/svn.html">http://www.swig.org/svn.html</a>
<a href="http://www.swig.org/svn.html">SWIG Bleeding Edge</a>
</pre></div>
<H2><a name="Preface_nn6"></a>1.4 Prerequisites</H2>
<H2><a name="Preface_nn6">1.5 Prerequisites</a></H2>
<p>
@ -127,7 +152,7 @@ However, this isn't meant to be a tutorial on C++ programming. For many
of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program
in C++, you may just want to skip those parts of the manual.
<H2><a name="Preface_nn7"></a>1.5 Organization of this manual</H2>
<H2><a name="Preface_nn7">1.6 Organization of this manual</a></H2>
<p>
@ -139,7 +164,7 @@ can probably skip to that chapter and find almost everything you need
to know.
</p>
<H2><a name="Preface_nn8"></a>1.6 How to avoid reading the manual</H2>
<H2><a name="Preface_nn8">1.7 How to avoid reading the manual</a></H2>
<p>
@ -151,7 +176,7 @@ The SWIG distribution also comes with a large directory of
examples that illustrate different topics.
</p>
<H2><a name="Preface_nn9"></a>1.7 Backwards compatibility</H2>
<H2><a name="Preface_nn9">1.8 Backwards compatibility</a></H2>
<p>
@ -162,8 +187,8 @@ this isn't always possible as the
primary goal over time is to make SWIG
better---a process that would simply be impossible if the developers
are constantly bogged down with backwards compatibility issues.
Potential incompatibilities are clearly marked in the detailed release notes
(CHANGES files).
Potential incompatibilities are clearly marked in the detailed
<a href="#Preface_release_notes">release notes</a>.
</p>
@ -187,7 +212,16 @@ Note: The version symbol is not defined in the generated SWIG
wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
</p>
<H2><a name="Preface_nn10"></a>1.8 Credits</H2>
<H2><a name="Preface_release_notes">1.9 Release notes</a></H2>
<p>
The CHANGES.current, CHANGES and RELEASENOTES files shipped with SWIG in the top level directory
contain, respectively, detailed release notes for the current version,
detailed release notes for previous releases and summary release notes from SWIG-1.3.22 onwards.
</p>
<H2><a name="Preface_nn10">1.10 Credits</a></H2>
<p>
@ -200,7 +234,7 @@ who have made contributions at all levels over time. Contributors
are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or in submitted bugs.
</p>
<H2><a name="Preface_nn11"></a>1.9 Bug reports</H2>
<H2><a name="Preface_nn11">1.11 Bug reports</a></H2>
<p>
@ -215,5 +249,211 @@ used, and any important pieces of the SWIG generated wrapper code. We
can only fix bugs if we know about them.
</p>
<H2><a name="Preface_installation">1.12 Installation</a></H2>
<H3><a name="Preface_windows_installation">1.12.1 Windows installation</a></H3>
<p>
Please see the dedicated <a href="Windows.html#Windows">Windows chapter</a> for instructions on installing
SWIG on Windows and running the examples. The Windows distribution is
called swigwin and includes a prebuilt SWIG executable, swig.exe, included in
the top level directory. Otherwise it is exactly the same as
the main SWIG distribution. There is no need to download anything else.
</p>
<H3><a name="Preface_unix_installation">1.12.2 Unix installation</a></H3>
<p>
These installation instructions are for using the distributed tarball,
for example, <tt>swig-3.0.8.tar.gz</tt>.
If you wish to build and install from source on Github, extra steps are required.
Please see the <a href="http://swig.org/svn.html">Bleeding Edge</a> page on the SWIG website.
</p>
<p>
You must use <a href="http://www.gnu.org/software/make/">GNU make</a> to build and install SWIG.
</p>
<p>
<a href="http://www.pcre.org/">PCRE</a>
needs to be installed on your system to build SWIG, in particular
pcre-config must be available. If you have PCRE headers and libraries but not
pcre-config itself or, alternatively, wish to override the compiler or linker
flags returned by pcre-config, you may set PCRE_LIBS and PCRE_CFLAGS variables
to be used instead. And if you don't have PCRE at all, the configure script
will provide instructions for obtaining it.
</p>
<p>
To build and install SWIG, simply type the following:
</p>
<div class="shell"><pre>
$ ./configure
$ make
$ make install
</pre></div>
<p>
By default SWIG installs itself in /usr/local. If you need to install SWIG in
a different location or in your home directory, use the <tt>--prefix</tt> option
to <tt>./configure</tt>. For example:
</p>
<div class="shell"><pre>
$ ./configure --prefix=/home/yourname/projects
$ make
$ make install
</pre></div>
<p>
Note: the directory given to <tt>--prefix</tt> must be an absolute pathname. Do <b>not</b> use
the ~ shell-escape to refer to your home directory. SWIG won't work properly
if you do this.
</p>
<p>
The INSTALL file shipped in the top level directory details more about using configure. Also try
</p>
<div class="shell"><pre>
$ ./configure --help.
</pre></div>
<p>
The configure script will attempt to locate various packages on your machine
including Tcl, Perl5, Python and all the other target languages that SWIG
supports. Don't panic if you get 'not found' messages -- SWIG does not need these
packages to compile or run. The configure script is actually looking for
these packages so that you can try out the SWIG examples contained
in the 'Examples' directory without having to hack Makefiles.
Note that the <tt>--without-xxx</tt> options, where xxx is a target language, have
minimal effect. All they do is reduce the amount of testing done with
'make check'. The SWIG executable and library files installed cannot currently
be configured with a subset of target languages.
</p>
<p>
SWIG used to include a set of runtime libraries for some languages for working
with multiple modules. These are no longer built during the installation stage.
However, users can build them just like any wrapper module as described in
the <a href="Modules.html#Modules">Modules chapter</a>.
The CHANGES file shipped with SWIG in the top level directory
also lists some examples which build the runtime library.
</p>
<p>
Note:
</p>
<ul>
<li>
If you checked the code out via Git, you will have to run <tt>./autogen.sh</tt>
before <tt>./configure</tt>. In addition, a full build of SWIG requires
a number of packages to be installed. Full instructions at
<a href="http://www.swig.org/svn.html">SWIG bleeding edge</a>.
</li>
</ul>
<H3><a name="Preface_osx_installation">1.12.3 Macintosh OS X installation</a></H3>
<p>
SWIG is known to work on various flavors of OS X. Follow the Unix installation
instructions above. However, as of this writing, there is still great deal of
inconsistency with how shared libaries are handled by various scripting languages
on OS X.
</p>
<p>
Users of OS X should be aware that Darwin handles shared libraries and linking in
a radically different way than most Unix systems. In order to test SWIG and run
the examples, SWIG configures itself to use flat namespaces and to allow undefined
symbols (<tt>-flat_namespace -undefined suppress</tt>). This mostly closely follows the Unix
model and makes it more likely that the SWIG examples will work with whatever
installation of software you might have. However, this is generally not the recommended
technique for building larger extension modules. Instead, you should utilize
Darwin's two-level namespaces. Some details about this can be found here
<a href="https://developer.apple.com/library/mac/documentation/Porting/Conceptual/PortingUnix/compiling/compiling.html#//apple_ref/doc/uid/TP40002850-BCIHJBBF">Understanding Two-Level Namespaces</a>.
</p>
<p>
Needless to say, you might have to experiment a bit to get things working at first.
</p>
<H3><a name="Preface_testing">1.12.4 Testing</a></H3>
<p>
If you want to test SWIG after building it, a check can be performed on Unix operating systems.
Type the following:
</p>
<div class="shell"><pre>
$ make -k check
</pre></div>
<p>
This step can be performed either before or after installation.
The check requires at least one of the target languages to be
installed. If it fails, it may mean that you have an uninstalled
language module or that the file 'Examples/Makefile' has been
incorrectly configured. It may also fail due to compiler issues such
as a broken C++ compiler. Even if the check fails, there is a
pretty good chance SWIG still works correctly --- you will just have to
mess around with one of the examples and some makefiles to get it to work.
Some tests may also fail due to missing dependency packages, eg PCRE
or Boost, but this will require careful analysis of the configure output
done during configuration.
</p>
<p>
The test suite executed by the check is designed to stress-test
many parts of the implementation including obscure corner cases. If some
of these tests fail or generate warning messages, there is no reason for
alarm --- the test may be related to some new SWIG feature or a difficult bug
that we're trying to resolve. Chances are that SWIG will work just fine
for you. Note that if you have more than one CPU/core, then you can use
parallel make to speed up the check as it does take quite some time to run,
for example:
</p>
<div class="shell"><pre>
$ make -j2 -k check
</pre></div>
<p>
Also, SWIG's support for C++ is sufficiently advanced that certain
tests may fail on older C++ compilers (for instance if your compiler
does not support member templates). These errors are harmless if you
don't intend to use these features in your own programs.
</p>
<p>
Note: The test-suite currently contains over 500 tests. If you
have many different target languages installed and a slow machine, it
might take more than an hour to run the test-suite.
</p>
<H3><a name="Preface_examples">1.12.5 Examples</a></H3>
<p>
The Examples directory contains a variety of examples of using SWIG
and it has some browsable documentation. Simply point your browser to
the file "Example/index.html".
</p>
<p>
The Examples directory also includes Visual C++ project 6 (.dsp) files for
building some of the examples on Windows. Later versions of Visual Studio
will convert these old style project files into a current solution file.
</p>
</body>
</html>

35
Doc/Manual/Preprocessor.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG Preprocessor</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Preprocessor"></a>7 Preprocessing</H1>
<H1><a name="Preprocessor">8 Preprocessing</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -37,7 +38,7 @@ However, a number of modifications and enhancements have been made. This
chapter describes some of these modifications.
</p>
<H2><a name="Preprocessor_nn2"></a>7.1 File inclusion</H2>
<H2><a name="Preprocessor_nn2">8.1 File inclusion</a></H2>
<p>
@ -63,7 +64,7 @@ By default, the <tt>#include</tt> is ignored unless you run SWIG with the
is that you often don't want SWIG to try and wrap everything included
in standard header system headers and auxiliary files.
<H2><a name="Preprocessor_nn3"></a>7.2 File imports</H2>
<H2><a name="Preprocessor_nn3">8.2 File imports</a></H2>
<p>
@ -92,7 +93,7 @@ The <tt>-importall</tt> directive tells SWIG to follow all <tt>#include</tt> sta
as imports. This might be useful if you want to extract type definitions from system
header files without generating any wrappers.
<H2><a name="Preprocessor_condition_compilation"></a>7.3 Conditional Compilation</H2>
<H2><a name="Preprocessor_condition_compilation">8.3 Conditional Compilation</a></H2>
<p>
@ -115,9 +116,12 @@ SWIGCLISP Defined when using CLISP
SWIGCSHARP Defined when using C#
SWIGGUILE Defined when using Guile
SWIGJAVA Defined when using Java
SWIGJAVASCRIPT Defined when using Javascript
SWIG_JAVASCRIPT_JSC Defined when using Javascript for JavascriptCore
SWIG_JAVASCRIPT_V8 Defined when using Javascript for v8 or node.js
SWIGLUA Defined when using Lua
SWIGMODULA3 Defined when using Modula-3
SWIGMZSCHEME Defined when using Mzscheme
SWIGMZSCHEME Defined when using Mzscheme
SWIGOCAML Defined when using Ocaml
SWIGOCTAVE Defined when using Octave
SWIGPERL Defined when using Perl
@ -126,6 +130,7 @@ SWIGPIKE Defined when using Pike
SWIGPYTHON Defined when using Python
SWIGR Defined when using R
SWIGRUBY Defined when using Ruby
SWIGSCILAB Defined when using Scilab
SWIGSEXP Defined when using S-expressions
SWIGTCL Defined when using Tcl
SWIGXML Defined when using XML
@ -152,7 +157,7 @@ SWIG (except for the symbol `<tt>SWIG</tt>' which is only defined
within the SWIG compiler).
</p>
<H2><a name="Preprocessor_nn5"></a>7.4 Macro Expansion</H2>
<H2><a name="Preprocessor_nn5">8.4 Macro Expansion</a></H2>
<p>
@ -207,7 +212,7 @@ like <tt>#x</tt>. This is a non-standard SWIG extension.
</li>
</ul>
<H2><a name="Preprocessor_nn6"></a>7.5 SWIG Macros</H2>
<H2><a name="Preprocessor_nn6">8.5 SWIG Macros</a></H2>
<p>
@ -253,7 +258,7 @@ many of SWIG's advanced features and libraries are built using this mechanism (s
support).
</p>
<H2><a name="Preprocessor_nn7"></a>7.6 C99 and GNU Extensions</H2>
<H2><a name="Preprocessor_nn7">8.6 C99 and GNU Extensions</a></H2>
<p>
@ -309,14 +314,14 @@ interface building. However, they are used internally to implement a number of
SWIG directives and are provided to make SWIG more compatible with C99 code.
</p>
<H2><a name="Preprocessor_delimiters"></a>7.7 Preprocessing and delimiters</H2>
<H2><a name="Preprocessor_delimiters">8.7 Preprocessing and delimiters</a></H2>
<p>
The preprocessor handles { }, " " and %{ %} delimiters differently.
</p>
<H3><a name="Preprocessor_nn8"></a>7.7.1 Preprocessing and %{ ... %} &amp; " ... " delimiters</H3>
<H3><a name="Preprocessor_nn8">8.7.1 Preprocessing and %{ ... %} &amp; " ... " delimiters</a></H3>
<p>
@ -341,7 +346,7 @@ the contents of the <tt>%{ ... %}</tt> block are copied without
modification to the output (including all preprocessor directives).
</p>
<H3><a name="Preprocessor_nn9"></a>7.7.2 Preprocessing and { ... } delimiters</H3>
<H3><a name="Preprocessor_nn9">8.7.2 Preprocessing and { ... } delimiters</a></H3>
<p>
@ -383,7 +388,7 @@ to actually go into the wrapper file, prefix the preprocessor directives with <t
SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code.
</p>
<H2><a name="Preprocessor_typemap_delimiters"></a>7.8 Preprocessor and Typemaps</H2>
<H2><a name="Preprocessor_typemap_delimiters">8.8 Preprocessor and Typemaps</a></H2>
<p>
@ -454,7 +459,7 @@ would generate
</div>
<H2><a name="Preprocessor_nn10"></a>7.9 Viewing preprocessor output</H2>
<H2><a name="Preprocessor_nn10">8.9 Viewing preprocessor output</a></H2>
<p>
@ -464,7 +469,7 @@ Instead the results after the preprocessor has run are displayed.
This might be useful as an aid to debugging and viewing the results of macro expansions.
</p>
<H2><a name="Preprocessor_warning_error"></a>7.10 The #error and #warning directives</H2>
<H2><a name="Preprocessor_warning_error">8.10 The #error and #warning directives</a></H2>
<p>

1248
Doc/Manual/Python.html
View file

File diff suppressed because it is too large Load diff

36
Doc/Manual/R.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and R</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="R"></a>35 SWIG and R</H1>
<H1><a name="R">37 SWIG and R</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -33,7 +34,7 @@ compile and run an R interface to QuantLib running on Mandriva Linux
with gcc. The R bindings also work on Microsoft Windows using Visual C++.
</p>
<H2><a name="R_nn2"></a>35.1 Bugs</H2>
<H2><a name="R_nn2">37.1 Bugs</a></H2>
<p>
@ -45,7 +46,7 @@ Currently the following features are not implemented or broken:
<li>C Array wrappings
</ul>
<H2><a name="R_nn3"></a>35.2 Using R and SWIG</H2>
<H2><a name="R_nn3">37.2 Using R and SWIG</a></H2>
<p>
@ -119,7 +120,24 @@ Without it, inheritance of wrapped objects may fail.
These two files can be loaded in any order
</p>
<H2><a name="R_nn4"></a>35.3 Precompiling large R files</H2>
<p>
If you are compiling code yourself (not using R itself), there are a few things to watch out for:
</p>
<ul>
<li>The output shared library name (to the left of the file extension) MUST match the module name, or alternatively, you can also set the -package NAME command line argument. See swig -r -help for more information
<li>If you do not set the output file name appropriately, you might see errors like
<div class="shell">
<pre>
> fact(4)
Error in .Call("R_swig_fact", s_arg1, as.logical(.copy), PACKAGE = "example") :
"R_swig_fact" not available for .Call() for package "example"
</pre>
</div>
<li>Make sure the architecture of the shared library(x64 for instance), matches the architecture of the R program you want to load your shared library into
</ul>
<H2><a name="R_nn4">37.3 Precompiling large R files</a></H2>
In cases where the R file is large, one make save a lot of loading
@ -137,7 +155,7 @@ will save a large amount of loading time.
<H2><a name="R_nn5"></a>35.4 General policy</H2>
<H2><a name="R_nn5">37.4 General policy</a></H2>
<p>
@ -146,7 +164,7 @@ wrapping over the underlying functions and rely on the R type system
to provide R syntax.
</p>
<H2><a name="R_language_conventions"></a>35.5 Language conventions</H2>
<H2><a name="R_language_conventions">37.5 Language conventions</a></H2>
<p>
@ -155,7 +173,7 @@ and [ are overloaded to allow for R syntax (one based indices and
slices)
</p>
<H2><a name="R_nn6"></a>35.6 C++ classes</H2>
<H2><a name="R_nn6">37.6 C++ classes</a></H2>
<p>
@ -167,7 +185,7 @@ keep track of the pointer object which removes the necessity for a lot
of the proxy class baggage you see in other languages.
</p>
<H2><a name="R_nn7"></a>35.7 Enumerations</H2>
<H2><a name="R_nn7">37.7 Enumerations</a></H2>
<p>

4
Doc/Manual/README
View file

@ -1,9 +1,9 @@
This directory contains the HTML for the SWIG users manual.
All of this HTML is hand-written. However, section numbering, indices,
and the table of contents is generated automatically by the 'maketoc.py'
and the table of contents are generated automatically by the 'maketoc.py'
script. The Makefile has further information on how the various alternative
forms of the documentation is generated from the hand-written HTML.
forms of the documentation are generated from the hand-written HTML.
There are 4 types of boxes that code or whatever can be inside:
- <div class="shell">...</div>

8968
Doc/Manual/Ruby.html
View file

File diff suppressed because it is too large Load diff

435
Doc/Manual/SWIG.html
View file

File diff suppressed because it is too large Load diff

482
Doc/Manual/SWIGPlus.html
View file

File diff suppressed because it is too large Load diff

2148
Doc/Manual/Scilab.html Normal file
View file

File diff suppressed because it is too large Load diff

91
Doc/Manual/Scripting.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Scripting Languages</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Scripting"></a>4 Scripting Languages</H1>
<H1><a name="Scripting">4 Scripting Languages</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -37,7 +38,7 @@ programming and the mechanisms by which scripting language interpreters
access C and C++ code.
</p>
<H2><a name="Scripting_nn2"></a>4.1 The two language view of the world</H2>
<H2><a name="Scripting_nn2">4.1 The two language view of the world</a></H2>
<p>
@ -68,7 +69,7 @@ languages can be used for rapid prototyping, interactive debugging,
scripting, and access to high-level data structures such associative
arrays. </p>
<H2><a name="Scripting_nn3"></a>4.2 How does a scripting language talk to C?</H2>
<H2><a name="Scripting_nn3">4.2 How does a scripting language talk to C?</a></H2>
<p>
@ -93,7 +94,7 @@ function, arguments, and so forth. The next few sections illustrate
the process.
</p>
<H3><a name="Scripting_nn4"></a>4.2.1 Wrapper functions</H3>
<H3><a name="Scripting_nn4">4.2.1 Wrapper functions</a></H3>
<p>
@ -101,8 +102,10 @@ Suppose you have an ordinary C function like this :</p>
<div class="code"><pre>
int fact(int n) {
if (n &lt;= 1) return 1;
else return n*fact(n-1);
if (n &lt;= 1)
return 1;
else
return n*fact(n-1);
}
</pre></div>
@ -123,18 +126,17 @@ As an example, the Tcl wrapper function for the <tt>fact()</tt>
function above example might look like the following : </p>
<div class="code"><pre>
int wrap_fact(ClientData clientData, Tcl_Interp *interp,
int argc, char *argv[]) {
int result;
int arg0;
if (argc != 2) {
interp-&gt;result = "wrong # args";
return TCL_ERROR;
}
arg0 = atoi(argv[1]);
result = fact(arg0);
sprintf(interp-&gt;result,"%d", result);
return TCL_OK;
int wrap_fact(ClientData clientData, Tcl_Interp *interp, int argc, char *argv[]) {
int result;
int arg0;
if (argc != 2) {
interp-&gt;result = "wrong # args";
return TCL_ERROR;
}
arg0 = atoi(argv[1]);
result = fact(arg0);
sprintf(interp-&gt;result,"%d", result);
return TCL_OK;
}
</pre></div>
@ -148,9 +150,9 @@ requires code like the following :</p>
<div class="code"><pre>
int Wrap_Init(Tcl_Interp *interp) {
Tcl_CreateCommand(interp, "fact", wrap_fact, (ClientData) NULL,
(Tcl_CmdDeleteProc *) NULL);
return TCL_OK;
Tcl_CreateCommand(interp, "fact", wrap_fact, (ClientData) NULL,
(Tcl_CmdDeleteProc *) NULL);
return TCL_OK;
}
</pre></div>
@ -165,7 +167,7 @@ Python. Both require special wrappers to be written and both need
additional initialization code. Only the specific details are
different.</p>
<H3><a name="Scripting_nn5"></a>4.2.2 Variable linking</H3>
<H3><a name="Scripting_nn5">4.2.2 Variable linking</a></H3>
<p>
@ -201,7 +203,7 @@ typing <tt>$Foo = 4</tt> would call the underlying set function to change
the value.
</p>
<H3><a name="Scripting_nn6"></a>4.2.3 Constants</H3>
<H3><a name="Scripting_nn6">4.2.3 Constants</a></H3>
<p>
@ -222,7 +224,7 @@ functions for creating variables so installing constants is usually
a trivial exercise.
</p>
<H3><a name="Scripting_nn7"></a>4.2.4 Structures and classes</H3>
<H3><a name="Scripting_nn7">4.2.4 Structures and classes</a></H3>
<p>
@ -243,9 +245,9 @@ representation of a structure. For example,
<div class="code"><pre>
struct Vector {
Vector();
~Vector();
double x,y,z;
Vector();
~Vector();
double x,y,z;
};
</pre></div>
@ -283,7 +285,7 @@ internals of an object, the interpreter does not need to know anything
about the actual representation of a <tt>Vector</tt>.
</p>
<H3><a name="Scripting_nn8"></a>4.2.5 Proxy classes</H3>
<H3><a name="Scripting_nn8">4.2.5 Proxy classes</a></H3>
<p>
@ -293,14 +295,14 @@ A proxy class is a special kind of object that gets created
in a scripting language to access a C/C++ class (or struct) in a way
that looks like the original structure (that is, it proxies the real
C++ class). For example, if you
have the following C definition :</p>
have the following C++ definition :</p>
<div class="code"><pre>
class Vector {
public:
Vector();
~Vector();
double x,y,z;
Vector();
~Vector();
double x,y,z;
};
</pre></div>
@ -334,18 +336,18 @@ Finally, in Tcl :
<div class="targetlang"><pre>
Vector v
v configure -x 3 -y 4 -z 13
v configure -x 3 -y 4 -z -13
</pre></div>
<p>
When proxy classes are used, two objects are at really work--one in
When proxy classes are used, two objects are really at work--one in
the scripting language, and an underlying C/C++ object. Operations
affect both objects equally and for all practical purposes, it appears
as if you are simply manipulating a C/C++ object.
</p>
<H2><a name="Scripting_nn9"></a>4.3 Building scripting language extensions</H2>
<H2><a name="Scripting_nn9">4.3 Building scripting language extensions</a></H2>
<p>
@ -353,32 +355,27 @@ The final step in using a scripting language with your C/C++
application is adding your extensions to the scripting language
itself. There are two primary approaches for doing
this. The preferred technique is to build a dynamically loadable
extension in the form a shared library. Alternatively, you can
extension in the form of a shared library. Alternatively, you can
recompile the scripting language interpreter with your extensions
added to it.
</p>
<H3><a name="Scripting_nn10"></a>4.3.1 Shared libraries and dynamic loading</H3>
<H3><a name="Scripting_nn10">4.3.1 Shared libraries and dynamic loading</a></H3>
<p>
To create a shared library or DLL, you often need to look at the
manual pages for your compiler and linker. However, the procedure
for a few common machines is shown below:</p>
for a few common platforms is shown below:</p>
<div class="shell"><pre>
# Build a shared library for Solaris
gcc -c example.c example_wrap.c -I/usr/local/include
gcc -fpic -c example.c example_wrap.c -I/usr/local/include
ld -G example.o example_wrap.o -o example.so
# Build a shared library for Linux
gcc -fpic -c example.c example_wrap.c -I/usr/local/include
gcc -shared example.o example_wrap.o -o example.so
# Build a shared library for Irix
gcc -c example.c example_wrap.c -I/usr/local/include
ld -shared example.o example_wrap.o -o example.so
</pre></div>
<p>
@ -405,7 +402,7 @@ changing the link line to the following :</p>
c++ -shared example.o example_wrap.o -o example.so
</pre></div>
<H3><a name="Scripting_nn11"></a>4.3.2 Linking with shared libraries</H3>
<H3><a name="Scripting_nn11">4.3.2 Linking with shared libraries</a></H3>
<p>
@ -452,7 +449,7 @@ the path using linker options instead.
</ul>
<H3><a name="Scripting_nn12"></a>4.3.3 Static linking</H3>
<H3><a name="Scripting_nn12">4.3.3 Static linking</a></H3>
<p>

22
Doc/Manual/Sections.html
View file

@ -1,16 +1,19 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG-2.0 Documentation</title>
<title>SWIG-3.0 Documentation</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Sections"></a>SWIG-2.0 Documentation</H1>
<H1><a name="Sections">SWIG-3.0 Documentation</a></H1>
Last update : SWIG-2.0.6 (30 April 2012)
<p>
Last update : SWIG-3.0.9 (in progress)
</p>
<H2>Sections</H2>
<H2><a name="Sections_Sections">Sections</a></H2>
<H3>SWIG Core Documentation</H3>
<H3><a name="Sections_core_docs">SWIG Core Documentation</a></H3>
<ul>
<li><a href="Preface.html#Preface">Preface</a></li>
<li><a href="Introduction.html#Introduction">Introduction</a></li>
@ -18,6 +21,7 @@ Last update : SWIG-2.0.6 (30 April 2012)
<li><a href="Scripting.html#Scripting">Scripting</a></li>
<li><a href="SWIG.html#SWIG">SWIG Basics</a> (Read this!)</li>
<li><a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a></li>
<li><a href="CPlusPlus11.html#CPlusPlus11">SWIG and C++11</a></li>
<li><a href="Preprocessor.html#Preprocessor">The SWIG preprocessor</a></li>
<li><a href="Library.html#Library">The SWIG library</a></li>
<li><a href="Arguments.html#Arguments">Argument handling</a></li>
@ -30,7 +34,7 @@ Last update : SWIG-2.0.6 (30 April 2012)
<li><a href="CCache.html#CCache">Using SWIG with ccache</a></li>
</ul>
<H3>Language Module Documentation</H3>
<H3><a name="Sections_language_modules">Language Module Documentation</a></H3>
<ul>
<li><a href="Allegrocl.html#Allegrocl">Allegro Common Lisp support</a></li>
@ -41,6 +45,7 @@ Last update : SWIG-2.0.6 (30 April 2012)
<li><a href="Go.html#Go">Go support</a></li>
<li><a href="Guile.html#Guile">Guile support</a></li>
<li><a href="Java.html#Java">Java support</a></li>
<li><a href="Javascript.html#Javascript">Javascript support</a></li>
<li><a href="Lisp.html#Lisp">Common Lisp support</a></li>
<li><a href="Lua.html#Lua">Lua support</a></li>
<li><a href="Modula3.html#Modula3">Modula3 support</a></li>
@ -53,10 +58,11 @@ Last update : SWIG-2.0.6 (30 April 2012)
<li><a href="Python.html#Python">Python support</a></li>
<li><a href="R.html#R">R support</a></li>
<li><a href="Ruby.html#Ruby">Ruby support</a></li>
<li><a href="Scilab.html#Scilab">Scilab support</a></li>
<li><a href="Tcl.html#Tcl">Tcl support</a></li>
</ul>
<H3>Developer Documentation</H3>
<H3><a name="Sections_developers_docs">Developer Documentation</a></H3>
<ul>
<li><a href="Extending.html#Extending">Extending SWIG</a></li>

177
Doc/Manual/Tcl.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and Tcl</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Tcl"></a>37 SWIG and Tcl</H1>
<H1><a name="Tcl">40 SWIG and Tcl</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -83,7 +84,7 @@ Tcl 8.0 or a later release. Earlier releases of SWIG supported Tcl 7.x, but
this is no longer supported.
</p>
<H2><a name="Tcl_nn2"></a>37.1 Preliminaries</H2>
<H2><a name="Tcl_nn2">40.1 Preliminaries</a></H2>
<p>
@ -109,7 +110,7 @@ build a Tcl extension module. To finish building the module, you
need to compile this file and link it with the rest of your program.
</p>
<H3><a name="Tcl_nn3"></a>37.1.1 Getting the right header files</H3>
<H3><a name="Tcl_nn3">40.1.1 Getting the right header files</a></H3>
<p>
@ -127,19 +128,20 @@ this is the case, you should probably make a symbolic link so that <tt>tcl.h</tt
header file.
</p>
<H3><a name="Tcl_nn4"></a>37.1.2 Compiling a dynamic module</H3>
<H3><a name="Tcl_nn4">40.1.2 Compiling a dynamic module</a></H3>
<p>
The preferred approach to building an extension module is to compile it into
a shared object file or DLL. To do this, you will need to compile your program
a shared object file or DLL. Assuming you have code you need to link to in a file
called <tt>example.c</tt>, you will need to compile your program
using commands like this (shown for Linux):
</p>
<div class="code"><pre>
$ swig -tcl example.i
$ gcc -c example.c
$ gcc -c example_wrap.c -I/usr/local/include
$ gcc -fPIC -c example.c
$ gcc -fPIC -c example_wrap.c -I/usr/local/include
$ gcc -shared example.o example_wrap.o -o example.so
</pre></div>
@ -159,10 +161,10 @@ of the module. If the name of your SWIG module is "<tt>example</tt>", the
name of the corresponding object file should be
"<tt>example.so</tt>".
The name of the module is specified using the <tt>%module</tt> directive or the
<tt> -module</tt> command line option.
<tt>-module</tt> command line option.
</p>
<H3><a name="Tcl_nn5"></a>37.1.3 Static linking</H3>
<H3><a name="Tcl_nn5">40.1.3 Static linking</a></H3>
<p>
@ -206,8 +208,8 @@ $ swig -tcl example.i
$ gcc example.c example_wrap.c \
-Xlinker -export-dynamic \
-DHAVE_CONFIG_H -I/usr/local/include/ \
-L/usr/local/lib -ltcl -lm -ldl \
-o mytclsh
-L/usr/local/lib -ltcl -lm -ldl \
-o mytclsh
</pre></div>
@ -228,7 +230,7 @@ minimal in most situations (and quite frankly not worth the extra
hassle in the opinion of this author).
</p>
<H3><a name="Tcl_nn6"></a>37.1.4 Using your module</H3>
<H3><a name="Tcl_nn6">40.1.4 Using your module</a></H3>
<p>
@ -356,7 +358,7 @@ to the default system configuration (this requires root access and you will need
the man pages).
</p>
<H3><a name="Tcl_nn7"></a>37.1.5 Compilation of C++ extensions</H3>
<H3><a name="Tcl_nn7">40.1.5 Compilation of C++ extensions</a></H3>
<p>
@ -373,8 +375,8 @@ compiler. For example:
<div class="code"><pre>
% swig -c++ -tcl example.i
% g++ -c example.cxx
% g++ -c example_wrap.cxx -I/usr/local/include
% g++ -fPIC -c example.cxx
% g++ -fPIC -c example_wrap.cxx -I/usr/local/include
% g++ -shared example.o example_wrap.o -o example.so
</pre></div>
@ -386,8 +388,8 @@ Solaris, you often need to add an extra library <tt>-lCrun</tt> like this:
<div class="code"><pre>
% swig -c++ -tcl example.i
% CC -c example.cxx
% CC -c example_wrap.cxx -I/usr/local/include
% CC -KPIC -c example.cxx
% CC -KPIC -c example_wrap.cxx -I/usr/local/include
% CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o example.so -lCrun
</pre></div>
@ -439,7 +441,7 @@ erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
</p>
<H3><a name="Tcl_nn8"></a>37.1.6 Compiling for 64-bit platforms</H3>
<H3><a name="Tcl_nn8">40.1.6 Compiling for 64-bit platforms</a></H3>
<p>
@ -466,7 +468,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H3><a name="Tcl_nn9"></a>37.1.7 Setting a package prefix</H3>
<H3><a name="Tcl_nn9">40.1.7 Setting a package prefix</a></H3>
<p>
@ -485,7 +487,7 @@ option will append the prefix to the name when creating a command and
call it "<tt>Foo_bar</tt>".
</p>
<H3><a name="Tcl_nn10"></a>37.1.8 Using namespaces</H3>
<H3><a name="Tcl_nn10">40.1.8 Using namespaces</a></H3>
<p>
@ -503,11 +505,11 @@ name, but you can override it using the <tt>-prefix</tt> option.
</p>
<p>
When the<tt> -namespace</tt> option is used, objects in the module
When the <tt>-namespace</tt> option is used, objects in the module
are always accessed with the namespace name such as <tt>Foo::bar</tt>.
</p>
<H2><a name="Tcl_nn11"></a>37.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
<H2><a name="Tcl_nn11">40.2 Building Tcl/Tk Extensions under Windows 95/NT</a></H2>
<p>
@ -518,7 +520,7 @@ covers the process of using SWIG with Microsoft Visual C++.
although the procedure may be similar with other compilers.
</p>
<H3><a name="Tcl_nn12"></a>37.2.1 Running SWIG from Developer Studio</H3>
<H3><a name="Tcl_nn12">40.2.1 Running SWIG from Developer Studio</a></H3>
<p>
@ -576,7 +578,7 @@ MSDOS &gt; tclsh80
%
</pre></div>
<H3><a name="Tcl_nn13"></a>37.2.2 Using NMAKE</H3>
<H3><a name="Tcl_nn13">40.2.2 Using NMAKE</a></H3>
<p>
@ -624,11 +626,11 @@ CFLAGS = /Z7 /Od /c /nologo
TCL_INCLUDES = -Id:\tcl8.0a2\generic -Id:\tcl8.0a2\win
TCLLIB = d:\tcl8.0a2\win\tcl80.lib
tcl::
..\..\swig -tcl -o $(WRAPFILE) $(INTERFACE)
$(CC) $(CFLAGS) $(TCL_INCLUDES) $(SRCS) $(WRAPFILE)
set LIB=$(TOOLS)\lib
$(LINK) $(LOPT) -out:example.dll $(LIBS) $(TCLLIB) example.obj example_wrap.obj
tcl:
..\..\swig -tcl -o $(WRAPFILE) $(INTERFACE)
$(CC) $(CFLAGS) $(TCL_INCLUDES) $(SRCS) $(WRAPFILE)
set LIB=$(TOOLS)\lib
$(LINK) $(LOPT) -out:example.dll $(LIBS) $(TCLLIB) example.obj example_wrap.obj
</pre></div>
@ -639,7 +641,7 @@ to get you started. With a little practice, you'll be making lots of
Tcl extensions.
</p>
<H2><a name="Tcl_nn14"></a>37.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Tcl_nn14">40.3 A tour of basic C/C++ wrapping</a></H2>
<p>
@ -650,7 +652,7 @@ classes. This section briefly covers the essential aspects of this
wrapping.
</p>
<H3><a name="Tcl_nn15"></a>37.3.1 Modules</H3>
<H3><a name="Tcl_nn15">40.3.1 Modules</a></H3>
<p>
@ -684,7 +686,7 @@ To fix this, supply an extra argument to <tt>load</tt> like this:
</pre>
</div>
<H3><a name="Tcl_nn16"></a>37.3.2 Functions</H3>
<H3><a name="Tcl_nn16">40.3.2 Functions</a></H3>
<p>
@ -709,7 +711,7 @@ like you think it does:
%
</pre></div>
<H3><a name="Tcl_nn17"></a>37.3.3 Global variables</H3>
<H3><a name="Tcl_nn17">40.3.3 Global variables</a></H3>
<p>
@ -789,7 +791,7 @@ extern char *path; // Read-only (due to %immutable)
</pre>
</div>
<H3><a name="Tcl_nn18"></a>37.3.4 Constants and enums</H3>
<H3><a name="Tcl_nn18">40.3.4 Constants and enums</a></H3>
<p>
@ -873,7 +875,7 @@ When an identifier name is given, it is used to perform an implicit hash-table l
conversion. This allows the <tt>global</tt> statement to be omitted.
</p>
<H3><a name="Tcl_nn19"></a>37.3.5 Pointers</H3>
<H3><a name="Tcl_nn19">40.3.5 Pointers</a></H3>
<p>
@ -969,7 +971,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
<tt>None</tt> if the conversion can't be performed.
</p>
<H3><a name="Tcl_nn20"></a>37.3.6 Structures</H3>
<H3><a name="Tcl_nn20">40.3.6 Structures</a></H3>
<p>
@ -979,7 +981,7 @@ This provides a very natural interface. For example,
<div class="code"><pre>
struct Vector {
double x,y,z;
double x,y,z;
};
</pre></div>
@ -1251,7 +1253,7 @@ Note: Tcl only destroys the underlying object if it has ownership. See the
memory management section that appears shortly.
</p>
<H3><a name="Tcl_nn21"></a>37.3.7 C++ classes</H3>
<H3><a name="Tcl_nn21">40.3.7 C++ classes</a></H3>
<p>
@ -1282,7 +1284,7 @@ you can use it in Tcl like this:
% x insert Lager
% x get 1
Stout
% puts [l cget -length]
% puts [x cget -length]
3
%
</pre></div>
@ -1318,7 +1320,7 @@ In Tcl, the static member is accessed as follows:
</pre>
</div>
<H3><a name="Tcl_nn22"></a>37.3.8 C++ inheritance</H3>
<H3><a name="Tcl_nn22">40.3.8 C++ inheritance</a></H3>
<p>
@ -1367,7 +1369,7 @@ For instance:
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Tcl_nn23"></a>37.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Tcl_nn23">40.3.9 Pointers, references, values, and arrays</a></H3>
<p>
@ -1421,7 +1423,7 @@ to hold the result and a pointer is returned (Tcl will release this memory
when the return value is garbage collected).
</p>
<H3><a name="Tcl_nn24"></a>37.3.10 C++ overloaded functions</H3>
<H3><a name="Tcl_nn24">40.3.10 C++ overloaded functions</a></H3>
<p>
@ -1544,7 +1546,7 @@ first declaration takes precedence.
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<H3><a name="Tcl_nn25"></a>37.3.11 C++ operators</H3>
<H3><a name="Tcl_nn25">40.3.11 C++ operators</a></H3>
<p>
@ -1646,7 +1648,7 @@ There are ways to make this operator appear as part of the class using the <tt>%
Keep reading.
</p>
<H3><a name="Tcl_nn26"></a>37.3.12 C++ namespaces</H3>
<H3><a name="Tcl_nn26">40.3.12 C++ namespaces</a></H3>
<p>
@ -1710,7 +1712,7 @@ utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve.
</p>
<H3><a name="Tcl_nn27"></a>37.3.13 C++ templates</H3>
<H3><a name="Tcl_nn27">40.3.13 C++ templates</a></H3>
<p>
@ -1762,7 +1764,7 @@ More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</
examples will appear later.
</p>
<H3><a name="Tcl_nn28"></a>37.3.14 C++ Smart Pointers</H3>
<H3><a name="Tcl_nn28">40.3.14 C++ Smart Pointers</a></H3>
<p>
@ -1846,7 +1848,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</pre>
</div>
<H2><a name="Tcl_nn29"></a>37.4 Further details on the Tcl class interface</H2>
<H2><a name="Tcl_nn29">40.4 Further details on the Tcl class interface</a></H2>
<p>
@ -1859,7 +1861,7 @@ of low-level details were omitted. This section provides a brief overview
of how the proxy classes work.
</p>
<H3><a name="Tcl_nn30"></a>37.4.1 Proxy classes</H3>
<H3><a name="Tcl_nn30">40.4.1 Proxy classes</a></H3>
<p>
@ -1924,7 +1926,7 @@ function. This allows objects to be encapsulated objects that look a lot like
as shown in the last section.
</p>
<H3><a name="Tcl_nn31"></a>37.4.2 Memory management</H3>
<H3><a name="Tcl_nn31">40.4.2 Memory management</a></H3>
<p>
@ -2112,7 +2114,7 @@ typemaps--an advanced topic discussed later.
</p>
<H2><a name="Tcl_nn32"></a>37.5 Input and output parameters</H2>
<H2><a name="Tcl_nn32">40.5 Input and output parameters</a></H2>
<p>
@ -2300,7 +2302,7 @@ set c [lindex $dim 1]
</pre>
</div>
<H2><a name="Tcl_nn33"></a>37.6 Exception handling </H2>
<H2><a name="Tcl_nn33">40.6 Exception handling </a></H2>
<p>
@ -2364,7 +2366,7 @@ Tcl extension by specifying the following in an interface file :
$action // Gets substituted by actual function call
}
catch (RangeError) {
Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
Tcl_SetResult(interp, (char *)"Array index out-of-bounds", TCL_STATIC);
return TCL_ERROR;
}
}
@ -2383,7 +2385,7 @@ exception handler to only apply to specific methods like this:
$action
}
catch (RangeError) {
Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
Tcl_SetResult(interp, (char *)"Array index out-of-bounds", TCL_STATIC);
return TCL_ERROR;
}
}
@ -2393,7 +2395,7 @@ exception handler to only apply to specific methods like this:
$action
}
catch (RangeError) {
Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
Tcl_SetResult(interp, (char *)"Array index out-of-bounds", TCL_STATIC);
return TCL_ERROR;
}
}
@ -2418,7 +2420,7 @@ For example:
$action
}
catch (RangeError) {
Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
Tcl_SetResult(interp, (char *)"Array index out-of-bounds", TCL_STATIC);
return TCL_ERROR;
}
}
@ -2434,7 +2436,7 @@ Since SWIG's exception handling is user-definable, you are not limited to C++ ex
See the chapter on "<a href="Customization.html#Customization">Customization Features</a>" for more examples.
</p>
<H2><a name="Tcl_nn34"></a>37.7 Typemaps</H2>
<H2><a name="Tcl_nn34">40.7 Typemaps</a></H2>
<p>
@ -2451,7 +2453,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Tcl interface.
</p>
<H3><a name="Tcl_nn35"></a>37.7.1 What is a typemap?</H3>
<H3><a name="Tcl_nn35">40.7.1 What is a typemap?</a></H3>
<p>
@ -2464,8 +2466,9 @@ you might define a typemap like this:
%module example
%typemap(in) int {
if (Tcl_GetIntFromObj(interp,$input,&amp;$1) == TCL_ERROR) return TCL_ERROR;
printf("Received an integer : %d\n",$1);
if (Tcl_GetIntFromObj(interp,$input,&amp;$1) == TCL_ERROR)
return TCL_ERROR;
printf("Received an integer : %d\n",$1);
}
%inline %{
extern int fact(int n);
@ -2502,8 +2505,9 @@ You can refine this by supplying an optional parameter name. For example:
%module example
%typemap(in) int n {
if (Tcl_GetIntFromObj(interp,$input,&amp;$1) == TCL_ERROR) return TCL_ERROR;
printf("n = %d\n",$1);
if (Tcl_GetIntFromObj(interp,$input,&amp;$1) == TCL_ERROR)
return TCL_ERROR;
printf("n = %d\n",$1);
}
%inline %{
extern int fact(int n);
@ -2525,8 +2529,9 @@ the typemap system follows <tt>typedef</tt> declarations. For example:
<div class="code">
<pre>
%typemap(in) int n {
if (Tcl_GetIntFromObj(interp,$input,&amp;$1) == TCL_ERROR) return TCL_ERROR;
printf("n = %d\n",$1);
if (Tcl_GetIntFromObj(interp,$input,&amp;$1) == TCL_ERROR)
return TCL_ERROR;
printf("n = %d\n",$1);
}
%inline %{
typedef int Integer;
@ -2568,7 +2573,7 @@ parameter is omitted):
</pre>
</div>
<H3><a name="Tcl_nn36"></a>37.7.2 Tcl typemaps</H3>
<H3><a name="Tcl_nn36">40.7.2 Tcl typemaps</a></H3>
<p>
@ -2706,7 +2711,7 @@ Initialize an argument to a value before any conversions occur.
Examples of these methods will appear shortly.
</p>
<H3><a name="Tcl_nn37"></a>37.7.3 Typemap variables</H3>
<H3><a name="Tcl_nn37">40.7.3 Typemap variables</a></H3>
<p>
@ -2777,7 +2782,7 @@ properly assigned.
The Tcl name of the wrapper function being created.
</div>
<H3><a name="Tcl_nn38"></a>37.7.4 Converting a Tcl list to a char ** </H3>
<H3><a name="Tcl_nn38">40.7.4 Converting a Tcl list to a char ** </a></H3>
<p>
@ -2839,7 +2844,7 @@ argv[2] = Larry
3
</pre></div>
<H3><a name="Tcl_nn39"></a>37.7.5 Returning values in arguments</H3>
<H3><a name="Tcl_nn39">40.7.5 Returning values in arguments</a></H3>
<p>
@ -2881,7 +2886,7 @@ result, a Tcl function using these typemaps will work like this :
%
</pre></div>
<H3><a name="Tcl_nn40"></a>37.7.6 Useful functions</H3>
<H3><a name="Tcl_nn40">40.7.6 Useful functions</a></H3>
<p>
@ -2920,7 +2925,6 @@ int Tcl_GetDoubleFromObj(Tcl_Interp *, Tcl_Obj *o, double *dp);
<div class="code">
<pre>
Tcl_Obj *Tcl_NewStringObj(char *str, int len);
void Tcl_SetStringObj(Tcl_Obj *obj, char *str, int len);
char *Tcl_GetStringFromObj(Tcl_Obj *obj, int *len);
void Tcl_AppendToObj(Tcl_Obj *obj, char *str, int len);
</pre>
@ -2958,7 +2962,7 @@ int Tcl_IsShared(Tcl_Obj *obj);
</pre>
</div>
<H3><a name="Tcl_nn41"></a>37.7.7 Standard typemaps</H3>
<H3><a name="Tcl_nn41">40.7.7 Standard typemaps</a></H3>
<p>
@ -2975,10 +2979,10 @@ work)
<div class="code">
<pre>
%typemap(in) int, short, long {
int temp;
if (Tcl_GetIntFromObj(interp, $input, &amp;temp) == TCL_ERROR)
return TCL_ERROR;
$1 = ($1_ltype) temp;
int temp;
if (Tcl_GetIntFromObj(interp, $input, &amp;temp) == TCL_ERROR)
return TCL_ERROR;
$1 = ($1_ltype) temp;
}
</pre>
</div>
@ -3036,13 +3040,14 @@ work)
<div class="code">
<pre>
%typemap(out) char * {
Tcl_SetStringObj($result,$1);
%typemap(out,noblock=1,fragment="SWIG_FromCharPtr") char *, const char * {
Tcl_SetObjResult(interp,SWIG_FromCharPtr((const char *)$1));
}
</pre>
</div>
<H3><a name="Tcl_nn42"></a>37.7.8 Pointer handling</H3>
<H3><a name="Tcl_nn42">40.7.8 Pointer handling</a></H3>
<p>
@ -3118,7 +3123,7 @@ For example:
</pre>
</div>
<H2><a name="Tcl_nn43"></a>37.8 Turning a SWIG module into a Tcl Package.</H2>
<H2><a name="Tcl_nn43">40.8 Turning a SWIG module into a Tcl Package.</a></H2>
<p>
@ -3152,8 +3157,8 @@ subdirectory which has the same name as the package. For example :
<div class="code"><pre>
./example/
pkgIndex.tcl # The file created by pkg_mkIndex
example.so # The SWIG generated module
pkgIndex.tcl # The file created by pkg_mkIndex
example.so # The SWIG generated module
</pre></div>
<p>
@ -3190,7 +3195,7 @@ As a final note, most SWIG examples do not yet use the
to use the <tt>load</tt> command instead.
</p>
<H2><a name="Tcl_nn44"></a>37.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
<H2><a name="Tcl_nn44">40.9 Building new kinds of Tcl interfaces (in Tcl)</a></H2>
<p>
@ -3263,14 +3268,14 @@ Our script allows easy array access as follows :
<div class="code"><pre>
set a [Array double 100] ;# Create a double [100]
for {set i 0} {$i &lt; 100} {incr i 1} { ;# Clear the array
$a set $i 0.0
$a set $i 0.0
}
$a set 3 3.1455 ;# Set an individual element
set b [$a get 10] ;# Retrieve an element
set ia [Array int 50] ;# Create an int[50]
for {set i 0} {$i &lt; 50} {incr i 1} { ;# Clear it
$ia set $i 0
$ia set $i 0
}
$ia set 3 7 ;# Set an individual element
set ib [$ia get 10] ;# Get an individual element
@ -3289,7 +3294,7 @@ danger of blowing something up (although it is easily accomplished
with an out of bounds array access).
</p>
<H3><a name="Tcl_nn45"></a>37.9.1 Proxy classes</H3>
<H3><a name="Tcl_nn45">40.9.1 Proxy classes</a></H3>
<p>
@ -3410,7 +3415,7 @@ short, but clever Tcl script can be combined with SWIG to do many
interesting things.
</p>
<H2><a name="Tcl_nn46"></a>37.10 Tcl/Tk Stubs</H2>
<H2><a name="Tcl_nn46">40.10 Tcl/Tk Stubs</a></H2>
<p>

297
Doc/Manual/Typemaps.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Typemaps</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Typemaps"></a>10 Typemaps</H1>
<H1><a name="Typemaps">11 Typemaps</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -48,6 +49,8 @@
<li><a href="#Typemaps_special_macro_descriptor">$descriptor(type)</a>
<li><a href="#Typemaps_special_macro_typemap">$typemap(method, typepattern)</a>
</ul>
<li><a href="#Typemaps_special_variable_attributes">Special variables and typemap attributes</a>
<li><a href="#Typemaps_special_variables_and_macros">Special variables combined with special variable macros</a>
</ul>
<li><a href="#Typemaps_nn25">Common typemap methods</a>
<ul>
@ -85,7 +88,7 @@
<li><a href="#Typemaps_runtime_type_checker_usage">Usage</a>
</ul>
<li><a href="#Typemaps_overloading">Typemaps and overloading</a>
<li><a href="#Typemaps_nn48">More about <tt>%apply</tt> and <tt>%clear</tt></a>
<li><a href="#Typemaps_nn48">More about %apply and %clear</a>
<li><a href="#Typemaps_nn47">Passing data between typemaps</a>
<li><a href="#Typemaps_nn52">C++ "this" pointer</a>
<li><a href="#Typemaps_nn51">Where to go for more information?</a>
@ -95,7 +98,7 @@
<H2><a name="Typemaps_nn2"></a>10.1 Introduction</H2>
<H2><a name="Typemaps_nn2">11.1 Introduction</a></H2>
<p>
@ -112,7 +115,7 @@ to re-read the earlier chapters if you have found your way to this
chapter with only a vague idea of what SWIG already does by default.
</p>
<H3><a name="Typemaps_nn3"></a>10.1.1 Type conversion</H3>
<H3><a name="Typemaps_nn3">11.1.1 Type conversion</a></H3>
<p>
@ -205,7 +208,7 @@ to read the extension documentation for your favorite language to know
how it works (an exercise left to the reader).
</p>
<H3><a name="Typemaps_nn4"></a>10.1.2 Typemaps</H3>
<H3><a name="Typemaps_nn4">11.1.2 Typemaps</a></H3>
<p>
@ -306,7 +309,7 @@ parts of the generated wrapper functions. Because arbitrary code can be insert
possible to completely change the way in which values are converted.
</p>
<H3><a name="Typemaps_nn5"></a>10.1.3 Pattern matching</H3>
<H3><a name="Typemaps_nn5">11.1.3 Pattern matching</a></H3>
<p>
@ -408,7 +411,7 @@ In this case, a single input object is expanded into a pair of C arguments. Thi
provides a hint to the unusual variable naming scheme involving <tt>$1</tt>, <tt>$2</tt>, and so forth.
</p>
<H3><a name="Typemaps_nn6"></a>10.1.4 Reusing typemaps</H3>
<H3><a name="Typemaps_nn6">11.1.4 Reusing typemaps</a></H3>
<p>
@ -464,7 +467,7 @@ typedef int size_t;
then SWIG already knows that the <tt>int</tt> typemaps apply. You don't have to do anything.
</p>
<H3><a name="Typemaps_nn7"></a>10.1.5 What can be done with typemaps?</H3>
<H3><a name="Typemaps_nn7">11.1.5 What can be done with typemaps?</a></H3>
<p>
@ -576,7 +579,7 @@ typemaps that expand upon this list. For example, the Java module defines a var
aspects of the Java bindings. Consult language specific documentation for further details.
</p>
<H3><a name="Typemaps_nn8"></a>10.1.6 What can't be done with typemaps?</H3>
<H3><a name="Typemaps_nn8">11.1.6 What can't be done with typemaps?</a></H3>
<p>
@ -639,7 +642,7 @@ void wrap_foo(char *s, int x) {
</pre>
</div>
<H3><a name="Typemaps_aspects"></a>10.1.7 Similarities to Aspect Oriented Programming</H3>
<H3><a name="Typemaps_aspects">11.1.7 Similarities to Aspect Oriented Programming</a></H3>
<p>
@ -653,11 +656,11 @@ The <a href="http://en.wikipedia.org/wiki/Aspect-oriented_programming#Terminolog
<li> <b>Aspect</b>: Aspects are the combination of the pointcut and the advice, hence each typemap is an aspect.
</ul>
<p>
SWIG can also be viewed as has having a second set of aspects based around <a href="Customization.html">%feature</a>.
SWIG can also be viewed as has having a second set of aspects based around <a href="Customization.html#Customization">%feature</a>.
Features such as <tt>%exception</tt> are also cross-cutting concerns as they encapsulate code that can be used to add logging or exception handling to any function.
</p>
<H3><a name="Typemaps_nn9"></a>10.1.8 The rest of this chapter</H3>
<H3><a name="Typemaps_nn9">11.1.8 The rest of this chapter</a></H3>
<p>
@ -677,14 +680,14 @@ of "The C Programming Language" by Kernighan and Ritchie or
"The C++ Programming Language" by Stroustrup before going any further.
</p>
<H2><a name="Typemaps_nn10"></a>10.2 Typemap specifications</H2>
<H2><a name="Typemaps_nn10">11.2 Typemap specifications</a></H2>
<p>
This section describes the behavior of the <tt>%typemap</tt> directive itself.
</p>
<H3><a name="Typemaps_defining"></a>10.2.1 Defining a typemap</H3>
<H3><a name="Typemaps_defining">11.2.1 Defining a typemap</a></H3>
<p>
@ -773,7 +776,7 @@ Here are some examples of valid typemap specifications:
}
/* Typemap with modifiers */
%typemap(in,doc="integer") int "$1 = gh_scm2int($input);";
%typemap(in,doc="integer") int "$1 = scm_to_int($input);";
/* Typemap applied to patterns of multiple arguments */
%typemap(in) (char *str, int len),
@ -797,7 +800,7 @@ Admittedly, it's not the most readable syntax at first glance. However, the pur
individual pieces will become clear.
</p>
<H3><a name="Typemaps_nn12"></a>10.2.2 Typemap scope</H3>
<H3><a name="Typemaps_nn12">11.2.2 Typemap scope</a></H3>
<p>
@ -847,7 +850,7 @@ class Foo {
</pre>
</div>
<H3><a name="Typemaps_nn13"></a>10.2.3 Copying a typemap</H3>
<H3><a name="Typemaps_nn13">11.2.3 Copying a typemap</a></H3>
<p>
@ -905,7 +908,7 @@ The patterns for <tt>%apply</tt> follow the same rules as for <tt>%typemap</tt>.
</pre>
</div>
<H3><a name="Typemaps_nn14"></a>10.2.4 Deleting a typemap</H3>
<H3><a name="Typemaps_nn14">11.2.4 Deleting a typemap</a></H3>
<p>
@ -938,7 +941,7 @@ For example:
after the clear operation.
</p>
<H3><a name="Typemaps_nn15"></a>10.2.5 Placement of typemaps</H3>
<H3><a name="Typemaps_nn15">11.2.5 Placement of typemaps</a></H3>
<p>
@ -1018,7 +1021,7 @@ It should be noted that for scoping to work, SWIG has to know that <tt>string</t
within a particular namespace. In this example, this is done using the forward class declaration <tt>class string</tt>.
</p>
<H2><a name="Typemaps_pattern_matching"></a>10.3 Pattern matching rules</H2>
<H2><a name="Typemaps_pattern_matching">11.3 Pattern matching rules</a></H2>
<p>
@ -1026,7 +1029,7 @@ The section describes the pattern matching rules by which C/C++ datatypes are as
The matching rules can be observed in practice by using the debugging options also described.
</p>
<H3><a name="Typemaps_nn17"></a>10.3.1 Basic matching rules</H3>
<H3><a name="Typemaps_nn17">11.3.1 Basic matching rules</a></H3>
<p>
@ -1125,7 +1128,7 @@ void F(int x[1000]); // int [ANY] rule (typemap 5)
stripped all qualifiers in one step.
</p>
<H3><a name="Typemaps_typedef_reductions"></a>10.3.2 Typedef reductions matching</H3>
<H3><a name="Typemaps_typedef_reductions">11.3.2 Typedef reductions matching</a></H3>
<p>
@ -1300,7 +1303,7 @@ void go(Struct aStruct);
</pre>
</div>
<H3><a name="Typemaps_nn19"></a>10.3.3 Default typemap matching rules</H3>
<H3><a name="Typemaps_nn19">11.3.3 Default typemap matching rules</a></H3>
<p>
@ -1438,7 +1441,7 @@ Finally the best way to view the typemap matching rules in action is via the <a
simpler scheme to match the current C++ class template partial specialization matching rules.
</p>
<H3><a name="Typemaps_multi_argument_typemaps_patterns"></a>10.3.4 Multi-arguments typemaps</H3>
<H3><a name="Typemaps_multi_argument_typemaps_patterns">11.3.4 Multi-arguments typemaps</a></H3>
<p>
@ -1468,7 +1471,7 @@ but all subsequent arguments must match exactly.
</p>
<H3><a name="Typemaps_matching_template_comparison"></a>10.3.5 Matching rules compared to C++ templates</H3>
<H3><a name="Typemaps_matching_template_comparison">11.3.5 Matching rules compared to C++ templates</a></H3>
<p>
@ -1627,7 +1630,7 @@ are similar to those for specialized template handling.
</p>
<H3><a name="Typemaps_debugging_search"></a>10.3.6 Debugging typemap pattern matching</H3>
<H3><a name="Typemaps_debugging_search">11.3.6 Debugging typemap pattern matching</a></H3>
<p>
@ -1840,7 +1843,7 @@ Also the types may be displayed slightly differently - <tt>char const *</tt> and
</li>
</ul>
<H2><a name="Typemaps_nn21"></a>10.4 Code generation rules</H2>
<H2><a name="Typemaps_nn21">11.4 Code generation rules</a></H2>
<p>
@ -1848,7 +1851,7 @@ This section describes rules by which typemap code is inserted into
the generated wrapper code.
</p>
<H3><a name="Typemaps_nn22"></a>10.4.1 Scope</H3>
<H3><a name="Typemaps_nn22">11.4.1 Scope</a></H3>
<p>
@ -1926,7 +1929,7 @@ a block scope when it is emitted. This sometimes results in a less complicated
Note that only the third of the three typemaps have the typemap code passed through the SWIG preprocessor.
</p>
<H3><a name="Typemaps_nn23"></a>10.4.2 Declaring new local variables</H3>
<H3><a name="Typemaps_nn23">11.4.2 Declaring new local variables</a></H3>
<p>
@ -2050,6 +2053,22 @@ wrap_foo() {
</pre>
</div>
<p>There is an exception: if the variable name starts with the <tt>_global_</tt> prefix,
the argument number is not appended. Such variables can be used throughout the generated
wrapper function. For example, the above typemap could be rewritten to use <tt>_global_temp</tt>
instead of <tt>temp</tt> and the generated code would then contain a single <tt>_global_temp</tt> variable
instead of <tt>temp1</tt>, <tt>temp2</tt> and <tt>temp3</tt>:
</p>
<div class="code">
<pre>
%typemap(in) std::string * <b>(std::string _global_temp)</b> {
... as above ...
}
</pre>
</div>
<p>
Some typemaps do not recognize local variables (or they may simply not
apply). At this time, only typemaps that apply to argument conversion support this (input typemaps such as the "in" typemap).
@ -2077,7 +2096,7 @@ each type must have its own local variable declaration.
</div>
<H3><a name="Typemaps_special_variables"></a>10.4.3 Special variables</H3>
<H3><a name="Typemaps_special_variables">11.4.3 Special variables</a></H3>
<p>
@ -2329,7 +2348,7 @@ Another approach, which only works for arrays is to use the <tt>$1_basetype</tt>
</pre>
</div>
<H3><a name="Typemaps_special_variable_macros"></a>10.4.4 Special variable macros</H3>
<H3><a name="Typemaps_special_variable_macros">11.4.4 Special variable macros</a></H3>
<p>
@ -2341,7 +2360,7 @@ it is done during the SWIG parsing/compilation stages.
The following special variable macros are available across all language modules.
</p>
<H4><a name="Typemaps_special_macro_descriptor"></a>10.4.4.1 $descriptor(type)</H4>
<H4><a name="Typemaps_special_macro_descriptor">11.4.4.1 $descriptor(type)</a></H4>
<p>
@ -2352,7 +2371,7 @@ For example, <tt>$descriptor(std::vector&lt;int&gt; *)</tt> will expand into <tt
This macro is mostly used in the scripting target languages and is demonstrated later in the <a href="#Typemaps_runtime_type_checker_usage">Run-time type checker usage</a> section.
</p>
<H4><a name="Typemaps_special_macro_typemap"></a>10.4.4.2 $typemap(method, typepattern)</H4>
<H4><a name="Typemaps_special_macro_typemap">11.4.4.2 $typemap(method, typepattern)</a></H4>
<p>
@ -2409,7 +2428,77 @@ The result is the following expansion
</pre>
</div>
<H2><a name="Typemaps_nn25"></a>10.5 Common typemap methods</H2>
<H3><a name="Typemaps_special_variable_attributes">11.4.5 Special variables and typemap attributes</a></H3>
<p>
As of SWIG-3.0.7 typemap attributes will also expand special variables and special variable macros.
</p>
<p>
Example usage showing the expansion in the 'out' attribute (C# specific) as well as the main typemap body:
</p>
<div class="code">
<pre>
%typemap(ctype, out="$*1_ltype") unsigned int&amp; "$*1_ltype"
</pre>
</div>
<p>
is equivalent to the following as <tt>$*1_ltype</tt> expands to <tt>unsigned int</tt>:
</p>
<div class="code">
<pre>
%typemap(ctype, out="unsigned int") unsigned int&amp; "unsigned int"
</pre>
</div>
<H3><a name="Typemaps_special_variables_and_macros">11.4.6 Special variables combined with special variable macros</a></H3>
<p>
Special variables can also be used within special variable macros.
The special variables are expanded before they are used in the special variable macros.
</p>
<p>
Consider the following C# typemaps:
</p>
<div class="code">
<pre>
%typemap(cstype) unsigned int "uint"
%typemap(cstype, out="$typemap(cstype, $*1_ltype)") unsigned int&amp; "$typemap(cstype, $*1_ltype)"
</pre>
</div>
<p>
Special variables are expanded first and hence the above is equivalent to:
</p>
<div class="code">
<pre>
%typemap(cstype) unsigned int "uint"
%typemap(cstype, out="$typemap(cstype, unsigned int)") unsigned int&amp; "$typemap(cstype, unsigned int)"
</pre>
</div>
<p>
which then expands to:
</p>
<div class="code">
<pre>
%typemap(cstype) unsigned int "uint"
%typemap(cstype, out="uint") unsigned int&amp; "uint"
</pre>
</div>
<H2><a name="Typemaps_nn25">11.5 Common typemap methods</a></H2>
<p>
@ -2417,7 +2506,7 @@ The set of typemaps recognized by a language module may vary. However,
the following typemap methods are nearly universal:
</p>
<H3><a name="Typemaps_nn26"></a>10.5.1 "in" typemap</H3>
<H3><a name="Typemaps_nn26">11.5.1 "in" typemap</a></H3>
<p>
@ -2477,7 +2566,7 @@ Usually <tt>numinputs</tt> is not specified, whereupon the default value is 1, t
is the same as the old "ignore" typemap.
</p>
<H3><a name="Typemaps_nn27"></a>10.5.2 "typecheck" typemap</H3>
<H3><a name="Typemaps_nn27">11.5.2 "typecheck" typemap</a></H3>
<p>
@ -2503,7 +2592,7 @@ If you define new "in" typemaps <em>and</em> your program uses overloaded method
"typecheck" typemaps. More details about this follow in the <a href="#Typemaps_overloading">Typemaps and overloading</a> section.
</p>
<H3><a name="Typemaps_nn28"></a>10.5.3 "out" typemap</H3>
<H3><a name="Typemaps_nn28">11.5.3 "out" typemap</a></H3>
<p>
@ -2534,7 +2623,7 @@ $symname - Name of function/method being wrapped
The "out" typemap supports an optional attribute flag called "optimal". This is for code optimisation and is detailed in the <a href="#Typemaps_optimal">Optimal code generation when returning by value</a> section.
</p>
<H3><a name="Typemaps_nn29"></a>10.5.4 "arginit" typemap</H3>
<H3><a name="Typemaps_nn29">11.5.4 "arginit" typemap</a></H3>
<p>
@ -2553,7 +2642,7 @@ For example:
</pre>
</div>
<H3><a name="Typemaps_nn30"></a>10.5.5 "default" typemap</H3>
<H3><a name="Typemaps_nn30">11.5.5 "default" typemap</a></H3>
<p>
@ -2586,7 +2675,7 @@ See the <a href="SWIG.html#SWIG_default_args">Default/optional arguments</a> sec
for further information on default argument wrapping.
</p>
<H3><a name="Typemaps_nn31"></a>10.5.6 "check" typemap</H3>
<H3><a name="Typemaps_nn31">11.5.6 "check" typemap</a></H3>
<p>
@ -2605,7 +2694,7 @@ converted. For example:
</pre>
</div>
<H3><a name="Typemaps_nn32"></a>10.5.7 "argout" typemap</H3>
<H3><a name="Typemaps_nn32">11.5.7 "argout" typemap</a></H3>
<p>
@ -2651,7 +2740,7 @@ return values are often appended to return value of the function.
See the <tt>typemaps.i</tt> library file for examples.
</p>
<H3><a name="Typemaps_nn33"></a>10.5.8 "freearg" typemap</H3>
<H3><a name="Typemaps_nn33">11.5.8 "freearg" typemap</a></H3>
<p>
@ -2684,7 +2773,7 @@ be used in other typemaps whenever a wrapper function needs to abort
prematurely.
</p>
<H3><a name="Typemaps_nn34"></a>10.5.9 "newfree" typemap</H3>
<H3><a name="Typemaps_nn34">11.5.9 "newfree" typemap</a></H3>
<p>
@ -2713,7 +2802,7 @@ string *foo();
See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for further details.
</p>
<H3><a name="Typemaps_nn35"></a>10.5.10 "memberin" typemap</H3>
<H3><a name="Typemaps_nn35">11.5.10 "memberin" typemap</a></H3>
<p>
@ -2735,7 +2824,7 @@ It is rarely necessary to write "memberin" typemaps---SWIG already provides
a default implementation for arrays, strings, and other objects.
</p>
<H3><a name="Typemaps_nn36"></a>10.5.11 "varin" typemap</H3>
<H3><a name="Typemaps_nn36">11.5.11 "varin" typemap</a></H3>
<p>
@ -2743,7 +2832,7 @@ The "varin" typemap is used to convert objects in the target language to C for t
purposes of assigning to a C/C++ global variable. This is implementation specific.
</p>
<H3><a name="Typemaps_nn37"></a>10.5.12 "varout" typemap</H3>
<H3><a name="Typemaps_nn37">11.5.12 "varout" typemap</a></H3>
<p>
@ -2751,7 +2840,7 @@ The "varout" typemap is used to convert a C/C++ object to an object in the targe
language when reading a C/C++ global variable. This is implementation specific.
</p>
<H3><a name="throws_typemap"></a>10.5.13 "throws" typemap</H3>
<H3><a name="throws_typemap">11.5.13 "throws" typemap</a></H3>
<p>
@ -2797,7 +2886,7 @@ Note that if your methods do not have an exception specification yet they do thr
For a neat way to handle these, see the <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section.
</p>
<H2><a name="Typemaps_nn39"></a>10.6 Some typemap examples</H2>
<H2><a name="Typemaps_nn39">11.6 Some typemap examples</a></H2>
<p>
@ -2805,7 +2894,7 @@ This section contains a few examples. Consult language module documentation
for more examples.
</p>
<H3><a name="Typemaps_nn40"></a>10.6.1 Typemaps for arrays</H3>
<H3><a name="Typemaps_nn40">11.6.1 Typemaps for arrays</a></H3>
<p>
@ -2962,8 +3051,8 @@ For example, suppose you had a structure like this:
<div class="code"><pre>
struct SomeObject {
float value[4];
...
float value[4];
...
};
</pre></div>
@ -3064,7 +3153,7 @@ Now, you will find that member access is quite nice:
useless and has since been eliminated. To return structure members, simply use the "out" typemap.
</p>
<H3><a name="Typemaps_nn41"></a>10.6.2 Implementing constraints with typemaps</H3>
<H3><a name="Typemaps_nn41">11.6.2 Implementing constraints with typemaps</a></H3>
<p>
@ -3077,9 +3166,9 @@ checking the values of function arguments. For example:</p>
%module math
%typemap(check) double posdouble {
if ($1 &lt; 0) {
croak("Expecting a positive number");
}
if ($1 &lt; 0) {
croak("Expecting a positive number");
}
}
...
@ -3112,7 +3201,7 @@ a NULL pointer. As a result, SWIG can often prevent a potential
segmentation faults or other run-time problems by raising an exception
rather than blindly passing values to the underlying C/C++ program.</p>
<H2><a name="Typemaps_nn43"></a>10.7 Typemaps for multiple target languages</H2>
<H2><a name="Typemaps_nn43">11.7 Typemaps for multiple target languages</a></H2>
<p>
@ -3142,7 +3231,7 @@ The example above also shows a common approach of issuing a warning for an as ye
<tt>%typemap(ruby,in) int "$1 = NUM2INT($input);"</tt>.
</p>
<H2><a name="Typemaps_optimal"></a>10.8 Optimal code generation when returning by value</H2>
<H2><a name="Typemaps_optimal">11.8 Optimal code generation when returning by value</a></H2>
<p>
@ -3331,7 +3420,7 @@ example.i:7: Warning 475: optimal attribute usage in the out typemap.
However, it doesn't always get it right, for example when <tt>$1</tt> is within some commented out code.
</p>
<H2><a name="Typemaps_multi_argument_typemaps"></a>10.9 Multi-argument typemaps</H2>
<H2><a name="Typemaps_multi_argument_typemaps">11.9 Multi-argument typemaps</a></H2>
<p>
@ -3355,12 +3444,12 @@ list of strings like this:
<div class="targetlang">
<pre>
&gt;&gt;&gt; foo(["ale","lager","stout"])
&gt;&gt;&gt; foo(["ale", "lager", "stout"])
</pre>
</div>
<p>
To do this, you not only need to map a list of strings to <tt> char *argv[]</tt>, but the
To do this, you not only need to map a list of strings to <tt>char *argv[]</tt>, but the
value of <tt>int argc</tt> is implicitly determined by the length of the list. Using only simple
typemaps, this type of conversion is possible, but extremely painful.
Multi-argument typemaps help in this situation.
@ -3398,6 +3487,11 @@ maps perform the conversion described for the above example:
%typemap(freearg) (int argc, char *argv[]) {
if ($2) free($2);
}
/* Required for C++ method overloading */
%typecheck(SWIG_TYPECHECK_STRING_ARRAY) (int argc, char *argv[]) {
$1 = PyList_Check($input) ? 1 : 0;
}
</pre>
</div>
@ -3465,6 +3559,11 @@ Other directives such as <tt>%apply</tt> and <tt>%clear</tt> also work with mult
</pre>
</div>
<p>
Don't forget to also provide a suitable <a href="#Typemaps_overloading">typemap for overloaded functions</a>, such as <tt>%typecheck</tt> shown for foo above.
This is only required if the function is overloaded in C++.
</p>
<p>
Although multi-argument typemaps may seem like an exotic, little used feature, there
are several situations where they make sense. First, suppose you wanted to wrap
@ -3598,7 +3697,7 @@ with non-consecutive C/C++ arguments; a workaround such as a helper function re-
the arguments to make them consecutive will need to be written.
</p>
<H2><a name="Typemaps_warnings"></a>10.10 Typemap warnings</H2>
<H2><a name="Typemaps_warnings">11.10 Typemap warnings</a></H2>
<p>
@ -3607,7 +3706,7 @@ See the information in the <a href="Warnings.html#Warnings_nn5">issuing warnings
</p>
<H2><a name="Typemaps_fragments"></a>10.11 Typemap fragments</H2>
<H2><a name="Typemaps_fragments">11.11 Typemap fragments</a></H2>
<p>
@ -3860,7 +3959,7 @@ fragment usage unless a desire to really get to grips
with some powerful but tricky macro and fragment usage that is used in parts of the SWIG typemap library.
</p>
<H3><a name="Typemaps_fragment_type_specialization"></a>10.11.1 Fragment type specialization</H3>
<H3><a name="Typemaps_fragment_type_specialization">11.11.1 Fragment type specialization</a></H3>
<p>
@ -3893,7 +3992,7 @@ struct A {
</pre>
</div>
<H3><a name="Typemaps_automatic_specialization"></a>10.11.2 Fragments and automatic typemap specialization</H3>
<H3><a name="Typemaps_automatic_specialization">11.11.2 Fragments and automatic typemap specialization</a></H3>
<p>
@ -3939,7 +4038,7 @@ The interested (or very brave) reader can take a look at the fragments.swg file
</p>
<H2><a name="Typemaps_runtime_type_checker"></a>10.12 The run-time type checker</H2>
<H2><a name="Typemaps_runtime_type_checker">11.12 The run-time type checker</a></H2>
<p>
@ -3956,7 +4055,7 @@ Requirements for the type system:
<li>Store inheritance and type equivalence information and be able to correctly
re-create the type pointer.</li>
<li>Share type information between modules.</li>
<li>Modules can be loaded in any order, irregardless of actual type
<li>Modules can be loaded in any order, regardless of actual type
dependency.</li>
<li>Avoid the use of dynamically allocated memory, and library/system calls in general.</li>
<li>Provide a reasonably fast implementation, minimizing the lookup time for all
@ -3965,7 +4064,7 @@ language modules.</li>
<li>Modules can be unloaded from the type system.</li>
</ul>
<H3><a name="Typemaps_nn45"></a>10.12.1 Implementation</H3>
<H3><a name="Typemaps_nn45">11.12.1 Implementation</a></H3>
<p>
@ -4151,7 +4250,7 @@ structures rather than creating new ones. These <tt>swig_module_info</tt>
structures are chained together in a circularly linked list.
</p>
<H3><a name="Typemaps_runtime_type_checker_usage"></a>10.12.2 Usage</H3>
<H3><a name="Typemaps_runtime_type_checker_usage">11.12.2 Usage</a></H3>
<p>This section covers how to use these functions from typemaps. To learn how to
@ -4245,7 +4344,7 @@ probably just look at the output of SWIG to get a better sense for how types are
managed.
</p>
<H2><a name="Typemaps_overloading"></a>10.13 Typemaps and overloading</H2>
<H2><a name="Typemaps_overloading">11.13 Typemaps and overloading</a></H2>
<p>
@ -4413,7 +4512,7 @@ before arrays, and so forth.
<p>
Using the above table as a guide, each target language defines a collection of "typecheck" typemaps.
The follow excerpt from the Python module illustrates this:
The following excerpt from the Python module illustrates this:
</p>
<div class="code">
@ -4422,22 +4521,22 @@ The follow excerpt from the Python module illustrates this:
/* Note: %typecheck(X) is a macro for %typemap(typecheck,precedence=X) */
%typecheck(SWIG_TYPECHECK_INTEGER)
int, short, long,
unsigned int, unsigned short, unsigned long,
signed char, unsigned char,
long long, unsigned long long,
const int &amp;, const short &amp;, const long &amp;,
const unsigned int &amp;, const unsigned short &amp;, const unsigned long &amp;,
const long long &amp;, const unsigned long long &amp;,
enum SWIGTYPE,
bool, const bool &amp;
int, short, long,
unsigned int, unsigned short, unsigned long,
signed char, unsigned char,
long long, unsigned long long,
const int &amp;, const short &amp;, const long &amp;,
const unsigned int &amp;, const unsigned short &amp;, const unsigned long &amp;,
const long long &amp;, const unsigned long long &amp;,
enum SWIGTYPE,
bool, const bool &amp;
{
$1 = (PyInt_Check($input) || PyLong_Check($input)) ? 1 : 0;
}
%typecheck(SWIG_TYPECHECK_DOUBLE)
float, double,
const float &amp;, const double &amp;
float, double,
const float &amp;, const double &amp;
{
$1 = (PyFloat_Check($input) || PyInt_Check($input) || PyLong_Check($input)) ? 1 : 0;
}
@ -4526,11 +4625,31 @@ Here is an example,
<p>
The bottom line: If you are writing new typemaps and you are using overloaded methods, you will probably
have to write typecheck code or copy existing code. Since this is a relatively new SWIG feature, there are
few examples to work with. However, you might look at some of the existing library files likes 'typemaps.i' for
a guide.
have to write new typecheck code or copy and modify existing typecheck code.
</p>
<p>
If you write a typecheck typemap and omit the precedence level, for example commenting it out as shown below:
</p>
<div class="code">
<pre>
%typemap(typecheck /*,precedence=SWIG_TYPECHECK_INTEGER*/) int {
$1 = PyInt_Check($input) ? 1 : 0;
}
</pre>
</div>
<p>
then the type is given a precedence higher than any other known precedence level and a <a href="Warnings.html#Warnings">warning</a> is issued:
</p>
<div class="shell">
<pre>
example.i:18: Warning 467: Overloaded method foo(int) not supported (incomplete type checking rule - no precedence level in typecheck typemap for 'int').
</pre>
</div>
<p>
<b>Notes:</b>
</p>
@ -4556,7 +4675,7 @@ Subsequent "in" typemaps would then perform more extensive type-checking.
</li>
</ul>
<H2><a name="Typemaps_nn48"></a>10.14 More about <tt>%apply</tt> and <tt>%clear</tt></H2>
<H2><a name="Typemaps_nn48">11.14 More about %apply and %clear</a></H2>
<p>
@ -4642,7 +4761,7 @@ example:
</div>
<H2><a name="Typemaps_nn47"></a>10.15 Passing data between typemaps</H2>
<H2><a name="Typemaps_nn47">11.15 Passing data between typemaps</a></H2>
<p>
@ -4679,7 +4798,7 @@ sure that the typemaps sharing information have exactly the same types and names
</p>
<H2><a name="Typemaps_nn52"></a>10.16 C++ "this" pointer</H2>
<H2><a name="Typemaps_nn52">11.16 C++ "this" pointer</a></H2>
<p>
@ -4739,7 +4858,7 @@ will also match the typemap. One work around is to create an interface file tha
the method, but gives the argument a name other than <tt>self</tt>.
</p>
<H2><a name="Typemaps_nn51"></a>10.17 Where to go for more information?</H2>
<H2><a name="Typemaps_nn51">11.17 Where to go for more information?</a></H2>
<p>

97
Doc/Manual/Varargs.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Variable Length Arguments</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Varargs"></a>13 Variable Length Arguments</H1>
<H1><a name="Varargs">14 Variable Length Arguments</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -42,7 +43,7 @@ added in SWIG-1.3.12. Most other wrapper generation tools have
wisely chosen to avoid this issue.
</p>
<H2><a name="Varargs_nn2"></a>13.1 Introduction</H2>
<H2><a name="Varargs_nn2">14.1 Introduction</a></H2>
<p>
@ -139,7 +140,7 @@ List make_list(const char *s, ...) {
</pre>
</div>
<H2><a name="Varargs_nn3"></a>13.2 The Problem</H2>
<H2><a name="Varargs_nn3">14.2 The Problem</a></H2>
<p>
@ -232,7 +233,7 @@ can also support real varargs wrapping (with stack-frame manipulation) if you
are willing to get hands dirty. Keep reading.
</p>
<H2><a name="Varargs_nn4"></a>13.3 Default varargs support</H2>
<H2><a name="Varargs_nn4">14.3 Default varargs support</a></H2>
<p>
@ -301,7 +302,7 @@ Read on for further solutions.
</p>
<H2><a name="Varargs_nn5"></a>13.4 Argument replacement using %varargs</H2>
<H2><a name="Varargs_nn5">14.4 Argument replacement using %varargs</a></H2>
<p>
@ -398,7 +399,7 @@ int execlp(const char *path, const char *arg, ...);
</div>
<p>
Note that <tt>str3</tt> is the name of the last argument, as we have used <tt>%vargars</tt> with 3.
Note that <tt>str3</tt> is the name of the last argument, as we have used <tt>%varargs</tt> with 3.
Now <tt>execlp("a", "b", "c", "d", "e")</tt> will result in an error as one too many arguments has been passed,
as now only 2 additional 'str' arguments can be passed with the 3rd one always using the specified default <tt>NULL</tt>.
</p>
@ -412,7 +413,7 @@ mixed argument types such as <tt>printf()</tt>. Providing general purpose
wrappers to such functions presents special problems (covered shortly).
</p>
<H2><a name="Varargs_nn6"></a>13.5 Varargs and typemaps</H2>
<H2><a name="Varargs_nn6">14.5 Varargs and typemaps</a></H2>
<p>
@ -509,10 +510,10 @@ like this:
<div class="code">
<pre>
%typemap(in) (...)(char *args[10]) {
%typemap(in) (...)(char *vargs[10]) {
int i;
int argc;
for (i = 0; i &lt; 10; i++) args[i] = 0;
for (i = 0; i &lt; 10; i++) vargs[i] = 0;
argc = PyTuple_Size(varargs);
if (argc &gt; 10) {
PyErr_SetString(PyExc_ValueError, "Too many arguments");
@ -528,7 +529,7 @@ like this:
return NULL;
}
pystr = PyUnicode_AsUTF8String(pyobj);
str = PyBytes_AsString(pystr);
str = strdup(PyBytes_AsString(pystr));
Py_XDECREF(pystr);
%#else
if (!PyString_Check(pyobj)) {
@ -537,22 +538,34 @@ like this:
}
str = PyString_AsString(pyobj);
%#endif
args[i] = str;
vargs[i] = str;
}
$1 = (void *) args;
$1 = (void *)vargs;
}
%typemap(freearg) (...) {
%#if PY_VERSION_HEX&gt;=0x03000000
int i;
for (i = 0; i &lt; 10; i++) {
free(vargs$argnum[i]);
}
%#endif
}
</pre>
</div>
<p>
In this typemap, the special variable <tt>varargs</tt> is a tuple
In the 'in' typemap, the special variable <tt>varargs</tt> is a tuple
holding all of the extra arguments passed (this is specific to the
Python module). The typemap then pulls this apart and sticks the
values into the array of strings <tt>args</tt>. Then, the array is
assigned to <tt>$1</tt> (recall that this is the <tt>void *</tt>
variable corresponding to <tt>(...)</tt>). However, this assignment
is only half of the picture----clearly this alone is not enough to
make the function work. To patch everything up, you have to rewrite the
make the function work. The 'freearg' typemap cleans up memory
allocated in the 'in' typemap; this code is generated to be called
after the <tt>execlp</tt> function is called. To patch everything
up, you have to rewrite the
underlying action code using the <tt>%feature</tt> directive like
this:
</p>
@ -560,9 +573,9 @@ this:
<div class="code">
<pre>
%feature("action") execlp {
char *args = (char **) arg3;
result = execlp(arg1, arg2, args[0], args[1], args[2], args[3], args[4],
args[5],args[6],args[7],args[8],args[9], NULL);
char **vargs = (char **) arg3;
result = execlp(arg1, arg2, vargs[0], vargs[1], vargs[2], vargs[3], vargs[4],
vargs[5], vargs[6], vargs[7], vargs[8], vargs[9], NULL);
}
int execlp(const char *path, const char *arg, ...);
@ -577,7 +590,7 @@ really want to elevate your guru status and increase your job
security, continue to the next section.
</p>
<H2><a name="Varargs_nn7"></a>13.6 Varargs wrapping with libffi</H2>
<H2><a name="Varargs_nn7">14.6 Varargs wrapping with libffi</a></H2>
<p>
@ -593,7 +606,7 @@ you need to bring out some bigger guns.
<p>
One way to do this is to use a special purpose library such as libffi
(<a
href="http://sources.redhat.com/libffi/">http://sources.redhat.com/libffi</a>).
href="http://www.sourceware.org/libffi/">http://www.sourceware.org/libffi/</a>).
libffi is a library that allows you to dynamically construct
call-stacks and invoke procedures in a relatively platform independent
manner. Details about the library can be found in the libffi
@ -623,7 +636,7 @@ example. For example:
PyObject *o = PyTuple_GetItem(varargs,i);
if (!PyString_Check(o)) {
PyErr_SetString(PyExc_ValueError,"Expected a string");
free(argv);
free(argv);
return NULL;
}
argv[i] = PyString_AsString(o);
@ -829,7 +842,7 @@ provide an argument number for the first extra argument. This can be used to in
values. Please consult the chapter on each language module for more details.
</p>
<H2><a name="Varargs_nn8"></a>13.7 Wrapping of va_list</H2>
<H2><a name="Varargs_nn8">14.7 Wrapping of va_list</a></H2>
<p>
@ -839,13 +852,13 @@ of type <tt>va_list</tt>. For example:
<div class="code">
<pre>
int vfprintf(FILE *f, const char *fmt, va_list ap);
int vprintf(const char *fmt, va_list ap);
</pre>
</div>
<p>
As far as we know, there is no obvious way to wrap these functions
with SWIG. This is because there is no documented way to assemble the
As far as we know, there is no obvious way to wrap these functions with
SWIG. This is because there is no documented way to assemble the
proper va_list structure (there are no C library functions to do it
and the contents of va_list are opaque). Not only that, the contents
of a <tt>va_list</tt> structure are closely tied to the underlying
@ -853,7 +866,37 @@ call-stack. It's not clear that exporting a <tt>va_list</tt> would
have any use or that it would work at all.
</p>
<H2><a name="Varargs_nn9"></a>13.8 C++ Issues</H2>
<p>
A workaround can be implemented by writing a simple varargs C wrapper and then using the techniques
discussed earlier in this chapter for varargs. Below is a simple wrapper for <tt>vprintf</tt> renamed so that
it can still be called as <tt>vprintf</tt> from your target language. The <tt>%varargs</tt>
used in the example restricts the function to taking one string argument.
</p>
<div class="code">
<pre>
%{
int vprintf(const char *fmt, va_list ap);
%}
%varargs(const char *) my_vprintf;
%rename(vprintf) my_vprintf;
%inline %{
int my_vprintf(const char *fmt, ...) {
va_list ap;
int result;
va_start(ap, fmt);
result = vprintf(fmt, ap);
va_end(ap);
return result;
}
%}
</pre>
</div>
<H2><a name="Varargs_nn9">14.8 C++ Issues</a></H2>
<p>
@ -922,7 +965,7 @@ design or to provide an alternative interface using a helper function than it is
fully general wrapper to a varargs C++ member function.
</p>
<H2><a name="Varargs_nn10"></a>13.9 Discussion</H2>
<H2><a name="Varargs_nn10">14.9 Discussion</a></H2>
<p>

61
Doc/Manual/Warnings.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Warning Messages</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Warnings"></a>14 Warning Messages</H1>
<H1><a name="Warnings">15 Warning Messages</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -35,7 +36,7 @@
<H2><a name="Warnings_nn2"></a>14.1 Introduction</H2>
<H2><a name="Warnings_nn2">15.1 Introduction</a></H2>
<p>
@ -55,7 +56,7 @@ where the generated wrapper code will probably compile, but it may not
work like you expect.
</p>
<H2><a name="Warnings_suppression"></a>14.2 Warning message suppression</H2>
<H2><a name="Warnings_suppression">15.2 Warning message suppression</a></H2>
<p>
@ -147,7 +148,7 @@ your interface. Ignore the warning messages at your own peril.
</p>
<H2><a name="Warnings_nn4"></a>14.3 Enabling extra warnings</H2>
<H2><a name="Warnings_nn4">15.3 Enabling extra warnings</a></H2>
<p>
@ -220,7 +221,7 @@ that is, any warnings suppressed or added in <tt>%warnfilter</tt>, <tt>#pragma S
or the <tt>-w</tt> option.
</p>
<H2><a name="Warnings_nn5"></a>14.4 Issuing a warning message</H2>
<H2><a name="Warnings_nn5">15.4 Issuing a warning message</a></H2>
<p>
@ -274,7 +275,7 @@ example.i:24: Warning 901: You are really going to regret this usage of blah * s
</pre>
</div>
<H2><a name="Warnings_symbolic_symbols"></a>14.5 Symbolic symbols</H2>
<H2><a name="Warnings_symbolic_symbols">15.5 Symbolic symbols</a></H2>
<p>
@ -309,7 +310,7 @@ or
</pre>
</div>
<H2><a name="Warnings_nn6"></a>14.6 Commentary</H2>
<H2><a name="Warnings_nn6">15.6 Commentary</a></H2>
<p>
@ -326,7 +327,7 @@ no obvious recovery. There is no mechanism for suppressing error
messages.
</p>
<H2><a name="Warnings_nn7"></a>14.7 Warnings as errors</H2>
<H2><a name="Warnings_nn7">15.7 Warnings as errors</a></H2>
<p>
@ -335,7 +336,7 @@ option. This will cause SWIG to exit with a non successful exit code if a
warning is encountered.
</p>
<H2><a name="Warnings_nn8"></a>14.8 Message output format</H2>
<H2><a name="Warnings_nn8">15.8 Message output format</a></H2>
<p>
@ -349,15 +350,15 @@ These can be overridden using command line options, for example:
<div class="shell"><pre>
$ swig -python -Fstandard example.i
example.i:4: Syntax error in input.
example.i:4: Syntax error in input(1).
$ swig -python -Fmicrosoft example.i
example.i(4) : Syntax error in input.
example.i(4) : Syntax error in input(1).
</pre></div>
<H2><a name="Warnings_nn9"></a>14.9 Warning number reference</H2>
<H2><a name="Warnings_nn9">15.9 Warning number reference</a></H2>
<H3><a name="Warnings_nn10"></a>14.9.1 Deprecated features (100-199)</H3>
<H3><a name="Warnings_nn10">15.9.1 Deprecated features (100-199)</a></H3>
<ul>
@ -382,9 +383,10 @@ example.i(4) : Syntax error in input.
<li>119. Deprecated <tt>%typemap(ignore)</tt>.
<li>120. Deprecated command line option (-runtime, -noruntime).
<li>121. Deprecated <tt>%name</tt> directive.
<li>126. The 'nestedworkaround' feature is deprecated.
</ul>
<H3><a name="Warnings_nn11"></a>14.9.2 Preprocessor (200-299)</H3>
<H3><a name="Warnings_nn11">15.9.2 Preprocessor (200-299)</a></H3>
<ul>
@ -396,7 +398,7 @@ example.i(4) : Syntax error in input.
<li>206. Unexpected tokens after #<em>directive</em> directive.
</ul>
<H3><a name="Warnings_nn12"></a>14.9.3 C/C++ Parser (300-399)</H3>
<H3><a name="Warnings_nn12">15.9.3 C/C++ Parser (300-399)</a></H3>
<ul>
@ -423,7 +425,8 @@ example.i(4) : Syntax error in input.
<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>325. Nested <em>kind</em> not currently supported (<em>name</em> ignored).
<li>326. Deprecated %extend name used - the <em>kind</em> name '<em>name</em>' should be used instead of the typedef name '<em>name</em>'.
<li>350. operator new ignored.
<li>351. operator delete ignored.
<li>352. operator+ ignored.
@ -472,7 +475,7 @@ example.i(4) : Syntax error in input.
<li>395. operator delete[] ignored.
</ul>
<H3><a name="Warnings_nn13"></a>14.9.4 Types and typemaps (400-499) </H3>
<H3><a name="Warnings_nn13">15.9.4 Types and typemaps (400-499) </a></H3>
<ul>
@ -490,18 +493,20 @@ example.i(4) : Syntax error in input.
<li>464. Unsupported constant value.
<li>465. Unable to handle type <em>type</em>.
<li>466. Unsupported variable type <em>type</em>.
<li>467. Overloaded <em>declaration</em> not supported (no type checking rule for '<em>type</em>')
<li>467. Overloaded <em>declaration</em> not supported (incomplete type checking rule - no precedence level in typecheck typemap for '<em>type</em>')
<li>468. No 'throw' typemap defined for exception type <em>type</em>
<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 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.
<li>476. Initialization using std::initializer_list.
<li>477. No directorthrows typemap defined for <em>type</em>
</ul>
<H3><a name="Warnings_nn14"></a>14.9.5 Code generation (500-599)</H3>
<H3><a name="Warnings_nn14">15.9.5 Code generation (500-599)</a></H3>
<ul>
@ -526,9 +531,11 @@ example.i(4) : Syntax error in input.
<li>519. %template() contains no name. Template method ignored: <em>declaration</em>
<li>520. <em>Base/Derived</em> class '<em>classname1</em>' of '<em>classname2</em>' is not similarly marked as a smart pointer.
<li>521. Illegal destructor name <em>name</em>. Ignored.
<li>522. Use of an illegal constructor name '<em>name</em>' in %extend is deprecated, the constructor name should be '<em>name</em>'.
<li>523. Use of an illegal destructor name '<em>name</em>' in %extend is deprecated, the destructor name should be '<em>name</em>'.
</ul>
<H3><a name="Warnings_nn15"></a>14.9.6 Language module specific (700-899) </H3>
<H3><a name="Warnings_nn15">15.9.6 Language module specific (700-899) </a></H3>
<ul>
@ -539,7 +546,7 @@ example.i(4) : Syntax error in input.
<li>810. No jni typemap defined for <em>type</em> (Java).
<li>811. No jtype typemap defined for <em>type</em> (Java).
<li>812. No jstype typemap defined for <em>type</em> (Java).
<li>813. Warning for <em>classname</em>: Base <em>baseclass</em> ignored. Multiple inheritance is not supported in Java. (Java).
<li>813. Warning for <em>classname</em>, base <em>baseclass</em> ignored. Multiple inheritance is not supported in Java. (Java).
<li>814.
<li>815. No javafinalize typemap defined for <em>type</em> (Java).
<li>816. No javabody typemap defined for <em>type</em> (Java).
@ -551,13 +558,15 @@ example.i(4) : Syntax error in input.
<li>822. Covariant return types not supported in Java. Proxy method will return <em>basetype</em> (Java).
<li>823. No javaconstruct typemap defined for <em>type</em> (Java).
<li>824. Missing JNI descriptor in directorin typemap defined for <em>type</em> (Java).
<li>825. "directorconnect" attribute missing in <em>type</em> "javaconstruct" typemap. (Java).
<li>826. The nspace feature is used on '<em>type</em>' without -package. The generated code may not compile as Java does not support types declared in a named package accessing types declared in an unnamed package. (Java).
</ul>
<ul>
<li>830. No ctype typemap defined for <em>type</em> (C#).
<li>831. No cstype typemap defined for <em>type</em> (C#).
<li>832. No cswtype typemap defined for <em>type</em> (C#).
<li>833. Warning for <em>classname</em>: Base <em>baseclass</em> ignored. Multiple inheritance is not supported in C#. (C#).
<li>833. Warning for <em>classname</em>, base <em>baseclass</em> ignored. Multiple inheritance is not supported in C#. (C#).
<li>834.
<li>835. No csfinalize typemap defined for <em>type</em> (C#).
<li>836. No csbody typemap defined for <em>type</em> (C#).
@ -573,18 +582,18 @@ example.i(4) : Syntax error in input.
</ul>
<ul>
<li>870. Warning for <em>classname</em>: Base <em>baseclass</em> ignored. Multiple inheritance is not supported in PHP.
<li>870. Warning for <em>classname</em>: Base <em>baseclass</em> ignored. Multiple inheritance is not supported in PHP. (Php).
<li>871. Unrecognized pragma <em>pragma</em>. (Php).
</ul>
<H3><a name="Warnings_nn16"></a>14.9.7 User defined (900-999)</H3>
<H3><a name="Warnings_nn16">15.9.7 User defined (900-999)</a></H3>
<p>
These numbers can be used by your own application.
</p>
<H2><a name="Warnings_nn17"></a>14.10 History</H2>
<H2><a name="Warnings_nn17">15.10 History</a></H2>
<p>

116
Doc/Manual/Windows.html
View file

@ -1,12 +1,13 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Getting started on Windows</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="Windows"></a>3 Getting started on Windows </H1>
<H1><a name="Windows">3 Getting started on Windows </a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -52,7 +53,7 @@ Usage within the Unix like environments MinGW and Cygwin is also detailed.
</p>
<H2><a name="Windows_installation"></a>3.1 Installation on Windows</H2>
<H2><a name="Windows_installation">3.1 Installation on Windows</a></H2>
<p>
@ -63,7 +64,7 @@ SWIG does not come with the usual Windows type installation program, however it
<li>Set environment variables as described in the <a href="#Windows_examples">SWIG Windows Examples</a> section in order to run examples using Visual C++.
</ul>
<H3><a name="Windows_executable"></a>3.1.1 Windows Executable</H3>
<H3><a name="Windows_executable">3.1.1 Windows Executable</a></H3>
<p>
@ -72,22 +73,22 @@ If you want to build your own swig.exe have a look at <a href="#Windows_swig_exe
</p>
<H2><a name="Windows_examples"></a>3.2 SWIG Windows Examples</H2>
<H2><a name="Windows_examples">3.2 SWIG Windows Examples</a></H2>
<p>
Using Microsoft Visual C++ is the most common approach to compiling and linking SWIG's output.
The Examples directory has a few Visual C++ project files (.dsp files).
These were produced by Visual C++ 6.
Later versions of Visual Studio should also be able to open and convert these project files.
The C# examples come with .NET 2003 solution (.sln) and project files instead of Visual C++ 6 project files.
Newer versions of Visual Studio should be able to open and convert these project files.
Each C# example comes with a Visual Studio 2005 solution and associated project files instead of Visual C++ 6 project files.
The project files have been set up to execute SWIG in a custom build rule for the SWIG interface (.i) file.
Alternatively run the <a href="#Windows_examples_cygwin">examples using Cygwin</a>.
<p>
More information on each of the examples is available with the examples distributed with SWIG (Examples/index.html).
<H3><a name="Windows_visual_studio"></a>3.2.1 Instructions for using the Examples with Visual Studio</H3>
<H3><a name="Windows_visual_studio">3.2.1 Instructions for using the Examples with Visual Studio</a></H3>
<p>
@ -105,7 +106,7 @@ If you don't want to use environment variables then change all occurrences of th
If you are interested in how the project files are set up there is explanatory information in some of the language module's documentation.
</p>
<H4><a name="Windows_csharp"></a>3.2.1.1 C#</H4>
<H4><a name="Windows_csharp">3.2.1.1 C#</a></H4>
<p>
@ -115,7 +116,7 @@ The accompanying C# and C++ project files are automatically used by the solution
</p>
<H4><a name="Windows_java"></a>3.2.1.2 Java</H4>
<H4><a name="Windows_java">3.2.1.2 Java</a></H4>
<p>
@ -129,7 +130,7 @@ JAVA_BIN: D:\jdk1.3\bin<br>
</p>
<H4><a name="Windows_perl"></a>3.2.1.3 Perl</H4>
<H4><a name="Windows_perl">3.2.1.3 Perl</a></H4>
<p>
@ -143,11 +144,11 @@ PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib<br>
</p>
<H4><a name="Windows_python"></a>3.2.1.4 Python</H4>
<H4><a name="Windows_python">3.2.1.4 Python</a></H4>
<p>
<b><tt>PYTHON_INCLUDE</tt></b> : Set this to the directory that contains python.h<br>
<b><tt>PYTHON_INCLUDE</tt></b> : Set this to the directory that contains Python.h<br>
<b><tt>PYTHON_LIB</tt></b> : Set this to the python library including path for linking<p>
Example using Python 2.1.1:<br>
<tt>
@ -157,13 +158,13 @@ PYTHON_LIB: D:\python21\libs\python21.lib<br>
</p>
<H4><a name="Windows_tcl"></a>3.2.1.5 TCL</H4>
<H4><a name="Windows_tcl">3.2.1.5 TCL</a></H4>
<p>
<b><tt>TCL_INCLUDE</tt></b> : Set this to the directory containing tcl.h<br>
<b><tt>TCL_LIB</tt></b> : Set this to the TCL library including path for linking<p>
Example using ActiveTcl 8.3.3.3 <br>
Example using ActiveTcl 8.3.3.3<br>
<tt>
TCL_INCLUDE: D:\tcl\include<br>
TCL_LIB: D:\tcl\lib\tcl83.lib<br>
@ -171,7 +172,7 @@ TCL_LIB: D:\tcl\lib\tcl83.lib<br>
</p>
<H4><a name="Windows_r"></a>3.2.1.6 R</H4>
<H4><a name="Windows_r">3.2.1.6 R</a></H4>
<p>
@ -185,7 +186,7 @@ R_LIB: C:\Program Files\R\R-2.5.1\bin\Rdll.lib<br>
</p>
<H4><a name="Windows_ruby"></a>3.2.1.7 Ruby</H4>
<H4><a name="Windows_ruby">3.2.1.7 Ruby</a></H4>
<p>
@ -199,21 +200,21 @@ RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib<br>
</p>
<H3><a name="Windows_other_compilers"></a>3.2.2 Instructions for using the Examples with other compilers</H3>
<H3><a name="Windows_other_compilers">3.2.2 Instructions for using the Examples with other compilers</a></H3>
<p>
If you do not have access to Visual C++ you will have to set up project files / Makefiles for your chosen compiler. There is a section in each of the language modules detailing what needs setting up using Visual C++ which may be of some guidance. Alternatively you may want to use Cygwin as described in the following section.
</p>
<H2><a name="Windows_cygwin_mingw"></a>3.3 SWIG on Cygwin and MinGW</H2>
<H2><a name="Windows_cygwin_mingw">3.3 SWIG on Cygwin and MinGW</a></H2>
<p>
SWIG can also be compiled and run using <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> which provides a Unix like front end to Windows and comes free with gcc, an ANSI C/C++ compiler. However, this is not a recommended approach as the prebuilt executable is supplied.
</p>
<H3><a name="Windows_swig_exe"></a>3.3.1 Building swig.exe on Windows</H3>
<H3><a name="Windows_swig_exe">3.3.1 Building swig.exe on Windows</a></H3>
<p>
@ -223,7 +224,7 @@ This information is provided for those that want to modify the SWIG source code
Normally this is not needed, so most people will want to ignore this section.
</p>
<H4><a name="Windows_mingw_msys"></a>3.3.1.1 Building swig.exe using MinGW and MSYS</H4>
<H4><a name="Windows_mingw_msys">3.3.1.1 Building swig.exe using MinGW and MSYS</a></H4>
<p>
@ -236,8 +237,8 @@ The short abbreviated instructions follow...
</ul>
<p>
The step by step instructions to download and install MinGW and MSYS, then download and build the latest version of SWIG from SVN follow...
Note that the instructions for obtaining SWIG from SVN are also online at <a href="http://www.swig.org/svn.html">SWIG SVN</a>.
The step by step instructions to download and install MinGW and MSYS, then download and build the latest version of SWIG from Github follow...
Note that the instructions for obtaining SWIG from Github are also online at <a href="http://www.swig.org/svn.html">SWIG Bleeding Edge</a>.
</p>
<p>
@ -293,22 +294,26 @@ Execute the steps in the order shown and don't use spaces in path names. In fact
Start the MSYS command prompt and execute:
<div class="shell"><pre>
cd /
tar -jxf msys-automake-1.8.2.tar.bz2
tar -jxf msys-automake-1.8.2.tar.bz2
tar -jxf msys-autoconf-2.59.tar.bz2
tar -zxf bison-2.0-MSYS.tar.gz
tar -zxf bison-2.0-MSYS.tar.gz
</pre></div>
</li>
<li>
To get the latest SWIG SVN (version from Subversion source control), type in the following:
The very latest development version of SWIG is available from <a href="https://github.com/swig/swig">SWIG on Github</a>
and can be downloaded as a zip file or if you have Git installed, via Git.
Either download the latest <a href="https://github.com/swig/swig/archive/master.zip">Zip file</a> snapshot and unzip and rename the top level folder to /usr/src/swig.
Otherwise if using Git, type in the following:
<div class="shell"><pre>
mkdir /usr/src
cd /usr/src
svn co https://swig.svn.sourceforge.net/svnroot/swig/trunk swig
git clone https://github.com/swig/swig.git
</pre></div>
<b>Pitfall note:</b>
If you want to check out SWIG to a different folder to the proposed
If you want to place SWIG in a different folder to the proposed
/usr/src/swig, do not use MSYS emulated windows drive letters, because
the autotools will fail miserably on those.
</li>
@ -337,7 +342,7 @@ make
</ol>
<H4><a name="Windows_cygwin"></a>3.3.1.2 Building swig.exe using Cygwin</H4>
<H4><a name="Windows_cygwin">3.3.1.2 Building swig.exe using Cygwin</a></H4>
<p>
@ -348,7 +353,7 @@ Note that the Cygwin environment will also allow one to regenerate the autotool
These files are generated using the <tt>autogen.sh</tt> script and will only need regenerating in circumstances such as changing the build system.
</p>
<H4><a name="Windows_building_alternatives"></a>3.3.1.3 Building swig.exe alternatives</H4>
<H4><a name="Windows_building_alternatives">3.3.1.3 Building swig.exe alternatives</a></H4>
<p>
@ -358,7 +363,7 @@ file in order to build swig.exe from the Visual C++ IDE.
</p>
<H3><a name="Windows_examples_cygwin"></a>3.3.2 Running the examples on Windows using Cygwin</H3>
<H3><a name="Windows_examples_cygwin">3.3.2 Running the examples on Windows using Cygwin</a></H3>
<p>
@ -367,7 +372,7 @@ The modules which are known to work are Python, Tcl, Perl, Ruby, Java and C#.
Follow the Unix instructions in the README file in the SWIG root directory to build the examples.
</p>
<H2><a name="Windows_interface_file"></a>3.4 Microsoft extensions and other Windows quirks</H2>
<H2><a name="Windows_interface_file">3.4 Microsoft extensions and other Windows quirks</a></H2>
<p>
@ -384,6 +389,53 @@ Include it like you would any other interface file, for example:
__declspec(dllexport) ULONG __stdcall foo(DWORD, __int32);
</pre></div>
<p>Note that if you follow Microsoft's recommendation of wrapping the
<tt>__declspec</tt> calls in a preprocessor definition, you will need to
make sure that the definition is included by SWIG as well, by either defining it
manually or via a header. For example, if you have specified the
preprocessor definition in a header named <tt>export_lib.h</tt> and include
other headers which depend on it, you should use the <tt>%include</tt> directive
to include the definition explicitly. For example, if you had a header file,
<tt>bar.h</tt>, which depended on <tt>export_lib.h</tt>, your SWIG definition
file might look like:</p>
<div class="code"><pre>
// bar.i
%module bar
%include &lt;windows.i&gt;
%include "export_lib.h"
%include "bar.h"
</pre></div>
<p>
where export_lib.h may contain:
</p>
<div class="code"><pre>
// export_lib.h
#define BAR_API __declspec(dllexport)
</pre></div>
<p>
and bar.h may look like:
</p>
<div class="code"><pre>
// bar.h
#include "export_lib.h"
BAR_API void bar_function(int, double);
</pre></div>
<p>
Using the preprocessor to remove BAR_API is a popular simpler solution:
</p>
<div class="code"><pre>
// bar.i
%module bar
#define BAR_API
%include "bar.h"
</pre></div>
</body>
</html>

3
Doc/Manual/chapters
View file

@ -4,6 +4,7 @@ Windows.html
Scripting.html
SWIG.html
SWIGPlus.html
CPlusPlus11.html
Preprocessor.html
Library.html
Arguments.html
@ -23,6 +24,7 @@ D.html
Go.html
Guile.html
Java.html
Javascript.html
Lisp.html
Lua.html
Modula3.html
@ -35,5 +37,6 @@ Pike.html
Python.html
R.html
Ruby.html
Scilab.html
Tcl.html
Extending.html

15
Doc/Manual/fixstyle.py
View file

@ -1,6 +1,6 @@
#!/usr/bin/python
# Adds the SWIG stylesheet to the generated documentation on a single page
# Replace the inline htmldoc stylesheet with the SWIG stylesheet
import sys
import string
@ -14,11 +14,16 @@ swigstyle = "\n" + open("style.css").read()
lines = data.splitlines()
result = [ ]
skip = False
for s in lines:
if s == "<STYLE TYPE=\"text/css\"><!--":
result.append(s + swigstyle)
else:
result.append(s)
if not skip:
result.append(s)
if s == "<STYLE TYPE=\"text/css\"><!--":
result.append(swigstyle)
skip = True
elif s == "--></STYLE>":
result.append(s)
skip = False
data = "\n".join(result)

7
Doc/Manual/index.html
View file

@ -1,10 +1,11 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG-2.0 Documentation</title>
<title>SWIG-3.0 Documentation</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body bgcolor="#ffffff">
<H1><a name="index"></a>SWIG-2.0 Documentation</h1>
<H1><a name="index">SWIG-3.0 Documentation</a></H1>
The SWIG documentation is available in one of the following formats.
<ul>

4
Doc/Manual/linkchecker.config
View file

@ -1,5 +1,3 @@
[checking]
anchors=1
[filtering]
ignorewarnings=http-robots-denied
ignorewarnings=https-certificate-error

45
Doc/Manual/makechap.py
View file

@ -21,7 +21,7 @@ import string
###############################################################################
# Regexs for <a name="..."></a>
alink = re.compile(r"<a *name *= *\"(.*)\"></a>", re.IGNORECASE)
alink = re.compile(r"<a *name *= *\"(.*)\">.*</a>", re.IGNORECASE)
heading = re.compile(r"(_nn\d)", re.IGNORECASE)
def getheadingname(m):
@ -38,6 +38,19 @@ def getheadingname(m):
headingname = "%s_nn%d" % (filenamebase, nameindex)
return headingname
# Return heading - 1.1. Introduction in the examples below:
# old style example: <H2><a name="Preface_nn2"></a>1.1 Introduction</H2>
# new style example: <H2><a name="Preface_nn2">1.1 Introduction</a></H2>
def getheadingtext(m, s):
prevheadingtext_newstyle = m.group(2)
prevheadingtext_oldstyle = m.group(3)
if len(prevheadingtext_oldstyle) == 0 and len(prevheadingtext_newstyle) == 0:
raise RuntimeError("No heading text in line:\n%s" % s)
if len(prevheadingtext_oldstyle) > 0 and len(prevheadingtext_newstyle) > 0:
raise RuntimeError("Two heading texts, only one should be specified in line:\n%s" % s)
prevheadingtext = prevheadingtext_oldstyle if len(prevheadingtext_oldstyle) > 0 else prevheadingtext_newstyle
return prevheadingtext
###############################################################################
# Main program
###############################################################################
@ -59,11 +72,11 @@ name = ""
# Regexs for <h1>,... <h5> sections
h1 = re.compile(r".*?<H1>(<a.*a>)*[\d\.\s]*(.*?)</H1>", re.IGNORECASE)
h2 = re.compile(r".*?<H2>(<a.*a>)*[\d\.\s]*(.*?)</H2>", re.IGNORECASE)
h3 = re.compile(r".*?<H3>(<a.*a>)*[\d\.\s]*(.*?)</H3>", re.IGNORECASE)
h4 = re.compile(r".*?<H4>(<a.*a>)*[\d\.\s]*(.*?)</H4>", re.IGNORECASE)
h5 = re.compile(r".*?<H5>(<a.*a>)*[\d\.\s]*(.*?)</H5>", re.IGNORECASE)
h1 = re.compile(r".*?<H1>(<a.*?>\s*[\d\s]*(.*?)</a>)*[\d\s]*(.*?)</H1>", re.IGNORECASE)
h2 = re.compile(r".*?<H2>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H2>", re.IGNORECASE)
h3 = re.compile(r".*?<H3>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H3>", re.IGNORECASE)
h4 = re.compile(r".*?<H4>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H4>", re.IGNORECASE)
h5 = re.compile(r".*?<H5>(<a.*?>\s*[\d\.\s]*(.*?)</a>)*[\d\.\s]*(.*?)</H5>", re.IGNORECASE)
data = open(filename).read() # Read data
open(filename+".bak","w").write(data) # Make backup
@ -95,10 +108,10 @@ for s in lines:
m = h1.match(s)
if m:
prevheadingtext = m.group(2)
prevheadingtext = getheadingtext(m, s)
nameindex += 1
headingname = getheadingname(m)
result.append("""<H1><a name="%s"></a>%d %s</H1>""" % (headingname,num,prevheadingtext))
result.append("""<H1><a name="%s">%d %s</a></H1>""" % (headingname,num,prevheadingtext))
result.append("@INDEX@")
section = 0
subsection = 0
@ -109,11 +122,11 @@ for s in lines:
continue
m = h2.match(s)
if m:
prevheadingtext = m.group(2)
prevheadingtext = getheadingtext(m, s)
nameindex += 1
section += 1
headingname = getheadingname(m)
result.append("""<H2><a name="%s"></a>%d.%d %s</H2>""" % (headingname,num,section, prevheadingtext))
result.append("""<H2><a name="%s">%d.%d %s</a></H2>""" % (headingname,num,section, prevheadingtext))
if subsubsubsection:
index += "</ul>\n"
@ -132,11 +145,11 @@ for s in lines:
continue
m = h3.match(s)
if m:
prevheadingtext = m.group(2)
prevheadingtext = getheadingtext(m, s)
nameindex += 1
subsection += 1
headingname = getheadingname(m)
result.append("""<H3><a name="%s"></a>%d.%d.%d %s</H3>""" % (headingname,num,section, subsection, prevheadingtext))
result.append("""<H3><a name="%s">%d.%d.%d %s</a></H3>""" % (headingname,num,section, subsection, prevheadingtext))
if subsubsubsection:
index += "</ul>\n"
@ -151,12 +164,12 @@ for s in lines:
continue
m = h4.match(s)
if m:
prevheadingtext = m.group(2)
prevheadingtext = getheadingtext(m, s)
nameindex += 1
subsubsection += 1
headingname = getheadingname(m)
result.append("""<H4><a name="%s"></a>%d.%d.%d.%d %s</H4>""" % (headingname,num,section, subsection, subsubsection, prevheadingtext))
result.append("""<H4><a name="%s">%d.%d.%d.%d %s</a></H4>""" % (headingname,num,section, subsection, subsubsection, prevheadingtext))
if subsubsubsection:
index += "</ul>\n"
@ -169,11 +182,11 @@ for s in lines:
continue
m = h5.match(s)
if m:
prevheadingtext = m.group(2)
prevheadingtext = getheadingtext(m, s)
nameindex += 1
subsubsubsection += 1
headingname = getheadingname(m)
result.append("""<H5><a name="%s"></a>%d.%d.%d.%d.%d %s</H5>""" % (headingname,num,section, subsection, subsubsection, subsubsubsection, prevheadingtext))
result.append("""<H5><a name="%s">%d.%d.%d.%d.%d %s</a></H5>""" % (headingname,num,section, subsection, subsubsection, subsubsubsection, prevheadingtext))
if subsubsubsection == 1:
index += "<ul>\n"

4
Doc/Manual/maketoc.py
View file

@ -6,12 +6,14 @@ chs = open("chapters").readlines()
f = open("Contents.html","w")
print >>f, """
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>SWIG Users Manual</TITLE>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</HEAD>
<BODY BGCOLOR="#ffffff">
<H1><a name="Contents"></a>SWIG Users Manual</H1>
<p>

269
Doc/Manual/margin-left.patch
View file

@ -1,269 +0,0 @@
#
# Patch managed by http://www.holgerschurig.de/patcher.html
#
# This patch is against htmldoc 1.8.24, and it hacks in support for
# correctly indenting the <div class=""> sections in the SWIG manual.
# This patch should only be used until the 1.9 branch of htmldoc
# stabalizes, since the 1.9 branch includes true CSS1 support.
#
# This patch only affects the PDF generation, an unpatched htmldoc
# creates the one-page html documentation just fine.
#
--- htmldoc-1.8.24/htmldoc/ps-pdf.cxx~margin-left
+++ htmldoc-1.8.24/htmldoc/ps-pdf.cxx
@@ -158,6 +158,7 @@
# undef page_t
#endif // __hpux
+extern int lookup_div_class(uchar *);
/*
* Constants...
@@ -4188,9 +4189,24 @@
para->child = para->last_child = NULL;
}
- parse_doc(t->child, left, right, bottom, top, x, y, page, NULL,
+ {
+ int num_indent = 0;
+ uchar *cname;
+
+ if (cname = htmlGetVariable(t, (uchar *)"class")) {
+ num_indent = lookup_div_class(cname);
+ *left += 5.0f * num_indent;
+ *x = *left;
+ }
+
+ parse_doc(t->child, left, right, bottom, top, x, y, page, NULL,
needspace);
+ if (num_indent > 0) {
+ *left -= 5.0f * num_indent;
+ }
+ }
+
if (para->child != NULL)
{
parse_paragraph(para, *left, *right, *bottom, *top, x, y, page, *needspace);
--- htmldoc-1.8.24/htmldoc/htmldoc.cxx~margin-left
+++ htmldoc-1.8.24/htmldoc/htmldoc.cxx
@@ -62,6 +62,8 @@
const char *__XOS2RedirRoot(const char *);
}
#endif
+
+extern void parse_style(char *);
/*
@@ -2140,6 +2142,10 @@
}
else if (strcmp(temp, "--cookies") == 0)
file_cookies(temp2);
+ else if (strcmp(temp, "--stylesheet") == 0)
+ {
+ parse_style(temp2);
+ }
}
}
--- /dev/null
+++ htmldoc-1.8.24/htmldoc/style.cxx
@@ -0,0 +1,185 @@
+/* Extreamly simple parsing routines for CSS style sheets.
+ * We only parse div.class { } sections, and only look
+ * for margin-left: <num>em;
+ *
+ * Copyright (C) 2005 John Lenz <lenz@cs.wisc.edu>
+ *
+ * Released under GNU GPL v2 or above.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <fcntl.h>
+#include <string.h>
+#include <ctype.h>
+
+#include "types.h"
+
+#define BUFF_SIZE 512
+
+struct div_entry {
+ uchar class_name[BUFF_SIZE];
+ int indent;
+ struct div_entry *next;
+};
+
+static struct div_entry *head = 0;
+
+/* These are the parsing states */
+#define IGNORE_TILL_SEMI 0
+#define IGNORE_TILL_CLOSE_BRACE 1
+#define READING_DIV 2
+#define READING_CLASS 3
+#define READING_ATTRIBUTE 4
+#define READING_NUM 5
+#define CHECKING_ONLY_DIV 6
+
+static int at_eof = 0;
+
+static int strucmp(uchar *a, uchar *b) {
+ int i;
+ for (i = 0; a[i] && b[i]; i++) {
+ if (a[i] < b[i]) return -1;
+ if (a[i] > b[i]) return 1;
+ }
+ /* This isn't right, but who cares...*/
+ if (a[i] || b[i]) return 1;
+ return 0;
+}
+
+static int read_word(FILE *f, const char *word) {
+ char c;
+ for (int idx = 0; word[idx]; idx++) {
+ c = getc(f);
+ if (c == EOF) {
+ at_eof = 1;
+ return 0;
+ }
+ if (c != word[idx])
+ return 0;
+ }
+ return 1;
+}
+
+int lookup_div_class(uchar *name) {
+ struct div_entry *node = head;
+
+ while (node) {
+ if (strucmp(node->class_name, name) == 0)
+ return node->indent;
+ node = node->next;
+ }
+
+ return 0;
+}
+
+void parse_style(char *fname) {
+ FILE *f;
+ char c;
+ int state;
+ struct div_entry *cur = 0;
+ int class_idx = 0;
+ char num[BUFF_SIZE];
+ int num_idx = 0;
+
+ if (!fname) return;
+
+ f = fopen(fname, "r");
+ if (!f) {
+ fprintf(stderr, "Unable to parse style\n");
+ return;
+ }
+
+ state = READING_DIV;
+ while (!at_eof && (c = getc(f)) != EOF) {
+ switch (state) {
+
+ case IGNORE_TILL_SEMI:
+ if (c == ';')
+ state = READING_ATTRIBUTE;
+ break;
+
+ case IGNORE_TILL_CLOSE_BRACE:
+ if (c == '}')
+ state = READING_DIV;
+ break;
+
+ case READING_DIV:
+ if (c != ' ' && c != '\t' && c != '\n') {
+ if (c == 'd' && read_word(f, "iv.")) {
+ state = READING_CLASS;
+ cur = (struct div_entry *) malloc(sizeof(struct div_entry));
+ memset(cur, 0, sizeof(struct div_entry));
+ class_idx = 0;
+ } else
+ state = IGNORE_TILL_CLOSE_BRACE;
+ }
+ break;
+
+ case READING_CLASS:
+ if (isalpha(c)) {
+ if (class_idx >= BUFF_SIZE-1) {
+ fprintf(stderr, "class size %s too long\n", cur->class_name);
+ free(cur);
+ state = IGNORE_TILL_CLOSE_BRACE;
+ } else {
+ cur->class_name[class_idx++] = c;
+ }
+ } else {
+ if (c == '{') {
+ cur->next = head;
+ head = cur;
+ state = READING_ATTRIBUTE;
+ } else
+ state = CHECKING_ONLY_DIV;
+ }
+ break;
+
+ case READING_ATTRIBUTE:
+ if (c != ' ' && c != '\t' && c != '\n') {
+ if (c == '}')
+ state = READING_DIV;
+ else {
+ if (c == 'm' && read_word(f, "argin-left:")) {
+ num_idx = 0;
+ memset(num, 0, sizeof(num));
+ state = READING_NUM;
+ } else {
+ state = IGNORE_TILL_SEMI;
+ }
+ }
+ }
+ break;
+
+ case READING_NUM:
+ if (isdigit(c)) {
+ if (num_idx >= BUFF_SIZE - 1) {
+ fprintf(stderr, "Number too long\n");
+ state = IGNORE_TILL_SEMI;
+ } else {
+ num[num_idx++] = c;
+ }
+ } else if (c != ' ' && c != '\t') {
+ if (num_idx > 0 && c == 'e' && read_word(f, "m"))
+ cur->indent = atoi(num);
+ state = IGNORE_TILL_SEMI;
+ }
+ break;
+
+ case CHECKING_ONLY_DIV:
+ if (c != ' ' && c != '\t' && c != '\n') {
+ if (c == '{') {
+ cur->next = head;
+ head = cur;
+ state = READING_ATTRIBUTE;
+ } else {
+ free(cur);
+ state = IGNORE_TILL_CLOSE_BRACE;
+ }
+ }
+ break;
+ }
+ }
+
+ fclose(f);
+}
--- htmldoc-1.8.24/htmldoc/Makefile~margin-left
+++ htmldoc-1.8.24/htmldoc/Makefile
@@ -35,7 +35,7 @@
OBJS = gui.o file.o html.o htmldoc.o htmllib.o htmlsep.o http.o \
http-addr.o http-support.o image.o iso8859.o license.o md5.o \
- progress.o ps-pdf.o rc4.o snprintf.o string.o toc.o util.o
+ progress.o ps-pdf.o rc4.o snprintf.o string.o toc.o util.o style.o
#

10
Doc/Manual/style.css
View file

@ -32,6 +32,7 @@ div.code {
margin-left: 4em;
margin-right: 4em;
background-color: #F0FFFF;
font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
}
div.targetlang {
@ -41,9 +42,9 @@ div.targetlang {
margin-left: 4em;
margin-right: 4em;
background-color: #d7f6bb;
font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
}
div.shell {
border-style: solid;
border-width: 1px;
@ -51,6 +52,7 @@ div.shell {
margin-left: 4em;
margin-right: 4em;
background-color: #DCDCDC;
font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
}
div.diagram {
@ -60,6 +62,7 @@ div.diagram {
margin-left: 4em;
margin-right: 4em;
background-color: #FFEBCD;
font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
}
ul li p {
@ -82,3 +85,8 @@ div.indent p {
margin-right: 0;
}
pre, code, tt {
font-family: "Courier New", Courier, "Courier 10 Pitch", monospace;
}
body { font-family: serif; }