diff options
31 files changed, 6601 insertions, 4648 deletions
diff --git a/Doc/Manual/Advanced.html b/Doc/Manual/Advanced.html index 1655e61dd..c164f97bb 100644 --- a/Doc/Manual/Advanced.html +++ b/Doc/Manual/Advanced.html @@ -7,23 +7,23 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>15 Advanced Topics</H1> +<H1><a name="Advanced"></a>29 Advanced Topics</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Creating multi-module packages</a> +<li><a href="#Advanced_nn2">Creating multi-module packages</a> <ul> -<li><a href="#n3">Runtime support (and potential problems)</a> -<li><a href="#n4">Why doesn't C++ inheritance work between modules?</a> -<li><a href="#n5">The SWIG runtime library</a> -<li><a href="#n6">A few dynamic loading gotchas</a> +<li><a href="#Advanced_nn3">Runtime support (and potential problems)</a> +<li><a href="#Advanced_nn4">Why doesn't C++ inheritance work between modules?</a> +<li><a href="#Advanced_nn5">The SWIG runtime library</a> +<li><a href="#Advanced_nn6">A few dynamic loading gotchas</a> </ul> -<li><a href="#n7">Dynamic Loading of C++ modules</a> -<li><a href="#n8">Inside the SWIG type-checker</a> +<li><a href="#Advanced_nn7">Dynamic Loading of C++ modules</a> +<li><a href="#Advanced_nn8">Inside the SWIG type-checker</a> <ul> -<li><a href="#n9">Type equivalence</a> -<li><a href="#n10">Type casting</a> -<li><a href="#n11">Why a name based approach?</a> -<li><a href="#n12">Performance of the type-checker</a> +<li><a href="#Advanced_nn9">Type equivalence</a> +<li><a href="#Advanced_nn10">Type casting</a> +<li><a href="#Advanced_nn11">Why a name based approach?</a> +<li><a href="#Advanced_nn12">Performance of the type-checker</a> </ul> </ul> <!-- INDEX --> @@ -32,27 +32,42 @@ <b>Caution: This chapter is under repair!</b> -<a name="n2"></a><H2>15.1 Creating multi-module packages</H2> +<H2><a name="Advanced_nn2"></a>29.1 Creating multi-module packages</H2> -SWIG can be used to create packages consisting of many different modules. However, there are some technical aspects of doing this and techniques for managing the problem.<p> +<p> +SWIG can be used to create packages consisting of many different modules. However, there are some technical aspects of doing this and techniques for managing the problem. +</p> + +<p> This chapter doesn't apply to those languages that use static type checking, rather than runtime type checking, such as Java and C#. -<a name="n3"></a><H3>15.1.1 Runtime support (and potential problems)</H3> +</p> + +<H3><a name="Advanced_nn3"></a>29.1.1 Runtime support (and potential problems)</H3> +<p> Most SWIG generated modules rely upon a small collection of functions that are used during run-time. These functions are primarily used for pointer type-checking, exception handling, and so on. When you run SWIG, these functions are included in the wrapper file (and declared as static). -If you create a system consisting of many modules, each one will have an identical copy of these runtime libraries :<p> -<center><img src="ch11.1.png"></center><p> +If you create a system consisting of many modules, each one will have an identical copy of these runtime libraries : +</p> + +<center><img src="ch11.1.png" alt="Modules 1-N each have their own identical runtime library"></center> + <p> -This duplication of runtime libraries is usually harmless since there are no namespace conflicts and memory overhead is minimal. However, there is serious problem related to the fact that modules do not share type-information. This is particularly a problem when working with C++ (as described next).<p> -<a name="n4"></a><H3>15.1.2 Why doesn't C++ inheritance work between modules?</H3> +This duplication of runtime libraries is usually harmless since there are no namespace conflicts and memory overhead is minimal. However, there is serious problem related to the fact that modules do not share type-information. This is particularly a problem when working with C++ (as described next). +</p> + +<H3><a name="Advanced_nn4"></a>29.1.2 Why doesn't C++ inheritance work between modules?</H3> -Consider for a moment the following two interface files :<p> <p> -<blockquote><pre>// File : a.i +Consider for a moment the following two interface files : +</p> + +<blockquote><pre> +// File : a.i %module a // Here is a base class @@ -76,8 +91,11 @@ public: }; </pre></blockquote> -When compiled into two separate modules, the code does not work properly. In fact, you get a type error such as the following:<p> + <p> +When compiled into two separate modules, the code does not work properly. In fact, you get a type error such as the following: +</p> + <blockquote><pre> [beazley@guinness shadow]$ <b>python</b> Python 1.4 (Jan 16 1997) [GCC 2.7.2] @@ -94,18 +112,26 @@ Traceback (innermost last): TypeError: Type error in argument 1 of a_foo. Expected _a_p. >>> </pre></blockquote> + <p> -However, from our class definitions we know that "b" is an "a" by inheritance and there should be no type-error. This problem is directly due to the lack of type-sharing between modules. If we look closely at the module modules created here, they look like this :<p> -<center><img src="ch11.2.png"></center><p> +However, from our class definitions we know that "b" is an "a" by inheritance and there should be no type-error. This problem is directly due to the lack of type-sharing between modules. If we look closely at the module modules created here, they look like this : +</p> + +<center><img src="ch11.2.png" alt="a accepts a, b accepts a and b, b accepts b"></center> + <p> -The type information listed shows the acceptable values for various C datatypes. In the "a" module, we see that "a" can only accept instances of itself. In the "b" module, we see that "a" can accept both "a" and "b" instances--which is correct given that a "b" is an "a" by inheritance.<p> +The type information listed shows the acceptable values for various C datatypes. In the "a" module, we see that "a" can only accept instances of itself. In the "b" module, we see that "a" can accept both "a" and "b" instances--which is correct given that a "b" is an "a" by inheritance. +</p> + <p> -Unfortunately, this problem is inherent in the method by which SWIG makes modules. When we made the "a" module, we had no idea what derived classes might be used at a later time. However, it's impossible to produce the proper type information until after we know all of the derived classes. A nice problem to be sure, but one that can be fixed by making all modules share a single copy of the SWIG run-time library.<p> -<a name="n5"></a><H3>15.1.3 The SWIG runtime library</H3> +Unfortunately, this problem is inherent in the method by which SWIG makes modules. When we made the "a" module, we had no idea what derived classes might be used at a later time. However, it's impossible to produce the proper type information until after we know all of the derived classes. A nice problem to be sure, but one that can be fixed by making all modules share a single copy of the SWIG run-time library. +</p> + +<H3><a name="Advanced_nn5"></a>29.1.3 The SWIG runtime library</H3> To reduce overhead and to fix type-handling problems, it is possible to share the SWIG run-time functions between multiple modules. -The <a href="#Modules.html">Working with Modules</a> chapter describes this in further detail and how to build the SWIG runtime library. The steps can be summarised as follows: +The <a href="Modules.html#Modules">Working with Modules</a> chapter describes this in further detail and how to build the SWIG runtime library. The steps can be summarised as follows: <ul> <li> Build the SWIG run-time libraries. </li> @@ -113,24 +139,33 @@ The <a href="#Modules.html">Working with Modules</a> chapter describes this in f <li> Build SWIG modules by linking against the appropriate runtime libraries. </li> </ul> -When completed you should now end up with a collection of modules like this:<p> -<center><img src="ch11.3.png"></center><p> -<p> <p> -In this configuration, the runtime library manages all datatypes and other information between modules. This management process is dynamic in nature--when new modules are loaded, they contribute information to the run-time system. In the C++ world, one could incrementally load classes as needed. As this process occurs, type information is updated and base-classes learn about derived classes as needed.<p> +When completed you should now end up with a collection of modules like this: +</p> + +<center><img src="ch11.3.png" alt="Modules 1-N using single runtime"></center> <p> +In this configuration, the runtime library manages all datatypes and other information between modules. This management process is dynamic in nature--when new modules are loaded, they contribute information to the run-time system. In the C++ world, one could incrementally load classes as needed. As this process occurs, type information is updated and base-classes learn about derived classes as needed. +</p> +<p> <b>Compatibility Note:</b> In SWIG-1.3.19 and earlier releases, SWIG built the runtime libraries by default and attempted to install them with the SWIG installation. This had numerous limitations, not least, the version of the target language was tied to what was detected at installation time and would not necessarily be the version the user required. +</p> -<a name="n6"></a><H3>15.1.4 A few dynamic loading gotchas</H3> +<H3><a name="Advanced_nn6"></a>29.1.4 A few dynamic loading gotchas</H3> -When working with dynamic loading, it is critical to check that only one copy of the run-time library is being loaded into the system. When working with <tt>.a</tt> library files, problems can sometimes occur so there are a few approaches to the problem.<p> <p> -1. Rebuild the scripting language executable with the SWIG runtime library attached to it. This is actually, fairly easy to do using SWIG. For example :<p> +When working with dynamic loading, it is critical to check that only one copy of the run-time library is being loaded into the system. When working with <tt>.a</tt> library files, problems can sometimes occur so there are a few approaches to the problem. +</p> + <p> -<blockquote><pre>%module mytclsh +1. Rebuild the scripting language executable with the SWIG runtime library attached to it. This is actually, fairly easy to do using SWIG. For example : +</p> + +<blockquote><pre> +%module mytclsh %{ static void *__embedfunc(void *a) { return a}; @@ -138,31 +173,44 @@ static void *__embedfunc(void *a) { return a}; void *__embedfunc(void *); %include tclsh.i - </pre></blockquote> + <p> -Now, assuming you have built the <a href="Modules.html">runtime library</a> as <tt>swigruntcl</tt>, run SWIG and compile as follows:<p> -<p> +Now, assuming you have built the <a href="Modules.html#Modules">runtime library</a> as <tt>swigruntcl</tt>, run SWIG and compile as follows: +</p> + <blockquote><pre> % <b>swig -c -tcl mytclsh.i</b> % <b>gcc mytclsh_wrap.c -I/usr/local/include -L/usr/local/lib -ltcl -lswigruntcl -ldl -lm \ -o tclsh</b> </pre></blockquote> -This produces a new executable "<tt>tclsh</tt>" that contains a copy of the SWIG runtime library. The weird <tt>__embedfunc()</tt> function is needed to force the functions in the runtime library to be included in the final executable.<p> + <p> -To make new dynamically loadable SWIG modules, simply compile as follows :<p> +This produces a new executable "<tt>tclsh</tt>" that contains a copy of the SWIG runtime library. The weird <tt>__embedfunc()</tt> function is needed to force the functions in the runtime library to be included in the final executable. +</p> + <p> +To make new dynamically loadable SWIG modules, simply compile as follows : +</p> + <blockquote><pre> % <b>swig -c -tcl example.i</b> % <b>gcc -c example_wrap.c -I/usr/local/include</b> % <b>ld -shared example_wrap.o -o example.so</b> </pre></blockquote> + +<p> Linking against the <tt>swigruntcl</tt> library is no longer necessary as all of the functions are now included in the <tt>tclsh</tt> executable and will be resolved when your module is loaded. -However, some operating systems, like Windows, will still require linking with the libraries so that there are no unresolved symbols.<p> +However, some operating systems, like Windows, will still require linking with the libraries so that there are no unresolved symbols. +</p> + <p> -2. Using shared library versions of the runtime library<p> +2. Using shared library versions of the runtime library +</p> + <p> -If supported on your machine, the runtime libraries will be built as shared libraries (for example a <tt>.so</tt>, <tt>.sl</tt>, or .<tt>dll</tt> suffix). To compile using the runtime libraries, your link process should look something like this:<p> +If supported on your machine, the runtime libraries will be built as shared libraries (for example a <tt>.so</tt>, <tt>.sl</tt>, or .<tt>dll</tt> suffix). To compile using the runtime libraries, your link process should look something like this: +</p> <blockquote><pre> % <b>ld -shared example_wrap.o -o libexample.so</b> # Irix @@ -172,33 +220,58 @@ If supported on your machine, the runtime libraries will be built as shared libr /link /LIBPATH:PathToRuntimeLibrary /LIBPATH:c:\Tcl\lib</b> # Windows VC++ </pre></blockquote> +<p> In order for the <tt>libexample.so</tt> library to work, it needs to be placed in a location where the dynamic loader can find it. -Typically this is a system library directory (eg. <tt>/usr/local/lib</tt> or <tt>/usr/lib</tt>).<p> +Typically this is a system library directory (eg. <tt>/usr/local/lib</tt> or <tt>/usr/lib</tt>). +</p> + <p> -When running with the shared libary version, you may get error messages such as the following:<p> +When running with the shared libary version, you may get error messages such as the following: +</p> + +<blockquote><pre> +Unable to locate libexample.so +</pre></blockquote> + <p> -<blockquote><pre>Unable to locate libexample.so</pre></blockquote> This indicates that the loader was unable to find the shared libary at run-time. To find shared libaries, the loader looks through a collection of predetermined paths. If the shared library file is not in any of these directories, it results in an error. -On most machines, you can change the loader search path by changing the path (Windows) or environment variable <tt>LD_LIBRARY_PATH</tt> (Unix), e.g.<p> -<p> -<blockquote><pre>% <b>setenv LD_LIBRARY_PATH .:/home/beazley/packages/lib</b></pre></blockquote> -A somewhat better approach is to link your module with the proper path encoded. This is typically done using the `<tt>-rpath</tt>' or `<tt>-R</tt>' option to your linker on Unix (see the man page). For example:<p> +On most machines, you can change the loader search path by changing the path (Windows) or environment variable <tt>LD_LIBRARY_PATH</tt> (Unix), e.g. +</p> + +<blockquote><pre> +% <b>setenv LD_LIBRARY_PATH .:/home/beazley/packages/lib</b> +</pre></blockquote> + <p> -<blockquote><pre>% <b>ld -shared example_wrap.o example.o -rpath /home/beazley/packages/lib \ +A somewhat better approach is to link your module with the proper path encoded. This is typically done using the `<tt>-rpath</tt>' or `<tt>-R</tt>' option to your linker on Unix (see the man page). For example: +</p> + +<blockquote><pre> +% <b>ld -shared example_wrap.o example.o -rpath /home/beazley/packages/lib \ -L/home/beazley/packages/lib -lswigruntcl.so -o example.so</b> </pre></blockquote> -The <tt>-rpath</tt> option encodes the location of shared libraries into your modules and gets around having to set the <tt>LD_LIBRARY_PATH</tt> variable.<p> + +<p> +The <tt>-rpath</tt> option encodes the location of shared libraries into your modules and gets around having to set the <tt>LD_LIBRARY_PATH</tt> variable. +</p> + <p> -If all else fails, pull up the man pages for your linker and start playing around.<p> -<a name="n7"></a><H2>15.2 Dynamic Loading of C++ modules</H2> +If all else fails, pull up the man pages for your linker and start playing around. +</p> + +<H2><a name="Advanced_nn7"></a>29.2 Dynamic Loading of C++ modules</H2> -Dynamic loading of C++ modules presents a special problem for many systems. This is because C++ modules often need additional supporting code for proper initialization and operation. Static constructors are also a bit of a problem.<p> <p> -While the process of building C++ modules is, by no means, and exact science, here are a few rules of thumb to follow :<p> +Dynamic loading of C++ modules presents a special problem for many systems. This is because C++ modules often need additional supporting code for proper initialization and operation. Static constructors are also a bit of a problem. +</p> + <p> +While the process of building C++ modules is, by no means, and exact science, here are a few rules of thumb to follow : +</p> + <ul> <li>Don't use static constructors if at all possible (not always avoidable). <li>Try linking your module with the C++ compiler using a command like `c++ -shared'. This often solves alot of problems. @@ -206,113 +279,164 @@ While the process of building C++ modules is, by no means, and exact science, he <li>Read the compiler and linker man pages over and over until you have them memorized (this may not help in some cases however). <li>Search articles on Usenet, particularly in <tt>comp.lang.tcl</tt>, <tt>comp.lang.perl</tt>, <tt>comp.lang.python</tt> and <tt>comp.lang.ruby</tt>. Building C++ modules is a common problem. </ul> + <p> -The SWIG distribution contains some additional documentation about C++ modules in the Doc directory as well.<p> -<a name="n8"></a><H2>15.3 Inside the SWIG type-checker</H2> +The SWIG distribution contains some additional documentation about C++ modules in the Doc directory as well. +</p> +<H2><a name="Advanced_nn8"></a>29.3 Inside the SWIG type-checker</H2> -The SWIG runtime type-checker plays a critical role in the correct operation of SWIG modules. It not only checks the validity of pointer types, but also manages C++ inheritance, and performs proper type-casting of pointers when necessary. This section provides some insight into what it does, how it works, and why it is the way it is.<p> -<a name="n9"></a><H3>15.3.1 Type equivalence</H3> +<p> +The SWIG runtime type-checker plays a critical role in the correct operation of SWIG modules. It not only checks the validity of pointer types, but also manages C++ inheritance, and performs proper type-casting of pointers when necessary. This section provides some insight into what it does, how it works, and why it is the way it is. +</p> + +<H3><a name="Advanced_nn9"></a>29.3.1 Type equivalence</H3> -SWIG uses a name-based approach to managing pointer datatypes. For example, if you are using a pointer like "<tt>double *</tt>", the type-checker will look for a particular string representation of that datatype such as "<tt>_double_p</tt>". If no match is found, a type-error is reported.<p> <p> -However, the matching process is complicated by the fact that datatypes may use a variety of different names. For example, the following declarations<p> +SWIG uses a name-based approach to managing pointer datatypes. For example, if you are using a pointer like "<tt>double *</tt>", the type-checker will look for a particular string representation of that datatype such as "<tt>_double_p</tt>". If no match is found, a type-error is reported. +</p> + <p> -<blockquote><pre>typedef double Real; +However, the matching process is complicated by the fact that datatypes may use a variety of different names. For example, the following declarations +</p> + +<blockquote><pre> +typedef double Real; typedef Real * RealPtr; typedef double Float; </pre></blockquote> -define two sets of equivalent types :<p> + <p> -<blockquote><pre>{double, Real, Float} -{RealPtr, Real *} +define two sets of equivalent types : +</p> +<blockquote><pre> +{double, Real, Float} +{RealPtr, Real *} </pre></blockquote> -All of the types in each set are freely interchangable and the type-checker knows about the relationships by managing a table of equivalences such as the following :<p> + +<p> +All of the types in each set are freely interchangable and the type-checker knows about the relationships by managing a table of equivalences such as the following : +</p> + <blockquote><pre> double => { Real, Float } Real => { double, Float } Float => { double, Real } RealPtr => { Real * } Real * => { RealPtr } - </pre></blockquote> + <p> -When you declare a function such as the following :<p> -<p> -<blockquote><pre>void foo(Real *a); +When you declare a function such as the following : +</p> +<blockquote><pre> +void foo(Real *a); </pre></blockquote> -SWIG first checks to see if the argument passed is a "<tt>Real *</tt>". If not, it checks to see if it is any of the other equivalent types (<tt>double *</tt>, <tt>RealPtr</tt>, <tt>Float *</tt>). If so, the value is accepted and no error occurs.<p> + <p> -Derived versions of the various datatypes are also legal. For example, if you had a function like this,<p> +SWIG first checks to see if the argument passed is a "<tt>Real *</tt>". If not, it checks to see if it is any of the other equivalent types (<tt>double *</tt>, <tt>RealPtr</tt>, <tt>Float *</tt>). If so, the value is accepted and no error occurs. +</p> + <p> -<blockquote><pre>void bar(Float ***a); +Derived versions of the various datatypes are also legal. For example, if you had a function like this, +</p> +<blockquote><pre> +void bar(Float ***a); </pre></blockquote> -The type-checker will accept pointers of type <tt>double ***</tt> and <tt>Real ***.</tt> However, the type-checker does not always capture the full-range of possibilities. For example, a datatype of `<tt>RealPtr **</tt>' is equivalent to a `<tt>Float ***</tt>' but would be flagged as a type error. If you encounter this kind of problem, you can manually force SWIG to make an equivalence as follows:<p> + <p> -<blockquote><pre>// Tell the type checker that `Float_ppp' and `RealPtr_pp' are equivalent. +The type-checker will accept pointers of type <tt>double ***</tt> and <tt>Real ***.</tt> However, the type-checker does not always capture the full-range of possibilities. For example, a datatype of `<tt>RealPtr **</tt>' is equivalent to a `<tt>Float ***</tt>' but would be flagged as a type error. If you encounter this kind of problem, you can manually force SWIG to make an equivalence as follows: +</p> + +<blockquote><pre> +// Tell the type checker that `Float_ppp' and `RealPtr_pp' are equivalent. %init %{ SWIG_RegisterMapping("Float_ppp","RealPtr_pp",0); %} </pre></blockquote> -Doing this should hardly ever be necessary (I have never encountered a case where this was necessary), but if all else fails, you can force the run-time type checker into doing what you want.<p> + <p> -Type-equivalence of C++ classes is handled in a similar manner, but is encoded in a manner to support inheritance. For example, consider the following classes hierarchy :<p> +Doing this should hardly ever be necessary (I have never encountered a case where this was necessary), but if all else fails, you can force the run-time type checker into doing what you want. +</p> + <p> -<blockquote><pre>class A { }; +Type-equivalence of C++ classes is handled in a similar manner, but is encoded in a manner to support inheritance. For example, consider the following classes hierarchy : +</p> + +<blockquote><pre> +class A { }; class B : public A { }; class C : public B { }; class D {}; class E : public C, public D {}; - </pre></blockquote> -The type-checker encodes this into the following sets :<p> + <p> -<blockquote><pre>A => { B, C, E } "B isa A, C isa A, E isa A" +The type-checker encodes this into the following sets : +</p> + +<blockquote><pre> +A => { B, C, E } "B isa A, C isa A, E isa A" B => { C, E } "C isa B, E isa B" C => { E } "E isa C" D => { E } "E isa D" E => { } - </pre></blockquote> -The encoding reflects the class hierarchy. For example, any object of type "A" will also accept objects of type B,C, and E because these are all derived from A. However, it is not legal to go the other way. For example, a function operating on a object from class E will not accept an object from class A.<p> -<a name="n10"></a><H3>15.3.2 Type casting</H3> + +<p> +The encoding reflects the class hierarchy. For example, any object of type "A" will also accept objects of type B,C, and E because these are all derived from A. However, it is not legal to go the other way. For example, a function operating on a object from class E will not accept an object from class A. +</p> + +<H3><a name="Advanced_nn10"></a>29.3.2 Type casting</H3> -When working with C++ classes, SWIG needs to perform proper typecasting between derived and base classes. This is particularly important when working with multiple inheritance. To do this, conversion functions are created such as the following :<p> <p> -<blockquote><pre>void *EtoA(void *ptr) { +When working with C++ classes, SWIG needs to perform proper typecasting between derived and base classes. This is particularly important when working with multiple inheritance. To do this, conversion functions are created such as the following : +</p> + +<blockquote><pre> +void *EtoA(void *ptr) { E *in = (E *) ptr; A *out = (A *) in; // Cast using C++ return (void *) out; } </pre></blockquote> -All pointers are internally represented as void *, but conversion functions are always invoked when pointer values are converted between base and derived classes in a C++ class hierarchy.<p> -<a name="n11"></a><H3>15.3.3 Why a name based approach?</H3> +<p> +All pointers are internally represented as void *, but conversion functions are always invoked when pointer values are converted between base and derived classes in a C++ class hierarchy. +</p> + +<H3><a name="Advanced_nn11"></a>29.3.3 Why a name based approach?</H3> -SWIG uses a name-based approach to type-checking for a number of reasons :<p> <p> +SWIG uses a name-based approach to type-checking for a number of reasons : +</p> + <ul> <li>One of SWIG's main uses is code development and debugging. In this environment, the type name of an object turns out to be a useful piece of information in tracking down problems. <li>In languages like Perl, the name of a datatype is used to determine things like packages and classes. By using datatype names we get a natural mapping between C and Perl. <li>I believe using the original names of datatypes is more intuitive than munging them into something completely different. </ul> + <p> -An alternative to a name based scheme would be to generate type-signatures based on the structure of a datatype. Such a scheme would result in perfect type-checking, but I think it would also result in a very confusing scripting language module. For this reason, I see SWIG sticking with the name-based approach--at least for the foreseeable future. <p> -<a name="n12"></a><H3>15.3.4 Performance of the type-checker</H3> +An alternative to a name based scheme would be to generate type-signatures based on the structure of a datatype. Such a scheme would result in perfect type-checking, but I think it would also result in a very confusing scripting language module. For this reason, I see SWIG sticking with the name-based approach--at least for the foreseeable future. +</p> + +<H3><a name="Advanced_nn12"></a>29.3.4 Performance of the type-checker</H3> -The type-checker performs the following steps when matching a datatype :<p> <p> +The type-checker performs the following steps when matching a datatype : +</p> <dl> <dt>1. Check a pointer against the type supplied in the original C declaration. If there is a perfect match, we're done. @@ -321,14 +445,16 @@ The type-checker performs the following steps when matching a datatype :<p> <dt>4. If not found, report an error. </dl> + <p> -Most well-structured C codes will find an exact match on the first attempt, providing the best possible performance. For C++ codes, it is quite common to be passing various objects of a common base-class around between functions. When base-class functions are invoked, it almost always results in a miscompare (because the type-checker is looking for the base-type). In this case, we drop down to a small cache of recently used datatypes. If we've used a pointer of the same type recently, it will be in the cache and we can match against it. For tight loops, this results in about 10-15% overhead over finding a match on the first try. Finally, as a last resort, we need to search the internal pointer tables for a match. This involves a combination of hash table lookup and linear search. If a match is found, it is placed into the cache and the result returned. If not, we finally report a type-mismatch.<p> -<p> -As a rule of thumb, C++ programs require somewhat more processing than C programs, but this seems to be avoidable. Also, keep in mind that performance penalties in the type-checker don't necessarily translate into big penalties in the overall application. Performance is most greatly affected by the efficiency of the target scripting language and the types of operations your C code is performing.<p> -<p> +Most well-structured C codes will find an exact match on the first attempt, providing the best possible performance. For C++ codes, it is quite common to be passing various objects of a common base-class around between functions. When base-class functions are invoked, it almost always results in a miscompare (because the type-checker is looking for the base-type). In this case, we drop down to a small cache of recently used datatypes. If we've used a pointer of the same type recently, it will be in the cache and we can match against it. For tight loops, this results in about 10-15% overhead over finding a match on the first try. Finally, as a last resort, we need to search the internal pointer tables for a match. This involves a combination of hash table lookup and linear search. If a match is found, it is placed into the cache and the result returned. If not, we finally report a type-mismatch. +</p> + <p> +As a rule of thumb, C++ programs require somewhat more processing than C programs, but this seems to be avoidable. Also, keep in mind that performance penalties in the type-checker don't necessarily translate into big penalties in the overall application. Performance is most greatly affected by the efficiency of the target scripting language and the types of operations your C code is performing. +</p> -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : July 9, 2004</address> </body> diff --git a/Doc/Manual/Arguments.html b/Doc/Manual/Arguments.html index b1b5598f5..c70cda65a 100644 --- a/Doc/Manual/Arguments.html +++ b/Doc/Manual/Arguments.html @@ -5,22 +5,22 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>7 Argument Handling</H1> +<H1><a name="Arguments"></a>9 Argument Handling</H1> <!-- INDEX --> <ul> -<li><a href="#n2">The typemaps.i library</a> +<li><a href="#Arguments_nn2">The typemaps.i library</a> <ul> -<li><a href="#n3">Introduction</a> -<li><a href="#n4">Input parameters</a> -<li><a href="#n5">Output parameters</a> -<li><a href="#n6">Input/Output parameters</a> -<li><a href="#n7">Using different names</a> +<li><a href="#Arguments_nn3">Introduction</a> +<li><a href="#Arguments_nn4">Input parameters</a> +<li><a href="#Arguments_nn5">Output parameters</a> +<li><a href="#Arguments_nn6">Input/Output parameters</a> +<li><a href="#Arguments_nn7">Using different names</a> </ul> -<li><a href="#n8">Applying constraints to input values</a> +<li><a href="#Arguments_nn8">Applying constraints to input values</a> <ul> -<li><a href="#n9">Simple constraint example</a> -<li><a href="#n10">Constraint methods</a> -<li><a href="#n11">Applying constraints to new datatypes</a> +<li><a href="#Arguments_nn9">Simple constraint example</a> +<li><a href="#Arguments_nn10">Constraint methods</a> +<li><a href="#Arguments_nn11">Applying constraints to new datatypes</a> </ul> </ul> <!-- INDEX --> @@ -39,20 +39,21 @@ However, in certain applications it is desirable to change SWIG's handling of a specific datatype. For example, you might want to return multiple values through the arguments of a function. This chapter describes some of the techniques for doing this. +</p> -<a name="n2"></a><H2>7.1 The typemaps.i library</H2> +<H2><a name="Arguments_nn2"></a>9.1 The typemaps.i library</H2> This section describes the <tt>typemaps.i</tt> library file--commonly used to change certain properties of argument conversion. -<a name="n3"></a><H3>7.1.1 Introduction</H3> +<H3><a name="Arguments_nn3"></a>9.1.1 Introduction</H3> Suppose you had a C function like this: -<p> -<blockquote><pre>void add(double a, double b, double *result) { +<blockquote><pre> +void add(double a, double b, double *result) { *result = a + b; } </pre></blockquote> @@ -62,13 +63,15 @@ From reading the source code, it is clear that the function is storing a value in the <tt>double *result</tt> parameter. However, since SWIG does not examine function bodies, it has no way to know that this is the underlying behavior. +</p> <p> One way to deal with this is to use the <tt>typemaps.i</tt> library file and write interface code like this: +</p> -<p> -<blockquote><pre>// Simple example using typemaps +<blockquote><pre> +// Simple example using typemaps %module example %include "typemaps.i" @@ -76,22 +79,23 @@ One way to deal with this is to use the extern void add(double a, double b, double *result); </pre></blockquote> +<p> The <tt>%apply</tt> directive tells SWIG that you are going to apply a special type handling rule to a type. The "<tt>double *OUTPUT</tt>" specification is the name of a rule that defines how to return an output value from an argument of type <tt>double *</tt>. This rule gets applied to all of the datatypes -listed in curly braces-- in this case "<tt>double *result</tt>".<p> +listed in curly braces-- in this case "<tt>double *result</tt>".</p> <p> When the resulting module is created, you can now use the function like this (shown for Python): +</p> -<p> <blockquote><pre> ->>> a = add(3,4) ->>> print a +>>> a = add(3,4) +>>> print a 7 ->>> +>>> </pre></blockquote> In this case, you can see how the output value normally returned in @@ -103,8 +107,8 @@ since it is no longer necessary to manufacture a special <tt>double <p> Once a typemap has been applied to a type, it stays in effect for all future occurrences of the type and name. For example, you could write the following: +</p> -<p> <blockquote><pre> %module example %include "typemaps.i" @@ -122,6 +126,7 @@ In this case, the <tt>double *OUTPUT</tt> rule is applied to all of the function <p> Typemap transformations can even be extended to multiple return values. For example, consider this code: +</p> <blockquote> <pre> @@ -136,12 +141,12 @@ void getwinsize(int winid, int *width, int *height); In this case, the function returns multiple values, allowing it to be used like this: <blockquote><pre> ->>> w,h = genwinsize(wid) ->>> print w +>>> w,h = genwinsize(wid) +>>> print w 400 ->>> print h +>>> print h 300 ->>> +>>> </pre> </blockquote> @@ -149,8 +154,10 @@ In this case, the function returns multiple values, allowing it to be used like It should also be noted that although the <tt>%apply</tt> directive is used to associate typemap rules to datatypes, you can also use the rule names directly in arguments. For example, you could write this: +</p> -<blockquote><pre>// Simple example using typemaps +<blockquote><pre> +// Simple example using typemaps %module example %include "typemaps.i" @@ -166,12 +173,13 @@ else. To clear a typemap, the <tt>%clear</tt> directive should be used. For e </pre> </blockquote> -<a name="n4"></a><H3>7.1.2 Input parameters</H3> +<H3><a name="Arguments_nn4"></a>9.1.2 Input parameters</H3> <p> The following typemaps instruct SWIG that a pointer really only holds a single input value: +</p> <blockquote><pre> int *INPUT @@ -195,29 +203,33 @@ double add(double *a, double *b) { Now, consider this SWIG interface: -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example %include "typemaps.i" ... extern double add(double *INPUT, double *INPUT); </pre></blockquote> -When the function is used in the scripting language interpreter, it will work like this: <p> +When the function is used in the scripting language interpreter, it will work like this: +</p> + <blockquote><pre> result = add(3,4) </pre></blockquote> -<a name="n5"></a><H3>7.1.3 Output parameters</H3> +<H3><a name="Arguments_nn5"></a>9.1.3 Output parameters</H3> +<p> The following typemap rules tell SWIG that pointer is the output value of a function. When used, you do not need to supply the argument when calling the function. Instead, one or more output values are returned. +</p> -<p> -<blockquote><pre>int *OUTPUT +<blockquote><pre> +int *OUTPUT short *OUTPUT long *OUTPUT unsigned int *OUTPUT @@ -227,18 +239,20 @@ double *OUTPUT float *OUTPUT </pre></blockquote> -These methods can be used as shown in an earlier example. For example, if you have this C function :<p> <p> -<blockquote><pre>void add(double a, double b, double *c) { +These methods can be used as shown in an earlier example. For example, if you have this C function :</p> + +<blockquote><pre> +void add(double a, double b, double *c) { *c = a+b; } </pre></blockquote> <p> -A SWIG interface file might look like this :<p> +A SWIG interface file might look like this :</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example %include "typemaps.i" ... extern void add(double a, double b, double *OUTPUT); @@ -252,6 +266,7 @@ the output rules to more than one argument (as shown previously). <p> If the function also returns a value, it is returned along with the argument. For example, if you had this: +</p> <blockquote><pre> extern int foo(double a, double b, double *OUTPUT); @@ -265,11 +280,12 @@ iresult, dresult = foo(3.5, 2) </pre> </blockquote> -<a name="n6"></a><H3>7.1.4 Input/Output parameters</H3> +<H3><a name="Arguments_nn6"></a>9.1.4 Input/Output parameters</H3> +<p> When a pointer serves as both an input and output value you can use -the following typemaps :<p> +the following typemaps :</p> <blockquote><pre> int *INOUT @@ -283,30 +299,33 @@ float *INOUT </pre></blockquote> -A C function that uses this might be something like this:<p> - <p> -<blockquote><pre>void negate(double *x) { +A C function that uses this might be something like this:</p> + +<blockquote><pre> +void negate(double *x) { *x = -(*x); } </pre></blockquote> +<p> To make x function as both and input and output value, declare the -function like this in an interface file :<p> +function like this in an interface file :</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example %include typemaps.i ... extern void negate(double *INOUT); </pre></blockquote> -Now within a script, you can simply call the function normally :<p> - <p> -<blockquote><pre>a = negate(3); # a = -3 after calling this +Now within a script, you can simply call the function normally :</p> + +<blockquote><pre> +a = negate(3); # a = -3 after calling this </pre></blockquote> One subtle point of the <tt>INOUT</tt> rule is that many scripting languages @@ -319,15 +338,18 @@ rather than directly overwriting the value of the original input object. <p> <b>Compatibility note :</b> The <tt>INOUT</tt> rule used to be known as <tt>BOTH</tt> in earlier versions of SWIG. Backwards compatibility is preserved, but deprecated. +</p> -<a name="n7"></a><H3>7.1.5 Using different names</H3> +<H3><a name="Arguments_nn7"></a>9.1.5 Using different names</H3> +<p> As previously shown, the <tt>%apply</tt> directive can be used to apply the <tt>INPUT</tt>, <tt>OUTPUT</tt>, and <tt>INOUT</tt> typemaps to different argument names. For example: +</p> -<p> -<blockquote><pre>// Make double *result an output value +<blockquote><pre> +// Make double *result an output value %apply double *OUTPUT { double *result }; // Make Int32 *in an input value @@ -340,15 +362,15 @@ As previously shown, the <tt>%apply</tt> directive can be used to apply the <tt> To clear a rule, the <tt>%clear</tt> directive is used: -<p> -<blockquote><pre>%clear double *result; +<blockquote><pre> +%clear double *result; %clear Int32 *in, long *x; </pre></blockquote> Typemap declarations are lexically scoped so a typemap takes effect from the point of definition to the end of the file or a matching <tt>%clear</tt> declaration. -<a name="n8"></a><H2>7.2 Applying constraints to input values</H2> +<H2><a name="Arguments_nn8"></a>9.2 Applying constraints to input values</H2> In addition to changing the handling of various input values, it is @@ -356,14 +378,15 @@ also possible to use typemaps to apply constraints. For example, maybe you want 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. -<a name="n9"></a><H3>7.2.1 Simple constraint example</H3> +<H3><a name="Arguments_nn9"></a>9.2.1 Simple constraint example</H3> -The constraints library is best illustrated by the following interface -file :<p> <p> +The constraints library is best illustrated by the following interface +file :</p> -<blockquote><pre>// Interface file with constraints +<blockquote><pre> +// Interface file with constraints %module example %include "constraints.i" @@ -375,15 +398,17 @@ void free(void *NONNULL); // Non-NULL pointers only </pre></blockquote> +<p> The behavior of this file is exactly as you would expect. If any of 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> +values, prevent mysterious program crashes and so on.</p> -<a name="n10"></a><H3>7.2.2 Constraint methods</H3> +<H3><a name="Arguments_nn10"></a>9.2.2 Constraint methods</H3> -The following constraints are currently available<p> +<p> +The following constraints are currently available</p> <blockquote><pre> POSITIVE Any number > 0 (not zero) @@ -395,15 +420,16 @@ NONNULL Non-NULL pointer (pointers only). </pre></blockquote> -<a name="n11"></a><H3>7.2.3 Applying constraints to new datatypes</H3> +<H3><a name="Arguments_nn11"></a>9.2.3 Applying constraints to new datatypes</H3> +<p> The constraints library only supports the primitive C datatypes, but it is easy to apply it to new datatypes using <tt>%apply</tt>. For -example :<p> -<p> +example :</p> -<blockquote><pre>// Apply a constraint to a Real variable +<blockquote><pre> +// Apply a constraint to a Real variable %apply Number POSITIVE { Real in }; // Apply a constraint to a pointer type @@ -411,17 +437,17 @@ example :<p> </pre></blockquote> +<p> The special types of "Number" and "Pointer" can be applied to any numeric and pointer variable type respectively. To later remove a -constraint, the <tt>%clear</tt> directive can be used :<p> +constraint, the <tt>%clear</tt> directive can be used :</p> -<p> -<blockquote><pre>%clear Real in; +<blockquote><pre> +%clear Real in; %clear Vector *; </pre></blockquote> -<p><hr> - +<hr> <address>SWIG 1.3 - Last Modified : October 13, 2002</address> </body> </html> diff --git a/Doc/Manual/CSharp.html b/Doc/Manual/CSharp.html index 67b3beed8..bac6f7417 100644 --- a/Doc/Manual/CSharp.html +++ b/Doc/Manual/CSharp.html @@ -4,12 +4,12 @@ <title>SWIG and C#</title> </head> <body bgcolor="#FFFFFF"> -<a name="n1"></a><H1>15 SWIG and C#</H1> +<H1><a name="CSharp"></a>16 SWIG and C#</H1> <!-- INDEX --> -<ul> -</ul> <!-- INDEX --> + + The purpose of the C# module is to offer an automated way of accessing existing C/C++ code from .NET languages. The wrapper code implementation uses the Platform Invoke (PINVOKE) interface to access natively compiled C/C++ code. The PINVOKE interface has been chosen over Microsoft's Managed C++ interface as it is portable to both Microsoft Windows and non-Microsoft platforms. @@ -18,7 +18,7 @@ PINVOKE is part of the ECMA/ISO C# specification. <p> The C# module is one of the more recently added language modules to SWIG and consequently is missing some functionality available in some other SWIG modules. The C# module is very similar to the Java module, so until some documentation has been written, -please use the <a href="Java.html">Java documentation</a> as a guide to using SWIG with C#. +please use the <a href="Java.html#Java">Java documentation</a> as a guide to using SWIG with C#. The rest of this chapter should be read in conjunction with the Java documentation as it lists the main differences. <p> @@ -52,7 +52,7 @@ There is no implementation for type unsafe enums - not deemed necessary. <li> The default enum wrapping approach is proper C# enums, not typesafe enums. -<br/> +<br> Note that %csconst(0) will be ignored when wrapping C/C++ enums with proper C# enums. This is because C# enum items must be initialised from a compile time constant. If an enum item has an initialiser and the initialiser doesn't compile as C# code, @@ -70,20 +70,20 @@ Likewise there is no need for an equivalent to <tt>%javaexception</tt>. Typemap equivalent names: <blockquote><pre> -jni -> ctype -jtype -> imtype -jstype -> cstype -javain -> csin -javaout -> csout -javainterfaces -> csinterfaces and csinterfaces_derived -javabase -> csbase -javaclassmodifiers -> csclassmodifiers -javacode -> cscode -javaimports -> csimports -javabody -> csbody -javafinalize -> csfinalize -javadestruct -> csdestruct -javadestruct_derived -> csdestruct_derived +jni -> ctype +jtype -> imtype +jstype -> cstype +javain -> csin +javaout -> csout +javainterfaces -> csinterfaces and csinterfaces_derived +javabase -> csbase +javaclassmodifiers -> csclassmodifiers +javacode -> cscode +javaimports -> csimports +javabody -> csbody +javafinalize -> csfinalize +javadestruct -> csdestruct +javadestruct_derived -> csdestruct_derived </pre></blockquote> </li> @@ -101,30 +101,30 @@ csvarout C# code property get typemap <li> Feature equivalent names: <blockquote><pre> -%javaconst -> %csconst -%javaconstvalue -> %csconstvalue -%javamethodmodifiers -> %csmethodmodifiers +%javaconst -> %csconst +%javaconstvalue -> %csconstvalue +%javamethodmodifiers -> %csmethodmodifiers </pre></blockquote> </li> <li> Pragma equivalent names: <blockquote><pre> -%pragma(java) -> %pragma(csharp) -jniclassbase -> imclassbase -jniclassclassmodifiers -> imclassclassmodifiers -jniclasscode -> imclasscode -jniclassimports -> imclassimports -jniclassinterfaces -> imclassinterfaces +%pragma(java) -> %pragma(csharp) +jniclassbase -> imclassbase +jniclassclassmodifiers -> imclassclassmodifiers +jniclasscode -> imclasscode +jniclassimports -> imclassimports +jniclassinterfaces -> imclassinterfaces </pre></blockquote> </li> <li> Special variable equivalent names: <blockquote><pre> -$javaclassname -> $csclassname -$javainput -> $csinput -$jnicall -> $imcall +$javaclassname -> $csclassname +$javainput -> $csinput +$jnicall -> $imcall </pre></blockquote> </li> diff --git a/Doc/Manual/Chicken.html b/Doc/Manual/Chicken.html index 042a44fca..e927b8168 100644 --- a/Doc/Manual/Chicken.html +++ b/Doc/Manual/Chicken.html @@ -7,31 +7,31 @@ <body bgcolor="#ffffff"> -<a name="n1"></a><H1>25 SWIG and Chicken</H1> +<H1><a name="Chicken"></a>17 SWIG and Chicken</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Preliminaries</a> +<li><a href="#Chicken_nn2">Preliminaries</a> <ul> -<li><a href="#n3">Running SWIG in C mode</a> -<li><a href="#n4">Running SWIG in C++ mode</a> +<li><a href="#Chicken_nn3">Running SWIG in C mode</a> +<li><a href="#Chicken_nn4">Running SWIG in C++ mode</a> </ul> -<li><a href="#n5">Code Generation</a> +<li><a href="#Chicken_nn5">Code Generation</a> <ul> -<li><a href="#n6">Naming Conventions</a> -<li><a href="#n7">Modules and Prefixes</a> -<li><a href="#n8">Constants and Variables</a> -<li><a href="#n9">Functions</a> +<li><a href="#Chicken_nn6">Naming Conventions</a> +<li><a href="#Chicken_nn7">Modules and Prefixes</a> +<li><a href="#Chicken_nn8">Constants and Variables</a> +<li><a href="#Chicken_nn9">Functions</a> </ul> -<li><a href="#n10">TinyCLOS</a> -<li><a href="#n11">Compilation</a> -<li><a href="#n12">Linkage</a> +<li><a href="#Chicken_nn10">TinyCLOS</a> +<li><a href="#Chicken_nn11">Compilation</a> +<li><a href="#Chicken_nn12">Linkage</a> <ul> -<li><a href="#n13">Shared library</a> -<li><a href="#n14">Static binary</a> +<li><a href="#Chicken_nn13">Shared library</a> +<li><a href="#Chicken_nn14">Static binary</a> </ul> -<li><a href="#n15">Typemaps</a> -<li><a href="#n16">Pointers</a> -<li><a href="#n17">Unsupported features</a> +<li><a href="#Chicken_nn15">Typemaps</a> +<li><a href="#Chicken_nn16">Pointers</a> +<li><a href="#Chicken_nn17">Unsupported features</a> </ul> <!-- INDEX --> @@ -61,7 +61,7 @@ </p> -<a name="n2"></a><H2>25.1 Preliminaries</H2> +<H2><a name="Chicken_nn2"></a>17.1 Preliminaries</H2> <p> @@ -82,61 +82,77 @@ </p> -<a name="n3"></a><H3>25.1.1 Running SWIG in C mode</H3> +<H3><a name="Chicken_nn3"></a>17.1.1 Running SWIG in C mode</H3> - <p> + <p> To run SWIG CHICKEN in C mode, use the -chicken option. + </p> + <blockquote> <pre>% swig -chicken example.i</pre> </blockquote> + + <p> To allow the wrapper to take advantage of future CHICKEN code generation improvements, part of the wrapper is direct CHICKEN function calls (<tt>example_wrap.c</tt>) and part is CHICKEN Scheme (<tt>example.scm</tt>). The basic Scheme code must be compiled to C using your system's CHICKEN compiler. + </p> + <blockquote> <pre>% chicken example.scm -output-file oexample.c</pre> </blockquote> + + <p> So for the C mode of SWIG CHICKEN, <tt>example_wrap.c</tt> and <tt>oexample.c</tt> are the files that must be compiled to object files and linked into your project. - </p> + </p> -<a name="n4"></a><H3>25.1.2 Running SWIG in C++ mode</H3> +<H3><a name="Chicken_nn4"></a>17.1.2 Running SWIG in C++ mode</H3> - <p> + <p> To run SWIG CHICKEN in C++ mode, use the -chicken -c++ option. + </p> + <blockquote> <pre>% swig -chicken -c++ example.i</pre> </blockquote> + + <p> This will generate <tt>example_wrap.cxx</tt>, <tt>example.scm</tt>, <tt>example-generic.scm</tt> and <tt>example-clos.scm</tt>. The basic Scheme code must be compiled to C using your system's CHICKEN compiler. + </p> + <blockquote> <pre>% chicken example.scm -output-file oexample.c</pre> </blockquote> + + <p> So for the C++ mode of SWIG CHICKEN, <tt>example_wrap.cxx</tt> and <tt>oexample.c</tt> are the files that must be compiled to object files and linked into your project. - </p> + </p> -<a name="n5"></a><H2>25.2 Code Generation</H2> +<H2><a name="Chicken_nn5"></a>17.2 Code Generation</H2> -<a name="n6"></a><H3>25.2.1 Naming Conventions</H3> +<H3><a name="Chicken_nn6"></a>17.2.1 Naming Conventions</H3> <p> Given a C variable, function or constant declaration named <tt>Foo_Bar_to_Foo_Baz</tt>, the declaration will be available in CHICKEN as an identifier ending with - <tt>Foo-Bar->Foo-Baz</tt>. That is, an underscore is converted + <tt>Foo-Bar->Foo-Baz</tt>. That is, an underscore is converted to a dash and '_to_' is converted to an arrow. <br> @@ -156,7 +172,7 @@ <tt>%rename</tt> SWIG directive in the SWIG interface file. </p> -<a name="n7"></a><H3>25.2.2 Modules and Prefixes</H3> +<H3><a name="Chicken_nn7"></a>17.2.2 Modules and Prefixes</H3> <p> @@ -192,7 +208,7 @@ </p> -<a name="n8"></a><H3>25.2.3 Constants and Variables</H3> +<H3><a name="Chicken_nn8"></a>17.2.3 Constants and Variables</H3> <p> @@ -219,7 +235,7 @@ use <tt>(my-variable)</tt>. </p> -<a name="n9"></a><H3>25.2.4 Functions</H3> +<H3><a name="Chicken_nn9"></a>17.2.4 Functions</H3> <p> @@ -238,11 +254,12 @@ parameters). </p> -<a name="n10"></a><H2>25.3 TinyCLOS</H2> +<H2><a name="Chicken_nn10"></a>17.3 TinyCLOS</H2> - <p> + <p> The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as: + </p> <blockquote> Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a metaobject protocol. The implementation is even simpler than @@ -250,12 +267,15 @@ weighing in at around 850 lines of code, including (some) comments and documentation. </blockquote> + + <p> Almost all good Scheme books describe how to use metaobjects and generic procedures to implement an object-oriented Scheme system. Please consult a Scheme book if you are unfamiliar with the concept. + </p> - <br> + <p> CHICKEN has a modified version of TinyCLOS, which SWIG CHICKEN uses in C++ mode. SWIG CHICKEN generates a @@ -265,8 +285,9 @@ program needs, and <strong>then</strong> <tt>(include "xxx-clos")</tt> all the metaobject (class) macros your program needs. + </p> - <br> + <p> SWIG CHICKEN will call the destructor for all TinyCLOS objects that are garbage-collected by CHICKEN. It also allows access to @@ -274,9 +295,9 @@ of any TinyCLOS parameters. It is best to learn the TinyCLOS system by running the <tt>Examples/chicken/class/</tt> example. - </p> + </p> -<a name="n11"></a><H2>25.4 Compilation</H2> +<H2><a name="Chicken_nn11"></a>17.4 Compilation</H2> <p> @@ -290,7 +311,7 @@ much simpler <tt>csc</tt> or <tt>csc.bat</tt>. </p> -<a name="n12"></a><H2>25.5 Linkage</H2> +<H2><a name="Chicken_nn12"></a>17.5 Linkage</H2> <p> @@ -304,7 +325,7 @@ loadable module. </p> -<a name="n13"></a><H3>25.5.1 Shared library</H3> +<H3><a name="Chicken_nn13"></a>17.5.1 Shared library</H3> <p> @@ -313,42 +334,47 @@ in example.i and the C functions being wrapped are in example_impl.c. </p> - <pre><blockquote> + <blockquote> + <pre> $ swig -chicken example.i $ csc -svk example.scm example_impl.c example_wrap.c $ csi example.so test_script.scm - </blockquote></pre> + </pre> + </blockquote> <p> You must be careful not to name the example_impl.c file example.c because when compiling example.scm, csc compiles that into example.c! </p> -<a name="n14"></a><H3>25.5.2 Static binary</H3> +<H3><a name="Chicken_nn14"></a>17.5.2 Static binary</H3> <p>Again, we can easily use csc to build a binary.</p> - <pre><blockquote> + <blockquote> + <pre> $ swig -chicken example.i $ csc -vk example.scm example_impl.c example_wrap.c test_script.scm -o example $ ./example - </blockquote></pre> + </pre> + </blockquote> -<a name="n15"></a><H2>25.6 Typemaps</H2> +<H2><a name="Chicken_nn15"></a>17.6 Typemaps</H2> <p> The Chicken module handles all types via typemaps. This information is read from <code>Lib/chicken/typemaps.i</code> and <code>Lib/chicken/chicken.swg</code>. + </p> - <br> - + <p> Two Chicken-specific typemaps are supported: <code>clos_in</code> and <code>clos_out</code>. They are for converting TinyCLOS to and from low-level CHICKEN SWIG. Here is a quick example: + </p> <blockquote> <pre> @@ -365,7 +391,7 @@ <blockquote> <pre> -/* TinyCLOS <--> Low-level CHICKEN */ +/* TinyCLOS <--> Low-level CHICKEN */ %typemap("clos_in") SIMPLE_CLOS_OBJECT * "(slot-ref $input (quote this))" %typemap("clos_out") SIMPLE_CLOS_OBJECT * "(make $class (quote this) $1)" @@ -457,6 +483,7 @@ </pre> </blockquote> + <p> After SWIG processes <code>vtkObject.h</code> (from the <tt>%include "vtkObject.h"</tt> line), SWIG will have the complete definition of the <code>vtkObject</code> class because @@ -475,7 +502,7 @@ </p> -<a name="n16"></a><H2>25.7 Pointers</H2> +<H2><a name="Chicken_nn16"></a>17.7 Pointers</H2> <p> @@ -508,7 +535,7 @@ type. </p> -<a name="n17"></a><H2>25.8 Unsupported features</H2> +<H2><a name="Chicken_nn17"></a>17.8 Unsupported features</H2> <ul> diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index b12bc85b8..c05c5dd53 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -8,1095 +8,1125 @@ <p> -<h3><a href="Preface.html">0 Preface</a></h3> +<h3><a href="Preface.html#Preface">1 Preface</a></h3> <!-- INDEX --> <ul> -<li><a href="Preface.html#n2">Introduction</a> -<li><a href="Preface.html#n3">Special Introduction for Version 1.3</a> -<li><a href="Preface.html#n4">SWIG Versions</a> -<li><a href="Preface.html#n5">SWIG resources</a> -<li><a href="Preface.html#n6">Prerequisites</a> -<li><a href="Preface.html#n7">Organization of this manual</a> -<li><a href="Preface.html#n8">How to avoid reading the manual</a> -<li><a href="Preface.html#n9">Backwards Compatibility</a> -<li><a href="Preface.html#n10">Credits</a> -<li><a href="Preface.html#n11">Bug reports</a> +<li><a href="Preface.html#Preface_nn2">Introduction</a> +<li><a href="Preface.html#Preface_nn3">Special Introduction for Version 1.3</a> +<li><a href="Preface.html#Preface_nn4">SWIG Versions</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_nn10">Credits</a> +<li><a href="Preface.html#Preface_nn11">Bug reports</a> </ul> <!-- INDEX --> -<h3><a href="Introduction.html">1 Introduction</a></h3> +<h3><a href="Introduction.html#Introduction">2 Introduction</a></h3> <!-- INDEX --> <ul> -<li><a href="Introduction.html#n2">What is SWIG?</a> -<li><a href="Introduction.html#n3">Why use SWIG?</a> -<li><a href="Introduction.html#n4">A SWIG example</a> +<li><a href="Introduction.html#Introduction_nn2">What is SWIG?</a> +<li><a href="Introduction.html#Introduction_nn3">Why use SWIG?</a> +<li><a href="Introduction.html#Introduction_nn4">A SWIG example</a> <ul> -<li><a href="Introduction.html#n5">SWIG interface file</a> -<li><a href="Introduction.html#n6">The swig command</a> -<li><a href="Introduction.html#n7">Building a Perl5 module</a> -<li><a href="Introduction.html#n8">Building a Python module</a> -<li><a href="Introduction.html#n9">Shortcuts</a> +<li><a href="Introduction.html#Introduction_nn5">SWIG interface file</a> +<li><a href="Introduction.html#Introduction_nn6">The swig command</a> +<li><a href="Introduction.html#Introduction_nn7">Building a Perl5 module</a> +<li><a href="Introduction.html#Introduction_nn8">Building a Python module</a> +<li><a href="Introduction.html#Introduction_nn9">Shortcuts</a> </ul> -<li><a href="Introduction.html#n10">Supported C/C++ language features</a> -<li><a href="Introduction.html#n11">Non-intrusive interface building</a> -<li><a href="Introduction.html#n12">Hands off code generation</a> -<li><a href="Introduction.html#n13">SWIG and freedom</a> +<li><a href="Introduction.html#Introduction_nn10">Supported C/C++ language features</a> +<li><a href="Introduction.html#Introduction_nn11">Non-intrusive interface building</a> +<li><a href="Introduction.html#Introduction_nn12">Hands off code generation</a> +<li><a href="Introduction.html#Introduction_nn13">SWIG and freedom</a> </ul> <!-- INDEX --> -<h3><a href="Windows.html">2 Getting started on Windows </a></h3> +<h3><a href="Windows.html#Windows">3 Getting started on Windows </a></h3> <!-- INDEX --> <ul> -<li><a href="Windows.html#n2">Installation on Windows</a> +<li><a href="Windows.html#Windows_nn2">Installation on Windows</a> <ul> -<li><a href="Windows.html#n3">Windows Executable</a> +<li><a href="Windows.html#Windows_nn3">Windows Executable</a> </ul> -<li><a href="Windows.html#n4">SWIG Windows Examples</a> +<li><a href="Windows.html#examples">SWIG Windows Examples</a> <ul> -<li><a href="Windows.html#n5">Instructions for using the Examples with Visual Studio</a> +<li><a href="Windows.html#Windows_nn5">Instructions for using the Examples with Visual Studio</a> <ul> -<li><a href="Windows.html#n6">Python</a> -<li><a href="Windows.html#n7">TCL</a> -<li><a href="Windows.html#n8">Perl</a> -<li><a href="Windows.html#n9">Java</a> -<li><a href="Windows.html#n10">Ruby</a> -<li><a href="Windows.html#n11">C#</a> +<li><a href="Windows.html#Windows_nn6">Python</a> +<li><a href="Windows.html#Windows_nn7">TCL</a> +<li><a href="Windows.html#Windows_nn8">Perl</a> +<li><a href="Windows.html#Windows_nn9">Java</a> +<li><a href="Windows.html#Windows_nn10">Ruby</a> +<li><a href="Windows.html#Windows_nn11">C#</a> </ul> -<li><a href="Windows.html#n12">Instructions for using the Examples with other compilers</a> +<li><a href="Windows.html#Windows_nn12">Instructions for using the Examples with other compilers</a> </ul> -<li><a href="Windows.html#n13">SWIG on Cygwin and MinGW</a> +<li><a href="Windows.html#Windows_nn13">SWIG on Cygwin and MinGW</a> <ul> -<li><a href="Windows.html#n14">Building swig.exe on Windows</a> +<li><a href="Windows.html#swig_exe">Building swig.exe on Windows</a> <ul> -<li><a href="Windows.html#n15">Building swig.exe using MinGW and MSYS</a> -<li><a href="Windows.html#n16">Building swig.exe using Cygwin</a> -<li><a href="Windows.html#n17">Building swig.exe alternatives</a> +<li><a href="Windows.html#Windows_nn15">Building swig.exe using MinGW and MSYS</a> +<li><a href="Windows.html#Windows_nn16">Building swig.exe using Cygwin</a> +<li><a href="Windows.html#Windows_nn17">Building swig.exe alternatives</a> </ul> -<li><a href="Windows.html#n18">Running the examples on Windows using Cygwin</a> +<li><a href="Windows.html#examples_cygwin">Running the examples on Windows using Cygwin</a> </ul> </ul> <!-- INDEX --> -<h3><a href="Scripting.html">3 Scripting Languages</a></h3> +<h3><a href="Scripting.html#Scripting">4 Scripting Languages</a></h3> <!-- INDEX --> <ul> -<li><a href="Scripting.html#n2">The two language view of the world</a> -<li><a href="Scripting.html#n3">How does a scripting language talk to C?</a> +<li><a href="Scripting.html#Scripting_nn2">The two language view of the world</a> +<li><a href="Scripting.html#Scripting_nn3">How does a scripting language talk to C?</a> <ul> -<li><a href="Scripting.html#n4">Wrapper functions</a> -<li><a href="Scripting.html#n5">Variable linking</a> -<li><a href="Scripting.html#n6">Constants</a> -<li><a href="Scripting.html#n7">Structures and classes</a> -<li><a href="Scripting.html#n8">Shadow classes</a> +<li><a href="Scripting.html#Scripting_nn4">Wrapper functions</a> +<li><a href="Scripting.html#Scripting_nn5">Variable linking</a> +<li><a href="Scripting.html#Scripting_nn6">Constants</a> +<li><a href="Scripting.html#Scripting_nn7">Structures and classes</a> +<li><a href="Scripting.html#Scripting_nn8">Shadow classes</a> </ul> -<li><a href="Scripting.html#n9">Building scripting language extensions</a> +<li><a href="Scripting.html#Scripting_nn9">Building scripting language extensions</a> <ul> -<li><a href="Scripting.html#n10">Shared libraries and dynamic loading</a> -<li><a href="Scripting.html#n11">Linking with shared libraries</a> -<li><a href="Scripting.html#n12">Static linking</a> +<li><a href="Scripting.html#Scripting_nn10">Shared libraries and dynamic loading</a> +<li><a href="Scripting.html#Scripting_nn11">Linking with shared libraries</a> +<li><a href="Scripting.html#Scripting_nn12">Static linking</a> </ul> </ul> <!-- INDEX --> -<h3><a href="SWIG.html">4 SWIG Basics</a></h3> +<h3><a href="SWIG.html#SWIG">5 SWIG Basics</a></h3> <!-- INDEX --> <ul> -<li><a href="SWIG.html#n2">Running SWIG</a> +<li><a href="SWIG.html#SWIG_nn2">Running SWIG</a> <ul> -<li><a href="SWIG.html#n3">Input format</a> -<li><a href="SWIG.html#n4">SWIG Output</a> -<li><a href="SWIG.html#n5">Comments</a> -<li><a href="SWIG.html#n6">C Preprocessor</a> -<li><a href="SWIG.html#n7">SWIG Directives</a> -<li><a href="SWIG.html#n8">Parser Limitations</a> +<li><a href="SWIG.html#SWIG_nn3">Input format</a> +<li><a href="SWIG.html#output">SWIG Output</a> +<li><a href="SWIG.html#SWIG_nn5">Comments</a> +<li><a href="SWIG.html#SWIG_nn6">C Preprocessor</a> +<li><a href="SWIG.html#SWIG_nn7">SWIG Directives</a> +<li><a href="SWIG.html#SWIG_nn8">Parser Limitations</a> </ul> -<li><a href="SWIG.html#n9">Wrapping Simple C Declarations</a> +<li><a href="SWIG.html#SWIG_nn9">Wrapping Simple C Declarations</a> <ul> -<li><a href="SWIG.html#n10">Basic Type Handling</a> -<li><a href="SWIG.html#n11">Global Variables</a> -<li><a href="SWIG.html#n12">Constants</a> -<li><a href="SWIG.html#n13">A brief word about <tt>const</tt></a> -<li><a href="SWIG.html#n14">A cautionary tale of <tt>char *</tt></a> +<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> </ul> -<li><a href="SWIG.html#n15">Pointers and complex objects</a> +<li><a href="SWIG.html#SWIG_nn15">Pointers and complex objects</a> <ul> -<li><a href="SWIG.html#n16">Simple pointers</a> -<li><a href="SWIG.html#n17">Run time pointer type checking</a> -<li><a href="SWIG.html#n18">Derived types, structs, and classes</a> -<li><a href="SWIG.html#n19">Undefined datatypes</a> -<li><a href="SWIG.html#n20">Typedef</a> +<li><a href="SWIG.html#SWIG_nn16">Simple pointers</a> +<li><a href="SWIG.html#SWIG_nn17">Run time pointer type checking</a> +<li><a href="SWIG.html#SWIG_nn18">Derived types, structs, and classes</a> +<li><a href="SWIG.html#SWIG_nn19">Undefined datatypes</a> +<li><a href="SWIG.html#SWIG_nn20">Typedef</a> </ul> -<li><a href="SWIG.html#n21">Other Practicalities</a> +<li><a href="SWIG.html#SWIG_nn21">Other Practicalities</a> <ul> -<li><a href="SWIG.html#n22">Passing structures by value</a> -<li><a href="SWIG.html#n23">Return by value</a> -<li><a href="SWIG.html#n24">Linking to structure variables</a> -<li><a href="SWIG.html#n25">Linking to <tt>char *</tt></a> -<li><a href="SWIG.html#n26">Arrays</a> -<li><a href="SWIG.html#n27">Creating read-only variables</a> -<li><a href="SWIG.html#n28">Renaming and ignoring declarations</a> -<li><a href="SWIG.html#n29">Default/optional arguments</a> -<li><a href="SWIG.html#n30">Pointers to functions and callbacks</a> +<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_nn26">Arrays</a> +<li><a href="SWIG.html#SWIG_nn27">Creating read-only variables</a> +<li><a href="SWIG.html#SWIG_nn28">Renaming and ignoring declarations</a> +<li><a href="SWIG.html#SWIG_nn29">Default/optional arguments</a> +<li><a href="SWIG.html#SWIG_nn30">Pointers to functions and callbacks</a> </ul> -<li><a href="SWIG.html#n31">Structures and unions</a> +<li><a href="SWIG.html#SWIG_nn31">Structures and unions</a> <ul> -<li><a href="SWIG.html#n32">Typedef and structures</a> -<li><a href="SWIG.html#n33">Character strings and structures</a> -<li><a href="SWIG.html#n34">Array members</a> -<li><a href="SWIG.html#n35">Structure data members</a> -<li><a href="SWIG.html#n36">C constructors and destructors </a> -<li><a href="SWIG.html#n37">Adding member functions to C structures</a> -<li><a href="SWIG.html#n38">Nested structures</a> -<li><a href="SWIG.html#n39">Other things to note about structure wrapping</a> +<li><a href="SWIG.html#SWIG_nn32">Typedef and structures</a> +<li><a href="SWIG.html#SWIG_nn33">Character strings and structures</a> +<li><a href="SWIG.html#SWIG_nn34">Array members</a> +<li><a href="SWIG.html#SWIG_nn35">Structure data members</a> +<li><a href="SWIG.html#SWIG_nn36">C constructors and destructors </a> +<li><a href="SWIG.html#SWIG_nn37">Adding member functions to C structures</a> +<li><a href="SWIG.html#SWIG_nn38">Nested structures</a> +<li><a href="SWIG.html#SWIG_nn39">Other things to note about structure wrapping</a> </ul> -<li><a href="SWIG.html#n40">Code Insertion</a> +<li><a href="SWIG.html#SWIG_nn40">Code Insertion</a> <ul> -<li><a href="SWIG.html#n41">The output of SWIG</a> -<li><a href="SWIG.html#n42">Code insertion blocks</a> -<li><a href="SWIG.html#n43">Inlined code blocks</a> -<li><a href="SWIG.html#n44">Initialization blocks</a> +<li><a href="SWIG.html#SWIG_nn41">The output of SWIG</a> +<li><a href="SWIG.html#SWIG_nn42">Code insertion blocks</a> +<li><a href="SWIG.html#SWIG_nn43">Inlined code blocks</a> +<li><a href="SWIG.html#SWIG_nn44">Initialization blocks</a> </ul> -<li><a href="SWIG.html#n45">An Interface Building Strategy</a> +<li><a href="SWIG.html#SWIG_nn45">An Interface Building Strategy</a> <ul> -<li><a href="SWIG.html#n46">Preparing a C program for SWIG</a> -<li><a href="SWIG.html#n47">The SWIG interface file</a> -<li><a href="SWIG.html#n48">Why use separate interface files?</a> -<li><a href="SWIG.html#n49">Getting the right header files</a> -<li><a href="SWIG.html#n50">What to do with main()</a> +<li><a href="SWIG.html#SWIG_nn46">Preparing a C program for SWIG</a> +<li><a href="SWIG.html#SWIG_nn47">The SWIG interface file</a> +<li><a href="SWIG.html#SWIG_nn48">Why use separate interface files?</a> +<li><a href="SWIG.html#SWIG_nn49">Getting the right header files</a> +<li><a href="SWIG.html#SWIG_nn50">What to do with main()</a> </ul> </ul> <!-- INDEX --> -<h3><a href="SWIGPlus.html">5 SWIG and C++</a></h3> +<h3><a href="SWIGPlus.html#SWIGPlus">6 SWIG and C++</a></h3> <!-- INDEX --> <ul> -<li><a href="SWIGPlus.html#n2">Comments on C++ Wrapping</a> -<li><a href="SWIGPlus.html#n3">Approach</a> -<li><a href="SWIGPlus.html#n4">Supported C++ features</a> -<li><a href="SWIGPlus.html#n5">Command line options and compilation</a> -<li><a href="SWIGPlus.html#n6">Simple C++ wrapping</a> -<ul> -<li><a href="SWIGPlus.html#n7">Constructors and destructors</a> -<li><a href="SWIGPlus.html#n8">Default constructors</a> -<li><a href="SWIGPlus.html#n9">When constructor wrappers aren't created</a> -<li><a href="SWIGPlus.html#n10">Copy constructors</a> -<li><a href="SWIGPlus.html#n11">Member functions</a> -<li><a href="SWIGPlus.html#n12">Static members</a> -<li><a href="SWIGPlus.html#n13">Member functions and default arguments</a> -<li><a href="SWIGPlus.html#n14">Member data</a> -</ul> -<li><a href="SWIGPlus.html#n15">Protection</a> -<li><a href="SWIGPlus.html#n16">Enums and constants</a> -<li><a href="SWIGPlus.html#n17">Friends</a> -<li><a href="SWIGPlus.html#n18">References and pointers</a> -<li><a href="SWIGPlus.html#n19">Pass and return by value</a> -<li><a href="SWIGPlus.html#n20">Inheritance</a> -<li><a href="SWIGPlus.html#n21">A brief discussion of multiple inheritance, pointers, and type checking</a> -<li><a href="SWIGPlus.html#n22">Renaming</a> -<li><a href="SWIGPlus.html#n23">Wrapping Overloaded Functions and Methods</a> -<ul> -<li><a href="SWIGPlus.html#n24">Dispatch function generation</a> -<li><a href="SWIGPlus.html#n25">Ambiguity in Overloading</a> -<li><a href="SWIGPlus.html#n26">Ambiguity resolution and renaming</a> -<li><a href="SWIGPlus.html#n27">Comments on overloading</a> -</ul> -<li><a href="SWIGPlus.html#n28">Wrapping overloaded operators</a> -<li><a href="SWIGPlus.html#n29">Class extension</a> -<li><a href="SWIGPlus.html#n30">Templates</a> -<li><a href="SWIGPlus.html#n31">Namespaces</a> -<li><a href="SWIGPlus.html#n32">Exception specifiers</a> -<li><a href="SWIGPlus.html#n33">Pointers to Members</a> -<li><a href="SWIGPlus.html#n34">Smart pointers and operator->()</a> -<li><a href="SWIGPlus.html#n35">Using declarations and inheritance</a> -<li><a href="SWIGPlus.html#n36">Partial class definitions</a> -<li><a href="SWIGPlus.html#n37">A brief rant about const-correctness</a> -<li><a href="SWIGPlus.html#n38">Proxy classes</a> -<ul> -<li><a href="SWIGPlus.html#n39">Construction of proxy classes</a> -<li><a href="SWIGPlus.html#n40">Resource management in proxies</a> -<li><a href="SWIGPlus.html#n41">Language specific details</a> -</ul> -<li><a href="SWIGPlus.html#n42">Where to go for more information</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn2">Comments on C++ Wrapping</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn3">Approach</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn4">Supported C++ features</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn5">Command line options and compilation</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn6">Simple C++ wrapping</a> +<ul> +<li><a href="SWIGPlus.html#SWIGPlus_nn7">Constructors and destructors</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn8">Default constructors</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn9">When constructor wrappers aren't created</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn10">Copy constructors</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn11">Member functions</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn12">Static members</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn13">Member functions and default arguments</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn14">Member data</a> +</ul> +<li><a href="SWIGPlus.html#SWIGPlus_nn15">Protection</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn16">Enums and constants</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn17">Friends</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn18">References and pointers</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn19">Pass and return by value</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn20">Inheritance</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn21">A brief discussion of multiple inheritance, pointers, and type checking</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn22">Renaming</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn23">Wrapping Overloaded Functions and Methods</a> +<ul> +<li><a href="SWIGPlus.html#SWIGPlus_nn24">Dispatch function generation</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in Overloading</a> +<li><a href="SWIGPlus.html#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn27">Comments on overloading</a> +</ul> +<li><a href="SWIGPlus.html#SWIGPlus_nn28">Wrapping overloaded operators</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn29">Class extension</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn30">Templates</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn31">Namespaces</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn32">Exception specifiers</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn33">Pointers to Members</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn34">Smart pointers and operator->()</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn35">Using declarations and inheritance</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn36">Partial class definitions</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn37">A brief rant about const-correctness</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn38">Proxy classes</a> +<ul> +<li><a href="SWIGPlus.html#SWIGPlus_nn39">Construction of proxy classes</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn40">Resource management in proxies</a> +<li><a href="SWIGPlus.html#SWIGPlus_nn41">Language specific details</a> +</ul> +<li><a href="SWIGPlus.html#SWIGPlus_nn42">Where to go for more information</a> </ul> <!-- INDEX --> -<h3><a href="Preprocessor.html">6 Preprocessing</a></h3> +<h3><a href="Preprocessor.html#Preprocessor">7 Preprocessing</a></h3> <!-- INDEX --> <ul> -<li><a href="Preprocessor.html#n2">File inclusion</a> -<li><a href="Preprocessor.html#n3">File imports</a> -<li><a href="Preprocessor.html#n4">Conditional Compilation</a> -<li><a href="Preprocessor.html#n5">Macro Expansion</a> -<li><a href="Preprocessor.html#n6">SWIG Macros</a> -<li><a href="Preprocessor.html#n7">C99 and GNU Extensions</a> -<li><a href="Preprocessor.html#n8">Preprocessing and %{ ... %} blocks</a> -<li><a href="Preprocessor.html#n9">Preprocessing and { ... }</a> +<li><a href="Preprocessor.html#Preprocessor_nn2">File inclusion</a> +<li><a href="Preprocessor.html#Preprocessor_nn3">File imports</a> +<li><a href="Preprocessor.html#Preprocessor_nn4">Conditional Compilation</a> +<li><a href="Preprocessor.html#Preprocessor_nn5">Macro Expansion</a> +<li><a href="Preprocessor.html#Preprocessor_nn6">SWIG Macros</a> +<li><a href="Preprocessor.html#Preprocessor_nn7">C99 and GNU Extensions</a> +<li><a href="Preprocessor.html#Preprocessor_nn8">Preprocessing and %{ ... %} blocks</a> +<li><a href="Preprocessor.html#Preprocessor_nn9">Preprocessing and { ... }</a> +<li><a href="Preprocessor.html#Preprocessor_nn10">Viewing preprocessor output</a> </ul> <!-- INDEX --> -<h3><a href="Arguments.html">7 Argument Handling</a></h3> +<h3><a href="Library.html#Library">8 SWIG library</a></h3> <!-- INDEX --> <ul> -<li><a href="Arguments.html#n2">The typemaps.i library</a> +<li><a href="Library.html#Library_nn2">The %include directive and library search path</a> +<li><a href="Library.html#Library_nn3">C Arrays and Pointers</a> <ul> -<li><a href="Arguments.html#n3">Introduction</a> -<li><a href="Arguments.html#n4">Input parameters</a> -<li><a href="Arguments.html#n5">Output parameters</a> -<li><a href="Arguments.html#n6">Input/Output parameters</a> -<li><a href="Arguments.html#n7">Using different names</a> +<li><a href="Library.html#Library_nn4">cpointer.i</a> +<li><a href="Library.html#Library_nn5">carrays.i</a> +<li><a href="Library.html#Library_nn6">cmalloc.i</a> +<li><a href="Library.html#Library_nn7">cdata.i</a> </ul> -<li><a href="Arguments.html#n8">Applying constraints to input values</a> +<li><a href="Library.html#Library_nn8">C String Handling</a> <ul> -<li><a href="Arguments.html#n9">Simple constraint example</a> -<li><a href="Arguments.html#n10">Constraint methods</a> -<li><a href="Arguments.html#n11">Applying constraints to new datatypes</a> +<li><a href="Library.html#Library_nn9">Default string handling</a> +<li><a href="Library.html#Library_nn10">Passing binary data</a> +<li><a href="Library.html#Library_nn11">Using %newobject to release memory</a> +<li><a href="Library.html#Library_nn12">cstring.i</a> </ul> +<li><a href="Library.html#Library_nn13">C++ Library</a> +<ul> +<li><a href="Library.html#Library_nn14">std_string.i</a> +<li><a href="Library.html#Library_nn15">std_vector.i</a> </ul> -<!-- INDEX --> - -<h3><a href="Typemaps.html">8 Typemaps</a></h3> - -<!-- INDEX --> +<li><a href="Library.html#Library_nn16">Utility Libraries</a> <ul> -<li><a href="Typemaps.html#n2">Introduction</a> -<ul> -<li><a href="Typemaps.html#n3">Type conversion</a> -<li><a href="Typemaps.html#n4">Typemaps</a> -<li><a href="Typemaps.html#n5">Pattern matching</a> -<li><a href="Typemaps.html#n6">Reusing typemaps</a> -<li><a href="Typemaps.html#n7">What can be done with typemaps?</a> -<li><a href="Typemaps.html#n8">What can't be done with typemaps?</a> -<li><a href="Typemaps.html#n9">The rest of this chapter</a> -</ul> -<li><a href="Typemaps.html#n10">Typemap specifications</a> -<ul> -<li><a href="Typemaps.html#n11">Defining a typemap</a> -<li><a href="Typemaps.html#n12">Typemap scope</a> -<li><a href="Typemaps.html#n13">Copying a typemap</a> -<li><a href="Typemaps.html#n14">Deleting a typemap</a> -<li><a href="Typemaps.html#n15">Placement of typemaps</a> -</ul> -<li><a href="Typemaps.html#n16">Pattern matching rules</a> -<ul> -<li><a href="Typemaps.html#n17">Basic matching rules</a> -<li><a href="Typemaps.html#n18">Typedef reductions</a> -<li><a href="Typemaps.html#n19">Default typemaps</a> -<li><a href="Typemaps.html#n20">Multi-arguments typemaps</a> -</ul> -<li><a href="Typemaps.html#n21">Code generation rules</a> -<ul> -<li><a href="Typemaps.html#n22">Scope</a> -<li><a href="Typemaps.html#n23">Declaring new local variables</a> -<li><a href="Typemaps.html#n24">Special variables</a> -</ul> -<li><a href="Typemaps.html#n25">Common typemap methods</a> -<ul> -<li><a href="Typemaps.html#n26">"in" typemap</a> -<li><a href="Typemaps.html#n27">"typecheck" typemap</a> -<li><a href="Typemaps.html#n28">"out" typemap</a> -<li><a href="Typemaps.html#n29">"arginit" typemap</a> -<li><a href="Typemaps.html#n30">"default" typemap</a> -<li><a href="Typemaps.html#n31">"check" typemap</a> -<li><a href="Typemaps.html#n32">"argout" typemap</a> -<li><a href="Typemaps.html#n33">"freearg" typemap</a> -<li><a href="Typemaps.html#n34">"newfree" typemap</a> -<li><a href="Typemaps.html#n35">"memberin" typemap</a> -<li><a href="Typemaps.html#n36">"varin" typemap</a> -<li><a href="Typemaps.html#n37">"varout" typemap</a> -<li><a href="Typemaps.html#n38">"throws" typemap</a> -</ul> -<li><a href="Typemaps.html#n39">Some typemap examples</a> -<ul> -<li><a href="Typemaps.html#n40">Typemaps for arrays</a> -<li><a href="Typemaps.html#n41">Implementing constraints with typemaps</a> -</ul> -<li><a href="Typemaps.html#n42">Multi-argument typemaps</a> -<li><a href="Typemaps.html#n43">The run-time type checker</a> -<li><a href="Typemaps.html#n44">Typemaps and overloading</a> -<li><a href="Typemaps.html#n45">More about <tt>%apply</tt> and <tt>%clear</tt></a> -<li><a href="Typemaps.html#n46">Reducing wrapper code size</a> -<li><a href="Typemaps.html#n47">Passing data between typemaps</a> -<li><a href="Typemaps.html#n48">Where to go for more information?</a> +<li><a href="Library.html#Library_nn17">exception.i</a> +</ul> </ul> <!-- INDEX --> -<h3><a href="Customization.html">9 Customization Features</a></h3> +<h3><a href="Arguments.html#Arguments">9 Argument Handling</a></h3> <!-- INDEX --> <ul> -<li><a href="Customization.html#n2">Exception handling with %exception</a> +<li><a href="Arguments.html#Arguments_nn2">The typemaps.i library</a> <ul> -<li><a href="Customization.html#n3">Handling exceptions in C code</a> -<li><a href="Customization.html#n4">Exception handling with longjmp()</a> -<li><a href="Customization.html#n5">Handling C++ exceptions</a> -<li><a href="Customization.html#n6">Defining different exception handlers</a> -<li><a href="Customization.html#n7">Using The SWIG exception library</a> +<li><a href="Arguments.html#Arguments_nn3">Introduction</a> +<li><a href="Arguments.html#Arguments_nn4">Input parameters</a> +<li><a href="Arguments.html#Arguments_nn5">Output parameters</a> +<li><a href="Arguments.html#Arguments_nn6">Input/Output parameters</a> +<li><a href="Arguments.html#Arguments_nn7">Using different names</a> +</ul> +<li><a href="Arguments.html#Arguments_nn8">Applying constraints to input values</a> +<ul> +<li><a href="Arguments.html#Arguments_nn9">Simple constraint example</a> +<li><a href="Arguments.html#Arguments_nn10">Constraint methods</a> +<li><a href="Arguments.html#Arguments_nn11">Applying constraints to new datatypes</a> </ul> -<li><a href="Customization.html#n8">Object ownership and %newobject</a> -<li><a href="Customization.html#n9">Features and the %feature directive</a> </ul> <!-- INDEX --> -<h3><a href="Contract.html">10 Contracts</a></h3> +<h3><a href="Typemaps.html#Typemaps">10 Typemaps</a></h3> <!-- INDEX --> <ul> -<li><a href="Contract.html#n2">The %contract directive</a> -<li><a href="Contract.html#n3">%contract and classes</a> -<li><a href="Contract.html#n4">Constant aggregation and %aggregate_check</a> -<li><a href="Contract.html#n5">Notes</a> +<li><a href="Typemaps.html#Typemaps_nn2">Introduction</a> +<ul> +<li><a href="Typemaps.html#Typemaps_nn3">Type conversion</a> +<li><a href="Typemaps.html#Typemaps_nn4">Typemaps</a> +<li><a href="Typemaps.html#Typemaps_nn5">Pattern matching</a> +<li><a href="Typemaps.html#Typemaps_nn6">Reusing typemaps</a> +<li><a href="Typemaps.html#Typemaps_nn7">What can be done with typemaps?</a> +<li><a href="Typemaps.html#Typemaps_nn8">What can't be done with typemaps?</a> +<li><a href="Typemaps.html#Typemaps_nn9">The rest of this chapter</a> +</ul> +<li><a href="Typemaps.html#Typemaps_nn10">Typemap specifications</a> +<ul> +<li><a href="Typemaps.html#Typemaps_nn11">Defining a typemap</a> +<li><a href="Typemaps.html#Typemaps_nn12">Typemap scope</a> +<li><a href="Typemaps.html#Typemaps_nn13">Copying a typemap</a> +<li><a href="Typemaps.html#Typemaps_nn14">Deleting a typemap</a> +<li><a href="Typemaps.html#Typemaps_nn15">Placement of typemaps</a> +</ul> +<li><a href="Typemaps.html#Typemaps_nn16">Pattern matching rules</a> +<ul> +<li><a href="Typemaps.html#Typemaps_nn17">Basic matching rules</a> +<li><a href="Typemaps.html#Typemaps_nn18">Typedef reductions</a> +<li><a href="Typemaps.html#Typemaps_nn19">Default typemaps</a> +<li><a href="Typemaps.html#Typemaps_nn20">Multi-arguments typemaps</a> +</ul> +<li><a href="Typemaps.html#Typemaps_nn21">Code generation rules</a> +<ul> +<li><a href="Typemaps.html#Typemaps_nn22">Scope</a> +<li><a href="Typemaps.html#Typemaps_nn23">Declaring new local variables</a> +<li><a href="Typemaps.html#Typemaps_nn24">Special variables</a> +</ul> +<li><a href="Typemaps.html#Typemaps_nn25">Common typemap methods</a> +<ul> +<li><a href="Typemaps.html#Typemaps_nn26">"in" typemap</a> +<li><a href="Typemaps.html#Typemaps_nn27">"typecheck" typemap</a> +<li><a href="Typemaps.html#Typemaps_nn28">"out" typemap</a> +<li><a href="Typemaps.html#Typemaps_nn29">"arginit" typemap</a> +<li><a href="Typemaps.html#Typemaps_nn30">"default" typemap</a> +<li><a href="Typemaps.html#Typemaps_nn31">"check" typemap</a> +<li><a href="Typemaps.html#Typemaps_nn32">"argout" typemap</a> +<li><a href="Typemaps.html#Typemaps_nn33">"freearg" typemap</a> +<li><a href="Typemaps.html#Typemaps_nn34">"newfree" typemap</a> +<li><a href="Typemaps.html#Typemaps_nn35">"memberin" typemap</a> +<li><a href="Typemaps.html#Typemaps_nn36">"varin" typemap</a> +<li><a href="Typemaps.html#Typemaps_nn37">"varout" typemap</a> +<li><a href="Typemaps.html#throws_typemap">"throws" typemap</a> +</ul> +<li><a href="Typemaps.html#Typemaps_nn39">Some typemap examples</a> +<ul> +<li><a href="Typemaps.html#Typemaps_nn40">Typemaps for arrays</a> +<li><a href="Typemaps.html#Typemaps_nn41">Implementing constraints with typemaps</a> +</ul> +<li><a href="Typemaps.html#Typemaps_nn42">Multi-argument typemaps</a> +<li><a href="Typemaps.html#runtime_type_checker">The run-time type checker</a> +<li><a href="Typemaps.html#Typemaps_nn44">Typemaps and overloading</a> +<li><a href="Typemaps.html#Typemaps_nn45">More about <tt>%apply</tt> and <tt>%clear</tt></a> +<li><a href="Typemaps.html#Typemaps_nn46">Reducing wrapper code size</a> +<li><a href="Typemaps.html#Typemaps_nn47">Passing data between typemaps</a> +<li><a href="Typemaps.html#Typemaps_nn48">Where to go for more information?</a> </ul> <!-- INDEX --> -<h3><a href="Varargs.html">11 Variable Length Arguments</a></h3> +<h3><a href="Customization.html#Customization">11 Customization Features</a></h3> <!-- INDEX --> <ul> -<li><a href="Varargs.html#n2">Introduction</a> -<li><a href="Varargs.html#n3">The Problem</a> -<li><a href="Varargs.html#n4">Default varargs support</a> -<li><a href="Varargs.html#n5">Argument replacement using %varargs</a> -<li><a href="Varargs.html#n6">Varargs and typemaps</a> -<li><a href="Varargs.html#n7">Varargs wrapping with libffi</a> -<li><a href="Varargs.html#n8">Wrapping of va_list</a> -<li><a href="Varargs.html#n9">C++ Issues</a> -<li><a href="Varargs.html#n10">Discussion</a> +<li><a href="Customization.html#exception">Exception handling with %exception</a> +<ul> +<li><a href="Customization.html#Customization_nn3">Handling exceptions in C code</a> +<li><a href="Customization.html#Customization_nn4">Exception handling with longjmp()</a> +<li><a href="Customization.html#Customization_nn5">Handling C++ exceptions</a> +<li><a href="Customization.html#Customization_nn6">Defining different exception handlers</a> +<li><a href="Customization.html#Customization_nn7">Using The SWIG exception library</a> +</ul> +<li><a href="Customization.html#ownership">Object ownership and %newobject</a> +<li><a href="Customization.html#features">Features and the %feature directive</a> </ul> <!-- INDEX --> -<h3><a href="Warnings.html">12 Warning Messages</a></h3> +<h3><a href="Contract.html#Contract">12 Contracts</a></h3> <!-- INDEX --> <ul> -<li><a href="Warnings.html#n2">Introduction</a> -<li><a href="Warnings.html#n3">Warning message suppression</a> -<li><a href="Warnings.html#n4">Enabling additional warnings</a> -<li><a href="Warnings.html#n5">Issuing a warning message</a> -<li><a href="Warnings.html#n6">Commentary</a> -<li><a href="Warnings.html#n7">Warnings as errors</a> -<li><a href="Warnings.html#n8">Message output format</a> -<li><a href="Warnings.html#n9">Warning number reference</a> -<ul> -<li><a href="Warnings.html#n10">Deprecated features (100-199)</a> -<li><a href="Warnings.html#n11">Preprocessor (200-299)</a> -<li><a href="Warnings.html#n12">C/C++ Parser (300-399)</a> -<li><a href="Warnings.html#n13">Types and typemaps (400-499) </a> -<li><a href="Warnings.html#n14">Code generation (500-599)</a> -<li><a href="Warnings.html#n15">Language module specific (800-899) </a> -<li><a href="Warnings.html#n16">User defined (900-999)</a> -</ul> -<li><a href="Warnings.html#n17">History</a> +<li><a href="Contract.html#Contract_nn2">The %contract directive</a> +<li><a href="Contract.html#Contract_nn3">%contract and classes</a> +<li><a href="Contract.html#Contract_nn4">Constant aggregation and %aggregate_check</a> +<li><a href="Contract.html#Contract_nn5">Notes</a> </ul> <!-- INDEX --> -<h3><a href="Library.html">13 SWIG library</a></h3> +<h3><a href="Varargs.html#Varargs">13 Variable Length Arguments</a></h3> <!-- INDEX --> <ul> -<li><a href="Library.html#n2">The %include directive and library search path</a> -<li><a href="Library.html#n3">C Arrays and Pointers</a> -<ul> -<li><a href="Library.html#n4">cpointer.i</a> -<li><a href="Library.html#n5">carrays.i</a> -<li><a href="Library.html#n6">cmalloc.i</a> -<li><a href="Library.html#n7">cdata.i</a> +<li><a href="Varargs.html#Varargs_nn2">Introduction</a> +<li><a href="Varargs.html#Varargs_nn3">The Problem</a> +<li><a href="Varargs.html#Varargs_nn4">Default varargs support</a> +<li><a href="Varargs.html#Varargs_nn5">Argument replacement using %varargs</a> +<li><a href="Varargs.html#Varargs_nn6">Varargs and typemaps</a> +<li><a href="Varargs.html#Varargs_nn7">Varargs wrapping with libffi</a> +<li><a href="Varargs.html#Varargs_nn8">Wrapping of va_list</a> +<li><a href="Varargs.html#Varargs_nn9">C++ Issues</a> +<li><a href="Varargs.html#Varargs_nn10">Discussion</a> </ul> -<li><a href="Library.html#n8">C String Handling</a> -<ul> -<li><a href="Library.html#n9">Default string handling</a> -<li><a href="Library.html#n10">Passing binary data</a> -<li><a href="Library.html#n11">Using %newobject to release memory</a> -<li><a href="Library.html#n12">cstring.i</a> -</ul> -<li><a href="Library.html#n13">C++ Library</a> -<ul> -<li><a href="Library.html#n14">std_string.i</a> -<li><a href="Library.html#n15">std_vector.i</a> -</ul> -<li><a href="Library.html#n16">Utility Libraries</a> +<!-- INDEX --> + +<h3><a href="Warnings.html#Warnings">14 Warning Messages</a></h3> + +<!-- INDEX --> <ul> -<li><a href="Library.html#n17">exception.i</a> -</ul> +<li><a href="Warnings.html#Warnings_nn2">Introduction</a> +<li><a href="Warnings.html#Warnings_nn3">Warning message suppression</a> +<li><a href="Warnings.html#Warnings_nn4">Enabling additional warnings</a> +<li><a href="Warnings.html#Warnings_nn5">Issuing a warning message</a> +<li><a href="Warnings.html#Warnings_nn6">Commentary</a> +<li><a href="Warnings.html#Warnings_nn7">Warnings as errors</a> +<li><a href="Warnings.html#Warnings_nn8">Message output format</a> +<li><a href="Warnings.html#Warnings_nn9">Warning number reference</a> +<ul> +<li><a href="Warnings.html#Warnings_nn10">Deprecated features (100-199)</a> +<li><a href="Warnings.html#Warnings_nn11">Preprocessor (200-299)</a> +<li><a href="Warnings.html#Warnings_nn12">C/C++ Parser (300-399)</a> +<li><a href="Warnings.html#Warnings_nn13">Types and typemaps (400-499) </a> +<li><a href="Warnings.html#Warnings_nn14">Code generation (500-599)</a> +<li><a href="Warnings.html#Warnings_nn15">Language module specific (800-899) </a> +<li><a href="Warnings.html#Warnings_nn16">User defined (900-999)</a> +</ul> +<li><a href="Warnings.html#Warnings_nn17">History</a> </ul> <!-- INDEX --> -<h3><a href="Modules.html">14 Working with Modules</a></h3> +<h3><a href="Modules.html#Modules">15 Working with Modules</a></h3> <!-- INDEX --> <ul> -<li><a href="Modules.html#n2">The SWIG runtime code</a> -<li><a href="Modules.html#n3">Compiling Multiple SWIG modules</a> -<li><a href="Modules.html#n4">A word of caution about static libraries</a> -<li><a href="Modules.html#n5">References</a> +<li><a href="Modules.html#Modules_nn2">The SWIG runtime code</a> +<li><a href="Modules.html#Modules_nn3">Compiling Multiple SWIG modules</a> +<li><a href="Modules.html#Modules_nn4">A word of caution about static libraries</a> +<li><a href="Modules.html#Modules_nn5">References</a> +<li><a href="Modules.html#Modules_nn6">Reducing the wrapper file size</a> </ul> <!-- INDEX --> -<h3><a href="Advanced.html">15 Advanced Topics</a></h3> +<h3><a href="CSharp.html#CSharp">16 SWIG and C#</a></h3> + +<!-- INDEX --> +<!-- INDEX --> + +<h3><a href="Chicken.html#Chicken">17 SWIG and Chicken</a></h3> <!-- INDEX --> <ul> -<li><a href="Advanced.html#n2">Creating multi-module packages</a> +<li><a href="Chicken.html#Chicken_nn2">Preliminaries</a> +<ul> +<li><a href="Chicken.html#Chicken_nn3">Running SWIG in C mode</a> +<li><a href="Chicken.html#Chicken_nn4">Running SWIG in C++ mode</a> +</ul> +<li><a href="Chicken.html#Chicken_nn5">Code Generation</a> <ul> -<li><a href="Advanced.html#n3">Runtime support (and potential problems)</a> -<li><a href="Advanced.html#n4">Why doesn't C++ inheritance work between modules?</a> -<li><a href="Advanced.html#n5">The SWIG runtime library</a> -<li><a href="Advanced.html#n6">A few dynamic loading gotchas</a> +<li><a href="Chicken.html#Chicken_nn6">Naming Conventions</a> +<li><a href="Chicken.html#Chicken_nn7">Modules and Prefixes</a> +<li><a href="Chicken.html#Chicken_nn8">Constants and Variables</a> +<li><a href="Chicken.html#Chicken_nn9">Functions</a> </ul> -<li><a href="Advanced.html#n7">Dynamic Loading of C++ modules</a> -<li><a href="Advanced.html#n8">Inside the SWIG type-checker</a> +<li><a href="Chicken.html#Chicken_nn10">TinyCLOS</a> +<li><a href="Chicken.html#Chicken_nn11">Compilation</a> +<li><a href="Chicken.html#Chicken_nn12">Linkage</a> <ul> -<li><a href="Advanced.html#n9">Type equivalence</a> -<li><a href="Advanced.html#n10">Type casting</a> -<li><a href="Advanced.html#n11">Why a name based approach?</a> -<li><a href="Advanced.html#n12">Performance of the type-checker</a> +<li><a href="Chicken.html#Chicken_nn13">Shared library</a> +<li><a href="Chicken.html#Chicken_nn14">Static binary</a> </ul> +<li><a href="Chicken.html#Chicken_nn15">Typemaps</a> +<li><a href="Chicken.html#Chicken_nn16">Pointers</a> +<li><a href="Chicken.html#Chicken_nn17">Unsupported features</a> </ul> <!-- INDEX --> -<h3><a href="Guile.html">16 SWIG and Guile</a></h3> +<h3><a href="Guile.html#Guile">18 SWIG and Guile</a></h3> <!-- INDEX --> <ul> -<li><a href="Guile.html#n2">Meaning of "Module"</a> -<li><a href="Guile.html#n3">Using the SCM or GH Guile API</a> -<li><a href="Guile.html#n4">Linkage</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_nn4">Linkage</a> <ul> -<li><a href="Guile.html#n5">Simple Linkage</a> -<li><a href="Guile.html#n6">Passive Linkage</a> -<li><a href="Guile.html#n7">Native Guile Module Linkage</a> -<li><a href="Guile.html#n8">Old Auto-Loading Guile Module Linkage</a> -<li><a href="Guile.html#n9">Hobbit4D Linkage</a> -<li><a href="Guile.html#n10">General Remarks on Multiple SWIG Modules</a> +<li><a href="Guile.html#Guile_nn5">Simple Linkage</a> +<li><a href="Guile.html#Guile_nn6">Passive Linkage</a> +<li><a href="Guile.html#Guile_nn7">Native Guile Module Linkage</a> +<li><a href="Guile.html#Guile_nn8">Old Auto-Loading Guile Module Linkage</a> +<li><a href="Guile.html#Guile_nn9">Hobbit4D Linkage</a> +<li><a href="Guile.html#Guile_nn10">General Remarks on Multiple SWIG Modules</a> </ul> -<li><a href="Guile.html#n11">Underscore Folding</a> -<li><a href="Guile.html#n12">Typemaps</a> -<li><a href="Guile.html#n13">Representation of pointers as smobs</a> +<li><a href="Guile.html#Guile_nn11">Underscore Folding</a> +<li><a href="Guile.html#Guile_nn12">Typemaps</a> +<li><a href="Guile.html#Guile_nn13">Representation of pointers as smobs</a> <ul> -<li><a href="Guile.html#n14">GH Smobs</a> -<li><a href="Guile.html#n15">SCM Smobs</a> -<li><a href="Guile.html#n16">Garbage Collection</a> +<li><a href="Guile.html#Guile_nn14">GH Smobs</a> +<li><a href="Guile.html#Guile_nn15">SCM Smobs</a> +<li><a href="Guile.html#Guile_nn16">Garbage Collection</a> </ul> -<li><a href="Guile.html#n17">Exception Handling</a> -<li><a href="Guile.html#n18">Procedure documentation</a> -<li><a href="Guile.html#n19">Procedures with setters</a> -<li><a href="Guile.html#n20">GOOPS Shadow Classes</a> +<li><a href="Guile.html#Guile_nn17">Exception Handling</a> +<li><a href="Guile.html#Guile_nn18">Procedure documentation</a> +<li><a href="Guile.html#Guile_nn19">Procedures with setters</a> +<li><a href="Guile.html#Guile_nn20">GOOPS Shadow Classes</a> <ul> -<li><a href="Guile.html#n21">Naming Issues</a> -<li><a href="Guile.html#n22">Linking</a> +<li><a href="Guile.html#Guile_nn21">Naming Issues</a> +<li><a href="Guile.html#Guile_nn22">Linking</a> </ul> </ul> <!-- INDEX --> -<h3><a href="Java.html">17 SWIG and Java</a></h3> +<h3><a href="Java.html#Java">19 SWIG and Java</a></h3> <!-- INDEX --> <ul> -<li><a href="Java.html#n2">Overview</a> -<li><a href="Java.html#n3">Preliminaries</a> +<li><a href="Java.html#java_overview">Overview</a> +<li><a href="Java.html#java_preliminaries">Preliminaries</a> <ul> -<li><a href="Java.html#n4">Running SWIG</a> -<li><a href="Java.html#n5">Additional Commandline Options</a> -<li><a href="Java.html#n6">Getting the right header files</a> -<li><a href="Java.html#n7">Compiling a dynamic module</a> -<li><a href="Java.html#n8">Using your module</a> -<li><a href="Java.html#n9">Dynamic linking problems</a> -<li><a href="Java.html#n10">Compilation problems and compiling with C++</a> -<li><a href="Java.html#n11">Building on Windows</a> +<li><a href="Java.html#running_swig">Running SWIG</a> +<li><a href="Java.html#java_commandline">Additional Commandline Options</a> +<li><a href="Java.html#getting_right_headers">Getting the right header files</a> +<li><a href="Java.html#compiling_dynamic">Compiling a dynamic module</a> +<li><a href="Java.html#using_module">Using your module</a> +<li><a href="Java.html#dynamic_linking_problems">Dynamic linking problems</a> +<li><a href="Java.html#compilation_problems_cpp">Compilation problems and compiling with C++</a> +<li><a href="Java.html#building_windows">Building on Windows</a> <ul> -<li><a href="Java.html#n12">Running SWIG from Visual Studio</a> -<li><a href="Java.html#n13">Using NMAKE</a> +<li><a href="Java.html#visual_studio">Running SWIG from Visual Studio</a> +<li><a href="Java.html#nmake">Using NMAKE</a> </ul> </ul> -<li><a href="Java.html#n14">A tour of basic C/C++ wrapping</a> +<li><a href="Java.html#java_basic_tour">A tour of basic C/C++ wrapping</a> <ul> -<li><a href="Java.html#n15">Modules, packages and generated Java classes</a> -<li><a href="Java.html#n16">Functions</a> -<li><a href="Java.html#n17">Global variables</a> -<li><a href="Java.html#n18">Constants</a> -<li><a href="Java.html#n19">Enumerations</a> +<li><a href="Java.html#module_packages_classes">Modules, packages and generated Java classes</a> +<li><a href="Java.html#functions">Functions</a> +<li><a href="Java.html#global_variables">Global variables</a> +<li><a href="Java.html#constants">Constants</a> +<li><a href="Java.html#enumerations">Enumerations</a> <ul> -<li><a href="Java.html#n20">Anonymous enums</a> -<li><a href="Java.html#n21">Typesafe enums</a> -<li><a href="Java.html#n22">Proper Java enums</a> -<li><a href="Java.html#n23">Type unsafe enums</a> -<li><a href="Java.html#n24">Simple enums</a> +<li><a href="Java.html#anonymous_enums">Anonymous enums</a> +<li><a href="Java.html#typesafe_enums">Typesafe enums</a> +<li><a href="Java.html#proper_enums">Proper Java enums</a> +<li><a href="Java.html#typeunsafe_enums">Type unsafe enums</a> +<li><a href="Java.html#simple_enums">Simple enums</a> </ul> -<li><a href="Java.html#n25">Pointers</a> -<li><a href="Java.html#n26">Structures</a> -<li><a href="Java.html#n27">C++ classes</a> -<li><a href="Java.html#n28">C++ inheritance</a> -<li><a href="Java.html#n29">Pointers, references, arrays and pass by value</a> +<li><a href="Java.html#pointers">Pointers</a> +<li><a href="Java.html#structures">Structures</a> +<li><a href="Java.html#classes">C++ classes</a> +<li><a href="Java.html#inheritance">C++ inheritance</a> +<li><a href="Java.html#pointers_refs_arrays">Pointers, references, arrays and pass by value</a> <ul> -<li><a href="Java.html#n30">Null pointers</a> +<li><a href="Java.html#null_pointers">Null pointers</a> </ul> -<li><a href="Java.html#n31">C++ overloaded functions</a> -<li><a href="Java.html#n32">C++ namespaces</a> -<li><a href="Java.html#n33">C++ templates</a> -<li><a href="Java.html#n34">C++ Smart Pointers</a> +<li><a href="Java.html#overloaded_functions">C++ overloaded functions</a> +<li><a href="Java.html#namespaces">C++ namespaces</a> +<li><a href="Java.html#templates">C++ templates</a> +<li><a href="Java.html#smart_pointers">C++ Smart Pointers</a> </ul> -<li><a href="Java.html#n35">Further details on the generated Java classes</a> +<li><a href="Java.html#further_details">Further details on the generated Java classes</a> <ul> -<li><a href="Java.html#n36">The intermediary JNI class</a> +<li><a href="Java.html#imclass">The intermediary JNI class</a> <ul> -<li><a href="Java.html#n37">The intermediary JNI class pragmas</a> +<li><a href="Java.html#imclass_pragmas">The intermediary JNI class pragmas</a> </ul> -<li><a href="Java.html#n38">The Java module class</a> +<li><a href="Java.html#java_module_class">The Java module class</a> <ul> -<li><a href="Java.html#n39">The Java module class pragmas</a> +<li><a href="Java.html#module_class_pragmas">The Java module class pragmas</a> </ul> -<li><a href="Java.html#n40">Java proxy classes</a> +<li><a href="Java.html#java_proxy_classes">Java proxy classes</a> <ul> -<li><a href="Java.html#n41">Memory management</a> -<li><a href="Java.html#n42">Inheritance</a> -<li><a href="Java.html#n43">Proxy classes and garbage collection</a> +<li><a href="Java.html#memory_management">Memory management</a> +<li><a href="Java.html#inheritance_mirroring">Inheritance</a> +<li><a href="Java.html#proxy_classes_gc">Proxy classes and garbage collection</a> </ul> -<li><a href="Java.html#n44">Type wrapper classes</a> -<li><a href="Java.html#n45">Enum classes</a> +<li><a href="Java.html#type_wrapper_classes">Type wrapper classes</a> +<li><a href="Java.html#enum_classes">Enum classes</a> <ul> -<li><a href="Java.html#n46">Typesafe enum classes</a> -<li><a href="Java.html#n47">Proper Java enum classes</a> -<li><a href="Java.html#n48">Type unsafe enum classes</a> +<li><a href="Java.html#typesafe_enums_classes">Typesafe enum classes</a> +<li><a href="Java.html#proper_enums_classes">Proper Java enum classes</a> +<li><a href="Java.html#typeunsafe_enums_classes">Type unsafe enum classes</a> </ul> </ul> -<li><a href="Java.html#n49">Cross language polymorphism using directors (experimental)</a> +<li><a href="Java.html#java_directors">Cross language polymorphism using directors (experimental)</a> <ul> -<li><a href="Java.html#n50">Enabling directors</a> -<li><a href="Java.html#n51">Director classes</a> -<li><a href="Java.html#n52">Overhead and code bloat</a> -<li><a href="Java.html#n53">Simple directors example</a> +<li><a href="Java.html#java_enabling_directors">Enabling directors</a> +<li><a href="Java.html#java_directors_classes">Director classes</a> +<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> </ul> -<li><a href="Java.html#n54">Common customization features</a> +<li><a href="Java.html#common_customization">Common customization features</a> <ul> -<li><a href="Java.html#n55">C/C++ helper functions</a> -<li><a href="Java.html#n56">Class extension with %extend</a> -<li><a href="Java.html#n57">Exception handling with %exception and %javaexception</a> -<li><a href="Java.html#n58">Method access with %javamethodmodifiers</a> +<li><a href="Java.html#helper_functions">C/C++ helper functions</a> +<li><a href="Java.html#class_extension">Class extension with %extend</a> +<li><a href="Java.html#exception_handling">Exception handling with %exception and %javaexception</a> +<li><a href="Java.html#method_access">Method access with %javamethodmodifiers</a> </ul> -<li><a href="Java.html#n59">Tips and techniques</a> +<li><a href="Java.html#tips_techniques">Tips and techniques</a> <ul> -<li><a href="Java.html#n60">Input and output parameters using primitive pointers and references</a> -<li><a href="Java.html#n61">Simple pointers</a> -<li><a href="Java.html#n62">Wrapping C arrays with Java arrays</a> -<li><a href="Java.html#n63">Unbounded C Arrays</a> +<li><a href="Java.html#input_output_parameters">Input and output parameters using primitive pointers and references</a> +<li><a href="Java.html#simple_pointers">Simple pointers</a> +<li><a href="Java.html#c_arrays">Wrapping C arrays with Java arrays</a> +<li><a href="Java.html#unbounded_c_arrays">Unbounded C Arrays</a> </ul> -<li><a href="Java.html#n64">Java typemaps</a> +<li><a href="Java.html#java_typemaps">Java typemaps</a> <ul> -<li><a href="Java.html#n65">Default primitive type mappings</a> -<li><a href="Java.html#n66">Sixty four bit JVMs</a> -<li><a href="Java.html#n67">What is a typemap?</a> -<li><a href="Java.html#n68">Typemaps for mapping C/C++ types to Java types</a> -<li><a href="Java.html#n69">Java typemap attributes</a> -<li><a href="Java.html#n70">Java special variables</a> -<li><a href="Java.html#n71">Typemaps for both C and C++ compilation</a> -<li><a href="Java.html#n72">Java code typemaps</a> -<li><a href="Java.html#n73">Director specific typemaps</a> +<li><a href="Java.html#default_primitive_type_mappings">Default primitive type mappings</a> +<li><a href="Java.html#jvm64">Sixty four bit JVMs</a> +<li><a href="Java.html#what_is_typemap">What is a typemap?</a> +<li><a href="Java.html#typemaps_c_to_java_types">Typemaps for mapping C/C++ types to Java types</a> +<li><a href="Java.html#typemap_attributes">Java typemap attributes</a> +<li><a href="Java.html#special_variables">Java special variables</a> +<li><a href="Java.html#typemaps_for_c_and_c++">Typemaps for both C and C++ compilation</a> +<li><a href="Java.html#java_code_typemaps">Java code typemaps</a> +<li><a href="Java.html#java_directors_typemaps">Director specific typemaps</a> </ul> -<li><a href="Java.html#n74">Typemap Examples</a> +<li><a href="Java.html#typemap_examples">Typemap Examples</a> <ul> -<li><a href="Java.html#n75">Simpler Java enums for enums without initializers</a> -<li><a href="Java.html#n76">Handling C++ exception specifications as Java exceptions</a> -<li><a href="Java.html#n77">NaN Exception - exception handling for a particular type</a> -<li><a href="Java.html#n78">Converting Java String arrays to char ** </a> -<li><a href="Java.html#n79">Expanding a Java object to multiple arguments</a> -<li><a href="Java.html#n80">Using typemaps to return arguments</a> -<li><a href="Java.html#n81">Adding Java downcasts to polymorphic return types</a> -<li><a href="Java.html#n82">Adding an equals method to the Java classes</a> -<li><a href="Java.html#n83">Void pointers and a common Java base class</a> +<li><a href="Java.html#simpler_enum_classes">Simpler Java enums for enums without initializers</a> +<li><a href="Java.html#exception_typemap">Handling C++ exception specifications as Java exceptions</a> +<li><a href="Java.html#nan_exception_typemap">NaN Exception - exception handling for a particular type</a> +<li><a href="Java.html#converting_java_string_arrays">Converting Java String arrays to char ** </a> +<li><a href="Java.html#expanding_java_object">Expanding a Java object to multiple arguments</a> +<li><a href="Java.html#using_typemaps_return_arguments">Using typemaps to return arguments</a> +<li><a href="Java.html#adding_downcasts">Adding Java downcasts to polymorphic return types</a> +<li><a href="Java.html#adding_equals_method">Adding an equals method to the Java classes</a> +<li><a href="Java.html#void_pointers">Void pointers and a common Java base class</a> </ul> -<li><a href="Java.html#n84">Living with Java Directors</a> -<li><a href="Java.html#n85">Odds and ends</a> +<li><a href="Java.html#java_directors_faq">Living with Java Directors</a> +<li><a href="Java.html#odds_ends">Odds and ends</a> <ul> -<li><a href="Java.html#n86">JavaDoc comments</a> -<li><a href="Java.html#n87">Functional interface without proxy classes</a> -<li><a href="Java.html#n88">Using your own JNI functions</a> -<li><a href="Java.html#n89">Performance concerns and hints</a> +<li><a href="Java.html#javadoc_comments">JavaDoc comments</a> +<li><a href="Java.html#functional_interface">Functional interface without proxy classes</a> +<li><a href="Java.html#using_own_jni_functions">Using your own JNI functions</a> +<li><a href="Java.html#performance">Performance concerns and hints</a> </ul> -<li><a href="Java.html#n90">Examples</a> +<li><a href="Java.html#java_examples">Examples</a> </ul> <!-- INDEX --> -<h3><a href="Modula3.html">18 SWIG and Modula-3</a></h3> +<h3><a href="Modula3.html#Modula3">20 SWIG and Modula-3</a></h3> <!-- INDEX --> <ul> -<li><a href="Modula3.html#n2">Overview</a> -<li><a href="Modula3.html#n3">Conception</a> +<li><a href="Modula3.html#modula3_overview">Overview</a> +<li><a href="Modula3.html#conception">Conception</a> <ul> -<li><a href="Modula3.html#n4">Interfaces to C libraries</a> -<li><a href="Modula3.html#n5">Interfaces to C++ libraries</a> -<li><a href="Modula3.html#n6">No plan?</a> +<li><a href="Modula3.html#cinterface">Interfaces to C libraries</a> +<li><a href="Modula3.html#noplan">Interfaces to C++ libraries</a> +<li><a href="Modula3.html#cppinterface">No plan?</a> </ul> -<li><a href="Modula3.html#n7">Preliminaries</a> +<li><a href="Modula3.html#preliminaries">Preliminaries</a> <ul> -<li><a href="Modula3.html#n8">Compilers</a> -<li><a href="Modula3.html#n9">Additional Commandline Options</a> +<li><a href="Modula3.html#compilers">Compilers</a> +<li><a href="Modula3.html#commandline">Additional Commandline Options</a> </ul> -<li><a href="Modula3.html#n10">Modula-3 typemaps</a> +<li><a href="Modula3.html#modula3_typemaps">Modula-3 typemaps</a> <ul> -<li><a href="Modula3.html#n11">Inputs and outputs</a> -<li><a href="Modula3.html#n12">Subranges, Enumerations, Sets</a> -<li><a href="Modula3.html#n13">Objects</a> -<li><a href="Modula3.html#n14">Imports</a> -<li><a href="Modula3.html#n15">Exceptions</a> -<li><a href="Modula3.html#n16">Pragmas</a> -<li><a href="Modula3.html#n17">Example</a> -<li><a href="Modula3.html#n18">Remarks</a> +<li><a href="Modula3.html#inoutparam">Inputs and outputs</a> +<li><a href="Modula3.html#ordinals">Subranges, Enumerations, Sets</a> +<li><a href="Modula3.html#class">Objects</a> +<li><a href="Modula3.html#imports">Imports</a> +<li><a href="Modula3.html#exceptions">Exceptions</a> +<li><a href="Modula3.html#swig_pragmas">Pragmas</a> +<li><a href="Modula3.html#typemap_example">Example</a> +<li><a href="Modula3.html#remarks">Remarks</a> </ul> </ul> <!-- INDEX --> -<h3><a href="Ocaml.html">19 SWIG and Ocaml</a></h3> +<h3><a href="Ocaml.html#Ocaml">21 SWIG and Ocaml</a></h3> <!-- INDEX --> <ul> -<li><a href="Ocaml.html#n2">Preliminaries</a> +<li><a href="Ocaml.html#Ocaml_nn2">Preliminaries</a> <ul> -<li><a href="Ocaml.html#n3">Running SWIG</a> -<li><a href="Ocaml.html#n4">Compiling the code</a> -<li><a href="Ocaml.html#n5">The camlp4 module</a> -<li><a href="Ocaml.html#n6">Using your module</a> -<li><a href="Ocaml.html#n7">Compilation problems and compiling with C++</a> +<li><a href="Ocaml.html#Ocaml_nn3">Running SWIG</a> +<li><a href="Ocaml.html#Ocaml_nn4">Compiling the code</a> +<li><a href="Ocaml.html#Ocaml_nn5">The camlp4 module</a> +<li><a href="Ocaml.html#Ocaml_nn6">Using your module</a> +<li><a href="Ocaml.html#Ocaml_nn7">Compilation problems and compiling with C++</a> </ul> -<li><a href="Ocaml.html#n8">The low-level Ocaml/C interface</a> +<li><a href="Ocaml.html#Ocaml_nn8">The low-level Ocaml/C interface</a> <ul> -<li><a href="Ocaml.html#n9">The generated module</a> -<li><a href="Ocaml.html#n10">Enums</a> -<li><a href="Ocaml.html#n11">Arrays</a> +<li><a href="Ocaml.html#Ocaml_nn9">The generated module</a> +<li><a href="Ocaml.html#Ocaml_nn10">Enums</a> +<li><a href="Ocaml.html#Ocaml_nn11">Arrays</a> <ul> -<li><a href="Ocaml.html#n12">Simple types of bounded arrays</a> -<li><a href="Ocaml.html#n13">Complex and unbounded arrays</a> -<li><a href="Ocaml.html#n14">Using an object</a> -<li><a href="Ocaml.html#n15">Example typemap for a function taking float * and int</a> +<li><a href="Ocaml.html#Ocaml_nn12">Simple types of bounded arrays</a> +<li><a href="Ocaml.html#Ocaml_nn13">Complex and unbounded arrays</a> +<li><a href="Ocaml.html#Ocaml_nn14">Using an object</a> +<li><a href="Ocaml.html#Ocaml_nn15">Example typemap for a function taking float * and int</a> </ul> -<li><a href="Ocaml.html#n16">C++ Classes</a> +<li><a href="Ocaml.html#Ocaml_nn16">C++ Classes</a> <ul> -<li><a href="Ocaml.html#n17">STL vector and string Example</a> -<li><a href="Ocaml.html#n18">C++ Class Example</a> -<li><a href="Ocaml.html#n19">Compiling the example</a> -<li><a href="Ocaml.html#n20">Sample Session</a> +<li><a href="Ocaml.html#Ocaml_nn17">STL vector and string Example</a> +<li><a href="Ocaml.html#Ocaml_nn18">C++ Class Example</a> +<li><a href="Ocaml.html#Ocaml_nn19">Compiling the example</a> +<li><a href="Ocaml.html#Ocaml_nn20">Sample Session</a> </ul> -<li><a href="Ocaml.html#n21">Director Classes</a> +<li><a href="Ocaml.html#Ocaml_nn21">Director Classes</a> <ul> -<li><a href="Ocaml.html#n22">Director Introduction</a> -<li><a href="Ocaml.html#n23">Overriding Methods in Ocaml</a> -<li><a href="Ocaml.html#n24">Director Usage Example</a> -<li><a href="Ocaml.html#n25">Creating director objects</a> -<li><a href="Ocaml.html#n26">Typemaps for directors, <tt>directorin, directorout, directorargout</tt></a> -<li><a href="Ocaml.html#n27"><tt>directorin</tt> typemap</a> -<li><a href="Ocaml.html#n28"><tt>directorout</tt> typemap</a> -<li><a href="Ocaml.html#n29"><tt>directorargout</tt> typemap</a> +<li><a href="Ocaml.html#Ocaml_nn22">Director Introduction</a> +<li><a href="Ocaml.html#Ocaml_nn23">Overriding Methods in Ocaml</a> +<li><a href="Ocaml.html#Ocaml_nn24">Director Usage Example</a> +<li><a href="Ocaml.html#Ocaml_nn25">Creating director objects</a> +<li><a href="Ocaml.html#Ocaml_nn26">Typemaps for directors, <tt>directorin, directorout, directorargout</tt></a> +<li><a href="Ocaml.html#Ocaml_nn27"><tt>directorin</tt> typemap</a> +<li><a href="Ocaml.html#Ocaml_nn28"><tt>directorout</tt> typemap</a> +<li><a href="Ocaml.html#Ocaml_nn29"><tt>directorargout</tt> typemap</a> </ul> -<li><a href="Ocaml.html#n30">Exceptions</a> +<li><a href="Ocaml.html#Ocaml_nn30">Exceptions</a> </ul> </ul> <!-- INDEX --> -<h3><a href="Perl5.html">20 SWIG and Perl5</a></h3> +<h3><a href="Perl5.html#Perl5">22 SWIG and Perl5</a></h3> <!-- INDEX --> <ul> -<li><a href="Perl5.html#n2">Overview</a> -<li><a href="Perl5.html#n3">Preliminaries</a> +<li><a href="Perl5.html#Perl5_nn2">Overview</a> +<li><a href="Perl5.html#Perl5_nn3">Preliminaries</a> <ul> -<li><a href="Perl5.html#n4">Getting the right header files</a> -<li><a href="Perl5.html#n5">Compiling a dynamic module</a> -<li><a href="Perl5.html#n6">Building a dynamic module with MakeMaker</a> -<li><a href="Perl5.html#n7">Building a static version of Perl</a> -<li><a href="Perl5.html#n8">Using the module</a> -<li><a href="Perl5.html#n9">Compilation problems and compiling with C++</a> -<li><a href="Perl5.html#n10">Compiling for 64-bit platforms</a> +<li><a href="Perl5.html#Perl5_nn4">Getting the right header files</a> +<li><a href="Perl5.html#Perl5_nn5">Compiling a dynamic module</a> +<li><a href="Perl5.html#Perl5_nn6">Building a dynamic module with MakeMaker</a> +<li><a href="Perl5.html#Perl5_nn7">Building a static version of Perl</a> +<li><a href="Perl5.html#Perl5_nn8">Using the module</a> +<li><a href="Perl5.html#Perl5_nn9">Compilation problems and compiling with C++</a> +<li><a href="Perl5.html#Perl5_nn10">Compiling for 64-bit platforms</a> </ul> -<li><a href="Perl5.html#n11">Building Perl Extensions under Windows</a> +<li><a href="Perl5.html#Perl5_nn11">Building Perl Extensions under Windows</a> <ul> -<li><a href="Perl5.html#n12">Running SWIG from Developer Studio</a> -<li><a href="Perl5.html#n13">Using other compilers</a> +<li><a href="Perl5.html#Perl5_nn12">Running SWIG from Developer Studio</a> +<li><a href="Perl5.html#Perl5_nn13">Using other compilers</a> </ul> -<li><a href="Perl5.html#n14">The low-level interface</a> +<li><a href="Perl5.html#Perl5_nn14">The low-level interface</a> <ul> -<li><a href="Perl5.html#n15">Functions</a> -<li><a href="Perl5.html#n16">Global variables</a> -<li><a href="Perl5.html#n17">Constants</a> -<li><a href="Perl5.html#n18">Pointers</a> -<li><a href="Perl5.html#n19">Structures</a> -<li><a href="Perl5.html#n20">C++ classes</a> -<li><a href="Perl5.html#n21">C++ classes and type-checking</a> -<li><a href="Perl5.html#n22">C++ overloaded functions</a> -<li><a href="Perl5.html#n23">Operators</a> -<li><a href="Perl5.html#n24">Modules and packages</a> +<li><a href="Perl5.html#Perl5_nn15">Functions</a> +<li><a href="Perl5.html#Perl5_nn16">Global variables</a> +<li><a href="Perl5.html#Perl5_nn17">Constants</a> +<li><a href="Perl5.html#Perl5_nn18">Pointers</a> +<li><a href="Perl5.html#Perl5_nn19">Structures</a> +<li><a href="Perl5.html#Perl5_nn20">C++ classes</a> +<li><a href="Perl5.html#Perl5_nn21">C++ classes and type-checking</a> +<li><a href="Perl5.html#Perl5_nn22">C++ overloaded functions</a> +<li><a href="Perl5.html#Perl5_nn23">Operators</a> +<li><a href="Perl5.html#Perl5_nn24">Modules and packages</a> </ul> -<li><a href="Perl5.html#n25">Input and output parameters</a> -<li><a href="Perl5.html#n26">Exception handling </a> -<li><a href="Perl5.html#n27">Remapping datatypes with typemaps</a> +<li><a href="Perl5.html#Perl5_nn25">Input and output parameters</a> +<li><a href="Perl5.html#Perl5_nn26">Exception handling </a> +<li><a href="Perl5.html#Perl5_nn27">Remapping datatypes with typemaps</a> <ul> -<li><a href="Perl5.html#n28">A simple typemap example</a> -<li><a href="Perl5.html#n29">Perl5 typemaps</a> -<li><a href="Perl5.html#n30">Typemap variables</a> -<li><a href="Perl5.html#n31">Useful functions</a> +<li><a href="Perl5.html#Perl5_nn28">A simple typemap example</a> +<li><a href="Perl5.html#Perl5_nn29">Perl5 typemaps</a> +<li><a href="Perl5.html#Perl5_nn30">Typemap variables</a> +<li><a href="Perl5.html#Perl5_nn31">Useful functions</a> </ul> -<li><a href="Perl5.html#n32">Typemap Examples</a> +<li><a href="Perl5.html#Perl5_nn32">Typemap Examples</a> <ul> -<li><a href="Perl5.html#n33">Converting a Perl5 array to a char ** </a> -<li><a href="Perl5.html#n34">Return values </a> -<li><a href="Perl5.html#n35">Returning values from arguments</a> -<li><a href="Perl5.html#n36">Accessing array structure members</a> -<li><a href="Perl5.html#n37">Turning Perl references into C pointers</a> -<li><a href="Perl5.html#n38">Pointer handling</a> +<li><a href="Perl5.html#Perl5_nn33">Converting a Perl5 array to a char ** </a> +<li><a href="Perl5.html#Perl5_nn34">Return values </a> +<li><a href="Perl5.html#Perl5_nn35">Returning values from arguments</a> +<li><a href="Perl5.html#Perl5_nn36">Accessing array structure members</a> +<li><a href="Perl5.html#Perl5_nn37">Turning Perl references into C pointers</a> +<li><a href="Perl5.html#Perl5_nn38">Pointer handling</a> </ul> -<li><a href="Perl5.html#n39">Proxy classes</a> +<li><a href="Perl5.html#Perl5_nn39">Proxy classes</a> <ul> -<li><a href="Perl5.html#n40">Preliminaries</a> -<li><a href="Perl5.html#n41">Object Ownership</a> -<li><a href="Perl5.html#n42">Nested Objects</a> -<li><a href="Perl5.html#n43">Shadow Functions</a> -<li><a href="Perl5.html#n44">Inheritance</a> +<li><a href="Perl5.html#Perl5_nn40">Preliminaries</a> +<li><a href="Perl5.html#Perl5_nn41">Structure and class wrappers</a> +<li><a href="Perl5.html#Perl5_nn42">Object Ownership</a> +<li><a href="Perl5.html#Perl5_nn43">Nested Objects</a> +<li><a href="Perl5.html#Perl5_nn44">Shadow Functions</a> +<li><a href="Perl5.html#Perl5_nn45">Inheritance</a> </ul> </ul> <!-- INDEX --> -<h3><a href="Php.html">21 SWIG and PHP4</a></h3> +<h3><a href="Php.html#Php">23 SWIG and PHP4</a></h3> <!-- INDEX --> <ul> -<li><a href="Php.html#n2">Preliminaries</a> -<li><a href="Php.html#n3">Building PHP4 Extensions</a> +<li><a href="Php.html#Php_nn2">Preliminaries</a> +<li><a href="Php.html#Php_nn3">Building PHP4 Extensions</a> <ul> -<li><a href="Php.html#n4">Building a loadable extension</a> -<li><a href="Php.html#n5">Basic PHP4 interface</a> -<li><a href="Php.html#n6">Functions</a> -<li><a href="Php.html#n7">Global Variables</a> -<li><a href="Php.html#n8">Pointers </a> -<li><a href="Php.html#n9">Structures and C++ classes</a> -<li><a href="Php.html#n10">Constants</a> -<li><a href="Php.html#n11">Shadow classes</a> -<li><a href="Php.html#n12">Constructors and Destructers</a> -<li><a href="Php.html#n13">Static Member Variables</a> -<li><a href="Php.html#n14">PHP4 Pragmas</a> -<li><a href="Php.html#n15">Building extensions into php</a> -<li><a href="Php.html#n16">To be furthered...</a> +<li><a href="Php.html#Php_nn4">Building a loadable extension</a> +<li><a href="Php.html#Php_nn5">Basic PHP4 interface</a> +<li><a href="Php.html#Php_nn6">Functions</a> +<li><a href="Php.html#Php_nn7">Global Variables</a> +<li><a href="Php.html#Php_nn8">Pointers </a> +<li><a href="Php.html#Php_nn9">Structures and C++ classes</a> +<li><a href="Php.html#Php_nn10">Constants</a> +<li><a href="Php.html#Php_nn11">Shadow classes</a> +<li><a href="Php.html#Php_nn12">Constructors and Destructers</a> +<li><a href="Php.html#Php_nn13">Static Member Variables</a> +<li><a href="Php.html#Php_nn14">PHP4 Pragmas</a> +<li><a href="Php.html#Php_nn15">Building extensions into php</a> +<li><a href="Php.html#Php_nn16">To be furthered...</a> </ul> </ul> <!-- INDEX --> -<h3><a href="Python.html">22 SWIG and Python</a></h3> +<h3><a href="Pike.html#Pike">24 SWIG and Pike</a></h3> <!-- INDEX --> <ul> -<li><a href="Python.html#n2">Overview</a> -<li><a href="Python.html#n3">Preliminaries</a> -<ul> -<li><a href="Python.html#n4">Running SWIG</a> -<li><a href="Python.html#n5">Getting the right header files</a> -<li><a href="Python.html#n6">Compiling a dynamic module</a> -<li><a href="Python.html#n7">Using distutils</a> -<li><a href="Python.html#n8">Static linking</a> -<li><a href="Python.html#n9">Using your module</a> -<li><a href="Python.html#n10">Compilation of C++ extensions</a> -<li><a href="Python.html#n11">Compiling for 64-bit platforms</a> -<li><a href="Python.html#n12">Building Python Extensions under Windows</a> -</ul> -<li><a href="Python.html#n13">A tour of basic C/C++ wrapping</a> -<ul> -<li><a href="Python.html#n14">Modules</a> -<li><a href="Python.html#n15">Functions</a> -<li><a href="Python.html#n16">Global variables</a> -<li><a href="Python.html#n17">Constants and enums</a> -<li><a href="Python.html#n18">Pointers</a> -<li><a href="Python.html#n19">Structures</a> -<li><a href="Python.html#n20">C++ classes</a> -<li><a href="Python.html#n21">C++ inheritance</a> -<li><a href="Python.html#n22">Pointers, references, values, and arrays</a> -<li><a href="Python.html#n23">C++ overloaded functions</a> -<li><a href="Python.html#n24">C++ operators</a> -<li><a href="Python.html#n25">C++ namespaces</a> -<li><a href="Python.html#n26">C++ templates</a> -<li><a href="Python.html#n27">C++ Smart Pointers</a> -</ul> -<li><a href="Python.html#n28">Further details on the Python class interface</a> -<ul> -<li><a href="Python.html#n29">Proxy classes</a> -<li><a href="Python.html#n30">Memory management</a> -<li><a href="Python.html#n31">Python 2.2 and classic classes</a> -</ul> -<li><a href="Python.html#n32">Cross language polymorphism (experimental)</a> -<ul> -<li><a href="Python.html#n33">Enabling directors</a> -<li><a href="Python.html#n34">Director classes</a> -<li><a href="Python.html#n35">Ownership and object destruction</a> -<li><a href="Python.html#n36">Exception unrolling</a> -<li><a href="Python.html#n37">Overhead and code bloat</a> -<li><a href="Python.html#n38">Typemaps</a> -<li><a href="Python.html#n39">Miscellaneous</a> -</ul> -<li><a href="Python.html#n40">Common customization features</a> -<ul> -<li><a href="Python.html#n41">C/C++ helper functions</a> -<li><a href="Python.html#n42">Adding additional Python code</a> -<li><a href="Python.html#n43">Class extension with %extend</a> -<li><a href="Python.html#n44">Exception handling with %exception</a> -</ul> -<li><a href="Python.html#n45">Tips and techniques</a> -<ul> -<li><a href="Python.html#n46">Input and output parameters</a> -<li><a href="Python.html#n47">Simple pointers</a> -<li><a href="Python.html#n48">Unbounded C Arrays</a> -<li><a href="Python.html#n49">String handling</a> -<li><a href="Python.html#n50">Arrays</a> -<li><a href="Python.html#n51">String arrays</a> -<li><a href="Python.html#n52">STL wrappers</a> -</ul> -<li><a href="Python.html#n53">Typemaps</a> -<ul> -<li><a href="Python.html#n54">What is a typemap?</a> -<li><a href="Python.html#n55">Python typemaps</a> -<li><a href="Python.html#n56">Typemap variables</a> -<li><a href="Python.html#n57">Useful Python Functions</a> -</ul> -<li><a href="Python.html#n58">Typemap Examples</a> -<ul> -<li><a href="Python.html#n59">Converting Python list to a char ** </a> -<li><a href="Python.html#n60">Expanding a Python object into multiple arguments</a> -<li><a href="Python.html#n61">Using typemaps to return arguments</a> -<li><a href="Python.html#n62">Mapping Python tuples into small arrays</a> -<li><a href="Python.html#n63">Mapping sequences to C arrays</a> -<li><a href="Python.html#n64">Pointer handling</a> +<li><a href="Pike.html#Pike_nn2">Preliminaries</a> +<ul> +<li><a href="Pike.html#Pike_nn3">Running SWIG</a> +<li><a href="Pike.html#Pike_nn4">Getting the right header files</a> +<li><a href="Pike.html#Pike_nn5">Using your module</a> +</ul> +<li><a href="Pike.html#Pike_nn6">Basic C/C++ Mapping</a> +<ul> +<li><a href="Pike.html#Pike_nn7">Modules</a> +<li><a href="Pike.html#Pike_nn8">Functions</a> +<li><a href="Pike.html#Pike_nn9">Global variables</a> +<li><a href="Pike.html#Pike_nn10">Constants and enumerated types</a> +<li><a href="Pike.html#Pike_nn11">Constructors and Destructors</a> +<li><a href="Pike.html#Pike_nn12">Static Members</a> </ul> </ul> <!-- INDEX --> -<h3><a href="Ruby.html">23 SWIG and Ruby</a></h3> +<h3><a href="Python.html#Python">25 SWIG and Python</a></h3> <!-- INDEX --> <ul> -<li><a href="Ruby.html#n2">Preliminaries</a> +<li><a href="Python.html#Python_nn2">Overview</a> +<li><a href="Python.html#Python_nn3">Preliminaries</a> +<ul> +<li><a href="Python.html#Python_nn4">Running SWIG</a> +<li><a href="Python.html#Python_nn5">Getting the right header files</a> +<li><a href="Python.html#Python_nn6">Compiling a dynamic module</a> +<li><a href="Python.html#Python_nn7">Using distutils</a> +<li><a href="Python.html#Python_nn8">Static linking</a> +<li><a href="Python.html#Python_nn9">Using your module</a> +<li><a href="Python.html#Python_nn10">Compilation of C++ extensions</a> +<li><a href="Python.html#Python_nn11">Compiling for 64-bit platforms</a> +<li><a href="Python.html#Python_nn12">Building Python Extensions under Windows</a> +</ul> +<li><a href="Python.html#Python_nn13">A tour of basic C/C++ wrapping</a> +<ul> +<li><a href="Python.html#Python_nn14">Modules</a> +<li><a href="Python.html#Python_nn15">Functions</a> +<li><a href="Python.html#Python_nn16">Global variables</a> +<li><a href="Python.html#Python_nn17">Constants and enums</a> +<li><a href="Python.html#Python_nn18">Pointers</a> +<li><a href="Python.html#Python_nn19">Structures</a> +<li><a href="Python.html#Python_nn20">C++ classes</a> +<li><a href="Python.html#Python_nn21">C++ inheritance</a> +<li><a href="Python.html#Python_nn22">Pointers, references, values, and arrays</a> +<li><a href="Python.html#Python_nn23">C++ overloaded functions</a> +<li><a href="Python.html#Python_nn24">C++ operators</a> +<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_nn28">Further details on the Python class interface</a> +<ul> +<li><a href="Python.html#Python_nn29">Proxy classes</a> +<li><a href="Python.html#Python_nn30">Memory management</a> +<li><a href="Python.html#Python_nn31">Python 2.2 and classic classes</a> +</ul> +<li><a href="Python.html#directors">Cross language polymorphism (experimental)</a> +<ul> +<li><a href="Python.html#Python_nn33">Enabling directors</a> +<li><a href="Python.html#Python_nn34">Director classes</a> +<li><a href="Python.html#Python_nn35">Ownership and object destruction</a> +<li><a href="Python.html#Python_nn36">Exception unrolling</a> +<li><a href="Python.html#Python_nn37">Overhead and code bloat</a> +<li><a href="Python.html#Python_nn38">Typemaps</a> +<li><a href="Python.html#Python_nn39">Miscellaneous</a> +</ul> +<li><a href="Python.html#Python_nn40">Common customization features</a> +<ul> +<li><a href="Python.html#Python_nn41">C/C++ helper functions</a> +<li><a href="Python.html#Python_nn42">Adding additional Python code</a> +<li><a href="Python.html#Python_nn43">Class extension with %extend</a> +<li><a href="Python.html#Python_nn44">Exception handling with %exception</a> +</ul> +<li><a href="Python.html#Python_nn45">Tips and techniques</a> +<ul> +<li><a href="Python.html#Python_nn46">Input and output parameters</a> +<li><a href="Python.html#Python_nn47">Simple pointers</a> +<li><a href="Python.html#Python_nn48">Unbounded C Arrays</a> +<li><a href="Python.html#Python_nn49">String handling</a> +<li><a href="Python.html#Python_nn50">Arrays</a> +<li><a href="Python.html#Python_nn51">String arrays</a> +<li><a href="Python.html#Python_nn52">STL wrappers</a> +</ul> +<li><a href="Python.html#Python_nn53">Typemaps</a> +<ul> +<li><a href="Python.html#Python_nn54">What is a typemap?</a> +<li><a href="Python.html#Python_nn55">Python typemaps</a> +<li><a href="Python.html#Python_nn56">Typemap variables</a> +<li><a href="Python.html#Python_nn57">Useful Python Functions</a> +</ul> +<li><a href="Python.html#Python_nn58">Typemap Examples</a> +<ul> +<li><a href="Python.html#Python_nn59">Converting Python list to a char ** </a> +<li><a href="Python.html#Python_nn60">Expanding a Python object into multiple arguments</a> +<li><a href="Python.html#Python_nn61">Using typemaps to return arguments</a> +<li><a href="Python.html#Python_nn62">Mapping Python tuples into small arrays</a> +<li><a href="Python.html#Python_nn63">Mapping sequences to C arrays</a> +<li><a href="Python.html#Python_nn64">Pointer handling</a> +</ul> +</ul> +<!-- INDEX --> + +<h3><a href="Ruby.html#Ruby">26 SWIG and Ruby</a></h3> + +<!-- INDEX --> <ul> -<li><a href="Ruby.html#n3">Running SWIG</a> -<li><a href="Ruby.html#n4">Getting the right header files</a> -<li><a href="Ruby.html#n5">Compiling a dynamic module</a> -<li><a href="Ruby.html#n6">Using your module</a> -<li><a href="Ruby.html#n7">Static linking</a> -<li><a href="Ruby.html#n8">Compilation of C++ extensions</a> +<li><a href="Ruby.html#Ruby_nn2">Preliminaries</a> +<ul> +<li><a href="Ruby.html#Ruby_nn3">Running SWIG</a> +<li><a href="Ruby.html#Ruby_nn4">Getting the right header files</a> +<li><a href="Ruby.html#Ruby_nn5">Compiling a dynamic module</a> +<li><a href="Ruby.html#Ruby_nn6">Using your module</a> +<li><a href="Ruby.html#Ruby_nn7">Static linking</a> +<li><a href="Ruby.html#Ruby_nn8">Compilation of C++ extensions</a> </ul> -<li><a href="Ruby.html#n9">Building Ruby Extensions under Windows 95/NT</a> +<li><a href="Ruby.html#Ruby_nn9">Building Ruby Extensions under Windows 95/NT</a> <ul> -<li><a href="Ruby.html#n10">Running SWIG from Developer Studio</a> +<li><a href="Ruby.html#Ruby_nn10">Running SWIG from Developer Studio</a> </ul> -<li><a href="Ruby.html#n11">The Ruby-to-C/C++ Mapping</a> +<li><a href="Ruby.html#Ruby_nn11">The Ruby-to-C/C++ Mapping</a> <ul> -<li><a href="Ruby.html#n12">Modules</a> -<li><a href="Ruby.html#n13">Functions</a> -<li><a href="Ruby.html#n14">Variable Linking</a> -<li><a href="Ruby.html#n15">Constants</a> -<li><a href="Ruby.html#n16">Pointers</a> -<li><a href="Ruby.html#n17">Structures</a> -<li><a href="Ruby.html#n18">C++ classes</a> -<li><a href="Ruby.html#n19">C++ Inheritance</a> -<li><a href="Ruby.html#n20">C++ Overloaded Functions</a> -<li><a href="Ruby.html#n21">C++ Operators</a> -<li><a href="Ruby.html#n22">C++ namespaces</a> -<li><a href="Ruby.html#n23">C++ templates</a> -<li><a href="Ruby.html#n24">C++ Smart Pointers</a> -<li><a href="Ruby.html#n25">Cross-Language Polymorphism</a> +<li><a href="Ruby.html#Ruby_nn12">Modules</a> +<li><a href="Ruby.html#Ruby_nn13">Functions</a> +<li><a href="Ruby.html#Ruby_nn14">Variable Linking</a> +<li><a href="Ruby.html#Ruby_nn15">Constants</a> +<li><a href="Ruby.html#Ruby_nn16">Pointers</a> +<li><a href="Ruby.html#Ruby_nn17">Structures</a> +<li><a href="Ruby.html#Ruby_nn18">C++ classes</a> +<li><a href="Ruby.html#Ruby_nn19">C++ Inheritance</a> +<li><a href="Ruby.html#Ruby_nn20">C++ Overloaded Functions</a> +<li><a href="Ruby.html#Ruby_nn21">C++ Operators</a> +<li><a href="Ruby.html#Ruby_nn22">C++ namespaces</a> +<li><a href="Ruby.html#Ruby_nn23">C++ templates</a> +<li><a href="Ruby.html#ruby_cpp_smart_pointers">C++ Smart Pointers</a> +<li><a href="Ruby.html#Ruby_nn25">Cross-Language Polymorphism</a> <ul> -<li><a href="Ruby.html#n26">Exception Unrolling</a> +<li><a href="Ruby.html#Ruby_nn26">Exception Unrolling</a> </ul> </ul> -<li><a href="Ruby.html#n27">Input and output parameters</a> -<li><a href="Ruby.html#n28">Simple exception handling </a> -<li><a href="Ruby.html#n29">Typemaps</a> +<li><a href="Ruby.html#Ruby_nn27">Input and output parameters</a> +<li><a href="Ruby.html#Ruby_nn28">Simple exception handling </a> +<li><a href="Ruby.html#Ruby_nn29">Typemaps</a> <ul> -<li><a href="Ruby.html#n30">What is a typemap?</a> -<li><a href="Ruby.html#n31">Ruby typemaps</a> -<li><a href="Ruby.html#n32">Typemap variables</a> -<li><a href="Ruby.html#n33">Useful Functions</a> +<li><a href="Ruby.html#Ruby_nn30">What is a typemap?</a> +<li><a href="Ruby.html#Ruby_nn31">Ruby typemaps</a> +<li><a href="Ruby.html#Ruby_nn32">Typemap variables</a> +<li><a href="Ruby.html#Ruby_nn33">Useful Functions</a> <ul> -<li><a href="Ruby.html#n34">C Datatypes to Ruby Objects</a> -<li><a href="Ruby.html#n35">Ruby Objects to C Datatypes</a> -<li><a href="Ruby.html#n36">Macros for VALUE</a> -<li><a href="Ruby.html#n37">Exceptions</a> -<li><a href="Ruby.html#n38">Iterators</a> +<li><a href="Ruby.html#Ruby_nn34">C Datatypes to Ruby Objects</a> +<li><a href="Ruby.html#Ruby_nn35">Ruby Objects to C Datatypes</a> +<li><a href="Ruby.html#Ruby_nn36">Macros for VALUE</a> +<li><a href="Ruby.html#Ruby_nn37">Exceptions</a> +<li><a href="Ruby.html#Ruby_nn38">Iterators</a> </ul> -<li><a href="Ruby.html#n39">Typemap Examples</a> -<li><a href="Ruby.html#n40">Converting a Ruby array to a char **</a> -<li><a href="Ruby.html#n41">Collecting arguments in a hash</a> -<li><a href="Ruby.html#n42">Pointer handling</a> +<li><a href="Ruby.html#ruby_typemap_examples">Typemap Examples</a> +<li><a href="Ruby.html#Ruby_nn40">Converting a Ruby array to a char **</a> +<li><a href="Ruby.html#Ruby_nn41">Collecting arguments in a hash</a> +<li><a href="Ruby.html#Ruby_nn42">Pointer handling</a> <ul> -<li><a href="Ruby.html#n43">Ruby Datatype Wrapping</a> +<li><a href="Ruby.html#Ruby_nn43">Ruby Datatype Wrapping</a> </ul> </ul> -<li><a href="Ruby.html#n44">Operator overloading</a> +<li><a href="Ruby.html#ruby_operator_overloading">Operator overloading</a> <ul> -<li><a href="Ruby.html#n45">Example: STL Vector to Ruby Array</a> +<li><a href="Ruby.html#Ruby_nn45">Example: STL Vector to Ruby Array</a> </ul> -<li><a href="Ruby.html#n46">Advanced Topics</a> +<li><a href="Ruby.html#Ruby_nn46">Advanced Topics</a> <ul> -<li><a href="Ruby.html#n47">Creating Multi-Module Packages</a> -<li><a href="Ruby.html#n48">Defining Aliases</a> -<li><a href="Ruby.html#n49">Predicate Methods</a> -<li><a href="Ruby.html#n50">Specifying Mixin Modules</a> -<li><a href="Ruby.html#n51">Interacting with Ruby's Garbage Collector</a> +<li><a href="Ruby.html#Ruby_nn47">Creating Multi-Module Packages</a> +<li><a href="Ruby.html#Ruby_nn48">Defining Aliases</a> +<li><a href="Ruby.html#Ruby_nn49">Predicate Methods</a> +<li><a href="Ruby.html#Ruby_nn50">Specifying Mixin Modules</a> +<li><a href="Ruby.html#Ruby_nn51">Interacting with Ruby's Garbage Collector</a> </ul> </ul> <!-- INDEX --> -<h3><a href="Tcl.html">24 SWIG and Tcl</a></h3> +<h3><a href="Tcl.html#Tcl">27 SWIG and Tcl</a></h3> <!-- INDEX --> <ul> -<li><a href="Tcl.html#n2">Preliminaries</a> +<li><a href="Tcl.html#Tcl_nn2">Preliminaries</a> <ul> -<li><a href="Tcl.html#n3">Getting the right header files</a> -<li><a href="Tcl.html#n4">Compiling a dynamic module</a> -<li><a href="Tcl.html#n5">Static linking</a> -<li><a href="Tcl.html#n6">Using your module</a> -<li><a href="Tcl.html#n7">Compilation of C++ extensions</a> -<li><a href="Tcl.html#n8">Compiling for 64-bit platforms</a> -<li><a href="Tcl.html#n9">Setting a package prefix</a> -<li><a href="Tcl.html#n10">Using namespaces</a> +<li><a href="Tcl.html#Tcl_nn3">Getting the right header files</a> +<li><a href="Tcl.html#Tcl_nn4">Compiling a dynamic module</a> +<li><a href="Tcl.html#Tcl_nn5">Static linking</a> +<li><a href="Tcl.html#Tcl_nn6">Using your module</a> +<li><a href="Tcl.html#Tcl_nn7">Compilation of C++ extensions</a> +<li><a href="Tcl.html#Tcl_nn8">Compiling for 64-bit platforms</a> +<li><a href="Tcl.html#Tcl_nn9">Setting a package prefix</a> +<li><a href="Tcl.html#Tcl_nn10">Using namespaces</a> </ul> -<li><a href="Tcl.html#n11">Building Tcl/Tk Extensions under Windows 95/NT</a> +<li><a href="Tcl.html#Tcl_nn11">Building Tcl/Tk Extensions under Windows 95/NT</a> <ul> -<li><a href="Tcl.html#n12">Running SWIG from Developer Studio</a> -<li><a href="Tcl.html#n13">Using NMAKE</a> +<li><a href="Tcl.html#Tcl_nn12">Running SWIG from Developer Studio</a> +<li><a href="Tcl.html#Tcl_nn13">Using NMAKE</a> </ul> -<li><a href="Tcl.html#n14">A tour of basic C/C++ wrapping</a> +<li><a href="Tcl.html#Tcl_nn14">A tour of basic C/C++ wrapping</a> <ul> -<li><a href="Tcl.html#n15">Modules</a> -<li><a href="Tcl.html#n16">Functions</a> -<li><a href="Tcl.html#n17">Global variables</a> -<li><a href="Tcl.html#n18">Constants and enums</a> -<li><a href="Tcl.html#n19">Pointers</a> -<li><a href="Tcl.html#n20">Structures</a> -<li><a href="Tcl.html#n21">C++ classes</a> -<li><a href="Tcl.html#n22">C++ inheritance</a> -<li><a href="Tcl.html#n23">Pointers, references, values, and arrays</a> -<li><a href="Tcl.html#n24">C++ overloaded functions</a> -<li><a href="Tcl.html#n25">C++ operators</a> -<li><a href="Tcl.html#n26">C++ namespaces</a> -<li><a href="Tcl.html#n27">C++ templates</a> -<li><a href="Tcl.html#n28">C++ Smart Pointers</a> +<li><a href="Tcl.html#Tcl_nn15">Modules</a> +<li><a href="Tcl.html#Tcl_nn16">Functions</a> +<li><a href="Tcl.html#Tcl_nn17">Global variables</a> +<li><a href="Tcl.html#Tcl_nn18">Constants and enums</a> +<li><a href="Tcl.html#Tcl_nn19">Pointers</a> +<li><a href="Tcl.html#Tcl_nn20">Structures</a> +<li><a href="Tcl.html#Tcl_nn21">C++ classes</a> +<li><a href="Tcl.html#Tcl_nn22">C++ inheritance</a> +<li><a href="Tcl.html#Tcl_nn23">Pointers, references, values, and arrays</a> +<li><a href="Tcl.html#Tcl_nn24">C++ overloaded functions</a> +<li><a href="Tcl.html#Tcl_nn25">C++ operators</a> +<li><a href="Tcl.html#Tcl_nn26">C++ namespaces</a> +<li><a href="Tcl.html#Tcl_nn27">C++ templates</a> +<li><a href="Tcl.html#Tcl_nn28">C++ Smart Pointers</a> </ul> -<li><a href="Tcl.html#n29">Further details on the Tcl class interface</a> +<li><a href="Tcl.html#Tcl_nn29">Further details on the Tcl class interface</a> <ul> -<li><a href="Tcl.html#n30">Proxy classes</a> -<li><a href="Tcl.html#n31">Memory management</a> +<li><a href="Tcl.html#Tcl_nn30">Proxy classes</a> +<li><a href="Tcl.html#Tcl_nn31">Memory management</a> </ul> -<li><a href="Tcl.html#n32">Input and output parameters</a> -<li><a href="Tcl.html#n33">Exception handling </a> -<li><a href="Tcl.html#n34">Typemaps</a> +<li><a href="Tcl.html#Tcl_nn32">Input and output parameters</a> +<li><a href="Tcl.html#Tcl_nn33">Exception handling </a> +<li><a href="Tcl.html#Tcl_nn34">Typemaps</a> <ul> -<li><a href="Tcl.html#n35">What is a typemap?</a> -<li><a href="Tcl.html#n36">Tcl typemaps</a> -<li><a href="Tcl.html#n37">Typemap variables</a> -<li><a href="Tcl.html#n38">Converting a Tcl list to a char ** </a> -<li><a href="Tcl.html#n39">Returning values in arguments</a> -<li><a href="Tcl.html#n40">Useful functions</a> -<li><a href="Tcl.html#n41">Standard typemaps</a> -<li><a href="Tcl.html#n42">Pointer handling</a> +<li><a href="Tcl.html#Tcl_nn35">What is a typemap?</a> +<li><a href="Tcl.html#Tcl_nn36">Tcl typemaps</a> +<li><a href="Tcl.html#Tcl_nn37">Typemap variables</a> +<li><a href="Tcl.html#Tcl_nn38">Converting a Tcl list to a char ** </a> +<li><a href="Tcl.html#Tcl_nn39">Returning values in arguments</a> +<li><a href="Tcl.html#Tcl_nn40">Useful functions</a> +<li><a href="Tcl.html#Tcl_nn41">Standard typemaps</a> +<li><a href="Tcl.html#Tcl_nn42">Pointer handling</a> </ul> -<li><a href="Tcl.html#n43">Turning a SWIG module into a Tcl Package.</a> -<li><a href="Tcl.html#n44">Building new kinds of Tcl interfaces (in Tcl)</a> +<li><a href="Tcl.html#Tcl_nn43">Turning a SWIG module into a Tcl Package.</a> +<li><a href="Tcl.html#Tcl_nn44">Building new kinds of Tcl interfaces (in Tcl)</a> <ul> -<li><a href="Tcl.html#n45">Shadow classes</a> +<li><a href="Tcl.html#Tcl_nn45">Shadow classes</a> </ul> </ul> <!-- INDEX --> -<h3><a href="Chicken.html">25 SWIG and Chicken</a></h3> +<h3><a href="Extending.html#Extending">28 Extending SWIG</a></h3> <!-- INDEX --> <ul> -<li><a href="Chicken.html#n2">Preliminaries</a> -<ul> -<li><a href="Chicken.html#n3">Running SWIG in C mode</a> -<li><a href="Chicken.html#n4">Running SWIG in C++ mode</a> -</ul> -<li><a href="Chicken.html#n5">Code Generation</a> -<ul> -<li><a href="Chicken.html#n6">Naming Conventions</a> -<li><a href="Chicken.html#n7">Modules and Prefixes</a> -<li><a href="Chicken.html#n8">Constants and Variables</a> -<li><a href="Chicken.html#n9">Functions</a> -</ul> -<li><a href="Chicken.html#n10">TinyCLOS</a> -<li><a href="Chicken.html#n11">Compilation</a> -<li><a href="Chicken.html#n12">Linkage</a> -<ul> -<li><a href="Chicken.html#n13">Shared library</a> -<li><a href="Chicken.html#n14">Static binary</a> -</ul> -<li><a href="Chicken.html#n15">Typemaps</a> -<li><a href="Chicken.html#n16">Pointers</a> -<li><a href="Chicken.html#n17">Unsupported features</a> +<li><a href="Extending.html#Extending_nn2">Introduction</a> +<li><a href="Extending.html#Extending_nn3">Prerequisites</a> +<li><a href="Extending.html#Extending_nn4">The Big Picture</a> +<li><a href="Extending.html#Extending_nn5">Execution Model</a> +<ul> +<li><a href="Extending.html#Extending_nn6">Preprocessing</a> +<li><a href="Extending.html#Extending_nn7">Parsing</a> +<li><a href="Extending.html#Extending_nn8">Parse Trees</a> +<li><a href="Extending.html#Extending_nn9">Attribute namespaces</a> +<li><a href="Extending.html#Extending_nn10">Symbol Tables</a> +<li><a href="Extending.html#Extending_nn11">The %feature directive</a> +<li><a href="Extending.html#Extending_nn12">Code Generation</a> +<li><a href="Extending.html#Extending_nn13">SWIG and XML</a> +</ul> +<li><a href="Extending.html#Extending_nn14">Primitive Data Structures</a> +<ul> +<li><a href="Extending.html#Extending_nn15">Strings</a> +<li><a href="Extending.html#Extending_nn16">Hashes</a> +<li><a href="Extending.html#Extending_nn17">Lists</a> +<li><a href="Extending.html#Extending_nn18">Common operations</a> +<li><a href="Extending.html#Extending_nn19">Iterating over Lists and Hashes</a> +<li><a href="Extending.html#Extending_nn20">I/O</a> +</ul> +<li><a href="Extending.html#Extending_nn21">Navigating and manipulating parse trees</a> +<li><a href="Extending.html#Extending_nn22">Working with attributes</a> +<li><a href="Extending.html#Extending_nn23">Type system</a> +<ul> +<li><a href="Extending.html#Extending_nn24">String encoding of types</a> +<li><a href="Extending.html#Extending_nn25">Type construction</a> +<li><a href="Extending.html#Extending_nn26">Type tests</a> +<li><a href="Extending.html#Extending_nn27">Typedef and inheritance</a> +<li><a href="Extending.html#Extending_nn28">Lvalues</a> +<li><a href="Extending.html#Extending_nn29">Output functions</a> +</ul> +<li><a href="Extending.html#Extending_nn30">Parameters</a> +<li><a href="Extending.html#Extending_nn31">Writing a Language Module</a> +<ul> +<li><a href="Extending.html#Extending_nn32">Execution model</a> +<li><a href="Extending.html#Extending_nn33">Starting out</a> +<li><a href="Extending.html#Extending_nn34">Command line options</a> +<li><a href="Extending.html#Extending_nn35">Configuration and preprocessing</a> +<li><a href="Extending.html#Extending_nn36">Entry point to code generation</a> +<li><a href="Extending.html#Extending_nn37">Module I/O and wrapper skeleton</a> +<li><a href="Extending.html#Extending_nn38">Low-level code generators</a> +<li><a href="Extending.html#Extending_nn39">Configuration files</a> +<li><a href="Extending.html#Extending_nn40">Runtime support</a> +<li><a href="Extending.html#Extending_nn41">Standard library files</a> +<li><a href="Extending.html#Extending_nn42">Examples and test cases</a> +<li><a href="Extending.html#Extending_nn43">Documentation</a> +</ul> +<li><a href="Extending.html#Extending_nn44">Typemaps</a> +<ul> +<li><a href="Extending.html#Extending_nn45">Proxy classes</a> +</ul> +<li><a href="Extending.html#Extending_nn46">Guide to parse tree nodes</a> </ul> <!-- INDEX --> -<h3><a href="Extending.html">26 Extending SWIG</a></h3> +<h3><a href="Advanced.html#Advanced">29 Advanced Topics</a></h3> <!-- INDEX --> <ul> -<li><a href="Extending.html#n2">Introduction</a> -<li><a href="Extending.html#n3">Prerequisites</a> -<li><a href="Extending.html#n4">The Big Picture</a> -<li><a href="Extending.html#n5">Execution Model</a> -<ul> -<li><a href="Extending.html#n6">Preprocessing</a> -<li><a href="Extending.html#n7">Parsing</a> -<li><a href="Extending.html#n8">Parse Trees</a> -<li><a href="Extending.html#n9">Attribute namespaces</a> -<li><a href="Extending.html#n10">Symbol Tables</a> -<li><a href="Extending.html#n11">The %feature directive</a> -<li><a href="Extending.html#n12">Code Generation</a> -<li><a href="Extending.html#n13">SWIG and XML</a> -</ul> -<li><a href="Extending.html#n14">Primitive Data Structures</a> -<ul> -<li><a href="Extending.html#n15">Strings</a> -<li><a href="Extending.html#n16">Hashes</a> -<li><a href="Extending.html#n17">Lists</a> -<li><a href="Extending.html#n18">Common operations</a> -<li><a href="Extending.html#n19">Iterating over Lists and Hashes</a> -<li><a href="Extending.html#n20">I/O</a> -</ul> -<li><a href="Extending.html#n21">Navigating and manipulating parse trees</a> -<li><a href="Extending.html#n22">Working with attributes</a> -<li><a href="Extending.html#n23">Type system</a> -<ul> -<li><a href="Extending.html#n24">String encoding of types</a> -<li><a href="Extending.html#n25">Type construction</a> -<li><a href="Extending.html#n26">Type tests</a> -<li><a href="Extending.html#n27">Typedef and inheritance</a> -<li><a href="Extending.html#n28">Lvalues</a> -<li><a href="Extending.html#n29">Output functions</a> -</ul> -<li><a href="Extending.html#n30">Parameters</a> -<li><a href="Extending.html#n31">Writing a Language Module</a> -<ul> -<li><a href="Extending.html#n32">Execution model</a> -<li><a href="Extending.html#n33">Starting out</a> -<li><a href="Extending.html#n34">Command line options</a> -<li><a href="Extending.html#n35">Configuration and preprocessing</a> -<li><a href="Extending.html#n36">Entry point to code generation</a> -<li><a href="Extending.html#n37">Module I/O and wrapper skeleton</a> -<li><a href="Extending.html#n38">Low-level code generators</a> -<li><a href="Extending.html#n39">Configuration files</a> -<li><a href="Extending.html#n40">Runtime support</a> -<li><a href="Extending.html#n41">Standard library files</a> -<li><a href="Extending.html#n42">Examples and test cases</a> -<li><a href="Extending.html#n43">Documentation</a> -</ul> -<li><a href="Extending.html#n44">Typemaps</a> -<ul> -<li><a href="Extending.html#n45">Proxy classes</a> -</ul> -<li><a href="Extending.html#n46">Guide to parse tree nodes</a> +<li><a href="Advanced.html#Advanced_nn2">Creating multi-module packages</a> +<ul> +<li><a href="Advanced.html#Advanced_nn3">Runtime support (and potential problems)</a> +<li><a href="Advanced.html#Advanced_nn4">Why doesn't C++ inheritance work between modules?</a> +<li><a href="Advanced.html#Advanced_nn5">The SWIG runtime library</a> +<li><a href="Advanced.html#Advanced_nn6">A few dynamic loading gotchas</a> +</ul> +<li><a href="Advanced.html#Advanced_nn7">Dynamic Loading of C++ modules</a> +<li><a href="Advanced.html#Advanced_nn8">Inside the SWIG type-checker</a> +<ul> +<li><a href="Advanced.html#Advanced_nn9">Type equivalence</a> +<li><a href="Advanced.html#Advanced_nn10">Type casting</a> +<li><a href="Advanced.html#Advanced_nn11">Why a name based approach?</a> +<li><a href="Advanced.html#Advanced_nn12">Performance of the type-checker</a> +</ul> </ul> <!-- INDEX --> diff --git a/Doc/Manual/Contract.html b/Doc/Manual/Contract.html index 8ecf98486..0001bf9fd 100644 --- a/Doc/Manual/Contract.html +++ b/Doc/Manual/Contract.html @@ -5,13 +5,13 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>10 Contracts</H1> +<H1><a name="Contract"></a>12 Contracts</H1> <!-- INDEX --> <ul> -<li><a href="#n2">The %contract directive</a> -<li><a href="#n3">%contract and classes</a> -<li><a href="#n4">Constant aggregation and %aggregate_check</a> -<li><a href="#n5">Notes</a> +<li><a href="#Contract_nn2">The %contract directive</a> +<li><a href="#Contract_nn3">%contract and classes</a> +<li><a href="#Contract_nn4">Constant aggregation and %aggregate_check</a> +<li><a href="#Contract_nn5">Notes</a> </ul> <!-- INDEX --> @@ -31,8 +31,9 @@ to a declaration. For example, you can easily attach argument checking rules, check the output values of a function and more. When one of the rules is violated by a script, a runtime exception is generated rather than having the program continue to execute. +</p> -<a name="n2"></a><H2>10.1 The %contract directive</H2> +<H2><a name="Contract_nn2"></a>12.1 The %contract directive</H2> Contracts are added to a declaration using the %contract directive. Here @@ -42,9 +43,9 @@ is a simple example: <pre> %contract sqrt(double x) { require: - x >= 0; + x >= 0; ensure: - sqrt >= 0; + sqrt >= 0; } ... @@ -65,24 +66,26 @@ cases, the conditions that must hold must be specified as boolean expressions. <p> In the above example, we're simply making sure that sqrt() returns a non-negative number (if it didn't, then it would be broken in some way). +</p> <p> Once a contract has been specified, it modifies the behavior of the resulting module. For example: +</p> <blockquote> <pre> ->>> example.sqrt(2) +>>> example.sqrt(2) 1.4142135623730951 ->>> example.sqrt(-2) +>>> example.sqrt(-2) Traceback (most recent call last): - File "<stdin>", line 1, in ? -RuntimeError: Contract violation: require: (arg1>=0) ->>> + File "<stdin>", line 1, in ? +RuntimeError: Contract violation: require: (arg1>=0) +>>> </pre> </blockquote> -<a name="n3"></a><H2>10.2 %contract and classes</H2> +<H2><a name="Contract_nn3"></a>12.2 %contract and classes</H2> The <tt>%contract</tt> directive can also be applied to class methods and constructors. For example: @@ -91,14 +94,14 @@ The <tt>%contract</tt> directive can also be applied to class methods and constr <pre> %contract Foo::bar(int x, int y) { require: - x > 0; + x > 0; ensure: - bar > 0; + bar > 0; } %contract Foo::Foo(int a) { require: - a > 0; + a > 0; } class Foo { @@ -127,12 +130,12 @@ In addition to this, separate contracts can be applied to both the base class an <pre> %contract Foo::bar(int x, int) { require: - x > 0; + x > 0; } %contract Spam::bar(int, int y) { require: - y > 0; + y > 0; } class Foo { @@ -153,7 +156,7 @@ In other words conditions specified for the base class and conditions 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. -<a name="n4"></a><H2>10.3 Constant aggregation and %aggregate_check</H2> +<H2><a name="Contract_nn4"></a>12.3 Constant aggregation and %aggregate_check</H2> Consider an interface file that contains the following code: @@ -229,13 +232,13 @@ void move(SomeObject *, int direction, int distance); Regrettably, there is no automatic way to perform similar checks with enums values. Maybe in a future release. -<a name="n5"></a><H2>10.4 Notes</H2> +<H2><a name="Contract_nn5"></a>12.4 Notes</H2> Contract support was implemented by Songyan (Tiger) Feng and first appeared in SWIG-1.3.20. -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : November 12, 2003</address> </body> diff --git a/Doc/Manual/Customization.html b/Doc/Manual/Customization.html index 510a3c464..1a1f90ccd 100644 --- a/Doc/Manual/Customization.html +++ b/Doc/Manual/Customization.html @@ -5,19 +5,19 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>9 Customization Features</H1> +<H1><a name="Customization"></a>11 Customization Features</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Exception handling with %exception</a> +<li><a href="#exception">Exception handling with %exception</a> <ul> -<li><a href="#n3">Handling exceptions in C code</a> -<li><a href="#n4">Exception handling with longjmp()</a> -<li><a href="#n5">Handling C++ exceptions</a> -<li><a href="#n6">Defining different exception handlers</a> -<li><a href="#n7">Using The SWIG exception library</a> +<li><a href="#Customization_nn3">Handling exceptions in C code</a> +<li><a href="#Customization_nn4">Exception handling with longjmp()</a> +<li><a href="#Customization_nn5">Handling C++ exceptions</a> +<li><a href="#Customization_nn6">Defining different exception handlers</a> +<li><a href="#Customization_nn7">Using The SWIG exception library</a> </ul> -<li><a href="#n8">Object ownership and %newobject</a> -<li><a href="#n9">Features and the %feature directive</a> +<li><a href="#ownership">Object ownership and %newobject</a> +<li><a href="#features">Features and the %feature directive</a> </ul> <!-- INDEX --> @@ -31,15 +31,16 @@ describes some of these customization techniques. First, a discussion of exception handling is presented. Then, a more general-purpose customization mechanism known as "features" is described. -<a name="exception"> -<a name="n2"></a><H2>9.1 Exception handling with %exception</H2> +<H2><a name="exception"></a>11.1 Exception handling with %exception</H2> +<p> The <tt>%exception</tt> directive allows you to define a general purpose exception handler. For example, you can specify the following: +</p> -<p> -<blockquote><pre>%exception { +<blockquote><pre> +%exception { try { $action } @@ -49,31 +50,34 @@ handler. For example, you can specify the following: } } </pre></blockquote> -<p> +<p> When defined, the code enclosed in braces is inserted directly into the low-level wrapper functions. The special symbol <tt>$action</tt> gets replaced with the actual operation to be performed (a function call, method invocation, attribute access, etc.). An exception handler remains in effect until it is explicitly deleted. This is done by using either <tt>%exception</tt> or <tt>%noexception</tt> with no code. For example: -<p> -<blockquote><pre>%exception; // Deletes any previously defined handler +</p> + +<blockquote><pre> +%exception; // Deletes any previously defined handler </pre></blockquote> <p> <b>Compatibility note:</b> Previous versions of SWIG used a special directive <tt>%except</tt> for exception handling. That directive is still supported but is deprecated--<tt>%exception</tt> provides the same functionality, but is substantially more flexible. +</p> -<a name="n3"></a><H3>9.1.1 Handling exceptions in C code</H3> +<H3><a name="Customization_nn3"></a>11.1.1 Handling exceptions in C code</H3> +<p> C has no formal exception handling mechanism so there are several approaches that might be used. A somewhat common technique is to simply set a special error code. For example: +</p> -<p> <blockquote><pre> - /* File : except.c */ static char error_message[256]; @@ -94,11 +98,13 @@ char *check_exception() { </pre></blockquote> +<p> To use these functions, functions simply call <tt>throw_exception()</tt> to indicate an error occurred. For example -:<p> -<p> -<blockquote><pre>double inv(double x) { +:</p> + +<blockquote><pre> +double inv(double x) { if (x != 0) return 1.0/x; else { throw_exception("Division by zero"); @@ -108,11 +114,12 @@ To use these functions, functions simply call </pre></blockquote> +<p> To catch the exception, you can write a simple exception handler such -as the following (shown for Perl5) :<p> +as the following (shown for Perl5) :</p> -<p> -<blockquote><pre>%exception { +<blockquote><pre> +%exception { char *err; clear_exception(); $action @@ -121,10 +128,12 @@ as the following (shown for Perl5) :<p> } } </pre></blockquote> + <p> In this case, when an error occurs, it is translated into a Perl error. +</p> -<a name="n4"></a><H3>9.1.2 Exception handling with longjmp()</H3> +<H3><a name="Customization_nn4"></a>11.1.2 Exception handling with longjmp()</H3> Exception handling can also be added to C code using the @@ -157,20 +166,22 @@ extern int exception_status; </pre></blockquote> -Now, within a C program, you can do the following :<p> - <p> -<blockquote><pre>double inv(double x) { +Now, within a C program, you can do the following :</p> + +<blockquote><pre> +double inv(double x) { if (x) return 1.0/x; else throw(DivisionByZero); } </pre></blockquote> -Finally, to create a SWIG exception handler, write the following :<p> - <p> -<blockquote><pre>%{ +Finally, to create a SWIG exception handler, write the following :</p> + +<blockquote><pre> +%{ #include "except.h" %} @@ -192,13 +203,15 @@ Finally, to create a SWIG exception handler, write the following :<p> Note: This implementation is only intended to illustrate the general idea. To make it work better, you'll need to modify it to handle nested <tt>try</tt> declarations. -<a name="n5"></a><H3>9.1.3 Handling C++ exceptions</H3> +<H3><a name="Customization_nn5"></a>11.1.3 Handling C++ exceptions</H3> +<p> Handling C++ exceptions is also straightforward. For example: +</p> -<p> -<blockquote><pre>%exception { +<blockquote><pre> +%exception { try { $action } catch(RangeError) { @@ -214,17 +227,18 @@ Handling C++ exceptions is also straightforward. For example: </pre></blockquote> +<p> The exception types need to be declared as classes elsewhere, possibly -in a header file :<p> +in a header file :</p> -<p> -<blockquote><pre>class RangeError {}; +<blockquote><pre> +class RangeError {}; class DivisionByZero {}; class OutOfMemory {}; </pre> </blockquote> -<a name="n6"></a><H3>9.1.4 Defining different exception handlers</H3> +<H3><a name="Customization_nn6"></a>11.1.4 Defining different exception handlers</H3> By default, the <tt>%exception</tt> directive creates an exception @@ -232,14 +246,15 @@ handler that is used for all wrapper functions that follow it. Unless there is a well-defined (and simple) error handling mechanism in place, defining one universal exception handler may be unwieldy and result in excessive code bloat since the handler is inlined into each wrapper function. -<p> +<p> To fix this, you can be more selective about how you use the <tt>%exception</tt> directive. One approach is to only place it around critical pieces of code. For example: +</p> -<p> -<blockquote><pre>%exception { +<blockquote><pre> +%exception { ... your exception handler ... } /* Define critical operations that can throw exceptions here */ @@ -291,6 +306,7 @@ in the specified class as well as for identically named functions appearing in d <p> <tt>%exception</tt> can even be used to pinpoint a precise declaration when overloading is used. For example: +</p> <blockquote> <pre> @@ -347,17 +363,18 @@ was intended to be a mechanism for pinpointing specific declarations. However, it never really worked that well and the new %exception directive is much better. -<a name="n7"></a><H3>9.1.5 Using The SWIG exception library</H3> +<H3><a name="Customization_nn7"></a>11.1.5 Using The SWIG exception library</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 -common scripting language exceptions in a portable manner. For example :<p> +common scripting language exceptions in a portable manner. For example :</p> -<p> -<blockquote><pre>// Language independent exception handler +<blockquote><pre> +// Language independent exception handler %include exception.i %exception { @@ -376,12 +393,13 @@ common scripting language exceptions in a portable manner. For example :<p> </pre></blockquote> +<p> As arguments, <tt>SWIG_exception()</tt> takes an error type code (an integer) and an error message string. The currently supported error -types are :<p> +types are :</p> -<p> -<blockquote><pre>SWIG_MemoryError +<blockquote><pre> +SWIG_MemoryError SWIG_IOError SWIG_RuntimeError SWIG_IndexError @@ -393,14 +411,14 @@ SWIG_ValueError SWIG_SystemError SWIG_UnknownError </pre></blockquote> -<p> +<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. +</p> -<a name="ownership"> -<a name="n8"></a><H2>9.2 Object ownership and %newobject</H2> +<H2><a name="ownership"></a>11.2 Object ownership and %newobject</H2> A common problem in some applications is managing proper ownership of objects. For @@ -424,6 +442,7 @@ returned object was newly created). <p> To fix this, you can provide an extra hint to the code generator using the <tt>%newobject</tt> directive. For example: +</p> <blockquote> <pre> @@ -455,6 +474,7 @@ Closely related to <tt>%newobject</tt> is a special typemap. The "newfree" type can be used to deallocate a newly allocated return value. It is only available on methods for which <tt>%newobject</tt> has been applied and is commonly used to clean-up string results. For example: +</p> <blockquote> <pre> @@ -473,6 +493,7 @@ The "newfree" typemap in the example simply releases this memory. <p> <b>Compatibility note:</b> Previous versions of SWIG had a special <tt>%new</tt> directive. However, unlike <tt>%newobject</tt>, it only applied to the next declaration. For example: +</p> <blockquote> <pre> @@ -485,6 +506,7 @@ For now this is still supported but is deprecated. <p> <b>How to shoot yourself in the foot:</b> The <tt>%newobject</tt> directive is not a declaration modifier like the old <tt>%new</tt> directive. Don't write code like this: +</p> <blockquote> <pre> @@ -494,8 +516,7 @@ char *strdup(const char *s); </blockquote> The results might not be what you expect. -<a name="features"></a> -<a name="n9"></a><H2>9.3 Features and the %feature directive</H2> +<H2><a name="features"></a>11.3 Features and the %feature directive</H2> Both <tt>%exception</tt> and <tt>%newobject</tt> are examples of a @@ -539,10 +560,12 @@ When a feature is defined, it is given a name and a value. Most commonly, the value is supplied after the declaration name as shown for the <tt>"except"</tt> example above. However, if the feature is simple, a value might be supplied as an extra argument as shown for the <tt>"new"</tt> feature. +</p> <p> A feature stays in effect until it is explicitly disabled. A feature is disabled by supplying a <tt>%feature</tt> directive with no value. For example: +</p> <blockquote> <pre> @@ -554,6 +577,7 @@ supplying a <tt>%feature</tt> directive with no value. For example: If no declaration name is given, a global feature is defined. This feature is then attached to <em>every</em> declaration that follows. This is how global exception handlers are defined. For example: +</p> <blockquote> <pre> @@ -618,10 +642,10 @@ 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#exception_handling">Java exception handling</a> section. <p> - As can be seen, the intended use for the <tt>%feature</tt> directive is as a highly flexible customization mechanism that can be used to annotate declarations with additional information for use by specific target language modules. Another example is in the Python module. You might use <tt>%feature</tt> to rewrite proxy/shadow class code as follows: +</p> <blockquote> <pre> @@ -647,7 +671,7 @@ public: Further details of <tt>%feature</tt> usage is described in the documentation for specific language modules. -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : June 28, 2004</address> </body> diff --git a/Doc/Manual/Extending.html b/Doc/Manual/Extending.html index 9759c4d71..09ddbc712 100644 --- a/Doc/Manual/Extending.html +++ b/Doc/Manual/Extending.html @@ -5,64 +5,64 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>26 Extending SWIG</H1> +<H1><a name="Extending"></a>28 Extending SWIG</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Introduction</a> -<li><a href="#n3">Prerequisites</a> -<li><a href="#n4">The Big Picture</a> -<li><a href="#n5">Execution Model</a> +<li><a href="#Extending_nn2">Introduction</a> +<li><a href="#Extending_nn3">Prerequisites</a> +<li><a href="#Extending_nn4">The Big Picture</a> +<li><a href="#Extending_nn5">Execution Model</a> <ul> -<li><a href="#n6">Preprocessing</a> -<li><a href="#n7">Parsing</a> -<li><a href="#n8">Parse Trees</a> -<li><a href="#n9">Attribute namespaces</a> -<li><a href="#n10">Symbol Tables</a> -<li><a href="#n11">The %feature directive</a> -<li><a href="#n12">Code Generation</a> -<li><a href="#n13">SWIG and XML</a> +<li><a href="#Extending_nn6">Preprocessing</a> +<li><a href="#Extending_nn7">Parsing</a> +<li><a href="#Extending_nn8">Parse Trees</a> +<li><a href="#Extending_nn9">Attribute namespaces</a> +<li><a href="#Extending_nn10">Symbol Tables</a> +<li><a href="#Extending_nn11">The %feature directive</a> +<li><a href="#Extending_nn12">Code Generation</a> +<li><a href="#Extending_nn13">SWIG and XML</a> </ul> -<li><a href="#n14">Primitive Data Structures</a> +<li><a href="#Extending_nn14">Primitive Data Structures</a> <ul> -<li><a href="#n15">Strings</a> -<li><a href="#n16">Hashes</a> -<li><a href="#n17">Lists</a> -<li><a href="#n18">Common operations</a> -<li><a href="#n19">Iterating over Lists and Hashes</a> -<li><a href="#n20">I/O</a> +<li><a href="#Extending_nn15">Strings</a> +<li><a href="#Extending_nn16">Hashes</a> +<li><a href="#Extending_nn17">Lists</a> +<li><a href="#Extending_nn18">Common operations</a> +<li><a href="#Extending_nn19">Iterating over Lists and Hashes</a> +<li><a href="#Extending_nn20">I/O</a> </ul> -<li><a href="#n21">Navigating and manipulating parse trees</a> -<li><a href="#n22">Working with attributes</a> -<li><a href="#n23">Type system</a> +<li><a href="#Extending_nn21">Navigating and manipulating parse trees</a> +<li><a href="#Extending_nn22">Working with attributes</a> +<li><a href="#Extending_nn23">Type system</a> <ul> -<li><a href="#n24">String encoding of types</a> -<li><a href="#n25">Type construction</a> -<li><a href="#n26">Type tests</a> -<li><a href="#n27">Typedef and inheritance</a> -<li><a href="#n28">Lvalues</a> -<li><a href="#n29">Output functions</a> +<li><a href="#Extending_nn24">String encoding of types</a> +<li><a href="#Extending_nn25">Type construction</a> +<li><a href="#Extending_nn26">Type tests</a> +<li><a href="#Extending_nn27">Typedef and inheritance</a> +<li><a href="#Extending_nn28">Lvalues</a> +<li><a href="#Extending_nn29">Output functions</a> </ul> -<li><a href="#n30">Parameters</a> -<li><a href="#n31">Writing a Language Module</a> +<li><a href="#Extending_nn30">Parameters</a> +<li><a href="#Extending_nn31">Writing a Language Module</a> <ul> -<li><a href="#n32">Execution model</a> -<li><a href="#n33">Starting out</a> -<li><a href="#n34">Command line options</a> -<li><a href="#n35">Configuration and preprocessing</a> -<li><a href="#n36">Entry point to code generation</a> -<li><a href="#n37">Module I/O and wrapper skeleton</a> -<li><a href="#n38">Low-level code generators</a> -<li><a href="#n39">Configuration files</a> -<li><a href="#n40">Runtime support</a> -<li><a href="#n41">Standard library files</a> -<li><a href="#n42">Examples and test cases</a> -<li><a href="#n43">Documentation</a> +<li><a href="#Extending_nn32">Execution model</a> +<li><a href="#Extending_nn33">Starting out</a> +<li><a href="#Extending_nn34">Command line options</a> +<li><a href="#Extending_nn35">Configuration and preprocessing</a> +<li><a href="#Extending_nn36">Entry point to code generation</a> +<li><a href="#Extending_nn37">Module I/O and wrapper skeleton</a> +<li><a href="#Extending_nn38">Low-level code generators</a> +<li><a href="#Extending_nn39">Configuration files</a> +<li><a href="#Extending_nn40">Runtime support</a> +<li><a href="#Extending_nn41">Standard library files</a> +<li><a href="#Extending_nn42">Examples and test cases</a> +<li><a href="#Extending_nn43">Documentation</a> </ul> -<li><a href="#n44">Typemaps</a> +<li><a href="#Extending_nn44">Typemaps</a> <ul> -<li><a href="#n45">Proxy classes</a> +<li><a href="#Extending_nn45">Proxy classes</a> </ul> -<li><a href="#n46">Guide to parse tree nodes</a> +<li><a href="#Extending_nn46">Guide to parse tree nodes</a> </ul> <!-- INDEX --> @@ -70,25 +70,29 @@ <b>Caution: This chapter is being rewritten! (11/25/01)</b> -<a name="n2"></a><H2>26.1 Introduction</H2> +<H2><a name="Extending_nn2"></a>28.1 Introduction</H2> +<p> This chapter describes SWIG's internal organization and the process by which new target languages can be developed. First, a brief word of warning---SWIG has been undergoing a massive redevelopment effort that has focused extensively on its internal organization. The information in this chapter is mostly up to date, but changes are ongoing. Expect a few inconsistencies. +</p> <p> Also, this chapter is not meant to be a hand-holding tutorial. As a starting point, you should probably look at one of SWIG's existing modules. +</p> -<a name="n3"></a><H2>26.2 Prerequisites</H2> +<H2><a name="Extending_nn3"></a>28.2 Prerequisites</H2> +<p> In order to extend SWIG, it is useful to have the following background: +</p> -<p> <ul> <li>An understanding of the C API for the target language. <li>A good grasp of the C++ type system. @@ -96,20 +100,23 @@ In order to extend SWIG, it is useful to have the following background: <li>Some familiarity with writing C++ (language modules are currently written in C++). </ul> +<p> Since SWIG is essentially a specialized C++ compiler, it may be useful to have some prior experience with compiler design (perhaps even a compilers course) to better understand certain parts of the system. A number of books will also be useful. For example, "The C Programming -Language" by Kernighan and Ritchie (a.k.a, "K&R") and the "C++ +Language" by Kernighan and Ritchie (a.k.a, "K&R") and the "C++ Annotated Reference Manual" by Stroustrup (a.k.a, the "ARM") will be of great use. +</p> <p> Also, it is useful to keep in mind that SWIG primarily operates as an extension of the C++ <em>type</em> system. At first glance, this might not be obvious, but almost all SWIG directives as well as the low-level generation of wrapper code are driven by C++ datatypes. +</p> -<a name="n4"></a><H2>26.3 The Big Picture</H2> +<H2><a name="Extending_nn4"></a>28.3 The Big Picture</H2> SWIG is a special purpose compiler that parses C++ declarations to @@ -121,8 +128,8 @@ three fundamental extensions to the C++ language: conversion/marshalling behavior of specific C++ datatypes. All type conversion in SWIG is based on typemaps. Furthermore, the association of typemaps to datatypes utilizes an advanced pattern matching mechanism that is fully integrated with the C++ type system. +</li> -<p> <li><b>Declaration Annotation</b>. To customize wrapper code generation, most declarations can be annotated with special features. For example, you can make a variable read-only, you can ignore a @@ -130,19 +137,21 @@ declaration, you can rename a member function, you can add exception handling, and so forth. Virtually all of these customizations are built on top of a low-level declaration annotator that can attach arbitrary attributes to any declaration. Code generation modules can look for these attributes to guide the wrapping process. +</li> -<p> <li><b>Class extension</b>. SWIG allows classes and structures to be extended with new methods and attributes (the <tt>%extend</tt> directive). This has the effect of altering the API in the target language and can be used to generate OO interfaces to C libraries. </ul> +<p> It is important to emphasize that virtually all SWIG features reduce to one of these three fundamental concepts. The type system and pattern matching rules also play a critical role in making the system work. For example, both typemaps and declaration annotation are based on pattern matching and interact heavily with the underlying type system. +</p> -<a name="n5"></a><H2>26.4 Execution Model</H2> +<H2><a name="Extending_nn5"></a>28.4 Execution Model</H2> When you run SWIG on an interface, processing is handled in stages by a series of system components: @@ -155,34 +164,37 @@ inclusion. However, the preprocessor also performs some transformations of the interface. For instance, <tt>#define</tt> statements are sometimes transformed into <tt>%constant</tt> declarations. In addition, information related to file/line number tracking is inserted. +</li> -<p> <li>A C/C++ parser reads the preprocessed input and generates a full parse tree of all of the SWIG directives and C declarations found. The parser is responsible for many aspects of the system including renaming, declaration annotation, and template expansion. However, the parser does not produce any output nor does it interact with the target language module as it runs. SWIG is not a one-pass compiler. +</li> -<p> <li>A type-checking pass is made. This adjusts all of the C++ typenames to properly handle namespaces, typedefs, nested classes, and other issues related to type scoping. +</li> -<p> <li>A semantic pass is made on the parse tree to collect information related to properties of the C++ interface. For example, this pass would determine whether or not a class allows a default constructor. +</li> -<p> <li>A code generation pass is made using a specific target language module. This phase is responsible for generating the actual wrapper code. All of SWIG's user-defined modules are invoked during this stage of compilation. +</li> </ul> +<p> The next few sections briefly describe some of these stages. +</p> -<a name="n6"></a><H3>26.4.1 Preprocessing</H3> +<H3><a name="Extending_nn6"></a>28.4.1 Preprocessing</H3> The preprocessor plays a critical role in the SWIG implementation. This is because a lot @@ -232,11 +244,13 @@ of <tt>swig.swg</tt> looks like this: </pre> </blockquote> +<p> The fact that most of the standard SWIG directives are macros is intended to simplify the implementation of the internals. For instance, rather than having to support dozens of special directives, it is easier to have a few basic primitives such as <tt>%feature</tt> or <tt>%insert</tt>. +</p> <p> The <em><tt>langconfig.swg</tt></em> file is supplied by the target @@ -246,6 +260,7 @@ support code (e.g., the type-checker) as well as a collection of typemaps that define the default wrapping behavior. Note: the name of this file depends on the target language and is usually something like <tt>python.swg</tt> or <tt>perl5.swg</tt>. +</p> <p> As a debugging aide, the text that SWIG feeds to its C++ parser can be @@ -253,12 +268,15 @@ obtained by running <tt>swig -E interface.i</tt>. This output probably isn't too useful in general, but it will show how macros have been expanded as well as everything else that goes into the low-level construction of the wrapper code. +</p> -<a name="n7"></a><H3>26.4.2 Parsing</H3> +<H3><a name="Extending_nn7"></a>28.4.2 Parsing</H3> +<p> The current C++ parser handles a subset of C++. Most incompatibilities with C are due to subtle aspects of how SWIG parses declarations. Specifically, SWIG expects all C/C++ declarations to follow this general form: +</p> <blockquote> <pre> @@ -266,6 +284,7 @@ subtle aspects of how SWIG parses declarations. Specifically, SWIG expects all </pre> </blockquote> +<p> <tt><em>storage</em></tt> is a keyword such as <tt>extern</tt>, <tt>static</tt>, <tt>typedef</tt>, or <tt>virtual</tt>. <tt><em>type</em></tt> is a primitive datatype such as <tt>int</tt> or <tt>void</tt>. <tt><em>type</em></tt> may be optionally @@ -274,16 +293,19 @@ is a name with additional type-construction modifiers attached to it (pointers, functions, etc.). Examples of declarators include <tt>*x</tt>, <tt>**x</tt>, <tt>x[20]</tt>, and <tt>(*x)(int,double)</tt>. The <tt><em>initializer</em></tt> may be a value assigned using <tt>=</tt> or body of code enclosed in braces <tt>{ ... }</tt>. +</p> <p> This declaration format covers most common C++ declarations. However, the C++ standard is somewhat more flexible in the placement of the parts. For example, it is technically legal, although uncommon to write something like <tt>int typedef const a</tt> in your program. SWIG simply doesn't bother to deal with this case. +</p> -<P> +<p> The other significant difference between C++ and SWIG is in the treatment of typenames. In C++, if you have a declaration like this, +</p> <blockquote> <pre> @@ -291,23 +313,27 @@ int blah(Foo *x, Bar *y); </pre> </blockquote> +<p> it won't parse correctly unless <tt>Foo</tt> and <tt>Bar</tt> have been previously defined as types either using a <tt>class</tt> definition or a <tt>typedef</tt>. The reasons for this are subtle, but this treatment of typenames is normally integrated at the level of the C tokenizer---when a typename appears, a different token is returned to the parser instead of an identifier. +</p> <p> SWIG does not operate in this manner--any legal identifier can be used as a type name. The reason for this is primarily motivated by the use of SWIG with partially defined data. Specifically, SWIG is supposed to be easy to use on interfaces with missing type information. +</p> <p> Because of the different treatment of typenames, the most serious limitation of the SWIG parser is that it can't process type declarations where an extra (and unnecessary) grouping operator is used. For example: +</p> <blockquote> <pre> @@ -316,15 +342,18 @@ int (y)(int); /* A function y */ </pre> </blockquote> +<p> The placing of extra parentheses in type declarations like this is already recognized by the C++ community as a potential source of strange programming errors. For example, Scott Meyers "Effective STL" discusses this problem in a section on avoiding C++'s "most vexing parse." -<p> +</p> +<p> The parser is also unable to handle declarations with no return type or bare argument names. For example, in an old C program, you might see things like this: +</p> <blockquote> <pre> @@ -339,7 +368,7 @@ interprets the above code as an abstract declarator for a function returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as arguments). -<a name="n8"></a><H3>26.4.3 Parse Trees</H3> +<H3><a name="Extending_nn8"></a>28.4.3 Parse Trees</H3> The SWIG parser produces a complete parse tree of the input file before any wrapper code @@ -393,15 +422,18 @@ $ <b>swig -c++ -python -dump_tags example.i</b> </pre> </blockquote> +<p> Even for the most simple interface, the parse tree structure is larger than you might expect. For example, in the above output, a substantial number of nodes are actually generated by the <tt>python.swg</tt> configuration file which defines typemaps and other directives. The contents of the user-supplied input file don't appear until the end of the output. +</p> <p> The contents of each parse tree node consist of a collection of attribute/value pairs. Internally, the nodes are simply represented by hash tables. A display of the parse-tree structure can be obtained using <tt>swig -dump_tree</tt>. For example: +</p> <blockquote> <pre> @@ -586,23 +618,26 @@ $ swig -c++ -python -dump_tree example.i </pre> </blockquote> -<a name="n9"></a><H3>26.4.4 Attribute namespaces</H3> +<H3><a name="Extending_nn9"></a>28.4.4 Attribute namespaces</H3> +<p> Attributes of parse tree nodes are often prepended with a namespace qualifier. For example, the attributes <tt>sym:name</tt> and <tt>sym:symtab</tt> are attributes related to symbol table management and are prefixed with <tt>sym:</tt>. As a general rule, only those attributes which are directly related to the raw declaration appear without a prefix (type, name, declarator, etc.). +</p> <p> Target language modules may add additional attributes to nodes to assist the generation of wrapper code. The convention for doing this is to place these attributes in a namespace that matches the name of the target language. For example, <tt>python:foo</tt> or <tt>perl:foo</tt>. +</p> -<a name="n10"></a><H3>26.4.5 Symbol Tables</H3> +<H3><a name="Extending_nn10"></a>28.4.5 Symbol Tables</H3> During parsing, all symbols are managed in the space of the target @@ -682,7 +717,7 @@ example.i:5. Previous declaration is foo_i(int ) </pre> </blockquote> -<a name="n11"></a><H3>26.4.6 The %feature directive</H3> +<H3><a name="Extending_nn11"></a>28.4.6 The %feature directive</H3> A number of SWIG directives such as <tt>%exception</tt> are implemented using the @@ -732,17 +767,20 @@ data stored in a feature attribute is usually just a raw unparsed string. For example, the exception code above is simply stored without any modifications. -<a name="n12"></a><H3>26.4.7 Code Generation</H3> +<H3><a name="Extending_nn12"></a>28.4.7 Code Generation</H3> +<p> Language modules work by defining handler functions that know how to respond to different types of parse-tree nodes. These handlers simply look at the attributes of each node in order to produce low-level code. +</p> <p> In reality, the generation of code is somewhat more subtle than simply invoking handler functions. This is because parse-tree nodes might be transformed. For example, suppose you are wrapping a class like this: +</p> <blockquote> <pre> @@ -753,8 +791,10 @@ public: </pre> </blockquote> +<p> When the parser constructs a node for the member <tt>bar</tt>, it creates a raw "cdecl" node with the following attributes: +</p> <blockquote> <pre> @@ -794,11 +834,12 @@ type : int.p decl : f(int).p parms : Foo *self, int x <-- Added parameter storage : virtual -wrap:action : result = (arg1)->bar(arg2) <-- Action code added +wrap:action : result = (arg1)->bar(arg2) <-- Action code added sym:name : Foo_bar <-- Symbol name changed </pre> </blockquote> +<p> In this transformation, notice how an additional parameter was added to the parameter list and how the symbol name of the node has suddenly changed into an accessor using the naming scheme described in the @@ -806,6 +847,7 @@ changed into an accessor using the naming scheme described in the been generated--notice how the <tt>wrap:action</tt> attribute defines the access to the underlying method. The data in this transformed node is then used to generate a wrapper. +</p> <p> Language modules work by registering handler functions for dealing with @@ -813,6 +855,7 @@ various types of nodes at different stages of transformation. This is done by inheriting from a special <tt>Language</tt> class and defining a collection of virtual methods. For example, the Python module defines a class as follows: +</p> <blockquote> <pre> @@ -840,7 +883,7 @@ public : The role of these functions is described shortly. -<a name="n13"></a><H3>26.4.8 SWIG and XML</H3> +<H3><a name="Extending_nn13"></a>28.4.8 SWIG and XML</H3> Much of SWIG's current parser design was originally motivated by @@ -851,22 +894,26 @@ by aspects of XML parsing. Therefore, in trying to understand SWIG's internal data structures, it may be useful keep XML in the back of your mind as a model. -<a name="n14"></a><H2>26.5 Primitive Data Structures</H2> +<H2><a name="Extending_nn14"></a>28.5 Primitive Data Structures</H2> +<p> Most of SWIG is constructed using three basic data structures: strings, hashes, and lists. These data structures are dynamic in same way as similar structures found in many scripting languages. For instance, you can have containers (lists and hash tables) of mixed types and certain operations are polymorphic. +</p> <p> This section briefly describes the basic structures so that later sections of this chapter make more sense. +</p> <p> When describing the low-level API, the following type name conventions are used: +</p> <ul> <li><tt>String</tt>. A string object. @@ -891,11 +938,13 @@ typedef Hash Typetab; </pre> </blockquote> -<a name="n15"></a><H3>26.5.1 Strings</H3> +<H3><a name="Extending_nn15"></a>28.5.1 Strings</H3> <p> <b><tt>String *NewString(const String_or_char *val)</tt></b> +</p> + <blockquote> Creates a new string with initial value <tt>val</tt>. <tt>val</tt> may be a <tt>char *</tt> or another <tt>String</tt> object. If you want @@ -904,6 +953,8 @@ to create an empty string, use "" for val. <p> <b><tt>String *NewStringf(const char *fmt, ...)</tt></b> +</p> + <blockquote> Creates a new string whose initial value is set according to a C <tt>printf</tt> style format string in <tt>fmt</tt>. Additional arguments follow depending @@ -912,36 +963,48 @@ on <tt>fmt</tt>. <p> <b><tt>String *Copy(String *s)</tt></b> +</p> + <blockquote> Make a copy of the string <tt>s</tt>. </blockquote> <p> <b><tt>void Delete(String *s)</tt></b> +</p> + <blockquote> Deletes <tt>s</tt>. </blockquote> <p> <b><tt>int Len(String_or_char *s)</tt></b> +</p> + <blockquote> Returns the length of the string. </blockquote> <p> <b><tt>char *Char(String_or_char *s)</tt></b> +</p> + <blockquote> Returns a pointer to the first character in a string. </blockquote> <p> <b><tt>void Append(String *s, String_or_char *t)</tt></b> +</p> + <blockquote> Appends <tt>t</tt> to the end of string <tt>s</tt>. </blockquote> <p> <b><tt>void Insert(String *s, int pos, String_or_char *t)</tt></b> +</p> + <blockquote> Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>. The contents of <tt>s</tt> are shifted accordingly. The special value <tt>DOH_END</tt> @@ -950,6 +1013,8 @@ can be used for <tt>pos</tt> to indicate insertion at the end of the string (app <p> <b><tt>int Strcmp(const String_or_char *s, const String_or_char *t)</tt></b> +</p> + <blockquote> Compare strings <tt>s</tt> and <tt>t</tt>. Same as the C <tt>strcmp()</tt> function. @@ -957,6 +1022,8 @@ function. <p> <b><tt>int Strncmp(const String_or_char *s, const String_or_char *t, int len)</tt></b> +</p> + <blockquote> Compare the first <tt>len</tt> characters of strings <tt>s</tt> and <tt>t</tt>. Same as the C <tt>strncmp()</tt> function. @@ -964,6 +1031,8 @@ function. <p> <b><tt>char *Strstr(const String_or_char *s, const String_or_char *pat)</tt></b> +</p> + <blockquote> Returns a pointer to the first occurrence of <tt>pat</tt> in <tt>s</tt>. Same as the C <tt>strstr()</tt> function. @@ -971,6 +1040,8 @@ Same as the C <tt>strstr()</tt> function. <p> <b><tt>char *Strchr(const String_or_char *s, char ch)</tt></b> +</p> + <blockquote> Returns a pointer to the first occurrence of character <tt>ch</tt> in <tt>s</tt>. Same as the C <tt>strchr()</tt> function. @@ -978,12 +1049,16 @@ Same as the C <tt>strchr()</tt> function. <p> <b><tt>void Chop(String *s)</tt></b> +</p> + <blockquote> Chops trailing whitespace off the end of <tt>s</tt>. </blockquote> <p> <b><tt>int Replace(String *s, const String_or_char *pat, const String_or_char *rep, int flags)</tt></b> +</p> + <blockquote> Replaces the pattern <tt>pat</tt> with <tt>rep</tt> in string <tt>s</tt>. <tt>flags</tt> is a combination of the following flags: @@ -996,38 +1071,51 @@ DOH_REPLACE_FIRST - Replace first occurrence only. </pre> </blockquote> +<p> Returns the number of replacements made (if any). +</p> + </blockquote> -<a name="n16"></a><H3>26.5.2 Hashes</H3> +<H3><a name="Extending_nn16"></a>28.5.2 Hashes</H3> <p> <b><tt>Hash *NewHash()</tt></b> +</p> + <blockquote> Creates a new empty hash table. </blockquote> <p> <b><tt>Hash *Copy(Hash *h)</tt></b> +</p> + <blockquote> Make a shallow copy of the hash <tt>h</tt>. </blockquote> <p> <b><tt>void Delete(Hash *h)</tt></b> +</p> + <blockquote> Deletes <tt>h</tt>. </blockquote> <p> <b><tt>int Len(Hash *h)</tt></b> +</p> + <blockquote> Returns the number of items in <tt>h</tt>. </blockquote> <p> <b><tt>Object *Getattr(Hash *h, String_or_char *key)</tt></b> +</p> + <blockquote> Gets an object from <tt>h</tt>. <tt>key</tt> may be a string or a simple <tt>char *</tt> string. Returns NULL if not found. @@ -1035,6 +1123,8 @@ a simple <tt>char *</tt> string. Returns NULL if not found. <p> <b><tt>int Setattr(Hash *h, String_or_char *key, Object_or_char *val)</tt></b> +</p> + <blockquote> Stores <tt>val</tt> in <tt>h</tt>. <tt>key</tt> may be a string or a simple <tt>char *</tt>. If <tt>val</tt> is not a standard @@ -1047,6 +1137,8 @@ of <tt>val</tt>. Returns 1 if this operation replaced an existing hash entry, <p> <b><tt>int Delattr(Hash *h, String_or_char *key)</tt></b> +</p> + <blockquote> Deletes the hash item referenced by <tt>key</tt>. Decreases the reference count on the corresponding object (if any). Returns 1 @@ -1055,40 +1147,52 @@ if an object was removed, 0 otherwise. <p> <b><tt>List *Keys(Hash *h)</tt></b> +</p> + <blockquote> Returns the list of hash table keys. </blockquote> -<a name="n17"></a><H3>26.5.3 Lists</H3> +<H3><a name="Extending_nn17"></a>28.5.3 Lists</H3> <p> <b><tt>List *NewList()</tt></b> +</p> + <blockquote> Creates a new empty list. </blockquote> <p> <b><tt>List *Copy(List *x)</tt></b> +</p> + <blockquote> Make a shallow copy of the List <tt>x</tt>. </blockquote> <p> <b><tt>void Delete(List *x)</tt></b> +</p> + <blockquote> Deletes <tt>x</tt>. </blockquote> <p> <b><tt>int Len(List *x)</tt></b> +</p> + <blockquote> Returns the number of items in <tt>x</tt>. </blockquote> <p> <b><tt>Object *Getitem(List *x, int n)</tt></b> +</p> + <blockquote> Returns an object from <tt>x</tt> with index <tt>n</tt>. If <tt>n</tt> is beyond the end of the list, the last item is returned. If <tt>n</tt> is @@ -1097,6 +1201,8 @@ negative, the first item is returned. <p> <b><tt>int *Setitem(List *x, int n, Object_or_char *val)</tt></b> +</p> + <blockquote> Stores <tt>val</tt> in <tt>x</tt>. If <tt>val</tt> is not a standard @@ -1107,6 +1213,8 @@ case it is used to construct a <tt>String</tt> that is stored in the list. <p> <b><tt>int *Delitem(List *x, int n)</tt></b> +</p> + <blockquote> Deletes item <tt>n</tt> from the list, shifting items down if necessary. To delete the last item in the list, use the special value <tt>DOH_END</tt> @@ -1115,6 +1223,8 @@ for <tt>n</tt>. <p> <b><tt>void Append(List *x, Object_or_char *t)</tt></b> +</p> + <blockquote> Appends <tt>t</tt> to the end of <tt>x</tt>. If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt> and is @@ -1123,6 +1233,8 @@ used to create a String object. <p> <b><tt>void Insert(String *s, int pos, Object_or_char *t)</tt></b> +</p> + <blockquote> Inserts <tt>t</tt> into <tt>s</tt> at position <tt>pos</tt>. The contents of <tt>s</tt> are shifted accordingly. The special value <tt>DOH_END</tt> @@ -1131,25 +1243,31 @@ 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. </blockquote> -<a name="n18"></a><H3>26.5.4 Common operations</H3> +<H3><a name="Extending_nn18"></a>28.5.4 Common operations</H3> The following operations are applicable to all datatypes. <p> <b><tt>Object *Copy(Object *x)</tt></b> +</p> + <blockquote> Make a copy of the object <tt>x</tt>. </blockquote> <p> <b><tt>void Delete(Object *x)</tt></b> +</p> + <blockquote> Deletes <tt>x</tt>. </blockquote> <p> <b><tt>void Setfile(Object *x, String_or_char *f)</tt></b> +</p> + <blockquote> Sets the filename associated with <tt>x</tt>. Used to track objects and report errors. @@ -1157,12 +1275,16 @@ objects and report errors. <p> <b><tt>String *Getfile(Object *x)</tt></b> +</p> + <blockquote> Gets the filename associated with <tt>x</tt>. </blockquote> <p> <b><tt>void Setline(Object *x, int n)</tt></b> +</p> + <blockquote> Sets the line number associated with <tt>x</tt>. Used to track objects and report errors. @@ -1170,17 +1292,21 @@ objects and report errors. <p> <b><tt>int Getline(Object *x)</tt></b> +</p> + <blockquote> Gets the line number associated with <tt>x</tt>. </blockquote> -<a name="n19"></a><H3>26.5.5 Iterating over Lists and Hashes</H3> +<H3><a name="Extending_nn19"></a>28.5.5 Iterating over Lists and Hashes</H3> To iterate over the elements of a list or a hash table, the following functions are used: <p> <b><tt>Iterator First(Object *x)</tt></b> +</p> + <blockquote> Returns an iterator object that points to the first item in a list or hash table. The <tt>item</tt> attribute of the Iterator object is a pointer to the item. For hash tables, the <tt>key</tt> attribute @@ -1190,6 +1316,8 @@ are NULL if the object contains no items or if there are no more items. <p> <b><tt>Iterator Next(Iterator i)</tt></b> +</p> + <blockquote> Returns an iterator that points to the next item in a list or hash table. </blockquote> @@ -1214,7 +1342,7 @@ for (j = First(j); j.item; j= Next(j)) { </pre> </blockquote> -<a name="n20"></a><H3>26.5.6 I/O</H3> +<H3><a name="Extending_nn20"></a>28.5.6 I/O</H3> Special I/O functions are used for all internal I/O. These operations @@ -1223,6 +1351,8 @@ work on C <tt>FILE *</tt> objects, String objects, and special <tt>File</tt> obj <p> <b><tt>int Printf(String_or_FILE *f, const char *fmt, ...)</tt></b> +</p> + <blockquote> Formatted I/O. Same as the C <tt>fprintf()</tt> function except that output can also be directed to a string object. Note: the <tt>%s</tt> format @@ -1232,6 +1362,8 @@ operators have the same meaning. <p> <b><tt>int Printv(String_or_FILE *f, String_or_char *arg1,..., NULL)</tt></b> +</p> + <blockquote> Prints a variable number of strings arguments to the output. The last argument to this function must be NULL. The other arguments can either @@ -1240,36 +1372,48 @@ be <tt>char *</tt> or string objects. <p> <b><tt>int Putc(int ch, String_or_FILE *f)</tt></b> +</p> + <blockquote> Same as the C <tt>fputc()</tt> function. </blockquote> <p> <b><tt>int Write(String_or_FILE *f, void *buf, int len)</tt></b> +</p> + <blockquote> Same as the C <tt>write()</tt> function. </blockquote> <p> <b><tt>int Read(String_or_FILE *f, void *buf, int maxlen)</tt></b> +</p> + <blockquote> Same as the C <tt>read()</tt> function. </blockquote> <p> <b><tt>int Getc(String_or_FILE *f)</tt></b> +</p> + <blockquote> Same as the C <tt>fgetc()</tt> function. </blockquote> <p> <b><tt>int Ungetc(int ch, String_or_FILE *f)</tt></b> +</p> + <blockquote> Same as the C <tt>ungetc()</tt> function. </blockquote> <p> <b><tt>int Seek(String_or_FILE *f, int offset, int whence)</tt></b> +</p> + <blockquote> Same as the C <tt>seek()</tt> function. <tt>offset</tt> is the number of bytes. <tt>whence</tt> is one of <tt>SEEK_SET</tt>,<tt>SEEK_CUR</tt>, @@ -1278,12 +1422,16 @@ or <tt>SEEK_END</tt>.. <p> <b><tt>long Tell(String_or_FILE *f)</tt></b> +</p> + <blockquote> Same as the C <tt>tell()</tt> function. </blockquote> <p> <b><tt>File *NewFile(const char *filename, const char *mode)</tt></b> +</p> + <blockquote> Create a File object using the <tt>fopen()</tt> library call. This file differs from <tt>FILE *</tt> in that it can be placed in the standard @@ -1292,12 +1440,16 @@ SWIG containers (lists, hashes, etc.). <p> <b><tt>File *NewFileFromFile(FILE *f)</tt></b> +</p> + <blockquote> Create a File object wrapper around an existing <tt>FILE *</tt> object. </blockquote> <p> <b><tt>int Close(String_or_FILE *f)</tt></b> +</p> + <blockquote> Closes a file. Has no effect on strings. </blockquote> @@ -1321,7 +1473,7 @@ Printf(f, "%s\n", s); Similarly, the preprocessor and parser all operate on string-files. -<a name="n21"></a><H2>26.6 Navigating and manipulating parse trees</H2> +<H2><a name="Extending_nn21"></a>28.6 Navigating and manipulating parse trees</H2> Parse trees are built as collections of hash tables. Each node is a hash table in which @@ -1330,6 +1482,8 @@ other parse tree nodes. The following macros can be used to move around the pa <p> <b><tt>String *nodeType(Node *n)</tt></b> +</p> + <blockquote> Returns the node type tag as a string. The returned string indicates the type of parse tree node. @@ -1337,18 +1491,24 @@ tree node. <p> <b><tt>Node *nextSibling(Node *n)</tt></b> +</p> + <blockquote> Returns the next node in the parse tree. For example, the next C declaration. </blockquote> <p> <b><tt>Node *previousSibling(Node *n)</tt></b> +</p> + <blockquote> Returns the previous node in the parse tree. For example, the previous C declaration. </blockquote> <p> <b><tt>Node *firstChild(Node *n)</tt></b> +</p> + <blockquote> Returns the first child node. For example, if <tt>n</tt> was a C++ class node, this would return the node for the first class member. @@ -1356,6 +1516,8 @@ return the node for the first class member. <p> <b><tt>Node *lastChild(Node *n)</tt></b> +</p> + <blockquote> Returns the last child node. You might use this if you wanted to append a new node to the of a class. @@ -1363,6 +1525,8 @@ node to the of a class. <p> <b><tt>Node *parentNode(Node *n)</tt></b> +</p> + <blockquote> Returns the parent of node <tt>n</tt>. Use this to move up the pass tree. </blockquote> @@ -1373,6 +1537,8 @@ knowing what you are doing is likely to be dangerous. <p> <b><tt>void set_nodeType(Node *n, const String_or_char)</tt></b> +</p> + <blockquote> Change the node type. tree node. @@ -1380,30 +1546,40 @@ tree node. <p> <b><tt>void set_nextSibling(Node *n, Node *s)</tt></b> +</p> + <blockquote> Set the next sibling. </blockquote> <p> <b><tt>void set_previousSibling(Node *n, Node *s)</tt></b> +</p> + <blockquote> Set the previous sibling. </blockquote> <p> <b><tt>void set_firstChild(Node *n, Node *c)</tt></b> +</p> + <blockquote> Set the first child node. </blockquote> <p> <b><tt>void set_lastChild(Node *n, Node *c)</tt></b> +</p> + <blockquote> Set the last child node. </blockquote> <p> <b><tt>void set_parentNode(Node *n, Node *p)</tt></b> +</p> + <blockquote> Set the parent node. </blockquote> @@ -1412,18 +1588,22 @@ The following utility functions are used to alter the parse tree (at your own ri <p> <b><tt>void appendChild(Node *parent, Node *child)</tt></b> +</p> + <blockquote> Append a child to <tt>parent</tt>. The appended node becomes the last child. </blockquote> <p> <b><tt>void deleteNode(Node *node)</tt></b> +</p> + <blockquote> Deletes a node from the parse tree. Deletion reconnects siblings and properly updates the parent so that sibling nodes are unaffected. </blockquote> -<a name="n22"></a><H2>26.7 Working with attributes</H2> +<H2><a name="Extending_nn22"></a>28.7 Working with attributes</H2> Since parse tree nodes are just hash tables, attributes are accessed using the <tt>Getattr()</tt>, @@ -1454,6 +1634,7 @@ Setattr(n,"python:docstring", doc); /* Store docstring */ <p> A quick way to check the value of an attribute is to use the <tt>checkAttribute()</tt> function like this: +</p> <blockquote> <pre> @@ -1469,9 +1650,12 @@ Changing the values of existing attributes is allowed and is sometimes done to i node transformations. However, if a function/method modifies a node, it is required to restore modified attributes to their original values. To simplify the task of saving/restoring attributes, the following functions are used: +</p> <p> <b><tt>int Swig_save(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL)</tt></b> +</p> + <blockquote> Saves a copy of attributes <tt>name1</tt>, <tt>name2</tt>, etc. from node <tt>n</tt>. Copies of the attributes are actually resaved in the node in a different namespace which is @@ -1483,6 +1667,8 @@ values of attributes might have been saved. <p> <b><tt>int Swig_restore(Node *n)</tt></b> +</p> + <blockquote> Restores the attributes saved by the previous call to <tt>Swig_save()</tt>. Those attributes that were supplied to <tt>Swig_save()</tt> will be restored to their @@ -1513,6 +1699,8 @@ int variableHandler(Node *n) { <p> <b><tt>int Swig_require(const char *ns, Node *n, const char *name1, const char *name2, ..., NIL)</tt></b> +</p> + <blockquote> This is an enhanced version of <tt>Swig_save()</tt> that adds error checking. If an attribute name is not present in <tt>n</tt>, a failed assertion results and SWIG terminates with a fatal @@ -1522,14 +1710,14 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after function. </blockquote> -<a name="n23"></a><H2>26.8 Type system</H2> +<H2><a name="Extending_nn23"></a>28.8 Type system</H2> SWIG implements the complete C++ type system including typedef, inheritance, pointers, references, and pointers to members. A detailed discussion of type theory is impossible here. However, let's cover the highlights. -<a name="n24"></a><H3>26.8.1 String encoding of types</H3> +<H3><a name="Extending_nn24"></a>28.8.1 String encoding of types</H3> <p> @@ -1539,6 +1727,7 @@ always some kind of primitive type such as <tt>int</tt> or <tt>double</tt>. The operators consist of things like pointers, references, arrays, and so forth. Internally, types are represented as strings that are constructed in a very precise manner. Here are some examples: +</p> <blockquote> <pre> @@ -1554,12 +1743,15 @@ vector<int> * "p.vector<(int)>" </pre> </blockquote> +<p> Reading the SWIG encoding is often easier than figuring out the C code---just read it from left to right. For a type of "p.f(int,double).int" is a "pointer to a function(int,double) that returns int". +</p> <p> The following operator encodings are used in type strings: +</p> <blockquote> <pre> @@ -1584,6 +1776,7 @@ If you want to experiment with type encodings, the raw type strings can be inserted into an interface file using backticks `` wherever a type is expected. For instance, here is an extremely perverted example: +</p> <blockquote> <pre> @@ -1617,7 +1810,7 @@ is processed in a few pieces. In this case, you have the base type make the final type, the two parts are just joined together using string concatenation. -<a name="n25"></a><H3>26.8.2 Type construction</H3> +<H3><a name="Extending_nn25"></a>28.8.2 Type construction</H3> The following functions are used to construct types. You should use @@ -1625,30 +1818,40 @@ these functions instead of trying to build the type strings yourself. <p> <b><tt>void SwigType_add_pointer(SwigType *ty)</tt></b> +</p> + <blockquote> Adds a pointer to <tt>ty</tt>. </blockquote> <p> <b><tt>void SwigType_del_pointer(SwigType *ty)</tt></b> +</p> + <blockquote> Removes a single pointer from <tt>ty</tt>. </blockquote> <p> <b><tt>void SwigType_add_reference(SwigType *ty)</tt></b> +</p> + <blockquote> Adds a reference to <tt>ty</tt>. </blockquote> <p> <b><tt>void SwigType_add_array(SwigType *ty, String_or_char *dim)</tt></b> +</p> + <blockquote> Adds an array with dimension <tt>dim</tt> to <tt>ty</tt>. </blockquote> <p> <b><tt>void SwigType_add_qualifier(SwigType *ty, String_or_char *q)</tt></b> +</p> + <blockquote> Adds a type qualifier <tt>q</tt> to <tt>ty</tt>. <tt>q</tt> is typically <tt>"const"</tt> or <tt>"volatile"</tt>. @@ -1656,12 +1859,16 @@ Adds a type qualifier <tt>q</tt> to <tt>ty</tt>. <tt>q</tt> is typically <p> <b><tt>void SwigType_add_memberpointer(SwigType *ty, String_or_char *cls)</tt></b> +</p> + <blockquote> Adds a pointer to a member of class <tt>cls</tt> to <tt>ty</tt>. </blockquote> <p> <b><tt>void SwigType_add_function(SwigType *ty, ParmList *p)</tt></b> +</p> + <blockquote> Adds a function to <tt>ty</tt>. <tt>p</tt> is a linked-list of parameter nodes as generated by the parser. See the section on parameter lists @@ -1670,6 +1877,8 @@ for details about the representation. <p> <b><tt>void SwigType_add_template(SwigType *ty, ParmList *p)</tt></b> +</p> + <blockquote> Adds a template to <tt>ty</tt>. <tt>p</tt> is a linked-list of parameter nodes as generated by the parser. See the section on parameter lists @@ -1678,6 +1887,8 @@ for details about the representation. <p> <b><tt>SwigType *SwigType_pop(SwigType *ty)</tt></b> +</p> + <blockquote> Removes the last type constructor from <tt>ty</tt> and returns it. <tt>ty</tt> is modified. @@ -1685,6 +1896,8 @@ Removes the last type constructor from <tt>ty</tt> and returns it. <p> <b><tt>void SwigType_push(SwigType *ty, SwigType *op)</tt></b> +</p> + <blockquote> Pushes the type operators in <tt>op</tt> onto type <tt>ty</tt>. The opposite of <tt>SwigType_pop()</tt>. @@ -1692,6 +1905,8 @@ opposite of <tt>SwigType_pop()</tt>. <p> <b><tt>SwigType *SwigType_pop_arrays(SwigType *ty)</tt></b> +</p> + <blockquote> Removes all leading array operators from <tt>ty</tt> and returns them. <tt>ty</tt> is modified. For example, if <tt>ty</tt> is <tt>"a(20).a(10).p.int"</tt>, @@ -1701,6 +1916,8 @@ so that it has the value <tt>"p.int"</tt>. <p> <b><tt>SwigType *SwigType_pop_function(SwigType *ty)</tt></b> +</p> + <blockquote> Removes a function operator from <tt>ty</tt> including any qualification. <tt>ty</tt> is modified. For example, if <tt>ty</tt> is <tt>"f(int).int"</tt>, @@ -1710,6 +1927,8 @@ so that it has the value <tt>"int"</tt>. <p> <b><tt>SwigType *SwigType_base(SwigType *ty)</tt></b> +</p> + <blockquote> Returns the base type of a type. For example, if <tt>ty</tt> is <tt>"p.a(20).int"</tt>, this function would return <tt>"int"</tt>. @@ -1718,78 +1937,100 @@ Returns the base type of a type. For example, if <tt>ty</tt> is <p> <b><tt>SwigType *SwigType_prefix(SwigType *ty)</tt></b> +</p> + <blockquote> Returns the prefix of a type. For example, if <tt>ty</tt> is <tt>"p.a(20).int"</tt>, this function would return <tt>"p.a(20)."</tt>. <tt>ty</tt> is unmodified. </blockquote> -<a name="n26"></a><H3>26.8.3 Type tests</H3> +<H3><a name="Extending_nn26"></a>28.8.3 Type tests</H3> The following functions can be used to test properties of a datatype. <p> <b><tt>int SwigType_ispointer(SwigType *ty)</tt></b> +</p> + <blockquote> Checks if <tt>ty</tt> is a standard pointer. </blockquote> <p> <b><tt>int SwigType_ismemberpointer(SwigType *ty)</tt></b> +</p> + <blockquote> Checks if <tt>ty</tt> is a member pointer. </blockquote> <p> <b><tt>int SwigType_isreference(SwigType *ty)</tt></b> +</p> + <blockquote> Checks if <tt>ty</tt> is a C++ reference. </blockquote> <p> <b><tt>int SwigType_isarray(SwigType *ty)</tt></b> +</p> + <blockquote> Checks if <tt>ty</tt> is an array. </blockquote> <p> <b><tt>int SwigType_isfunction(SwigType *ty)</tt></b> +</p> + <blockquote> Checks if <tt>ty</tt> is a function. </blockquote> <p> <b><tt>int SwigType_isqualifier(SwigType *ty)</tt></b> +</p> + <blockquote> Checks if <tt>ty</tt> is a qualifier. </blockquote> <p> <b><tt>int SwigType_issimple(SwigType *ty)</tt></b> +</p> + <blockquote> Checks if <tt>ty</tt> is a simple type. No operators applied. </blockquote> <p> <b><tt>int SwigType_isconst(SwigType *ty)</tt></b> +</p> + <blockquote> Checks if <tt>ty</tt> is a const type. </blockquote> <p> <b><tt>int SwigType_isvarargs(SwigType *ty)</tt></b> +</p> + <blockquote> Checks if <tt>ty</tt> is a varargs type. </blockquote> <p> <b><tt>int SwigType_istemplate(SwigType *ty)</tt></b> +</p> + <blockquote> Checks if <tt>ty</tt> is a templatized type. </blockquote> -<a name="n27"></a><H3>26.8.4 Typedef and inheritance</H3> +<H3><a name="Extending_nn27"></a>28.8.4 Typedef and inheritance</H3> The behavior of <tt>typedef</tt> declaration is to introduce a type alias. @@ -1803,6 +2044,7 @@ datatypes). <p> To handle <tt>typedef</tt>, SWIG builds a collection of trees containing typedef relations. For example, +</p> <blockquote> <pre> @@ -1829,15 +2071,19 @@ To resolve a single typedef relationship, the following function is used: <p> <b><tt>SwigType *SwigType_typedef_resolve(SwigType *ty)</tt></b> +</p> + <blockquote> Checks if <tt>ty</tt> can be reduced to a new type via typedef. If so, returns the new type. If not, returns NULL. </blockquote> +<p> Typedefs are only resolved in simple typenames that appear in a type. For example, the type base name and in function parameters. When resolving types, the process starts in the leaf nodes and moves up the tree towards the root. Here are a few examples that show how it works: +</p> <blockquote> <pre> @@ -1869,12 +2115,14 @@ The following function will fully reduce a datatype: <p> <b><tt>SwigType *SwigType_typedef_resolve_all(SwigType *ty)</tt></b> +</p> + <blockquote> Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype will consist only of primitive typenames. </blockquote> -<a name="n28"></a><H3>26.8.5 Lvalues</H3> +<H3><a name="Extending_nn28"></a>28.8.5 Lvalues</H3> When generating wrapper code, it is necessary to emit datatypes that can @@ -1885,6 +2133,8 @@ use the following function: <p> <b><tt>SwigType *SwigType_ltype(SwigType *ty)</tt></b> +</p> + <blockquote> Converts type <tt>ty</tt> to a type that can be used as an lvalue in assignment. The resulting type is stripped of qualifiers and arrays are @@ -1905,13 +2155,15 @@ Literal y; // type = 'Literal', ltype='p.char' </pre> </blockquote> -<a name="n29"></a><H3>26.8.6 Output functions</H3> +<H3><a name="Extending_nn29"></a>28.8.6 Output functions</H3> The following functions produce strings that are suitable for output. <p> <b><tt>String *SwigType_str(SwigType *ty, String_or_char *id = 0)</tt></b> +</p> + <blockquote> Generates a C string for a datatype. <tt>id</tt> is an optional declarator. For example, if <tt>ty</tt> is "p.f(int).int" and <tt>id</tt> is "foo", then @@ -1921,6 +2173,8 @@ used to convert string-encoded types back into a form that is valid C syntax. <p> <b><tt>String *SwigType_lstr(SwigType *ty, String_or_char *id = 0)</tt></b> +</p> + <blockquote> This is the same as <tt>SwigType_str()</tt> except that the result is generated from the type's lvalue (as generated from SwigType_ltype). @@ -1928,6 +2182,8 @@ is generated from the type's lvalue (as generated from SwigType_ltype). <p> <b><tt>String *SwigType_lcaststr(SwigType *ty, String_or_char *id = 0)</tt></b> +</p> + <blockquote> Generates a casting operation that converts from type <tt>ty</tt> to its lvalue. <tt>id</tt> is an optional name to include in the cast. For example, @@ -1937,6 +2193,8 @@ this function produces the string "<tt>(char *) foo</tt>". <p> <b><tt>String *SwigType_rcaststr(SwigType *ty, String_or_char *id = 0)</tt></b> +</p> + <blockquote> Generates a casting operation that converts from a type's lvalue to a type equivalent to <tt>ty</tt>. <tt>id</tt> is an optional name to @@ -1947,6 +2205,8 @@ function produces the string "<tt>(const char *) foo</tt>". <p> <b><tt>String *SwigType_manglestr(SwigType *ty)</tt></b> +</p> + <blockquote> Generates a mangled string encoding of type <tt>ty</tt>. The mangled string only contains characters that are part of a valid @@ -1955,7 +2215,7 @@ SWIG, but is most commonly associated with type-descriptor objects that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>). </blockquote> -<a name="n30"></a><H2>26.9 Parameters</H2> +<H2><a name="Extending_nn30"></a>28.9 Parameters</H2> Several type-related functions involve parameter lists. These include @@ -1987,35 +2247,47 @@ for (p = parms; p; p = nextSibling(p)) { </pre> </blockquote> +<p> Note: this code is exactly the same as what you would use to walk parse tree nodes. +</p> <p> An empty list of parameters is denoted by a NULL pointer. +</p> <p> Since parameter lists are fairly common, the following utility functions are provided to manipulate them: +</p> <p> <b><tt>Parm *CopyParm(Parm *p);</tt></b> +</p> + <blockquote> Copies a single parameter. </blockquote> <p> <b><tt>ParmList *CopyParmList(ParmList *p);</tt></b> +</p> + <blockquote> Copies an entire list of parameters. </blockquote> <p> <b><tt>int ParmList_len(ParmList *p);</tt></b> +</p> + <blockquote> Returns the number of parameters in a parameter list. </blockquote> <p> <b><tt>String *ParmList_str(ParmList *p);</tt></b> +</p> + <blockquote> Converts a parameter list into a C string. For example, produces a string like "<tt>(int *p, int n, double x);</tt>". @@ -2023,6 +2295,8 @@ produces a string like "<tt>(int *p, int n, double x);</tt>". <p> <b><tt>String *ParmList_protostr(ParmList *p);</tt></b> +</p> + <blockquote> The same as <tt>ParmList_str()</tt> except that parameter names are not included. Used to emit prototypes. @@ -2030,11 +2304,13 @@ included. Used to emit prototypes. <p> <b><tt>int ParmList_numrequired(ParmList *p);</tt></b> +</p> + <blockquote> Returns the number of required (non-optional) arguments in <tt>p</tt>. </blockquote> -<a name="n31"></a><H2>26.10 Writing a Language Module</H2> +<H2><a name="Extending_nn31"></a>28.10 Writing a Language Module</H2> This section briefly outlines the steps needed to create a bare-bones @@ -2043,7 +2319,7 @@ of existing modules. Since the code is relatively easy to read, this section describes the creation of a minimal Python module. You should be able to extrapolate this to other languages. -<a name="n32"></a><H3>26.10.1 Execution model</H3> +<H3><a name="Extending_nn32"></a>28.10.1 Execution model</H3> Code generation modules are defined by inheriting from the <tt>Language</tt> class, @@ -2051,7 +2327,7 @@ currently defined in the <tt>Source/Modules1.1</tt> directory of SWIG. Starting the parsing of command line options, all aspects of code generation are controlled by different methods of the <tt>Language</tt> that must be defined by your module. -<a name="n33"></a><H3>26.10.2 Starting out</H3> +<H3><a name="Extending_nn33"></a>28.10.2 Starting out</H3> To define a new language module, first create a minimal implementation using @@ -2086,6 +2362,7 @@ swig_python(void) { </pre> </blockquote> +<p> The "swigmod.h" header file contains, among other things, the declaration of the <tt>Language</tt> base class and so you should include it at the top of your language module's source file. Similarly, the "swigconfig.h" header @@ -2094,31 +2371,41 @@ should <em>not</em> include any header files that are installed with the target language. That is to say, the implementation of the SWIG Python module shouldn't have any dependencies on the Python header files. The wrapper code generated by SWIG will almost always depend on some language-specific C/C++ -header files, but SWIG itself does not.<p> +header files, but SWIG itself does not. +</p> +<p> Give your language class a reasonable name, usually the same as the target language. By convention, these class names are all uppercase (e.g. "PYTHON" for the Python language module) but this is not a requirement. This class will ultimately consist of a number of overrides of the virtual functions declared in the <tt>Language</tt> base class, in addition to any language-specific member functions and data you -need. For now, just use the dummy implementations shown above.<p> +need. For now, just use the dummy implementations shown above. +</p> +<p> The language module ends with a factory function, <tt>swig_python()</tt>, that simply returns a new instance of the language class. As shown, it should be declared with the <tt>extern "C"</tt> storage qualifier so that it can be called from C code. It should also return a pointer to the base class (<tt>Language</tt>) so that only the interface -(and not the implementation) of your language module is exposed to the rest of SWIG.<p> +(and not the implementation) of your language module is exposed to the rest of SWIG. +</p> +<p> Save the code for your language module in a file named "<tt>python.cxx</tt>" and. place this file in the <tt>Source/Modules1.1</tt> directory of the SWIG distribution. To ensure that your module is compiled into SWIG along with the other language modules, modify the file <tt>Source/Modules1.1/Makefile.in</tt> to include the additional source files. Look for the lines that define the <tt>SRCS</tt> and <tt>OBJS</tt> variables and add entries for your language. In addition, modify the file <tt>Source/Modules1.1/swigmain.cxx</tt> -with an additional command line option that activates the module. Read the source---it's straightforward.<p> +with an additional command line option that activates the module. Read the source---it's straightforward. +</p> +<p> Next, at the top level of the SWIG distribution, re-run the <tt>autogen.sh</tt> script to regenerate the various build files: +</p> + <blockquote> <pre> $ <b>sh autogen.sh</b> @@ -2143,7 +2430,7 @@ Once it finishes compiling, try running SWIG with the command-line option that activates your module. For example, <tt>swig -python foo.i</tt>. The messages from your new module should appear. -<a name="n34"></a><H3>26.10.3 Command line options</H3> +<H3><a name="Extending_nn34"></a>28.10.3 Command line options</H3> When SWIG starts, the command line options are passed to your language module. This occurs @@ -2189,20 +2476,25 @@ void Language::main(int argc, char *argv[]) { </pre> </blockquote> +<p> The exact set of options depends on what you want to do in your module. Generally, you would use the options to change code generation modes or to print diagnostic information. +</p> <p> If a module recognizes an option, it should always call <tt>Swig_mark_arg()</tt> to mark the option as valid. If you forget to do this, SWIG will terminate with an unrecognized command line option error. +</p> -<a name="n35"></a><H3>26.10.4 Configuration and preprocessing</H3> +<H3><a name="Extending_nn35"></a>28.10.4 Configuration and preprocessing</H3> +<p> In addition to looking at command line options, the <tt>main()</tt> method is responsible for some initial configuration of the SWIG library and preprocessor. To do this, insert some code like this: +</p> <blockquote> <pre> @@ -2224,25 +2516,30 @@ void main(int argc, char *argv[]) { </pre> </blockquote> +<p> The above code does several things--it registers the name of the language module with the core, it supplies some preprocessor macro definitions for use in input files (so that they can determine the target language), and it registers a start-up file. In this case, the file <tt>python.swg</tt> will be parsed before any part of the user-supplied input file. +</p> <p> Before proceeding any further, create a directory for your module in the SWIG library (The <tt>Lib</tt> directory). Now, create a configuration file in the directory. For example, <tt>python.swg</tt>. +</p> <p> Just to review, your language module should now consist of two files-- an implementation file <tt>python.cxx</tt> and a configuration file <tt>python.swg</tt>. +</p> -<a name="n36"></a><H3>26.10.5 Entry point to code generation</H3> +<H3><a name="Extending_nn36"></a>28.10.5 Entry point to code generation</H3> +<p> SWIG is a multi-pass compiler. Once the <tt>main()</tt> method has been invoked, the language module does not execute again until preprocessing, parsing, and a variety of semantic analysis passes have @@ -2250,10 +2547,12 @@ been performed. When the core is ready to start generating wrappers, it invokes the <tt>top()</tt> method of your language class. The argument to <tt>top</tt> is a single parse tree node that corresponds to the top of the entire parse tree. +</p> <p> To get the code generation process started, the <tt>top()</tt> procedure needs to do several things: +</p> <ul> <li>Initialize the wrapper code output. @@ -2265,6 +2564,7 @@ to do several things: <p> An outline of <tt>top()</tt> might be as follows: +</p> <blockquote> <pre> @@ -2294,41 +2594,50 @@ int Python::top(Node *n) { </pre> </blockquote> -<a name="n37"></a><H3>26.10.6 Module I/O and wrapper skeleton</H3> +<H3><a name="Extending_nn37"></a>28.10.6 Module I/O and wrapper skeleton</H3> -<a name="n38"></a><H3>26.10.7 Low-level code generators</H3> +<H3><a name="Extending_nn38"></a>28.10.7 Low-level code generators</H3> -<a name="n39"></a><H3>26.10.8 Configuration files</H3> +<H3><a name="Extending_nn39"></a>28.10.8 Configuration files</H3> <!-- please report bugs in this section to ttn --> +<p> At the time of this writing, SWIG supports nearly a dozen languages, which means that for continued sanity in maintaining the configuration files, the language modules need to follow some conventions. These are outlined here along with the admission that, yes it is ok to violate these conventions in minor ways, as long as you know where to apply the proper kludge to keep the overall system regular and running. -Engineering is the art of compromise, see...<p> +Engineering is the art of compromise, see... +</p> +<p> Much of the maintenance regularity depends on choosing a suitable nickname for your language module (and then using it in a controlled way). Nicknames should be all lower case letters with an optional numeric suffix (no underscores, no dashes, no spaces). Some examples -are: <TT>foo</TT>, <TT>bar</TT>, <TT>qux99</TT>.<p> +are: <TT>foo</TT>, <TT>bar</TT>, <TT>qux99</TT>. +</p> +<p> The numeric suffix variant, as in the last example, is somewhat tricky to work with because sometimes people expect to refer to the language without this number but sometimes that number is extremely relevant -(especially when it corresponds to langauge implementation versions with +(especially when it corresponds to language implementation versions with incompatible interfaces). New language modules that unavoidably require a numeric suffix in their nickname should include that number in all -uses, or be prepared to kludge.<p> +uses, or be prepared to kludge. +</p> +<p> The nickname is used in four places: -<TABLE> +</p> + +<TABLE summary="nickname table"> <TR><TD><B>usage</B></TD><TD><B>transform</B></TD></TR> <TR><TD>"skip" tag</TD><TD>(none)</TD></TR> <TR><TD>Examples/ subdir name</TD><TD>(none)</TD></TR> @@ -2337,8 +2646,10 @@ The nickname is used in four places: <TR><TD>Examples/test-suite/ subdir name</TD><TD>(none)</TD></TR> <!-- add more uses here (remember to adjust header) --> </TABLE> + <p> As you can see, most usages are direct. +</p> <dl> @@ -2349,58 +2660,68 @@ to generate the <TT>configure</TT> script. This is where you need to add shell script fragments and autoconf macros to detect the presence of whatever development support your language module requires, typically directories where headers and libraries can be found, and/or -utility programs useful for integrating the generated wrapper code.<p> +utility programs useful for integrating the generated wrapper code. +<p> Use the <TT>AC_ARG_WITH</TT>, <TT>AC_MSG_CHECKING</TT>, <TT>AC_SUBST</TT> macros and so forth (see other languages for examples). Avoid using the <TT>[</TT> and <TT>]</TT> character in shell script fragments. The variable names passed to <TT>AC_SUBST</TT> should begin with the nickname, -entirely upcased.<p> +entirely upcased. +</p> +<p> At the end of the new section is the place to put the aforementioned nickname kludges (should they be needed). See Perl5 and Php4 for examples of what to do. [If this is still unclear after you've read -the code, ping me and I'll expand on this further. --ttn]<p> +the code, ping me and I'll expand on this further. --ttn] +</p> <dt> <b>Makefile.in</b> <dd> Some of the variables AC_SUBSTitutued are essential to the support of your language module. Fashion these into a shell script -"test" clause and assign that to a skip tag using "-z" and "-o":<p> +"test" clause and assign that to a skip tag using "-z" and "-o": <blockquote><tt> skip-qux99 = [ -z "@QUX99INCLUDE@" -o -z "@QUX99LIBS" ] -</tt></blockquote><p> +</tt></blockquote> +<p> This means if those vars should ever be empty, qux99 support should be considered absent and so it would be a good idea to skip actions that -might rely on it.<p> +might rely on it. +</p> +<p> Here is where you may also define an alias (but then you'll need to -kludge --- don't do this):<p> +kludge --- don't do this): +</p> <blockquote><tt> skip-qux = $(skip-qux99) -</tt></blockquote><p> +</tt></blockquote> +<p> Lastly, you need to modify each of <TT>check-aliveness</TT>, <TT>check-examples</TT>, <TT>check-test-suite</TT>, <TT>check-gifplot</TT> (all targets) and <TT>lib-languages</TT> (var). Use the nickname for these, not the alias. Note that you can do this even before you have any tests or examples set up; the Makefile rules do some sanity checking and skip around -these kinds of problems.<p> +these kinds of problems. +</p> <dt> <b>Examples/Makefile.in</b> <dd> Nothing special here; see comments at top the of this file -and look to the existing languages for examples.<p> +and look to the existing languages for examples. <dt> <b>Examples/qux99/check.list</b> <dd> Do <TT>cp ../python/check.list .</TT> and modify to taste. -One subdir per line.<p> +One subdir per line. <dt> <b>Examples/GIFPlot/Qux99/check.list</b> <dd> Do <TT>cp ../Python/check.list .</TT> and modify to taste. -One subdir per line.<p> +One subdir per line. <dt> <b>Lib/qux99/extra-install.list</b> <dd> If you add your language to the top-level Makefile.in var @@ -2408,35 +2729,41 @@ One subdir per line.<p> all <TT>*.i</TT> and <TT>*.swg</TT> files from the language-specific subdirectory of <TT>Lib</TT>. Use (optional) file <TT>extra-install.list</TT> in that directory to name -additional files to install (see ruby for example).<p> +additional files to install (see ruby for example). <dt> <b>Runtime/Makefile.in</b> <dd> Add another <TT>make</TT> invocation to <TT>all</TT>, and -a section for your language module.<p> +a section for your language module. <dt> <b>Source/Modules1.1/Makefile.in</b> <dd> Add appropriate entries for vars <TT>OBJS</TT> and <TT>SRCS</TT>. -That's it!<p> +That's it! </dl> +<p> At some point it would be a good idea to use <A HREF="http://www.gnu.org/software/automake/">automake</A> to handle some of these configuration tasks, but that point is now long past. If you are interested in working on that, feel free to -raise the issue in the context of a next-generation clean-slate SWIG.<p> +raise the issue in the context of a next-generation clean-slate SWIG. -<a name="n40"></a><H3>26.10.9 Runtime support</H3> +<H3><a name="Extending_nn40"></a>28.10.9 Runtime support</H3> +<p> Discuss the kinds of functions typically needed for SWIG runtime support (e.g. <tt>SWIG_ConvertPtr()</tt> and <tt>SWIG_NewPointerObj()</tt>) and the names of the SWIG files that implement those functions. +</p> -<a name="n41"></a><H3>26.10.10 Standard library files</H3> +<H3><a name="Extending_nn41"></a>28.10.10 Standard library files</H3> +<p> Discuss the standard library files that most language modules provide, e.g. +</p> + <ul> <li> typemaps.i </li> <li> std_string.i </li> @@ -2444,39 +2771,50 @@ Discuss the standard library files that most language modules provide, e.g. <li> stl.i </li> </ul> -<a name="n42"></a><H3>26.10.11 Examples and test cases</H3> +<H3><a name="Extending_nn42"></a>28.10.11 Examples and test cases</H3> +<p> Each of the language modules provides one or more examples. These examples are used to demonstrate different features of the language module to SWIG end-users, but you'll find that they're useful during development and testing of your language module as well. You can use examples from the existing SWIG -language modules for inspiration.<p> +language modules for inspiration. +</p> +<p> Each example is self-contained and consists of (at least) a <tt>Makefile</tt>, a SWIG interface file for the example module, and a script that demonstrates the functionality for that module. All of these files are stored in the same subdirectory, and that directory should be nested under <tt>Examples/python</tt>. For example, the files for the Python "simple" example are found in -<tt>Examples/python/simple</tt>.<p> +<tt>Examples/python/simple</tt>. +</p> +<p> By default, all of the examples are built and run when the user types <tt>make check</tt>. To ensure that your examples are automatically run during this process, see the section on <a href="#n37a">configuration files</a>. +</p> -<a name="n43"></a><H3>26.10.12 Documentation</H3> +<H3><a name="Extending_nn43"></a>28.10.12 Documentation</H3> +<p> Don't forget to write end-user documentation for your language module. Currently, each language module has a dedicated chapter (although this structure may change in the future). You shouldn't rehash things that are already covered in sufficient -detail in the <a href="SWIG.html">SWIG Basics</a> and <a href="SWIGPlus.html">SWIG +detail in the <a href="SWIG.html#SWIG">SWIG Basics</a> and <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapters. There is no fixed format for <em>what</em>, exactly, you should document about your language module, but you'll obviously want to cover issues that -are unique to your language.<p> +are unique to your language. +</p> +<p> Some topics that you'll want to be sure to address include: +</p> + <ul> <li> Command line options unique to your language module. <li> Non-obvious mappings between C/C++ and scripting language concepts. @@ -2492,19 +2830,22 @@ Some topics that you'll want to be sure to address include: if available. </ul> -<a name="n44"></a><H2>26.11 Typemaps</H2> +<H2><a name="Extending_nn44"></a>28.11 Typemaps</H2> -<a name="n45"></a><H3>26.11.1 Proxy classes</H3> +<H3><a name="Extending_nn45"></a>28.11.1 Proxy classes</H3> -<a name="n46"></a><H2>26.12 Guide to parse tree nodes</H2> +<H2><a name="Extending_nn46"></a>28.12 Guide to parse tree nodes</H2> +<p> This section describes the different parse tree nodes and their attributes. +</p> <p> <b>cdecl</b> +</p> <blockquote> Describes general C declarations including variables, functions, and typedefs. @@ -2525,6 +2866,8 @@ and D is a declarator. <p> <b>constructor</b> +</p> + <blockquote> C++ constructor declaration. @@ -2540,6 +2883,8 @@ C++ constructor declaration. <p> <b>destructor</b> +</p> + <blockquote> C++ destructor declaration. @@ -2554,6 +2899,8 @@ C++ destructor declaration. <p> <b>access</b> +</p> + <blockquote> C++ access change. @@ -2565,6 +2912,8 @@ C++ access change. <p> <b>constant</b> +</p> + <blockquote> Constant created by %constant or #define. @@ -2579,6 +2928,8 @@ Constant created by %constant or #define. <p> <b>class</b> +</p> + <blockquote> C++ class definition or C structure definition. @@ -2597,6 +2948,8 @@ C++ class definition or C structure definition. <p> <b>enum</b> +</p> + <blockquote> Enumeration. @@ -2611,6 +2964,8 @@ Enumeration. <p> <b>enumitem</b> +</p> + <blockquote> Enumeration value. @@ -2624,6 +2979,8 @@ Enumeration value. <p> <b>namespace</b> +</p> + <blockquote> C++ namespace. @@ -2638,6 +2995,8 @@ C++ namespace. <p> <b>using</b> +</p> + <blockquote> C++ using directive. @@ -2652,6 +3011,8 @@ C++ using directive. <p> <b>classforward</b> +</p> + <blockquote> A forward C++ class declaration. @@ -2664,6 +3025,8 @@ A forward C++ class declaration. <p> <b>insert</b> +</p> + <blockquote> Code insertion directive. For example, %{ ... %} or %insert(section). @@ -2676,6 +3039,8 @@ Code insertion directive. For example, %{ ... %} or <p> <b>top</b> +</p> + <blockquote> Top of the parse tree. @@ -2686,6 +3051,8 @@ Top of the parse tree. <p> <b>extend</b> +</p> + <blockquote> %extend directive. @@ -2697,6 +3064,8 @@ Top of the parse tree. <p> <b>apply</b> +</p> + <blockquote> %apply pattern { patternlist }. @@ -2708,6 +3077,8 @@ Top of the parse tree. <p> <b>clear</b> +</p> + <blockquote> %clear patternlist; @@ -2718,6 +3089,8 @@ Top of the parse tree. <p> <b>include</b> +</p> + <blockquote> %include directive. @@ -2729,6 +3102,8 @@ Top of the parse tree. <p> <b>import</b> +</p> + <blockquote> %import directive. @@ -2741,6 +3116,8 @@ Top of the parse tree. <p> <b>module</b> +</p> + <blockquote> %module directive. @@ -2752,6 +3129,8 @@ Top of the parse tree. <p> <b>typemap</b> +</p> + <blockquote> %typemap directive. @@ -2765,6 +3144,8 @@ Top of the parse tree. <p> <b>typemapcopy</b> +</p> + <blockquote> %typemap directive with copy. @@ -2778,6 +3159,8 @@ Top of the parse tree. <p> <b>typemapitem</b> +</p> + <blockquote> %typemap pattern. Used with %apply, %clear, %typemap. @@ -2789,6 +3172,8 @@ Top of the parse tree. <p> <b>types</b> +</p> + <blockquote> %types directive. @@ -2800,6 +3185,8 @@ Top of the parse tree. <p> <b>extern</b> +</p> + <blockquote> extern "X" { ... } declaration. diff --git a/Doc/Manual/Guile.html b/Doc/Manual/Guile.html index fecd14fd5..5d224295b 100644 --- a/Doc/Manual/Guile.html +++ b/Doc/Manual/Guile.html @@ -7,35 +7,35 @@ <body bgcolor="#ffffff"> -<a name="n1"></a><H1>16 SWIG and Guile</H1> +<H1><a name="Guile"></a>18 SWIG and Guile</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Meaning of "Module"</a> -<li><a href="#n3">Using the SCM or GH Guile API</a> -<li><a href="#n4">Linkage</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_nn4">Linkage</a> <ul> -<li><a href="#n5">Simple Linkage</a> -<li><a href="#n6">Passive Linkage</a> -<li><a href="#n7">Native Guile Module Linkage</a> -<li><a href="#n8">Old Auto-Loading Guile Module Linkage</a> -<li><a href="#n9">Hobbit4D Linkage</a> -<li><a href="#n10">General Remarks on Multiple SWIG Modules</a> +<li><a href="#Guile_nn5">Simple Linkage</a> +<li><a href="#Guile_nn6">Passive Linkage</a> +<li><a href="#Guile_nn7">Native Guile Module Linkage</a> +<li><a href="#Guile_nn8">Old Auto-Loading Guile Module Linkage</a> +<li><a href="#Guile_nn9">Hobbit4D Linkage</a> +<li><a href="#Guile_nn10">General Remarks on Multiple SWIG Modules</a> </ul> -<li><a href="#n11">Underscore Folding</a> -<li><a href="#n12">Typemaps</a> -<li><a href="#n13">Representation of pointers as smobs</a> +<li><a href="#Guile_nn11">Underscore Folding</a> +<li><a href="#Guile_nn12">Typemaps</a> +<li><a href="#Guile_nn13">Representation of pointers as smobs</a> <ul> -<li><a href="#n14">GH Smobs</a> -<li><a href="#n15">SCM Smobs</a> -<li><a href="#n16">Garbage Collection</a> +<li><a href="#Guile_nn14">GH Smobs</a> +<li><a href="#Guile_nn15">SCM Smobs</a> +<li><a href="#Guile_nn16">Garbage Collection</a> </ul> -<li><a href="#n17">Exception Handling</a> -<li><a href="#n18">Procedure documentation</a> -<li><a href="#n19">Procedures with setters</a> -<li><a href="#n20">GOOPS Shadow Classes</a> +<li><a href="#Guile_nn17">Exception Handling</a> +<li><a href="#Guile_nn18">Procedure documentation</a> +<li><a href="#Guile_nn19">Procedures with setters</a> +<li><a href="#Guile_nn20">GOOPS Shadow Classes</a> <ul> -<li><a href="#n21">Naming Issues</a> -<li><a href="#n22">Linking</a> +<li><a href="#Guile_nn21">Naming Issues</a> +<li><a href="#Guile_nn22">Linking</a> </ul> </ul> <!-- INDEX --> @@ -45,7 +45,7 @@ <p> This section details guile-specific support in SWIG. -<a name="n2"></a><H2>16.1 Meaning of "Module"</H2> +<H2><a name="Guile_nn2"></a>18.1 Meaning of "Module"</H2> <p> @@ -53,13 +53,13 @@ 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". -<a name="n3"></a><H2>16.2 Using the SCM or GH Guile API</H2> +<H2><a name="Guile_nn3"></a>18.2 Using the SCM or GH Guile API</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 "-gh" argument -is the default. The "-scm" wrapper generation assumes a guile version >= 1.6 and has several advantages over +is the default. The "-scm" wrapper generation assumes a guile version >= 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. Thus eventually the guile GH wrapper code generation will be depreciated (as guile 1.6 and above become more common) and the @@ -101,7 +101,7 @@ for the specific API. Currently only the guile language module has created a ma 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> -<a name="n4"></a><H2>16.3 Linkage</H2> +<H2><a name="Guile_nn4"></a>18.3 Linkage</H2> <p> @@ -109,7 +109,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>. -<a name="n5"></a><H3>16.3.1 Simple Linkage</H3> +<H3><a name="Guile_nn5"></a>18.3.1 Simple Linkage</H3> The default linkage is the simplest; nothing special is done. In this @@ -170,6 +170,8 @@ Since SWIG doesn't know how to load your extension module (with <code>dynamic-link</code> or <code>load-extension</code>), you need to supply this information by including a directive like this in the interface file: +</p> + <blockquote> <pre> %scheme %{ (load-extension "./example.so" "SWIG_init") %} @@ -185,7 +187,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. -<a name="n6"></a><H3>16.3.2 Passive Linkage</H3> +<H3><a name="Guile_nn6"></a>18.3.2 Passive Linkage</H3> <p>Passive linkage is just like simple linkage, but it generates an @@ -195,7 +197,7 @@ package name (see below). <p>You should use passive linkage rather than simple linkage when you are using multiple modules. -<a name="n7"></a><H3>16.3.3 Native Guile Module Linkage</H3> +<H3><a name="Guile_nn7"></a>18.3.3 Native Guile Module Linkage</H3> <p>SWIG can also generate wrapper code that does all the Guile module @@ -236,7 +238,7 @@ Newer Guile versions have a shorthand procedure for this: </blockquote> </ul> -<a name="n8"></a><H3>16.3.4 Old Auto-Loading Guile Module Linkage</H3> +<H3><a name="Guile_nn8"></a>18.3.4 Old Auto-Loading Guile Module Linkage</H3> <p>Guile used to support an autoloading facility for object-code @@ -262,7 +264,7 @@ option, SWIG generates an exported module initialization function with an appropriate name. -<a name="n9"></a><H3>16.3.5 Hobbit4D Linkage</H3> +<H3><a name="Guile_nn9"></a>18.3.5 Hobbit4D Linkage</H3> <p> @@ -271,6 +273,7 @@ libraries suitable for use by hobbit's <code>(hobbit4d link)</code> guile module. This is called the "hobbit" linkage, and requires also using the "-package" command line option to set the part of the module name before the last symbol. For example, both command lines: +</p> <blockquote> <pre> @@ -279,13 +282,15 @@ swig -guile -package my/lib -module foo foo.i </pre> </blockquote> +<p> would create module <code>(my lib foo)</code> (assuming in the first case foo.i declares the module to be "foo"). The installed files are my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very experimental; the (hobbit4d link) conventions are not well understood. +</p> -<a name="n10"></a><H3>16.3.6 General Remarks on Multiple SWIG Modules</H3> +<H3><a name="Guile_nn10"></a>18.3.6 General Remarks on Multiple SWIG Modules</H3> If you want to use multiple SWIG modules, they have to share some @@ -298,9 +303,9 @@ The remaining modules must be compiled with the with the runtime code. You could create an empty swig module and use that to generate the runtime code instead of placing the runtime code into a module with code that is being wrapped. See the -<a href="#Modules.html">Working with Modules</a> chapter for further details. +<a href="Modules.html#Modules">Working with Modules</a> chapter for further details. -<a name="n11"></a><H2>16.4 Underscore Folding</H2> +<H2><a name="Guile_nn11"></a>18.4 Underscore Folding</H2> <p> @@ -312,7 +317,7 @@ complained so far. <code>%rename</code> to specify the Guile name of the wrapped functions and variables (see CHANGES). -<a name="n12"></a><H2>16.5 Typemaps</H2> +<H2><a name="Guile_nn12"></a>18.5 Typemaps</H2> <p> @@ -343,18 +348,21 @@ By default, if more than one value is to be returned, a list of the values is created and returned; to switch back to this behavior, use <blockquote> -<pre>%values_as_list;</pre> +<pre> +%values_as_list;</pre> </blockquote> <li><em>Multiple values as vectors.</em> By issuing <blockquote> -<pre>%values_as_vector;</pre> +<pre> +%values_as_vector;</pre> </blockquote> vectors instead of lists will be used. <li><em>Multiple values for multiple-value continuations.</em> <strong>This is the most elegant way.</strong> By issuing <blockquote> -<pre>%multiple_values;</pre> +<pre> +%multiple_values;</pre> </blockquote> multiple values are passed to the multiple-value continuation, as created by <code>call-with-values</code> or the @@ -375,7 +383,7 @@ In <code><var>body</var></code>, the first result of </ul> See also the "multivalue" example. -<a name="n13"></a><H2>16.6 Representation of pointers as smobs</H2> +<H2><a name="Guile_nn13"></a>18.6 Representation of pointers as smobs</H2> <p> @@ -392,11 +400,11 @@ upper half of the CAR is read from this struct. To get the pointer represented by a smob, the wrapper code calls the function <code>SWIG_ConvertPtr()</code>, passing a pointer to a struct representing the expected pointer type. See also -<a href="Typemaps.html#n41">Section 8.8 The run-time type checker</a>. +<a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>. If the Scheme object passed was not a SWIG smob representing a compatible pointer, a <code>wrong-type-arg</code> exception is raised. -<a name="n14"></a><H3>16.6.1 GH Smobs</H3> +<H3><a name="Guile_nn14"></a>18.6.1 GH Smobs</H3> <p> @@ -415,7 +423,7 @@ available. <code>SWIG_Guile_Init()</code> registers a smob type named a table of all C pointer types seen so far, to which new types seen are appended. The CDR stores the pointer value. -<a name="n15"></a><H3>16.6.2 SCM Smobs</H3> +<H3><a name="Guile_nn15"></a>18.6.2 SCM Smobs</H3> <p>The SCM interface (using the "-scm" argument to swig) uses common.swg. @@ -430,7 +438,7 @@ in the smob tag. If a generated GOOPS module has been loaded, smobs will be wra GOOPS class.</p> -<a name="n16"></a><H3>16.6.3 Garbage Collection</H3> +<H3><a name="Guile_nn16"></a>18.6.3 Garbage Collection</H3> <p>Garbage collection is a feature of the new SCM interface, and it is automatically included @@ -440,11 +448,11 @@ to the destructor for this type. The destructor is the generated wrapper around So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for the wrapped delete function. So the only way to delete an object is from the garbage collector, since the delete function is not available to scripts. How swig determines if a type should be garbage collected -is exactly like described in <a href="Customization.html#n9"> -Section 9.2 Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and +is exactly like described in <a href="Customization.html#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> -<a name="n17"></a><H2>16.7 Exception Handling</H2> +<H2><a name="Guile_nn17"></a>18.7 Exception Handling</H2> <p> @@ -468,7 +476,7 @@ mapping: The default when not specified here is to use "swig-error". See Lib/exception.i for details. -<a name="n18"></a><H2>16.8 Procedure documentation</H2> +<H2><a name="Guile_nn18"></a>18.8 Procedure documentation</H2> <p>If invoked with the command-line option <code>-procdoc @@ -501,7 +509,7 @@ like this: typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for details. -<a name="n19"></a><H2>16.9 Procedures with setters</H2> +<H2><a name="Guile_nn19"></a>18.9 Procedures with setters</H2> <p>For global variables, SWIG creates a single wrapper procedure @@ -529,7 +537,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. -<a name="n20"></a><H2>16.10 GOOPS Shadow Classes</H2> +<H2><a name="Guile_nn20"></a>18.10 GOOPS Shadow Classes</H2> <p>SWIG can also generate classes and generic functions for use with @@ -551,7 +559,8 @@ current directory. GOOPS support requires either passive or module linkage.</p> <p>If <code>-emit-slot-accessors</code> is also passed as an argument, then the generated file will contain accessor methods for all the slots in the classes and for global variables. The input class</p> -<blockquote><pre> class Foo { +<blockquote><pre> + class Foo { public: Foo(int i) : a(i) {} int a; @@ -561,7 +570,8 @@ slots in the classes and for global variables. The input class</p> Foo getFooPlus(int i) { return Foo(a + i); } </pre></blockquote> will produce (if <code>-emit-slot-accessors</code> is not passed as a parameter) -<blockquote><pre>(define-class <Foo> (<swig>) +<blockquote><pre> +(define-class <Foo> (<swig>) (a #:allocation #:swig-virtual #:slot-ref primitive:Foo-a-get #:slot-set! primitive:Foo-a-set) @@ -579,7 +589,8 @@ will produce (if <code>-emit-slot-accessors</code> is not passed as a parameter) (export <Foo> getMultBy getFooMultBy getFooPlus ) </pre></blockquote> and will produce (if <code>-emit-slot-accessors</code> is passed as a parameter) -<blockquote><pre>(define-class <Foo> (<swig>) +<blockquote><pre> +(define-class <Foo> (<swig>) (a #:allocation #:swig-virtual #:slot-ref primitive:Foo-a-get #:slot-set! primitive:Foo-a-set @@ -620,7 +631,8 @@ which can then be used by this code the future the following will be valid <code>(make <Foo> #:a 5 #:b 4)</code></p> <p>Also note that the order the declarations occur in the .i file make a difference. For example, -</p><blockquote><pre>%module test +</p><blockquote><pre> +%module test %{ #include "foo.h" %} @@ -636,7 +648,8 @@ This is a valid SWIG file it will work as you think it will for primitive suppor GOOPS file will be broken. Since the <code>someFunc</code> definition is parsed by SWIG before all the declarations in foo.h, the generated GOOPS file will contain the definition of <code>someFunc()</code> before the definition of <Foo>. The generated GOOPS file would look like -<blockquote><pre>;;... +<blockquote><pre> +;;... (define-method (someFunc (swig_smob <Foo>)) (primitive:someFunc (slot-ref swig_smob 'smob))) @@ -652,7 +665,7 @@ before the definition of <Foo>. The generated GOOPS file would look like Notice that <Foo> is used before it is defined. The fix is to just put the <code>%import "foo.h"</code> before the <code>%inline</code> block. -<a name="n21"></a><H3>16.10.1 Naming Issues</H3> +<H3><a name="Guile_nn21"></a>18.10.1 Naming Issues</H3> <p>As you can see in the example above, there are potential naming conflicts. The default exported @@ -679,18 +692,19 @@ The second generated guile-module contains all the GOOPS class definitions and i a file named <i>module</i>.scm in the directory specified with -outdir or the current directory. The name of this guile-module is the name of the swig-module (given on the command line or with the <code>%module</code> directive). -In the previous example, the GOOPS definitions will be in a file named Test.scm.</p><p> +In the previous example, the GOOPS definitions will be in a file named Test.scm.</p> -</p><p>Because of the naming conflicts, you can't in general use both the <code>-primitive</code> and the GOOPS +<p>Because of the naming conflicts, you can't in general use both the <code>-primitive</code> and the GOOPS guile-modules at the same time. To do this, you need to rename the exported symbols from one or both guile-modules. For example,</p> -<blockquote><pre>(use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:))) +<blockquote><pre> +(use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:))) (use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:))) </pre></blockquote> <p>TODO: Renaming class name prefixes?</p> -<a name="n22"></a><H3>16.10.2 Linking</H3> +<H3><a name="Guile_nn22"></a>18.10.2 Linking</H3> <p>The guile-modules generated above all need to be linked together. GOOPS support requires @@ -710,18 +724,22 @@ 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.</li> -<blockquote><pre>%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %} +The <code>%goops</code> directive should contain code to load the .so library. + +<blockquote><pre> +%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %} </pre></blockquote> Produces the following code at the top of the generated GOOPS guile-module (with the <code>-package my/modules -module foo</code> command line arguments) -<blockquote><pre>(define-module (my modules foo)) +<blockquote><pre> +(define-module (my modules foo)) ;; %goops directive goes here (load-extension "./foo.so" "scm_init_my_modules_foo_module") (use-modules (oop goops) (Swig common)) </pre></blockquote> +</li> <li><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> @@ -730,8 +748,10 @@ 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 <code>%goops</code> directive can be empty. Otherwise, the <code>%goops</code> directive should contain -whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</li> -<blockquote><pre>%scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %} +whatever code is needed to load the <i>Module-primitive.scm</i> file into guile. + +<blockquote><pre> +%scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %} // only include the following definition if (my modules foo) cannot // be loaded automatically %goops %{ @@ -740,7 +760,8 @@ whatever code is needed to load the <i>Module-primitive.scm</i> file into guile. %} </pre></blockquote> Produces the following code at the top of the generated GOOPS guile-module -<blockquote><pre>(define-module (my modules foo)) +<blockquote><pre> +(define-module (my modules foo)) ;; %goops directive goes here (if any) (primitive-load "/path/to/foo-primitive.scm") @@ -751,15 +772,21 @@ Produces the following code at the top of the generated GOOPS guile-module 'primitive:))) </pre></blockquote> +</li> <li><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file. Swig will also automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code> into the GOOPS guile-module. Again the <code>%goops</code> -directive should contain whatever code is needed to get that module loaded into guile.</li> -<blockquote><pre>%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %} +directive should contain whatever code is needed to get that module loaded into guile. + +<blockquote><pre> +%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %} </pre></blockquote> + Produces the following code at the top of the generated GOOPS guile-module -<blockquote><pre>(define-module (my modules foo)) + +<blockquote><pre> +(define-module (my modules foo)) ;; %goops directive goes here (if any) (load-extension "./foo.so" "scm_init_my_modules_foo_module") @@ -769,6 +796,7 @@ Produces the following code at the top of the generated GOOPS guile-module 'primitive:))) </pre></blockquote> +</li> </ul> <p><b>(Swig common)</b>: The generated GOOPS guile-module also imports definitions from the diff --git a/Doc/Manual/Introduction.html b/Doc/Manual/Introduction.html index b18e5ee85..67aca32e1 100644 --- a/Doc/Manual/Introduction.html +++ b/Doc/Manual/Introduction.html @@ -5,29 +5,29 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>1 Introduction</H1> +<H1><a name="Introduction"></a>2 Introduction</H1> <!-- INDEX --> <ul> -<li><a href="#n2">What is SWIG?</a> -<li><a href="#n3">Why use SWIG?</a> -<li><a href="#n4">A SWIG example</a> +<li><a href="#Introduction_nn2">What is SWIG?</a> +<li><a href="#Introduction_nn3">Why use SWIG?</a> +<li><a href="#Introduction_nn4">A SWIG example</a> <ul> -<li><a href="#n5">SWIG interface file</a> -<li><a href="#n6">The swig command</a> -<li><a href="#n7">Building a Perl5 module</a> -<li><a href="#n8">Building a Python module</a> -<li><a href="#n9">Shortcuts</a> +<li><a href="#Introduction_nn5">SWIG interface file</a> +<li><a href="#Introduction_nn6">The swig command</a> +<li><a href="#Introduction_nn7">Building a Perl5 module</a> +<li><a href="#Introduction_nn8">Building a Python module</a> +<li><a href="#Introduction_nn9">Shortcuts</a> </ul> -<li><a href="#n10">Supported C/C++ language features</a> -<li><a href="#n11">Non-intrusive interface building</a> -<li><a href="#n12">Hands off code generation</a> -<li><a href="#n13">SWIG and freedom</a> +<li><a href="#Introduction_nn10">Supported C/C++ language features</a> +<li><a href="#Introduction_nn11">Non-intrusive interface building</a> +<li><a href="#Introduction_nn12">Hands off code generation</a> +<li><a href="#Introduction_nn13">SWIG and freedom</a> </ul> <!-- INDEX --> -<a name="n2"></a><H2>1.1 What is SWIG?</H2> +<H2><a name="Introduction_nn2"></a>2.1 What is SWIG?</H2> SWIG is a software development tool that simplifies the task of @@ -39,7 +39,6 @@ requires no modifications to existing code and can often be used to build a usable interface in only a few minutes. Possible applications of SWIG include: -<p> <ul> <li>Building interpreted interfaces to existing C programs. <li>Rapid prototyping and application development. @@ -65,7 +64,7 @@ project, it is particularly well suited to software development in the small; especially the research and development work that is commonly found in scientific and engineering projects. -<a name="n3"></a><H2>1.2 Why use SWIG?</H2> +<H2><a name="Introduction_nn3"></a>2.2 Why use SWIG?</H2> As stated in the previous section, the primary purpose of SWIG is to simplify @@ -110,7 +109,6 @@ From the standpoint of C/C++, a lot of people use SWIG because they want to brea out of the traditional monolithic C programming model which usually results in programs that resemble this: -<p> <ul> <li>A collection of functions and variables that do something useful. <li>A <tt>main()</tt> program that starts everything. @@ -131,16 +129,15 @@ other. At the same time, SWIG recognizes that all applications are different. 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 ;-). -<p> -<a name="n4"></a><H2>1.3 A SWIG example</H2> +<H2><a name="Introduction_nn4"></a>2.3 A SWIG example</H2> The best way to illustrate SWIG is with a simple example. Consider the -following C code: <p> +following C code: -<p> -<blockquote><pre>/* File : example.c */ +<blockquote><pre> +/* File : example.c */ double My_variable = 3.0; @@ -160,9 +157,9 @@ int my_mod(int n, int m) { Suppose that you wanted to access these functions and the global 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) : <p> +suffix) : -<a name="n5"></a><H3>1.3.1 SWIG interface file</H3> +<H3><a name="Introduction_nn5"></a>2.3.1 SWIG interface file</H3> <blockquote><pre> @@ -182,16 +179,16 @@ The interface file contains ANSI C function prototypes and variable declarations. The <tt>%module</tt> directive defines the name of the 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. <p> +files or additional C declarations. -<a name="n6"></a><H3>1.3.2 The swig command</H3> +<H3><a name="Introduction_nn6"></a>2.3.2 The swig command</H3> SWIG is invoked using the <tt>swig</tt> command. We can use this to -build a Tcl module (under Linux) as follows :<p> +build a Tcl module (under Linux) as follows : -<p> -<blockquote><pre>unix > <b>swig -tcl example.i</b> +<blockquote><pre> +unix > <b>swig -tcl example.i</b> unix > <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include</b> unix > <b>gcc -shared example.o example_wrap.o -o example.so</b> unix > <b>tclsh</b> @@ -214,17 +211,16 @@ Tcl module has been compiled into a shared library that can be loaded into Tcl. When loaded, Tcl can now access the functions 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.<p> +almost never need to worry about it. -<a name="n7"></a><H3>1.3.3 Building a Perl5 module</H3> +<H3><a name="Introduction_nn7"></a>2.3.3 Building a Perl5 module</H3> Now, let's turn these functions into a Perl5 module. Without making -any changes type the following (shown for Solaris):<p> +any changes type the following (shown for Solaris): -<p> -<p> -<blockquote><pre>unix > <b>swig -perl5 example.i</b> +<blockquote><pre> +unix > <b>swig -perl5 example.i</b> unix > <b>gcc -c example.c example_wrap.c \ -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b> unix > <b>ld -G example.o example_wrap.o -o example.so</b> # This is for Solaris @@ -241,13 +237,13 @@ unix > </pre></blockquote> -<a name="n8"></a><H3>1.3.4 Building a Python module</H3> +<H3><a name="Introduction_nn8"></a>2.3.4 Building a Python module</H3> -Finally, let's build a module for Python (shown for Irix).<p> +Finally, let's build a module for Python (shown for Irix). -<p> -<blockquote><pre>unix > <b>swig -python example.i</b> +<blockquote><pre> +unix > <b>swig -python example.i</b> unix > <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include/python2.0</b> unix > <b>gcc -shared example.o example_wrap.o -o _example.so</b> unix > <b>python</b> @@ -263,16 +259,16 @@ Type "copyright", "credits" or "license" for more information. 7.5 </pre></blockquote> -<a name="n9"></a><H3>1.3.5 Shortcuts</H3> +<H3><a name="Introduction_nn9"></a>2.3.5 Shortcuts</H3> To the truly lazy programmer, one may wonder why we needed the extra interface file at all. As it turns out, you can often do without it. For example, you could also build a Perl5 module by just running -SWIG on the C header file and specifying a module name as follows<p> +SWIG on the C header file and specifying a module name as follows -<p> -<blockquote><pre>unix > <b>swig -perl5 -module example example.h</b> +<blockquote><pre> +unix > <b>swig -perl5 -module example example.h</b> unix > <b>gcc -c example.c example_wrap.c \ -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b> unix > <b>ld -G example.o example_wrap.o -o example.so</b> @@ -287,7 +283,7 @@ print $example::My_variable + 4.5, "\n"; 7.5 </pre></blockquote> -<a name="n10"></a><H2>1.4 Supported C/C++ language features</H2> +<H2><a name="Introduction_nn10"></a>2.4 Supported C/C++ language features</H2> A primary goal of the SWIG project is to make the language binding @@ -323,7 +319,7 @@ wrapping simple C++ code. In fact, SWIG is able handle C++ code that stresses the very limits of many C++ compilers. -<a name="n11"></a><H2>1.5 Non-intrusive interface building</H2> +<H2><a name="Introduction_nn11"></a>2.5 Non-intrusive interface building</H2> When used as intended, SWIG requires minimal (if any) modification to @@ -333,7 +329,7 @@ the C code independent of the high level interface, you can change the interface and reuse the code in other applications. It is also possible to support different types of interfaces depending on the application. -<a name="n12"></a><H2>1.6 Hands off code generation</H2> +<H2><a name="Introduction_nn12"></a>2.6 Hands off code generation</H2> SWIG is designed to produce working code that needs no @@ -346,7 +342,7 @@ file. While this approach may limit flexibility for hard-core hackers, it allows others to forget about the low-level implementation details. -<a name="n13"></a><H2>1.7 SWIG and freedom</H2> +<H2><a name="Introduction_nn13"></a>2.7 SWIG and freedom</H2> No, this isn't a special section on the sorry state of world politics. @@ -371,8 +367,7 @@ 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. -<p><hr> - +<hr> <address>SWIG 1.3 - Last Modified : August 10, 2002</address> </body> </html> diff --git a/Doc/Manual/Java.html b/Doc/Manual/Java.html index 34a44ee52..a67551d57 100644 --- a/Doc/Manual/Java.html +++ b/Doc/Manual/Java.html @@ -4,130 +4,130 @@ <title>SWIG and Java</title> </head> <body bgcolor="#FFFFFF"> -<a name="n1"></a><H1>17 SWIG and Java</H1> +<H1><a name="Java"></a>19 SWIG and Java</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Overview</a> -<li><a href="#n3">Preliminaries</a> +<li><a href="#java_overview">Overview</a> +<li><a href="#java_preliminaries">Preliminaries</a> <ul> -<li><a href="#n4">Running SWIG</a> -<li><a href="#n5">Additional Commandline Options</a> -<li><a href="#n6">Getting the right header files</a> -<li><a href="#n7">Compiling a dynamic module</a> -<li><a href="#n8">Using your module</a> -<li><a href="#n9">Dynamic linking problems</a> -<li><a href="#n10">Compilation problems and compiling with C++</a> -<li><a href="#n11">Building on Windows</a> +<li><a href="#running_swig">Running SWIG</a> +<li><a href="#java_commandline">Additional Commandline Options</a> +<li><a href="#getting_right_headers">Getting the right header files</a> +<li><a href="#compiling_dynamic">Compiling a dynamic module</a> +<li><a href="#using_module">Using your module</a> +<li><a href="#dynamic_linking_problems">Dynamic linking problems</a> +<li><a href="#compilation_problems_cpp">Compilation problems and compiling with C++</a> +<li><a href="#building_windows">Building on Windows</a> <ul> -<li><a href="#n12">Running SWIG from Visual Studio</a> -<li><a href="#n13">Using NMAKE</a> +<li><a href="#visual_studio">Running SWIG from Visual Studio</a> +<li><a href="#nmake">Using NMAKE</a> </ul> </ul> -<li><a href="#n14">A tour of basic C/C++ wrapping</a> +<li><a href="#java_basic_tour">A tour of basic C/C++ wrapping</a> <ul> -<li><a href="#n15">Modules, packages and generated Java classes</a> -<li><a href="#n16">Functions</a> -<li><a href="#n17">Global variables</a> -<li><a href="#n18">Constants</a> -<li><a href="#n19">Enumerations</a> +<li><a href="#module_packages_classes">Modules, packages and generated Java classes</a> +<li><a href="#functions">Functions</a> +<li><a href="#global_variables">Global variables</a> +<li><a href="#constants">Constants</a> +<li><a href="#enumerations">Enumerations</a> <ul> -<li><a href="#n20">Anonymous enums</a> -<li><a href="#n21">Typesafe enums</a> -<li><a href="#n22">Proper Java enums</a> -<li><a href="#n23">Type unsafe enums</a> -<li><a href="#n24">Simple enums</a> +<li><a href="#anonymous_enums">Anonymous enums</a> +<li><a href="#typesafe_enums">Typesafe enums</a> +<li><a href="#proper_enums">Proper Java enums</a> +<li><a href="#typeunsafe_enums">Type unsafe enums</a> +<li><a href="#simple_enums">Simple enums</a> </ul> -<li><a href="#n25">Pointers</a> -<li><a href="#n26">Structures</a> -<li><a href="#n27">C++ classes</a> -<li><a href="#n28">C++ inheritance</a> -<li><a href="#n29">Pointers, references, arrays and pass by value</a> +<li><a href="#pointers">Pointers</a> +<li><a href="#structures">Structures</a> +<li><a href="#classes">C++ classes</a> +<li><a href="#inheritance">C++ inheritance</a> +<li><a href="#pointers_refs_arrays">Pointers, references, arrays and pass by value</a> <ul> -<li><a href="#n30">Null pointers</a> +<li><a href="#null_pointers">Null pointers</a> </ul> -<li><a href="#n31">C++ overloaded functions</a> -<li><a href="#n32">C++ namespaces</a> -<li><a href="#n33">C++ templates</a> -<li><a href="#n34">C++ Smart Pointers</a> +<li><a href="#overloaded_functions">C++ overloaded functions</a> +<li><a href="#namespaces">C++ namespaces</a> +<li><a href="#templates">C++ templates</a> +<li><a href="#smart_pointers">C++ Smart Pointers</a> </ul> -<li><a href="#n35">Further details on the generated Java classes</a> +<li><a href="#further_details">Further details on the generated Java classes</a> <ul> -<li><a href="#n36">The intermediary JNI class</a> +<li><a href="#imclass">The intermediary JNI class</a> <ul> -<li><a href="#n37">The intermediary JNI class pragmas</a> +<li><a href="#imclass_pragmas">The intermediary JNI class pragmas</a> </ul> -<li><a href="#n38">The Java module class</a> +<li><a href="#java_module_class">The Java module class</a> <ul> -<li><a href="#n39">The Java module class pragmas</a> +<li><a href="#module_class_pragmas">The Java module class pragmas</a> </ul> -<li><a href="#n40">Java proxy classes</a> +<li><a href="#java_proxy_classes">Java proxy classes</a> <ul> -<li><a href="#n41">Memory management</a> -<li><a href="#n42">Inheritance</a> -<li><a href="#n43">Proxy classes and garbage collection</a> +<li><a href="#memory_management">Memory management</a> +<li><a href="#inheritance_mirroring">Inheritance</a> +<li><a href="#proxy_classes_gc">Proxy classes and garbage collection</a> </ul> -<li><a href="#n44">Type wrapper classes</a> -<li><a href="#n45">Enum classes</a> +<li><a href="#type_wrapper_classes">Type wrapper classes</a> +<li><a href="#enum_classes">Enum classes</a> <ul> -<li><a href="#n46">Typesafe enum classes</a> -<li><a href="#n47">Proper Java enum classes</a> -<li><a href="#n48">Type unsafe enum classes</a> +<li><a href="#typesafe_enums_classes">Typesafe enum classes</a> +<li><a href="#proper_enums_classes">Proper Java enum classes</a> +<li><a href="#typeunsafe_enums_classes">Type unsafe enum classes</a> </ul> </ul> -<li><a href="#n49">Cross language polymorphism using directors (experimental)</a> +<li><a href="#java_directors">Cross language polymorphism using directors (experimental)</a> <ul> -<li><a href="#n50">Enabling directors</a> -<li><a href="#n51">Director classes</a> -<li><a href="#n52">Overhead and code bloat</a> -<li><a href="#n53">Simple directors example</a> +<li><a href="#java_enabling_directors">Enabling directors</a> +<li><a href="#java_directors_classes">Director classes</a> +<li><a href="#java_directors_overhead">Overhead and code bloat</a> +<li><a href="#java_directors_example">Simple directors example</a> </ul> -<li><a href="#n54">Common customization features</a> +<li><a href="#common_customization">Common customization features</a> <ul> -<li><a href="#n55">C/C++ helper functions</a> -<li><a href="#n56">Class extension with %extend</a> -<li><a href="#n57">Exception handling with %exception and %javaexception</a> -<li><a href="#n58">Method access with %javamethodmodifiers</a> +<li><a href="#helper_functions">C/C++ helper functions</a> +<li><a href="#class_extension">Class extension with %extend</a> +<li><a href="#exception_handling">Exception handling with %exception and %javaexception</a> +<li><a href="#method_access">Method access with %javamethodmodifiers</a> </ul> -<li><a href="#n59">Tips and techniques</a> +<li><a href="#tips_techniques">Tips and techniques</a> <ul> -<li><a href="#n60">Input and output parameters using primitive pointers and references</a> -<li><a href="#n61">Simple pointers</a> -<li><a href="#n62">Wrapping C arrays with Java arrays</a> -<li><a href="#n63">Unbounded C Arrays</a> +<li><a href="#input_output_parameters">Input and output parameters using primitive pointers and references</a> +<li><a href="#simple_pointers">Simple pointers</a> +<li><a href="#c_arrays">Wrapping C arrays with Java arrays</a> +<li><a href="#unbounded_c_arrays">Unbounded C Arrays</a> </ul> -<li><a href="#n64">Java typemaps</a> +<li><a href="#java_typemaps">Java typemaps</a> <ul> -<li><a href="#n65">Default primitive type mappings</a> -<li><a href="#n66">Sixty four bit JVMs</a> -<li><a href="#n67">What is a typemap?</a> -<li><a href="#n68">Typemaps for mapping C/C++ types to Java types</a> -<li><a href="#n69">Java typemap attributes</a> -<li><a href="#n70">Java special variables</a> -<li><a href="#n71">Typemaps for both C and C++ compilation</a> -<li><a href="#n72">Java code typemaps</a> -<li><a href="#n73">Director specific typemaps</a> +<li><a href="#default_primitive_type_mappings">Default primitive type mappings</a> +<li><a href="#jvm64">Sixty four bit JVMs</a> +<li><a href="#what_is_typemap">What is a typemap?</a> +<li><a href="#typemaps_c_to_java_types">Typemaps for mapping C/C++ types to Java types</a> +<li><a href="#typemap_attributes">Java typemap attributes</a> +<li><a href="#special_variables">Java special variables</a> +<li><a href="#typemaps_for_c_and_c++">Typemaps for both C and C++ compilation</a> +<li><a href="#java_code_typemaps">Java code typemaps</a> +<li><a href="#java_directors_typemaps">Director specific typemaps</a> </ul> -<li><a href="#n74">Typemap Examples</a> +<li><a href="#typemap_examples">Typemap Examples</a> <ul> -<li><a href="#n75">Simpler Java enums for enums without initializers</a> -<li><a href="#n76">Handling C++ exception specifications as Java exceptions</a> -<li><a href="#n77">NaN Exception - exception handling for a particular type</a> -<li><a href="#n78">Converting Java String arrays to char ** </a> -<li><a href="#n79">Expanding a Java object to multiple arguments</a> -<li><a href="#n80">Using typemaps to return arguments</a> -<li><a href="#n81">Adding Java downcasts to polymorphic return types</a> -<li><a href="#n82">Adding an equals method to the Java classes</a> -<li><a href="#n83">Void pointers and a common Java base class</a> +<li><a href="#simpler_enum_classes">Simpler Java enums for enums without initializers</a> +<li><a href="#exception_typemap">Handling C++ exception specifications as Java exceptions</a> +<li><a href="#nan_exception_typemap">NaN Exception - exception handling for a particular type</a> +<li><a href="#converting_java_string_arrays">Converting Java String arrays to char ** </a> +<li><a href="#expanding_java_object">Expanding a Java object to multiple arguments</a> +<li><a href="#using_typemaps_return_arguments">Using typemaps to return arguments</a> +<li><a href="#adding_downcasts">Adding Java downcasts to polymorphic return types</a> +<li><a href="#adding_equals_method">Adding an equals method to the Java classes</a> +<li><a href="#void_pointers">Void pointers and a common Java base class</a> </ul> -<li><a href="#n84">Living with Java Directors</a> -<li><a href="#n85">Odds and ends</a> +<li><a href="#java_directors_faq">Living with Java Directors</a> +<li><a href="#odds_ends">Odds and ends</a> <ul> -<li><a href="#n86">JavaDoc comments</a> -<li><a href="#n87">Functional interface without proxy classes</a> -<li><a href="#n88">Using your own JNI functions</a> -<li><a href="#n89">Performance concerns and hints</a> +<li><a href="#javadoc_comments">JavaDoc comments</a> +<li><a href="#functional_interface">Functional interface without proxy classes</a> +<li><a href="#using_own_jni_functions">Using your own JNI functions</a> +<li><a href="#performance">Performance concerns and hints</a> </ul> -<li><a href="#n90">Examples</a> +<li><a href="#java_examples">Examples</a> </ul> <!-- INDEX --> @@ -137,10 +137,10 @@ This chapter describes SWIG's support of Java. It covers most SWIG features, but certain low-level details are covered in less depth than in earlier chapters. -<a name="overview"></a> -<a name="n2"></a><H2>17.1 Overview</H2> +<H2><a name="java_overview"></a>19.1 Overview</H2> +<p> The 100% Pure Java effort is a commendable concept, however in the real world programmers often either need to re-use their existing code or in some situations want to take advantage of Java but are forced into using some native (C/C++) code. The Java extension to SWIG makes it very easy to plumb in existing C/C++ code for access from Java, as SWIG writes the Java Native Interface (JNI) code for you. @@ -150,17 +150,18 @@ If only one or two JNI functions are needed then using SWIG may be overkill. SWIG enables a Java program to easily call into C/C++ code from Java. Historically, SWIG was not able to generate any code to call into Java code from C++. However, SWIG now supports full cross language polymorphism and code is generated to call up from C++ to Java when wrapping C++ virtual methods. +</p> <p> - Java is one of the few non-scripting language modules in SWIG. As SWIG utilizes the type safety that the Java language offers, it takes a somewhat different approach to that used for scripting languages. In particular runtime type checking and the runtime library are not used by Java. This should be borne in mind when reading the rest of the SWIG documentation. This chapter on Java is relatively self contained and will provide you with nearly everything you need for using SWIG and Java. -However, the "<a href="SWIG.html">SWIG Basics</a>" chapter will be a useful read in conjunction with this one. -<p> +However, the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter will be a useful read in conjunction with this one. +</p> +<p> This chapter starts with a few practicalities on running SWIG and compiling the generated code. If you are looking for the minimum amount to read, have a look at the sections up to and including the <a href="#java_basic_tour">tour of basic C/C++ wrapping</a> section which explains how to call the various C/C++ code constructs from Java. @@ -169,24 +170,25 @@ Due to the complexities of C and C++ there are different ways in which C/C++ cod SWIG is a powerful tool and the rest of the chapter details how the default code wrapping can be tailored. Various customisation tips and techniques using SWIG directives are covered. The latter sections cover the advanced techniques of using typemaps for complete control of the wrapping process. +</p> -<a name="preliminaries"></a> -<a name="n3"></a><H2>17.2 Preliminaries</H2> +<H2><a name="java_preliminaries"></a>19.2 Preliminaries</H2> +<p> SWIG 1.1 works with JDKs from JDK 1.1 to JDK1.4 (Java 2 SDK1.4) and should also work with any later versions. Given the choice, you should probably use the latest version of Sun's JDK. The SWIG Java module is known to work using Sun's JVM on Solaris, Linux and the various flavours of Microsoft Windows including Cygwin. The Kaffe JVM is known to give a few problems and at the time of writing was not a fully fledged JVM with full JNI support. The generated code is also known to work on vxWorks using WindRiver's PJava 3.1. The best way to determine whether your combination of operating system and JDK will work is to test the examples and test-suite that comes with SWIG. -Run <tt>make -k check</tt> from the SWIG root directory after installing SWIG on Unix systems. <p> +Run <tt>make -k check</tt> from the SWIG root directory after installing SWIG on Unix systems. </p> +<p> The Java module requires your system to support shared libraries and dynamic loading. -This is the commonly used method to load JNI code so your system will more than likely support this.<p> +This is the commonly used method to load JNI code so your system will more than likely support this.</p> -<a name="running_swig"></a> -<a name="n4"></a><H3>17.2.1 Running SWIG</H3> +<H3><a name="running_swig"></a>19.2.1 Running SWIG</H3> Suppose that you defined a SWIG module such as the following: @@ -202,16 +204,19 @@ int fact(int n); </blockquote> -To build a Java module, run SWIG using the <tt>-java</tt> option :<p> +<p> +To build a Java module, run SWIG using the <tt>-java</tt> option :</p> -<blockquote><pre>%swig -java example.i +<blockquote><pre> +%swig -java example.i </pre></blockquote> -<p> +<p> If building C++, add the <tt>-c++</tt> option: +</p> -<p> -<blockquote><pre>$ swig -c++ -java example.i +<blockquote><pre> +$ swig -c++ -java example.i </pre></blockquote> This creates two different files; a C/C++ source file <tt>example_wrap.c</tt> or @@ -224,16 +229,17 @@ The name of the wrapper file is derived from the name of the input file. For ex input file is <tt>example.i</tt>, the name of the wrapper file is <tt>example_wrap.c</tt>. To change this, you can use the <tt>-o</tt> option. It is also possible to change the <a href="SWIG.html#output">output directory </a> that the Java files are generated into using <tt>-outdir</tt>. +</p> -<a name="commandline"></a> -<a name="n5"></a><H3>17.2.2 Additional Commandline Options</H3> +<H3><a name="java_commandline"></a>19.2.2 Additional Commandline Options</H3> The following table list the additional commandline options available for the Java module. They can also be seen by using: -<blockquote><pre>swig -java -help +<blockquote><pre> +swig -java -help </pre></blockquote> -<table> +<table summary="Java specific options"> <tr> <th>Java specific options</th> </tr> @@ -252,34 +258,35 @@ The following table list the additional commandline options available for the Ja <br> Their use will become clearer by the time you have finished reading this section on SWIG and Java. -<a name="getting_right_headers"></a> -<a name="n6"></a><H3>17.2.3 Getting the right header files</H3> +<H3><a name="getting_right_headers"></a>19.2.3 Getting the right header files</H3> -In order to compile the C/C++ wrappers, the compiler needs the <tt>jni.h</tt> and <tt>jni_md.h</tt> header files which are part of the JDK. -They are usually in directories like this:<p> <p> +In order to compile the C/C++ wrappers, the compiler needs the <tt>jni.h</tt> and <tt>jni_md.h</tt> header files which are part of the JDK. +They are usually in directories like this:</p> + <blockquote><pre> /usr/java/include /usr/java/include/<operating_system> </pre></blockquote> -<p> -The exact location may vary on your machine, but the above locations are typical. <p> +<p> +The exact location may vary on your machine, but the above locations are typical. </p> -<a name="compiling_dynamic"></a> -<a name="n7"></a><H3>17.2.4 Compiling a dynamic module</H3> +<H3><a name="compiling_dynamic"></a>19.2.4 Compiling a dynamic module</H3> -The JNI code exists in a dynamic module or shared library (DLL on Windows) and gets loaded by the JVM. -To build a shared library file, you need to compile your module in a manner similar to the following (shown for Solaris):<p> <p> +The JNI code exists in a dynamic module or shared library (DLL on Windows) and gets loaded by the JVM. +To build a shared library file, you need to compile your module in a manner similar to the following (shown for Solaris):</p> + <blockquote><pre> $ swig -java example.i $ gcc -c example_wrap.c -I/usr/java/include -I/usr/java/include/solaris $ ld -G example_wrap.o -o libexample.so - </pre></blockquote> + +<p> The exact commands for doing this vary from platform to platform. However, SWIG tries to guess the right options when it is installed. Therefore, you may want to start with one of the examples in the <tt>Examples/java</tt> @@ -287,19 +294,19 @@ directory. If that doesn't work, you will need to read the man-pages for your compiler and linker to get the right set of options. You might also check the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">SWIG Wiki</a> for additional information. -<p> +</p> +<p> The name of the shared library output file is important. If the name of your SWIG module is "<tt>example</tt>", the name of the corresponding shared library file should be "<tt>libexample.so</tt>" (or equivalent depending on your machine, see <a href="#dynamic_linking_problems">Dynamic linking problems</a> for more information). -The name of the module is specified using the <tt>%module</tt> directive or<tt> -module</tt> command line option.<p> -<p> +The name of the module is specified using the <tt>%module</tt> directive or<tt> -module</tt> command line option.</p> -<a name="using_module"></a> -<a name="n8"></a><H3>17.2.5 Using your module</H3> +<H3><a name="using_module"></a>19.2.5 Using your module</H3> -To load your shared native library module in Java, simply use Java's <tt>System.loadLibrary</tt> method in a Java class:<p> <p> +To load your shared native library module in Java, simply use Java's <tt>System.loadLibrary</tt> method in a Java class:</p> + <blockquote><pre> // main.java @@ -324,30 +331,36 @@ $ If it doesn't work have a look at the following section which discusses problems loading the shared library. -<a name="dynamic_linking_problems"></a> -<a name="n9"></a><H3>17.2.6 Dynamic linking problems</H3> +<H3><a name="dynamic_linking_problems"></a>19.2.6 Dynamic linking problems</H3> +<p> As shown in the previous section the code to load a native library (shared library) is <tt>System.loadLibrary("name")</tt>. This can fail with an UnsatisfiedLinkError exception and can be due to a number of reasons. +</p> + <p> You may get an exception similar to this: +</p> + <blockquote><pre> $ java main Exception in thread "main" java.lang.UnsatisfiedLinkError: no example in java.library.path at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1312) at java.lang.Runtime.loadLibrary0(Runtime.java:749) at java.lang.System.loadLibrary(System.java:820) - at main.<clinit>(main.java:5) + at main.<clinit>(main.java:5) </pre></blockquote> +<p> The most common cause for this is an incorrect naming of the native library for the name passed to the <tt>loadLibrary</tt> function. The string passed to the <tt>loadLibrary</tt> function must not include the file extension name in the string, that is <i>.dll</i> or <i>.so</i>. The string must be <i>name</i> and not <i>libname</i> for all platforms. On Windows the native library must then be called <i>name.dll</i> and on most Unix systems it must be called <i>libname.so</i>. If you are debugging using <tt> java -debug</tt>, then the native library must be called <i>name_g.dll</i> on Windows and <i>libname_g.so</i> on Unix. -<p> +</p> +<p> Another common reason for the native library not loading is because it is not in your path. On Windows make sure the <i>path</i> environment variable contains the path to the native library. On Unix make sure that your <i>LD_LIBRARY_PATH</i> contains the path to the native library. @@ -356,8 +369,7 @@ For example you could recompile your native library with extra path information You could use a command such as <tt>ldconfig</tt> (Linux) or <tt>crle</tt> (Solaris) to add additional search paths to the default system configuration (this requires root access and you will need to read the man pages). - -<p> +</p> The native library will also not load if there are any unresolved symbols in the compiled C/C++ code. The following exception is indicative of this: @@ -371,16 +383,17 @@ symbol: fact at java.lang.ClassLoader.loadLibrary(ClassLoader.java, Compiled Code) at java.lang.Runtime.loadLibrary0(Runtime.java, Compiled Code) at java.lang.System.loadLibrary(System.java, Compiled Code) - at main.<clinit>(main.java:5) + at main.<clinit>(main.java:5) $ </pre></blockquote> +<p> This error usually indicates that you forgot to include some object files or libraries in the linking of the native library file. Make sure you compile both the SWIG wrapper file and the code you are wrapping into the native library file. Also make sure you pass all of the required libraries to the linker. The <tt>java -verbose:jni</tt> commandline switch is also a great way to get more information on unresolved symbols. One last piece of advice is to beware of the common faux pas of having more than one native library version in your path. -<p> +</p> In summary, ensure that you are using the correct C/C++ compiler and linker combination and options for successful native library loading. If you are using the examples that ship with SWIG, then the Examples/Makefile must have these set up correctly for your system. @@ -389,27 +402,30 @@ The <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">SWIG Wiki</a> also has The following section also contains some C++ specific linking problems and solutions. -<a name="compilation_problems_cpp"></a> -<a name="n10"></a><H3>17.2.7 Compilation problems and compiling with C++</H3> +<H3><a name="compilation_problems_cpp"></a>19.2.7 Compilation problems and compiling with C++</H3> +<p> On most machines, shared library files should be linked using the C++ compiler. For example: +</p> -<p> -<blockquote><pre>% swig -c++ -java example.i +<blockquote><pre> +% swig -c++ -java example.i % g++ -c -fpic example.cxx % g++ -c -fpic example_wrap.cxx -I/usr/java/j2sdk1.4.1/include -I/usr/java/ j2sdk1.4.1/include/linux % g++ -shared example.o example_wrap.o -o libexample.so </pre></blockquote> +<p> In addition to this, you may need to include additional library files to make it work. For example, if you are using the Sun C++ compiler on Solaris, you often need to add an extra library <tt>-lCrun</tt> like this: +</p> -<p> -<blockquote><pre>% swig -c++ -java example.i +<blockquote><pre> +% swig -c++ -java example.i % CC -c example.cxx % CC -c example_wrap.cxx -I/usr/java/include -I/usr/java/include/solaris % CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o libexample.so -lCrun @@ -424,10 +440,10 @@ shared library. For example: <blockquote> <pre> $ ldd swig - libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000) - libm.so.6 => /lib/libm.so.6 (0x4005b000) - libc.so.6 => /lib/libc.so.6 (0x40077000) - /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) + libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000) + libm.so.6 => /lib/libm.so.6 (0x4005b000) + libc.so.6 => /lib/libc.so.6 (0x40077000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) $ </pre> </blockquote> @@ -435,23 +451,23 @@ $ Finally make sure the version of JDK header files matches the version of Java that you are running as incompatibilities could lead to compilation problems or unpredictable behaviour. -<a name="building_windows"></a> -<a name="n11"></a><H3>17.2.8 Building on Windows</H3> +<H3><a name="building_windows"></a>19.2.8 Building on Windows</H3> +<p> Building on Windows is roughly similar to the process used with Unix. You will want to produce a DLL that can be loaded by the Java Virtual Machine. This section covers the process of using SWIG with Microsoft Visual C++ 6 although the procedure may be similar with other compilers. -In order for everything to work, you will need to have a JDK installed on your machine in order to read the JNI header files.<p> +In order for everything to work, you will need to have a JDK installed on your machine in order to read the JNI header files.</p> -<a name="visual_studio"></a> -<a name="n12"></a><H4>17.2.8.1 Running SWIG from Visual Studio</H4> +<H4><a name="visual_studio"></a>19.2.8.1 Running SWIG from Visual Studio</H4> +<p> If you are developing your application within Microsoft Visual studio, SWIG can be invoked as a custom build option. The Examples\java directory has a few <a href="Windows.html#examples">Windows Examples</a> containing Visual Studio project (.dsp) files. -The process to re-create the project files for a C project are roughly:<p> -<p> +The process to re-create the project files for a C project are roughly:</p> + <ul> <li>Open up a new workspace and use the AppWizard to select a DLL project. <li>Add both the SWIG interface file (the .i file), any supporting C files, and the name of the wrapper file that will be created by SWIG (ie. <tt>example_wrap.c</tt>). @@ -466,24 +482,29 @@ Don't worry if the wrapper file doesn't exist yet--Visual Studio will keep a ref <li>Finally, add the java compilation as a post build rule in the Post-build step tab in project settings, eg, "c:\jdk1.3\bin\javac *.java" <li>Build your project. </ul> + <p> Note: If using C++, choose a C++ suffix for the wrapper file, for example <tt>example_wrap.cxx</tt>. Use <tt>_wrap.cxx</tt> instead of <tt>_wrap.c</tt> in the instructions above and add -c++ when invoking swig. +</p> + <p> Now, assuming all went well, SWIG will be automatically invoked when you build your project. -When doing a build, any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file. +When doing a build, any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file. +</p> + The Java classes that SWIG output should also be compiled into .class files. To run the native code in the DLL (example.dll), make sure that it is in your path then run your Java program which uses it, as described in the previous section. If the library fails to load have a look at <a href="#dynamic_linking_problems">Dynamic linking problems</a>. -<a name="nmake"></a> -<a name="n13"></a><H4>17.2.8.2 Using NMAKE</H4> +<H4><a name="nmake"></a>19.2.8.2 Using NMAKE</H4> +<p> Alternatively, a Makefile for use by NMAKE can be written. Make sure the environment variables for MSVC++ are available and the MSVC++ tools are in your path. -Now, just write a short Makefile like this :<p> -<p> +Now, just write a short Makefile like this :</p> + <blockquote><pre> # Makefile for using SWIG and Java for C code @@ -527,15 +548,15 @@ java:: $(LINK) $(LOPT) -out:example.dll $(LIBS) example.obj example_wrap.obj javac *.java </pre></blockquote> + <p> To build the DLL and compile the java code, run NMAKE (you may need to run <tt>vcvars32</tt> first). This is a pretty simplistic Makefile, but hopefully its enough to get you started. Of course you may want to make changes for it to work for C++ by adding in the -c++ command line switch for swig and replacing .c with .cxx. -<p> +</p> -<a name="java_basic_tour"></a> -<a name="n14"></a><H2>17.3 A tour of basic C/C++ wrapping</H2> +<H2><a name="java_basic_tour"></a>19.3 A tour of basic C/C++ wrapping</H2> By default, SWIG attempts to build a natural Java interface @@ -543,10 +564,10 @@ to your C/C++ code. Functions are wrapped as functions, classes are wrapped as variables are wrapped with JavaBean type getters and setters and so forth. This section briefly covers the essential aspects of this wrapping. -<a name="module_packages_classes"></a> -<a name="n15"></a><H3>17.3.1 Modules, packages and generated Java classes</H3> +<H3><a name="module_packages_classes"></a>19.3.1 Modules, packages and generated Java classes</H3> +<p> The SWIG <tt>%module</tt> directive specifies the name of the Java module. When you specify `<tt>%module example</tt>', the <i>module name</i> determines the name of some of the generated files in the module. @@ -559,11 +580,12 @@ proxy class files nor a Java keyword. Sometimes a C/C++ type cannot be wrapped b example a pointer to a primitive type. In these situations a <i>type wrapper class</i> is generated. Wrapping an enum generates an <i>enum class</i>, either a proper Java enum or a Java class that simulates the enums pattern. Details of all these generated classes will unfold as you read this section. -<p> +</p> +<p> The JNI (C/C++) code is generated into a file which also contains the module name, for example <tt>example_wrap.cxx</tt> or <tt>example_wrap.c</tt>. These C or C++ files complete the contents of the module. -<p> +</p> The generated Java classes can be placed into a Java package by using the <tt>-package</tt> commandline option. This is often combined with the <tt>-outdir</tt> to specify a package directory for generating the Java files. @@ -574,20 +596,22 @@ swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i SWIG won't create the directory, so make sure it exists beforehand. -<a name="functions"></a> -<a name="n16"></a><H3>17.3.2 Functions</H3> +<H3><a name="functions"></a>19.3.2 Functions</H3> +<p> There is no such thing as a global Java function so global C functions are wrapped as static methods in the module class. For example, +</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example int fact(int n); </pre></blockquote> -creates a static function that works exactly like you think it might:<p> +<p> +creates a static function that works exactly like you think it might:</p> <blockquote><pre> public class example { @@ -599,15 +623,14 @@ public class example { <p> -The Java class <tt>example</tt> is the <i>module class</i>. The function can be used as follows from Java:<p> +The Java class <tt>example</tt> is the <i>module class</i>. The function can be used as follows from Java:</p> <blockquote><pre> System.out.println(example.fact(4)); </pre></blockquote> -<a name="global_variables"></a> -<a name="n17"></a><H3>17.3.3 Global variables</H3> +<H3><a name="global_variables"></a>19.3.3 Global variables</H3> C/C++ global variables are fully supported by SWIG. @@ -625,9 +648,7 @@ extern double density; </pre></blockquote> <p> - -Now in Java :<p> -<p> +Now in Java :</p> <blockquote><pre> // Print out value of a C global variable @@ -651,9 +672,11 @@ int clash; <p> If a variable is declared as <tt>const</tt>, it is wrapped as a read-only variable. That is only a getter is produced. +</p> <p> To make ordinary variables read-only, you can use the <tt>%immutable</tt> directive. For example: +</p> <blockquote> <pre> @@ -668,6 +691,7 @@ The <tt>%immutable</tt> directive stays in effect until it is explicitly disable <p> If you just want to make a specific variable immutable, supply a declaration name. For example: +</p> <blockquote> <pre> @@ -678,8 +702,7 @@ extern char *path; // Read-only (due to %immutable) </blockquote> -<a name="constants"></a> -<a name="n18"></a><H3>17.3.4 Constants</H3> +<H3><a name="constants"></a>19.3.4 Constants</H3> C/C++ constants are wrapped as Java static final variables. @@ -740,20 +763,21 @@ a Java <tt>long</tt> is the smallest sized Java type that will take all possible Similarly for <tt>LARGE</tt>. <p> - Be careful using the <tt>%javaconst(1)</tt> directive as not all C code will compile as Java code. For example neither the <tt>1000LL</tt> value for <tt>BIG</tt> nor <tt>2000ULL</tt> for <tt>LARGE</tt> above would generate valid Java code. The example demonstrates how you can target particular constants (<tt>BIG</tt> and <tt>LARGE</tt>) with <tt>%javaconst</tt>. SWIG doesn't use <tt>%javaconst(1)</tt> as the default as it tries to generate code that will always compile. However, using a <tt>%javaconst(1)</tt> at the top of your interface file is strongly recommended as the preferred compile time constants will be generated and most C constants will compile as Java code and in anycase the odd constant that doesn't can be fixed using <tt>%javaconst(0)</tt>. -<p> +</p> +<p> There is an alternative directive which can be used for these rare constant values that won't compile as Java code. This is the <tt>%javaconstvalue(value)</tt> directive, where <tt>value</tt> is a Java code replacement for the C constant and can be either a string or a number. This is useful if you do not want to use either the parsed C value nor a JNI call, such as when the C parsed value will not compile as Java code and a compile time constant is required. The same example demonstrates this: +</p> <blockquote><pre> %javaconst(1); @@ -779,10 +803,13 @@ public interface exampleConstants { Note: declarations declared as <tt>const</tt> are wrapped as read-only variables and will be accessed using a getter as described in the previous section. They are not wrapped as constants. +</p> <p> <b>Compatibility Note:</b> In SWIG-1.3.19 and earlier releases, the constants were generated into the module class and the constants interface didn't exist. Backwards compatibility is maintained as the module class implements the constants interface (even though some consider this type of interface implementation to be bad practice): +</p> + <blockquote><pre> public class example implements exampleConstants { } @@ -793,8 +820,7 @@ You thus have the choice of accessing these constants from either the module cla Or if you decide this practice isn't so bad and your own class implements <tt>exampleConstants</tt>, you can of course just use <tt>EXPRESSION</tt>. -<a name="enumerations"></a> -<a name="n19"></a><H3>17.3.5 Enumerations</H3> +<H3><a name="enumerations"></a>19.3.5 Enumerations</H3> SWIG handles both named and unnamed (anonymous) enumerations. @@ -806,8 +832,7 @@ The second generates proper Java enums. The final two approaches use simple integers for each enum item. Before looking at the various approaches for wrapping named C/C++ enums, anonymous enums are considered. -<a name="anonymous_enums"></a> -<a name="n20"></a><H4>17.3.5.1 Anonymous enums</H4> +<H4><a name="anonymous_enums"></a>19.3.5.1 Anonymous enums</H4> There is no name for anonymous enums and so they are handled like constants. For example: @@ -858,18 +883,18 @@ public interface exampleConstants { As in the case of constants, you can access them through either the module class or the constants interface, for example, <tt>example.ALE</tt> or <tt>exampleConstants.ALE</tt>. -<a name="typesafe_enums"></a> -<a name="n21"></a><H4>17.3.5.2 Typesafe enums</H4> +<H4><a name="typesafe_enums"></a>19.3.5.2 Typesafe enums</H4> +<p> This is the default approach to wrapping named enums. The typesafe enum pattern is a relatively well known construct to work around the lack of enums in versions of Java prior to Java 2 SDK 1.5. It basically defines a class for the enumeration and permits a limited number of final static instances of the class. Each instance equates to an enum item within the enumeration. The implementation is in the "enumtypesafe.swg" file. Let's look at an example: +</p> -<p> <blockquote> <pre> %include "enumtypesafe.swg" // optional as typesafe enums are the default @@ -889,11 +914,12 @@ public final class Beverage { </pre> </blockquote> +<p> See <a href="#typesafe_enums_classes">Typesafe enum classes</a> to see the omitted support methods. Note that the enum item with an initializer (LAGER) is initialized with the enum value obtained via a JNI call. However, as with anonymous enums and constants, use of the <tt>%javaconst</tt> directive is strongly recommended to change this behaviour: +</p> -<p> <blockquote> <pre> %include "enumtypesafe.swg" // optional as typesafe enums are the default @@ -916,6 +942,7 @@ public final class Beverage { </pre> </blockquote> +<p> The generated code is easier to read and more efficient as a true constant is used instead of a JNI call. As is the case for constants, the default is <tt>%javaconst(0)</tt> as not all C values will compile as Java code. However, it is recommended to add in a <tt>%javaconst(1)</tt> directive at the top of your @@ -923,6 +950,7 @@ interface file as it is only on very rare occasions that this will produce code The <tt>%javaconstvalue(value)</tt> directive can also be used for typesafe enums. Note that global enums are generated into a Java class within whatever package you are using. C++ enums defined within a C++ class are generated into a static final inner Java class within the Java proxy class. +</p> <p> Typesafe enums have their advantages over using plain integers in that they they can be used in a typesafe manner. @@ -933,18 +961,19 @@ Please look at the following references for further information: <a href="http://www.javaworld.com/javaworld/jw-07-1997/jw-07-enumerated.html">Create enumerated constants in Java</a> JavaWorld article, <a href="http://www.javaworld.com/javaworld/javatips/jw-javatip133.html">Java Tip 133: More on typesafe enums</a> and <a href="http://www.javaworld.com/javaworld/javatips/jw-javatip122.html">Java Tip 122: Beware of Java typesafe enumerations</a> JavaWorld tips. +</p> <p> - Note that the syntax required for using typesafe enums is the same as that for proper Java enums. This is useful during the period that a project has to support legacy versions of Java. When upgrading to J2SDK 1.5 or later, proper Java enums could be used instead, without users having to change their code. The following section details proper Java enum generation. +</p> -<a name="proper_enums"></a> -<a name="n22"></a><H4>17.3.5.3 Proper Java enums</H4> +<H4><a name="proper_enums"></a>19.3.5.3 Proper Java enums</H4> +<p> Proper Java enums were only introduced in Java 2 SDK 1.5 so this approach is only compatible with more recent versions of Java. Java enums have been designed to overcome all the limitations of both typesafe and type unsafe enums and should be the choice solution, provided older versions of Java do not have to be supported. @@ -954,8 +983,8 @@ Java enums are in many respects similar to Java classes in that they can be cust SWIG takes advantage of this feature to facilitate wrapping C/C++ enums that have initializers. In order to wrap all possible C/C++ enums using proper Java enums, the "enums.swg" file must be used. Let's take a look at an example. +</p> -<p> <blockquote> <pre> %include "enums.swg" @@ -987,17 +1016,17 @@ The <tt>%javaconstvalue(value)</tt> directive covered in the <a href="#constants The additional support methods need not be generated if none of the enum items have initializers and this is covered later in the <a href="#simpler_enum_classes">Simpler Java enums for enums without initializers</a> section. -<a name="typeunsafe_enums"></a> -<a name="n23"></a><H4>17.3.5.4 Type unsafe enums</H4> +<H4><a name="typeunsafe_enums"></a>19.3.5.4 Type unsafe enums</H4> +<p> In this approach each enum item in a named enumeration is wrapped as a static final integer in a class named after the C/C++ enum name. This is a commonly used pattern in Java to simulate C/C++ enums, but it is not typesafe. However, the main advantage over the typesafe enum pattern is enum items can be used in switch statements. In order to use this approach, the "enumtypeunsafe.swg" file must be used. Let's take a look at an example. +</p> -<p> <blockquote> <pre> %include "enumtypeunsafe.swg" @@ -1028,9 +1057,9 @@ C++ enums defined within a C++ class are generated into a static final inner Jav <p> Note that unlike typesafe enums, this approach requires users to mostly use different syntax compared with proper Java enums. Thus the upgrade path to proper enums provided in J2SDK 1.5 is more painful. +</p> -<a name="simple_enums"></a> -<a name="n24"></a><H4>17.3.5.5 Simple enums</H4> +<H4><a name="simple_enums"></a>19.3.5.5 Simple enums</H4> This approach is similar to the type unsafe approach. @@ -1042,15 +1071,12 @@ In fact, this approach is effectively wrapping the enums as if they were anonymo The implementation is in the "enumsimple.swg" file. <p> - <b>Compatibility Note:</b> SWIG-1.3.21 and earlier versions wrapped all enums using this approach. The type unsafe approach is preferable to this one and this simple approach is only included for backwards compatibility with these earlier versions of SWIG. +</p> -<p> - -<a name="pointers"></a> -<a name="n25"></a><H3>17.3.6 Pointers</H3> +<H3><a name="pointers"></a>19.3.6 Pointers</H3> C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with @@ -1087,6 +1113,7 @@ called <tt>SWIGTYPE_p_FILE</tt>. Once obtained, a type wrapper object can be freely passed around to different C functions that expect to receive an object of that type. The only thing you can't do is dereference the pointer from Java. Of course, that isn't much of a concern in this example. +</p> <p> As much as you might be inclined to modify a pointer value directly @@ -1102,6 +1129,7 @@ a pointer to a new type by using Java casts as it is particularly dangerous espe casting C++ objects. If you need to cast a pointer or change its value, consider writing some helper functions instead. For example: +</p> <blockquote> <pre> @@ -1123,21 +1151,23 @@ Foo *IncrFoo(Foo *f, int i) { </pre> </blockquote> +<p> Also, if working with C++, you should always try to use the new C++ style casts. For example, in the above code, the C-style cast may return a bogus result whereas as the C++-style cast will return a NULL pointer if the conversion can't be performed. -<p> +</p> -<a name="structures"></a> -<a name="n26"></a><H3>17.3.7 Structures</H3> +<H3><a name="structures"></a>19.3.7 Structures</H3> +<p> If you wrap a C structure, it is wrapped by a Java class with getters and setters for access to the member variables. For example, +</p> -<p> -<blockquote><pre>struct Vector { +<blockquote><pre> +struct Vector { double x,y,z; }; @@ -1152,17 +1182,22 @@ v.setY(7.2); double x = v.getX(); double y = v.getY(); </pre></blockquote> + +<p> The variable setters and getters are also based on the JavaBean design pattern already covered under the Global variables section. -Similar access is provided for unions and the public data members of C++ classes.<p> +Similar access is provided for unions and the public data members of C++ classes.</p> +<p> This object is actually an instance of a Java class that has been wrapped around a pointer to the C structure. This instance doesn't actually do anything--it just serves as a proxy. The pointer to the C object is held in the Java proxy class in much the same way as pointers are held by type wrapper classes. Further details about Java proxy classes are covered a little later. +</p> <p> <tt>const</tt> members of a structure are read-only. Data members can also be forced to be read-only using the <tt>%immutable</tt> directive. For example: +</p> <blockquote> <pre> @@ -1183,10 +1218,12 @@ dynamically allocated using <tt>malloc</tt> or <tt>new</tt> (depending on whethe SWIG is run with the -c++ option). When the structure member is set, the old contents will be released and a new value created. If this is not the behavior you want, you will have to use a typemap (described later). +</p> <p> If a structure contains arrays, access to those arrays is managed through pointers. For example, consider this: +</p> <blockquote> <pre> @@ -1227,6 +1264,7 @@ Array access can be changed from this default to use Java arrays and this is cov <p> When a member of a structure is itself a structure, it is handled as a pointer. For example, suppose you have two structures like this: +</p> <blockquote> <pre> @@ -1255,7 +1293,7 @@ This is the same value as generated by this C code: <blockquote> <pre> Bar b; -Foo *x = &b->f; /* Points inside b */ +Foo *x = &b->f; /* Points inside b */ </pre> </blockquote> @@ -1272,14 +1310,15 @@ x.setA(3); // Modify x.a - this is the same as b.f.a </blockquote> -<a name="classes"></a> -<a name="n27"></a><H3>17.3.8 C++ classes</H3> +<H3><a name="classes"></a>19.3.8 C++ classes</H3> +<p> C++ classes are wrapped by Java classes as well. For example, if you have this class, +</p> -<p> -<blockquote><pre>class List { +<blockquote><pre> +class List { public: List(); ~List(); @@ -1306,6 +1345,7 @@ Class data members are accessed in the same manner as C structures. <p> Static class members are unsurprisingly wrapped as static members of the Java class: +</p> <blockquote> <pre> @@ -1327,8 +1367,7 @@ int bar = Spam.getBar(); </blockquote> -<a name="inheritance"></a> -<a name="n28"></a><H3>17.3.9 C++ inheritance</H3> +<H3><a name="inheritance"></a>19.3.9 C++ inheritance</H3> SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have @@ -1377,9 +1416,9 @@ then the Java function <tt>spam()</tt> accepts instances of <tt>Foo</tt> or inst <p> Note that Java does not support multiple inheritance so any multiple inheritance in the C++ code is not going to work. A warning is given when multiple inheritance is detected and only the first base class is used. +</p> -<a name="pointers_refs_arrays"></a> -<a name="n29"></a><H3>17.3.10 Pointers, references, arrays and pass by value</H3> +<H3><a name="pointers_refs_arrays"></a>19.3.10 Pointers, references, arrays and pass by value</H3> In C++, there are many different ways a function might receive @@ -1388,7 +1427,7 @@ and manipulate objects. For example: <blockquote> <pre> void spam1(Foo *x); // Pass by pointer -void spam2(Foo &x); // Pass by reference +void spam2(Foo &x); // Pass by reference void spam3(Foo x); // Pass by value void spam4(Foo x[]); // Array of objects </pre> @@ -1416,7 +1455,7 @@ functions like this, <blockquote> <pre> Foo *spam5(); -Foo &spam6(); +Foo &spam6(); Foo spam7(); </pre> </blockquote> @@ -1426,8 +1465,7 @@ Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Java will release this memory when the returned object's finalizer is run by the garbage collector). -<a name="null_pointers"></a> -<a name="n30"></a><H4>17.3.10.1 Null pointers</H4> +<H4><a name="null_pointers"></a>19.3.10.1 Null pointers</H4> Working with null pointers is easy. @@ -1447,8 +1485,7 @@ example.spam4(null); // Array - ok For <tt>spam1</tt> and <tt>spam4</tt> above the Java <tt>null</tt> gets translated into a NULL pointer for passing to the C/C++ function. The converse also occurs, that is, NULL pointers are translated into <tt>null</tt> Java objects when returned from a C/C++ function. -<a name="overloaded_functions"></a> -<a name="n31"></a><H3>17.3.11 C++ overloaded functions</H3> +<H3><a name="overloaded_functions"></a>19.3.11 C++ overloaded functions</H3> C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example, @@ -1477,7 +1514,7 @@ Similarly, if you have a class like this, class Foo { public: Foo(); - Foo(const Foo &); + Foo(const Foo &); ... }; </pre> @@ -1508,7 +1545,7 @@ Here is another example: <blockquote> <pre> void foo(Bar *b); -void foo(Bar &b); +void foo(Bar &b); </pre> </blockquote> @@ -1543,10 +1580,7 @@ void spam(short); // Ignored </pre> </blockquote> -<P> - -<a name="namespaces"></a> -<a name="n32"></a><H3>17.3.12 C++ namespaces</H3> +<H3><a name="namespaces"></a>19.3.12 C++ namespaces</H3> SWIG is aware of C++ namespaces, but namespace names do not appear in @@ -1598,8 +1632,7 @@ If you have more than one namespace and your want to keep their symbols separate, consider wrapping them as separate SWIG modules. Each SWIG module can be placed into a separate package. -<a name="templates"></a> -<a name="n33"></a><H3>17.3.13 C++ templates</H3> +<H3><a name="templates"></a>19.3.13 C++ templates</H3> C++ templates don't present a huge problem for SWIG. However, in order @@ -1621,7 +1654,7 @@ struct pair { T1 first; T2 second; pair(); - pair(const T1&, const T2&); + pair(const T1&, const T2&); ~pair(); }; @@ -1640,21 +1673,20 @@ int second = p.getSecond(); </blockquote> Obviously, there is more to template wrapping than shown in this example. -More details can be found in the <a href="SWIGPlus.html">SWIG and C++</a> chapter. +More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter. -<a name="smart_pointers"></a> -<a name="n34"></a><H3>17.3.14 C++ Smart Pointers</H3> +<H3><a name="smart_pointers"></a>19.3.14 C++ Smart Pointers</H3> In certain C++ programs, it is common to use classes that have been wrapped by so-called "smart pointers." Generally, this involves the use of a template class -that implements <tt>operator->()</tt> like this: +that implements <tt>operator->()</tt> like this: <blockquote> <pre> template<class T> class SmartPtr { ... - T *operator->(); + T *operator->(); ... } </pre> @@ -1678,8 +1710,8 @@ A smart pointer would be used in C++ as follows: <pre> SmartPtr<Foo> p = CreateFoo(); // Created somehow (not shown) ... -p->x = 3; // Foo::x -int y = p->bar(); // Foo::bar +p->x = 3; // Foo::x +int y = p->bar(); // Foo::bar </pre> </blockquote> @@ -1706,7 +1738,7 @@ int y = p.bar(); // Foo::bar </pre> </blockquote> -If you ever need to access the underlying pointer returned by <tt>operator->()</tt> itself, +If you ever need to access the underlying pointer returned by <tt>operator->()</tt> itself, simply use the <tt>__deref__()</tt> method. For example: <blockquote> @@ -1715,8 +1747,7 @@ Foo f = p.__deref__(); // Returns underlying Foo * </pre> </blockquote> -<a name="further_details"></a> -<a name="n35"></a><H2>17.4 Further details on the generated Java classes</H2> +<H2><a name="further_details"></a>19.4 Further details on the generated Java classes</H2> In the previous section, a high-level view of Java wrapping was @@ -1729,11 +1760,10 @@ of how the proxy classes work and then covers the type wrapper classes. Finally enum classes are covered. First, the crucial intermediary JNI class is considered. -<a name="imclass"></a> -<a name="n36"></a><H3>17.4.1 The intermediary JNI class</H3> +<H3><a name="imclass"></a>19.4.1 The intermediary JNI class</H3> -In the <a href="SWIG.html">"SWIG basics"</a> and <a href="SWIGPlus.html">"SWIG and C++"</a> chapters, +In the <a href="SWIG.html#SWIG">"SWIG basics"</a> and <a href="SWIGPlus.html#SWIGPlus">"SWIG and C++"</a> chapters, details of low-level structure and class wrapping are described. To summarize those chapters, if you have a global function and class like this @@ -1760,13 +1790,13 @@ void delete_Foo(Foo *f) { delete f; } int Foo_x_get(Foo *f) { - return f->x; + return f->x; } void Foo_x_set(Foo *f, int value) { - f->x = value; + f->x = value; } int Foo_spam(Foo *f, int num, Foo* foo) { - return f->spam(num, foo); + return f->spam(num, foo); } </pre> </blockquote> @@ -1804,20 +1834,25 @@ class exampleJNI { </pre> </blockquote> +<p> This class contains the complete Java - C/C++ interface so all function calls go via this class. As this class acts as a go-between for all JNI calls to C/C++ code from the Java <a href="#java_proxy_classes">proxy classes</a>, <a href="#type_wrapper_classes">type wrapper classes</a> and <a href="#java_module_class">module class</a>, it is known as the intermediary JNI class. -<p> +</p> +<p> You may notice that SWIG uses a Java long wherever a pointer or class object needs traversing the Java-C/C++ boundary. This approach leads to minimal JNI code which makes for better performance as JNI code involves a lot of string manipulation. SWIG uses Java code wherever possible as it is compiled into byte code which requires fewer string operations. +</p> <p> The functions in the intermediary JNI class cannot be accessed outside of its package. Access to them is gained through the module class for globals otherwise the appropriate proxy class. +</p> <p> The name of the intermediary JNI class can be changed from its default, that is, the module name with JNI appended after it. The module directive attribute <tt>jniclassname</tt> is used to achieve this: +</p> <blockquote> <pre> @@ -1828,14 +1863,14 @@ The module directive attribute <tt>jniclassname</tt> is used to achieve this: If <tt>name</tt> is the same as <tt>modulename</tt> then the module class name gets changed from <tt>modulename</tt> to <tt>modulenameModule</tt>. -<a name="imclass_pragmas"></a> -<a name="n37"></a><H4>17.4.1.1 The intermediary JNI class pragmas</H4> +<H4><a name="imclass_pragmas"></a>19.4.1.1 The intermediary JNI class pragmas</H4> +<p> The intermediary JNI class can be tailored through the use of pragmas, but is not commonly done. The pragmas for this class are: +</p> -<p> -<table BORDER> +<table BORDER summary="Intermediary JNI class pragmas"> <tr VALIGN=TOP> <td><b>Pragma</b></td> <td><b>Description</b></td> @@ -1860,6 +1895,7 @@ The intermediary JNI class can be tailored through the use of pragmas, but is no <p> The pragma code appears in the generated intermediary JNI class where you would expect: +</p> <blockquote> <pre> @@ -1900,8 +1936,7 @@ For example, let's change the intermediary JNI class access to public. All the methods in the intermediary JNI class will then be callable outside of the package as the method modifiers are public by default. -<a name="java_module_class"></a> -<a name="n38"></a><H3>17.4.2 The Java module class</H3> +<H3><a name="java_module_class"></a>19.4.2 The Java module class</H3> All global functions and variable getters/setters appear in the module class. For our example, there is just one function: @@ -1926,14 +1961,14 @@ example.egg(new Foo()); The primary reason for having the module class wrapping the calls in the intermediary JNI class is to implement static type checking. In this case only a <tt>Foo</tt> can be passed to the <tt>egg</tt> function, whereas any <tt>long</tt> can be passed to the <tt>egg</tt> function in the intermediary JNI class. -<a name="module_class_pragmas"></a> -<a name="n39"></a><H4>17.4.2.1 The Java module class pragmas</H4> +<H4><a name="module_class_pragmas"></a>19.4.2.1 The Java module class pragmas</H4> +<p> The module class can be tailored through the use of pragmas, in the same manner as the intermediary JNI class. The pragmas are similarly named and are used in the same way. The complete list follows: +</p> -<p> -<table BORDER> +<table BORDER summary="Java module class pragmas"> <tr VALIGN=TOP> <td><b>Pragma</b></td> <td><b>Description</b></td> @@ -1956,9 +1991,10 @@ The module class can be tailored through the use of pragmas, in the same manner </table> -<p> +<p> The pragma code appears in the generated module class like this: +</p> <blockquote> <pre> @@ -1974,8 +2010,7 @@ The pragma code appears in the generated module class like this: See <a href="#imclass_pragmas">The intermediary JNI class pragmas</a> section for further details on using pragmas. -<a name="java_proxy_classes"></a> -<a name="n40"></a><H3>17.4.3 Java proxy classes</H3> +<H3><a name="java_proxy_classes"></a>19.4.3 Java proxy classes</H3> A Java proxy class is generated for each structure, union or C++ class that is wrapped. @@ -2045,8 +2080,7 @@ int y = f.spam(5, new Foo()); </pre> </blockquote> -<a name="memory_management"></a> -<a name="n41"></a><H4>17.4.3.1 Memory management</H4> +<H4><a name="memory_management"></a>19.4.3.1 Memory management</H4> Each proxy class has an ownership flag <tt>swigCMemOwn</tt>. The value of this @@ -2054,11 +2088,12 @@ flag determines who is responsible for deleting the underlying C++ object. If the proxy class's finalizer will destroy the C++ object when the proxy class is garbage collected. If set to false, then the destruction of the proxy class has no effect on the C++ object. -<P> +<p> When an object is created by a constructor or returned by value, Java automatically takes ownership of the result. On the other hand, when pointers or references are returned to Java, there is often no way to know where they came from. Therefore, the ownership is set to false. For example: +</p> <blockquote> @@ -2067,7 +2102,7 @@ class Foo { public: Foo(); Foo bar1(); - Foo &bar2(); + Foo &bar2(); Foo *bar2(); }; </pre> @@ -2093,6 +2128,7 @@ Java to assume ownership and destroy it! For the most part, memory management issues remain hidden. However, there are situations where you might have to manually change the ownership of an object. For instance, consider code like this: +</p> <blockquote> <pre> @@ -2128,11 +2164,13 @@ you're lucky, you will only get a segmentation fault. To work around this, the ownership flag of <tt>o</tt> needs changing to <tt>false</tt>. The ownership flag is a private member variable of the proxy class so this is not possible without some customization of the proxy class. This is achieved using a typemap to add pure Java code to the proxy class and is detailed later in the section on typemaps. +</p> <p> Sometimes a function will create memory and return a pointer to a newly allocated object. SWIG has no way of knowing this so by default the proxy class does not manage the returned object. However, you can tell the proxy class to manage the memory if you specify the <tt>%newobject</tt> directive. Consider: +</p> <blockquote> <pre> @@ -2178,8 +2216,7 @@ Obj obj = Factory.createObj(); // obj.swigCMemOwn = true; </blockquote> -<a name="inheritance_mirroring"></a> -<a name="n42"></a><H4>17.4.3.2 Inheritance</H4> +<H4><a name="inheritance_mirroring"></a>19.4.3.2 Inheritance</H4> Java proxy classes will mirror C++ inheritance chains. For example, given the base class <tt>Base</tt> and its derived class <tt>Derived</tt>: @@ -2272,24 +2309,25 @@ public class Derived extends Base { } </pre></blockquote> +<p> Note the memory ownership is controlled by the base class. However each class in the inheritance hierarchy has its own pointer value which is obtained during construction. The <tt>SWIGDerivedUpcast()</tt> call converts the pointer from a <tt>Derived *</tt> to a <tt>Base *</tt>. This is a necessity as C++ compilers are free to implement pointers in the inheritance hierarchy with different values. +</p> <p> - It is of course possible to extend <tt>Base</tt> using your own Java classes. If <tt>Derived</tt> is provided by the C++ code, you could for example add in a pure Java class <tt>Extended</tt> derived from <tt>Base</tt>. There is a caveat and that is any C++ code will not know about your pure Java class <tt>Extended</tt> so this type of derivation is restricted. However, true cross language polymorphism can be achieved using the <a href="#java_directors">directors</a> feature. -<p> +</p> -<a name="proxy_classes_gc"></a> -<a name="n43"></a><H4>17.4.3.3 Proxy classes and garbage collection</H4> +<H4><a name="proxy_classes_gc"></a>19.4.3.3 Proxy classes and garbage collection</H4> +<p> By default each proxy class has a <tt>delete()</tt> and a <tt>finalize()</tt> method. The <tt>finalize()</tt> method calls <tt>delete()</tt> which frees any malloc'd memory for wrapped C structs or calls the C++ class destructors. The idea is for <tt>delete()</tt> to be called when you have finished with the C/C++ object. @@ -2297,27 +2335,31 @@ Ideally you need not call <tt>delete()</tt>, but rather leave it to the garbage The unfortunate thing is that Sun, in their wisdom, do not guarantee that the finalizers will be called. When a program exits, the garbage collector does not always call the finalizers. Depending on what the finalizers do and which operating system you use, this may or may not be a problem. -<p> +</p> +<p> If the <tt>delete()</tt> call into JNI code is just for memory handling, there is not a problem when run on most operating systems, for example Windows and Unix. Say your JNI code creates memory on the heap which your finalizers should clean up, the finalizers may or may not be called before the program exits. In Windows and Unix all memory that a process uses is returned to the system on exit, so this isn't a problem. This is not the case in some operating systems like vxWorks. If however, your finalizer calls into JNI code invoking the C++ destructor which in turn releases a TCP/IP socket for example, there is no guarantee that it will be released. Note that with long running programs the garbage collector will eventually run, thereby calling any unreferenced object's finalizers. -<p> +</p> +<p> Some not so ideal solutions are: +</p> + <ol> -<li start=1> +<li> Call the <tt>System.runFinalizersOnExit(true)</tt> or <tt>Runtime.getRuntime().runFinalizersOnExit(true)</tt> to ensure the finalizers are called before the program exits. The catch is that this is a deprecated function call as the documenation says: <blockquote><i> This method is inherently unsafe. It may result in finalizers being called on live objects while other threads are concurrently manipulating those objects, resulting in erratic behavior or deadlock. </i></blockquote> In many cases you will be lucky and find that it works, but it is not to be advocated. -Have a look at <a href=http://java.sun.com>Sun's Java web site</a> and search for <tt>runFinalizersOnExit</tt>. +Have a look at <a href="http://java.sun.com">Sun's Java web site</a> and search for <tt>runFinalizersOnExit</tt>. </li> -<p> + <li> From jdk1.3 onwards a new function, <tt>addShutdownHook()</tt>, was introduced which is guaranteed to be called when your program exits. You can encourage the garbage collector to call the finalizers, for example, add this static block to the class that has the <tt>main()</tt> function: @@ -2333,7 +2375,7 @@ You can encourage the garbage collector to call the finalizers, for example, add Although this usually works, the documentation doesn't guarantee that <tt>runFinalization()</tt> will actually call the finalizers. As the the shutdown hook is guaranteed you could also make a JNI call to clean up any resources that are being tracked by the C/C++ code. </li> -<p> + <li> Call the <tt>delete()</tt> function manually which will immediately invoke the C++ destructor. As a suggestion it may be a good idea to set the object to null so that should the object be inadvertantly used again a Java null pointer exception is thrown, the alternative would crash the JVM by using a null C pointer. @@ -2349,7 +2391,6 @@ myA=null; The SWIG generated code ensures that the memory is not deleted twice, in the event the finalizers get called in addition to the manual <tt>delete()</tt> call. </li> -<p> <li> Write your own object manager in Java. You could derive all SWIG classes from a single base class which could track which objects have had their finalizers run, then call the rest of them on program termination. @@ -2357,8 +2398,7 @@ The section on <a href="#java_typemaps">Java typemaps</a> details how to specify </li> </ol> -<a name="type_wrapper_classes"></a> -<a name="n44"></a><H3>17.4.4 Type wrapper classes</H3> +<H3><a name="type_wrapper_classes"></a>19.4.4 Type wrapper classes</H3> The generated type wrapper class, for say an <tt>int *</tt>, looks like this: @@ -2390,16 +2430,18 @@ The section on <a href="#java_typemaps">Java typemaps</a> details how to modify Note that if you use a pointer or reference to a proxy class in a function then no type wrapper class is generated because the proxy class can be used as the function parameter. If however, you need anything more complicated like a pointer to a pointer to a proxy class then a typewrapper class is generated for your use. -<p> +</p> +<p> Note that SWIG generates a type wrapper class and not a proxy class when it has not parsed the definition of a type that gets used. For example, say SWIG has not parsed the definition of <tt>class Snazzy</tt> because it is in a header file that you may have forgotten to use the <tt>%include</tt> directive on. Should SWIG parse <tt>Snazzy *</tt> being used in a function parameter, it will then generates a type wrapper class around a <tt>Snazzy</tt> pointer. Also recall from earlier that SWIG will use a pointer when a class is passed by value or by reference: +</p> <blockquote> <pre> -void spam(Snazzy *x, Snazzy &y, Snazzy z); +void spam(Snazzy *x, Snazzy &y, Snazzy z); </pre> </blockquote> @@ -2416,34 +2458,35 @@ public static void spam(SWIGTYPE_p_Snazzy x, SWIGTYPE_p_Snazzy y, SWIGTYPE_p_Sna <p> Note that typedefs are tracked by SWIG and the typedef name is used to construct the type wrapper class name. For example, consider the case where <tt>Snazzy</tt> is a typedef to an <tt>int</tt> which SWIG does parse: +</p> <blockquote> <pre> typedef int Snazzy; -void spam(Snazzy *x, Snazzy &y, Snazzy z); +void spam(Snazzy *x, Snazzy &y, Snazzy z); </pre> </blockquote> +<p> Because the typedefs have been tracked the Java function generated is: +</p> + <blockquote> <pre> public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... } </pre> </blockquote> -<p> -<a name="enum_classes"></a> -<a name="n45"></a><H3>17.4.5 Enum classes</H3> +<H3><a name="enum_classes"></a>19.4.5 Enum classes</H3> SWIG can generate three types of enum classes. The <a href="#enumerations">Enumerations</a> section discussed these but omitted all the details. The following sub-sections detail the various types of enum classes that can be generated. -<a name="typesafe_enums_classes"></a> -<a name="n46"></a><H4>17.4.5.1 Typesafe enum classes</H4> +<H4><a name="typesafe_enums_classes"></a>19.4.5.1 Typesafe enum classes</H4> The following example demonstrates the typesafe enum classes which SWIG generates: @@ -2511,8 +2554,7 @@ The JNI layer returns the enum value from the C/C++ world as an integer and this The <tt>swigValue</tt> method is used for marshalling in the other direction. The <tt>toString</tt> method is overridden so that the enum name is available. -<a name="proper_enums_classes"></a> -<a name="n47"></a><H4>17.4.5.2 Proper Java enum classes</H4> +<H4><a name="proper_enums_classes"></a>19.4.5.2 Proper Java enum classes</H4> The following example demonstrates the Java enums approach: @@ -2576,8 +2618,7 @@ All the constructors and methods in the Java enum are required just to handle C/ These needn't be generated if the enum being wrapped does not have any initializers and the <a href="#simpler_enum_classes">Simpler Java enums for enums without initializers</a> section describes how typemaps can be used to achieve this. -<a name="typeunsafe_enums_classes"></a> -<a name="n48"></a><H4>17.4.5.3 Type unsafe enum classes</H4> +<H4><a name="typeunsafe_enums_classes"></a>19.4.5.3 Type unsafe enum classes</H4> The following example demonstrates type unsafe enums: @@ -2602,27 +2643,29 @@ public final class Beverage { </pre> </blockquote> -<a name="java_directors"></a> -<a name="n49"></a><H2>17.5 Cross language polymorphism using directors (experimental)</H2> +<H2><a name="java_directors"></a>19.5 Cross language polymorphism using directors (experimental)</H2> -Proxy classes provide a natural, object-oriented way to wrap C++ classes. -As described earlier, each proxy instance has an associated C++ instance, and method calls from Java to the proxy are passed to the C++ instance transparently via C wrapper functions. <p> +Proxy classes provide a natural, object-oriented way to wrap C++ classes. +as described earlier, each proxy instance has an associated C++ instance, and method calls from Java to the proxy are passed to the C++ instance transparently via C wrapper functions. +</p> +<p> This arrangement is asymmetric in the sense that no corresponding mechanism exists to pass method calls down the inheritance chain from C++ to Java. In particular, if a C++ class has been extended in Java (by deriving from the proxy class), these classes will not be visible from C++ code. Virtual method calls from C++ are thus not able to access the lowest implementation in the inheritance chain. -<p> +</p> +<p> SWIG can address this problem and make the relationship between C++ classes and proxy classes more symmetric. To achieve this goal, new classes called directors are introduced at the bottom of the C++ inheritance chain. The job of the directors is to route method calls correctly, either to C++ implementations higher in the inheritance chain or to Java implementations lower in the inheritance chain. The upshot is that C++ classes can be extended in Java and from C++ these extensions look exactly like native C++ classes. Neither C++ code nor Java code needs to know where a particular method is implemented: the combination of proxy classes, director classes, and C wrapper functions transparently takes care of all the cross-language method routing. +</p> -<a name="java_enabling_directors"></a> -<a name="n50"></a><H3>17.5.1 Enabling directors</H3> +<H3><a name="java_enabling_directors"></a>19.5.1 Enabling directors</H3> The director feature is disabled by default. @@ -2640,7 +2683,7 @@ Second, you must use the %feature("director") directive to tell SWIG which class The %feature directive can be applied globally, to specific classes, and to specific methods, like this: <blockquote> -<pre> +<pre> // generate directors for all classes that have virtual methods %feature("director"); @@ -2662,11 +2705,14 @@ So for example, </pre> </blockquote> -will generate directors for all virtual methods of class Foo except bar(). <p> +will generate directors for all virtual methods of class Foo except bar(). +</p> +<p> Directors can also be generated implicitly through inheritance. In the following, class Bar will get a director class that handles the methods one() and two() (but not three()): +</p> <blockquote> <pre> @@ -2684,49 +2730,52 @@ public: </pre> </blockquote> -<a name="java_directors_classes"></a> -<a name="n51"></a><H3>17.5.2 Director classes</H3> +<H3><a name="java_directors_classes"></a>19.5.2 Director classes</H3> +<p> For each class that has directors enabled, SWIG generates a new class that derives from both the class in question and a special <tt>Swig::Director</tt> class. These new classes, referred to as director classes, can be loosely thought of as the C++ equivalent of the Java proxy classes. The director classes store a pointer to their underlying Java proxy classes. -<p> +</p> +<p> For simplicity let's ignore the <tt>Swig::Director</tt> class and refer to the original C++ class as the director's base class. By default, a director class extends all virtual methods in the inheritance chain of its base class (see the preceding section for how to modify this behavior). Thus all virtual method calls, whether they originate in C++ or in Java via proxy classes, eventually end up in at the implementation in the director class. The job of the director methods is to route these method calls to the appropriate place in the inheritance chain. By "appropriate place" we mean the method that would have been called if the C++ base class and its Java derived classes were seamlessly integrated. That seamless integration is exactly what the director classes provide, transparently skipping over all the messy JNI glue code that binds the two languages together. -<p> +</p> +<p> In reality, the "appropriate place" is one of only two possibilities: C++ or Java. Once this decision is made, the rest is fairly easy. If the correct implementation is in C++, then the lowest implementation of the method in the C++ inheritance chain is called explicitly. If the correct implementation is in Java, the Java API is used to call the method of the underlying Java object (after which the usual virtual method resolution in Java automatically finds the right implementation). -<p> +</p> -<a name="java_directors_overhead"></a> -<a name="n52"></a><H3>17.5.3 Overhead and code bloat</H3> +<H3><a name="java_directors_overhead"></a>19.5.3 Overhead and code bloat</H3> +<p> Enabling directors for a class will generate a new director method for every virtual method in the class' inheritance chain. This alone can generate a lot of code bloat for large hierarchies. Method arguments that require complex conversions to and from Java types can result in large director methods. For this reason it is recommended that directors are selectively enabled only for specific classes that are likely to be extended in Java and used in C++. -<p> +</p> +<p> Although directors make it natural to mix native C++ objects with Java objects (as director objects), one should be aware of the obvious fact that method calls to Java objects from C++ will be much slower than calls to C++ objects. Additionally, compared to classes that do not use directors, the call routing in the director methods adds a small overhead. This situation can be optimized by selectively enabling director methods (using the %feature directive) for only those methods that are likely to be extended in Java. +</p> -<a name="java_directors_example"></a> -<a name="n53"></a><H3>17.5.4 Simple directors example</H3> +<H3><a name="java_directors_example"></a>19.5.4 Simple directors example</H3> <p> @@ -2746,7 +2795,7 @@ public: }; void callup(DirectorBase *director) { - director->upcall_method(); + director->upcall_method(); } </pre> </blockquote> @@ -2785,8 +2834,7 @@ directorDerived::upcall_method() invoked. </pre> </blockquote> -<a name="common_customization"></a> -<a name="n54"></a><H2>17.6 Common customization features</H2> +<H2><a name="common_customization"></a>19.6 Common customization features</H2> An earlier section presented the absolute basics of C/C++ wrapping. If you do nothing @@ -2796,8 +2844,7 @@ types of functionality might be missing or the interface to certain functions mi be awkward. This section describes some common SWIG features that are used to improve the interface to existing C/C++ code. -<a name="helper_functions"></a> -<a name="n55"></a><H3>17.6.1 C/C++ helper functions</H3> +<H3><a name="helper_functions"></a>19.6.1 C/C++ helper functions</H3> Sometimes when you create a module, it is missing certain bits of functionality. For @@ -2855,8 +2902,7 @@ Admittedly, this is not the most elegant looking approach. However, it works an hard to implement. It is possible to improve on this using Java code, typemaps, and other customization features as covered in later sections, but sometimes helper functions are a quick and easy solution to difficult cases. -<a name="class_extension"></a> -<a name="n56"></a><H3>17.6.2 Class extension with %extend</H3> +<H3><a name="class_extension"></a>19.6.2 Class extension with %extend</H3> One of the more interesting features of SWIG is that it can extend @@ -2877,14 +2923,14 @@ struct Vector { %extend Vector { char *toString() { static char tmp[1024]; - sprintf(tmp,"Vector(%g,%g,%g)", self->x,self->y,self->z); + sprintf(tmp,"Vector(%g,%g,%g)", self->x,self->y,self->z); return tmp; } Vector(double x, double y, double z) { Vector *v = (Vector *) malloc(sizeof(Vector)); - v->x = x; - v->y = y; - v->z = z; + v->x = x; + v->y = y; + v->z = z; return v; } }; @@ -2910,8 +2956,7 @@ Vector(2,3,4) <tt>%extend</tt> works with both C and C++ code. It does not modify the underlying object in any way---the extensions only show up in the Java interface. -<a name="exception_handling"></a> -<a name="n57"></a><H3>17.6.3 Exception handling with %exception and %javaexception</H3> +<H3><a name="exception_handling"></a>19.6.3 Exception handling with %exception and %javaexception</H3> If a C or C++ function throws an error, you may want to convert that error into a Java @@ -2922,14 +2967,15 @@ It is detailed in full in the <a href="Customization.html#exception">Exception h <p> In C, a function often indicates an error by returning a status code (a negative number or a NULL pointer perhaps). Here is a simple example of how you might handle that: +</p> <blockquote> <pre> %exception malloc { $action if (!result) { - jclass clazz = (*jenv)->FindClass(jenv, "java/lang/OutOfMemoryError"); - (*jenv)->ThrowNew(jenv, clazz, "Not enough memory"); + jclass clazz = (*jenv)->FindClass(jenv, "java/lang/OutOfMemoryError"); + (*jenv)->ThrowNew(jenv, clazz, "Not enough memory"); return $null; } } @@ -2964,8 +3010,8 @@ that. For example: %exception malloc { $action if (err_occurred()) { - jclass clazz = (*jenv)->FindClass(jenv, "java/lang/OutOfMemoryError"); - (*jenv)->ThrowNew(jenv, clazz, "Not enough memory"); + jclass clazz = (*jenv)->FindClass(jenv, "java/lang/OutOfMemoryError"); + (*jenv)->ThrowNew(jenv, clazz, "Not enough memory"); return $null; } } @@ -2982,16 +3028,16 @@ See the section on <p> C++ exceptions are also easy to handle. -We can catch the C++ exception and rethrow it as a Java exception like this:<p> +We can catch the C++ exception and rethrow it as a Java exception like this:</p> <blockquote> <pre> %exception getitem { try { $action - } catch (std::out_of_range &e) { - jclass clazz = jenv->FindClass("java/lang/Exception"); - jenv->ThrowNew(clazz, "Range error"); + } catch (std::out_of_range &e) { + jclass clazz = jenv->FindClass("java/lang/Exception"); + jenv->ThrowNew(clazz, "Range error"); return $null; } } @@ -3014,9 +3060,9 @@ The <tt>%nojavaexception</tt> feature is the equivalent to <tt>%noexception</tt> %javaexception("java.lang.Exception") getitem { try { $action - } catch (std::out_of_range &e) { - jclass clazz = jenv->FindClass("java/lang/Exception"); - jenv->ThrowNew(clazz, "Range error"); + } catch (std::out_of_range &e) { + jclass clazz = jenv->FindClass("java/lang/Exception"); + jenv->ThrowNew(clazz, "Range error"); return $null; } } @@ -3047,11 +3093,11 @@ It is however possible to write JNI calls which will compile under both C and C+ <p> The language-independent <tt>exception.i</tt> library file can also be used -to raise exceptions. See the <a href="Library.html">SWIG Library</a> chapter. +to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> chapter. The typemap example <a href="#exception_typemap">Handling C++ exception specifications as Java exceptions</a> provides further exception handling capabilities. +</p> -<a name="method_access"></a> -<a name="n58"></a><H3>17.6.4 Method access with %javamethodmodifiers</H3> +<H3><a name="method_access"></a>19.6.4 Method access with %javamethodmodifiers</H3> A Java feature called <tt>%javamethodmodifiers</tt> can be used to change the method modifiers from the default <tt>public</tt>. It applies to both module class methods and proxy class methods. For example: @@ -3073,8 +3119,7 @@ protected static void protect_me() { </pre> </blockquote> -<a name="tips_techniques"></a> -<a name="n59"></a><H2>17.7 Tips and techniques</H2> +<H2><a name="tips_techniques"></a>19.7 Tips and techniques</H2> Although SWIG is largely automatic, there are certain types of wrapping problems that @@ -3082,8 +3127,7 @@ require additional user input. Examples include dealing with output parameter strings and arrays. This chapter discusses the common techniques for solving these problems. -<a name="input_output_parameters"></a> -<a name="n60"></a><H3>17.7.1 Input and output parameters using primitive pointers and references</H3> +<H3><a name="input_output_parameters"></a>19.7.1 Input and output parameters using primitive pointers and references</H3> A common problem in some C programs is handling parameters passed as simple pointers or references. For @@ -3143,6 +3187,7 @@ and how the <tt>OUTPUT</tt> parameter will return the result in the first elemen <p> If you don't want to use the names <tt>INPUT</tt> or <tt>OUTPUT</tt>, use the <tt>%apply</tt> directive. For example: +</p> <blockquote> <pre> @@ -3159,6 +3204,7 @@ int sub(int *x, int *y); <p> If a function mutates one of its parameters like this, +</p> <blockquote> <pre> @@ -3205,17 +3251,19 @@ void negate(int *INOUT); or using a reference: <blockquote> <pre> -void negate(int &INOUT); +void negate(int &INOUT); </pre> </blockquote> <p> Note: Since most Java primitive types are immutable and are passed by value, it is not possible to perform in-place modification of a type passed as a parameter. +</p> <p> Be aware that the primary purpose of the <tt>typemaps.i</tt> file is to support primitive datatypes. Writing a function like this +</p> <blockquote> <pre> @@ -3225,8 +3273,7 @@ void foo(Bar *OUTPUT); will not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>. -<a name="simple_pointers"></a> -<a name="n61"></a><H3>17.7.2 Simple pointers</H3> +<H3><a name="simple_pointers"></a>19.7.2 Simple pointers</H3> If you must work with simple pointers such as <tt>int *</tt> or <tt>double *</tt> another approach to using @@ -3277,10 +3324,9 @@ System.out.println("3 + 4 = " + result); </pre> </blockquote> -See the <a href="Library.html">SWIG Library</a> chapter for further details. +See the <a href="Library.html#Library">SWIG Library</a> chapter for further details. -<a name="c_arrays"></a> -<a name="n62"></a><H3>17.7.3 Wrapping C arrays with Java arrays</H3> +<H3><a name="c_arrays"></a>19.7.3 Wrapping C arrays with Java arrays</H3> SWIG can wrap arrays in a more natural Java manner than the default by using the <tt>arrays_java.i</tt> library file. @@ -3329,16 +3375,19 @@ global_array: 100 101 102 103 </pre> </blockquote> +<p> Note that for assigning array variables the length of the C variable is used, so it is possible to use a Java array that is bigger than the C code will cope with. Only the number of elements in the C array will be used. However, if the Java array is not large enough then you are likely to get a segmentation fault or access violation, just like you would in C. When arrays are used in functions like <tt>populate</tt>, the size of the C array passed to the function is determined by the size of the Java array. +</p> + <p> Please be aware that the typemaps in this library are not efficient as all the elements are copied from the Java array to a C array whenever the array is passed to and from JNI code. There is an alternative approach using the SWIG array library and this is covered in the next. +</p> -<a name="unbounded_c_arrays"></a> -<a name="n63"></a><H3>17.7.4 Unbounded C Arrays</H3> +<H3><a name="unbounded_c_arrays"></a>19.7.4 Unbounded C Arrays</H3> Sometimes a C function expects an array to be passed as a pointer. For example, @@ -3463,16 +3512,17 @@ On the other hand, this low-level approach is extremely efficient and well suited for applications in which you need to create buffers, package binary data, etc. -<a name="java_typemaps"></a> -<a name="n64"></a><H2>17.8 Java typemaps</H2> +<H2><a name="java_typemaps"></a>19.8 Java typemaps</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. -You are advised to be familiar with the the material in the "<a href="Typemaps.html">Typemaps</a>" chapter. +You are advised to be familiar with the the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. While not absolutely essential knowledge, this section assumes some familiarity with the Java Native Interface (JNI). -JNI documentation can be consulted either online at <a href=http://java.sun.com>Sun's Java web site</a> or from a good JNI book. -The following two books are recommended:<p> +JNI documentation can be consulted either online at <a href="http://java.sun.com">Sun's Java web site</a> or from a good JNI book. +The following two books are recommended:</p> + <ul> <li> Title: 'Essential JNI: Java Native Interface.' Author: Rob Gordon. Publisher: Prentice Hall. ISBN: 0-13-679895-0. </li> <li> Title: 'The Java Native Interface: Programmer's Guide and Specification.' Author: Sheng Liang. Publisher: Addison-Wesley. ISBN: 0-201-32577-2. </li> @@ -3483,12 +3533,13 @@ Before proceeding, it should be stressed that typemaps are not a required part of using SWIG---the default wrapping behavior is enough in most cases. Typemaps are only used if you want to change some aspect of the generated code. -<a name="default_primitive_type_mappings"></a> -<a name="n65"></a><H3>17.8.1 Default primitive type mappings</H3> +<H3><a name="default_primitive_type_mappings"></a>19.8.1 Default primitive type mappings</H3> + +<p> +The following table lists the default type mapping from Java to C/C++.</p> -The following table lists the default type mapping from Java to C/C++.<p> -<table BORDER> +<table BORDER summary="Default primitive type mappings"> <tr> <td><b>C/C++ type</b></td> <td><b>Java type</b></td> @@ -3502,79 +3553,79 @@ The following table lists the default type mapping from Java to C/C++.<p> </tr> <tr> -<td>char<br>const char &</td> +<td>char<br>const char &</td> <td>char</td> <td>jchar</td> </tr> <tr> -<td>signed char<br>const signed char &</td> +<td>signed char<br>const signed char &</td> <td>byte</td> <td>jbyte</td> </tr> <tr> -<td>unsigned char<br>const unsigned char &</td> +<td>unsigned char<br>const unsigned char &</td> <td>short</td> <td>jshort</td> </tr> <tr> -<td>short<br>const short &</td> +<td>short<br>const short &</td> <td>short</td> <td>jshort</td> </tr> <tr> -<td>unsigned short<br> const unsigned short &</td> +<td>unsigned short<br> const unsigned short &</td> <td>int</td> <td>jint</td> </tr> <tr> -<td>int<br> const int &</td> +<td>int<br> const int &</td> <td>int</td> <td>jint</td> </tr> <tr> -<td>unsigned int<br> const unsigned int &</td> +<td>unsigned int<br> const unsigned int &</td> <td>long</td> <td>jlong</td> </tr> <tr> -<td>long<br>const long &</td> +<td>long<br>const long &</td> <td>int</td> <td>jint</td> </tr> <tr> -<td>unsigned long<br>const unsigned long &</td> +<td>unsigned long<br>const unsigned long &</td> <td>long</td> <td>jlong</td> </tr> <tr> -<td>long long<br> const long long &</td> +<td>long long<br> const long long &</td> <td>long</td> <td>jlong</td> </tr> <tr> -<td>unsigned long long<br>const unsigned long long &</td> +<td>unsigned long long<br>const unsigned long long &</td> <td>java.math.BigInteger</td> <td>jobject</td> </tr> <tr> -<td>float<br>const float &</td> +<td>float<br>const float &</td> <td>float</td> <td>jfloat</td> </tr> <tr> -<td>double<br> const double &</td> +<td>double<br> const double &</td> <td>double</td> <td>jdouble</td> </tr> @@ -3586,15 +3637,16 @@ The following table lists the default type mapping from Java to C/C++.<p> </tr> </table> -<br> + +<p> Note that SWIG wraps the C <tt>char</tt> type as a character. Pointers and arrays of this type are wrapped as strings. The <tt>signed char</tt> type can be used if you want to treat <tt>char</tt> as a signed number rather than a character. Also note that all const references to primitive types are treated as if they are passed by value. -<p> +</p> Given the following C function: <blockquote> <pre> -void func(unsigned short a, char *b, const long &c, unsigned long long d); +void func(unsigned short a, char *b, const long &c, unsigned long long d); </pre> </blockquote> The module class method would be: <blockquote> <pre> @@ -3610,15 +3662,14 @@ and the JNI function would look like this: JNIEXPORT void JNICALL Java_exampleJNI_func(JNIEnv *jenv, jclass jcls, jint jarg1, jstring jarg2, jint jarg3, jobject jarg4) {...} </pre> </blockquote> -<p> +<p> The mappings for C <tt>int</tt> and C <tt>long</tt> are appropriate for 32 bit applications which are used in the 32 bit JVMs. There is no perfect mapping between Java and C as Java doesn't support all the unsigned C data types. However, the mappings allow the full range of values for each C type from Java. -<p> +</p> -<a name="jvm64"></a> -<a name="n66"></a><H3>17.8.2 Sixty four bit JVMs</H3> +<H3><a name="jvm64"></a>19.8.2 Sixty four bit JVMs</H3> If you are using a 64 bit JVM you may have to override the C long, but probably not C int default mappings. @@ -3629,16 +3680,17 @@ Note that the Java write once run anywhere philosophy holds true for all pure Ja Unfortunately it won't of course hold true for JNI code. -<a name="what_is_typemap"></a> -<a name="n67"></a><H3>17.8.3 What is a typemap?</H3> +<H3><a name="what_is_typemap"></a>19.8.3 What is a typemap?</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 Java to C, you might define a typemap like this: +</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example %typemap(in) int { $1 = $input; @@ -3655,11 +3707,12 @@ will be applied. The supplied C code is used to convert values. In this code a number of special variables prefaced by a <tt>$</tt> are used. The <tt>$1</tt> variable is a placeholder for a local variable of type <tt>int</tt>. The <tt>$input</tt> variable contains the Java data, the JNI <tt>jint</tt> in this case. +</p> <p> +When this example is compiled into a Java module, it can be used as follows: +</p> -When this example is compiled into a Java module, it can be used as follows:<p> -<p> <blockquote><pre> System.out.println(example.fact(6)); </pre></blockquote> @@ -3691,6 +3744,7 @@ more than simple text-matching--typemaps are fully integrated into the SWIG C++ type-system. When you define a typemap for <tt>int</tt>, that typemap applies to <tt>int</tt> and qualified variations such as <tt>const int</tt>. In addition, the typemap system follows <tt>typedef</tt> declarations. For example: +</p> <blockquote> <pre> @@ -3709,6 +3763,7 @@ type <tt>int</tt>. <p> Typemaps can also be defined for groups of consecutive arguments. For example: +</p> <blockquote> <pre> @@ -3730,8 +3785,7 @@ int c = example.count('e',"Hello World"); </pre> </blockquote> -<a name="typemaps_c_to_java_types"></a> -<a name="n68"></a><H3>17.8.4 Typemaps for mapping C/C++ types to Java types</H3> +<H3><a name="typemaps_c_to_java_types"></a>19.8.4 Typemaps for mapping C/C++ types to Java types</H3> The typemaps available to the Java module include the common typemaps listed in the main typemaps section. @@ -3739,7 +3793,7 @@ There are a number of additional typemaps which are necessary for using SWIG wit The most important of these implement the mapping of C/C++ types to Java types: <br> -<table BORDER> +<table BORDER summary="Typemap mappings for C/C++ types to Java types"> <tr> <td><b>Typemap</b></td> @@ -3808,6 +3862,7 @@ The most important of these implement the mapping of C/C++ types to Java types: <p> If you are writing your own typemaps to handle a particular type, you will normally have to write a collection of them. The default typemaps are in "<tt>java.swg</tt>" and so might be a good place for finding typemaps to base any new ones on. +</p> <p> The "jni", "jtype" and "jstype" typemaps are usually defined together to handle the Java to C/C++ type mapping. @@ -3816,14 +3871,18 @@ If an "in" typemap is written, a "freearg" and "argout" typemap may also need to as some types have a default "freearg" and/or "argout" typemap which may need overriding. The "freearg" typemap sometimes releases memory allocated by the "in" typemap. The "argout" typemap sometimes sets values in function parameters which are passed by reference in Java. +</p> -<p>The default code generated by SWIG for the Java module comes from the typemaps in the "<tt>java.swg</tt>" library file which implements the +<p> +The default code generated by SWIG for the Java module comes from the typemaps in the "<tt>java.swg</tt>" library file which implements the <a href="#default_primitive_type_mappings">Default primitive type mappings</a> covered earlier. There are other type mapping typemaps in the Java library. These are listed below: +</p> + <br> -<table BORDER> +<table BORDER summary="Java library typemap mappings"> <tr VALIGN=TOP> <td><b>C Type</b></td> <td><b>Typemap</b></td> @@ -3914,8 +3973,7 @@ These are listed below: </table> -<a name="typemap_attributes"></a> -<a name="n69"></a><H3>17.8.5 Java typemap attributes</H3> +<H3><a name="typemap_attributes"></a>19.8.5 Java typemap attributes</H3> There is an additional typemap attribute that the Java module supports. @@ -3929,38 +3987,40 @@ It is analogous to the <a href="#exception_handling">%javaexception</a> feature' </pre> </blockquote> +<p> The attribute is necessary for supporting Java checked exceptions and can be added to just about any typemap. -The list of typemaps include all the C/C++ (JNI) typemaps in the "<a href="Typemaps.html">Typemaps</a>" chapter and the +The list of typemaps include all the C/C++ (JNI) typemaps in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter and the Java specific typemaps listed in <a href="#typemaps_c_to_java_types">the previous section</a>, barring the "jni", "jtype" and "jstype" typemaps as they could never contain code to throw an exception. - -<p/> +</p> The throws clause is generated for the proxy method as well as the JNI method in the JNI intermediary class. If a method uses more than one typemap and each of those typemaps have classes specified in the throws clause, the union of the exception classes is added to the throws clause ensuring there are no duplicate classes. See the <a href="#nan_exception_typemap">NaN exception example</a> for further usage. -<a name="special_variables"></a> -<a name="n70"></a><H3>17.8.6 Java special variables</H3> +<H3><a name="special_variables"></a>19.8.6 Java special variables</H3> -The standard SWIG special variables are available for use within typemaps as described in the <a href=Typemaps.html>Typemaps documentation</a>, for example <tt>$1</tt>, <tt>$input</tt>,<tt>$result</tt> etc. +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> The Java module uses a few additional special variables: -<p> +</p> +<p> <b><tt>$javaclassname</tt></b><br> <tt>$javaclassname</tt> is similar to <tt>$1_type</tt>. It expands to the class name for use in Java. When wrapping a union, struct or class, it expands to the Java proxy class name. Otherwise it expands to the type wrapper class name. For example, <tt>$javaclassname</tt> is replaced by <tt>Foo</tt> when the wrapping a <tt>struct Foo</tt> or <tt>struct Foo *</tt> and <tt>SWIGTYPE_p_unsigned_short</tt> is used for <tt>unsigned short *</tt>. -<p> +</p> +<p> <b><tt>$null </tt></b><br> Used in input typemaps to return early from JNI functions that have either void or a non-void return type. Example: +</p> <blockquote><pre> %typemap(check) int * %{ @@ -3995,14 +4055,17 @@ JNIEXPORT jobject JNICALL Java_jnifn(...) { } </pre></blockquote> +<p> <b><tt>$javainput, $jnicall and $owner</tt></b><br> The $javainput special variable is used in "javain" typemaps and $jnicall and $owner are used in "javaout" typemaps. $jnicall is analogous to $action in %exception. It is replaced by the call to the native method in the intermediary JNI class. $owner is replaced by either <tt>true</tt> if %newobject has been used, otherwise <tt>false</tt>. $javainput is analogous to the $input special variable. It is replaced by the parameter name. -<p> +</p> +<p> Here is an example: +</p> <blockquote><pre> %typemap(javain) Class "Class.getCPtr($javainput)" @@ -4042,38 +4105,37 @@ public static Class bar(Class cls, int ush) { </pre></blockquote> <p> - <b><tt>$static</tt></b><br> This special variable expands to either <i>static</i> or nothing depending on whether the class is an inner Java class or not. It is used in the "javaclassmodifiers" typemap so that global classes can be wrapped as Java proxy classes and nested C++ classes/enums can be wrapped with the Java equivalent, that is, static inner proxy classes. +</p> <p> - <b><tt>$jniinput, $javacall and $packagepath</tt></b><br> These special variables are used in the directors typemaps. See <a href="#java_directors_typemaps">Director specific typemaps</a> for details. +</p> <p> - <b><tt>$module</tt></b><br> This special variable expands to the module name, as specified by <tt>%module</tt> or the <tt>-module</tt> commandline option. Useful for constructing the intermediary classname, which is just <tt>$moduleJNI</tt>. +</p> -<a name="typemaps_for_c_and_c++"></a> -<a name="n71"></a><H3>17.8.7 Typemaps for both C and C++ compilation</H3> +<H3><a name="typemaps_for_c_and_c++"></a>19.8.7 Typemaps for both C and C++ compilation</H3> JNI calls must be written differently depending on whether the code is being compiled as C or C++. For example C compilation requires the pointer to a function pointer struct member syntax like <blockquote><pre> -const jclass clazz = (*jenv)->FindClass(jenv, "java/lang/String"); +const jclass clazz = (*jenv)->FindClass(jenv, "java/lang/String"); </pre></blockquote> whereas C++ code compilation of the same function call is a member function call using a class pointer like <blockquote><pre> -const jclass clazz = jenv->FindClass("java/lang/String"); +const jclass clazz = jenv->FindClass("java/lang/String"); </pre></blockquote> To enable typemaps to be used for either C or C++ compilation, a set of JCALLx macros have been defined in Lib/java/javahead.swg, @@ -4084,21 +4146,21 @@ The above JNI calls would be written in a typemap like this const jclass clazz = JCALL1(FindClass, jenv, "java/lang/String"); </pre></blockquote> +<p> Note that the SWIG preprocessor expands these into the appropriate C or C++ JNI calling convention. The C calling convention is emitted by default and the C++ calling convention is emitted when using the -c++ SWIG commandline option. If you do not intend your code to be targeting both C and C++ then your typemaps can use the appropriate JNI calling convention and need not use the JCALLx macros. -<p> +</p> -<a name="java_code_typemaps"></a> -<a name="n72"></a><H3>17.8.8 Java code typemaps</H3> +<H3><a name="java_code_typemaps"></a>19.8.8 Java code typemaps</H3> +<p> Most of SWIG's typemaps are used for the generation of C/C++ code. The typemaps in this section are used solely for the generation of Java code. Elements of proxy classes and type wrapper classes come from the following typemaps (the defaults). - -<p> +</p> <tt>%typemap(javabase)</tt> <blockquote> @@ -4162,12 +4224,14 @@ interfaces (extends) for Java class: empty default the <tt>finalize()</tt> method (proxy classes only): default calls the <tt>delete()</tt> method </blockquote> +<p> <b>Compatibility Note:</b> In SWIG-1.3.21 and earlier releases, typemaps called "javagetcptr" and "javaptrconstructormodifiers" were available. These are deprecated and the "javabody" typemap can be used instead. +</p> <p> - In summary the contents of the typemaps make up a proxy class like this: +</p> <blockquote> <pre> @@ -4183,10 +4247,13 @@ public void <i>delete</i>() [ javadestruct OR javadestruct_derived typemap ] </pre> </blockquote> -Note the <tt><i>delete</i>()</tt> methodname is configurable, see "javadestruct" and "javadestruct_derived" typemaps above. <p> +Note the <tt><i>delete</i>()</tt> methodname is configurable, see "javadestruct" and "javadestruct_derived" typemaps above. +</p> +<p> The type wrapper class is similar in construction: +</p> <blockquote> <pre> @@ -4212,14 +4279,16 @@ The enum class is also similar in construction: </pre> </blockquote> +<p> The "javaimports" typemap is ignored if the enum class is wrapped by an inner Java class, that is when wrapping an enum declared within a C++ class. +</p> <p> - The defaults can be overridden to tailor these classes. Here is an example which will change the <tt>getCPtr</tt> method and constructor from the default protected access to public access. This has a practical application if you are invoking SWIG more than once and generating the wrapped classes into different packages in each invocation. If the classes in one package are using the classes in another package, then these methods need to be public. +</p> <blockquote> <pre> @@ -4246,10 +4315,11 @@ To target proxy classes that are derived from a wrapped class as well, the "java <p> For the typemap to be used in all type wrapper classes, all the different types that type wrapper classes could be used for should be targeted: +</p> <blockquote> <pre> -%typemap(javabody) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], SWIGTYPE (CLASS::*) %{ +%typemap(javabody) SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], SWIGTYPE (CLASS::*) %{ private long swigCPtr; public $javaclassname(long cPtr, boolean bFutureUse) { @@ -4268,15 +4338,17 @@ For the typemap to be used in all type wrapper classes, all the different types </blockquote> Again this is the same that is in "<tt>java.swg</tt>", barring the method modifier for <tt>getCPtr</tt>. -<a name="java_directors_typemaps"></a> -<a name="n73"></a><H3>17.8.9 Director specific typemaps</H3> +<H3><a name="java_directors_typemaps"></a>19.8.9 Director specific typemaps</H3> +<p> The Java directors feature requires the "javadirectorin", "javadirectorout" and the "directorin" typemaps in order to work properly. The "javapackage" typemap is an optional typemap used to identify the Java package path for individual SWIG generated proxy classes. -<p> +</p> +<p> <tt>%typemap(directorin)</tt> +</p> <blockquote> @@ -4405,6 +4477,7 @@ The corrected interface file looks like: <p> Practically speaking, you should create a separate SWIG interface file, which is %import-ed into each SWIG interface file, when you have multiple Java packages: +</p> <blockquote> <pre> @@ -4421,8 +4494,7 @@ The basic strategy here is to provide a default package typemap for the majority </blockquote> -<a name="typemap_examples"></a> -<a name="n74"></a><H2>17.9 Typemap Examples</H2> +<H2><a name="typemap_examples"></a>19.9 Typemap Examples</H2> This section includes a few examples of typemaps. For more examples, you @@ -4430,8 +4502,7 @@ might look at the files "<tt>java.swg</tt>" and "<tt>typemaps.i</tt>" in the SWIG library. -<a name="simpler_enum_classes"></a> -<a name="n75"></a><H3>17.9.1 Simpler Java enums for enums without initializers</H3> +<H3><a name="simpler_enum_classes"></a>19.9.1 Simpler Java enums for enums without initializers</H3> The default <a href="#proper_enums_classes">Proper Java enums</a> approach to wrapping enums is somewhat verbose. @@ -4487,21 +4558,22 @@ public static HairType getHair() { </pre> </blockquote> +<p> For marshalling Java enums to C/C++ enums, the <tt>ordinal</tt> method is used to convert the Java enum into an integer value for passing to the JNI layer, see the "javain" typemap. For marshalling C/C++ enums to Java enums, the C/C++ enum value is cast to an integer in the C/C++ typemaps (not shown). This integer value is then used to index into the array of enum constants that the Java language provides. See the <tt>getEnumConstants</tt> method in the "javaout" typemap. +</p> <p> - These typemaps can often be used as the default for wrapping enums as in many cases there won't be any enum initializers. In fact a good strategy is to always use these typemaps and to specifically handle enums with initializers using %apply. This would be done by using the original versions of these typemaps in "enums.swg" under another typemap name for applying using %apply. +</p> -<a name="exception_typemap"></a> -<a name="n76"></a><H3>17.9.2 Handling C++ exception specifications as Java exceptions</H3> +<H3><a name="exception_typemap"></a>19.9.2 Handling C++ exception specifications as Java exceptions</H3> This example demonstrates various ways in which C++ exceptions can be tailored and converted into Java exceptions. @@ -4538,7 +4610,7 @@ The default generic "throws" typemap looks like this: <blockquote> <pre> -%typemap(throws) SWIGTYPE, SWIGTYPE &, SWIGTYPE *, SWIGTYPE [ANY] %{ +%typemap(throws) SWIGTYPE, SWIGTYPE &, SWIGTYPE *, SWIGTYPE [ANY] %{ SWIG_JavaThrowException(jenv, SWIG_JavaRuntimeException, "C++ $1_type exception thrown"); return $null; @@ -4554,9 +4626,9 @@ If, however, we wanted to throw a checked exception, say <tt>java.io.IOException <blockquote> <pre> %typemap(throws, throws="java.io.IOException") FileException { - jclass excep = jenv->FindClass("java/io/IOException"); + jclass excep = jenv->FindClass("java/io/IOException"); if (excep) - jenv->ThrowNew(excep, $1.what().c_str()); + jenv->ThrowNew(excep, $1.what().c_str()); return $null; } </pre> @@ -4611,15 +4683,18 @@ public class FileException extends java.lang.Exception { We could alternatively have used <tt>%rename</tt> to rename <tt>what()</tt> into <tt>getMessage()</tt>. -<a name="nan_exception_typemap"></a> -<a name="n77"></a><H3>17.9.3 NaN Exception - exception handling for a particular type</H3> +<H3><a name="nan_exception_typemap"></a>19.9.3 NaN Exception - exception handling for a particular type</H3> +<p> A Java exception can be thrown from any Java or JNI code. Therefore, as most typemaps contain either Java or JNI code, just about any typemap could throw an exception. The following example demonstrates exception handling on a type by type basis by checking for 'Not a number' (NaN) whenever a parameter of type <tt>float</tt> is wrapped. +</p> + <p> Consider the following C++ code: +</p> <blockquote> <pre> @@ -4716,13 +4791,14 @@ public class example { If we were a martyr to the JNI cause, we could replace the succinct code within the "javain" typemap with a few pages of JNI code. If we had, we would have put it in the "in" typemap which, like all JNI and Java typemaps, also supports the 'throws' attribute. -<a name="converting_java_string_arrays"></a> -<a name="n78"></a><H3>17.9.4 Converting Java String arrays to char ** </H3> +<H3><a name="converting_java_string_arrays"></a>19.9.4 Converting Java String arrays to char ** </H3> -A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings. -The following SWIG interface file allows a Java String array to be used as a <tt>char **</tt> object.<p> <p> +A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings. +The following SWIG interface file allows a Java String array to be used as a <tt>char **</tt> object. +</p> + <blockquote><pre> %module example @@ -4796,16 +4872,18 @@ int print_args(char **argv) { char **get_args() { static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0}; - return &values[0]; + return &values[0]; } %} </pre></blockquote> +<p> Note that the 'C' JNI calling convention is used. Checking for any thrown exceptions after JNI function calls has been omitted. -When this module is compiled, our wrapped C functions can be used by the following Java program:<p> -<p> +When this module is compiled, our wrapped C functions can be used by the following Java program: +</p> + <blockquote><pre> // File main.java @@ -4851,8 +4929,7 @@ the C function. The "out" typemap is used for function return values. Lastly the "jni", "jtype" and "jstype" typemaps are also required to specify what Java types to use. -<a name="expanding_java_object"></a> -<a name="n79"></a><H3>17.9.5 Expanding a Java object to multiple arguments</H3> +<H3><a name="expanding_java_object"></a>19.9.5 Expanding a Java object to multiple arguments</H3> Suppose that you had a collection of C functions with arguments @@ -4881,23 +4958,23 @@ previous example's typemaps: <pre> %typemap(in) (int argc, char **argv) { int i = 0; - $1 = (*jenv)->GetArrayLength(jenv, $input); + $1 = (*jenv)->GetArrayLength(jenv, $input); $2 = (char **) malloc(($1+1)*sizeof(char *)); /* make a copy of each string */ - for (i = 0; i<$1; i++) { - jstring j_string = (jstring)(*jenv)->GetObjectArrayElement(jenv, $input, i); - const char * c_string = (*jenv)->GetStringUTFChars(jenv, j_string, 0); + for (i = 0; i<$1; i++) { + jstring j_string = (jstring)(*jenv)->GetObjectArrayElement(jenv, $input, i); + const char * c_string = (*jenv)->GetStringUTFChars(jenv, j_string, 0); $2[i] = malloc(strlen((c_string)+1)*sizeof(const char *)); strcpy($2[i], c_string); - (*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string); - (*jenv)->DeleteLocalRef(jenv, j_string); + (*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string); + (*jenv)->DeleteLocalRef(jenv, j_string); } $2[i] = 0; } %typemap(freearg) (int argc, char **argv) { int i; - for (i=0; i<$1-1; i++) + for (i=0; i<$1-1; i++) free($2[i]); free($2); } @@ -4917,6 +4994,7 @@ the supplied Java parameter. <p> With the above typemap in place, you will find it no longer necessary to supply the argument count. This is automatically set by the typemap code. For example: +</p> <blockquote> <pre> @@ -4925,18 +5003,24 @@ example.foo(new String[]{"red", "green", "blue", "white"}); </blockquote> -<a name="using_typemaps_return_arguments"></a> -<a name="n80"></a><H3>17.9.6 Using typemaps to return arguments</H3> +<H3><a name="using_typemaps_return_arguments"></a>19.9.6 Using typemaps to return arguments</H3> +<p> A common problem in some C programs is that values may be returned in function parameters rather than in the return value of a function. The <tt>typemaps.i</tt> file defines INPUT, OUTPUT and INOUT typemaps which can be used to solve some instances of this problem. -This library file uses an array as a means of moving data to and from Java when wrapping a C function that takes non const pointers or non const references as parameters. <p> - +This library file uses an array as a means of moving data to and from Java when wrapping a C function that takes non const pointers or non const references as parameters. +</p> + +<p> Now we are going to outline an alternative approach to using arrays for C pointers. The INOUT typemap uses a <tt>double[]</tt> array for receiving and returning the <tt>double*</tt> parameters. -In this approach we are able to use a Java class <tt>myDouble</tt> instead of <tt>double[]</tt> arrays where the C pointer <tt>double*</tt> is required. +In this approach we are able to use a Java class <tt>myDouble</tt> instead of <tt>double[]</tt> arrays where the C pointer <tt>double*</tt> is required. +</p> + +<p> Here is our example function: +</p> <blockquote><pre> /* Returns a status value and two values in out1 and out2 */ @@ -4971,12 +5055,12 @@ argument of MyDouble instead of double *. This will allow the calling function to read the double * value after returning from the function. */ %typemap(in) double *OUTVALUE { - jclass clazz = jenv->FindClass("MyDouble"); - jfieldID fid = jenv->GetFieldID(clazz, "swigCPtr", "J"); - jlong cPtr = jenv->GetLongField($input, fid); + jclass clazz = jenv->FindClass("MyDouble"); + jfieldID fid = jenv->GetFieldID(clazz, "swigCPtr", "J"); + jlong cPtr = jenv->GetLongField($input, fid); MyDouble *pMyDouble = NULL; - *(MyDouble **)&pMyDouble = *(MyDouble **)&cPtr; - $1 = &pMyDouble->value; + *(MyDouble **)&pMyDouble = *(MyDouble **)&cPtr; + $1 = &pMyDouble->value; } %typemap(jtype) double *OUTVALUE "MyDouble" @@ -4990,13 +5074,18 @@ allow the calling function to read the double * value after returning from the f int spam(double a, double b, double *out1, double *out2); </pre></blockquote> +<p> Note that the C++ JNI calling convention has been used this time and so must be compiled as C++ and the -c++ commandline must be passed to SWIG. -JNI error checking has been omitted for clarity.<p> +JNI error checking has been omitted for clarity. +</p> +<p> What the typemaps do are make the named <tt>double*</tt> function parameters use our new <tt>MyDouble</tt> wrapper structure. The "in" typemap takes this structure, gets the C++ pointer to it, takes the <tt>double value</tt> member variable and passes it to the C++ <tt>spam</tt> function. In Java, when the function returns, we use the SWIG created <tt>getValue()</tt> function to get the output value. The following Java program demonstrates this: +</p> + <blockquote><pre> // File: main.java @@ -5026,8 +5115,7 @@ $ java main 1 12.0 340.0 </pre></blockquote> -<a name="adding_downcasts"></a> -<a name="n81"></a><H3>17.9.7 Adding Java downcasts to polymorphic return types</H3> +<H3><a name="adding_downcasts"></a>19.9.7 Adding Java downcasts to polymorphic return types</H3> SWIG support for polymorphism works in that the appropriate virtual function is called. However, the default generated code does not allow for downcasting. @@ -5080,21 +5168,25 @@ java.lang.ClassCastException at main.main(main.java:16) </pre></blockquote> +<p> Even though we know from examination of the C++ code that <tt>vehicle_factory</tt> returns an object of type <tt>Ambulance</tt>, we are not able to use this knowledge to perform the downcast in Java. This occurs because the runtime type information is not completely passed from C++ to Java when returning the type from <tt>vehicle_factory()</tt>. Usually this is not a problem as virtual functions do work by default, such as in the case of <tt>start()</tt>. There are a few solutions to getting downcasts to work. -<p> +</p> +<p> The first is not to use a Java cast but a call to C++ to make the cast. Add this to your code: +</p> + <blockquote><pre> %exception Ambulance::dynamic_cast(Vehicle *vehicle) { $action if (!result) { - jclass excep = jenv->FindClass("java/lang/ClassCastException"); + jclass excep = jenv->FindClass("java/lang/ClassCastException"); if (excep) { - jenv->ThrowNew(excep, "dynamic_cast exception"); + jenv->ThrowNew(excep, "dynamic_cast exception"); } } } @@ -5118,7 +5210,7 @@ Add the following before the definition of <tt>vehicle_factory</tt>: <blockquote><pre> %typemap(out) Vehicle * { Ambulance *downcast = dynamic_cast<Ambulance *>($1); - *(Ambulance **)&$result = downcast; + *(Ambulance **)&$result = downcast; } %typemap(javaout) Vehicle * { @@ -5175,24 +5267,24 @@ Note that in this case, the Java class is constructed using JNI code rather than FireEngine *fireengine = dynamic_cast<FireEngine *>($1); if (ambulance) { // call the Ambulance(long cPtr, boolean cMemoryOwn) constructor - jclass clazz = jenv->FindClass("Ambulance"); + jclass clazz = jenv->FindClass("Ambulance"); if (clazz) { - jmethodID mid = jenv->GetMethodID(clazz, "<init>", "(JZ)V"); + jmethodID mid = jenv->GetMethodID(clazz, "<init>", "(JZ)V"); if (mid) { jlong cptr = 0; - *(Ambulance **)&cptr = ambulance; - $result = jenv->NewObject(clazz, mid, cptr, false); + *(Ambulance **)&cptr = ambulance; + $result = jenv->NewObject(clazz, mid, cptr, false); } } } else if (fireengine) { // call the FireEngine(long cPtr, boolean cMemoryOwn) constructor - jclass clazz = jenv->FindClass("FireEngine"); + jclass clazz = jenv->FindClass("FireEngine"); if (clazz) { - jmethodID mid = jenv->GetMethodID(clazz, "<init>", "(JZ)V"); + jmethodID mid = jenv->GetMethodID(clazz, "<init>", "(JZ)V"); if (mid) { jlong cptr = 0; - *(FireEngine **)&cptr = fireengine; - $result = jenv->NewObject(clazz, mid, cptr, false); + *(FireEngine **)&cptr = fireengine; + $result = jenv->NewObject(clazz, mid, cptr, false); } } } @@ -5210,8 +5302,7 @@ There are other solutions to this problem, but this last example demonstrates so SWIG usually generates code which constructs the proxy classes using Java code as it is easier to handle error conditions and is faster. Note that the JNI code above uses a number of string lookups to call a constructor, whereas this would not occur using byte compiled Java code. -<a name="adding_equals_method"></a> -<a name="n82"></a><H3>17.9.8 Adding an equals method to the Java classes</H3> +<H3><a name="adding_equals_method"></a>19.9.8 Adding an equals method to the Java classes</H3> When a pointer is returned from a JNI function, it is wrapped using a new Java proxy class or type wrapper class. @@ -5246,8 +5337,7 @@ System.out.println("foo1? " + foo1.equals(foo2)); </blockquote> -<a name="void_pointers"></a> -<a name="n83"></a><H3>17.9.9 Void pointers and a common Java base class</H3> +<H3><a name="void_pointers"></a>19.9.9 Void pointers and a common Java base class</H3> One might wonder why the common code that SWIG emits for the proxy and type wrapper classes is not pushed into a base class. @@ -5260,9 +5350,11 @@ Here is an example which uses a common base class for all proxy classes and type <blockquote> <pre> -%typemap(javabase) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], SWIGTYPE (CLASS::*) "SWIG" +%typemap(javabase) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], + SWIGTYPE (CLASS::*) "SWIG" -%typemap(javacode) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], SWIGTYPE (CLASS::*) %{ +%typemap(javacode) SWIGTYPE, SWIGTYPE *, SWIGTYPE &, SWIGTYPE [], + SWIGTYPE (CLASS::*) %{ protected long getPointer() { return swigCPtr; } @@ -5272,6 +5364,7 @@ Here is an example which uses a common base class for all proxy classes and type <p> Define new base class called SWIG: +</p> <blockquote> <pre> @@ -5298,42 +5391,45 @@ This example contains some useful functionality which you may want in your code. <li> It also has a function which effectively implements a cast from the type of the proxy/type wrapper class to a void pointer. This is necessary for passing a proxy class or a type wrapper class to a function that takes a void pointer. </ul> -<a name="java_directors_faq"></a> -<a name="n84"></a><H2>17.10 Living with Java Directors</H2> +<H2><a name="java_directors_faq"></a>19.10 Living with Java Directors</H2> <p> This section is intended to address frequently asked questions and frequently encountered problems when using Java directors. </p> + <ol> <li><i>When my program starts up, it complains that </i>method_foo<i> cannot be found in a Java method called </i>swig_module_init<i>. How do I fix - this?</i></li> + this?</i> <p> Open up the C++ wrapper source code file and look for <code>"method_foo"</code> (include the double quotes, they are important!) Look at the JNI field descriptor and make sure that each class that occurs in the descriptor has the correct package name in front of it. If the package name is incorrect, put a "javapackage" typemap in your SWIG interface file. </p> + </li> <li><i>I'm compiling my code and I'm using templates. I provided a javapackage typemap, but SWIG doesn't generate the right JNI field - descriptor.</i></li> + descriptor.</i> <p> Use the template's renamed name as the argument to the "javapackage" typemap: - <br> + </p> <blockquote> <pre> -%typemap(javapackage) std::vector<int> "your.package.here" -%template(VectorOfInt) std::vector<int>; +%typemap(javapackage) std::vector<int> "your.package.here" +%template(VectorOfInt) std::vector<int>; </pre> </blockquote> + </li> <li><i>When I pass class pointers or references through a C++ upcall and I try to type cast them, Java complains with a ClassCastException. What am I - doing wrong?</i></li> + doing wrong?</i> <p> Normally, a non-director generated Java proxy class creates temporary Java objects as follows: + </p> <blockquote> <pre> public static void MyClass_method_upcall(MyClass self, long jarg1) @@ -5365,6 +5461,7 @@ public static void MyClass_method_upcall(MyClass self, long jarg1, When you import a SWIG interface file containing class definitions, the classes you want to be director-enabled must be have the <code>feature("director")</code> enabled for type symmetry to work. This applies even when the class being wrapped isn't a director-enabled class but takes parameters that are director-enabled classes. </p> + <p> The current "type symmetry" design will work for simple C++ inheritance, but will most likely fail for anything more compicated such as tree or diamond C++ inheritance hierarchies. Those who are interested in challenging problems are more than welcome to hack the <code>Java::Java_director_declaration</code> method in <code>Source/Modules/java.cxx</code>. @@ -5373,6 +5470,7 @@ public static void MyClass_method_upcall(MyClass self, long jarg1, If all else fails, you can use the downcastXXXXX() method to attempt to recover the director class's Java object pointer. For the Java Foo proxy class, the Foo director class's java object pointer can be accessed through the javaObjectFoo() method. The generated method's signature is: + </p> <blockquote> <pre> @@ -5429,15 +5527,15 @@ public class MyClassDerived extends MyClass { } </pre> </blockquote> - - <p> + </li> <li><i>Why isn't the proxy class declared abstract? Why aren't the director - upcall methods in the proxy class declared abstract?</i></li> + upcall methods in the proxy class declared abstract?</i> <p> Declaring the proxy class and its methods abstract would break the JNI argument marshalling and SWIG's downcall functionality (going from Java to C++.) Create an abstract Java subclass that inherits from the director-enabled class instead. Using the previous Foo class example: + </p> <blockquote> <pre> @@ -5463,14 +5561,13 @@ public abstract class UserVisibleFoo extends Foo { </pre> </blockquote> This doesn't prevent the user from creating subclasses derived from Foo, however, UserVisibleFoo provides the safety net that reminds the user to override the <code>method_upcall()</code> method. + </li> </ol> -<a name="odds_ends"></a> -<a name="n85"></a><H2>17.11 Odds and ends</H2> +<H2><a name="odds_ends"></a>19.11 Odds and ends</H2> -<a name="javadoc_comments"></a> -<a name="n86"></a><H3>17.11.1 JavaDoc comments</H3> +<H3><a name="javadoc_comments"></a>19.11.1 JavaDoc comments</H3> The SWIG documentation system is currently deprecated. @@ -5521,16 +5618,19 @@ public class Barmy { -<a name="functional_interface"></a> -<a name="n87"></a><H3>17.11.2 Functional interface without proxy classes</H3> +<H3><a name="functional_interface"></a>19.11.2 Functional interface without proxy classes</H3> +<p> It is possible to run SWIG in a mode that does not produce proxy classes by using the -noproxy commandline option. The interface is rather primitive when wrapping structures or classes and is accessed through function calls to the module class. All the functions in the module class are wrapped by functions with identical names as those in the intermediary JNI class. -<p> +</p> +<p> Consider the example we looked at when examining proxy classes: +</p> + <blockquote> <pre> class Foo { @@ -5573,8 +5673,7 @@ Unlike proxy classes, there is no attempt at tracking memory. All destructors have to be called manually for example the <tt>delete_Foo(foo)</tt> call above. -<a name="using_own_jni_functions"></a> -<a name="n88"></a><H3>17.11.3 Using your own JNI functions</H3> +<H3><a name="using_own_jni_functions"></a>19.11.3 Using your own JNI functions</H3> You may have some hand written JNI functions that you want to use in addition to the SWIG generated JNI functions. @@ -5606,35 +5705,41 @@ and as usual this function is wrapped by another which for a global C function w } </pre></blockquote> +<p> The <tt>packageName</tt> and <tt>moduleName</tt> must of course be correct else you will get linker errors when the JVM dynamically loads the JNI function. You may have to add in some "jtype", "jstype", "javain" and "javaout" typemaps when wrapping some JNI types. Here the default typemaps work for for <tt>int</tt> and <tt>char *</tt>. -<p> +</p> +<p> In summary the <tt>%native</tt> directive is telling SWIG to generate the Java code to access the JNI C code, but not the JNI C function itself. This directive is only really useful if you want to mix your own hand crafted JNI code and the SWIG generated code into one Java class or package. +</p> -<a name="performance"></a> -<a name="n89"></a><H3>17.11.4 Performance concerns and hints</H3> +<H3><a name="performance"></a>19.11.4 Performance concerns and hints</H3> +<p> If you're directly manipulating huge arrays of complex objects from Java, performance may suffer greatly when using the array functions in <tt>arrays_java.i</tt>. -Try and minimise the expensive JNI calls to C/C++ functions, perhaps by using temporary Java variables instead of accessing the information directly from the C/C++ object.<p> +Try and minimise the expensive JNI calls to C/C++ functions, perhaps by using temporary Java variables instead of accessing the information directly from the C/C++ object. +</p> +<p> Java classes without any finalizers generally speed up code execution as there is less for the garbage collector to do. Finalizer generation can be stopped by using an empty <tt>javafinalize</tt> typemap: +</p> <blockquote><pre> %typemap(javafinalize) SWIGTYPE "" </pre></blockquote> +<p> However, you will have to be careful about memory management and make sure that you code in a call to the <tt>delete()</tt> member function. This method calls the C++ destructor or <tt>free()</tt> for C code. -<p> +</p> -<a name="java_examples"></a> -<a name="n90"></a><H2>17.12 Examples</H2> +<H2><a name="java_examples"></a>19.12 Examples</H2> The directory Examples/java has a number of further examples. diff --git a/Doc/Manual/Library.html b/Doc/Manual/Library.html index be1ebd2be..bce66503b 100644 --- a/Doc/Manual/Library.html +++ b/Doc/Manual/Library.html @@ -5,32 +5,32 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>13 SWIG library</H1> +<H1><a name="Library"></a>8 SWIG library</H1> <!-- INDEX --> <ul> -<li><a href="#n2">The %include directive and library search path</a> -<li><a href="#n3">C Arrays and Pointers</a> +<li><a href="#Library_nn2">The %include directive and library search path</a> +<li><a href="#Library_nn3">C Arrays and Pointers</a> <ul> -<li><a href="#n4">cpointer.i</a> -<li><a href="#n5">carrays.i</a> -<li><a href="#n6">cmalloc.i</a> -<li><a href="#n7">cdata.i</a> +<li><a href="#Library_nn4">cpointer.i</a> +<li><a href="#Library_nn5">carrays.i</a> +<li><a href="#Library_nn6">cmalloc.i</a> +<li><a href="#Library_nn7">cdata.i</a> </ul> -<li><a href="#n8">C String Handling</a> +<li><a href="#Library_nn8">C String Handling</a> <ul> -<li><a href="#n9">Default string handling</a> -<li><a href="#n10">Passing binary data</a> -<li><a href="#n11">Using %newobject to release memory</a> -<li><a href="#n12">cstring.i</a> +<li><a href="#Library_nn9">Default string handling</a> +<li><a href="#Library_nn10">Passing binary data</a> +<li><a href="#Library_nn11">Using %newobject to release memory</a> +<li><a href="#Library_nn12">cstring.i</a> </ul> -<li><a href="#n13">C++ Library</a> +<li><a href="#Library_nn13">C++ Library</a> <ul> -<li><a href="#n14">std_string.i</a> -<li><a href="#n15">std_vector.i</a> +<li><a href="#Library_nn14">std_string.i</a> +<li><a href="#Library_nn15">std_vector.i</a> </ul> -<li><a href="#n16">Utility Libraries</a> +<li><a href="#Library_nn16">Utility Libraries</a> <ul> -<li><a href="#n17">exception.i</a> +<li><a href="#Library_nn17">exception.i</a> </ul> </ul> <!-- INDEX --> @@ -49,14 +49,14 @@ library files for manipulating pointers, arrays, and other structures. Most these files are now deprecated and have been removed from the distribution. Alternative libraries provide similar functionality. Please read this chapter carefully if you used the old libraries. +</p> -<a name="n2"></a><H2>13.1 The %include directive and library search path</H2> +<H2><a name="Library_nn2"></a>8.1 The %include directive and library search path</H2> Library files are included using the <tt>%include</tt> directive. When searching for files, directories are searched in the following order: -<p> <ul> <li>The current directory <li>Directories specified with the <tt>-I</tt> command line option @@ -64,16 +64,19 @@ When searching for files, directories are searched in the following order: <li><tt>/usr/local/lib/swig_lib</tt> (or wherever you installed SWIG) <li>On Windows, SWIG also looks for the library relative to the location of <tt>swig.exe</tt>. </ul> -<p> +<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. +</p> + <p> You can override the location of the SWIG library by setting the -<tt>SWIG_LIB</tt> environment variable.<p> +<tt>SWIG_LIB</tt> environment variable. +</p> -<a name="n3"></a><H2>13.2 C Arrays and Pointers</H2> +<H2><a name="Library_nn3"></a>8.2 C Arrays and Pointers</H2> This section describes library modules for manipulating low-level C arrays and pointers. @@ -83,7 +86,7 @@ used to allocate memory, manufacture pointers, dereference memory, and wrap pointers as class-like objects. Since these functions provide direct access to memory, their use is potentially unsafe and you should exercise caution. -<a name="n4"></a><H3>13.2.1 cpointer.i</H3> +<H3><a name="Library_nn4"></a>8.2.1 cpointer.i</H3> The <tt>cpointer.i</tt> module defines macros that can be used to used @@ -93,11 +96,15 @@ this module is in generating pointers to primitive datatypes such as <p> <b><tt>%pointer_functions(type,name)</tt></b> +</p> + <blockquote> Generates a collection of four functions for manipulating a pointer <tt>type *</tt>: <p> <tt>type *new_name()</tt> +</p> + <blockquote> Creates a new object of type <tt>type</tt> and returns a pointer to it. In C, the object is created using <tt>calloc()</tt>. In C++, <tt>new</tt> is used. @@ -105,6 +112,8 @@ object is created using <tt>calloc()</tt>. In C++, <tt>new</tt> is used. <p> <tt>type *copy_name(type value)</tt> +</p> + <blockquote> Creates a new object of type <tt>type</tt> and returns a pointer to it. An initial value is set by copying it from <tt>value</tt>. In C, the @@ -113,18 +122,24 @@ object is created using <tt>calloc()</tt>. In C++, <tt>new</tt> is used. <p> <tt>type *delete_name(type *obj)</tt> +</p> + <blockquote> Deletes an object type <tt>type</tt>. </blockquote> <p> <tt>void name_assign(type *obj, type value)</tt> +</p> + <blockquote> Assigns <tt>*obj = value</tt>. </blockquote> <p> <tt>type name_value(type *obj)</tt> +</p> + <blockquote> Returns the value of <tt>*obj</tt>. </blockquote> @@ -151,18 +166,19 @@ Now, in Python: <blockquote> <pre> ->>> import example ->>> c = example.new_intp() # Create an "int" for storing result ->>> example.add(3,4,c) # Call function ->>> example.intp_value(c) # Dereference +>>> import example +>>> c = example.new_intp() # Create an "int" for storing result +>>> example.add(3,4,c) # Call function +>>> example.intp_value(c) # Dereference 7 ->>> example.delete_intp(c) # Delete +>>> example.delete_intp(c) # Delete </pre> </blockquote> <p> -<p> <b><tt>%pointer_class(type,name)</tt></b> +</p> + <blockquote> Wraps a pointer of <tt>type *</tt> inside a class-based interface. This interface is as follows: @@ -190,10 +206,14 @@ the "class" may be transparently passed to any function that expects the pointe <p> If the target language does not support proxy classes, the use of this macro will produce the example same functions as <tt>%pointer_functions()</tt> macro. +</p> + <p> It should be noted that the class interface does introduce a new object or wrap a pointer inside a special structure. Instead, the raw pointer is used directly. +</p> + </blockquote> @@ -216,10 +236,10 @@ Now, in Python (using proxy classes) <blockquote> <pre> ->>> import example ->>> c = example.intp() # Create an "int" for storing result ->>> example.add(3,4,c) # Call function ->>> c.value() # Dereference +>>> import example +>>> c = example.intp() # Create an "int" for storing result +>>> example.add(3,4,c) # Call function +>>> c.value() # Dereference 7 </pre> </blockquote> @@ -229,8 +249,9 @@ pointers. This is because the pointers are access like objects and they can be (destruction of the pointer object destroys the underlying object). <p> -<p> <b><tt>%pointer_cast(type1, type2, name)</tt></b> +</p> + <blockquote> Creates a casting function that converts <tt>type1</tt> to <tt>type2</tt>. The name of the function is <tt>name</tt>. For example: @@ -247,11 +268,13 @@ In this example, the function <tt>int_to_uint()</tt> would be used to cast type <p> <b>Note:</b> None of these macros can be used to safely work with strings (<tt>char *</tt> or <tt>char **</tt>). +</p> <P> <b>Note:</b> When working with simple pointers, typemaps can often be used to provide more seamless operation. +</p> -<a name="n5"></a><H3>13.2.2 carrays.i</H3> +<H3><a name="Library_nn5"></a>8.2.2 carrays.i</H3> This module defines macros that assist in wrapping ordinary C pointers as arrays. @@ -261,11 +284,15 @@ raw C array data. <p> <b><tt>%array_functions(type,name)</tt></b> +</p> + <blockquote> Creates four functions. <p> <tt>type *new_name(int nelements)</tt> +</p> + <blockquote> Creates a new array of objects of type <tt>type</tt>. In C, the array is allocated using <tt>calloc()</tt>. In C++, <tt>new []</tt> is used. @@ -273,18 +300,24 @@ Creates a new array of objects of type <tt>type</tt>. In C, the array is alloc <p> <tt>type *delete_name(type *ary)</tt> +</p> + <blockquote> Deletes an array. In C, <tt>free()</tt> is used. In C++, <tt>delete []</tt> is used. </blockquote> <p> <tt>type name_getitem(type *ary, int index)</tt> +</p> + <blockquote> Returns the value <tt>ary[index]</tt>. </blockquote> <p> <tt>void name_setitem(type *ary, int index, type value)</tt> +</p> + <blockquote> Assigns <tt>ary[index] = value</tt>. </blockquote> @@ -296,6 +329,7 @@ should not correspond to any other name used in the interface file. <p> Here is an example of <tt>%array_functions()</tt>. Suppose you had a function like this: +</p> <blockquote> <pre> @@ -333,8 +367,6 @@ delete_doubleArray(a) # Destroy array </pre> </blockquote> -<p> -<p> <b><tt>%array_class(type,name)</tt></b> <blockquote> Wraps a pointer of <tt>type *</tt> inside a class-based interface. This @@ -365,6 +397,7 @@ it can be transparently passed to any function that expects the pointer. <p> When combined with proxy classes, the <tt>%array_class()</tt> macro can be especially useful. For example: +</p> <blockquote> <pre> @@ -392,12 +425,14 @@ example.print_array(c) # Pass to C <b>Note:</b> These macros do not encapsulate C arrays inside a special data structure or proxy. There is no bounds checking or safety of any kind. If you want this, you should consider using a special array object rather than a bare pointer. +</p> <p> <b>Note:</b> <tt>%array_functions()</tt> and <tt>%array_class()</tt> should not be used with types of <tt>char</tt> or <tt>char *</tt>. +</p> -<a name="n6"></a><H3>13.2.3 cmalloc.i</H3> +<H3><a name="Library_nn6"></a>8.2.3 cmalloc.i</H3> This module defines macros for wrapping the low-level C memory allocation functions @@ -405,6 +440,8 @@ This module defines macros for wrapping the low-level C memory allocation functi <p> <b><tt>%malloc(type [,name=type])</tt></b> +</p> + <blockquote> Creates a wrapper around <tt>malloc()</tt> with the following prototype: <blockquote><pre> @@ -418,6 +455,8 @@ is not a valid identifier (e.g., "<tt>int *</tt>", "<tt>double **</tt>", etc.). <p> <b><tt>%calloc(type [,name=type])</tt></b> +</p> + <blockquote> Creates a wrapper around <tt>calloc()</tt> with the following prototype: <blockquote><pre> @@ -429,6 +468,8 @@ If <tt>type</tt> is <tt>void</tt>, then the size parameter <tt>sz</tt> is requir <p> <b><tt>%realloc(type [,name=type])</tt></b> +</p> + <blockquote> Creates a wrapper around <tt>realloc()</tt> with the following prototype: <blockquote><pre> @@ -442,6 +483,8 @@ it holds 100 integers. <p> <b><tt>%free(type [,name=type])</tt></b> +</p> + <blockquote> Creates a wrapper around <tt>free()</tt> with the following prototype: <blockquote><pre> @@ -452,6 +495,8 @@ void free_<em>name</em>(<em>type</em> *ptr); <p> <b><tt>%sizeof(type [,name=type])</tt></b> +</p> + <blockquote> Creates the constant: <blockquote><pre> @@ -462,12 +507,15 @@ Creates the constant: <p> <b><tt>%allocators(type [,name=type])</tt></b> +</p> + <blockquote> Generates wrappers for all five of the above operations. </blockquote> <p> Here is a simple example that illustrates the use of these macros: +</p> <blockquote> <pre> @@ -489,27 +537,27 @@ Now, in a script: <blockquote> <pre> ->>> from example import * ->>> a = malloc_int() ->>> a +>>> from example import * +>>> a = malloc_int() +>>> a '_000efa70_p_int' ->>> free_int(a) ->>> b = malloc_intp() ->>> b +>>> free_int(a) +>>> b = malloc_intp() +>>> b '_000efb20_p_p_int' ->>> free_intp(b) ->>> c = calloc_double(50) ->>> c +>>> free_intp(b) +>>> c = calloc_double(50) +>>> c '_000fab98_p_double' ->>> c = realloc_double(100000) ->>> free_double(c) ->>> print sizeof_double +>>> c = realloc_double(100000) +>>> free_double(c) +>>> print sizeof_double 8 ->>> +>>> </pre> </blockquote> -<a name="n7"></a><H3>13.2.4 cdata.i</H3> +<H3><a name="Library_nn7"></a>8.2.4 cdata.i</H3> The <tt>cdata.i</tt> module defines functions for converting raw C data to and from strings @@ -520,6 +568,8 @@ in order for this to work. <p> <b><tt>char *cdata(void *ptr, int nbytes)</tt></b> +</p> + <blockquote> Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a string. <tt>ptr</tt> can be any pointer. @@ -527,6 +577,8 @@ pointer. <p> <b><tt>void memmove(void *ptr, char *s)</tt></b> +</p> + <blockquote> Copies all of the string data in <tt>s</tt> into the memory pointed to by <tt>ptr</tt>. The string may contain embedded NULL bytes. The length of @@ -551,18 +603,18 @@ Python example: <blockquote> <pre> ->>> a = intArray(10) ->>> for i in range(0,10): +>>> a = intArray(10) +>>> for i in range(0,10): ... a[i] = i ->>> b = cdata(a,40) ->>> b +>>> b = cdata(a,40) +>>> b '\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00\x04 \x00\x00\x00\x05\x00\x00\x00\x06\x00\x00\x00\x07\x00\x00\x00\x08\x00\x00\x00\t' ->>> c = intArray(10) ->>> memmove(c,b) ->>> print c[4] +>>> c = intArray(10) +>>> memmove(c,b) +>>> print c[4] 4 ->>> +>>> </pre> </blockquote> @@ -570,6 +622,8 @@ Since the size of data is not always known, the following macro is also defined: <p> <b><tt>%cdata(type [,name=type])</tt></b> +</p> + <blockquote> Generates the following function for extracting C data for a given type. <blockquote> @@ -583,7 +637,7 @@ char *cdata_<em>name</em>(int nitems) <b>Note:</b> These functions provide direct access to memory and can be used to overwrite data. Clearly they are unsafe. -<a name="n8"></a><H2>13.3 C String Handling</H2> +<H2><a name="Library_nn8"></a>8.3 C String Handling</H2> A common problem when working with C programs is dealing with @@ -599,8 +653,9 @@ The problems (and perils) of using <tt>char *</tt> are well-known. However, SWIG is not in the business of enforcing morality. The modules in this section provide basic functionality for manipulating raw C strings. +</p> -<a name="n9"></a><H3>13.3.1 Default string handling</H3> +<H3><a name="Library_nn9"></a>8.3.1 Default string handling</H3> Suppose you have a C function with this prototype: @@ -633,8 +688,9 @@ a <tt>char *</tt> argument points to data inside the target language, it is <b>NOT</b> safe for a function to modify this data (doing so may corrupt the 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> -<a name="n10"></a><H3>13.3.2 Passing binary data</H3> +<H3><a name="Library_nn10"></a>8.3.2 Passing binary data</H3> If you have a function that expects binary data, @@ -660,14 +716,14 @@ Now, in the target language, you can use binary string data like this: <blockquote> <pre> ->>> s = "H\x00\x15eg\x09\x20" ->>> parity(s,0) +>>> s = "H\x00\x15eg\x09\x20" +>>> parity(s,0) </pre> </blockquote> In the wrapper function, the passed string will be expanded to a pointer and length parameter. -<a name="n11"></a><H3>13.3.3 Using %newobject to release memory</H3> +<H3><a name="Library_nn11"></a>8.3.3 Using %newobject to release memory</H3> If you have a function that allocates memory like this, @@ -687,6 +743,7 @@ into a string object and the old contents ignored. <p> To fix the memory leak, use the <tt>%newobject</tt> directive. +</p> <blockquote> <pre> @@ -698,7 +755,7 @@ char *foo(); This will release the result. -<a name="n12"></a><H3>13.3.4 cstring.i</H3> +<H3><a name="Library_nn12"></a>8.3.4 cstring.i</H3> The <tt>cstring.i</tt> library file provides a collection of macros @@ -731,9 +788,12 @@ involving bounds checking). <p> The macros defined in this module all expand to various combinations of typemaps. Therefore, the same pattern matching rules and ideas apply. +</p> <p> <b>%cstring_bounded_output(parm, maxsize)</b> +</p> + <blockquote> Turns parameter <tt><em>parm</em></tt> into an output value. The output string is assumed to be NULL-terminated and smaller than @@ -751,9 +811,9 @@ In the target language: <blockquote> <pre> ->>> get_path() +>>> get_path() /home/beazley/packages/Foo/Bar ->>> +>>> </pre> </blockquote> @@ -768,6 +828,8 @@ bytes are written, your program will crash with a buffer overflow!</b> <p> <b>%cstring_chunk_output(parm, chunksize)</b> +</p> + <blockquote> Turns parameter <tt><em>parm</em></tt> into an output value. The output string is always <tt><em>chunksize</em></tt> and may contain @@ -785,9 +847,9 @@ In the target language: <blockquote> <pre> ->>> get_packet() +>>> get_packet() '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88' ->>> +>>> </pre> </blockquote> @@ -801,6 +863,8 @@ bytes are written, your program will crash with a buffer overflow!</b> <p> <b>%cstring_bounded_mutable(parm, maxsize)</b> +</p> + <blockquote> Turns parameter <tt><em>parm</em></tt> into a mutable string argument. The input string is assumed to be NULL-terminated and smaller than @@ -819,9 +883,9 @@ In the target language: <blockquote> <pre> ->>> make_upper("hello world") +>>> make_upper("hello world") 'HELLO WORLD' ->>> +>>> </pre> </blockquote> @@ -837,6 +901,8 @@ written, your program will crash with a buffer overflow!</b> <p> <b>%cstring_mutable(parm [, expansion])</b> +</p> + <blockquote> Turns parameter <tt><em>parm</em></tt> into a mutable string argument. The input string is assumed to be NULL-terminated. An optional @@ -861,11 +927,11 @@ In the target language: <blockquote> <pre> ->>> make_upper("hello world") +>>> make_upper("hello world") 'HELLO WORLD' ->>> attach_header("Hello world") +>>> attach_header("Hello world") 'header: Hello world' ->>> +>>> </pre> </blockquote> @@ -884,6 +950,8 @@ bytes, then the program will crash with a buffer overflow!</b> <p> <b>%cstring_output_maxsize(parm, maxparm)</b> +</p> + <blockquote> This macro is used to handle bounded character output functions where both a <tt>char *</tt> and a maximum length parameter are provided. @@ -902,9 +970,9 @@ In the target language: <blockquote> <pre> ->>> get_path(1024) +>>> get_path(1024) '/home/beazley/Packages/Foo/Bar' ->>> +>>> </pre> </blockquote> @@ -918,6 +986,8 @@ into that buffer and returned as a string object. <p> <b>%cstring_output_withsize(parm, maxparm)</b> +</p> + <blockquote> This macro is used to handle bounded character output functions where both a <tt>char *</tt> and a pointer <tt>int *</tt> are passed. Initially, @@ -938,11 +1008,11 @@ In the target language: <blockquote> <pre> ->>> get_data(1024) +>>> get_data(1024) 'x627388912' ->>> get_data(1024) +>>> get_data(1024) 'xyzzy' ->>> +>>> </pre> </blockquote> @@ -954,6 +1024,8 @@ how much data is actually returned by changing the value of the <tt>maxparm</tt> <p> <b>%cstring_output_allocate(parm, release)</b> +</p> + <blockquote> This macro is used to return strings that are allocated within the program and returned in a parameter of type <tt>char **</tt>. For example: @@ -983,9 +1055,9 @@ In the target language: <blockquote> <pre> ->>> foo() +>>> foo() 'Hello world\n' ->>> +>>> </pre> </blockquote> </blockquote> @@ -993,6 +1065,8 @@ In the target language: <p> <b>%cstring_output_allocate_size(parm, szparm, release)</b> +</p> + <blockquote> This macro is used to return strings that are allocated within the program and returned in two parameters of type <tt>char **</tt> and <tt>int *</tt>. For example: @@ -1024,9 +1098,9 @@ In the target language: <blockquote> <pre> ->>> foo() +>>> foo() '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88' ->>> +>>> </pre> </blockquote> @@ -1053,30 +1127,31 @@ void my_get_data(char **result, int *len) { <b>Comments:</b> <ul> -<Li>Support for the <tt>cstring.i</tt> module depends on the target language. Not all +<li>Support for the <tt>cstring.i</tt> module depends on the target language. Not all SWIG modules currently support this library. +</li> -<p> <li>Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques. +</li> -<P> <li>If used in C++, this library uses <tt>new</tt> and <tt>delete []</tt> for memory allocation. If using ANSI C, the library uses <tt>malloc()</tt> and <tt>free()</tt>. +</li> -<p> <li>Rather than manipulating <tt>char *</tt> directly, you might consider using a special string structure or class instead. +</li> </ul> -<a name="n13"></a><H2>13.4 C++ Library</H2> +<H2><a name="Library_nn13"></a>8.4 C++ Library</H2> The library modules in this section provide access to parts of the standard C++ library. All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete C++ library support including support for the STL. -<a name="n14"></a><H3>13.4.1 std_string.i</H3> +<H3><a name="Library_nn14"></a>8.4.1 std_string.i</H3> The <tt>std_string.i</tt> library provides typemaps for converting C++ <tt>std::string</tt> @@ -1088,7 +1163,7 @@ objects to and from strings in the target scripting language. For example: %include "std_string.i" std::string foo(); -void bar(const std::string &x); +void bar(const std::string &x); </pre> </blockquote> @@ -1102,12 +1177,13 @@ bar("Hello World"); # Pass string as std::string </blockquote> This module only supports types <tt>std::string</tt> and -<tt>const std::string &</tt>. Pointers and non-const references +<tt>const std::string &</tt>. Pointers and non-const references are left unmodified and returned as SWIG pointers. <p> This library file is fully aware of C++ namespaces. If you export <tt>std::string</tt> or rename it with a typedef, make sure you include those declarations in your interface. For example: +</p> <blockquote> <pre> @@ -1117,14 +1193,14 @@ it with a typedef, make sure you include those declarations in your interface. using namespace std; typedef std::string String; ... -void foo(string s, const String &t); // std_string typemaps still applied +void foo(string s, const String &t); // std_string typemaps still applied </pre> </blockquote> <b>Note:</b> The <tt>std_string</tt> library is incompatible with Perl on some platforms. We're looking into it. -<a name="n15"></a><H3>13.4.2 std_vector.i</H3> +<H3><a name="Library_nn15"></a>8.4.2 std_vector.i</H3> The <tt>std_vector.i</tt> library provides support for the C++ <tt>vector</tt> class in the STL. @@ -1137,66 +1213,66 @@ instantiate different versions of <tt>vector</tt> for the types that you want to %include "std_vector.i" namespace std { - %template(vectori) vector<int>; - %template(vectord) vector<double>; + %template(vectori) vector<int>; + %template(vectord) vector<double>; }; </pre> </blockquote> -When a template <tt>vector<X></tt> is instantiated a number of things happen: +When a template <tt>vector<X></tt> is instantiated a number of things happen: <ul> <li>A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class. +</li> -<p> -<li>Input typemaps are defined for <tt>vector<X></tt>, <tt>const vector<X> &</tt>, and -<tt>const vector<X> *</tt>. For each of these, a pointer <tt>vector<X> *</tt> may be passed or +<li>Input typemaps are defined for <tt>vector<X></tt>, <tt>const vector<X> &</tt>, and +<tt>const vector<X> *</tt>. For each of these, a pointer <tt>vector<X> *</tt> may be passed or a native list object in the target language. +</li> -<P> -<li>An output typemap is defined for <tt>vector<X></tt>. In this case, the values in the +<li>An output typemap is defined for <tt>vector<X></tt>. In this case, the values in the vector are expanded into a list object in the target language. +</li> -<p> -<li>For all other variations of the type, the wrappers expect to receive a <tt>vector<X> *</tt> +<li>For all other variations of the type, the wrappers expect to receive a <tt>vector<X> *</tt> object in the usual manner. +</li> -<P> <li>An exception handler for <tt>std::out_of_range</tt> is defined. +</li> -<p> <li>Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language. +</li> </ul> -<p> To illustrate the use of this library, consider the following functions: <blockquote> <pre> /* File : example.h */ -#include <vector> -#include <algorithm> -#include <functional> -#include <numeric> +#include <vector> +#include <algorithm> +#include <functional> +#include <numeric> -double average(std::vector<int> v) { +double average(std::vector<int> v) { return std::accumulate(v.begin(),v.end(),0.0)/v.size(); } -std::vector<double> half(const std::vector<double>& v) { - std::vector<double> w(v); +std::vector<double> half(const std::vector<double>& v) { + std::vector<double> w(v); for (unsigned int i=0; i<w.size(); i++) w[i] /= 2.0; return w; } -void halve_in_place(std::vector<double>& v) { +void halve_in_place(std::vector<double>& v) { std::transform(v.begin(),v.end(),v.begin(), - std::bind2nd(std::divides<double>(),2.0)); + std::bind2nd(std::divides<double>(),2.0)); } </pre> </blockquote> @@ -1213,8 +1289,8 @@ To wrap with SWIG, you might write the following: %include "std_vector.i" // Instantiate templates used by example namespace std { - %template(IntVector) vector<int>; - %template(DoubleVector) vector<double>; + %template(IntVector) vector<int>; + %template(DoubleVector) vector<double>; } // Include the header file with above prototypes @@ -1226,38 +1302,38 @@ Now, to illustrate the behavior in the scripting interpreter, consider this Pyth <blockquote> <pre> ->>> from example import * ->>> iv = IntVector(4) # Create an vector<int> ->>> for i in range(0,4): +>>> from example import * +>>> iv = IntVector(4) # Create an vector<int> +>>> for i in range(0,4): ... iv[i] = i ->>> average(iv) # Call method +>>> average(iv) # Call method 1.5 ->>> average([0,1,2,3]) # Call with list +>>> average([0,1,2,3]) # Call with list 1.5 ->>> half([1,2,3]) # Half a list +>>> half([1,2,3]) # Half a list (0.5,1.0,1.5) ->>> halve_in_place([1,2,3]) # Oops +>>> halve_in_place([1,2,3]) # Oops Traceback (most recent call last): - File "<stdin>", line 1, in ? + File "<stdin>", line 1, in ? TypeError: Type error. Expected _p_std__vectorTdouble_t ->>> dv = DoubleVector(4) ->>> for i in range(0,4): +>>> dv = DoubleVector(4) +>>> for i in range(0,4): ... dv[i] = i ->>> halve_in_place(dv) # Ok ->>> for i in dv: +>>> halve_in_place(dv) # Ok +>>> for i in dv: ... print i ... 0.0 0.5 1.0 1.5 ->>> dv[20] = 4.5 +>>> dv[20] = 4.5 Traceback (most recent call last): - File "<stdin>", line 1, in ? + File "<stdin>", line 1, in ? File "example.py", line 81, in __setitem__ def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args) IndexError: vector index out of range ->>> +>>> </pre> </blockquote> @@ -1269,13 +1345,13 @@ make sure you include the appropriate <tt>using</tt> or typedef directives. For %include "std_vector.i" namespace std { - %template(IntVector) vector<int>; + %template(IntVector) vector<int>; } using namespace std; typedef std::vector Vector; -void foo(vector<int> *x, const Vector &x); +void foo(vector<int> *x, const Vector &x); </pre> </blockquote> @@ -1284,19 +1360,22 @@ void foo(vector<int> *x, const Vector &x); and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in <tt>std_vector.i</tt>. Alternatively, you can show them the code if you want to make their head explode. +</p> <p> <b>Note:</b> This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary. +</p> <p> <b>Note:</b> <tt>std_vector.i</tt> was written by Luigi "The Amazing" Ballabio. +</p> -<a name="n16"></a><H2>13.5 Utility Libraries</H2> +<H2><a name="Library_nn16"></a>8.5 Utility Libraries</H2> -<a name="n17"></a><H3>13.5.1 exception.i</H3> +<H3><a name="Library_nn17"></a>8.5.1 exception.i</H3> The <tt>exception.i</tt> library provides a language-independent function for raising a run-time @@ -1304,6 +1383,8 @@ exception in the target language. <p> <b><tt>SWIG_exception(int code, const char *message)</tt></b> +</p> + <blockquote> Raises an exception in the target language. <tt>code</tt> is one of the following symbolic constants: @@ -1336,14 +1417,14 @@ For example: try { $action } catch (std::out_of_range& e) { - SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what())); + SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what())); } } </pre> </blockquote> -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : May 29, 2002</address> </body> </html> diff --git a/Doc/Manual/Modula3.html b/Doc/Manual/Modula3.html index c9fbba7ca..81afe4851 100644 --- a/Doc/Manual/Modula3.html +++ b/Doc/Manual/Modula3.html @@ -4,31 +4,31 @@ <title>SWIG and Modula-3</title> </head> <body bgcolor="#FFFFFF"> -<a name="n1"></a><H1>18 SWIG and Modula-3</H1> +<H1><a name="Modula3"></a>20 SWIG and Modula-3</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Overview</a> -<li><a href="#n3">Conception</a> +<li><a href="#modula3_overview">Overview</a> +<li><a href="#conception">Conception</a> <ul> -<li><a href="#n4">Interfaces to C libraries</a> -<li><a href="#n5">Interfaces to C++ libraries</a> -<li><a href="#n6">No plan?</a> +<li><a href="#cinterface">Interfaces to C libraries</a> +<li><a href="#noplan">Interfaces to C++ libraries</a> +<li><a href="#cppinterface">No plan?</a> </ul> -<li><a href="#n7">Preliminaries</a> +<li><a href="#preliminaries">Preliminaries</a> <ul> -<li><a href="#n8">Compilers</a> -<li><a href="#n9">Additional Commandline Options</a> +<li><a href="#compilers">Compilers</a> +<li><a href="#commandline">Additional Commandline Options</a> </ul> -<li><a href="#n10">Modula-3 typemaps</a> +<li><a href="#modula3_typemaps">Modula-3 typemaps</a> <ul> -<li><a href="#n11">Inputs and outputs</a> -<li><a href="#n12">Subranges, Enumerations, Sets</a> -<li><a href="#n13">Objects</a> -<li><a href="#n14">Imports</a> -<li><a href="#n15">Exceptions</a> -<li><a href="#n16">Pragmas</a> -<li><a href="#n17">Example</a> -<li><a href="#n18">Remarks</a> +<li><a href="#inoutparam">Inputs and outputs</a> +<li><a href="#ordinals">Subranges, Enumerations, Sets</a> +<li><a href="#class">Objects</a> +<li><a href="#imports">Imports</a> +<li><a href="#exceptions">Exceptions</a> +<li><a href="#swig_pragmas">Pragmas</a> +<li><a href="#typemap_example">Example</a> +<li><a href="#remarks">Remarks</a> </ul> </ul> <!-- INDEX --> @@ -38,12 +38,11 @@ This chapter describes SWIG's support of <a href="http://www.m3.org/">Modula-3</a>. You should be familiar with the -<a href="SWIG.html">basics</a> +<a href="SWIG.html#SWIG">basics</a> of SWIG, especially typemaps. -<a name="overview"></a> -<a name="n2"></a><H2>18.1 Overview</H2> +<H2><a name="modula3_overview"></a>20.1 Overview</H2> <p> @@ -52,6 +51,8 @@ Many features are still not designed satisfyingly and I need more discussion about the odds and ends. The Modula-3 generator was already useful for interfacing to the libraries +</p> + <a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/plplot/"> PLPlot </a> @@ -66,9 +67,9 @@ FFTW The following introduction may help you when you are uncertain about using the Modula-3 support or SWIG at all. +</p> -<a name="whycxx"></a> <a name="n3"></a><DISABLED>18.1.1 Why not scripting ?</DISABLED> @@ -80,6 +81,7 @@ to make programming life easier by hiding machine internals from the programmer there are several aspects of todays scripting languages that are unfavourable in my opinion. +</p> <p> Besides C, C++, Cluster (a Modula derivate for Amiga computers) @@ -102,8 +104,8 @@ e.g. matching regular expressions, complex built-in datatypes like lists, dictionaries, are not advantages of the language itself but can be provided by function libraries. +</p> -<a name="whymodula3"></a> <a name="n4"></a><DISABLED>18.1.2 Why Modula-3 ?</DISABLED> @@ -124,6 +126,7 @@ control three languages, namely the preprocessor, C and ++, Modula-3 is made in one go and the language definition is really compact. +</p> On the one hand Modula-3 can be safe (but probably less efficient) in normal modules @@ -138,14 +141,13 @@ requires more writing than scripting languages do. Today if I want to safe characters I prefer Haskell (similar to OCAML) - it's statically typed, too. +</p> -<a name="whycxx"></a> <a name="n5"></a><DISABLED>18.1.3 Why C / C++ ?</DISABLED> <p> - Although it is no problem to write Modula-3 programs that performs as fast as C most libraries are not written in Modula-3 but in C. @@ -153,13 +155,12 @@ Fortunately the binary interface of most function libraries can be addressed by Modula-3. Even more fortunately even non-C libraries may provide C header files. This is where SWIG becomes helpful. +</p> -<a name="whycxx"></a> <a name="n6"></a><DISABLED>18.1.4 Why SWIG ?</DISABLED> <p> - The C headers and the possibility to interface to C libraries still leaves the work for you to write Modula-3 interfaces to them. @@ -167,9 +168,9 @@ To make things comfortable you will also need wrappers that convert between high-level features of Modula-3 (garbage collecting, exceptions) and the low level of the C libraries. +</p> <p> - SWIG converts C headers to Modula-3 interfaces for you. You could call the C functions without loss of efficiency but it won't be joy @@ -185,6 +186,7 @@ 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 otherwise you lose static safety and consistency. +</p> <p> @@ -203,9 +205,10 @@ when a new library version is released. You will realise that writing <b>good</b> SWIG interfaces is very costly and it will only amortise when considering evolving libraries. +</p> -<p> +<p> Without SWIG you would probably never consider to call C++ libraries from Modula-3. But with SWIG this is worth a consideration. @@ -215,23 +218,22 @@ In fact it breaks down C++ libraries to C interfaces which can be in turn called from Modula-3. To make it complete you can hide the C interface with Modula-3 classes and exceptions. +</p> <p> - Although SWIG does the best it can do it can only serve as a one-way strategy. That means you can use C++ libraries with Modula-3 (even with call back functions), but it's certainly not possible to smoothly integrate Modula-3 code into a C / C++ project. +</p> --> -<a name="conception"></a> -<a name="n3"></a><H2>18.2 Conception</H2> +<H2><a name="conception"></a>20.2 Conception</H2> -<a name="cinterface"></a> -<a name="n4"></a><H3>18.2.1 Interfaces to C libraries</H3> +<H3><a name="cinterface"></a>20.2.1 Interfaces to C libraries</H3> <p> @@ -249,7 +251,7 @@ All you have to do is to write pieces of Modula-3 code that SWIG puts together. </p> -<table border> +<table border summary="Modula-3 C library support"> <tr><th colspan=2>C library support integrated in Modula-3<th></tr> <tr> <td>Pragma <tt><* EXTERNAL *></tt></td> @@ -276,7 +278,7 @@ and C's <tt>char *</tt> type.</td> In each run of SWIG the Modula-3 part generates several files: </p> -<table border> +<table border summary="Modula-3 generated files"> <tr> <td>Module<tt>Raw.i3</tt></td> <td>Declaration of types that are equivalent to those of the C library, @@ -314,7 +316,7 @@ generates several files: Here's a scheme of how the function calls to Modula-3 wrappers a redirected to C library functions: -<table> +<table summary="Modula-3 C library"> <tr> <td align=center> Modula-3 wrapper<br> @@ -347,8 +349,7 @@ a redirected to C library functions: </table> -<a name="cppinterface"></a> -<a name="n5"></a><H3>18.2.2 Interfaces to C++ libraries</H3> +<H3><a name="noplan"></a>20.2.2 Interfaces to C++ libraries</H3> <p> @@ -361,7 +362,7 @@ with a C interface. Here's a scheme of how the function calls to Modula-3 wrappers a redirected to C library functions: -<table> +<table summary="Modula-3 C++ library"> <tr> <td align=center> Modula-3 wrapper<br> @@ -400,6 +401,7 @@ a redirected to C library functions: <p> Wrapping C++ libraries arises additional problems: +</p> <ul> <li> Is it sensible to wrap C++ class with Modula-3 classes? @@ -445,8 +447,7 @@ There is no C++ library I wrote a SWIG interface for, so I'm not sure if this is possible or sensible, yet. </p> -<a name="cppinterface"></a> -<a name="n6"></a><H3>18.2.3 No plan?</H3> +<H3><a name="cppinterface"></a>20.2.3 No plan?</H3> <p> @@ -468,12 +469,10 @@ and the principal type must be renamed (<tt>%typemap</tt>). </p> -<a name="preliminaries"></a> -<a name="n7"></a><H2>18.3 Preliminaries</H2> +<H2><a name="preliminaries"></a>20.3 Preliminaries</H2> -<a name="compilers"></a> -<a name="n8"></a><H3>18.3.1 Compilers</H3> +<H3><a name="compilers"></a>20.3.1 Compilers</H3> There are different Modula-3 compilers around: @@ -485,8 +484,7 @@ may do so. For testing examples I used Critical Mass cm3. -<a name="commandline"></a> -<a name="n9"></a><H3>18.3.2 Additional Commandline Options</H3> +<H3><a name="commandline"></a>20.3.2 Additional Commandline Options</H3> There are some experimental command line options @@ -494,7 +492,7 @@ that prevent SWIG from generating interface files. Instead files are emitted that may assist you when writing SWIG interface files. -<table> +<table summary="Modula-3 specific options"> <tr> <th>Modula-3 specific options</th> </tr> @@ -560,12 +558,10 @@ Instead generate templates for some basic typemaps. </tr> </table> -<a name="typemaps"></a> -<a name="n10"></a><H2>18.4 Modula-3 typemaps</H2> +<H2><a name="modula3_typemaps"></a>20.4 Modula-3 typemaps</H2> -<a name="inoutparam"></a> -<a name="n11"></a><H3>18.4.1 Inputs and outputs</H3> +<H3><a name="inoutparam"></a>20.4.1 Inputs and outputs</H3> <p> @@ -614,7 +610,7 @@ consist of the following parts: <li>Return values.</li> </ul> -<table border> +<table border summary="Modula-3 typemaps"> <tr> <th>Typemap</th> <th>Example</th> @@ -654,21 +650,21 @@ consist of the following parts: </tr> <tr> <td>m3wrapinname</td> - <td><tt></tt></td> + <td></td> <td> New name of the input argument. </td> </tr> <tr> <td>m3wrapintype</td> - <td><tt></tt></td> + <td></td> <td> Modula-3 type of the input argument. </td> </tr> <tr> <td>m3wrapindefault</td> - <td><tt></tt></td> + <td></td> <td> Default value of the input argument </td> @@ -682,14 +678,14 @@ consist of the following parts: </tr> <tr> <td>m3wrapincheck</td> - <td><tt>IF Text.Length($1_name) > 10 THEN RAISE E("str too long"); END;</tt></td> + <td><tt>IF Text.Length($1_name) > 10 THEN RAISE E("str too long"); END;</tt></td> <td> Check the integrity of the input value. </td> </tr> <tr> <td>m3wrapoutname</td> - <td><tt></tt></td> + <td></td> <td> Name of the <tt>RECORD</tt> field to be used for returning multiple values. This applies to referential output arguments that shall be turned @@ -698,56 +694,56 @@ consist of the following parts: </tr> <tr> <td>m3wrapouttype</td> - <td><tt></tt></td> + <td></td> <td> Type of the value that is returned instead of a referential output argument. </td> </tr> <tr> <td>m3wrapoutconv</td> - <td><tt></tt></td> + <td></td> <td> </td> </tr> <tr> <td>m3wrapoutcheck</td> - <td><tt></tt></td> + <td></td> <td> </td> </tr> <tr> <td>m3wrapretraw</td> - <td><tt></tt></td> + <td></td> <td> </td> </tr> <tr> <td>m3wrapretname</td> - <td><tt></tt></td> + <td></td> <td> </td> </tr> <tr> <td>m3wraprettype</td> - <td><tt></tt></td> + <td></td> <td> </td> </tr> <tr> <td>m3wrapretvar</td> - <td><tt></tt></td> + <td></td> <td> </td> </tr> <tr> <td>m3wrapretconv</td> - <td><tt></tt></td> + <td></td> <td> </td> </tr> <tr> <td>m3wrapretcheck</td> - <td><tt></tt></td> + <td></td> <td> </td> </tr> @@ -764,16 +760,13 @@ consist of the following parts: </table> -<a name="ordinals"></a> -<a name="n12"></a><H3>18.4.2 Subranges, Enumerations, Sets</H3> +<H3><a name="ordinals"></a>20.4.2 Subranges, Enumerations, Sets</H3> -<a name="class"></a> -<a name="n13"></a><H3>18.4.3 Objects</H3> +<H3><a name="class"></a>20.4.3 Objects</H3> -<a name="imports"></a> -<a name="n14"></a><H3>18.4.4 Imports</H3> +<H3><a name="imports"></a>20.4.4 Imports</H3> <p> @@ -806,8 +799,7 @@ IMPORT M3toC; </pre> -<a name="exceptions"></a> -<a name="n15"></a><H3>18.4.5 Exceptions</H3> +<H3><a name="exceptions"></a>20.4.5 Exceptions</H3> Modula-3 provides another possibility @@ -825,11 +817,10 @@ contains code that may raise the exceptions <tt>OSError.E</tt> you should declare <tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>. -<a name="swig_pragmas"></a> -<a name="n16"></a><H3>18.4.6 Pragmas</H3> +<H3><a name="swig_pragmas"></a>20.4.6 Pragmas</H3> -<table border> +<table border summary="Modula-3 pragmas"> <tr> <td>unsafe</td> <td><tt>%pragma(modula3) unsafe="true";</tt></td> @@ -844,8 +835,7 @@ you should declare </tr> </table> -<a name="typemap_example"></a> -<a name="n17"></a><H3>18.4.7 Example</H3> +<H3><a name="typemap_example"></a>20.4.7 Example</H3> The generation of wrappers in Modula-3 needs very fine control @@ -871,7 +861,7 @@ where almost everything is generated by a typemap: BEGIN TRY arg1 := M3toC.SharedTtoS(str); <I>(* m3wrapinconv *)</I> - IF Text.Length(arg1) > 10 THEN <I>(* m3wrapincheck *)</I> + IF Text.Length(arg1) > 10 THEN <I>(* m3wrapincheck *)</I> RAISE E("str too long"); END; <I> (* m3wrapretraw m3wrapargraw *)</I> @@ -887,8 +877,7 @@ where almost everything is generated by a typemap: END Name; </pre></blockquote> -<a name="remarks"></a> -<a name="n18"></a><H3>18.4.8 Remarks</H3> +<H3><a name="remarks"></a>20.4.8 Remarks</H3> <ul> diff --git a/Doc/Manual/Modules.html b/Doc/Manual/Modules.html index 8c257368e..2af27c5a9 100644 --- a/Doc/Manual/Modules.html +++ b/Doc/Manual/Modules.html @@ -5,13 +5,14 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>14 Working with Modules</H1> +<H1><a name="Modules"></a>15 Working with Modules</H1> <!-- INDEX --> <ul> -<li><a href="#n2">The SWIG runtime code</a> -<li><a href="#n3">Compiling Multiple SWIG modules</a> -<li><a href="#n4">A word of caution about static libraries</a> -<li><a href="#n5">References</a> +<li><a href="#Modules_nn2">The SWIG runtime code</a> +<li><a href="#Modules_nn3">Compiling Multiple SWIG modules</a> +<li><a href="#Modules_nn4">A word of caution about static libraries</a> +<li><a href="#Modules_nn5">References</a> +<li><a href="#Modules_nn6">Reducing the wrapper file size</a> </ul> <!-- INDEX --> @@ -28,8 +29,9 @@ target language interface when it is broken up into smaller pieces. <p> This chapter describes the problem of using SWIG in programs where you want to create a collection of modules. +</p> -<a name="n2"></a><H2>14.1 The SWIG runtime code</H2> +<H2><a name="Modules_nn2"></a>15.1 The SWIG runtime code</H2> Many of SWIG's target languages generate a set of functions @@ -52,13 +54,15 @@ module is used in the same application, those modules often need to share type information. This is especially true for C++ programs where SWIG must collect and share information about inheritance relationships that cross module boundaries. +</p> <p> To solve the problem of sharing information across modules, the SWIG runtime functions need to be exposed in a way that allows data to be shared between modules. The next section describes how to do that. +</p> -<a name="n3"></a><H2>14.2 Compiling Multiple SWIG modules</H2> +<H2><a name="Modules_nn3"></a>15.2 Compiling Multiple SWIG modules</H2> Suppose that you have three SWIG interface files A.i, B.i, and C.i @@ -67,10 +71,12 @@ there are two approaches you can take: <p> <b>Option 1:</b> Designate one module to provide the runtime code +</p> <p> With this option, one of the modules is designated as providing the runtime environment. This is done with the <tt>-runtime</tt> option like this: +</p> <blockquote> <pre> @@ -99,14 +105,17 @@ on the system. On many systems, the symbols contained in dynamically loaded mod are private. Therefore, even though module A provides the runtime code, the other modules won't be able to find it. You'll know if this is the case if you try to load the other modules and you get errors about unresolved SWIG_* functions. +</p> <p> <b>Option 2: Build a runtime library</b> +</p> <p> The second way to work with multiple modules is to create a special runtime library module. To do this, you first need to create an empty SWIG interface file, say swigrun.i, containing just the %module directive, for example: +</p> <blockquote> <pre> @@ -155,8 +164,9 @@ you need to link all of the modules against that library. When you use the modules created using this technique, the runtime code will be automatically loaded when the modules are imported. Moreover, since all of the modules are linked against the same runtime library, they will share that code. +</p> -<a name="n4"></a><H2>14.3 A word of caution about static libraries</H2> +<H2><a name="Modules_nn4"></a>15.3 A word of caution about static libraries</H2> When working with multiple SWIG modules, you should take care not to use static @@ -165,27 +175,31 @@ of SWIG modules with that library, each module will get its own private copy of into it. This is very often <b>NOT</b> what you want and it can lead to unexpected or bizarre program behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libaries. -<a name="n5"></a><H2>14.4 References</H2> +<H2><a name="Modules_nn5"></a>15.4 References</H2> Due to the complexity of working with shared libraries and multiple modules, it might be a good idea to consult an outside reference. John Levine's "Linkers and Loaders" is highly recommended. -<a name="n6"></a><H2>14.5 Reducing the wrapper file size</H2> +<H2><a name="Modules_nn6"></a>15.5 Reducing the wrapper file size</H2> + + +<p> Using multiple modules with the <tt>%import</tt> directive is the most common approach to modularising large projects. In this way a number of different wrapper files can be generated, thereby avoiding the generation of a single large wrapper file. There are a couple of alternative solutions for reducing the size of a wrapper file through the use of command line options. +</p> -<p/> <b>-fcompact</b><br> This command line option will compact the size of the wrapper file without changing the code generated into the wrapper file. It simply removes blank lines and joins lines of code together. This is useful for compilers that have a maximum file size that can be handled. -<p/> +<p> <b>-fvirtual</b><br> This command line option will remove the generation of superfluous virtual method wrappers. Consider the following inheritance hierarchy: +</p> <blockquote> <pre> @@ -204,7 +218,7 @@ Normally wrappers are generated for both methods, whereas this command line opti Normal polymorphic behaviour remains as <tt>Derived::method</tt> will still be called should you have a <tt>Derived</tt> instance and call the wrapper for <tt>Base::method</tt>. -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : July 9, 2004</address> </body> diff --git a/Doc/Manual/Ocaml.html b/Doc/Manual/Ocaml.html index bd368cc15..46e38c06c 100644 --- a/Doc/Manual/Ocaml.html +++ b/Doc/Manual/Ocaml.html @@ -6,47 +6,47 @@ </head> <body bgcolor="#ffffff"> <a name="n1"></a> -<a name="n1"></a><H1>19 SWIG and Ocaml</H1> +<H1><a name="Ocaml"></a>21 SWIG and Ocaml</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Preliminaries</a> +<li><a href="#Ocaml_nn2">Preliminaries</a> <ul> -<li><a href="#n3">Running SWIG</a> -<li><a href="#n4">Compiling the code</a> -<li><a href="#n5">The camlp4 module</a> -<li><a href="#n6">Using your module</a> -<li><a href="#n7">Compilation problems and compiling with C++</a> +<li><a href="#Ocaml_nn3">Running SWIG</a> +<li><a href="#Ocaml_nn4">Compiling the code</a> +<li><a href="#Ocaml_nn5">The camlp4 module</a> +<li><a href="#Ocaml_nn6">Using your module</a> +<li><a href="#Ocaml_nn7">Compilation problems and compiling with C++</a> </ul> -<li><a href="#n8">The low-level Ocaml/C interface</a> +<li><a href="#Ocaml_nn8">The low-level Ocaml/C interface</a> <ul> -<li><a href="#n9">The generated module</a> -<li><a href="#n10">Enums</a> -<li><a href="#n11">Arrays</a> +<li><a href="#Ocaml_nn9">The generated module</a> +<li><a href="#Ocaml_nn10">Enums</a> +<li><a href="#Ocaml_nn11">Arrays</a> <ul> -<li><a href="#n12">Simple types of bounded arrays</a> -<li><a href="#n13">Complex and unbounded arrays</a> -<li><a href="#n14">Using an object</a> -<li><a href="#n15">Example typemap for a function taking float * and int</a> +<li><a href="#Ocaml_nn12">Simple types of bounded arrays</a> +<li><a href="#Ocaml_nn13">Complex and unbounded arrays</a> +<li><a href="#Ocaml_nn14">Using an object</a> +<li><a href="#Ocaml_nn15">Example typemap for a function taking float * and int</a> </ul> -<li><a href="#n16">C++ Classes</a> +<li><a href="#Ocaml_nn16">C++ Classes</a> <ul> -<li><a href="#n17">STL vector and string Example</a> -<li><a href="#n18">C++ Class Example</a> -<li><a href="#n19">Compiling the example</a> -<li><a href="#n20">Sample Session</a> +<li><a href="#Ocaml_nn17">STL vector and string Example</a> +<li><a href="#Ocaml_nn18">C++ Class Example</a> +<li><a href="#Ocaml_nn19">Compiling the example</a> +<li><a href="#Ocaml_nn20">Sample Session</a> </ul> -<li><a href="#n21">Director Classes</a> +<li><a href="#Ocaml_nn21">Director Classes</a> <ul> -<li><a href="#n22">Director Introduction</a> -<li><a href="#n23">Overriding Methods in Ocaml</a> -<li><a href="#n24">Director Usage Example</a> -<li><a href="#n25">Creating director objects</a> -<li><a href="#n26">Typemaps for directors, <tt>directorin, directorout, directorargout</tt></a> -<li><a href="#n27"><tt>directorin</tt> typemap</a> -<li><a href="#n28"><tt>directorout</tt> typemap</a> -<li><a href="#n29"><tt>directorargout</tt> typemap</a> +<li><a href="#Ocaml_nn22">Director Introduction</a> +<li><a href="#Ocaml_nn23">Overriding Methods in Ocaml</a> +<li><a href="#Ocaml_nn24">Director Usage Example</a> +<li><a href="#Ocaml_nn25">Creating director objects</a> +<li><a href="#Ocaml_nn26">Typemaps for directors, <tt>directorin, directorout, directorargout</tt></a> +<li><a href="#Ocaml_nn27"><tt>directorin</tt> typemap</a> +<li><a href="#Ocaml_nn28"><tt>directorout</tt> typemap</a> +<li><a href="#Ocaml_nn29"><tt>directorargout</tt> typemap</a> </ul> -<li><a href="#n30">Exceptions</a> +<li><a href="#Ocaml_nn30">Exceptions</a> </ul> </ul> <!-- INDEX --> @@ -73,7 +73,7 @@ If you're not familiar with the Objective Caml language, you can visit <a href="http://www.ocaml.org/">The Ocaml Website</a>. </p> -<a name="n2"></a><H2>19.1 Preliminaries</H2> +<H2><a name="Ocaml_nn2"></a>21.1 Preliminaries</H2> SWIG 1.3 works with Ocaml 3.04 and above. Given the choice, @@ -90,7 +90,7 @@ usual -lxxx against libxxx.so, as well as with Gerd Stolpmann's 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. -<a name="n3"></a><H3>19.1.1 Running SWIG</H3> +<H3><a name="Ocaml_nn3"></a>21.1.1 Running SWIG</H3> The basics of getting a SWIG Ocaml module up and running @@ -99,7 +99,9 @@ will be loaded dynamically. This has only been tested on Linux so far. option. <blockquote> - <pre>%swig -ocaml example.i</pre> + <pre> +%swig -ocaml example.i + </pre> </blockquote> <p> This will produce 3 files. The file <tt>example_wrap.c</tt> contains @@ -109,9 +111,10 @@ you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or the resulting .ml and .mli files as well, and do the final link with -custom (not needed for native link). </p> -<a name="n4"></a><H3>19.1.2 Compiling the code</H3> +<H3><a name="Ocaml_nn4"></a>21.1.2 Compiling the code</H3> +<p> The O'Caml 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 @@ -122,7 +125,7 @@ the user more freedom with respect to custom typing. Use <tt>ocamlc</tt> or <tt>ocamlopt</tt> to compile your SWIG interface like: -<p> </p> +</p> <blockquote> <pre> @@ -131,38 +134,47 @@ the user more freedom with respect to custom typing. % ocamlc -c -ccopt "-I/usr/include/foo" example_wrap.c % ocamlc -c example.mli % ocamlc -c example.ml - </blockquote> + </pre> +</blockquote> <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> <blockquote> - <pre>% cp example_wrap.cxx example_wrap.cxx.c<br>% ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c<br>% ...<br></pre> - </blockquote> + <pre> +% cp example_wrap.cxx example_wrap.cxx.c<br>% ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c<br>% ...<br> + </pre> +</blockquote> -<a name="n5"></a><H3>19.1.3 The camlp4 module</H3> +<H3><a name="Ocaml_nn5"></a>21.1.3 The camlp4 module</H3> +<p> The camlp4 module (swigp4.ml -> swigp4.cmo) contains a simple rewriter which makes C++ code blend more seamlessly with objective caml code. It's 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 <tt>"ocamlc -I `camlp4 -where` -pp 'camlp4o pa_extend.cmo q_MLast.cmo' -c swigp4.ml"</tt> +</p> + <p> The basic principle of the module is to recognize certain non-caml expressions and convert them for use with C++ code as interfaced by SWIG. The camlp4 module is written to work with generated SWIG interfaces, and probably isn't great to use with anything else. +</p> + <p> Here are the main rewriting rules: -<p> -<table border="1"> +</p> + +<table border="1" summary="Rewriting rules"> <tr><th>Input</th><th>Rewritten to</th></tr> <tr><td>f'( ... ) as in<br> atoi'("0") or<br> _exit'(0)</td> <td>f(C_list [ ... ]) as in<br> atoi (C_list [ C_string "0" ]) or<br> _exit (C_list [ C_int 0 ])</td></tr> -<tr><td>object -> method ( ... )</td><td>(invoke object) "method" (C_list [ ... ])</td></tr> +<tr><td>object -> method ( ... )</td><td>(invoke object) "method" (C_list [ ... ])</td></tr> <tr><td> object <i>'binop</i> argument as in<br> a '+= b</td> @@ -178,9 +190,9 @@ and >>, they are replaced by lsl and lsr in operator names. (invoke a) "!" C_void</td></tr> <tr><td> <b>Smart pointer access like this</b><br> -object '-> method ( args )<br> +object '-> method ( args )<br> </td><td> -(invoke (invoke object "->" C_void)) +(invoke (invoke object "->" C_void)) </td></tr> <tr><td> <b>Invoke syntax</b><br> @@ -211,37 +223,47 @@ let b = C_string (getenv "PATH") </td></tr> </table> -<a name="n6"></a><H3>19.1.4 Using your module</H3> +<H3><a name="Ocaml_nn6"></a>21.1.4 Using your module</H3> - You can test-drive your module by building a +<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 +<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. +</p> -<a name="n7"></a><H3>19.1.5 Compilation problems and compiling with C++</H3> +<H3><a name="Ocaml_nn7"></a>21.1.5 Compilation problems and compiling with C++</H3> - As mentioned above, .cxx files need special +<p> +As mentioned above, .cxx files need special handling to be compiled with <tt>ocamlc</tt>. Other than that, C code that uses <tt>class</tt> as a non-keyword, and C code that is too liberal with pointer types may not compile under the C++ compiler. Most code meant to be compiled as C++ will not have problems. +</p> -<a name="n8"></a><H2>19.2 The low-level Ocaml/C interface</H2> +<H2><a name="Ocaml_nn8"></a>21.2 The low-level Ocaml/C interface</H2> - In order to provide access to overloaded functions, and +<p> +In order to provide access to overloaded functions, and provide sensible outputs from them, all C entites are represented as members of the c_obj type: +</p> + <p> 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> +</p> <blockquote><pre> type c_obj = @@ -284,11 +306,15 @@ appropriate C value and returns a c_obj representing it.</li> a C_obj, which contains a closure giving method access.</li> </ul> - Because of this style, a typemap can return any kind of value it + +<p> +Because of this style, a typemap can return any kind of value it 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> +is that you must append them to the return list with swig_result = caml_list_append(swig_result,v). +</p> +<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 @@ -302,13 +328,15 @@ is that you must append them to the return list with swig_result = caml_list_a 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> + 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. When evaluated in caml_ptr_val, the returned value is - the result of a call to the object's "&" operator, taken as a pointer. + the result of a call to the object's "&" 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 @@ -316,20 +344,24 @@ is that you must append them to the return list with swig_result = caml_list_a 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> -<a name="n9"></a><H3>19.2.1 The generated module</H3> +<H3><a name="Ocaml_nn9"></a>21.2.1 The generated module</H3> +<p> The SWIG <tt>%module</tt> directive specifies the name of the Ocaml module to be generated. If you specified `<tt>%module example</tt>', then your Ocaml code will be accessible in the module Example. The module name is always capitalized as is the ocaml convention. Note that you must not use any Ocaml keyword to name your module. Remember -that the keywords are not the same as the C++ ones. <p> +that the keywords are not the same as the C++ ones. +</p> +<p> You can introduce extra code into the output wherever you like with SWIG. These are the places you can introduce code: -<table border="1"> +<table border="1" summary="Extra code sections"> <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 @@ -345,11 +377,13 @@ which should run when the module is loaded may be inserted here. </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> -<a name="n10"></a><H3>19.2.2 Enums</H3> +<H3><a name="Ocaml_nn10"></a>21.2.2 Enums</H3> +<p> SWIG will wrap enumerations as polymorphic variants in the output 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 @@ -358,7 +392,8 @@ 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> +</p> + <blockquote><pre> %module enum_test %{ @@ -366,9 +401,11 @@ enum c_enum_type { a = 1, b, c = 4, d = 8 }; %} enum c_enum_type { a = 1, b, c = 4, d = 8 }; </pre></blockquote> + <p> The output mli contains: -<p> +</p> + <blockquote><pre> type c_enum_type = [ `unknown @@ -387,7 +424,8 @@ val enum_to_int c_enum_type -> c_obj -> c_obj </blockquote> So it's possible to do this: <blockquote> - <pre>bash-2.05a$ ocamlmktop -custom enum_test_wrap.o enum_test.cmo -o enum_test_top + <pre> +bash-2.05a$ ocamlmktop -custom enum_test_wrap.o enum_test.cmo -o enum_test_top bash-2.05a$ ./enum_test_top Objective Caml version 3.04 @@ -401,12 +439,10 @@ val x : Enum_test.c_obj = C_enum `a </pre> </blockquote> -<p> </p> - -<a name="n11"></a><H3>19.2.3 Arrays</H3> +<H3><a name="Ocaml_nn11"></a>21.2.3 Arrays</H3> -<a name="n12"></a><H4>19.2.3.1 Simple types of bounded arrays</H4> +<H4><a name="Ocaml_nn12"></a>21.2.3.1 Simple types of bounded arrays</H4> <p> @@ -414,6 +450,7 @@ SWIG has support for array types, but you generally will need to provide a typemap to handle them. You can currently roll your own, or expand some of the macros provided (but not included by default) with the SWIG distribution. +</p> <p> By including "carray.i", you will get access to some macros that help you @@ -426,7 +463,7 @@ arrays of simple types with known bounds in your code, but this only works for arrays whose bounds are completely specified. </p> -<a name="n13"></a><H4>19.2.3.2 Complex and unbounded arrays</H4> +<H4><a name="Ocaml_nn13"></a>21.2.3.2 Complex and unbounded arrays</H4> <p> @@ -439,7 +476,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> -<a name="n14"></a><H4>19.2.3.3 Using an object</H4> +<H4><a name="Ocaml_nn14"></a>21.2.3.3 Using an object</H4> <p> @@ -453,7 +490,7 @@ Consider writing an object when the ending condition of your array is complex, such as using a required centinel, etc. </p> -<a name="n15"></a><H4>19.2.3.4 Example typemap for a function taking float * and int</H4> +<H4><a name="Ocaml_nn15"></a>21.2.3.4 Example typemap for a function taking float * and int</H4> <p> @@ -465,11 +502,12 @@ argument is the length of the array passed from ocaml, making passing an array into this type of function convenient. </p> -<table border="1" bgcolor="#dddddd"><tr><th><center>tarray.i</center></th></tr> +<table border="1" bgcolor="#dddddd" summary="float * and int typemap example"> +<tr><th><center>tarray.i</center></th></tr> <tr><td><pre> %module tarray %{ -#include <stdio.h> +#include <stdio.h> void printfloats( float *tab, int len ) { int i; @@ -503,7 +541,7 @@ void printfloats( float *tab, int len ); </pre></td></tr></table> -<a name="n16"></a><H3>19.2.4 C++ Classes</H3> +<H3><a name="Ocaml_nn16"></a>21.2.4 C++ Classes</H3> C++ classes, along with structs and unions are represented by C_obj @@ -515,7 +553,8 @@ an object has is represented as a string in the object's method table, 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)) -<table> + +<table summary="SWIG provided operators"> <tr><td>"~"</td><td>Delete this object</td></tr> <tr><td>"&"</td><td>Return an ordinary C_ptr value representing this object's address</td></tr> @@ -539,9 +578,8 @@ argument. With zero arguments, the value is returned. Note that this string belongs to the wrapper object, and not the underlying pointer, so using create_[x]_from_ptr alters the returned value for the same object. -<p> -<a name="n17"></a><H4>19.2.4.1 STL vector and string Example</H4> +<H4><a name="Ocaml_nn17"></a>21.2.4.1 STL vector and string Example</H4> Standard typemaps are now provided for STL vector and string. More are in @@ -550,7 +588,8 @@ as strings. STL string references don't mutate the original string, (which might be surprising), because Ocaml strings are mutable but have fixed length. Instead, use multiple returns, as in the argout_ref example. -<table border="1" bgcolor="#dddddd"><tr><th><center>example.i</center></th></tr> +<table border="1" bgcolor="#dddddd" summary="STL vector and string example"> +<tr><th><center>example.i</center></th></tr> <tr><td><pre> %module example %{ @@ -567,12 +606,17 @@ namespace std { </pre></td></tr> <tr><td><font size="-1"><i>This example is in Examples/ocaml/stl </i></font></td></tr> -</table><p> +</table> + +<p> +Since there's a makefile in that directory, the example is easy to build. +</p> -Since there's a makefile in that directory, the example is easy to build.<p> +<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 module. +</p> <blockquote><pre> bash-2.05a$ ./example_top @@ -583,27 +627,27 @@ bash-2.05a$ ./example_top # open Swig ;; # open Example ;; # let x = new_StringVector '() ;; -val x : Example.c_obj = C_obj <fun> -# x -> ":methods" () ;; +val x : Example.c_obj = C_obj <fun> +# x -> ":methods" () ;; - : Example.c_obj = C_list [C_string "nop"; C_string "size"; C_string "empty"; C_string "clear"; C_string "push_back"; C_string "[]"; C_string "="; C_string "set"; - C_string "~"; C_string "&"; C_string ":parents"; C_string ":classof"; + C_string "~"; C_string "&"; C_string ":parents"; C_string ":classof"; C_string ":methods"] -# x -> push_back ("foo") ;; +# x -> push_back ("foo") ;; - : Example.c_obj = C_void -# x -> push_back ("bar") ;; +# x -> push_back ("bar") ;; - : Example.c_obj = C_void -# x -> push_back ("baz") ;; +# x -> push_back ("baz") ;; - : Example.c_obj = C_void # x '[1] ;; - : Example.c_obj = C_string "bar" -# x -> set (1,"spam") ;; +# x -> set (1,"spam") ;; - : Example.c_obj = C_void # x '[1] ;; - : Example.c_obj = C_string "spam" -# for i = 0 to (x -> size() as int) - 1 do +# for i = 0 to (x -> size() as int) - 1 do print_endline ((x '[i to int]) as string) done ;; foo @@ -613,12 +657,13 @@ baz # </pre></blockquote> -<a name="n18"></a><H4>19.2.4.2 C++ Class Example</H4> +<H4><a name="Ocaml_nn18"></a>21.2.4.2 C++ Class Example</H4> Here's a simple example using Trolltech's Qt Library: -<table border="1" bgcolor="#dddddd"><tr><th><center>qt.i</center></th></tr> +<table border="1" bgcolor="#dddddd" summary="Qt Library example"> + <tr><th><center>qt.i</center></th></tr> <tr><td><pre> %module qt %{ @@ -638,9 +683,9 @@ public: void resize( int x, int y ); void show(); }; -</pre></td></tr></table><p> +</pre></td></tr></table> -<a name="n19"></a><H4>19.2.4.3 Compiling the example</H4> +<H4><a name="Ocaml_nn19"></a>21.2.4.3 Compiling the example</H4> <blockquote><pre> @@ -658,7 +703,7 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \ -L$QTPATH/lib -cclib -lqt </pre></blockquote> -<a name="n20"></a><H4>19.2.4.4 Sample Session</H4> +<H4><a name="Ocaml_nn20"></a>21.2.4.4 Sample Session</H4> <blockquote><pre> @@ -670,33 +715,40 @@ bash-2.05a$ ./qt_top # open Swig ;; # open Qt ;; # let a = new_QApplication '(0,0) ;; -val a : Qt.c_obj = C_obj <fun> +val a : Qt.c_obj = C_obj <fun> # let hello = new_QPushButton '("hi",0) ;; -val hello : Qt.c_obj = C_obj <fun> -# hello -> resize (100,30) ;; +val hello : Qt.c_obj = C_obj <fun> +# hello -> resize (100,30) ;; - : Qt.c_obj = C_void -# hello -> show () ;; +# hello -> show () ;; - : Qt.c_obj = C_void -# a -> exec () ;; -</pre></blockquote><p> +# a -> exec () ;; +</pre></blockquote> +<p> Assuming you have a working installation of QT, you will see a window containing the string "hi" in a button. +</p> -<a name="n21"></a><H3>19.2.5 Director Classes</H3> +<H3><a name="Ocaml_nn21"></a>21.2.5 Director Classes</H3> -<a name="n22"></a><H4>19.2.5.1 Director Introduction</H4> +<H4><a name="Ocaml_nn22"></a>21.2.5.1 Director Introduction</H4> +<p> Director classes are classes which allow Ocaml code to override the public methods of a C++ object. This facility allows the user to use C++ libraries that require a derived class to provide application specific functionality in the context of an application or utility framework. +</p> + <p> You can turn on director classes by using an optional module argument like this: -<pre><blockquote><p> +</p> + +<blockquote><pre> %module(directors="1") ... @@ -706,9 +758,9 @@ this: class foo { ... }; -</p></blockquote></pre> +</pre></blockquote> -<a name="n23"></a><H4>19.2.5.2 Overriding Methods in Ocaml</H4> +<H4><a name="Ocaml_nn23"></a>21.2.5.2 Overriding Methods in Ocaml</H4> <p> @@ -721,21 +773,26 @@ underlying implemenation. The object you receive is the underlying object, so you are free to call any methods you want from within your derived method. Note that calls to the underlying object do not invoke Ocaml code. You need to handle that yourself. +</p> + <p> <tt>new_derived_object</tt> receives your function, the function that creates the underlying object, and any constructor arguments, and provides an object that you can use in any usual way. When C++ code calls one of the object's methods, the object invokes the Ocaml function as if it had been invoked from Ocaml, allowing any method definitions to override the C++ ones. +</p> + <p> 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> +</p> -<a name="n24"></a><H4>19.2.5.3 Director Usage Example</H4> +<H4><a name="Ocaml_nn24"></a>21.2.5.3 Director Usage Example</H4> -<table border="1" bgcolor="#dddddd"><tr><th><center>example_prog.ml</center> +<table border="1" bgcolor="#dddddd" summary="Director usage example"> +<tr><th><center>example_prog.ml</center> </th></tr> <tr><td><pre> open Swig @@ -745,14 +802,14 @@ open Example let triangle_class pts ob meth args = match meth with - "cover" -> + "cover" -> (match args with - C_list [ x_arg ; y_arg ] -> + C_list [ x_arg ; y_arg ] -> let xa = x_arg as float and ya = y_arg as float in (point_in_triangle pts xa ya) to bool - | _ -> raise (Failure "cover needs two double arguments.")) - | _ -> (invoke ob) meth args ;; + | _ -> raise (Failure "cover needs two double arguments.")) + | _ -> (invoke ob) meth args ;; let triangle = new_derived_object @@ -763,6 +820,7 @@ let triangle = let _ = _draw_shape_coverage '(triangle, C_int 60, C_int 20) ;; </pre></td></tr> </table> + <p> This is the meat of what you need to do. The actual "class" definition containing the overloaded method is defined in the function triangle_class. @@ -776,27 +834,31 @@ generally be Failure, or NotObject. You must call other ocaml methods that you rely on yourself. Due to the way directors are implemented, method calls on your object from with ocaml code will always invoke C++ methods even if they are overridden in ocaml. +</p> + <p> In the example, the draw_shape_coverage function plots the indicated number -of points as either covered (<tt>x</tt>) or uncovered (<tt> </tt>) between +of points as either covered (<tt>x</tt>) or uncovered ( ) between 0 and 1 on the X and Y axes. Your shape implementation can provide any coverage map it likes, as long as it responds to the "cover" method call with a boolean return (the underlying method returns bool). This might allow a tricky shape implementation, such as a boolean combination, to be expressed in a more effortless style in ocaml, while leaving the "engine" part of the program in C++. -<p> -<a name="n25"></a><H4>19.2.5.4 Creating director objects</H4> +</p> + +<H4><a name="Ocaml_nn25"></a>21.2.5.4 Creating director objects</H4> The definition of the actual object triangle can be described this way: -<pre><blockquote><p> +<blockquote><pre> let triangle = new_derived_object new_shape (triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0))) '() -</p></blockquote></pre> +</pre></blockquote> + <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 @@ -806,6 +868,8 @@ 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. +</p> + <p> The actual object passed to the self parameter of the director object will be a C_director_core, containing a c_obj option ref and a c_obj. The @@ -819,8 +883,9 @@ after that point (the actual raise is from an inner function used by new_derived_object, and throws NotObject). This prevents a deleted C++ object from causing a core dump, as long as the object is destroyed properly. +</p> -<a name="n26"></a><H4>19.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4> +<H4><a name="Ocaml_nn26"></a>21.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4> <p> @@ -829,8 +894,9 @@ are used in place of <tt>in, out, argout</tt> typemaps, except that their direction is reversed. They provide for you to provide argout values, as 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> -<a name="n27"></a><H4>19.2.5.6 <tt>directorin</tt> typemap</H4> +</p> + +<H4><a name="Ocaml_nn27"></a>21.2.5.6 <tt>directorin</tt> typemap</H4> <p> @@ -841,7 +907,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> -<a name="n28"></a><H4>19.2.5.7 <tt>directorout</tt> typemap</H4> +<H4><a name="Ocaml_nn28"></a>21.2.5.7 <tt>directorout</tt> typemap</H4> <p> @@ -852,11 +918,11 @@ for the same type, except when there are special requirements for object ownership, etc. </p> -<a name="n29"></a><H4>19.2.5.8 <tt>directorargout</tt> typemap</H4> +<H4><a name="Ocaml_nn29"></a>21.2.5.8 <tt>directorargout</tt> typemap</H4> <p> -C++ allows function arguments which are by pointer (*) and by reference (&) +C++ allows function arguments which are by pointer (*) and by reference (&) to receive a value from the called function, as well as sending one there. Sometimes, this is the main purpose of the argument given. <tt>directorargout</tt> typemaps allow your caml code to emulate this by specifying additional return @@ -869,7 +935,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> -<a name="n30"></a><H3>19.2.6 Exceptions</H3> +<H3><a name="Ocaml_nn30"></a>21.2.6 Exceptions</H3> Catching exceptions is now supported using SWIG's %exception feature. A simple diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html index 58fe222cf..5e808d7ab 100644 --- a/Doc/Manual/Perl5.html +++ b/Doc/Manual/Perl5.html @@ -5,63 +5,64 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>20 SWIG and Perl5</H1> +<H1><a name="Perl5"></a>22 SWIG and Perl5</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Overview</a> -<li><a href="#n3">Preliminaries</a> +<li><a href="#Perl5_nn2">Overview</a> +<li><a href="#Perl5_nn3">Preliminaries</a> <ul> -<li><a href="#n4">Getting the right header files</a> -<li><a href="#n5">Compiling a dynamic module</a> -<li><a href="#n6">Building a dynamic module with MakeMaker</a> -<li><a href="#n7">Building a static version of Perl</a> -<li><a href="#n8">Using the module</a> -<li><a href="#n9">Compilation problems and compiling with C++</a> -<li><a href="#n10">Compiling for 64-bit platforms</a> +<li><a href="#Perl5_nn4">Getting the right header files</a> +<li><a href="#Perl5_nn5">Compiling a dynamic module</a> +<li><a href="#Perl5_nn6">Building a dynamic module with MakeMaker</a> +<li><a href="#Perl5_nn7">Building a static version of Perl</a> +<li><a href="#Perl5_nn8">Using the module</a> +<li><a href="#Perl5_nn9">Compilation problems and compiling with C++</a> +<li><a href="#Perl5_nn10">Compiling for 64-bit platforms</a> </ul> -<li><a href="#n11">Building Perl Extensions under Windows</a> +<li><a href="#Perl5_nn11">Building Perl Extensions under Windows</a> <ul> -<li><a href="#n12">Running SWIG from Developer Studio</a> -<li><a href="#n13">Using other compilers</a> +<li><a href="#Perl5_nn12">Running SWIG from Developer Studio</a> +<li><a href="#Perl5_nn13">Using other compilers</a> </ul> -<li><a href="#n14">The low-level interface</a> +<li><a href="#Perl5_nn14">The low-level interface</a> <ul> -<li><a href="#n15">Functions</a> -<li><a href="#n16">Global variables</a> -<li><a href="#n17">Constants</a> -<li><a href="#n18">Pointers</a> -<li><a href="#n19">Structures</a> -<li><a href="#n20">C++ classes</a> -<li><a href="#n21">C++ classes and type-checking</a> -<li><a href="#n22">C++ overloaded functions</a> -<li><a href="#n23">Operators</a> -<li><a href="#n24">Modules and packages</a> +<li><a href="#Perl5_nn15">Functions</a> +<li><a href="#Perl5_nn16">Global variables</a> +<li><a href="#Perl5_nn17">Constants</a> +<li><a href="#Perl5_nn18">Pointers</a> +<li><a href="#Perl5_nn19">Structures</a> +<li><a href="#Perl5_nn20">C++ classes</a> +<li><a href="#Perl5_nn21">C++ classes and type-checking</a> +<li><a href="#Perl5_nn22">C++ overloaded functions</a> +<li><a href="#Perl5_nn23">Operators</a> +<li><a href="#Perl5_nn24">Modules and packages</a> </ul> -<li><a href="#n25">Input and output parameters</a> -<li><a href="#n26">Exception handling </a> -<li><a href="#n27">Remapping datatypes with typemaps</a> +<li><a href="#Perl5_nn25">Input and output parameters</a> +<li><a href="#Perl5_nn26">Exception handling </a> +<li><a href="#Perl5_nn27">Remapping datatypes with typemaps</a> <ul> -<li><a href="#n28">A simple typemap example</a> -<li><a href="#n29">Perl5 typemaps</a> -<li><a href="#n30">Typemap variables</a> -<li><a href="#n31">Useful functions</a> +<li><a href="#Perl5_nn28">A simple typemap example</a> +<li><a href="#Perl5_nn29">Perl5 typemaps</a> +<li><a href="#Perl5_nn30">Typemap variables</a> +<li><a href="#Perl5_nn31">Useful functions</a> </ul> -<li><a href="#n32">Typemap Examples</a> +<li><a href="#Perl5_nn32">Typemap Examples</a> <ul> -<li><a href="#n33">Converting a Perl5 array to a char ** </a> -<li><a href="#n34">Return values </a> -<li><a href="#n35">Returning values from arguments</a> -<li><a href="#n36">Accessing array structure members</a> -<li><a href="#n37">Turning Perl references into C pointers</a> -<li><a href="#n38">Pointer handling</a> +<li><a href="#Perl5_nn33">Converting a Perl5 array to a char ** </a> +<li><a href="#Perl5_nn34">Return values </a> +<li><a href="#Perl5_nn35">Returning values from arguments</a> +<li><a href="#Perl5_nn36">Accessing array structure members</a> +<li><a href="#Perl5_nn37">Turning Perl references into C pointers</a> +<li><a href="#Perl5_nn38">Pointer handling</a> </ul> -<li><a href="#n39">Proxy classes</a> +<li><a href="#Perl5_nn39">Proxy classes</a> <ul> -<li><a href="#n40">Preliminaries</a> -<li><a href="#n41">Object Ownership</a> -<li><a href="#n42">Nested Objects</a> -<li><a href="#n43">Shadow Functions</a> -<li><a href="#n44">Inheritance</a> +<li><a href="#Perl5_nn40">Preliminaries</a> +<li><a href="#Perl5_nn41">Structure and class wrappers</a> +<li><a href="#Perl5_nn42">Object Ownership</a> +<li><a href="#Perl5_nn43">Nested Objects</a> +<li><a href="#Perl5_nn44">Shadow Functions</a> +<li><a href="#Perl5_nn45">Inheritance</a> </ul> </ul> <!-- INDEX --> @@ -76,9 +77,10 @@ module is one of the earliest SWIG modules, it has continued to evolve and has been improved greatly with the help of SWIG users. For the best results, it is recommended that SWIG be used with Perl5.003 or later. Earlier versions are problematic and SWIG generated extensions -may not compile or run correctly.<p> +may not compile or run correctly. +</p> -<a name="n2"></a><H2>20.1 Overview</H2> +<H2><a name="Perl5_nn2"></a>22.1 Overview</H2> To build Perl extension modules, SWIG uses a layered approach. At @@ -95,12 +97,15 @@ and installing Perl modules is discussed. Next, the low-level procedural interface is presented. Finally, proxy classes are described. Advanced customization features, typemaps, and other options are found near the end of the chapter. +</p> -<a name="n3"></a><H2>20.2 Preliminaries</H2> +<H2><a name="Perl5_nn3"></a>22.2 Preliminaries</H2> +<p> To build a Perl5 module, run Swig using the <tt>-perl</tt> option as -follows :<p> +follows : +</p> <blockquote><pre> swig -perl example.i @@ -115,11 +120,13 @@ properly load the module. <p> To build the module, you will need to compile the file <tt>example_wrap.c</tt> and link it with the rest of your program. +</p> -<a name="n4"></a><H3>20.2.1 Getting the right header files</H3> +<H3><a name="Perl5_nn4"></a>22.2.1 Getting the right header files</H3> -In order to compile, SWIG extensions need the following Perl5 header files :<p> +<p> +In order to compile, SWIG extensions need the following Perl5 header files :</p> <blockquote><pre> #include "Extern.h" @@ -128,15 +135,17 @@ In order to compile, SWIG extensions need the following Perl5 header files :<p> </pre></blockquote> <p> -These are typically located in a directory like this<p> +These are typically located in a directory like this</p> -<p> -<blockquote><pre>/usr/lib/perl5/5.00503/i386-linux/CORE +<blockquote><pre> +/usr/lib/perl5/5.00503/i386-linux/CORE </pre></blockquote> + <p> The SWIG configuration script automatically tries to locate this directory so that it can compile examples. However, if you need to find out where the directory is loaded, an easy way to find out is to run Perl itself. +</p> <blockquote> <pre> @@ -145,14 +154,15 @@ loaded, an easy way to find out is to run Perl itself. </pre> </blockquote> -<a name="n5"></a><H3>20.2.2 Compiling a dynamic module</H3> +<H3><a name="Perl5_nn5"></a>22.2.2 Compiling a dynamic module</H3> 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 using comands like this (shown for Linux): -<blockquote><pre>$ swig -perl example.i +<blockquote><pre> +$ swig -perl example.i % gcc example.c % gcc -c example_wrap.c -I/usr/lib/perl5/5.00503/i386-linux/CORE -Dbool=char % gcc -shared example.o example_wrap.o -o example.so @@ -171,16 +181,18 @@ When linking the module, the name of the shared object file must match the modul the SWIG interface file. If you used `<tt>%module example</tt>', then the target should be named `<tt>example.so</tt>', `<tt>example.sl</tt>', or the appropriate dynamic module name on your system. +</p> -<a name="n6"></a><H3>20.2.3 Building a dynamic module with MakeMaker</H3> +<H3><a name="Perl5_nn6"></a>22.2.3 Building a dynamic module with MakeMaker</H3> +<p> It is also possible to use Perl to build dynamically loadable modules for you using the MakeMaker utility. To do this, write a Perl -script such as the following :<p> +script such as the following :</p> -<p> -<blockquote><pre># File : Makefile.PL +<blockquote><pre> +# File : Makefile.PL use ExtUtils::MakeMaker; WriteMakefile( `NAME' => `example', # Name of package @@ -190,10 +202,11 @@ WriteMakefile( </pre></blockquote> -Now, to build a module, simply follow these steps :<p> - <p> -<blockquote><pre>% perl Makefile.PL +Now, to build a module, simply follow these steps :</p> + +<blockquote><pre> +% perl Makefile.PL % make % make install </pre></blockquote> @@ -202,28 +215,30 @@ Now, to build a module, simply follow these steps :<p> If you are planning to distribute a SWIG-generated module, this is the preferred approach to compilation. More information about MakeMaker can be found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen, -and Randal Schwartz.<p> +and Randal Schwartz.</p> -<a name="n7"></a><H3>20.2.4 Building a static version of Perl</H3> +<H3><a name="Perl5_nn7"></a>22.2.4 Building a static version of Perl</H3> +<p> If you machine does not support dynamic loading or if you've tried to use it without success, you can build a new version of the Perl interpreter with your SWIG extensions added to it. To build a static -extension, you first need to invoke SWIG as follows :<p> +extension, you first need to invoke SWIG as follows :</p> -<p> -<blockquote><pre>% swig -perl -static example.i +<blockquote><pre> +% swig -perl -static example.i </pre></blockquote> + <p> By default SWIG includes code for dynamic loading, but the -<tt>-static</tt> option takes it out.<p> +<tt>-static</tt> option takes it out.</p> <p> Next, you will need to supply a <tt>main()</tt> function that initializes your extension and starts the Perl interpreter. While, this may sound daunting, SWIG can do this for you automatically as -follows :<p> +follows :</p> <blockquote><pre> %module example @@ -236,13 +251,13 @@ extern int fact(int); </pre></blockquote> <p> -The same thing can be accomplished by running SWIG as follows :<p> - -<p> -<blockquote><pre>% swig -perl -static -lperlmain.i example.i +The same thing can be accomplished by running SWIG as follows :</p> +<blockquote><pre> +% swig -perl -static -lperlmain.i example.i </pre></blockquote> +<p> The <tt>permain.i</tt> file inserts Perl's <tt>main()</tt> function into the wrapper code and automatically initializes the SWIG generated module. If you just want to make a quick a dirty module, this may be @@ -250,11 +265,12 @@ the easiest way. By default, the <tt>perlmain.i</tt> code does not initialize any other Perl extensions. If you need to use other packages, you will need to modify it appropriately. You can do this by just copying <tt>perlmain.i</tt> out of the SWIG library, placing it -in your own directory, and modifying it to suit your purposes.<p> +in your own directory, and modifying it to suit your purposes.</p> <p> To build your new Perl executable, follow the exact same procedure as for a dynamic module, but change the link line to something like this: +</p> <blockquote><pre> % gcc example.o example_wrap.o -L/usr/lib/perl5/5.00503/i386-linux/CORE \ @@ -266,15 +282,18 @@ This will produce a new version of Perl called <tt>myperl</tt>. It should be functionality identical to Perl with your C/C++ extension added to it. Depending on your machine, you may need to link with additional libraries such as <tt>-lsocket, -lnsl, -ldl</tt>, etc. +</p> -<a name="n8"></a><H3>20.2.5 Using the module</H3> +<H3><a name="Perl5_nn8"></a>22.2.5 Using the module</H3> +<p> To use the module, simply use the Perl <tt>use</tt> statement. If all goes well, you will be able to do this: +</p> -<p> -<blockquote><pre>$ perl +<blockquote><pre> +$ perl use example; print example::fact(4),"\n"; 24 @@ -297,6 +316,7 @@ you specified with the <tt>%module</tt> directive. <p> A somewhat related, but slightly different error is this: +</p> <blockquote> <pre> @@ -314,6 +334,7 @@ of your application when you linked the extension module. <p> Another common error is the following: +</p> <blockquote> <pre> @@ -341,9 +362,11 @@ without updating the header file. To fix this, you can either edit the SWIG input file to remove the offending declaration or you can use the <tt>%ignore</tt> directive to ignore the declaration. Better yet, update the header file so that it doesn't have an undefined declaration. +</p> <p> Finally, suppose that your extension module is linked with another library like this: +</p> <blockquote> <pre> @@ -363,7 +386,7 @@ No such file or directory at /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm lin at - line 1 BEGIN failed--compilation aborted at - line 1. ->>> +>>> </pre> </blockquote> @@ -400,7 +423,7 @@ Finally, you can use a command such as <tt>ldconfig</tt> (Linux) or system configuration (this requires root access and you will need to read the man pages). -<a name="n9"></a><H3>20.2.6 Compilation problems and compiling with C++</H3> +<H3><a name="Perl5_nn9"></a>22.2.6 Compilation problems and compiling with C++</H3> Compilation of C++ extensions has traditionally been a tricky problem. @@ -411,20 +434,23 @@ correctly. <p> On most machines, C++ extension modules should be linked using the C++ compiler. For example: +</p> -<p> -<blockquote><pre>% swig -c++ -perl example.i +<blockquote><pre> +% swig -c++ -perl example.i % g++ -c example.cxx % g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE % <b>g++ -shared example.o example_wrap.o -o example.so</b> </pre></blockquote> +<p> In addition to this, you may need to include additional library files to make it work. For example, if you are using the Sun C++ compiler on Solaris, you often need to add an extra library <tt>-lCrun</tt> like this: +</p> -<p> -<blockquote><pre>% swig -c++ -perl example.i +<blockquote><pre> +% swig -c++ -perl example.i % g++ -c example.cxx % g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE % g++ -shared example.o example_wrap.o -o example.so <b>-lCrun</b> @@ -437,6 +463,7 @@ probably need to do some experimentation. Another possible compile problem comes from recent versions of Perl (5.8.0) and the GNU tools. If you see errors having to do with _crypt_struct, that means _GNU_SOURCE is not defined and it needs to be. So you should compile the wrapper like: +</p> <blockquote><pre> % g++ -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE -D_GNU_SOURCE @@ -459,6 +486,7 @@ In the experience of this author, this has never actually appeared to be necessary on most platforms. Relinking the interpreter with C++ really only includes the special run-time libraries described above---as long as you link your extension modules with these libraries, it should not be necessary to rebuild Perl. +</p> <p> If you aren't entirely sure about the linking of a C++ extension, you @@ -466,14 +494,15 @@ might look at an existing C++ program. On many Unix machines, the <tt>ldd</tt> command will list library dependencies. This should give you some clues about what you might have to include when you link your extension module. For example, notice the first line of output here: +</p> <blockquote> <pre> $ ldd swig - <b>libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)</b> - libm.so.6 => /lib/libm.so.6 (0x4005b000) - libc.so.6 => /lib/libc.so.6 (0x40077000) - /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) + <b>libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)</b> + libm.so.6 => /lib/libm.so.6 (0x4005b000) + libc.so.6 => /lib/libc.so.6 (0x40077000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) $ </pre> </blockquote> @@ -491,13 +520,13 @@ this probably won't matter. However, if these modules start sharing data, you will need to take steps to avoid segmentation faults and other erratic program behavior. Also, be aware that certain C++ features, especially RTTI, can behave strangely when working with multiple modules. +</p> <p> It should be noted that you may get alot of error messages about the `<tt>bool</tt>' datatype when compiling a C++ Perl module. If -you experience this problem, you can try the following :<p> +you experience this problem, you can try the following :</p> -<p> <ul> <li>Use <tt>-DHAS_BOOL</tt> when compiling the SWIG wrapper code <li>Or use <tt>-Dbool=char</tt> when compiling. @@ -507,6 +536,7 @@ you experience this problem, you can try the following :<p> Finally, recent versions of Perl (5.8.0) have namespace conflict problems. Perl defines a bunch of short macros to make the Perl API function names shorter. For example, in /usr/lib/perl/5.8.0/CORE/embed.h there is a line: +</p> <blockquote><pre> #define do_open Perl_do_open @@ -523,7 +553,7 @@ in Lib/perl5/noembed.h while compiling the wrapper, you will have to find the macro that conflicts and add an #undef into the .i file. Please report any conflicting macros you find to <a href="mailto:swig@cs.uchicago.edu">swig@cs.uchicago.edu</a>. -<a name="n10"></a><H3>20.2.7 Compiling for 64-bit platforms</H3> +<H3><a name="Perl5_nn10"></a>22.2.7 Compiling for 64-bit platforms</H3> On platforms that support 64-bit applications (Solaris, Irix, etc.), @@ -538,6 +568,7 @@ as a 64-bit application. In addition, all libraries, wrapper code, and every other part of your application will need to be compiled for 64-bits. If you plan to use other third-party extension modules, they will also have to be recompiled as 64-bit extensions. +</p> <p> If you are wrapping commercial software for which you have no source @@ -545,8 +576,9 @@ code, you will be forced to use the same linking standard as used by that software. This may prevent the use of 64-bit extensions. It may also introduce problems on platforms that support more than one linking standard (e.g., -o32 and -n32 on Irix). +</p> -<a name="n11"></a><H2>20.3 Building Perl Extensions under Windows</H2> +<H2><a name="Perl5_nn11"></a>22.3 Building Perl Extensions under Windows</H2> Building a SWIG extension to Perl under Windows is roughly @@ -555,14 +587,14 @@ produce a DLL that can be loaded into the Perl interpreter. This section assumes you are using SWIG with Microsoft Visual C++ although the procedure may be similar with other compilers. -<a name="n12"></a><H3>20.3.1 Running SWIG from Developer Studio</H3> +<H3><a name="Perl5_nn12"></a>22.3.1 Running SWIG from Developer Studio</H3> +<p> If you are developing your application within Microsoft developer studio, SWIG can be invoked as a custom build option. The process -roughly requires these steps :<p> +roughly requires these steps :</p> -<p> <ul> <li>Open up a new workspace and use the AppWizard to select a DLL project. @@ -601,13 +633,15 @@ match the name of your Perl module (ie. example.dll). <li>Build your project. </ul> + <p> Now, assuming you made it this far, SWIG will be automatically invoked when you build your project. Any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file. To run your new Perl extension, simply run Perl and -use the use command as normal. For example :<p> -<p> +use the use command as normal. For example : +</p> + <blockquote><pre> DOS > perl use example; @@ -616,13 +650,13 @@ print "$a\n"; </pre></blockquote> -<a name="n13"></a><H3>20.3.2 Using other compilers</H3> +<H3><a name="Perl5_nn13"></a>22.3.2 Using other compilers</H3> SWIG is known to work with Cygwin and may work with other compilers on Windows. -For general hints and suggestions refer to the <a href="Windows.html">Windows</a> chapter. +For general hints and suggestions refer to the <a href="Windows.html#Windows">Windows</a> chapter. -<a name="n14"></a><H2>20.4 The low-level interface</H2> +<H2><a name="Perl5_nn14"></a>22.4 The low-level interface</H2> At its core, the Perl module uses a simple low-level interface @@ -630,43 +664,50 @@ to C function, variables, constants, and classes. This low-level interface can be used to control your application. However, it is also used to construct more user-friendly proxy classes as described in the next section. -<a name="n15"></a><H3>20.4.1 Functions</H3> +<H3><a name="Perl5_nn15"></a>22.4.1 Functions</H3> +<p> C functions are converted into new Perl built-in commands (or subroutines). For example: +</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example int fact(int a); ... - </pre></blockquote> -Now, in Perl: + <p> -<blockquote><pre>use example; +Now, in Perl: +</p> + +<blockquote><pre> +use example; $a = &example::fact(2); </pre></blockquote> -<a name="n16"></a><H3>20.4.2 Global variables</H3> +<H3><a name="Perl5_nn16"></a>22.4.2 Global variables</H3> +<p> Global variables are handled using Perl's magic variable mechanism. SWIG generates a pair of functions that intercept read/write operations and attaches them to a Perl variable with -the same name as the C global variable. Thus, an interface like this <p> +the same name as the C global variable. Thus, an interface like this </p> -<p> -<blockquote><pre>%module example; +<blockquote><pre> +%module example; ... double Spam; ... - </pre></blockquote> -is accessed as follows :<p> <p> -<blockquote><pre>use example; +is accessed as follows :</p> + +<blockquote><pre> +use example; print $example::Spam,"\n"; $example::Spam = $example::Spam + 4 # ... etc ... @@ -677,9 +718,11 @@ $example::Spam = $example::Spam + 4 If a variable is declared as <tt>const</tt>, it is wrapped as a read-only variable. Attempts to modify its value will result in an error. +</p> <p> To make ordinary variables read-only, you can also use the <tt>%immutable</tt> directive. For example: +</p> <blockquote> <pre> @@ -701,7 +744,7 @@ extern char *path; // Declared later in the input </pre> </blockquote> -<a name="n17"></a><H3>20.4.3 Constants</H3> +<H3><a name="Perl5_nn17"></a>22.4.3 Constants</H3> Constants are wrapped as read-only Perl variables. For example: @@ -724,20 +767,22 @@ $example::FOO = 2; # Error </pre> </blockquote> -<a name="n18"></a><H3>20.4.4 Pointers</H3> +<H3><a name="Perl5_nn18"></a>22.4.4 Pointers</H3> +<p> SWIG represents pointers as blessed references. A blessed reference is the same as a Perl reference except that it has additional information attached to it indicating what kind of reference it -is. That is, if you have a C declaration like this :<p> +is. That is, if you have a C declaration like this :</p> -<p> -<blockquote><pre>Matrix *new_Matrix(int n, int m); +<blockquote><pre> +Matrix *new_Matrix(int n, int m); </pre></blockquote> <p> The module returns a value generated as follows: +</p> <blockquote><pre> $ptr = new_Matrix(int n, int m); # Save pointer return result @@ -747,11 +792,11 @@ bless $ptr, "p_Matrix"; # Bless it as a pointer to Matrix <p> SWIG uses the "blessing" to check the datatype of various pointers. In the event of a mismatch, an error or warning message is -generated.<p> +generated.</p> <p> To check to see if a value is the NULL pointer, use the -<tt>defined()</tt> command :<p> +<tt>defined()</tt> command :</p> <blockquote><pre> if (defined($ptr)) { @@ -762,8 +807,10 @@ if (defined($ptr)) { </pre></blockquote> +<p> To create a NULL pointer, you should pass the <tt>undef </tt>value to -a function. <p> +a function. +</p> <p> The "value" of a Perl reference is not the same as the underlying C @@ -773,10 +820,11 @@ In general, <tt>$a</tt> and <tt>$b</tt> will be different--since they are different references. Thus, it is a mistake to check the equality of <tt>$a </tt>and <tt>$b</tt> to check the equality of two C pointers. The correct method to check equality of C pointers is to -dereference them as follows :<p> +dereference them as follows : +</p> -<p> -<blockquote><pre>if ($$a == $$b) { +<blockquote><pre> +if ($$a == $$b) { print "a and b point to the same thing in C"; } else { print "a and b point to different objects."; @@ -818,28 +866,30 @@ to use the new C++ style casts. For example, in the above code, the C-style cast may return a bogus result whereas as the C++-style cast will return <tt>NULL</tt> if the conversion can't be performed. -<P> +<p> <b>Compatibility Note:</b> In earlier versions, SWIG tried to preserve the same pointer naming conventions as XS and <tt>xsubpp</tt>. Given the advancement of the SWIG typesystem and the growing differences between SWIG and XS, this is no longer supported. +</p> -<a name="n19"></a><H3>20.4.5 Structures</H3> +<H3><a name="Perl5_nn19"></a>22.4.5 Structures</H3> +<p> Access to the contents of a structure are provided through a set of low-level accessor functions as described in the "SWIG Basics" chapter. For example, -<p> +</p> -<p> -<blockquote><pre>struct Vector { +<blockquote><pre> +struct Vector { double x,y,z; }; - </pre></blockquote> +<p> gets mapped into the following collection of accessor functions: +</p> -<p> <blockquote><pre> struct Vector *new_Vector(); void delete_Vector(Vector *v); @@ -852,21 +902,24 @@ void Vector_z_set(Vector *obj, double z) </pre></blockquote> +<p> These functions are then used to access structure data from Perl as follows: +</p> -<p> <blockquote><pre> $v = example::new_Vector(); print example::Vector_x_get($v),"\n"; # Get x component example::Vector_x_set($v,7.8); # Change x component </pre></blockquote> -<p> -Similar access is provided for unions and the data members of C++ classes.<p> +<p> +Similar access is provided for unions and the data members of C++ classes. +</p> <p> <tt>const</tt> members of a structure are read-only. Data members can also be forced to be read-only using the <tt>%immutable</tt> directive. For example: +</p> <blockquote> <pre> @@ -887,9 +940,11 @@ dynamically allocated using <tt>malloc</tt> or <tt>new</tt> (depending on whethe SWIG is run with the -c++ option). When the structure member is set, the old contents will be released and a new value created. If this is not the behavior you want, you will have to use a typemap (described later). +</p> <p> Array members are normally wrapped as read-only. For example, +</p> <blockquote> <pre> @@ -904,7 +959,7 @@ produces a single accessor function like this: <blockquote> <pre> int *Foo_x_get(Foo *self) { - return self->x; + return self->x; }; </pre> </blockquote> @@ -916,6 +971,7 @@ string in the structure). <p> When structure members are wrapped, they are handled as pointers. For example, +</p> <blockquote> <pre> @@ -934,24 +990,26 @@ generates accessor functions such as this: <blockquote> <pre> Foo *Bar_f_get(Bar *b) { - return &b->f; + return &b->f; } void Bar_f_set(Bar *b, Foo *val) { - b->f = *val; + b->f = *val; } </pre> </blockquote> -<a name="n20"></a><H3>20.4.6 C++ classes</H3> +<H3><a name="Perl5_nn20"></a>22.4.6 C++ classes</H3> +<p> C++ classes are wrapped by building a set of low level accessor functions. -Consider the following class :<p> +Consider the following class : +</p> -<p> -<blockquote><pre>class List { +<blockquote><pre> +class List { public: List(); ~List(); @@ -965,10 +1023,11 @@ static void print(List *l); </pre></blockquote> <p> -When wrapped by SWIG, the following functions are created :<p> +When wrapped by SWIG, the following functions are created : +</p> -<p> -<blockquote><pre>List *new_List(); +<blockquote><pre> +List *new_List(); void delete_List(List *l); int List_search(List *l, char *item); void List_insert(List *l, char *item); @@ -1002,7 +1061,7 @@ as the first argument. Although this interface is fairly primitive, it provides direct access to C++ objects. A higher level interface using Perl proxy classes can be built using these low-level accessors. This is described shortly. -<a name="n21"></a><H3>20.4.7 C++ classes and type-checking</H3> +<H3><a name="Perl5_nn21"></a>22.4.7 C++ classes and type-checking</H3> The SWIG type-checker is fully aware of C++ inheritance. Therefore, if you have @@ -1032,7 +1091,7 @@ then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any cla If necesssary, the type-checker also adjusts the value of the pointer (as is necessary when multiple inheritance is used). -<a name="n22"></a><H3>20.4.8 C++ overloaded functions</H3> +<H3><a name="Perl5_nn22"></a>22.4.8 C++ overloaded functions</H3> If you have a C++ program with overloaded functions or methods, you will need to disambiguate @@ -1070,7 +1129,7 @@ example::Spam_foo_d($s,3.14); Please refer to the "SWIG Basics" chapter for more information. -<a name="n23"></a><H3>20.4.9 Operators</H3> +<H3><a name="Perl5_nn23"></a>22.4.9 Operators</H3> C++ operators can also be wrapped using the <tt>%rename</tt> directive. All you need to do is @@ -1078,9 +1137,9 @@ give the operator the name of a valid Perl identifier. For example: <blockquote> <pre> -%rename(add_complex) operator+(Complex &, Complex &); +%rename(add_complex) operator+(Complex &, Complex &); ... -Complex operator+(Complex &, Complex &); +Complex operator+(Complex &, Complex &); </pre> </blockquote> @@ -1097,15 +1156,17 @@ $c = example::add_complex($a,$b); Some preliminary work on mapping C++ operators into Perl operators has been completed. This is covered later. -<a name="n24"></a><H3>20.4.10 Modules and packages</H3> +<H3><a name="Perl5_nn24"></a>22.4.10 Modules and packages</H3> +<p> When you create a SWIG extension, everything gets placed into a single Perl module. The name of the module is determined by the -<tt>%module</tt> directive. To use the module, do the following :<p> +<tt>%module</tt> directive. To use the module, do the following : +</p> -<p> -<blockquote><pre>% perl5 +<blockquote><pre> +% perl5 use example; # load the example module print example::fact(4),"\n" # Call a function in it 24 @@ -1117,42 +1178,52 @@ within a single file. A package, on the other hand, is the Perl equivalent of a namespace. A package is alot like a module, except that it is independent of files. Any number of files may be part of the same package--or a package may be broken up into a collection of -modules if you prefer to think about it in this way.<p> +modules if you prefer to think about it in this way. +</p> -<p> SWIG installs its functions into a package with the same name as +<p> +SWIG installs its functions into a package with the same name as the module. </p> -<p><b>Incompatible Change:</b> previous versions of SWIG enabled you to +<p> +<b>Incompatible Change:</b> previous versions of SWIG enabled you to change the name of the package by using the -package option, this feature has been removed in order to properly support modules that used nested namespaces, e.g. Foo::Bar::Baz. To give your module a nested namespace simply provide the fully qualified name in your %module directive: </p> -<blockquote><pre>%module "Foo::Bar::Baz" +<blockquote><pre> +%module "Foo::Bar::Baz" </pre></blockquote> -<p><b>NOTE:</b> the double quotes are necessary. +<p> +<b>NOTE:</b> the double quotes are necessary. +</p> <!-- +<p> This can be changed by giving SWIG the -package -option :<p> +option : +</p> -<p> -<blockquote><pre>% swig -perl -package Foo example.i +<blockquote><pre> +% swig -perl -package Foo example.i </pre></blockquote> <p> In this case, you still create a module called `<tt>example</tt>' exactly as before, but all of the functions in that module will be installed into the package -`<tt>Foo</tt>.' For example :<p> -<p> -<blockquote><pre>use example; # Load the module like before +`<tt>Foo</tt>.' For example : +</p> + +<blockquote><pre> +use example; # Load the module like before print Foo::fact(4),"\n"; # Call a function in package FooBar </pre></blockquote> --> -<a name="n25"></a><H2>20.5 Input and output parameters</H2> +<H2><a name="Perl5_nn25"></a>22.5 Input and output parameters</H2> A common problem in some C programs is handling parameters passed as simple pointers. For @@ -1201,12 +1272,15 @@ print "$b\n"; </pre> </blockquote> +<p> Notice how the <tt>INPUT</tt> parameters allow integer values to be passed instead of pointers and how the <tt>OUTPUT</tt> parameter creates a return result. +</p> <p> If you don't want to use the names <tt>INPUT</tt> or <tt>OUTPUT</tt>, use the <tt>%apply</tt> directive. For example: +</p> <blockquote> <pre> @@ -1223,6 +1297,7 @@ int sub(int *x, int *y); <p> If a function mutates one of its parameters like this, +</p> <blockquote> <pre> @@ -1256,6 +1331,7 @@ print "$a\n"; The most common use of these special typemap rules is to handle functions that return more than one value. For example, sometimes a function returns a result as well as a special error code: +</p> <blockquote> <pre> @@ -1338,14 +1414,16 @@ print "$c\n"; <b>Note:</b> The <tt>REFERENCE</tt> feature is only currently supported for numeric types (integers and floating point). -<a name="n26"></a><H2>20.6 Exception handling </H2> +<H2><a name="Perl5_nn26"></a>22.6 Exception handling </H2> +<p> The SWIG <tt>%exception</tt> directive can be used to create a user-definable exception handler for converting exceptions in your C/C++ program into Perl exceptions. The chapter on customization features contains more details, but suppose you have a C++ class like the -following :<p> +following : +</p> <blockquote><pre> class RangeError {}; // Used for an exception @@ -1388,13 +1466,15 @@ class DoubleArray { }; </pre></blockquote> +<p> Since several methods in this class can throw an exception for an out-of-bounds access, you might want to catch this in the Perl extension by writing the following in an interface file: +</p> -<p> -<blockquote><pre>%exception { +<blockquote><pre> +%exception { try { $action } @@ -1408,16 +1488,19 @@ class DoubleArray { }; </pre></blockquote> +<p> The exception handling code is inserted directly into generated wrapper functions. The <tt>$action</tt> variable is replaced with the C/C++ code being executed by the wrapper. When an exception handler is defined, errors can be caught and used to gracefully generate a Perl error instead of forcing the entire program to terminate with an uncaught error. +</p> <p> As shown, the exception handling code will be added to every wrapper function. Since this is somewhat inefficient. You might consider refining the exception handler to only apply to specific methods like this: +</p> <blockquote> <pre> @@ -1447,6 +1530,7 @@ named <tt>getitem</tt> and <tt>setitem</tt>. <p> If you had a lot of different methods, you can avoid extra typing by using a macro. For example: +</p> <blockquote> <pre> @@ -1467,10 +1551,12 @@ For example: </blockquote> Since SWIG's exception handling is user-definable, you are not limited to C++ exception handling. -See the chapter on "<a href="Customization.html">Customization features</a>" for more examples. +See the chapter on "<a href="Customization.html#Customization">Customization features</a>" for more examples. <p> <b>Compatibility note:</b> In SWIG1.1, exceptions were defined using the older <tt>%except</tt> directive: +</p> + <blockquote> <pre> %except(python) { @@ -1487,29 +1573,34 @@ See the chapter on "<a href="Customization.html">Customization features</a>" for This is still supported, but it is deprecated. The newer <tt>%exception</tt> directive provides the same functionality, but it has additional capabilities that make it more powerful. -<a name="n27"></a><H2>20.7 Remapping datatypes with typemaps</H2> +<H2><a name="Perl5_nn27"></a>22.7 Remapping datatypes with typemaps</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 Perl C API as well -as the material in the "<a href="Typemaps.html">Typemaps</a>" chapter. +as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. +</p> <p> Before proceeding, it should be stressed that typemaps are <em>not</em> a required part of using SWIG---the default wrapping behavior is enough in most cases. Typemaps are only used if you want to change some aspect of the primitive C-Perl interface. +</p> -<a name="n28"></a><H3>20.7.1 A simple typemap example</H3> +<H3><a name="Perl5_nn28"></a>22.7.1 A simple typemap example</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 Perl to C, you might define a typemap like this: +</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example %typemap(in) int { $1 = (int) SvIV($input); @@ -1528,12 +1619,14 @@ will be applied. The supplied C code is used to convert values. In this code a number of special variable prefaced by a <tt>$</tt> are used. The <tt>$1</tt> variable is placeholder for a local variable of type <tt>int</tt>. The <tt>$input</tt> variable is the input object (usually a <tt>SV *</tt>). +</p> <p> -When this example is used in Perl5, it will operate as follows :<p> +When this example is used in Perl5, it will operate as follows : +</p> -<p> -<blockquote><pre>use example; +<blockquote><pre> +use example; $n = example::fact(6); print "$n\n"; ... @@ -1549,6 +1642,7 @@ more than simple text-matching--typemaps are fully integrated into the SWIG type-system. When you define a typemap for <tt>int</tt>, that typemap applies to <tt>int</tt> and qualified variations such as <tt>const int</tt>. In addition, the typemap system follows <tt>typedef</tt> declarations. For example: +</p> <blockquote> <pre> @@ -1567,6 +1661,7 @@ type <tt>int</tt>. <p> Typemaps can also be defined for groups of consecutive arguments. For example: +</p> <blockquote> <pre> @@ -1586,12 +1681,12 @@ parameter is ommitted): <pre> example::count("e","Hello World"); 1 ->>> +>>> </pre> </blockquote> -<a name="n29"></a><H3>20.7.2 Perl5 typemaps</H3> +<H3><a name="Perl5_nn29"></a>22.7.2 Perl5 typemaps</H3> The previous section illustrated an "in" typemap for converting Perl objects to C. @@ -1610,76 +1705,101 @@ like this: </pre> </blockquote> +<p> The following typemap methods are available: +</p> + <p> <tt>%typemap(in)</tt> +</p> + <blockquote> -Converts Perl5 object to input function arguments.<p> +Converts Perl5 object to input function arguments. </blockquote> <p> <tt>%typemap(out)</tt> +</p> + <blockquote> -Converts function return value to a Perl5 value.<p> +Converts function return value to a Perl5 value. </blockquote> <p> <tt>%typemap(varin)</tt> +</p> + <blockquote> -Converts a Perl5 object to a global variable.<p> +Converts a Perl5 object to a global variable. </blockquote> <p> <tt>%typemap(varout)</tt> +</p> + <blockquote> -Converts a global variable to a Perl5 object.<p> +Converts a global variable to a Perl5 object. </blockquote> <p> <tt>%typemap(freearg)</tt> +</p> + <blockquote> -Cleans up a function argument after a function call<p> +Cleans up a function argument after a function call </blockquote> <p> <tt>%typemap(argout)</tt> +</p> + <blockquote> -Output argument handling<p> +Output argument handling </blockquote> <p> -<tt>%typemap(ret) </tt> +<tt>%typemap(ret)</tt> +</p> + <blockquote> -Clean up return value from a function.<p> +Clean up return value from a function. </blockquote> <p> <tt>%typemap(memberin)</tt> +</p> + <blockquote> -Setting of C++ member data (all languages).<p> +Setting of C++ member data (all languages). </blockquote> <p> <tt>%typemap(memberout)</tt> +</p> + <blockquote> -Return of C++ member data (all languages).<p> +Return of C++ member data (all languages). </blockquote> <p> <tt>%typemap(check)</tt> +</p> + <blockquote> -Check value of input parameter.<p> +Check value of input parameter. </blockquote> -<a name="n30"></a><H3>20.7.3 Typemap variables</H3> +<H3><a name="Perl5_nn30"></a>22.7.3 Typemap variables</H3> Within typemap code, a number of special variables prefaced with a <tt>$</tt> may appear. -A full list of variables can be found in the "<a href="Typemaps.html">Typemaps</a>" chapter. +A full list of variables can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. This is a list of the most common variables: <p> <tt>$1</tt> +</p> + <blockquote> A C local variable corresponding to the actual type specified in the <tt>%typemap</tt> directive. For input values, this is a C local variable @@ -1689,30 +1809,40 @@ the raw result that's supposed to be returned to Perl. <p> <tt>$input</tt> +</p> + <blockquote> A Perl object holding the value of an argument of variable value. </blockquote> <p> <tt>$result</tt> +</p> + <blockquote> A Perl object that holds the result to be returned to Perl. </blockquote> -<p> +<p> <tt>$1_name</tt> +</p> + <blockquote> The parameter name that was matched. </blockquote> -<p> +<p> <tt>$1_type</tt> +</p> + <blockquote> The actual C datatype matched by the typemap. </blockquote> -<p> +<p> <tt>$1_ltype</tt> +</p> + <blockquote> An assignable version of the datatype matched by the typemap (a type that can appear on the left-hand-side of a C assignment operation). This type is stripped of qualifiers and may be an altered version of <tt>$1_type</tt>. @@ -1725,19 +1855,22 @@ properly assigned. The Perl name of the wrapper function being created. </blockquote> -<a name="n31"></a><H3>20.7.4 Useful functions</H3> +<H3><a name="Perl5_nn31"></a>22.7.4 Useful functions</H3> +<p> When writing typemaps, it is necessary to work directly with Perl5 objects. This, unfortunately, can be a daunting task. Consult the "perlguts" man-page for all of the really ugly details. A short summary of commonly used functions is provided here for reference. It should be stressed that SWIG can be usef quite effectively without knowing any of these details--especially now that there are typemap -libraries that can already been written.<p> +libraries that can already been written. +</p> <p> <b>Perl Integer Functions</b> +</p> <blockquote> <pre> @@ -1785,23 +1918,25 @@ int sv_isa(SV *, char *0; </blockquote> -<a name="n32"></a><H2>20.8 Typemap Examples</H2> +<H2><a name="Perl5_nn32"></a>22.8 Typemap Examples</H2> This section includes a few examples of typemaps. For more examples, you might look at the files "<tt>perl5.swg</tt>" and "<tt>typemaps.i</tt>" in the SWIG library. -<a name="n33"></a><H3>20.8.1 Converting a Perl5 array to a char ** </H3> +<H3><a name="Perl5_nn33"></a>22.8.1 Converting a Perl5 array to a char ** </H3> +<p> A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings. The following SWIG interface file allows a Perl5 array -reference to be used as a char ** datatype.<p> +reference to be used as a char ** datatype. +</p> -<p> -<blockquote><pre>%module argv +<blockquote><pre> +%module argv // This tells SWIG to treat char ** as a special case %typemap(in) char ** { @@ -1868,8 +2003,10 @@ char **get_args() { </pre></blockquote> +<p> When this module is compiled, the wrapped C functions can be used in a -Perl script as follows :<p> +Perl script as follows : +</p> <blockquote><pre> use argv; @@ -1880,23 +2017,26 @@ print @$b,"\n"; # Print it out </pre></blockquote> -<a name="n34"></a><H3>20.8.2 Return values </H3> +<H3><a name="Perl5_nn34"></a>22.8.2 Return values </H3> +<p> Return values are placed on the argument stack of each wrapper function. The current value of the argument stack pointer is contained in a variable <tt>argvi</tt>. Whenever a new output value is added, it is critical that this value be incremented. For multiple output values, the final value of <tt>argvi</tt> should be the total -number of output values. <p> +number of output values. +</p> <p> The total number of return values should not exceed the number of input values unless you explicitly extend the argument stack. This -can be done using the <tt>EXTEND()</tt> macro as in :<p> +can be done using the <tt>EXTEND()</tt> macro as in : +</p> -<p> -<blockquote><pre>%typemap(argout) int *OUTPUT { +<blockquote><pre> +%typemap(argout) int *OUTPUT { if (argvi >= items) { EXTEND(sp,1); /* Extend the stack by 1 object */ } @@ -1906,14 +2046,16 @@ can be done using the <tt>EXTEND()</tt> macro as in :<p> } </pre></blockquote> -<a name="n35"></a><H3>20.8.3 Returning values from arguments</H3> +<H3><a name="Perl5_nn35"></a>22.8.3 Returning values from arguments</H3> +<p> Sometimes it is desirable for a function to return a value in one of its arguments. This example describes the implementation of the <tt>OUTPUT</tt> typemap. +</p> -<p> -<blockquote><pre>%module return +<blockquote><pre> +%module return // This tells SWIG to treat an double * argument with name 'OutDouble' as // an output value. @@ -1949,20 +2091,24 @@ int multout(double a, double b, double *OUTPUT, double *OUTPUT); <p> When this function is called, the output arguments are appended to the stack used to return results. This shows up an array in Perl. -For example :<p> +For example : +</p> -<p> -<blockquote><pre>@r = multout(7,13); +<blockquote><pre> +@r = multout(7,13); print "multout(7,13) = @r\n"; ($x,$y) = multout(7,13); </pre></blockquote> -<a name="n36"></a><H3>20.8.4 Accessing array structure members</H3> +<H3><a name="Perl5_nn36"></a>22.8.4 Accessing array structure members</H3> -Consider the following data structure :<p> <p> -<blockquote><pre>#define SIZE 8 +Consider the following data structure : +</p> + +<blockquote><pre> +#define SIZE 8 typedef struct { int values[SIZE]; ... @@ -1970,13 +2116,15 @@ typedef struct { </pre></blockquote> +<p> By default, SWIG doesn't know how to the handle the values structure member it's an array, not a pointer. In this case, SWIG makes the array member read-only. Reading will simply return a pointer to the first item in the array. To make the member writable, a "memberin" typemap can be used. +</p> -<p> -<blockquote><pre>%typemap(memberin) int [SIZE] { +<blockquote><pre> +%typemap(memberin) int [SIZE] { int i; for (i = 0; i < SIZE; i++) { $1[i] = $input[i]; @@ -1985,15 +2133,19 @@ To make the member writable, a "memberin" typemap can be used. </pre></blockquote> +<p> Whenever a <tt>int [SIZE]</tt> member is encountered in a structure or class, this typemap provides a safe mechanism for setting its value. +</p> <p> As in the previous example, the typemap can be generalized for any dimension. For example: +</p> -<blockquote><pre>%typemap(memberin) int [ANY] { +<blockquote><pre> +%typemap(memberin) int [ANY] { int i; for (i = 0; i < $1_dim0; i++) { $1[i] = $input[i]; @@ -2009,24 +2161,27 @@ the "in" typemap in the previous section would be used to convert an <tt>int[]</tt> array to C whereas the "memberin" typemap would be used to copy the converted array into a C data structure. -<a name="n37"></a><H3>20.8.5 Turning Perl references into C pointers</H3> +<H3><a name="Perl5_nn37"></a>22.8.5 Turning Perl references into C pointers</H3> +<p> A frequent confusion on the SWIG mailing list is errors caused by the mixing of Perl references and C pointers. For example, suppose you -have a C function that modifies its arguments like this :<p> +have a C function that modifies its arguments like this : +</p> -<p> -<blockquote><pre>void add(double a, double b, double *c) { +<blockquote><pre> +void add(double a, double b, double *c) { *c = a + b; } - </pre></blockquote> -A common misinterpretation of this function is the following Perl script :<p> - <p> -<blockquote><pre># Perl script +A common misinterpretation of this function is the following Perl script : +</p> + +<blockquote><pre> +# Perl script $a = 3.5; $b = 7.5; $c = 0.0; # Output value @@ -2034,10 +2189,11 @@ add($a,$b,\$c); # Place result in c (Except that it doesn't work) </pre></blockquote> <p> -To make this work with a reference, you can use a typemap such as this:<p> +To make this work with a reference, you can use a typemap such as this: +</p> -<p> -<blockquote><pre>%typemap(in) double * (double dvalue) { +<blockquote><pre> +%typemap(in) double * (double dvalue) { SV* tempsv; if (!SvROK($input)) { croak("expected a reference\n"); @@ -2056,10 +2212,13 @@ To make this work with a reference, you can use a typemap such as this:<p> sv_setnv(tempsv, *$input); } </pre></blockquote> + <p> -Now, if you place this before the add function, you can do this :<p> -<p> -<blockquote><pre>$a = 3.5; +Now, if you place this before the add function, you can do this : +</p> + +<blockquote><pre> +$a = 3.5; $b = 7.5; $c = 0.0; add($a,$b,\$c); # Now it works! @@ -2067,19 +2226,21 @@ print "$c\n"; </pre></blockquote> -<a name="n38"></a><H3>20.8.6 Pointer handling</H3> +<H3><a name="Perl5_nn38"></a>22.8.6 Pointer handling</H3> +<p> Occasionally, it might be necessary to convert pointer values that have been stored using the SWIG typed-pointer representation. To convert a pointer from Perl to C, the following function is used: +</p> <p> <tt> int SWIG_ConvertPtr(SV *obj, void **ptr, swig_type_info *ty, int flags) </tt> +</p> -<p> <blockquote> Converts a Perl object <tt>obj</tt> to a C pointer. The result of the conversion is placed into the pointer located at <tt>ptr</tt>. <tt>ty</tt> is a SWIG type descriptor structure. @@ -2090,27 +2251,28 @@ currently undefined and reserved for future expansion. Returns 0 on success and <p> <tt> void *SWIG_MakePtr(SV *obj, void *ptr, swig_type_info *ty, int flags)</tt> -<p> +</p> <blockquote> Creates a new Perl pointer object. <tt>obj</tt> is a Perl SV that has been initialized to hold the result, <tt>ptr</tt> is the pointer to convert, <tt>ty</tt> is the SWIG type descriptor structure that describes the type, and <tt>flags</tt> is a flag that controls properties of the conversion. <tt>flags</tt> is currently undefined and reserved. - </blockquote> +<p> Both of these functions require the use of a special SWIG type-descriptor structure. This structure contains information about the mangled name of the datatype, type-equivalence information, as well as information about converting pointer values under C++ inheritance. For a type of <tt>Foo *</tt>, the type descriptor structure is usually accessed as follows: +</p> <blockquote> <pre> Foo *f; -if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, 0) == -1) return NULL; +if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, 0) == -1) return NULL; SV *sv = sv_newmortal(); SWIG_MakePtr(sv, f, SWIGTYPE_p_Foo, 0); @@ -2123,7 +2285,7 @@ variable <tt>$1_descriptor</tt>. For example: <blockquote> <pre> %typemap(in) Foo * { - if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,0)) == -1) return NULL; + if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,0)) == -1) return NULL; } </pre> </blockquote> @@ -2134,25 +2296,27 @@ For example: <blockquote> <pre> %typemap(in) Foo * { - if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), 0)) == -1) return NULL; + if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), 0)) == -1) return NULL; } </pre> </blockquote> -<a name="n39"></a><H2>20.9 Proxy classes</H2> +<H2><a name="Perl5_nn39"></a>22.9 Proxy classes</H2> +<p> <b>Out of date. Needs update.</b> +</p> <p> - Using the low-level procedural interface, SWIG can also construct a high-level object oriented interface to C structures and C++ classes. This is done by constructing a Perl proxy class that provides an OO wrapper to the underlying code. This section describes the implementation details of the proxy interface. +</p> -<a name="n40"></a><H3>20.9.1 Preliminaries</H3> +<H3><a name="Perl5_nn40"></a>22.9.1 Preliminaries</H3> To generate proxy classes, you need to use the <tt>-proxy</tt> command line option. @@ -2170,12 +2334,15 @@ you provided with the <tt>%module</tt> directive. Then, in place of the origina SWIG creates a collection of high-level Perl wrappers. In your scripts, you will use these high level wrappers. The wrappers, in turn, interact with the low-level procedural module. -<h3>Structure and class wrappers</h3> +<H3><a name="Perl5_nn41"></a>22.9.2 Structure and class wrappers</H3> -Suppose you have the following SWIG interface file :<p> <p> -<blockquote><pre>%module example +Suppose you have the following SWIG interface file : +</p> + +<blockquote><pre> +%module example struct Vector { Vector(double x, double y, double z); ~Vector(); @@ -2184,11 +2351,13 @@ struct Vector { </pre></blockquote> +<p> When wrapped, SWIG creates the following set of low-level accessor -functions as described in previous sections.<p> +functions as described in previous sections. +</p> -<p> -<blockquote><pre>Vector *new_Vector(double x, double y, double z); +<blockquote><pre> +Vector *new_Vector(double x, double y, double z); void delete_Vector(Vector *v); double Vector_x_get(Vector *v); double Vector_x_set(Vector *v, double value); @@ -2199,11 +2368,13 @@ double Vector_z_set(Vector *v, double value); </pre></blockquote> +<p> However, when proxy classes are enabled, these accessor functions are wrapped inside a Perl class like this: +</p> -<p> -<blockquote><pre>package example::Vector; +<blockquote><pre> +package example::Vector; @ISA = qw( example ); %OWNER = (); %BLESSEDMEMBERS = (); @@ -2221,7 +2392,7 @@ sub new () { } sub DESTROY { - return unless $_[0]->isa('HASH'); + return unless $_[0]->isa('HASH'); my $self = tied(%{$_[0]}); delete $ITERATORS{$self}; if (exists $OWNER{$self}) { @@ -2261,12 +2432,15 @@ constructors and destructors for the package and are always named table. This hash table is used to access the member variables of a structure in addition to being able to invoke member functions. The <tt>%OWNER</tt> and <tt>%BLESSEDMEMBERS</tt> hash tables are used -internally and described shortly. <p> +internally and described shortly. +</p> <p> -To use our new shadow class we can simply do the following:<p> -<p> -<blockquote><pre># Perl code using Vector class +To use our new shadow class we can simply do the following: +</p> + +<blockquote><pre> +# Perl code using Vector class $v = new Vector(2,3,4); $w = Vector->new(-1,-2,-3); @@ -2286,37 +2460,44 @@ $v->DESTROY(); </pre></blockquote> -<a name="n41"></a><H3>20.9.2 Object Ownership</H3> +<H3><a name="Perl5_nn42"></a>22.9.3 Object Ownership</H3> +<p> In order for shadow classes to work properly, it is necessary for Perl to manage some mechanism of object ownership. Here's the crux of the -problem---suppose you had a function like this :<p> -<p> -<blockquote><pre>Vector *Vector_get(Vector *v, int index) { +problem---suppose you had a function like this : +</p> + +<blockquote><pre> +Vector *Vector_get(Vector *v, int index) { return &v[i]; } - </pre></blockquote> + +<p> This function takes a Vector pointer and returns a pointer to another Vector. Such a function might be used to manage arrays or lists of vectors (in C). Now contrast this function with the constructor for a -Vector object :<p> +Vector object : +</p> -<p> -<blockquote><pre>Vector *new_Vector(double x, double y, double z) { +<blockquote><pre> +Vector *new_Vector(double x, double y, double z) { Vector *v; v = new Vector(x,y,z); // Call C++ constructor return v; } - </pre></blockquote> + +<p> Both functions return a Vector, but the constructor is returning a brand-new Vector while the other function is returning a Vector that was already created (hopefully). In Perl, both vectors will be indistinguishable---clearly a problem considering that we would probably like the newly created Vector to be destroyed when we are -done with it.<p> +done with it. +</p> <p> To manage these problems, each class contains two methods that access @@ -2329,7 +2510,8 @@ destructor is invoked, the Perl shadow class module checks the <tt>%OWNER</tt> hash to see if Perl created the object. If so, the C/C++ destructor is invoked. If not, we simply destroy the Perl object and leave the underlying C object alone (under the assumption -that someone else must have created it).<p> +that someone else must have created it). +</p> <p> This scheme works remarkably well in practice but it isn't foolproof. @@ -2339,32 +2521,41 @@ corresponding Perl object (this situation turns out to come up frequently when constructing objects like linked lists and trees). When C takes possession of an object, you can change Perl's owership by simply deleting the object from the <tt>%OWNER</tt> hash. This is -done using the <tt>DISOWN </tt>method.<p> +done using the <tt>DISOWN </tt>method. +</p> -<p> -<blockquote><pre># Perl code to change ownership of an object +<blockquote><pre> +# Perl code to change ownership of an object $v = new Vector(x,y,z); $v->DISOWN(); </pre></blockquote> + <p> -To acquire ownership of an object, the <tt>ACQUIRE</tt> method can be used.<p> -<p> -<blockquote><pre># Given Perl ownership of a file +To acquire ownership of an object, the <tt>ACQUIRE</tt> method can be used. +</p> + +<blockquote><pre> +# Given Perl ownership of a file $u = Vector_get($v); $u->ACQUIRE(); </pre></blockquote> +<p> As always, a little care is in order. SWIG does not provide reference counting, garbage collection, or advanced features one might find in -sophisticated languages.<p> +sophisticated languages. +</p> -<a name="n42"></a><H3>20.9.3 Nested Objects</H3> +<H3><a name="Perl5_nn43"></a>22.9.4 Nested Objects</H3> -Suppose that we have a new object that looks like this :<p> <p> -<blockquote><pre>struct Particle { +Suppose that we have a new object that looks like this : +</p> + +<blockquote><pre> +struct Particle { Vector r; Vector v; Vector f; @@ -2372,13 +2563,16 @@ Suppose that we have a new object that looks like this :<p> } </pre></blockquote> + +<p> In this case, the members of the structure are complex objects that have already been encapsulated in a Perl shadow class. To handle these correctly, we use the <tt>%BLESSEDMEMBERS</tt> hash which would -look like this (along with some supporting code) :<p> +look like this (along with some supporting code) : +</p> -<p> -<blockquote><pre>package Particle; +<blockquote><pre> +package Particle; ... %BLESSEDMEMBERS = ( r => `Vector', @@ -2388,38 +2582,45 @@ look like this (along with some supporting code) :<p> </pre></blockquote> +<p> When fetching members from the structure, <tt>%BLESSEDMEMBERS</tt> is checked. If the requested field is present, we create a tied-hash table and return it. If not, we just return the corresponding member -unmodified.<p> +unmodified. +</p> <p> -This implementation allows us to operate on nested structures as follows :<p> +This implementation allows us to operate on nested structures as follows : +</p> + <blockquote><pre> # Perl access of nested structure $p = new Particle(); $p->{f}->{x} = 0.0; %${$p->{v}} = ( x=>0, y=>0, z=>0); </pre></blockquote> -<p> -<a name="n43"></a><H3>20.9.4 Shadow Functions</H3> +<H3><a name="Perl5_nn44"></a>22.9.5 Shadow Functions</H3> -When functions take arguments involving a complex object, it is -sometimes necessary to write a shadow function. For example :<p> <p> -<blockquote><pre>double dot_product(Vector *v1, Vector *v2); +When functions take arguments involving a complex object, it is +sometimes necessary to write a shadow function. For example : +</p> +<blockquote><pre> +double dot_product(Vector *v1, Vector *v2); </pre></blockquote> +<p> Since Vector is an object already wrapped into a shadow class, we need to modify this function to accept arguments that are given in the form of tied hash tables. This is done by creating a Perl function like -this :<p> +this : +</p> -<p> -<blockquote><pre>sub dot_product { +<blockquote><pre> +sub dot_product { my @args = @_; $args[0] = tied(%{$args[0]}); # Get the real pointer values $args[1] = tied(%{$args[1]}); @@ -2430,17 +2631,20 @@ this :<p> <p> This function replaces the original function, but operates in an -identical manner.<p> +identical manner. +</p> -<a name="n44"></a><H3>20.9.5 Inheritance</H3> +<H3><a name="Perl5_nn45"></a>22.9.6 Inheritance</H3> +<p> Simple C++ inheritance is handled using the Perl <tt>@ISA</tt> array in each class package. For example, if you have the following -interface file :<p> +interface file : +</p> -<p> -<blockquote><pre>// shapes.i +<blockquote><pre> +// shapes.i // SWIG interface file for shapes class %module shapes %{ @@ -2470,9 +2674,12 @@ public: </pre></blockquote> -The resulting, Perl wrapper class will create the following code :<p> +<p> +The resulting, Perl wrapper class will create the following code : +</p> -<blockquote><pre>Package Shape; +<blockquote><pre> +Package Shape; @ISA = (shapes); ... Package Circle; @@ -2482,6 +2689,8 @@ Package Square; @ISA = (shapes Shape); </pre></blockquote> + +<p> The <tt>@ISA</tt> array determines where to look for methods of a particular class. In this case, both the <tt>Circle</tt> and <tt>Square</tt> classes inherit functions from <tt>Shape</tt> so we'll @@ -2489,7 +2698,8 @@ want to look in the <tt>Shape</tt> base class for them. All classes also inherit from the top-level module <tt>shapes</tt>. This is because certain common operations needed to implement shadow classes are implemented only once and reused in the wrapper code for various -classes and structures.<p> +classes and structures. +</p> <p> Since SWIG shadow classes are implemented in Perl, it is easy to @@ -2497,9 +2707,10 @@ subclass from any SWIG generated class. To do this, simply put the name of a SWIG class in the <tt>@ISA</tt> array for your new class. However, be forewarned that this is not a trivial problem. In particular, inheritance of data members is extremely tricky (and I'm -not even sure if it really works). <p> +not even sure if it really works). +</p> -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : Feb 13, 2003</address> </body> diff --git a/Doc/Manual/Php.html b/Doc/Manual/Php.html index 57e9ba20a..1c05a155e 100644 --- a/Doc/Manual/Php.html +++ b/Doc/Manual/Php.html @@ -6,44 +6,50 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>21 SWIG and PHP4</H1> +<H1><a name="Php"></a>23 SWIG and PHP4</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Preliminaries</a> -<li><a href="#n3">Building PHP4 Extensions</a> +<li><a href="#Php_nn2">Preliminaries</a> +<li><a href="#Php_nn3">Building PHP4 Extensions</a> <ul> -<li><a href="#n4">Building a loadable extension</a> -<li><a href="#n5">Basic PHP4 interface</a> -<li><a href="#n6">Functions</a> -<li><a href="#n7">Global Variables</a> -<li><a href="#n8">Pointers </a> -<li><a href="#n9">Structures and C++ classes</a> -<li><a href="#n10">Constants</a> -<li><a href="#n11">Shadow classes</a> -<li><a href="#n12">Constructors and Destructers</a> -<li><a href="#n13">Static Member Variables</a> -<li><a href="#n14">PHP4 Pragmas</a> -<li><a href="#n15">Building extensions into php</a> -<li><a href="#n16">To be furthered...</a> +<li><a href="#Php_nn4">Building a loadable extension</a> +<li><a href="#Php_nn5">Basic PHP4 interface</a> +<li><a href="#Php_nn6">Functions</a> +<li><a href="#Php_nn7">Global Variables</a> +<li><a href="#Php_nn8">Pointers </a> +<li><a href="#Php_nn9">Structures and C++ classes</a> +<li><a href="#Php_nn10">Constants</a> +<li><a href="#Php_nn11">Shadow classes</a> +<li><a href="#Php_nn12">Constructors and Destructers</a> +<li><a href="#Php_nn13">Static Member Variables</a> +<li><a href="#Php_nn14">PHP4 Pragmas</a> +<li><a href="#Php_nn15">Building extensions into php</a> +<li><a href="#Php_nn16">To be furthered...</a> </ul> </ul> <!-- INDEX --> +<p> <b>Caution: This chapter (and module!) is still under construction</b> +</p> +<p> In this chapter, we discuss SWIG's support of PHP4. The PHP4 module is still under development so some of the features below may not work properly (or at all!.) +</p> + <p> The PHP4 module has undergone a lot of changes recently affecting the way shadow classes are implemented so you should read this document even if you thought you were familiar with what it said. The major change is that shadow classes are implemented inside the php module in C++ instead of in the generated .php file in php. +</p> -<a name="n2"></a><H2>21.1 Preliminaries</H2> +<H2><a name="Php_nn2"></a>23.1 Preliminaries</H2> In order to use this module, you will need to have a copy of the PHP 4.0 (or @@ -53,15 +59,18 @@ need either the php binary or the Apache php module. If you want to build your extension into php directly (without having the overhead of loading it into each script), you will need the complete PHP source tree available. -<a name="n3"></a><H2>21.2 Building PHP4 Extensions</H2> +<H2><a name="Php_nn3"></a>23.2 Building PHP4 Extensions</H2> -To build a PHP4 extension, run swig using the <tt>-php4</tt> option as follows : <p> +To build a PHP4 extension, run swig using the <tt>-php4</tt> option as follows : +</p> + <blockquote><pre> swig -php4 example.i - </pre></blockquote> + +<p> This will produce 3 files by default. The first file, <tt>example_wrap.c</tt> contains all of the C code needed to build a PHP4 extension. The second file, <tt>php_example.h</tt> contains the header information needed to link the @@ -71,6 +80,8 @@ a place-holder for extra code specified in the interface file. If you want to build your extension using the <tt>phpize</tt> utility, or if you want to build your module into PHP directly, you can specify the <tt>-phpfull</tt> command line argument to swig. +</p> + <p> The <tt>-phpfull</tt> will generate three extra files. The first extra file, <tt>config.m4</tt> contains the shell code needed to @@ -78,6 +89,8 @@ enable the extension as part of the PHP4 build process. The second extra file, <tt>Makefile.in</tt> contains the information needed to build the final Makefile after substitutions. The third and final extra file, <tt>CREDITS</tt> should contain the credits for the extension. +</p> + <p> To finish building the extension, you have two choices. You can either build the extension as a seperate object file which will then have to be explicitly @@ -85,19 +98,25 @@ loaded by each script. Or you can rebuild the entire php source tree and build the extension into the php executable/library so it will be available in every script. The first choice is the default, however it can be changed by passing the '-phpfull' command line switch to select the second build method. +</p> -<a name="n4"></a><H3>21.2.1 Building a loadable extension</H3> +<H3><a name="Php_nn4"></a>23.2.1 Building a loadable extension</H3> +<p> To build a dynamic module for PHP, you have two options. You can use the <tt>phpize</tt> utility, or you can do it manually. +</p> + <p> To build manually, use a compile string similar to this (different for each OS): +</p> <blockquote><pre> cc -I.. $(PHPINC) -fpic -c example_wrap.c cc -shared example_wrap.o -o libexample.so </pre></blockquote> + <p> To build with phpize, after you have run swig you will need to run the 'phpize' command (installed as part of php) in the same @@ -111,12 +130,17 @@ to check that a correct library version is installed or correct header files are included, etc, but you must edit this file before running phpize. ) If you like SWIG can generate simple extra tests for libraries and header files for you. +</p> + <blockquote><pre> swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h" </pre></blockquote> + <p> Will include in the config.m4 search for libxapian.a or libxapian.so and search for libomquery.a or libomquery.so as well as a search for om.h +</p> + <p> If you depend on source files not generated by SWIG, before generated configure file, you may need to edit the <tt> @@ -125,15 +149,21 @@ Makefile.in</tt> file. This contains the names of the source files to compile linked in. If there are extra C files to compile, you will need to add them to the Makefile.in, or add the names of libraries if they are needed. In simple cases SWIG is pretty good at generating a complete Makefile.in and -config.m4 which need no further editing. <p> +config.m4 which need no further editing. +</p> + +<p> You then run the configure script with the command line argument needed to enable the extension. Then run make, which builds the extension. The extension object file will be left in the modules sub directory, you can move it to wherever it is convenient to call from your php script. -<p> +</p> + <p> To test the extension from a PHP script, you need to load it first. You do this by putting the line, +</p> + <blockquote><pre> dl("/path/to/modulename.so"); // Load the module </pre></blockquote> @@ -146,23 +176,28 @@ attempts to do the <tt>dl()</tt> call for you: A more complicated method which builds the module directly into the <tt>php</tt> executable is described <a href="n12">below</a>. -<a name="n5"></a><H3>21.2.2 Basic PHP4 interface</H3> +<H3><a name="Php_nn5"></a>23.2.2 Basic PHP4 interface</H3> -<a name="n6"></a><H3>21.2.3 Functions</H3> +<H3><a name="Php_nn6"></a>23.2.3 Functions</H3> -C functions are converted into PHP functions. Default/optional arguments are -also allowed. An interface file like this :<p> <p> -<blockquote><pre>%module default +C functions are converted into PHP functions. Default/optional arguments are +also allowed. An interface file like this : +</p> + +<blockquote><pre> +%module default int foo(int a); double bar(double, double b = 3.0); ... - </pre></blockquote> -Will be accessed in PHP like this :<p> + <p> +Will be accessed in PHP like this : +</p> + <blockquote><pre> dl("default.so"); $a = foo(2); $b = bar(3.5, -1.5); @@ -170,50 +205,65 @@ $c = bar(3.5); # Use default argument for 2nd parameter </pre></blockquote> -<a name="n7"></a><H3>21.2.4 Global Variables</H3> +<H3><a name="Php_nn7"></a>23.2.4 Global Variables</H3> +<p> Global variables are difficult for PHP to handle, unlike Perl, their is no 'magic' way to intercept modifications made to variables, so changes in a PHP variable will not be reflected in its C equivalent. To get around the problem, two extra function are generated, <tt>Swig_sync_c()</tt> and <tt>Swig_sync_php()</tt>. These functions are called at the start and end of every function call, ensuring changes made in PHP are updated in C ( and vice versa. ) Because this is handled for you, you can modify the variables in PHP as normal, e.g. -<p><p> -<blockquote><pre>%module example; +</p> + +<blockquote><pre> +%module example; ... double seki = 2; ... int example_func(void); - </pre></blockquote> -is accessed as follow :<p> + <p> +is accessed as follow : +</p> + <blockquote><pre> dl("example.so"); print $seki; $seki = $seki * 2; # Does not affect C variable, still equal to 2 example_func(); # Syncs C variable to PHP Variable, now both 4 </pre></blockquote> + +<p> SWIG supports global variables of all C datatypes including pointers and complex -objects.<p> +objects. +</p> -<a name="n8"></a><H3>21.2.5 Pointers </H3> +<H3><a name="Php_nn8"></a>23.2.5 Pointers </H3> +<p> Pointers to C/C++ objects <b>no longer</b> represented as character strings such as:<tt>_523d3f4_Circle_p</tt>, instead they are represented as PHP resources, rather like MySQL connection handles. +</p> + <p> You can also explicitly create a NULL pointer as a string "NULL" or by passing a null or empty value. +</p> -<a name="n9"></a><H3>21.2.6 Structures and C++ classes</H3> +<H3><a name="Php_nn9"></a>23.2.6 Structures and C++ classes</H3> -For structures and classes, SWIG produces accessor fuction for each member function and data. For example :<p> <p> -<blockquote><pre>%module vector +For structures and classes, SWIG produces accessor fuction for each member function and data. For example : +</p> + +<blockquote><pre> +%module vector class Vector { public: @@ -224,7 +274,11 @@ public: }; </pre></blockquote> -This gets turned into the following collection of PHP functions :<p> + +<p> +This gets turned into the following collection of PHP functions : +</p> + <blockquote><pre> Vector_x_set($obj); Vector_x_get($obj); @@ -241,25 +295,29 @@ To use the class, simply use these functions. However, SWIG also has a mechanism for creating shadow classes that hides these functions and uses an object oriented interface instead - see <a href="n7">below</a> -<a name="n10"></a><H3>21.2.7 Constants</H3> +<H3><a name="Php_nn10"></a>23.2.7 Constants</H3> +<p> These work in much the same way as in C/C++, constants can be defined by using either the normal C pre-processor declarations, or the <tt>%constant</tt> SWIG directive. These will then be available from your PHP script as a PHP constant, (e.g. no dollar sign is needed to access them. ) For example, with a swig file like this, -<p> +</p> + <blockquote><pre> %module example #define PI 3.14159 %constant int E = 2.71828 - </pre> </blockquote> + <p> you can access from in your php script like this, +</p> + <blockquote><pre> dl("libexample.so"); @@ -274,16 +332,19 @@ echo "E = " . E . "\n"; There are two peculiarities with using constants in PHP4. The first is that if you try to use an undeclared constant, it will evaulate to a string set to the constants name. For example, -<p> +</p> + <blockquote><pre> %module example #define EASY_TO_MISPELL 0 - </pre> </blockquote> -accessed incorrectly in PHP, + <p> +accessed incorrectly in PHP, +</p> + <blockquote> <pre> dl("libexample.so"); @@ -296,93 +357,120 @@ if(EASY_TO_MISPEL) { </pre> </blockquote> -<p> +<p> will issue a warning about the undeclared constant, but will then evalute it and turn it into a string ('EASY_TO_MISPEL'), which evaluates to true, rather than the value of the constant which would be false. This is a feature. +</p> + <p> The second 'feature' is that although constants are case sensitive (by default), you cannot declare a constant twice with alternative cases. E.g., -<p> +</p> + <blockquote> <pre> %module example #define TEST Hello #define Test World - </pre> </blockquote> -accessed from PHP, + <p> -<pre> +accessed from PHP, +</p> + <blockquote> +<pre> dl("libexample.so"); echo TEST, Test; - -</blockquote> </pre> +</blockquote> + <p> will output "Hello Test" rather than "Hello World". This is because internally, all constants are stored in a hash table by their lower case name, so 'TEST' and 'Test' will map to the same hash element ('Test'). But, because we declared them case sensitive, the Zend engine will test if the case matches with the case the constant was declared with first. +</p> + <p> So, in the example above, the TEST constant was declared first, and will be stored under the hash element 'test'. The 'Test' constant will also map to the same hash element 'test', but will not overwrite it. When called from the script, the TEST constant will again be mapped to the hash element 'test' so the constant will be retrieved. The case will then be checked, and will match up, so the value ('Hello') will be returned. When 'Test' is evaulated, it will also map to the same hash element 'test'. The same constant will be retrieved, this time though the case check will fail as 'Test' != 'TEST'. So PHP will assume that Test is a undeclared constant, and as explained above, will return it as a string set to the constant name ('Test'). Hence the script above will print 'Hello Test'. If they were declared non-case sensitive, the output would be 'Hello Hello', as both point to the same value, without the case test taking place. ( Apologies, this paragraph needs rewritting to make some sense. ) +</p> -<a name="n11"></a><H3>21.2.8 Shadow classes</H3> +<H3><a name="Php_nn11"></a>23.2.8 Shadow classes</H3> +<p> To avoid having to call the various accessor function to get at structures or class members, we can turn C structs and C++ classes into PHP classes that can be be used directly in PHP scripts as objects and object methods. This is done by writing additional PHP code that builds PHP classes on top of the low-level SWIG interface. These PHP classes "shadow" an underlying C/C++ class. +</p> +<p> To have SWIG create shadow classes, use the <tt>-shadow</tt> option : -<p><p><blockquote><pre>% swig -php4 -shadow tbc.i +</p> + +<blockquote><pre> +% swig -php4 -shadow tbc.i </pre></blockquote> + <p> This will produce the same files as before except that the final module will declare internal PHP classes with the same names as the classes in your .i file. No longer are the shadow classes defined in the <tt>.php</tt> file, it will not contain significantly more support PHP code. +</p> +<p> For the most part, the code is the same except that we can now access members of complex data structures using <tt>-></tt> instead of the low level access or functions like before. +</p> +<p> .... ( more examples on the way ) .... +</p> -<a name="n12"></a><H3>21.2.9 Constructors and Destructers</H3> +<H3><a name="Php_nn12"></a>23.2.9 Constructors and Destructers</H3> +<p> Constructors are used in PHP as in C++, they are called when the object is created and any arguments are passed to them. However, function overloading is not allowed in PHP so only one constructor can be used. This creates a problem when copying objects, as we cannot avoid creating a whole new one when all we want is to make it point to the same value as the original. This is currently worked around by doing the following, +</p> + <ul> <li>Create the new PHP object <li>Delete the PHP objects pointer to the C object <li>Set the PHP object's pointer to the same as the original PHP object's pointer. </ul> + +<p> This is rather convoluted and hopefully will be improved upon in a later release. -<p><p> +</p> +<p> Because the internal wrapped objects are wrapped in PHP resources, PHP handles the cleaning up when there are no more references to the wrapped object. 'RegisterShutdownFunction' is no longer needed for this. I am not sure if PHP resources are all freed at the end of a script, or when they each go out of scope. +</p> -<a name="n13"></a><H3>21.2.10 Static Member Variables</H3> +<H3><a name="Php_nn13"></a>23.2.10 Static Member Variables</H3> Class variables are not supported in PHP, however class functions are, using @@ -398,8 +486,11 @@ class Ko { }; </pre></blockquote> + <p> would be accessed in PHP as, +</p> + <blockquote><pre> dl("libexample.so"); @@ -416,7 +507,7 @@ echo "There has now been " . Ko::threats() . " threats\n"; </pre></blockquote> -<a name="n14"></a><H3>21.2.11 PHP4 Pragmas</H3> +<H3><a name="Php_nn14"></a>23.2.11 PHP4 Pragmas</H3> There are a few pragmas understood by the PHP4 module. The first, @@ -445,21 +536,28 @@ function is called. %include "example.h" </pre></blockquote> -<a name="n15"></a><H3>21.2.12 Building extensions into php</H3> +<H3><a name="Php_nn15"></a>23.2.12 Building extensions into php</H3> +<p> This method, selected with the <tt>-phpfull</tt> command line switch, involves rebuilding the entire php source tree. Whilst more complicated to build, it does mean that the extension is then available without having to load it in each script. +</p> + <p> After running swig with the -phpfull switch, you will be left with a shockingly similiar set of files to the previous build process. However you will then need to move these files to a subdirectory within the php source tree, this subdirectory you will need to create under the ext directory, with the name of the extension ( e.g mkdir php-4.0.6/ext/modulename .) +</p> + <p> After moving the files into this directory, you will need to run the 'buildall' script in the php source directory. This rebuilds the configure script and includes the extra command line arguments from the module you have added. +</p> + <p> Before running the generated configure file, you may need to edit the <tt> Makefile.in</tt>. This contains the names of the source files to compile ( @@ -468,13 +566,18 @@ link in. If their are extra C files to compile you will need to add them to the Makefile, or add the names of libraries if they are needed. In most cases <tt>Makefile.in</tt> will be complete, especially if you make use of <tt>-withlibs</tt> and <tt>-withincs</tt> +</p> + <blockquote><pre> swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h" </pre></blockquote> + <p> Will include in the config.m4 and Makefile.in search for libxapian.a or libxapian.so and search for libomquery.a or libomquery.so as well as a search for om.h +</p> + <p> You then need to run the configure command and pass the necessary command line arguments to enable your module ( by default this is --enable-modulename, @@ -482,12 +585,16 @@ but this can be changed by editing the config.m4 file in the modules directory before running the buildall script. In addition, extra tests can be added to the config.m4 file to ensure the correct libraries and header files are installed.) +</p> + <p> Once configure has completed, you can run make to build php. If this all compiles correctly, you should end up with a php executable/library which contains your new module. You can test it with a php script which does not have the 'dl' command as used above. -<a name="n16"></a><H3>21.2.13 To be furthered...</H3> +</p> + +<H3><a name="Php_nn16"></a>23.2.13 To be furthered...</H3> </body> diff --git a/Doc/Manual/Pike.html b/Doc/Manual/Pike.html index d1ace2050..1f509902e 100644 --- a/Doc/Manual/Pike.html +++ b/Doc/Manual/Pike.html @@ -5,44 +5,48 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>5 SWIG and Pike</H1> +<H1><a name="Pike"></a>24 SWIG and Pike</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Preliminaries</a> +<li><a href="#Pike_nn2">Preliminaries</a> <ul> -<li><a href="#n3">Running SWIG</a> -<li><a href="#n4">Getting the right header files</a> -<li><a href="#n5">Using your module</a> +<li><a href="#Pike_nn3">Running SWIG</a> +<li><a href="#Pike_nn4">Getting the right header files</a> +<li><a href="#Pike_nn5">Using your module</a> </ul> -<li><a href="#n6">Basic C/C++ Mapping</a> +<li><a href="#Pike_nn6">Basic C/C++ Mapping</a> <ul> -<li><a href="#n7">Modules</a> -<li><a href="#n8">Functions</a> -<li><a href="#n9">Global variables</a> -<li><a href="#n10">Constants and enumerated types</a> -<li><a href="#n11">Constructors and Destructors</a> -<li><a href="#n12">Static Members</a> +<li><a href="#Pike_nn7">Modules</a> +<li><a href="#Pike_nn8">Functions</a> +<li><a href="#Pike_nn9">Global variables</a> +<li><a href="#Pike_nn10">Constants and enumerated types</a> +<li><a href="#Pike_nn11">Constructors and Destructors</a> +<li><a href="#Pike_nn12">Static Members</a> </ul> </ul> <!-- INDEX --> +<p> This chapter describes SWIG support for Pike. As of this writing, the SWIG Pike module is still under development and is not considered ready for prime time. The Pike module is being developed against the Pike 7.4.10 release and may not be compatible with previous versions -of Pike.<p> +of Pike. +</p> +<p> This chapter covers most SWIG features, but certain low-level details are covered in less depth than in earlier chapters. At the very -least, make sure you read the "<a - href="file:///home/jlj/src/SWIG/Doc/Manual/SWIG.html">SWIG Basics</a>" +least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter.<br> -<a name="n2"></a><H2>5.1 Preliminaries</H2> +</p> +<H2><a name="Pike_nn2"></a>24.1 Preliminaries</H2> -<a name="n3"></a><H3>5.1.1 Running SWIG</H3> + +<H3><a name="Pike_nn3"></a>24.1.1 Running SWIG</H3> Suppose that you defined a SWIG module such as the following: @@ -57,35 +61,46 @@ If you're building a C++ extension, be sure to add the <tt>-c++</tt> option: <blockquote> <pre>$ <b>swig -c++ -pike example.i</b><br></pre> </blockquote> + +<p> This creates a single source file named <tt>example_wrap.c</tt> (or <tt>example_wrap.cxx</tt>, if you ran SWIG with the <tt>-c++</tt> option). The SWIG-generated 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> +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 <tt>example.i</tt>, the name of the wrapper file is <tt>example_wrap.c</tt>. To change this, you can use the <tt>-o</tt> option: +</p> + <blockquote> <pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre> </blockquote> -<a name="n4"></a><H3>5.1.2 Getting the right header files</H3> +<H3><a name="Pike_nn4"></a>24.1.2 Getting the right header files</H3> +<p> In order to compile the C/C++ wrappers, the compiler needs to know the path to the Pike header files. These files are usually contained in a directory such as -<p> </p> +</p> + <blockquote> <pre>/usr/local/pike/7.4.10/include/pike<br></pre> </blockquote> + +<p> There doesn't seem to be any way to get Pike itself to reveal the location of these files, so you may need to hunt around for them. You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt> and so on. +</p> -<a name="n5"></a><H3>5.1.3 Using your module</H3> +<H3><a name="Pike_nn5"></a>24.1.3 Using your module</H3> To use your module, simply use Pike's <tt>import</tt> statement: @@ -98,10 +113,10 @@ Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend) (1) Result: 24 </pre></blockquote> -<a name="n6"></a><H2>5.2 Basic C/C++ Mapping</H2> +<H2><a name="Pike_nn6"></a>24.2 Basic C/C++ Mapping</H2> -<a name="n7"></a><H3>5.2.1 Modules</H3> +<H3><a name="Pike_nn7"></a>24.2.1 Modules</H3> All of the code for a given SWIG module is wrapped into a single Pike @@ -110,7 +125,7 @@ module ultimately determines the module's name (as far as Pike is concerned), SWIG's <tt>%module</tt> directive doesn't really have any significance. -<a name="n8"></a><H3>5.2.2 Functions</H3> +<H3><a name="Pike_nn8"></a>24.2.2 Functions</H3> Global functions are wrapped as new Pike built-in functions. For @@ -131,7 +146,7 @@ exactly as you'd expect it to: (1) Result: 24 </pre></blockquote> -<a name="n9"></a><H3>5.2.3 Global variables</H3> +<H3><a name="Pike_nn9"></a>24.2.3 Global variables</H3> Global variables are currently wrapped as a pair of of functions, one to get @@ -156,19 +171,19 @@ will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>: (3) Result: 3.141590 </pre></blockquote> -<a name="n10"></a><H3>5.2.4 Constants and enumerated types</H3> +<H3><a name="Pike_nn10"></a>24.2.4 Constants and enumerated types</H3> Enumerated types in C/C++ declarations are wrapped as Pike constants, not as Pike enums. -<a name="n11"></a><H3>5.2.5 Constructors and Destructors</H3> +<H3><a name="Pike_nn11"></a>24.2.5 Constructors and Destructors</H3> Constructors are wrapped as <tt>create()</tt> methods, and destructors are wrapped as <tt>destroy()</tt> methods, for Pike classes. -<a name="n12"></a><H3>5.2.6 Static Members</H3> +<H3><a name="Pike_nn12"></a>24.2.6 Static Members</H3> Since Pike doesn't support static methods or data for Pike classes, static @@ -190,4 +205,4 @@ public: SWIG will generate a <tt>Shape_print()</tt> method that invokes the static <tt>Shape::print()</tt> member function, as well as a pair of methods, <tt>Shape_nshapes_get()</tt> and <tt>Shape_nshapes_set()</tt>, to get and set -the value of <tt>Shape::nshapes</tt>.
\ No newline at end of file +the value of <tt>Shape::nshapes</tt>. diff --git a/Doc/Manual/Preface.html b/Doc/Manual/Preface.html index 578bfd70a..d54ced852 100644 --- a/Doc/Manual/Preface.html +++ b/Doc/Manual/Preface.html @@ -5,28 +5,28 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>0 Preface</H1> +<H1><a name="Preface"></a>1 Preface</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Introduction</a> -<li><a href="#n3">Special Introduction for Version 1.3</a> -<li><a href="#n4">SWIG Versions</a> -<li><a href="#n5">SWIG resources</a> -<li><a href="#n6">Prerequisites</a> -<li><a href="#n7">Organization of this manual</a> -<li><a href="#n8">How to avoid reading the manual</a> -<li><a href="#n9">Backwards Compatibility</a> -<li><a href="#n10">Credits</a> -<li><a href="#n11">Bug reports</a> +<li><a href="#Preface_nn2">Introduction</a> +<li><a href="#Preface_nn3">Special Introduction for Version 1.3</a> +<li><a href="#Preface_nn4">SWIG Versions</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_nn10">Credits</a> +<li><a href="#Preface_nn11">Bug reports</a> </ul> <!-- INDEX --> -<a name="n2"></a><H2>0.1 Introduction</H2> +<H2><a name="Preface_nn2"></a>1.1 Introduction</H2> -SWIG is a software development tool for building scripting language +SWIG (Simplified Wrapper and Interface Generator) is a software development tool for building scripting language interfaces to C and C++ programs. Originally developed in 1995, SWIG was first used by scientists in the Theoretical Physics Division at Los Alamos National Laboratory for building user interfaces to simulation codes running on the Connection @@ -44,8 +44,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. -<p> -<a name="n3"></a><H2>0.2 Special Introduction for Version 1.3</H2> +<H2><a name="Preface_nn3"></a>1.2 Special Introduction for Version 1.3</H2> Since SWIG was released in 1996, its user base and applicability has @@ -57,8 +56,7 @@ all of the ANSI C++ standard and approximately ten target languages including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby, and Tcl. -<p> -<a name="n4"></a><H2>0.3 SWIG Versions</H2> +<H2><a name="Preface_nn4"></a>1.3 SWIG Versions</H2> For several years, the most stable version of SWIG has been release @@ -69,10 +67,10 @@ represent stable releases. Currently, developers are working to create a stable SWIG-2.0 release (Maybe in 2003). Don't let the development status of SWIG-1.3 scare you---it is much more stable (and capable) than SWIG-1.1p5. -<a name="n5"></a><H2>0.4 SWIG resources</H2> +<H2><a name="Preface_nn5"></a>1.4 SWIG resources</H2> -The official location of SWIG related material is<p> +The official location of SWIG related material is <blockquote><pre> <a href="http://www.swig.org">http://www.swig.org</a> @@ -85,27 +83,31 @@ implementation tricks. <p> You can also subscribe to the SWIG mailing list by visiting the page +</p> -<p> -<blockquote><pre><a href="http://mailman.cs.uchicago.edu/listinfo/swig">http://mailman.cs.uchicago.edu/listinfo/swig</a> +<blockquote><pre> +<a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a> </pre></blockquote> <p> The mailing list often discusses some of the more technical aspects of -SWIG along with information about beta releases and future work.<p> +SWIG along with information about beta releases and future work. +</p> <p> CVS access to the latest version of SWIG is also available. More information about this can be obtained at: +</p> -<p> -<blockquote><pre><a href="http://www.swig.org/cvs.html">http://www.swig.org/cvs.html</a> +<blockquote><pre> +<a href="http://www.swig.org/cvs.html">http://www.swig.org/cvs.html</a> </pre></blockquote> -<a name="n6"></a><H2>0.5 Prerequisites</H2> +<H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2> +<p> This manual assumes that you know how to write C/C++ programs and that you have at least heard of scripting languages such as Tcl, Python, and Perl. A detailed knowledge of these scripting @@ -116,6 +118,7 @@ However, you should be reasonably familiar with the use of compilers, linkers, and makefiles since making scripting language extensions is somewhat more complicated than writing a normal C program. +</p> <p> Recent SWIG releases have become significantly more capable in @@ -126,7 +129,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. -<a name="n7"></a><H2>0.6 Organization of this manual</H2> +<H2><a name="Preface_nn7"></a>1.6 Organization of this manual</H2> The first few chapters of this manual describe SWIG in general and @@ -137,7 +140,7 @@ can probably skip to that chapter and find almost everything you need to know. Caveat: we are currently working on a documentation rewrite and many of the older language module chapters are still somewhat out of date. -<a name="n8"></a><H2>0.7 How to avoid reading the manual</H2> +<H2><a name="Preface_nn8"></a>1.7 How to avoid reading the manual</H2> If you hate reading manuals, glance at the "Introduction" which @@ -147,7 +150,7 @@ SWIG. After that, simply use the language-specific chapters as a reference. The SWIG distribution also comes with a large directory of examples that illustrate different topics. -<a name="n9"></a><H2>0.8 Backwards Compatibility</H2> +<H2><a name="Preface_nn9"></a>1.8 Backwards Compatibility</H2> If you are a previous user of SWIG, don't expect recent versions of @@ -164,7 +167,7 @@ for the large number of new features that have been added---namespaces, templates, smart pointers, overloaded methods, operators, and more. -<a name="n10"></a><H2>0.9 Credits</H2> +<H2><a name="Preface_nn10"></a>1.9 Credits</H2> SWIG is an unfunded project that would not be possible without the @@ -187,7 +190,7 @@ Gary Holt have provided a great deal of input on improving SWIG's Perl5 implementation. Kevin Butler contributed the first Windows NT port. -<a name="n11"></a><H2>0.10 Bug reports</H2> +<H2><a name="Preface_nn11"></a>1.10 Bug reports</H2> Although every attempt has been made to make SWIG bug-free, we are also trying @@ -200,7 +203,7 @@ core dump occurred), corresponding portions of the SWIG interface file used, and any important pieces of the SWIG generated wrapper code. We can only fix bugs if we know about them. -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : March 9, 2003</address> </body> </html> diff --git a/Doc/Manual/Preprocessor.html b/Doc/Manual/Preprocessor.html index d12b1bc72..173609220 100644 --- a/Doc/Manual/Preprocessor.html +++ b/Doc/Manual/Preprocessor.html @@ -5,17 +5,18 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>6 Preprocessing</H1> +<H1><a name="Preprocessor"></a>7 Preprocessing</H1> <!-- INDEX --> <ul> -<li><a href="#n2">File inclusion</a> -<li><a href="#n3">File imports</a> -<li><a href="#n4">Conditional Compilation</a> -<li><a href="#n5">Macro Expansion</a> -<li><a href="#n6">SWIG Macros</a> -<li><a href="#n7">C99 and GNU Extensions</a> -<li><a href="#n8">Preprocessing and %{ ... %} blocks</a> -<li><a href="#n9">Preprocessing and { ... }</a> +<li><a href="#Preprocessor_nn2">File inclusion</a> +<li><a href="#Preprocessor_nn3">File imports</a> +<li><a href="#Preprocessor_nn4">Conditional Compilation</a> +<li><a href="#Preprocessor_nn5">Macro Expansion</a> +<li><a href="#Preprocessor_nn6">SWIG Macros</a> +<li><a href="#Preprocessor_nn7">C99 and GNU Extensions</a> +<li><a href="#Preprocessor_nn8">Preprocessing and %{ ... %} blocks</a> +<li><a href="#Preprocessor_nn9">Preprocessing and { ... }</a> +<li><a href="#Preprocessor_nn10">Viewing preprocessor output</a> </ul> <!-- INDEX --> @@ -26,7 +27,7 @@ supports the standard preprocessor directives and macro expansion rules. However, a number of modifications and enhancements have been made. This chapter describes some of these modifications. -<a name="n2"></a><H2>6.1 File inclusion</H2> +<H2><a name="Preprocessor_nn2"></a>7.1 File inclusion</H2> To include another file into a SWIG interface, use the <tt>%include</tt> directive @@ -48,7 +49,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 auxilliary files. -<a name="n3"></a><H2>6.2 File imports</H2> +<H2><a name="Preprocessor_nn3"></a>7.2 File imports</H2> SWIG provides another file inclusion directive with the <tt>%import</tt> directive. @@ -73,15 +74,16 @@ 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. -<a name="n4"></a><H2>6.3 Conditional Compilation</H2> +<H2><a name="Preprocessor_nn4"></a>7.3 Conditional Compilation</H2> +<p> SWIG fully supports the use of <tt>#if</tt>, <tt>#ifdef</tt>, <tt>#ifndef</tt>, <tt>#else</tt>, <tt>#endif</tt> to conditionally include parts of an interface. The following symbols are predefined by SWIG when it is parsing the interface: +</p> -<p> <blockquote><pre> SWIG Always defined when SWIG is processing a file SWIGMAC Defined when running SWIG on the Macintosh @@ -116,13 +118,15 @@ __cplusplus Defined when -c++ option used </pre> </blockquote> +<p> Interface files can look at these symbols as necessary to change the way in which an interface is generated or to mix SWIG directives with C code. These symbols are also defined within the C code generated by SWIG (except for the symbol `<tt>SWIG</tt>' which is only defined -within the SWIG compiler).<p> +within the SWIG compiler). +</p> -<a name="n5"></a><H2>6.4 Macro Expansion</H2> +<H2><a name="Preprocessor_nn5"></a>7.4 Macro Expansion</H2> Traditional preprocessor macros can be used in SWIG interfaces. Be aware that the <tt>#define</tt> statement @@ -140,6 +144,7 @@ you may get some extra constants such as <tt>_FOO_H</tt> showing up in the scrip <p> More complex macros can be defined in the standard way. For example: +</p> <blockquote> <pre> @@ -157,18 +162,19 @@ The following operators can appear in macro definitions: <ul> <li><tt>#x</tt><br> Converts macro argument <tt>x</tt> to a string surrounded by double quotes ("x"). +</li> -<p> <li><tt>x ## y</tt><br> Concatenates x and y together to form <tt>xy</tt>. +</li> -<p> <li><tt>`x`</tt><br> If <tt>x</tt> is a string surrounded by double quotes, do nothing. Otherwise, turn into a string like <tt>#x</tt>. This is a non-standard SWIG extension. +</li> </ul> -<a name="n6"></a><H2>6.5 SWIG Macros</H2> +<H2><a name="Preprocessor_nn6"></a>7.5 SWIG Macros</H2> SWIG provides an enhanced macro capability with the <tt>%define</tt> and <tt>%enddef</tt> directives. @@ -208,8 +214,9 @@ directives except for nested <tt>%define</tt> statements. The SWIG macro capability is a very quick and easy way to generate large amounts of code. In fact, many of SWIG's advanced features and libraries are built using this mechanism (such as C++ template support). +</p> -<a name="n7"></a><H2>6.6 C99 and GNU Extensions</H2> +<H2><a name="Preprocessor_nn7"></a>7.6 C99 and GNU Extensions</H2> SWIG-1.3.12 and newer releases support variadic preprocessor macros. For example: @@ -227,10 +234,11 @@ macros defined using <tt>%define</tt>. <p> SWIG allows a variable number of arguments to be empty. However, this often results in an extra comma (,) and syntax error in the resulting expansion. For example: +</p> <blockquote> <pre> -DEBUGF("hello"); --> fprintf(stderr,"hello",); +DEBUGF("hello"); --> fprintf(stderr,"hello",); </pre> </blockquote> @@ -244,6 +252,7 @@ To get rid of the extra comma, use <tt>##</tt> like this: <p> SWIG also supports GNU-style variadic macros. For example: +</p> <blockquote> <pre> @@ -255,7 +264,7 @@ SWIG also supports GNU-style variadic macros. For example: 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. -<a name="n8"></a><H2>6.7 Preprocessing and %{ ... %} blocks</H2> +<H2><a name="Preprocessor_nn8"></a>7.7 Preprocessing and %{ ... %} blocks</H2> The SWIG preprocessor does not process any text enclosed in a code block %{ ... %}. Therefore, @@ -276,7 +285,7 @@ int blah() { the contents of the <tt>%{ ... %}</tt> block are copied without modification to the output (including all preprocessor directives). -<a name="n9"></a><H2>6.8 Preprocessing and { ... }</H2> +<H2><a name="Preprocessor_nn9"></a>7.8 Preprocessing and { ... }</H2> SWIG always runs the preprocessor on text appearing inside <tt>{ ... }</tt>. However, @@ -310,17 +319,21 @@ to actually go into the wrapper file, prefix the preprocessor directives with <t </pre> </blockquote> +<p> SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code. +</p> -<p> +<H2><a name="Preprocessor_nn10"></a>7.9 Viewing preprocessor output</H2> -<a name="n5"></a><H2>6.4 Viewing preprocessor output</H2> + +<p> Like many compilers, SWIG supports a <tt>-E</tt> command line option to display the output from the preprocessor. When the <tt>-E</tt> switch is used, SWIG will not generate any wrappers. 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> -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : March 9, 2003</address> </body> diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html index ba92c7275..dd5ad3d57 100644 --- a/Doc/Manual/Python.html +++ b/Doc/Manual/Python.html @@ -5,87 +5,87 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>22 SWIG and Python</H1> +<H1><a name="Python"></a>25 SWIG and Python</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Overview</a> -<li><a href="#n3">Preliminaries</a> +<li><a href="#Python_nn2">Overview</a> +<li><a href="#Python_nn3">Preliminaries</a> <ul> -<li><a href="#n4">Running SWIG</a> -<li><a href="#n5">Getting the right header files</a> -<li><a href="#n6">Compiling a dynamic module</a> -<li><a href="#n7">Using distutils</a> -<li><a href="#n8">Static linking</a> -<li><a href="#n9">Using your module</a> -<li><a href="#n10">Compilation of C++ extensions</a> -<li><a href="#n11">Compiling for 64-bit platforms</a> -<li><a href="#n12">Building Python Extensions under Windows</a> +<li><a href="#Python_nn4">Running SWIG</a> +<li><a href="#Python_nn5">Getting the right header files</a> +<li><a href="#Python_nn6">Compiling a dynamic module</a> +<li><a href="#Python_nn7">Using distutils</a> +<li><a href="#Python_nn8">Static linking</a> +<li><a href="#Python_nn9">Using your module</a> +<li><a href="#Python_nn10">Compilation of C++ extensions</a> +<li><a href="#Python_nn11">Compiling for 64-bit platforms</a> +<li><a href="#Python_nn12">Building Python Extensions under Windows</a> </ul> -<li><a href="#n13">A tour of basic C/C++ wrapping</a> +<li><a href="#Python_nn13">A tour of basic C/C++ wrapping</a> <ul> -<li><a href="#n14">Modules</a> -<li><a href="#n15">Functions</a> -<li><a href="#n16">Global variables</a> -<li><a href="#n17">Constants and enums</a> -<li><a href="#n18">Pointers</a> -<li><a href="#n19">Structures</a> -<li><a href="#n20">C++ classes</a> -<li><a href="#n21">C++ inheritance</a> -<li><a href="#n22">Pointers, references, values, and arrays</a> -<li><a href="#n23">C++ overloaded functions</a> -<li><a href="#n24">C++ operators</a> -<li><a href="#n25">C++ namespaces</a> -<li><a href="#n26">C++ templates</a> -<li><a href="#n27">C++ Smart Pointers</a> +<li><a href="#Python_nn14">Modules</a> +<li><a href="#Python_nn15">Functions</a> +<li><a href="#Python_nn16">Global variables</a> +<li><a href="#Python_nn17">Constants and enums</a> +<li><a href="#Python_nn18">Pointers</a> +<li><a href="#Python_nn19">Structures</a> +<li><a href="#Python_nn20">C++ classes</a> +<li><a href="#Python_nn21">C++ inheritance</a> +<li><a href="#Python_nn22">Pointers, references, values, and arrays</a> +<li><a href="#Python_nn23">C++ overloaded functions</a> +<li><a href="#Python_nn24">C++ operators</a> +<li><a href="#Python_nn25">C++ namespaces</a> +<li><a href="#Python_nn26">C++ templates</a> +<li><a href="#Python_nn27">C++ Smart Pointers</a> </ul> -<li><a href="#n28">Further details on the Python class interface</a> +<li><a href="#Python_nn28">Further details on the Python class interface</a> <ul> -<li><a href="#n29">Proxy classes</a> -<li><a href="#n30">Memory management</a> -<li><a href="#n31">Python 2.2 and classic classes</a> +<li><a href="#Python_nn29">Proxy classes</a> +<li><a href="#Python_nn30">Memory management</a> +<li><a href="#Python_nn31">Python 2.2 and classic classes</a> </ul> -<li><a href="#n32">Cross language polymorphism (experimental)</a> +<li><a href="#directors">Cross language polymorphism (experimental)</a> <ul> -<li><a href="#n33">Enabling directors</a> -<li><a href="#n34">Director classes</a> -<li><a href="#n35">Ownership and object destruction</a> -<li><a href="#n36">Exception unrolling</a> -<li><a href="#n37">Overhead and code bloat</a> -<li><a href="#n38">Typemaps</a> -<li><a href="#n39">Miscellaneous</a> +<li><a href="#Python_nn33">Enabling directors</a> +<li><a href="#Python_nn34">Director classes</a> +<li><a href="#Python_nn35">Ownership and object destruction</a> +<li><a href="#Python_nn36">Exception unrolling</a> +<li><a href="#Python_nn37">Overhead and code bloat</a> +<li><a href="#Python_nn38">Typemaps</a> +<li><a href="#Python_nn39">Miscellaneous</a> </ul> -<li><a href="#n40">Common customization features</a> +<li><a href="#Python_nn40">Common customization features</a> <ul> -<li><a href="#n41">C/C++ helper functions</a> -<li><a href="#n42">Adding additional Python code</a> -<li><a href="#n43">Class extension with %extend</a> -<li><a href="#n44">Exception handling with %exception</a> +<li><a href="#Python_nn41">C/C++ helper functions</a> +<li><a href="#Python_nn42">Adding additional Python code</a> +<li><a href="#Python_nn43">Class extension with %extend</a> +<li><a href="#Python_nn44">Exception handling with %exception</a> </ul> -<li><a href="#n45">Tips and techniques</a> +<li><a href="#Python_nn45">Tips and techniques</a> <ul> -<li><a href="#n46">Input and output parameters</a> -<li><a href="#n47">Simple pointers</a> -<li><a href="#n48">Unbounded C Arrays</a> -<li><a href="#n49">String handling</a> -<li><a href="#n50">Arrays</a> -<li><a href="#n51">String arrays</a> -<li><a href="#n52">STL wrappers</a> +<li><a href="#Python_nn46">Input and output parameters</a> +<li><a href="#Python_nn47">Simple pointers</a> +<li><a href="#Python_nn48">Unbounded C Arrays</a> +<li><a href="#Python_nn49">String handling</a> +<li><a href="#Python_nn50">Arrays</a> +<li><a href="#Python_nn51">String arrays</a> +<li><a href="#Python_nn52">STL wrappers</a> </ul> -<li><a href="#n53">Typemaps</a> +<li><a href="#Python_nn53">Typemaps</a> <ul> -<li><a href="#n54">What is a typemap?</a> -<li><a href="#n55">Python typemaps</a> -<li><a href="#n56">Typemap variables</a> -<li><a href="#n57">Useful Python Functions</a> +<li><a href="#Python_nn54">What is a typemap?</a> +<li><a href="#Python_nn55">Python typemaps</a> +<li><a href="#Python_nn56">Typemap variables</a> +<li><a href="#Python_nn57">Useful Python Functions</a> </ul> -<li><a href="#n58">Typemap Examples</a> +<li><a href="#Python_nn58">Typemap Examples</a> <ul> -<li><a href="#n59">Converting Python list to a char ** </a> -<li><a href="#n60">Expanding a Python object into multiple arguments</a> -<li><a href="#n61">Using typemaps to return arguments</a> -<li><a href="#n62">Mapping Python tuples into small arrays</a> -<li><a href="#n63">Mapping sequences to C arrays</a> -<li><a href="#n64">Pointer handling</a> +<li><a href="#Python_nn59">Converting Python list to a char ** </a> +<li><a href="#Python_nn60">Expanding a Python object into multiple arguments</a> +<li><a href="#Python_nn61">Using typemaps to return arguments</a> +<li><a href="#Python_nn62">Mapping Python tuples into small arrays</a> +<li><a href="#Python_nn63">Mapping sequences to C arrays</a> +<li><a href="#Python_nn64">Pointer handling</a> </ul> </ul> <!-- INDEX --> @@ -95,25 +95,28 @@ <b>Caution: This chapter is under repair!</b> <p> - This chapter describes SWIG's support of Python. SWIG is compatible with most recent Python versions including Python 2.2 as well as older versions dating back to Python 1.5.2. For the best results, consider using Python 2.0 or newer. +</p> <p> This chapter covers most SWIG features, but certain low-level details are covered in less depth than in earlier chapters. At the -very least, make sure you read the "<a href="SWIG.html">SWIG +very least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter. +</p> -<a name="n2"></a><H2>22.1 Overview</H2> +<H2><a name="Python_nn2"></a>25.1 Overview</H2> +<p> To build Python extension modules, SWIG uses a layered approach in which parts of the extension module are defined in C and other parts are defined in Python. The C layer contains low-level wrappers whereas Python code is used to define high-level features. +</p> <p> This layered approach recognizes the fact that certain aspects of @@ -121,6 +124,7 @@ extension building are better accomplished in each language (instead of trying to do everything in C or C++). Furthermore, by generating code in both languages, you get a lot more flexibility since you can enhance the extension module with support code in either language. +</p> <p> In describing the Python interface, this chapter starts by covering the @@ -129,14 +133,17 @@ Next, the Python interface to common C and C++ programming features is described. Advanced customization features such as typemaps are then described followed by a discussion of low-level implementation details. +</p> -<a name="n3"></a><H2>22.2 Preliminaries</H2> +<H2><a name="Python_nn3"></a>25.2 Preliminaries</H2> -<a name="n4"></a><H3>22.2.1 Running SWIG</H3> +<H3><a name="Python_nn4"></a>25.2.1 Running SWIG</H3> +<p> Suppose that you defined a SWIG module such as the following: +</p> <blockquote> <pre> @@ -148,16 +155,20 @@ int fact(int n); </pre> </blockquote> -To build a Python module, run SWIG using the <tt>-python</tt> option :<p> - <p> -<blockquote><pre>$ swig -python example.i +To build a Python module, run SWIG using the <tt>-python</tt> option : +</p> + +<blockquote><pre> +$ swig -python example.i </pre></blockquote> +<p> If building a C++ extension, add the <tt>-c++</tt> option: +</p> -<p> -<blockquote><pre>$ swig -c++ -python example.i +<blockquote><pre> +$ swig -c++ -python example.i </pre></blockquote> <p> @@ -166,6 +177,7 @@ This creates two different files; a C/C++ source file <tt>example_wrap.c</tt> or 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. The Python source file contains high-level support code. This is the file that you will import to use the module. +</p> <p> The name of the wrapper file is derived from the name of the input file. For example, if the @@ -173,15 +185,18 @@ input file is <tt>example.i</tt>, the name of the wrapper file is <tt>example_wr To change this, you can use the <tt>-o</tt> option. The name of the Python file is derived from the module name specified with <tt>%module</tt>. If the module name is <tt>example</tt>, then a file <tt>example.py</tt> is created. +</p> -<a name="n5"></a><H3>22.2.2 Getting the right header files</H3> +<H3><a name="Python_nn5"></a>25.2.2 Getting the right header files</H3> +<p> In order to compile the C/C++ wrappers, the compiler needs the <tt>Python.h</tt> header file. This file is usually contained in a directory such as +</p> -<p> -<blockquote><pre>/usr/local/include/python2.0 +<blockquote><pre> +/usr/local/include/python2.0 </pre></blockquote> The exact location may vary on your machine, but the above location is @@ -201,20 +216,23 @@ Type "copyright", "credits" or "license" for more information. </pre> </blockquote> -<a name="n6"></a><H3>22.2.3 Compiling a dynamic module</H3> +<H3><a name="Python_nn6"></a>25.2.3 Compiling a dynamic module</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 need to compile your program using comands like this (shown for Linux): +</p> -<p> -<blockquote><pre>$ swig -python example.i +<blockquote><pre> +$ swig -python example.i $ gcc -c example.c $ gcc -c example_wrap.c -I/usr/local/include/python2.0 $ gcc -shared example.o example_wrap.o -o _example.so </pre></blockquote> +<p> The exact commands for doing this vary from platform to platform. However, SWIG tries to guess the right options when it is installed. Therefore, you may want to start with one of the examples in the <tt>SWIG/Examples/python</tt> @@ -222,14 +240,18 @@ directory. If that doesn't work, you will need to read the man-pages for your compiler and linker to get the right set of options. You might also check the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">SWIG Wiki</a> for additional information. +</p> + <p> When linking the module, <b>the name of the output file has to match the name of the module prefixed by an underscore</b>. If the name of your module is "<tt>example</tt>", then the name of the corresponding object file should be "<tt>_example.so</tt>" or "<tt>_examplemodule.so</tt>". The name of the module is specified using the <tt>%module</tt> directive or the -<tt> -module</tt> command line option.<p> +<tt> -module</tt> command line option. +</p> +<p> <b>Compatibility Note:</b> In SWIG-1.3.13 and earlier releases, module names did not include the leading underscore. This is because modules were normally created as C-only extensions without the extra Python @@ -238,11 +260,12 @@ feature). This has been changed in SWIG-1.3.14 and is consistent with other Python extension modules. For example, the <tt>socket</tt> module actually consists of two files; <tt>socket.py</tt> and <tt>_socket.so</tt>. Many other built-in Python modules follow a similar convention. +</p> -<a name="n7"></a><H3>22.2.4 Using distutils</H3> +<H3><a name="Python_nn7"></a>25.2.4 Using distutils</H3> -<a name="n8"></a><H3>22.2.5 Static linking</H3> +<H3><a name="Python_nn8"></a>25.2.5 Static linking</H3> An alternative approach to dynamic linking is to rebuild the Python @@ -258,13 +281,15 @@ the Python source, adding an entry to the <tt>Modules/Setup</tt> file, and rebuilding the interpreter using the Python Makefile. However, newer Python versions have changed the build process. You may need to edit the 'setup.py' file in the Python distribution instead. +</p> <p> In earlier versions of SWIG, the <tt>embed.i</tt> library file could be used to rebuild the interpreter. For example: +</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example extern int fact(int); extern int mod(int, int); @@ -274,12 +299,14 @@ extern double My_variable; </pre></blockquote> +<p> The <tt>embed.i</tt> library file includes supporting code that contains everything needed to rebuild Python. To rebuild the interpreter, you simply do something like this: +</p> -<p> -<blockquote><pre>$ swig -python example.i +<blockquote><pre> +$ swig -python example.i $ gcc example.c example_wrap.c \ -Xlinker -export-dynamic \ -DHAVE_CONFIG_H -I/usr/local/include/python2.1 \ @@ -288,20 +315,22 @@ $ gcc example.c example_wrap.c \ -o mypython </pre></blockquote> +<p> You will need to supply the same libraries that were used to build Python the first time. This may include system libraries such as <tt>-lsocket</tt>, <tt>-lnsl</tt>, and <tt>-lpthread</tt>. Assuming this actually works, the new version of Python should be identical to the default version except that your extension module will be a built-in part of the interpreter. +</p> <p> - <b>Comment:</b> In practice, you should probably try to avoid static linking if possible. Some programmers may be inclined to use static linking in the interest of getting better performance. However, the performance gained by static linking tends to be rather minimal in most situations (and quite frankly not worth the extra hassle in the opinion of this author). +</p> <p> <b>Compatibility note:</b> The <tt>embed.i</tt> library file is @@ -309,15 +338,18 @@ deprecated and has not been maintained for several years. Even though it appears to "work" with Python 2.1, no future support is guaranteed. If using static linking, you might want to rely on a different approach (perhaps using distutils). +</p> -<a name="n9"></a><H3>22.2.6 Using your module</H3> +<H3><a name="Python_nn9"></a>25.2.6 Using your module</H3> +<p> To use your module, simply use the Python <tt>import</tt> statement. If all goes well, you will be able to this: +</p> -<p> -<blockquote><pre>$ python +<blockquote><pre> +$ python >>> import example >>> example.fact(4) 24 @@ -330,31 +362,35 @@ A common error received by first-time users is the following: <pre> >>> import example Traceback (most recent call last): - File "<stdin>", line 1, in ? + File "<stdin>", line 1, in ? File "example.py", line 2, in ? import _example ImportError: No module named _example </pre> </blockquote> +<p> If you get this message, it means that you either forgot to compile the wrapper code into an extension module or you didn't give the extension module the right name. Make sure that you compiled the wrappers into a module called <tt>_example.so</tt>. And don't forget the leading underscore (_). +</p> -<P> +<p> Another possible error is the following: +</p> <blockquote> <pre> >>> import example Traceback (most recent call last): - File "<stdin>", line 1, in ? + File "<stdin>", line 1, in ? ImportError: dynamic module does not define init function (init_example) >>> </pre> </blockquote> +<p> This error is almost always caused when a bad name is given to the shared object file. For example, if you created a file <tt>example.so</tt> instead of <tt>_example.so</tt> you would get this error. Alternatively, this error could arise if the name of the module is @@ -362,9 +398,11 @@ inconsistent with the module name supplied with the <tt>%module</tt> directive. Double-check the interface to make sure the module name and the shared object filename match. Another possible cause of this error is forgetting to link the SWIG-generated wrapper code with the rest of your application when creating the extension module. +</p> <p> Another common error is something similar to the following: +</p> <blockquote> <pre> @@ -375,11 +413,13 @@ ImportError: ./_example.so: undefined symbol: fact </pre> </blockquote> +<p> This error usually indicates that you forgot to include some object files or libraries in the linking of the shared library file. Make sure you compile both the SWIG wrapper file and your original program into a shared library file. Make sure you pass all of the required libraries to the linker. +</p> <p> Sometimes unresolved symbols occur because a wrapper has been created @@ -389,9 +429,11 @@ was never actually implemented or it was removed from a library without updating the header file. To fix this, you can either edit the SWIG input file to remove the offending declaration or you can use the <tt>%ignore</tt> directive to ignore the declaration. +</p> <p> Finally, suppose that your extension module is linked with another library like this: +</p> <blockquote> <pre> @@ -405,11 +447,11 @@ problem when you try to use your module: <blockquote> <pre> ->>> import example +>>> import example Traceback (most recent call last): - File "<stdin>", line 1, in ? + File "<stdin>", line 1, in ? ImportError: libfoo.so: cannot open shared object file: No such file or directory ->>> +>>> </pre> </blockquote> @@ -445,7 +487,7 @@ Finally, you can use a command such as <tt>ldconfig</tt> (Linux) or system configuration (this requires root access and you will need to read the man pages). -<a name="n10"></a><H3>22.2.7 Compilation of C++ extensions</H3> +<H3><a name="Python_nn10"></a>25.2.7 Compilation of C++ extensions</H3> Compilation of C++ extensions has traditionally been a tricky problem. @@ -456,20 +498,23 @@ correctly. <p> On most machines, C++ extension modules should be linked using the C++ compiler. For example: +</p> -<p> -<blockquote><pre>% swig -c++ -python example.i +<blockquote><pre> +% swig -c++ -python example.i % g++ -c example.cxx % g++ -c example_wrap.cxx -I/usr/local/include/python2.0 % g++ -shared example.o example_wrap.o -o _example.so </pre></blockquote> +<p> In addition to this, you may need to include additional library files to make it work. For example, if you are using the Sun C++ compiler on Solaris, you often need to add an extra library <tt>-lCrun</tt> like this: +</p> -<p> -<blockquote><pre>% swig -c++ -python example.i +<blockquote><pre> +% swig -c++ -python example.i % CC -c example.cxx % CC -c example_wrap.cxx -I/usr/local/include/python2.0 % CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o _example.so -lCrun @@ -485,6 +530,7 @@ In the experience of this author, this has never actually appeared to be necessary. Relinking the interpreter with C++ really only includes the special run-time libraries described above---as long as you link your extension modules with these libraries, it should not be necessary to rebuild Python. +</p> <p> If you aren't entirely sure about the linking of a C++ extension, you @@ -492,14 +538,15 @@ might look at an existing C++ program. On many Unix machines, the <tt>ldd</tt> command will list library dependencies. This should give you some clues about what you might have to include when you link your extension module. For example: +</p> <blockquote> <pre> $ ldd swig - libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000) - libm.so.6 => /lib/libm.so.6 (0x4005b000) - libc.so.6 => /lib/libc.so.6 (0x40077000) - /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) + libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000) + libm.so.6 => /lib/libm.so.6 (0x4005b000) + libc.so.6 => /lib/libc.so.6 (0x40077000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) $ </pre> </blockquote> @@ -517,8 +564,9 @@ this probably won't matter. However, if these modules start sharing data, you will need to take steps to avoid segmentation faults and other erratic program behavior. If working with lots of software components, you might want to investigate using a more formal standard such as COM. +</p> -<a name="n11"></a><H3>22.2.8 Compiling for 64-bit platforms</H3> +<H3><a name="Python_nn11"></a>25.2.8 Compiling for 64-bit platforms</H3> On platforms that support 64-bit applications (Solaris, Irix, etc.), @@ -533,6 +581,7 @@ as a 64-bit application. In addition, all libraries, wrapper code, and every other part of your application will need to be compiled for 64-bits. If you plan to use other third-party extension modules, they will also have to be recompiled as 64-bit extensions. +</p> <p> If you are wrapping commercial software for which you have no source @@ -540,8 +589,9 @@ code, you will be forced to use the same linking standard as used by that software. This may prevent the use of 64-bit extensions. It may also introduce problems on platforms that support more than one linking standard (e.g., -o32 and -n32 on Irix). +</p> -<a name="n12"></a><H3>22.2.9 Building Python Extensions under Windows</H3> +<H3><a name="Python_nn12"></a>25.2.9 Building Python Extensions under Windows</H3> Building a SWIG extension to Python under Windows is roughly @@ -554,8 +604,8 @@ take a quick look at these in addition to reading this section. <p> In Developer Studio, SWIG should be invoked as a custom build option. This is usually done as follows: +</p> -<p> <ul> <li>Open up a new workspace and use the AppWizard to select a DLL project. @@ -589,17 +639,19 @@ match the name of your Python module (ie. _example.dll). <li>Build your project. </ul> + <p> If all went well, SWIG will be automatically invoked whenever you build your project. Any changes made to the interface file will result in SWIG being automatically executed to produce a new version of the wrapper file. +</p> <p> To run your new Python extension, simply run Python -and use the <tt>import</tt> command as normal. For example :<p> +and use the <tt>import</tt> command as normal. For example : +</p> -<p> <blockquote><pre> MSDOS > python >>> import example @@ -622,15 +674,16 @@ and other compilers. However, the problem of building usable DLLs with these compilers tends to be rather problematic. For the latest information, you may want to consult the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl"> SWIG Wiki</a>. +</p> -<a name="n13"></a><H2>22.3 A tour of basic C/C++ wrapping</H2> +<H2><a name="Python_nn13"></a>25.3 A tour of basic C/C++ wrapping</H2> By default, SWIG tries to build a very natural Python interface to your C/C++ code. Functions are wrapped as functions, classes are wrapped as classes, and so forth. This section briefly covers the essential aspects of this wrapping. -<a name="n14"></a><H3>22.3.1 Modules</H3> +<H3><a name="Python_nn14"></a>25.3.1 Modules</H3> The SWIG <tt>%module</tt> directive specifies the name of the Python @@ -641,44 +694,52 @@ extension module <tt>_example.so</tt>. When choosing a module name, make sure you don't use the same name as a built-in Python command or standard module name. -<a name="n15"></a><H3>22.3.2 Functions</H3> +<H3><a name="Python_nn15"></a>25.3.2 Functions</H3> +<p> Global functions are wrapped as new Python built-in functions. For example, +</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example int fact(int n); - </pre></blockquote> +<p> creates a built-in function <tt>example.fact(n)</tt> that works exactly -like you think it does:<p> +like you think it does: +</p> -<p> -<blockquote><pre>>>> import example +<blockquote><pre> +>>> import example >>> print example.fact(4) 24 >>> </pre></blockquote> -<a name="n16"></a><H3>22.3.3 Global variables</H3> +<H3><a name="Python_nn16"></a>25.3.3 Global variables</H3> +<p> C/C++ global variables are fully supported by SWIG. However, the underlying mechanism is somewhat different than you might expect due to the way that -Python assignment works. When you type the following in Python<p> - -<p> -<blockquote><pre>a = 3.4 +Python assignment works. When you type the following in Python +</p> +<blockquote><pre> +a = 3.4 </pre></blockquote> -"a" becomes a name for an object containing the value 3.4. If you later type<p> + <p> -<blockquote><pre>b = a +"a" becomes a name for an object containing the value 3.4. If you later type +</p> +<blockquote><pre> +b = a </pre></blockquote> +<p> then "a" and "b" are both names for the object containing the value 3.4. Thus, there is only one object containing 3.4 and "a" and "b" are both names that refer to it. This is quite @@ -686,12 +747,14 @@ different than C where a variable name refers to a memory location in which a value is stored (and assignment copies data into that location). Because of this, there is no direct way to map variable assignment in C to variable assignment in Python. +</p> <p> To provide access to C global variables, SWIG creates a special object called `<tt>cvar</tt>' that is added to each SWIG generated module. Global variables are then accessed as attributes of this object. For example, consider this interface +</p> <blockquote><pre> // SWIG interface file with global variables @@ -702,9 +765,11 @@ extern double density; ... </pre></blockquote> <p> -Now look at the Python interface:<p> -<p> -<blockquote><pre>>>> import example +Now look at the Python interface: +</p> + +<blockquote><pre> +>>> import example >>> # Print out value of a C global variable >>> print example.cvar.My_variable 4 @@ -717,11 +782,12 @@ Now look at the Python interface:<p> <p> If you make an error in variable assignment, you will receive an error message. For example: +</p> <blockquote><pre> >>> example.cvar.density = "Hello" Traceback (most recent call last): - File "<stdin>", line 1, in ? + File "<stdin>", line 1, in ? TypeError: C variable 'density (double )' >>> </pre></blockquote> @@ -730,9 +796,11 @@ TypeError: C variable 'density (double )' If a variable is declared as <tt>const</tt>, it is wrapped as a read-only variable. Attempts to modify its value will result in an error. +</p> <p> To make ordinary variables read-only, you can use the <tt>%immutable</tt> directive. For example: +</p> <blockquote> <pre> @@ -747,6 +815,7 @@ The <tt>%immutable</tt> directive stays in effect until it is explicitly disable <p> If you just want to make a specific variable immutable, supply a declaration name. For example: +</p> <blockquote> <pre> @@ -758,13 +827,14 @@ extern char *path; // Read-only (due to %immutable) <p> If you would like to access variables using a name other than "<tt>cvar</tt>", it can be -changed using the <tt>-globals</tt> option :<p> - -<p> -<blockquote><pre>% swig -python -globals myvar example.i +changed using the <tt>-globals</tt> option : +</p> +<blockquote><pre> +% swig -python -globals myvar example.i </pre></blockquote> +<p> Some care is in order when importing multiple SWIG modules. If you use the "<tt>from <file> import *</tt>" style of importing, you will get a name clash on the variable `<tt>cvar</tt>' @@ -772,14 +842,17 @@ and you will only be able to access global variables from the last module loaded. To prevent this, you might consider renaming <tt>cvar</tt> or making it private to the module by giving it a name that starts with a leading underscore. SWIG does not create <tt>cvar</tt> -if there are no global variables in a module.<p> +if there are no global variables in a module. +</p> -<a name="n17"></a><H3>22.3.4 Constants and enums</H3> +<H3><a name="Python_nn17"></a>25.3.4 Constants and enums</H3> +<p> C/C++ constants are installed as Python objects containing the appropriate value. To create a constant, use <tt>#define</tt>, <tt>enum</tt>, or the <tt>%constant</tt> directive. For example: +</p> <blockquote> <pre> @@ -800,15 +873,17 @@ also telling the C compiler about it, the wrapper code won't compile. <p> Note: declarations declared as <tt>const</tt> are wrapped as read-only variables and will be accessed using the <tt>cvar</tt> object described in the previous section. They -are not wrapped as constants. For further discussion about this, see the <a href="SWIG.html">SWIG Basics</a> chapter. +are not wrapped as constants. For further discussion about this, see the <a href="SWIG.html#SWIG">SWIG Basics</a> chapter. +</p> <p> Constants are not guaranteed to remain constant in Python---the name of the constant could be accidentally reassigned to refer to some other object. Unfortunately, there is no easy way for SWIG to generate code that prevents this. You will just have to be careful. +</p> -<a name="n18"></a><H3>22.3.5 Pointers</H3> +<H3><a name="Python_nn18"></a>25.3.5 Pointers</H3> C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with @@ -828,28 +903,31 @@ When wrapped, you will be able to use the functions in a natural way from Python <blockquote> <pre> ->>> import example ->>> f = example.fopen("junk","w") ->>> example.fputs("Hello World\n", f) ->>> example.fclose(f) +>>> import example +>>> f = example.fopen("junk","w") +>>> example.fputs("Hello World\n", f) +>>> example.fclose(f) </pre> </blockquote> +<p> If this makes you uneasy, rest assured that there is no deep magic involved. Underneath the covers, pointers to C/C++ objects are simply represented as opaque values--normally an encoded character string like this: +</p> -<p> <blockquote><pre> ->>> print f +>>> print f _c0671108_p_FILE ->>> +>>> </pre></blockquote> +<p> This pointer value can be freely passed around to different C functions that expect to receive an object of type <tt>FILE *</tt>. The only thing you can't do is dereference the pointer from Python. Of course, that isn't much of a concern in this example. +</p> <p> As an alternative to strings, SWIG can encode pointers as a @@ -858,13 +936,15 @@ or documentation. However, this is a special built-in type that can be used to hold raw C pointer values. Internally, a CObject is just a container that holds a raw <tt>void *</tt> along with some additional information such as a type-string. +</p> <p> If you want to use CObjects instead of strings, compile the SWIG wrapper code with the <tt>-DSWIG_COBJECT_TYPES</tt> option. For example: +</p> -<p> -<blockquote><pre>% swig -python example.i +<blockquote><pre> +% swig -python example.i % gcc -c example.c % gcc -c -DSWIG_COBJECT_TYPES example_wrap.c -I/usr/local/include/python2.0 % gcc -shared example.o example_wrap.o -o _example.so @@ -877,6 +957,7 @@ using one type or the other (strings actually appear to be ever-so-slightly fast on the author's machine). Although CObjects feel more natural to some programmers, a disadvantage of this approach is that it makes debugging more difficult. For example, if you are using CObjects, you will get code that works like this: +</p> <blockquote> <pre> @@ -899,7 +980,9 @@ the string representation produces the following: </pre> </blockquote> +<p> For either pointer representation, the NULL pointer is represented by <tt>None</tt>. +</p> <p> As much as you might be inclined to modify a pointer value directly @@ -914,6 +997,7 @@ casting C++ objects, and it won't work if you switch to a new pointer representation such as CObjects. If you need to cast a pointer or change its value, consider writing some helper functions instead. For example: +</p> <blockquote> <pre> @@ -940,21 +1024,25 @@ to use the new C++ style casts. For example, in the above code, the 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. -<a name="n19"></a><H3>22.3.6 Structures</H3> +<H3><a name="Python_nn19"></a>25.3.6 Structures</H3> +<p> If you wrap a C structure, it is wrapped by a Python class. This provides a very natural interface. For example, +</p> -<p> -<blockquote><pre>struct Vector { +<blockquote><pre> +struct Vector { double x,y,z; }; </pre></blockquote> -is used as follows: <p> +is used as follows: +</p> + <blockquote><pre> >>> v = example.Vector() >>> v.x = 3.5 @@ -963,17 +1051,19 @@ is used as follows: 7.8 -4.5 0.0 >>> </pre></blockquote> -<p> -Similar access is provided for unions and the data members of C++ classes.<p> +<p> +Similar access is provided for unions and the data members of C++ classes. +</p> <p> If you print out the value of <tt>v</tt> in the above example, you will see something like this: +</p> <blockquote> <pre> ->>> print v +>>> print v <C Vector instance at _18e31408_p_Vector> </pre> </blockquote> @@ -985,9 +1075,9 @@ attribute. For example: <blockquote> <pre> ->>> print v.this +>>> print v.this _18e31408_p_Vector ->>> +>>> </pre> </blockquote> @@ -996,6 +1086,7 @@ Further details about the Python proxy class are covered a little later. <p> <tt>const</tt> members of a structure are read-only. Data members can also be forced to be read-only using the <tt>%immutable</tt> directive. For example: +</p> <blockquote> <pre> @@ -1016,10 +1107,12 @@ dynamically allocated using <tt>malloc</tt> or <tt>new</tt> (depending on whethe SWIG is run with the -c++ option). When the structure member is set, the old contents will be released and a new value created. If this is not the behavior you want, you will have to use a typemap (described later). +</p> <p> If a structure contains arrays, access to those arrays is managed through pointers. For example, consider this: +</p> <blockquote> <pre> @@ -1033,10 +1126,10 @@ If accessed in Python, you will see behavior like this: <blockquote> <pre> ->>> b = example.Bar() ->>> print b.x +>>> b = example.Bar() +>>> print b.x _801861a4_p_int ->>> +>>> </pre> </blockquote> @@ -1046,8 +1139,8 @@ another pointer. For example: <blockquote> <pre> ->>> c = example.Bar() ->>> c.x = b.x # Copy contents of b.x to c.x +>>> c = example.Bar() +>>> c.x = b.x # Copy contents of b.x to c.x </pre> </blockquote> @@ -1059,6 +1152,7 @@ fault or access violation. <p> When a member of a structure is itself a structure, it is handled as a pointer. For example, suppose you have two structures like this: +</p> <blockquote> <pre> @@ -1076,8 +1170,8 @@ Now, suppose that you access the <tt>f</tt> attribute of <tt>Bar</tt> like this: <blockquote> <pre> ->>> b = Bar() ->>> x = b.f +>>> b = Bar() +>>> x = b.f </pre> </blockquote> @@ -1087,7 +1181,7 @@ This is the same value as generated by this C code: <blockquote> <pre> Bar b; -Foo *x = &b->f; /* Points inside b */ +Foo *x = &b->f; /* Points inside b */ </pre> </blockquote> @@ -1096,20 +1190,22 @@ everything works just like you would expect. For example: <blockquote> <pre> ->>> b = Bar() ->>> b.f.a = 3 # Modify attribute of structure member ->>> x = b.f ->>> x.a = 3 # Modifies the same structure +>>> b = Bar() +>>> b.f.a = 3 # Modify attribute of structure member +>>> x = b.f +>>> x.a = 3 # Modifies the same structure </pre> </blockquote> -<a name="n20"></a><H3>22.3.7 C++ classes</H3> +<H3><a name="Python_nn20"></a>25.3.7 C++ classes</H3> +<p> C++ classes are wrapped by Python classes as well. For example, if you have this class, +</p> -<p> -<blockquote><pre>class List { +<blockquote><pre> +class List { public: List(); ~List(); @@ -1143,6 +1239,7 @@ Python classes had no support for static methods and no version of Python supports static member variables in a manner that SWIG can utilize. Therefore, SWIG generates wrappers that try to work around some of these issues. To illustrate, suppose you have a class like this: +</p> <blockquote> <pre> @@ -1159,10 +1256,10 @@ In Python, the static member can be access in three different ways: <blockquote> <pre> ->>> example.Spam_foo() # Spam::foo() ->>> s = example.Spam() ->>> s.foo() # Spam::foo() via an instance ->>> example.Spam.foo() # Spam::foo(). Python-2.2 only +>>> example.Spam_foo() # Spam::foo() +>>> s = example.Spam() +>>> s.foo() # Spam::foo() via an instance +>>> example.Spam.foo() # Spam::foo(). Python-2.2 only </pre> </blockquote> @@ -1172,15 +1269,16 @@ last technique is only available in Python-2.2 and later versions. <p> Static member variables are currently accessed as global variables. This means, they are accessed through <tt>cvar</tt> like this: +</p> <blockquote> <pre> ->>> print example.cvar.Spam_bar +>>> print example.cvar.Spam_bar 7 </pre> </blockquote> -<a name="n21"></a><H3>22.3.8 C++ inheritance</H3> +<H3><a name="Python_nn21"></a>25.3.8 C++ inheritance</H3> SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have @@ -1203,12 +1301,12 @@ structure. All of the usual Python utility functions work normally: <blockquote> <pre> ->>> b = Bar() ->>> instance(b,Foo) +>>> b = Bar() +>>> instance(b,Foo) 1 ->>> issubclass(Bar,Foo) +>>> issubclass(Bar,Foo) 1 ->>> issubclass(Foo,Bar) +>>> issubclass(Foo,Bar) 0 </pre> </blockquote> @@ -1225,8 +1323,9 @@ then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any cla <p> It is safe to use multiple inheritance with SWIG. +</p> -<a name="n22"></a><H3>22.3.9 Pointers, references, values, and arrays</H3> +<H3><a name="Python_nn22"></a>25.3.9 Pointers, references, values, and arrays</H3> In C++, there are many different ways a function might receive @@ -1235,7 +1334,7 @@ and manipulate objects. For example: <blockquote> <pre> void spam1(Foo *x); // Pass by pointer -void spam2(Foo &x); // Pass by reference +void spam2(Foo &x); // Pass by reference void spam3(Foo x); // Pass by value void spam4(Foo x[]); // Array of objects </pre> @@ -1249,11 +1348,11 @@ above functions, it is perfectly legal to do this: <blockquote> <pre> ->>> f = Foo() # Create a Foo ->>> spam1(f) # Ok. Pointer ->>> spam2(f) # Ok. Reference ->>> spam3(f) # Ok. Value. ->>> spam4(f) # Ok. Array (1 element) +>>> f = Foo() # Create a Foo +>>> spam1(f) # Ok. Pointer +>>> spam2(f) # Ok. Reference +>>> spam3(f) # Ok. Value. +>>> spam4(f) # Ok. Array (1 element) </pre> </blockquote> @@ -1263,7 +1362,7 @@ functions like this, <blockquote> <pre> Foo *spam5(); -Foo &spam6(); +Foo &spam6(); Foo spam7(); </pre> </blockquote> @@ -1273,7 +1372,7 @@ Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Python will release this memory when the return value is garbage collected). -<a name="n23"></a><H3>22.3.10 C++ overloaded functions</H3> +<H3><a name="Python_nn23"></a>25.3.10 C++ overloaded functions</H3> C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example, @@ -1290,8 +1389,8 @@ You can use them in Python in a straightforward manner: <blockquote> <pre> ->>> foo(3) # foo(int) ->>> foo("Hello") # foo(char *c) +>>> foo(3) # foo(int) +>>> foo("Hello") # foo(char *c) </pre> </blockquote> @@ -1302,7 +1401,7 @@ Similarly, if you have a class like this, class Foo { public: Foo(); - Foo(const Foo &); + Foo(const Foo &); ... }; </pre> @@ -1312,8 +1411,8 @@ you can write Python code like this: <blockquote> <pre> ->>> f = Foo() # Create a Foo ->>> g = Foo(f) # Copy f +>>> f = Foo() # Create a Foo +>>> g = Foo(f) # Copy f </pre> </blockquote> @@ -1332,7 +1431,7 @@ or <blockquote> <pre> void foo(Bar *b); -void foo(Bar &b); +void foo(Bar &b); </pre> </blockquote> @@ -1372,10 +1471,11 @@ declarations according to a set of type-precedence rules. The order in which in the input does not matter except in situations where ambiguity arises--in this case, the first declaration takes precedence. -<P> +<p> Please refer to the "SWIG and C++" chapter for more information about overloading. +</p> -<a name="n24"></a><H3>22.3.11 C++ operators</H3> +<H3><a name="Python_nn24"></a>25.3.11 C++ operators</H3> Certain C++ overloaded operators can be handled automatically by SWIG. For example, @@ -1388,11 +1488,11 @@ private: double rpart, ipart; public: Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { } - Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { } - Complex &operator=(const Complex &c); - Complex operator+(const Complex &c) const; - Complex operator-(const Complex &c) const; - Complex operator*(const Complex &c) const; + Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { } + Complex &operator=(const Complex &c); + Complex operator+(const Complex &c) const; + Complex operator-(const Complex &c) const; + Complex operator*(const Complex &c) const; Complex operator-() const; double re() const { return rpart; } @@ -1405,12 +1505,12 @@ When wrapped, it works like you expect: <blockquote> <pre> ->>> c = Complex(3,4) ->>> d = Complex(7,8) ->>> e = c + d ->>> e.re() +>>> c = Complex(3,4) +>>> d = Complex(7,8) +>>> e = c + d +>>> e.re() 10.0 ->>> e.im() +>>> e.im() 12.0 </pre> </blockquote> @@ -1423,7 +1523,7 @@ For example, if you had code like this <pre> class Complex { ... -friend Complex operator+(double, const Complex &c); +friend Complex operator+(double, const Complex &c); ... }; </pre> @@ -1435,9 +1535,9 @@ but you may have to encapsulate it in a special function. For example: <blockquote> <pre> -%rename(Complex_add_dc) operator+(double, const Complex &); +%rename(Complex_add_dc) operator+(double, const Complex &); ... -Complex operator+(double, const Complex &c); +Complex operator+(double, const Complex &c); </pre> </blockquote> @@ -1447,8 +1547,9 @@ Keep reading. <p> Also, be aware that certain operators don't map cleanly to Python. For instance, overloaded assignment operators don't map to Python semantics and will be ignored. +</p> -<a name="n25"></a><H3>22.3.12 C++ namespaces</H3> +<H3><a name="Python_nn25"></a>25.3.12 C++ namespaces</H3> SWIG is aware of C++ namespaces, but namespace names do not appear in @@ -1472,14 +1573,14 @@ it works in Python as follows: <blockquote> <pre> ->>> import example ->>> example.fact(3) +>>> import example +>>> example.fact(3) 6 ->>> v = example.Vector() ->>> v.x = 3.4 ->>> print v.y +>>> v = example.Vector() +>>> v.x = 3.4 +>>> print v.y 0.0 ->>> +>>> </pre> </blockquote> @@ -1507,7 +1608,7 @@ extension modules for each namespace separately. If your program utilizes thousands of small deeply nested namespaces each with identical symbol names, well, then you get what you deserve. -<a name="n26"></a><H3>22.3.13 C++ templates</H3> +<H3><a name="Python_nn26"></a>25.3.13 C++ templates</H3> C++ templates don't present a huge problem for SWIG. However, in order @@ -1529,7 +1630,7 @@ struct pair { T1 first; T2 second; pair(); - pair(const T1&, const T2&); + pair(const T1&, const T2&); ~pair(); }; @@ -1541,31 +1642,31 @@ In Python: <blockquote> <pre> ->>> import example ->>> p = example.pairii(3,4) ->>> p.first +>>> import example +>>> p = example.pairii(3,4) +>>> p.first 3 ->>> p.second +>>> p.second 4 </pre> </blockquote> Obviously, there is more to template wrapping than shown in this example. -More details can be found in the <a href="SWIGPlus.html">SWIG and C++</a> chapter. Some more complicated +More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter. Some more complicated examples will appear later. -<a name="n27"></a><H3>22.3.14 C++ Smart Pointers</H3> +<H3><a name="Python_nn27"></a>25.3.14 C++ Smart Pointers</H3> In certain C++ programs, it is common to use classes that have been wrapped by so-called "smart pointers." Generally, this involves the use of a template class -that implements <tt>operator->()</tt> like this: +that implements <tt>operator->()</tt> like this: <blockquote> <pre> template<class T> class SmartPtr { ... - T *operator->(); + T *operator->(); ... } </pre> @@ -1589,8 +1690,8 @@ A smart pointer would be used in C++ as follows: <pre> SmartPtr<Foo> p = CreateFoo(); // Created somehow (not shown) ... -p->x = 3; // Foo::x -int y = p->bar(); // Foo::bar +p->x = 3; // Foo::x +int y = p->bar(); // Foo::bar </pre> </blockquote> @@ -1611,22 +1712,22 @@ Now, in Python, everything should just "work": <blockquote> <pre> ->>> p = example.CreateFoo() # Create a smart-pointer somehow ->>> p.x = 3 # Foo::x ->>> p.bar() # Foo::bar +>>> p = example.CreateFoo() # Create a smart-pointer somehow +>>> p.x = 3 # Foo::x +>>> p.bar() # Foo::bar </pre> </blockquote> -If you ever need to access the underlying pointer returned by <tt>operator->()</tt> itself, +If you ever need to access the underlying pointer returned by <tt>operator->()</tt> itself, simply use the <tt>__deref__()</tt> method. For example: <blockquote> <pre> ->>> f = p.__deref__() # Returns underlying Foo * +>>> f = p.__deref__() # Returns underlying Foo * </pre> </blockquote> -<a name="n28"></a><H2>22.4 Further details on the Python class interface</H2> +<H2><a name="Python_nn28"></a>25.4 Further details on the Python class interface</H2> In the previous section, a high-level view of Python wrapping was @@ -1637,10 +1738,10 @@ advanced features such as operator overloading. However, a number of low-level details were omitted. This section provides a brief overview of how the proxy classes work. -<a name="n29"></a><H3>22.4.1 Proxy classes</H3> +<H3><a name="Python_nn29"></a>25.4.1 Proxy classes</H3> -In the <a href="SWIG.html">"SWIG basics"</a> and <a href="SWIGPlus.html">"SWIG and C++"</a> chapters, +In the <a href="SWIG.html#SWIG">"SWIG basics"</a> and <a href="SWIGPlus.html#SWIGPlus">"SWIG and C++"</a> chapters, details of low-level structure and class wrapping are described. To summarize those chapters, if you have a class like this @@ -1665,21 +1766,25 @@ void delete_Foo(Foo *f) { delete f; } int Foo_x_get(Foo *f) { - return f->x; + return f->x; } void Foo_x_set(Foo *f, int value) { - f->x = value; + f->x = value; } int Foo_spam(Foo *f, int arg1) { - return f->spam(arg1); + return f->spam(arg1); } </pre> </blockquote> +<p> These wrappers can be found in the low-level extension module (e.g., <tt>_example</tt>). +</p> + <p> Using these wrappers, SWIG generates a high-level Python proxy class like this (shown for Python 2.2): +</p> <blockquote> <pre> @@ -1704,9 +1809,9 @@ view, it makes the class work normally: <blockquote> <pre> ->>> f = example.Foo() ->>> f.x = 3 ->>> y = f.spam(5) +>>> f = example.Foo() +>>> f.x = 3 +>>> y = f.spam(5) </pre> </blockquote> @@ -1714,18 +1819,21 @@ The fact that the class has been wrapped by a real Python class offers certain a you can attach new Python methods to the class and you can even inherit from it (something not supported by Python built-in types until Python 2.2). -<a name="n30"></a><H3>22.4.2 Memory management</H3> +<H3><a name="Python_nn30"></a>25.4.2 Memory management</H3> +<p> Associated with proxy object, is an ownership flag <tt>.thisown</tt> The value of this flag determines who is responsible for deleting the underlying C++ object. If set to 1, the Python interpreter will destroy the C++ object when the proxy class is garbage collected. If set to 0 (or if the attribute is missing), then the destruction of the proxy class has no effect on the C++ object. +</p> -<P> +<p> When an object is created by a constructor or returned by value, Python automatically takes ownership of the result. For example: +</p> <blockquote> <pre> @@ -1741,11 +1849,11 @@ In Python: <blockquote> <pre> ->>> f = Foo() ->>> f.thisown +>>> f = Foo() +>>> f.thisown 1 ->>> g = f.bar() ->>> g.thisown +>>> g = f.bar() +>>> g.thisown 1 </pre> </blockquote> @@ -1766,11 +1874,11 @@ public: <blockquote> <pre> ->>> f = Foo() ->>> s = f.spam() ->>> print s.thisown +>>> f = Foo() +>>> s = f.spam() +>>> print s.thisown 0 ->>> +>>> </pre> </blockquote> @@ -1782,6 +1890,7 @@ Python to assume ownership and destroy it! <p> Related to containers, ownership issues can arise whenever an object is assigned to a member or global variable. For example, consider this interface: +</p> <blockquote> <pre> @@ -1801,13 +1910,13 @@ is assigned to a global variable. For example: <blockquote> <pre> ->>> f = example.Foo() ->>> f.thisown +>>> f = example.Foo() +>>> f.thisown 1 ->>> example.cvar.head = f ->>> f.thisown +>>> example.cvar.head = f +>>> f.thisown 0 ->>> +>>> </pre> </blockquote> In this case, C is now holding a reference to the object---you probably don't want Python to destroy it. @@ -1815,16 +1924,16 @@ Similarly, this occurs for members. For example: <blockquote> <pre> ->>> f = example.Foo() ->>> g = example.Foo() ->>> f.thisown +>>> f = example.Foo() +>>> g = example.Foo() +>>> f.thisown 1 ->>> g.thisown +>>> g.thisown 1 ->>> f.next = g ->>> g.thisown +>>> f.next = g +>>> g.thisown 0 ->>> +>>> </pre> </blockquote> @@ -1832,6 +1941,7 @@ Similarly, this occurs for members. For example: For the most part, memory management issues remain hidden. However, there are occasionally situations where you might have to manually change the ownership of an object. For instance, consider code like this: +</p> <blockquote> <pre> @@ -1848,12 +1958,12 @@ Now, consider the following Python code: <blockquote> <pre> ->>> v = Object() # Create an object ->>> n = Node() # Create a node ->>> n.set_value(v) # Set value ->>> v.thisown +>>> v = Object() # Create an object +>>> n = Node() # Create a node +>>> n.set_value(v) # Set value +>>> v.thisown 1 ->>> del v +>>> del v </pre> </blockquote> @@ -1866,17 +1976,18 @@ you're lucky, you will only get a segmentation fault. <p> To work around this, it is always possible to flip the ownership flag. For example, +</p> <blockquote> <pre> ->>> v.thisown = 0 +>>> v.thisown = 0 </pre> </blockquote> It is also possible to deal with situations like this using typemaps--an advanced topic discussed later. -<a name="n31"></a><H3>22.4.3 Python 2.2 and classic classes</H3> +<H3><a name="Python_nn31"></a>25.4.3 Python 2.2 and classic classes</H3> SWIG makes every attempt to preserve backwards compatibility with @@ -1894,37 +2005,44 @@ these wrappers encapsulate C++ objects in new-style classes that take advantage of new features (static methods and properties). However, if these very same wrappers are imported into an older version of Python, old-style classes are used instead. +</p> <p> This dual-nature of the wrapper code means that you can create extension modules with SWIG and those modules will work with all versions of Python ranging from Python-1.4 to the very latest release. Moreover, the wrappers take advantage of Python-2.2 features when available. +</p> -<P> +<p> For the most part, the interface presented to users is the same regardless of what version of Python is used. The only incompatibility lies in the handling of static member functions. In Python-2.2, they can be accessed via the class itself. In Python-2.1 and earlier, they have to be accessed as a global function or through an instance (see the earlier section). +</p> -<a name="directors"> -<a name="n32"></a><H2>22.5 Cross language polymorphism (experimental)</H2> +<H2><a name="directors"></a>25.5 Cross language polymorphism (experimental)</H2> +<p> Proxy classes provide a more natural, object-oriented way to access extension classes. As described above, each proxy instance has an associated C++ instance, and method calls to the proxy are passed to the C++ instance transparently via C wrapper functions. +</p> -<p> This arrangement is asymmetric in the sense that no corresponding +<p> +This arrangement is asymmetric in the sense that no corresponding mechanism exists to pass method calls down the inheritance chain from C++ to Python. In particular, if a C++ class has been extended in Python (by extending the proxy class), these extensions will not be visible from C++ code. Virtual method calls from C++ are thus not able access the lowest implementation in the inheritance chain. +</p> -<p> Changes have been made to SWIG 1.3.18 to address this problem and +<p> +Changes have been made to SWIG 1.3.18 to address this problem and make the relationship between C++ classes and proxy classes more symmetric. To achieve this goal, new classes called directors are introduced at the bottom of the C++ inheritance chain. The job of the @@ -1936,8 +2054,9 @@ exactly like native C++ classes. Neither C++ code nor Python code needs to know where a particular method is implemented: the combination of proxy classes, director classes, and C wrapper functions takes care of all the cross-language method routing transparently. +</p> -<a name="n33"></a><H3>22.5.1 Enabling directors</H3> +<H3><a name="Python_nn33"></a>25.5.1 Enabling directors</H3> The director feature is disabled by default. To use directors you @@ -1956,7 +2075,7 @@ and methods should get directors. The %feature directive can be applied globally, to specific classes, and to specific methods, like this: <blockquote> -<pre> +<pre> // generate directors for all classes that have virtual methods %feature("director"); @@ -1978,13 +2097,16 @@ directors for specific classes or methods. So for example, </pre> </blockquote> +<p> will generate directors for all virtual methods of class Foo except bar(). -<p> +</p> +<p> Directors can also be generated implicitly through inheritance. In the following, class Bar will get a director class that handles the methods one() and two() (but not three()): +</p> <blockquote> <pre> @@ -2002,9 +2124,10 @@ public: </pre> </blockquote> -<a name="n34"></a><H3>22.5.2 Director classes</H3> +<H3><a name="Python_nn34"></a>25.5.2 Director classes</H3> +<p> For each class that has directors enabled, SWIG generates a new class that derives from both the class in question and a special <tt>Swig::Director</tt> class. These new classes, referred to as director @@ -2013,8 +2136,9 @@ proxy classes. The director classes store a pointer to their underlying Python object and handle various issues related to object ownership. Indeed, this is quite similar to the "this" and "thisown" members of the Python proxy classes. -<p> +</p> +<p> For simplicity let's ignore the <tt>Swig::Director</tt> class and refer to the original C++ class as the director's base class. By default, a director class extends all virtual methods in the inheritance chain of its base @@ -2028,8 +2152,9 @@ the C++ base class and its extensions in Python were seamlessly integrated. That seamless integration is exactly what the director classes provide, transparently skipping over all the messy extension API glue that binds the two languages together. -<p> +</p> +<p> In reality, the "appropriate place" is one of only two possibilities: C++ or Python. Once this decision is made, the rest is fairly easy. If the correct implementation is in C++, then the lowest implementation of @@ -2038,8 +2163,9 @@ correct implementation is in Python, the Python API is used to call the method of the underlying Python object (after which the usual virtual method resolution in Python automatically finds the right implementation). -<p> +</p> +<p> Now how does the director decide which language should handle the method call? The basic rule is to handle the method in Python, unless there's a good reason not to. The reason for this is simple: Python has the most @@ -2059,8 +2185,9 @@ pointer to the Python object that called the wrapper function to the pointer stored by the director. If these are the same, then the C wrapper function tells the director to resolve the method by calling up the C++ inheritance chain, preventing an infinite loop. -<p> +</p> +<p> One more point needs to be made about the relationship between director classes and proxy classes. When a proxy class instance is created in Python, SWIG creates an instance of the original C++ class and assigns @@ -2074,18 +2201,21 @@ class is needed to route calls to these methods correctly. For unmodified proxy classes, all methods are ultimately implemented in C++ so there is no need for the extra overhead involved with routing the calls through Python. +</p> -<a name="n35"></a><H3>22.5.3 Ownership and object destruction</H3> +<H3><a name="Python_nn35"></a>25.5.3 Ownership and object destruction</H3> +<p> Memory management issues are slightly more complicated with directors than for proxy classes alone. Python instances hold a pointer to the associated C++ director object, and the director in turn holds a pointer back to the Python object. By default, proxy classes own their C++ director object and take care of deleting it when they are garbage collected. -<p> +</p> +<p> This relationship can be reversed by calling the special <tt>__disown__()</tt> method of the proxy class. After calling this method, the <tt>.thisown</tt> flag is set to zero, and the director @@ -2096,13 +2226,15 @@ will be destroyed at the same time. This is a good thing, since directors and proxies refer to each other and so must be created and destroyed together. Destroying one without destroying the other will likely cause your program to segfault. -<p> +</p> +<p> To help ensure that no references to the Python object remain after calling <tt>__disown__()</tt>, this method returns a weak reference to the Python object. Weak references are only available in Python versions 2.1 and higher, so for older versions you must exclicitly delete all references. Here is an example: +</p> <blockquote> <pre> @@ -2120,22 +2252,23 @@ public: <blockquote> <pre> ->>> c = FooContainer() ->>> a = Foo().__disown()__ ->>> c.addFoo(a) ->>> b = Foo() ->>> b = b.__disown()__ ->>> c.addFoo(b) ->>> c.addFoo(Foo().__disown()__) +>>> c = FooContainer() +>>> a = Foo().__disown()__ +>>> c.addFoo(a) +>>> b = Foo() +>>> b = b.__disown()__ +>>> c.addFoo(b) +>>> c.addFoo(Foo().__disown()__) </pre> </blockquote> +<p> In this example, we are assuming that FooContainer will take care of deleting all the Foo pointers it contains at some point. Note that no hard references to the Foo objects remain in Python. -<p> +</p> -<a name="n36"></a><H3>22.5.4 Exception unrolling</H3> +<H3><a name="Python_nn36"></a>25.5.4 Exception unrolling</H3> With directors routing method calls to Python, and proxies routing them @@ -2156,14 +2289,16 @@ suffice in most cases: </pre> </blockquote> +<p> This code will check the Python error state after each method call from a director into Python, and throw a C++ exception if an error occured. This exception can be caught in C++ to implement an error handler. Currently no information about the Python error is stored in the Swig::DirectorMethodException object, but this will likely change in the future. -<p> +</p> +<p> It may be the case that a method call originates in Python, travels up to C++ through a proxy class, and then back into Python via a director method. If an exception occurs in Python at this point, it would be nice @@ -2171,12 +2306,13 @@ for that exception to find its way back to the original caller. This can be done by combining a normal %exception directive with the <tt>director:except</tt> handler shown above. Here is an example of a suitable exception handler: +</p> <blockquote> <pre> %exception { try { $action } - catch (Swig::DirectorException &e) { SWIG_fail; } + catch (Swig::DirectorException &e) { SWIG_fail; } } </pre> </blockquote> @@ -2187,9 +2323,10 @@ exception. Because the Python error state is still set when Swig::DirectorMethodException is thrown, Python will register the exception as soon as the C wrapper function returns. -<a name="n37"></a><H3>22.5.5 Overhead and code bloat</H3> +<H3><a name="Python_nn37"></a>25.5.5 Overhead and code bloat</H3> +<p> Enabling directors for a class will generate a new director method for every virtual method in the class' inheritance chain. This alone can generate a lot of code bloat for large hierarchies. Method arguments @@ -2197,8 +2334,9 @@ that require complex conversions to and from target language types can result in large director methods. For this reason it is recommended that you selectively enable directors only for specific classes that are likely to be extended in Python and used in C++. -<p> +</p> +<p> Compared to classes that do not use directors, the call routing in the director methods does add some overhead. In particular, at least one dynamic cast and one extra function call occur per method call from @@ -2207,8 +2345,9 @@ completely negligible. For worst case routing, a method call that ultimately resolves in C++ may take one extra detour through Python in order to ensure that the method does not have an extended Python implementation. This could result in a noticible overhead in some cases. -<p> +</p> +<p> Although directors make it natural to mix native C++ objects with Python objects (as director objects) via a common base class pointer, one should be aware of the obvious fact that method calls to Python objects @@ -2216,27 +2355,30 @@ will be much slower than calls to C++ objects. This situation can be optimized by selectively enabling director methods (using the %feature directive) for only those methods that are likely to be extended in Python. +</p> -<a name="n38"></a><H3>22.5.6 Typemaps</H3> +<H3><a name="Python_nn38"></a>25.5.6 Typemaps</H3> +<p> Typemaps for input and output of most of the basic types from director classes have been written. These are roughly the reverse of the usual input and output typemaps used by the wrapper code. The typemap operation names are 'directorin', 'directorout', and 'directorargout'. The director code does not use any of the other kinds of typemaps yet. It is not clear at this point which kinds are appropriate and need to be supported. -<p> +</p> +<p> Typemaps for STL classes are under construction. So far there is support for std::string, std::vector, and std::complex, although there's no guarantee these are fully functional yet. -<p> +</p> -<a name="n39"></a><H3>22.5.7 Miscellaneous</H3> +<H3><a name="Python_nn39"></a>25.5.7 Miscellaneous</H3> -<a name="n40"></a><H2>22.6 Common customization features</H2> +<H2><a name="Python_nn40"></a>25.6 Common customization features</H2> The last section presented the absolute basics of C/C++ wrapping. If you do nothing @@ -2246,7 +2388,7 @@ types of functionality might be missing or the interface to certain functions mi be awkward. This section describes some common SWIG features that are used to improve your the interface to an extension module. -<a name="n41"></a><H3>22.6.1 C/C++ helper functions</H3> +<H3><a name="Python_nn41"></a>25.6.1 C/C++ helper functions</H3> Sometimes when you create a module, it is missing certain bits of functionality. For @@ -2263,14 +2405,14 @@ For example, you might get errors like this: <blockquote> <pre> ->>> a = [ +>>> a = [ ... [1,0,0,0], ... [0,1,0,0], ... [0,0,1,0], ... [0,0,0,1]] ->>> set_transform(im,a) +>>> set_transform(im,a) Traceback (most recent call last): - File "<stdin>", line 1, in ? + File "<stdin>", line 1, in ? TypeError: Type error. Expected _p_a_4__double </pre> </blockquote> @@ -2303,13 +2445,13 @@ From Python, you could then write code like this: <blockquote> <pre> ->>> a = new_mat44() ->>> mat44_set(a,0,0,1.0) ->>> mat44_set(a,1,1,1.0) ->>> mat44_set(a,2,2,1.0) +>>> a = new_mat44() +>>> mat44_set(a,0,0,1.0) +>>> mat44_set(a,1,1,1.0) +>>> mat44_set(a,2,2,1.0) ... ->>> set_transform(im,a) ->>> +>>> set_transform(im,a) +>>> </pre> </blockquote> @@ -2317,7 +2459,7 @@ Admittedly, this is not the most elegant looking approach. However, it works an hard to implement. It is possible to clean this up using Python code, typemaps, and other customization features as covered in later sections. -<a name="n42"></a><H3>22.6.2 Adding additional Python code</H3> +<H3><a name="Python_nn42"></a>25.6.2 Adding additional Python code</H3> If writing support code in C isn't enough, it is also possible to write code in @@ -2348,13 +2490,13 @@ low-level helper functions. For example, this code now seems to work: <blockquote> <pre> ->>> a = [ +>>> a = [ ... [1,0,0,0], ... [0,1,0,0], ... [0,0,1,0], ... [0,0,0,1]] ->>> set_transform(im,a) ->>> +>>> set_transform(im,a) +>>> </pre> </blockquote> @@ -2365,7 +2507,7 @@ soon enough. For now, think of this example as an illustration of what can be done without having to rely on any of the more advanced customization features. -<a name="n43"></a><H3>22.6.3 Class extension with %extend</H3> +<H3><a name="Python_nn43"></a>25.6.3 Class extension with %extend</H3> One of the more interesting features of SWIG is that it can extend @@ -2386,14 +2528,14 @@ struct Vector { %extend Vector { char *__str__() { static char tmp[1024]; - sprintf(tmp,"Vector(%g,%g,%g)", self->x,self->y,self->z); + sprintf(tmp,"Vector(%g,%g,%g)", self->x,self->y,self->z); return tmp; } Vector(double x, double y, double z) { Vector *v = (Vector *) malloc(sizeof(Vector)); - v->x = x; - v->y = y; - v->z = z; + v->x = x; + v->y = y; + v->z = z; return v; } }; @@ -2404,10 +2546,10 @@ Now, in Python <blockquote> <pre> ->>> v = example.Vector(2,3,4) ->>> print v +>>> v = example.Vector(2,3,4) +>>> print v Vector(2,3,4) ->>> +>>> </pre> </blockquote> @@ -2419,9 +2561,9 @@ For example, if you wanted to overload a Python operator, you might do this: %extend Vector { Vector __add__(Vector *other) { Vector v; - v.x = self->x + other->x; - v.y = self->y + other->y; - v.z = self->z + other->z; + v.x = self->x + other->x; + v.y = self->y + other->y; + v.z = self->z + other->z; return v; } }; @@ -2432,28 +2574,31 @@ Use it like this: <blockquote> <pre> ->>> import example ->>> v = example.Vector(2,3,4) ->>> w = example.Vector(10,11,12) ->>> print v+w +>>> import example +>>> v = example.Vector(2,3,4) +>>> w = example.Vector(10,11,12) +>>> print v+w Vector(12,14,16) ->>> +>>> </pre> </blockquote> <tt>%extend</tt> works with both C and C++ code. It does not modify the underlying object in any way---the extensions only show up in the Python interface. -<a name="n44"></a><H3>22.6.4 Exception handling with %exception</H3> +<H3><a name="Python_nn44"></a>25.6.4 Exception handling with %exception</H3> +<p> If a C or C++ function throws an error, you may want to convert that error into a Python exception. To do this, you can use the <tt>%exception</tt> directive. <tt>%exception</tt> simply lets you rewrite part of the generated wrapper code to include an error check. +</p> <p> In C, a function often indicates an error by returning a status code (a negative number or a NULL pointer perhaps). Here is a simple example of how you might handle that: +</p> <blockquote> <pre> @@ -2472,11 +2617,11 @@ In Python, <blockquote> <pre> ->>> a = example.malloc(2000000000) +>>> a = example.malloc(2000000000) Traceback (most recent call last): - File "<stdin>", line 1, in ? + File "<stdin>", line 1, in ? MemoryError: Not enough memory ->>> +>>> </pre> </blockquote> @@ -2499,14 +2644,15 @@ No declaration name is given to <tt>%exception</tt>, it is applied to all wrappe <p> C++ exceptions are also easy to handle. For example, you can write code like this: +</p> <blockquote> <pre> %exception getitem { try { $action - } catch (std::out_of_range &e) { - PyErr_SetString(PyExc_IndexError, const_cast<char*>(e.what())); + } catch (std::out_of_range &e) { + PyErr_SetString(PyExc_IndexError, const_cast<char*>(e.what())); return NULL; } } @@ -2522,6 +2668,7 @@ public: <p> When raising a Python exception from C, use the <tt>PyErr_SetString()</tt> function as shown above. The following exception types can be used as the first argument. +</p> <blockquote> <pre> @@ -2555,9 +2702,9 @@ PyExc_ZeroDivisionError </blockquote> The language-independent <tt>exception.i</tt> library file can also be used -to raise exceptions. See the <a href="Library.html">SWIG Library</a> chapter. +to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> chapter. -<a name="n45"></a><H2>22.7 Tips and techniques</H2> +<H2><a name="Python_nn45"></a>25.7 Tips and techniques</H2> Although SWIG is largely automatic, there are certain types of wrapping problems that @@ -2565,7 +2712,7 @@ require additional user input. Examples include dealing with output parameter strings, binary data, and arrays. This chapter discusses the common techniques for solving these problems. -<a name="n46"></a><H3>22.7.1 Input and output parameters</H3> +<H3><a name="Python_nn46"></a>25.7.1 Input and output parameters</H3> A common problem in some C programs is handling parameters passed as simple pointers. For @@ -2605,13 +2752,13 @@ In Python, this allows you to pass simple values. For example: <blockquote> <pre> ->>> a = add(3,4) ->>> print a +>>> a = add(3,4) +>>> print a 7 ->>> b = sub(7,4) ->>> print b +>>> b = sub(7,4) +>>> print b 3 ->>> +>>> </pre> </blockquote> @@ -2621,6 +2768,7 @@ and how the <tt>OUTPUT</tt> parameter creates a return result. <p> If you don't want to use the names <tt>INPUT</tt> or <tt>OUTPUT</tt>, use the <tt>%apply</tt> directive. For example: +</p> <blockquote> <pre> @@ -2637,6 +2785,7 @@ int sub(int *x, int *y); <p> If a function mutates one of its parameters like this, +</p> <blockquote> <pre> @@ -2660,10 +2809,10 @@ In Python, a mutated parameter shows up as a return value. For example: <blockquote> <pre> ->>> a = negate(3) ->>> print a +>>> a = negate(3) +>>> print a -3 ->>> +>>> </pre> </blockquote> @@ -2674,6 +2823,7 @@ perform in-place modification of a Python object passed as a parameter. The most common use of these special typemap rules is to handle functions that return more than one value. For example, sometimes a function returns a result as well as a special error code: +</p> <blockquote> <pre> @@ -2730,7 +2880,7 @@ Now, in Python: <blockquote> <pre> ->>> r,c = get_dimensions(m) +>>> r,c = get_dimensions(m) </pre> </blockquote> @@ -2745,7 +2895,7 @@ void foo(Bar *OUTPUT); may not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>. -<a name="n47"></a><H3>22.7.2 Simple pointers</H3> +<H3><a name="Python_nn47"></a>25.7.2 Simple pointers</H3> If you must work with simple pointers such as <tt>int *</tt> or <tt>double *</tt> and you don't want to use @@ -2778,13 +2928,13 @@ In Python, you would use the functions like this: <blockquote> <pre> ->>> result = new_intp() ->>> print result +>>> result = new_intp() +>>> print result _108fea8_p_int ->>> add(3,4,result) ->>> print intp_value(result) +>>> add(3,4,result) +>>> print intp_value(result) 7 ->>> +>>> </pre> </blockquote> @@ -2792,16 +2942,16 @@ If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type,name)</t <blockquote> <pre> ->>> result = intp() ->>> add(3,4,result) ->>> print result.value() +>>> result = intp() +>>> add(3,4,result) +>>> print result.value() 7 </pre> </blockquote> -See the <a href="Library.html">SWIG Library</a> chapter for further details. +See the <a href="Library.html#Library">SWIG Library</a> chapter for further details. -<a name="n48"></a><H3>22.7.3 Unbounded C Arrays</H3> +<H3><a name="Python_nn48"></a>25.7.3 Unbounded C Arrays</H3> Sometimes a C function expects an array to be passed as a pointer. For example, @@ -2834,12 +2984,12 @@ For instance, you will be able to do this in Python: <blockquote> <pre> ->>> a = intArray(10000000) # Array of 10-million integers ->>> for i in xrange(10000): # Set some values +>>> a = intArray(10000000) # Array of 10-million integers +>>> for i in xrange(10000): # Set some values ... a[i] = i ->>> sumitems(a,10000) +>>> sumitems(a,10000) 49995000 ->>> +>>> </pre> </blockquote> @@ -2855,7 +3005,7 @@ On the other hand, this low-level approach is extremely efficient and well suited for applications in which you need to create buffers, package binary data, etc. -<a name="n49"></a><H3>22.7.4 String handling</H3> +<H3><a name="Python_nn49"></a>25.7.4 String handling</H3> If a C function has an argument of <tt>char *</tt>, then a Python string @@ -2867,7 +3017,7 @@ can be passed as input. For example: void foo(char *s); # Python ->>> foo("Hello") +>>> foo("Hello") </pre> </blockquote> @@ -2878,16 +3028,19 @@ interpreter. <p> If your program modifies the input parameter or uses it to return data, consider -using the <tt>cstring.i</tt> library file described in the <a href="Library.html">SWIG Library</a> chapter. +using the <tt>cstring.i</tt> library file described in the <a href="Library.html#Library">SWIG Library</a> chapter. +</p> <p> When functions return a <tt>char *</tt>, it is assumed to be a NULL-terminated string. Data is copied into a new Python string and returned. +</p> <p> If your program needs to work with binary data, you can use a typemap to expand a Python string into a pointer/length argument pair. As luck would have it, just such a typemap is already defined. Just do this: +</p> <blockquote> <pre> @@ -2901,7 +3054,7 @@ Now in Python: <blockquote> <pre> ->>> parity("e\x09ffss\x00\x00\x01\nx", 0) +>>> parity("e\x09ffss\x00\x00\x01\nx", 0) </pre> </blockquote> @@ -2909,38 +3062,41 @@ If you need to return binary data, you might use the <tt>cstring.i</tt> library file. The <tt>cdata.i</tt> library can also be used to extra binary data from arbitrary pointers. -<a name="n50"></a><H3>22.7.5 Arrays</H3> +<H3><a name="Python_nn50"></a>25.7.5 Arrays</H3> -<a name="n51"></a><H3>22.7.6 String arrays</H3> +<H3><a name="Python_nn51"></a>25.7.6 String arrays</H3> -<a name="n52"></a><H3>22.7.7 STL wrappers</H3> +<H3><a name="Python_nn52"></a>25.7.7 STL wrappers</H3> -<a name="n53"></a><H2>22.8 Typemaps</H2> +<H2><a name="Python_nn53"></a>25.8 Typemaps</H2> 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 Python C API as well -as the material in the "<a href="Typemaps.html">Typemaps</a>" chapter. +as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. <p> Before proceeding, it should be stressed that typemaps are not a required part of using SWIG---the default wrapping behavior is enough in most cases. Typemaps are only used if you want to change some aspect of the primitive C-Python interface or if you want to elevate your guru status. +</p> -<a name="n54"></a><H3>22.8.1 What is a typemap?</H3> +<H3><a name="Python_nn54"></a>25.8.1 What is a typemap?</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 Python to C, you might define a typemap like this: +</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example %typemap(in) int { $1 = (int) PyLong_AsLong($input); @@ -2957,22 +3113,26 @@ will be applied. The supplied C code is used to convert values. In this code a number of special variable prefaced by a <tt>$</tt> are used. The <tt>$1</tt> variable is placeholder for a local variable of type <tt>int</tt>. The <tt>$input</tt> variable is the input object of type <tt>PyObject *</tt>. +</p> <p> When this example is compiled into a Python module, it operates as follows: +</p> -<p> -<blockquote><pre>>>> from example import * +<blockquote><pre> +>>> from example import * >>> fact(6) Received an integer : 6 720 </pre></blockquote> -<p> +<p> In this example, the typemap is applied to all occurrences of the <tt>int</tt> datatype. You can refine this by supplying an optional parameter name. For example: +</p> -<blockquote><pre>%module example +<blockquote><pre> +%module example %typemap(in) int nonnegative { $1 = (int) PyLong_AsLong($input); @@ -2992,6 +3152,7 @@ more than simple text-matching--typemaps are fully integrated into the SWIG C++ type-system. When you define a typemap for <tt>int</tt>, that typemap applies to <tt>int</tt> and qualified variations such as <tt>const int</tt>. In addition, the typemap system follows <tt>typedef</tt> declarations. For example: +</p> <blockquote> <pre> @@ -3006,6 +3167,7 @@ extern int fact(Integer n); // Above typemap is applied <p> Typemaps can also be defined for groups of consecutive arguments. For example: +</p> <blockquote> <pre> @@ -3024,13 +3186,13 @@ parameter is omitted): <blockquote> <pre> ->>> example.count('e','Hello World') +>>> example.count('e','Hello World') 1 ->>> +>>> </pre> </blockquote> -<a name="n55"></a><H3>22.8.2 Python typemaps</H3> +<H3><a name="Python_nn55"></a>25.8.2 Python typemaps</H3> The previous section illustrated an "in" typemap for converting Python objects to C. @@ -3046,7 +3208,7 @@ like this: </pre> </blockquote> -A detailed list of available methods can be found in the "<a href="Typemaps.html">Typemaps</a>" chapter. +A detailed list of available methods can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. However, the best source of typemap information (and examples) is probably the Python module itself. In fact, all of SWIG's default type handling is defined by typemaps. You can view these typemaps by looking at the <tt>python.swg</tt> file in the SWIG library. Just issue @@ -3062,15 +3224,17 @@ $ cat python.swg Additional typemap examples can also be found in the <tt>typemaps.i</tt> file. -<a name="n56"></a><H3>22.8.3 Typemap variables</H3> +<H3><a name="Python_nn56"></a>25.8.3 Typemap variables</H3> Within typemap code, a number of special variables prefaced with a <tt>$</tt> may appear. -A full list of variables can be found in the "<a href="Typemaps.html">Typemaps</a>" chapter. +A full list of variables can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. This is a list of the most common variables: <p> <tt>$1</tt> +</p> + <blockquote> A C local variable corresponding to the actual type specified in the <tt>%typemap</tt> directive. For input values, this is a C local variable @@ -3080,30 +3244,40 @@ the raw result that's supposed to be returned to Python. <p> <tt>$input</tt> +</p> + <blockquote> A <tt>PyObject *</tt> holding a raw Python object with an argument or variable value. </blockquote> <p> <tt>$result</tt> +</p> + <blockquote> A <tt>PyObject *</tt> that holds the result to be returned to Python. </blockquote> -<p> +<p> <tt>$1_name</tt> +</p> + <blockquote> The parameter name that was matched. </blockquote> -<p> +<p> <tt>$1_type</tt> +</p> + <blockquote> The actual C datatype matched by the typemap. </blockquote> -<p> +<p> <tt>$1_ltype</tt> +</p> + <blockquote> An assignable version of the datatype matched by the typemap (a type that can appear on the left-hand-side of a C assignment operation). This type is stripped of qualifiers and may be an altered version of <tt>$1_type</tt>. @@ -3111,12 +3285,15 @@ All arguments and local variables in wrapper functions are declared using this t properly assigned. </blockquote> +<p> <tt>$symname</tt> +</p> + <blockquote> The Python name of the wrapper function being created. </blockquote> -<a name="n57"></a><H3>22.8.4 Useful Python Functions</H3> +<H3><a name="Python_nn57"></a>25.8.4 Useful Python Functions</H3> When you write a typemap, you usually have to work directly with Python objects. @@ -3124,6 +3301,7 @@ The following functions may prove to be useful. <p> <b>Python Integer Functions</b> +</p> <blockquote> <pre> @@ -3213,23 +3391,25 @@ write me </pre> </blockquote> -<a name="n58"></a><H2>22.9 Typemap Examples</H2> +<H2><a name="Python_nn58"></a>25.9 Typemap Examples</H2> This section includes a few examples of typemaps. For more examples, you might look at the files "<tt>python.swg</tt>" and "<tt>typemaps.i</tt>" in the SWIG library. -<a name="n59"></a><H3>22.9.1 Converting Python list to a char ** </H3> +<H3><a name="Python_nn59"></a>25.9.1 Converting Python list to a char ** </H3> +<p> A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings. The following SWIG interface file allows a Python list -object to be used as a <tt>char **</tt> object.<p> +object to be used as a <tt>char **</tt> object. +</p> -<p> -<blockquote><pre>%module argv +<blockquote><pre> +%module argv // This tells SWIG to treat char ** as a special case %typemap(in) char ** { @@ -3273,11 +3453,14 @@ int print_args(char **argv) { %} </pre></blockquote> -When this module is compiled, the wrapped C function now operates as -follows :<p> <p> -<blockquote><pre>>>> from argv import * +When this module is compiled, the wrapped C function now operates as +follows : +</p> + +<blockquote><pre> +>>> from argv import * >>> print_args(["Dave","Mike","Mary","Jane","John"]) argv[0] = Dave argv[1] = Mike @@ -3293,7 +3476,7 @@ memory allocation is used to allocate memory for the array, the "freearg" typemap is used to later release this memory after the execution of the C function. -<a name="n60"></a><H3>22.9.2 Expanding a Python object into multiple arguments</H3> +<H3><a name="Python_nn60"></a>25.9.2 Expanding a Python object into multiple arguments</H3> Suppose that you had a collection of C functions with arguments @@ -3310,7 +3493,7 @@ allows the function to be used from Python as follows: <blockquote> <pre> ->>> foo(4, ["foo","bar","spam","1"]) +>>> foo(4, ["foo","bar","spam","1"]) </pre> </blockquote> @@ -3349,28 +3532,33 @@ previous example: </pre> </blockquote> +<p> When writing a multiple-argument typemap, each of the types is referenced by a variable such as <tt>$1</tt> or <tt>$2</tt>. The typemap code simply fills in the appropriate values from the supplied Python object. +</p> <p> With the above typemap in place, you will find it no longer necessary to supply the argument count. This is automatically set by the typemap code. For example: +</p> <blockquote> <pre> ->>> foo(["foo","bar","spam","1"]) +>>> foo(["foo","bar","spam","1"]) </pre> </blockquote> -<a name="n61"></a><H3>22.9.3 Using typemaps to return arguments</H3> +<H3><a name="Python_nn61"></a>25.9.3 Using typemaps to return arguments</H3> -A common problem in some C programs is that values may be returned in -arguments rather than in the return value of a function. For example -:<p> <p> -<blockquote><pre>/* Returns a status value and two values in out1 and out2 */ +A common problem in some C programs is that values may be returned in +arguments rather than in the return value of a function. For example: +</p> + +<blockquote><pre> +/* Returns a status value and two values in out1 and out2 */ int spam(double a, double b, double *out1, double *out2) { ... Do a bunch of stuff ... *out1 = result1; @@ -3379,9 +3567,13 @@ int spam(double a, double b, double *out1, double *out2) { }; </pre></blockquote> -A typemap can be used to handle this case as follows :<p> + <p> -<blockquote><pre>%module outarg +A typemap can be used to handle this case as follows : +</p> + +<blockquote><pre> +%module outarg // This tells SWIG to treat an double * argument with name 'OutValue' as // an output value. We'll append the value to the current result which @@ -3411,15 +3603,18 @@ int spam(double a, double b, double *OutValue, double *OutValue); </pre></blockquote> +<p> The typemap works as follows. First, a check is made to see if any previous result exists. If so, it is turned into a tuple and the new output value is concatenated to it. Otherwise, the result is returned normally. For the sample function <tt>spam()</tt>, there are three output values--meaning that the function will return a 3-tuple of the results. +</p> <p> As written, the function must accept 4 arguments as input values, last two being pointers to doubles. If these arguments are only used to hold output values (and have no meaningful input value), an additional typemap can be written. For example: +</p> <blockquote><pre> %typemap(in,numinputs=0) double *OutValue(double temp) { @@ -3428,32 +3623,39 @@ no meaningful input value), an additional typemap can be written. For example: </pre></blockquote> +<p> By specifying numinputs=0, the input value is ignored. However, since the argument still has to be set to some meaningful value before calling C, it is set to point to a local variable <tt>temp</tt>. When the function stores its output value, it will simply be placed in this local variable. As a result, the function can now be used as follows: +</p> -<p> -<blockquote><pre>>>> a = spam(4,5) +<blockquote><pre> +>>> a = spam(4,5) >>> print a (0, 2.45, 5.0) >>> x,y,z = spam(4,5) >>> </pre></blockquote> -<a name="n62"></a><H3>22.9.4 Mapping Python tuples into small arrays</H3> +<H3><a name="Python_nn62"></a>25.9.4 Mapping Python tuples into small arrays</H3> +<p> In some applications, it is sometimes desirable to pass small arrays -of numbers as arguments. For example :<p> +of numbers as arguments. For example : +</p> -<p> -<blockquote><pre>extern void set_direction(double a[4]); // Set direction vector +<blockquote><pre> +extern void set_direction(double a[4]); // Set direction vector </pre></blockquote> + <p> -This too, can be handled used typemaps as follows :<p> -<p> -<blockquote><pre>// Grab a 4 element array as a Python 4-tuple +This too, can be handled used typemaps as follows : +</p> + +<blockquote><pre> +// Grab a 4 element array as a Python 4-tuple %typemap(in) double[4](double temp[4]) { // temp[4] becomes a local variable int i; if (PyTuple_Check($input)) { @@ -3470,19 +3672,22 @@ This too, can be handled used typemaps as follows :<p> </pre></blockquote> -This allows our <tt>set_direction</tt> function to be called from -Python as follows :<p> - <p> -<blockquote><pre>>>> set_direction((0.5,0.0,1.0,-0.25)) +This allows our <tt>set_direction</tt> function to be called from +Python as follows : +</p> +<blockquote><pre> +>>> set_direction((0.5,0.0,1.0,-0.25)) </pre></blockquote> +<p> Since our mapping copies the contents of a Python tuple into a C array, such an approach would not be recommended for huge arrays, but -for small structures, this approach works fine.<p> +for small structures, this approach works fine. +</p> -<a name="n63"></a><H3>22.9.5 Mapping sequences to C arrays</H3> +<H3><a name="Python_nn63"></a>25.9.5 Mapping sequences to C arrays</H3> Suppose that you wanted to generalize the previous example to handle C @@ -3508,7 +3713,7 @@ arrays of different sizes. To do this, you might write a typemap as follows: } temp[i] = PyFloat_AsDouble(o); } - $1 = &temp[0]; + $1 = &temp[0]; } </pre> </blockquote> @@ -3556,24 +3761,26 @@ static int convert_darray(PyObject *input, double *ptr, int size) { if (!convert_darray($input,temp,$1_dim0))) { return NULL; } - $1 = &temp[0]; + $1 = &temp[0]; } </pre> </blockquote> -<a name="n64"></a><H3>22.9.6 Pointer handling</H3> +<H3><a name="Python_nn64"></a>25.9.6 Pointer handling</H3> +<p> Occasionally, it might be necessary to convert pointer values that have been stored using the SWIG typed-pointer representation. Since there are several ways in which pointers can be represented, the following two functions are used to safely perform this conversion: +</p> <p> <tt> int SWIG_ConvertPtr(PyObject *obj, void **ptr, swig_type_info *ty, int flags)</tt> +</p> -<p> <blockquote> Converts a Python object <tt>obj</tt> to a C pointer. The result of the conversion is placed into the pointer located at <tt>ptr</tt>. <tt>ty</tt> is a SWIG type descriptor structure. @@ -3585,7 +3792,7 @@ steals ownership of an object. Returns 0 on success and -1 on error. <p> <tt> PyObject *Swig_NewPointerObj(void *ptr, swig_type_info *ty, int own)</tt> -<p> +</p> <blockquote> Creates a new Python pointer object. <tt>ptr</tt> is the pointer to convert, <tt>ty</tt> is the SWIG type descriptor structure that @@ -3603,7 +3810,7 @@ is usually accessed as follows: <blockquote> <pre> Foo *f; -if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, SWIG_POINTER_EXCEPTION) == -1) +if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, SWIG_POINTER_EXCEPTION) == -1) return NULL; PyObject *obj; @@ -3617,7 +3824,7 @@ variable <tt>$1_descriptor</tt>. For example: <blockquote> <pre> %typemap(in) Foo * { -if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,SWIG_POINTER_EXCEPTION)) == -1) +if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,SWIG_POINTER_EXCEPTION)) == -1) return NULL; } </pre> @@ -3626,11 +3833,13 @@ if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,SWIG_POINTER_EXCEPTION) <p> If necessary, the descriptor for any type can be obtained using the <tt>$descriptor()</tt> macro in a typemap. For example: +</p> <blockquote> <pre> %typemap(in) Foo * { -if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), SWIG_POINTER_EXCEPTION)) == -1) +if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), + SWIG_POINTER_EXCEPTION)) == -1) return NULL; } </pre> diff --git a/Doc/Manual/Ruby.html b/Doc/Manual/Ruby.html index d716f14e7..7eb1f96c1 100644 --- a/Doc/Manual/Ruby.html +++ b/Doc/Manual/Ruby.html @@ -4,77 +4,76 @@ <title>SWIG and Ruby</title> </head> <body bgcolor="#ffffff"> -<a name="n1"></a> -<a name="n1"></a><H1>23 SWIG and Ruby</H1> +<H1><a name="Ruby"></a>26 SWIG and Ruby</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Preliminaries</a> +<li><a href="#Ruby_nn2">Preliminaries</a> <ul> -<li><a href="#n3">Running SWIG</a> -<li><a href="#n4">Getting the right header files</a> -<li><a href="#n5">Compiling a dynamic module</a> -<li><a href="#n6">Using your module</a> -<li><a href="#n7">Static linking</a> -<li><a href="#n8">Compilation of C++ extensions</a> +<li><a href="#Ruby_nn3">Running SWIG</a> +<li><a href="#Ruby_nn4">Getting the right header files</a> +<li><a href="#Ruby_nn5">Compiling a dynamic module</a> +<li><a href="#Ruby_nn6">Using your module</a> +<li><a href="#Ruby_nn7">Static linking</a> +<li><a href="#Ruby_nn8">Compilation of C++ extensions</a> </ul> -<li><a href="#n9">Building Ruby Extensions under Windows 95/NT</a> +<li><a href="#Ruby_nn9">Building Ruby Extensions under Windows 95/NT</a> <ul> -<li><a href="#n10">Running SWIG from Developer Studio</a> +<li><a href="#Ruby_nn10">Running SWIG from Developer Studio</a> </ul> -<li><a href="#n11">The Ruby-to-C/C++ Mapping</a> +<li><a href="#Ruby_nn11">The Ruby-to-C/C++ Mapping</a> <ul> -<li><a href="#n12">Modules</a> -<li><a href="#n13">Functions</a> -<li><a href="#n14">Variable Linking</a> -<li><a href="#n15">Constants</a> -<li><a href="#n16">Pointers</a> -<li><a href="#n17">Structures</a> -<li><a href="#n18">C++ classes</a> -<li><a href="#n19">C++ Inheritance</a> -<li><a href="#n20">C++ Overloaded Functions</a> -<li><a href="#n21">C++ Operators</a> -<li><a href="#n22">C++ namespaces</a> -<li><a href="#n23">C++ templates</a> -<li><a href="#n24">C++ Smart Pointers</a> -<li><a href="#n25">Cross-Language Polymorphism</a> +<li><a href="#Ruby_nn12">Modules</a> +<li><a href="#Ruby_nn13">Functions</a> +<li><a href="#Ruby_nn14">Variable Linking</a> +<li><a href="#Ruby_nn15">Constants</a> +<li><a href="#Ruby_nn16">Pointers</a> +<li><a href="#Ruby_nn17">Structures</a> +<li><a href="#Ruby_nn18">C++ classes</a> +<li><a href="#Ruby_nn19">C++ Inheritance</a> +<li><a href="#Ruby_nn20">C++ Overloaded Functions</a> +<li><a href="#Ruby_nn21">C++ Operators</a> +<li><a href="#Ruby_nn22">C++ namespaces</a> +<li><a href="#Ruby_nn23">C++ templates</a> +<li><a href="#ruby_cpp_smart_pointers">C++ Smart Pointers</a> +<li><a href="#Ruby_nn25">Cross-Language Polymorphism</a> <ul> -<li><a href="#n26">Exception Unrolling</a> +<li><a href="#Ruby_nn26">Exception Unrolling</a> </ul> </ul> -<li><a href="#n27">Input and output parameters</a> -<li><a href="#n28">Simple exception handling </a> -<li><a href="#n29">Typemaps</a> +<li><a href="#Ruby_nn27">Input and output parameters</a> +<li><a href="#Ruby_nn28">Simple exception handling </a> +<li><a href="#Ruby_nn29">Typemaps</a> <ul> -<li><a href="#n30">What is a typemap?</a> -<li><a href="#n31">Ruby typemaps</a> -<li><a href="#n32">Typemap variables</a> -<li><a href="#n33">Useful Functions</a> +<li><a href="#Ruby_nn30">What is a typemap?</a> +<li><a href="#Ruby_nn31">Ruby typemaps</a> +<li><a href="#Ruby_nn32">Typemap variables</a> +<li><a href="#Ruby_nn33">Useful Functions</a> <ul> -<li><a href="#n34">C Datatypes to Ruby Objects</a> -<li><a href="#n35">Ruby Objects to C Datatypes</a> -<li><a href="#n36">Macros for VALUE</a> -<li><a href="#n37">Exceptions</a> -<li><a href="#n38">Iterators</a> +<li><a href="#Ruby_nn34">C Datatypes to Ruby Objects</a> +<li><a href="#Ruby_nn35">Ruby Objects to C Datatypes</a> +<li><a href="#Ruby_nn36">Macros for VALUE</a> +<li><a href="#Ruby_nn37">Exceptions</a> +<li><a href="#Ruby_nn38">Iterators</a> </ul> -<li><a href="#n39">Typemap Examples</a> -<li><a href="#n40">Converting a Ruby array to a char **</a> -<li><a href="#n41">Collecting arguments in a hash</a> -<li><a href="#n42">Pointer handling</a> +<li><a href="#ruby_typemap_examples">Typemap Examples</a> +<li><a href="#Ruby_nn40">Converting a Ruby array to a char **</a> +<li><a href="#Ruby_nn41">Collecting arguments in a hash</a> +<li><a href="#Ruby_nn42">Pointer handling</a> <ul> -<li><a href="#n43">Ruby Datatype Wrapping</a> +<li><a href="#Ruby_nn43">Ruby Datatype Wrapping</a> </ul> </ul> -<li><a href="#n44">Operator overloading</a> +<li><a href="#ruby_operator_overloading">Operator overloading</a> <ul> -<li><a href="#n45">Example: STL Vector to Ruby Array</a> +<li><a href="#Ruby_nn45">Example: STL Vector to Ruby Array</a> </ul> -<li><a href="#n46">Advanced Topics</a> +<li><a href="#Ruby_nn46">Advanced Topics</a> <ul> -<li><a href="#n47">Creating Multi-Module Packages</a> -<li><a href="#n48">Defining Aliases</a> -<li><a href="#n49">Predicate Methods</a> -<li><a href="#n50">Specifying Mixin Modules</a> -<li><a href="#n51">Interacting with Ruby's Garbage Collector</a> +<li><a href="#Ruby_nn47">Creating Multi-Module Packages</a> +<li><a href="#Ruby_nn48">Defining Aliases</a> +<li><a href="#Ruby_nn49">Predicate Methods</a> +<li><a href="#Ruby_nn50">Specifying Mixin Modules</a> +<li><a href="#Ruby_nn51">Interacting with Ruby's Garbage Collector</a> </ul> </ul> <!-- INDEX --> @@ -83,7 +82,7 @@ <p>This chapter describes SWIG's support of Ruby. </p> <hr><a name="n2"></a> -<a name="n2"></a><H2>23.1 Preliminaries</H2> +<H2><a name="Ruby_nn2"></a>26.1 Preliminaries</H2> SWIG 1.3 is known to work with Ruby versions 1.6 and later. Given the @@ -96,23 +95,22 @@ without dynamic loading, but the compilation process will vary. <p>This chapter covers most SWIG features, but in less depth than is found in earlier chapters. At the very least, make sure you also read the "<a - href="SWIG.html">SWIG Basics</a>" chapter. It is also assumed that the + href="SWIG.html#SWIG">SWIG Basics</a>" chapter. It is also assumed that the reader has a basic understanding of Ruby. -<a name="n3"></a></p> -<a name="n3"></a><H3>23.1.1 Running SWIG</H3> + +<H3><a name="Ruby_nn3"></a>26.1.1 Running SWIG</H3> <p> To build a Ruby module, run SWIG using the <tt>-ruby</tt> option:</p> -<p></p> -<p></p> + <blockquote> <pre>$ <b>swig -ruby example.i</b> </pre> </blockquote> If building a C++ extension, add the <tt>-c++</tt> option: -<p></p> + <blockquote> <pre>$ <b>swig -c++ -ruby example.i</b> </pre> @@ -125,13 +123,16 @@ build a Ruby extension module. To finish building the module, you need to compile this file and link it with the rest of your program. -<a name="n4"></a></p> -<a name="n4"></a><H3>23.1.2 Getting the right header files</H3> +<H3><a name="Ruby_nn4"></a>26.1.2 Getting the right header files</H3> + + +<p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt> header file. This file is usually contained in a directory such as -<p></p> +</p> + <blockquote> <pre>/usr/local/lib/ruby/1.6/i686-linux/ruby.h<br></pre> </blockquote> @@ -149,8 +150,7 @@ can run Ruby to find out. For example: </pre> </blockquote> -<a name="n5"></a> -<a name="n5"></a><H3>23.1.3 Compiling a dynamic module</H3> +<H3><a name="Ruby_nn5"></a>26.1.3 Compiling a dynamic module</H3> Ruby extension modules are typically compiled into shared libraries @@ -160,7 +160,7 @@ doing this vary from platform to platform, your best bet is to follow the steps described in the <tt>README.EXT</tt> file from the Ruby distribution: -<p></p> + <ol> <li>Create a file called <tt>extconf.rb</tt> that looks like the following: @@ -169,7 +169,6 @@ following: </blockquote> </li> <li>Type the following to build the extension: - <p></p> <blockquote> <pre>$ <b>ruby extconf.rb</b> $ <b>make</b> @@ -194,7 +193,7 @@ platform. For example, a typical sequence of commands for the Linux operating system would look something like this: -<p></p> + <blockquote> <pre>$ <b>swig -ruby example.i</b> $ <b>gcc -c example.c</b> @@ -210,23 +209,22 @@ You might also check the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl"> SWIG Wiki</a> for additional information. <p> <a name="n6"></a></p> -<a name="n6"></a><H3>23.1.4 Using your module</H3> +<H3><a name="Ruby_nn6"></a>26.1.4 Using your module</H3> Ruby <i>module</i> names must be capitalized, but the convention for Ruby <i>feature</i> names is to use lowercase names. So, for example, the <b>Etc</b> extension module is imported by requiring the <b>etc</b> feature: -<pre><blockquote># The feature name begins with a lowercase letter...<br>require 'etc'<br><br># ... but the module name begins with an uppercase letter<br>puts "Your login name: #{Etc.getlogin}"<br></blockquote></pre> +<blockquote><pre># The feature name begins with a lowercase letter...<br>require 'etc'<br><br># ... but the module name begins with an uppercase letter<br>puts "Your login name: #{Etc.getlogin}"<br></pre></blockquote> To stay consistent with this practice, you should always specify a <b>lowercase</b> module name with SWIG's <tt>%module</tt> directive. SWIG will automatically correct the resulting Ruby module name for your extension. So for example, a SWIG interface file that begins with: -<pre><blockquote>%module example<br></blockquote></pre> +<blockquote><pre>%module example<br></pre></blockquote> will result in an extension module using the feature name "example" and Ruby module name "Example". -<a name="n7"></a> -<a name="n7"></a><H3>23.1.5 Static linking</H3> +<H3><a name="Ruby_nn7"></a>26.1.5 Static linking</H3> An alternative approach to dynamic linking is to rebuild the Ruby @@ -243,14 +241,14 @@ adding your directory to the list of extensions in the file, and finally rebuilding Ruby. </p> <p><a name="n8"></a></p> -<a name="n8"></a><H3>23.1.6 Compilation of C++ extensions</H3> +<H3><a name="Ruby_nn8"></a>26.1.6 Compilation of C++ extensions</H3> <p> On most machines, C++ extension modules should be linked using the C++ compiler. For example: </p> -<p></p> + <blockquote> <pre>$ <b>swig -c++ -ruby example.i</b> $ <b>g++ -c example.cxx</b> @@ -276,8 +274,7 @@ into your extension, e.g. <pre>require 'mkmf'<br>$libs = append_library($libs, "supc++")<br>create_makefile('example')<br></pre> </blockquote> <hr> -<a name="n9"></a> -<a name="n9"></a><H2>23.2 Building Ruby Extensions under Windows 95/NT</H2> +<H2><a name="Ruby_nn9"></a>26.2 Building Ruby Extensions under Windows 95/NT</H2> Building a SWIG extension to Ruby under Windows 95/NT is roughly @@ -306,7 +303,7 @@ you may need to download the source distribution to the Ruby package, as you will need the Ruby header files. <p><a name="n10"></a></p> -<a name="n10"></a><H3>23.2.1 Running SWIG from Developer Studio</H3> +<H3><a name="Ruby_nn10"></a>26.2.1 Running SWIG from Developer Studio</H3> If you are developing your application within Microsoft developer @@ -314,8 +311,7 @@ studio, SWIG can be invoked as a custom build option. The process roughly follows these steps : -<p></p> -<p></p> + <ul> <li>Open up a new workspace and use the AppWizard to select a DLL project. @@ -381,8 +377,7 @@ run your new Ruby extension, simply run Ruby and use the <tt>require</tt> command as normal. For example if you have this ruby file run.rb:</p> -<p></p> -<p></p> + <blockquote> <pre># file: run.rb<br>require 'Example'<br><br># Call a c function<br>print "Foo = ", Example.Foo, "\n"<br></pre> </blockquote> @@ -394,17 +389,15 @@ Ruby script from the DOS/Command prompt: Foo = 3.0 </pre> </blockquote> -<p> -</p> + <hr><a name="n11"></a> -<a name="n11"></a><H2>23.3 The Ruby-to-C/C++ Mapping</H2> +<H2><a name="Ruby_nn11"></a>26.3 The Ruby-to-C/C++ Mapping</H2> This section describes the basics of how SWIG maps C or C++ declarations in your SWIG interface files to Ruby constructs. -<a name="n12"></a> -<a name="n12"></a><H3>23.3.1 Modules</H3> +<H3><a name="Ruby_nn12"></a>26.3.1 Modules</H3> The SWIG <tt>%module</tt> directive specifies the name of the Ruby @@ -463,13 +456,13 @@ global module, take care that the names of your constants, classes and methods don't conflict with any of Ruby's built-in names. -<a name="n13"></a></p> -<a name="n13"></a><H3>23.3.2 Functions</H3> + +<H3><a name="Ruby_nn13"></a>26.3.2 Functions</H3> Global functions are wrapped as Ruby module methods. For example, given the SWIG interface file <tt>example.i</tt>: -<p></p> + <blockquote> <pre>%module example<br><br>int fact(int n);<br></pre> </blockquote> @@ -480,7 +473,7 @@ and C source file <tt>example.c</tt>: SWIG will generate a method <i>fact</i> in the <i>Example</i> module that can be used like so: -<p></p> + <blockquote> <pre>$ <b>irb</b> irb(main):001:0> <b>require 'example'</b> @@ -489,8 +482,7 @@ irb(main):002:0> <b>Example.fact(4)</b> 24 </pre> </blockquote> -<a name="n14"></a> -<a name="n14"></a><H3>23.3.3 Variable Linking</H3> +<H3><a name="Ruby_nn14"></a>26.3.3 Variable Linking</H3> C/C++ global variables are wrapped as a pair of singleton methods for @@ -504,8 +496,7 @@ variables: </blockquote> <p> Now look at the Ruby interface:</p> -<p></p> -<p></p> + <blockquote> <pre>$ <b>irb</b> irb(main):001:0> <b>require 'Example'</b> @@ -543,8 +534,7 @@ directive. For example: The <tt>%immutable</tt> directive stays in effect until it is explicitly disabled using <tt>%mutable</tt>. -<a name="n15"></a> -<a name="n15"></a><H3>23.3.4 Constants</H3> +<H3><a name="Ruby_nn15"></a>26.3.4 Constants</H3> C/C++ constants are wrapped as module constants initialized to the @@ -555,7 +545,7 @@ appropriate value. To create a constant, use <tt>#define</tt> or the </blockquote> Remember to use the :: operator in Ruby to get at these constant values, e.g. -<p></p> + <blockquote> <pre>$ <b>irb</b> irb(main):001:0> <b>require 'Example'</b> @@ -564,8 +554,7 @@ irb(main):002:0> <b>Example::PI</b> 3.14159 </pre> </blockquote> -<a name="n16"></a> -<a name="n16"></a><H3>23.3.5 Pointers</H3> +<H3><a name="Ruby_nn16"></a>26.3.5 Pointers</H3> "Opaque" pointers to arbitrary C/C++ types (i.e. types that aren't @@ -574,7 +563,7 @@ declared in your SWIG interface file) are wrapped as data objects. So, for example, consider a SWIG interface file containing only the declarations: -<p></p> + <blockquote> <pre>Foo *get_foo();<br>void set_foo(Foo *foo);<br></pre> </blockquote> @@ -587,15 +576,14 @@ internally generated Ruby class: </blockquote> A <tt>NULL</tt> pointer is always represented by the Ruby <tt>nil</tt> object. -<a name="n17"></a> -<a name="n17"></a><H3>23.3.6 Structures</H3> +<H3><a name="Ruby_nn17"></a>26.3.6 Structures</H3> C/C++ structs are wrapped as Ruby classes, with accessor methods (i.e. "getters" and "setters") for all of the struct members. For example, this struct declaration: -<p></p> + <blockquote> <pre>struct Vector {<br> double x, y;<br>};<br></pre> </blockquote> @@ -603,7 +591,7 @@ gets wrapped as a <tt>Vector</tt> class, with Ruby instance methods <tt>x</tt>, <tt>x=</tt>, <tt>y</tt> and <tt>y=</tt>. These methods can be used to access structure data from Ruby as follows: -<p></p> + <blockquote> <pre>$ <b>irb</b> irb(main):001:0> <b>require 'Example'</b> @@ -620,7 +608,7 @@ irb(main):004:0> <b>f.x</b> Similar access is provided for unions and the public data members of C++ classes.</p> -<p></p> + <p><tt>const</tt> members of a structure are read-only. Data members can also be forced to be read-only using the <tt>%immutable</tt> directive (in @@ -654,7 +642,7 @@ produces a single accessor function like this: </blockquote> If you want to set an array member, you will need to supply a "memberin" -typemap described in the <a href="#n24">section on typemaps</a>. As a +typemap described in the <a href="#ruby_cpp_smart_pointers">section on typemaps</a>. As a special case, SWIG does generate code to set array members of type <tt>char</tt> (allowing you to store a Ruby string in the structure). @@ -668,8 +656,7 @@ generates accessor functions such as this: <blockquote> <pre>Foo *Bar_f_get(Bar *b) {<br> return &b->f;<br>}<br><br>void Bar_f_set(Bar *b, Foo *val) {<br> b->f = *val;<br>}<br></pre> </blockquote> -<a name="n18"></a> -<a name="n18"></a><H3>23.3.7 C++ classes</H3> +<H3><a name="Ruby_nn18"></a>26.3.7 C++ classes</H3> Like structs, C++ classes are wrapped by creating a new Ruby class of @@ -681,8 +668,8 @@ methods, and public static member functions are wrapped as Ruby singleton methods. So, given the C++ class declaration: -<p></p> -<p></p> + + <blockquote> <pre>class List {<br>public:<br> List();<br> ~List();<br> int search(char *item);<br> void insert(char *item);<br> void remove(char *item);<br> char *get(int n);<br> int length;<br> static void print(List *l);<br>};<br></pre> </blockquote> @@ -705,8 +692,7 @@ In Ruby, these functions are used as follows: <blockquote> <pre>require 'Example'<br><br>l = Example::List.new<br><br>l.insert("Ale")<br>l.insert("Stout")<br>l.insert("Lager")<br>Example.print(l)<br>l.length()<br>----- produces the following output <br>Lager<br>Stout<br>Ale<br>3<br></pre> </blockquote> -<a name="n19"></a> -<a name="n19"></a><H3>23.3.8 C++ Inheritance</H3> +<H3><a name="Ruby_nn19"></a>26.3.8 C++ Inheritance</H3> The SWIG type-checker is fully aware of C++ inheritance. Therefore, if @@ -822,8 +808,7 @@ will otherwise behave as though they inherit from both <tt>Base1</tt> and <tt>Base2</tt> (i.e. they exhibit <a href="http://c2.com/cgi/wiki?DuckTyping">"Duck Typing"</a>). -<a name="n20"></a> -<a name="n20"></a><H3>23.3.9 C++ Overloaded Functions</H3> +<H3><a name="Ruby_nn20"></a>26.3.9 C++ Overloaded Functions</H3> C++ overloaded functions, methods, and constructors are mostly @@ -878,9 +863,9 @@ which declarations appear in the input does not matter except in situations where ambiguity arises--in this case, the first declaration takes precedence. -<p>Please refer to the <a href="SWIGPlus.html">"SWIG and C++"</a> +<p>Please refer to the <a href="SWIGPlus.html#SWIGPlus">"SWIG and C++"</a> chapter for more information about overloading. <a name="n21"></a></p> -<a name="n21"></a><H3>23.3.10 C++ Operators</H3> +<H3><a name="Ruby_nn21"></a>26.3.10 C++ Operators</H3> For the most part, overloaded operators are handled automatically by @@ -909,9 +894,8 @@ Now, in Ruby, you can do this: </blockquote> More details about wrapping C++ operators into Ruby operators is discussed in -the <a href="#n39">section on operator overloading</a>. -<a name="n22"></a> -<a name="n22"></a><H3>23.3.11 C++ namespaces</H3> +the <a href="#ruby_operator_overloading">section on operator overloading</a>. +<H3><a name="Ruby_nn22"></a>26.3.11 C++ namespaces</H3> SWIG is aware of C++ namespaces, but namespace names do not appear in @@ -946,8 +930,7 @@ For example, make the module name the same as the namespace and create extension modules for each namespace separately. If your program utilizes thousands of small deeply nested namespaces each with identical symbol names, well, then you get what you deserve. -<a name="n23"></a> -<a name="n23"></a><H3>23.3.12 C++ templates</H3> +<H3><a name="Ruby_nn23"></a>26.3.12 C++ templates</H3> C++ templates don't present a huge problem for SWIG. However, in order @@ -1000,10 +983,9 @@ float sum(const std::vector<float>& values); </blockquote> Obviously, there is a lot more to template wrapping than shown in these examples. -More details can be found in the <a href="SWIGPlus.html">SWIG and C++</a> +More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter. -<a name="n24"></a> -<a name="n24"></a><H3>23.3.13 C++ Smart Pointers</H3> +<H3><a name="ruby_cpp_smart_pointers"></a>26.3.13 C++ Smart Pointers</H3> In certain C++ programs, it is common to use classes that have been @@ -1040,21 +1022,19 @@ simply use the <tt>__deref__()</tt> method. For example: <blockquote> <pre>irb(main):004:0> <b>f = p.__deref__()</b> # Returns underlying Foo *<br></pre> </blockquote> -<a name="n25"></a> -<a name="n25"></a><H3>23.3.14 Cross-Language Polymorphism</H3> +<H3><a name="Ruby_nn25"></a>26.3.14 Cross-Language Polymorphism</H3> SWIG's Ruby module supports cross-language polymorphism (a.k.a. the "directors" feature) similar to that for SWIG's Python module. Rather than duplicate the -information presented in the <a href="Python.html">Python</a> chapter, +information presented in the <a href="Python.html#Python">Python</a> chapter, this secton just notes the differences that you need to be aware of when using this feature with Ruby. -<a name="n26"></a> -<a name="n26"></a><H4>23.3.14.1 Exception Unrolling</H4> +<H4><a name="Ruby_nn26"></a>26.3.14.1 Exception Unrolling</H4> Whenever a C++ director class routes one of its virtual member function @@ -1079,7 +1059,7 @@ Ruby exception is raised, it will be caught here and a C++ exception is raised in its place. <hr><a name="n27"></a> -<a name="n27"></a><H2>23.4 Input and output parameters</H2> +<H2><a name="Ruby_nn27"></a>26.4 Input and output parameters</H2> A common problem in some C programs is handling parameters passed as @@ -1154,18 +1134,17 @@ In Ruby: <pre>r, c = Example.get_dimensions(m)<br></pre> </blockquote> <hr> -<a name="n28"></a> -<a name="n28"></a><H2>23.5 Simple exception handling </H2> +<H2><a name="Ruby_nn28"></a>26.5 Simple exception handling </H2> The SWIG <tt>%exception</tt> directive can be used to define a user-definable exception handler that can convert C/C++ errors into Ruby exceptions. The -chapter on <a href="Customization.html">Customization Features</a> +chapter on <a href="Customization.html#Customization">Customization Features</a> contains more details, but suppose you have a C++ class like the following : -<p></p> + <blockquote> <pre>class DoubleArray {<br> private:<br> int n;<br> double *ptr;<br> public:<br> // Create a new array of fixed size<br> DoubleArray(int size) {<br> ptr = new double[size];<br> n = size;<br> }<br> // Destroy an array<br> ~DoubleArray() {<br> delete ptr;<br> }<br> // Return the length of the array<br> int length() {<br> return n;<br> }<br><br> // Get an array item and perform bounds checking.<br> double getitem(int i) {<br> if ((i >= 0) && (i < n))<br> return ptr[i];<br> else<br> throw RangeError();<br> }<br> // Set an array item and perform bounds checking.<br> void setitem(int i, double val) {<br> if ((i >= 0) && (i < n))<br> ptr[i] = val;<br> else {<br> throw RangeError();<br> }<br> }<br> };<br></pre> </blockquote> @@ -1174,7 +1153,7 @@ out-of-bounds access, you might want to catch this in the Ruby extension by writing the following in an interface file: -<p></p> + <blockquote> <pre>%exception {<br> try {<br> $action<br> }<br> catch (const RangeError&) {<br> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);<br> rb_raise(cpperror, "Range error.");<br> }<br>}<br><br>class DoubleArray {<br> ...<br>};<br></pre> </blockquote> @@ -1196,7 +1175,7 @@ functions named <tt>getitem</tt> and <tt>setitem</tt>. <p>Since SWIG's exception handling is user-definable, you are not limited to C++ -exception handling. See the chapter on <a href="Customization.html">Customization +exception handling. See the chapter on <a href="Customization.html#Customization">Customization Features</a> for more examples. </p> <p>When raising a Ruby exception from C/C++, use the <tt>rb_raise()</tt> @@ -1210,7 +1189,7 @@ Ruby exception classes, consult a Ruby reference such as <a href="http://www.rubycentral.com/book"><em>Programming Ruby</em></a>. </p> <hr><a name="n29"></a> -<a name="n29"></a><H2>23.6 Typemaps</H2> +<H2><a name="Ruby_nn29"></a>26.6 Typemaps</H2> This section describes how you can modify SWIG's default wrapping @@ -1219,22 +1198,22 @@ for various C/C++ datatypes using the <tt>%typemap</tt> directive. This is an advanced topic that assumes familiarity with the Ruby C API as well -as the material in the "<a href="Typemaps.html">Typemaps</a>" chapter. +as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. <p>Before proceeding, it should be stressed that typemaps are not a required part of using SWIG---the default wrapping behavior is enough in most cases. Typemaps are only used if you want to change some aspect of the primitive C-Ruby interface. -<a name="n30"></a></p> -<a name="n30"></a><H3>23.6.1 What is a typemap?</H3> + +<H3><a name="Ruby_nn30"></a>26.6.1 What is a typemap?</H3> A typemap is nothing more than a code generation rule that is attached to a specific C datatype. For example, to convert integers from Ruby to C, you might define a typemap like this: -<p></p> + <blockquote> <pre>%module example<br><br>%typemap(in) int {<br> $1 = (int) NUM2INT($input);<br> printf("Received an integer : %d\n",$1);<br>}<br><br>extern int fact(int n);<br></pre> </blockquote> @@ -1254,7 +1233,7 @@ The <tt>$input</tt> variable is the input Ruby object. <p>When this example is compiled into a Ruby module, the following sample code: </p> -<p></p> + <blockquote> <pre>require 'example'<br><br>puts Example.fact(6)<br></pre> </blockquote> @@ -1308,8 +1287,7 @@ follows (notice how the length parameter is omitted): <blockquote> <pre>puts Example.count('o','Hello World')<br>2<br></pre> </blockquote> -<a name="n31"></a> -<a name="n31"></a><H3>23.6.2 Ruby typemaps</H3> +<H3><a name="Ruby_nn31"></a>26.6.2 Ruby typemaps</H3> The previous section illustrated an "in" typemap for converting Ruby @@ -1363,16 +1341,15 @@ Ruby module: <blockquote>Initialize an argument to a value before any conversions occur. </blockquote> -Examples of these typemaps appears in the <a href="#n34">section on +Examples of these typemaps appears in the <a href="#ruby_typemap_examples">section on typemap examples</a> -<a name="n32"></a> -<a name="n32"></a><H3>23.6.3 Typemap variables</H3> +<H3><a name="Ruby_nn32"></a>26.6.3 Typemap variables</H3> Within a typemap, a number of special variables prefaced with a <tt>$</tt> may appear. A full list of variables can be found in the "<a - href="Typemaps.html">Typemaps</a>" chapter. This is a list of the most + href="Typemaps.html#Typemaps">Typemaps</a>" chapter. This is a list of the most common variables: <p><tt>$1</tt> @@ -1410,8 +1387,7 @@ so that their values can be properly assigned. <tt>$symname</tt> <blockquote>The Ruby name of the wrapper function being created. </blockquote> -<a name="n33"></a> -<a name="n33"></a><H3>23.6.4 Useful Functions</H3> +<H3><a name="Ruby_nn33"></a>26.6.4 Useful Functions</H3> When you write a typemap, you usually have to work directly with Ruby @@ -1422,21 +1398,19 @@ more can be found in <a href="http://www.rubycentral.com/book"><em>Programming Ruby</em></a>, by David Thomas and Andrew Hunt.) <p><a name="n34"></a></p> -<a name="n34"></a><H4>23.6.4.1 C Datatypes to Ruby Objects</H4> +<H4><a name="Ruby_nn34"></a>26.6.4.1 C Datatypes to Ruby Objects</H4> <blockquote> <pre>INT2NUM(long or int) - int to Fixnum or Bignum<br>INT2FIX(long or int) - int to Fixnum (faster than INT2NUM)<br>CHR2FIX(char) - char to Fixnum<br>rb_str_new2(char*) - char* to String<br>rb_float_new(double) - double to Float<br></pre> </blockquote> -<a name="n35"></a> -<a name="n35"></a><H4>23.6.4.2 Ruby Objects to C Datatypes</H4> +<H4><a name="Ruby_nn35"></a>26.6.4.2 Ruby Objects to C Datatypes</H4> <blockquote> <pre> int NUM2INT(Numeric)<br> int FIX2INT(Numeric)<br> unsigned int NUM2UINT(Numeric)<br> unsigned int FIX2UINT(Numeric)<br> long NUM2LONG(Numeric)<br> long FIX2LONG(Numeric)<br>unsigned long FIX2ULONG(Numeric)<br> char NUM2CHR(Numeric or String)<br> char * STR2CSTR(String)<br> char * rb_str2cstr(String, int*length)<br> double NUM2DBL(Numeric)<br><br></pre> </blockquote> -<a name="n36"></a> -<a name="n36"></a><H4>23.6.4.3 Macros for VALUE</H4> +<H4><a name="Ruby_nn36"></a>26.6.4.3 Macros for VALUE</H4> <p> @@ -1451,8 +1425,7 @@ and Andrew Hunt.) <blockquote>capacity of the Ruby array</blockquote> <tt>RARRAY(arr)->ptr</tt> <blockquote>pointer to array storage</blockquote> -<a name="n37"></a> -<a name="n37"></a><H4>23.6.4.4 Exceptions</H4> +<H4><a name="Ruby_nn37"></a>26.6.4.4 Exceptions</H4> <p> @@ -1510,8 +1483,7 @@ interpreted as with <tt>printf()</tt>. if Ruby was invoked with the <tt>-w</tt> flag. The given format string <i>fmt</i> and remaining arguments are interpreted as with <tt>printf()</tt>. </blockquote> -<a name="n38"></a> -<a name="n38"></a><H4>23.6.4.5 Iterators</H4> +<H4><a name="Ruby_nn38"></a>26.6.4.5 Iterators</H4> <p> @@ -1544,15 +1516,13 @@ value)</tt> <tt>void rb_throw(const char *tag, VALUE value)</tt> <blockquote> Equivalent to Ruby's <tt>throw</tt>. </blockquote> -<a name="n39"></a> -<a name="n39"></a><H3>23.6.5 Typemap Examples</H3> +<H3><a name="ruby_typemap_examples"></a>26.6.5 Typemap Examples</H3> This section includes a few examples of typemaps. For more examples, you might look at the examples in the <tt>Example/ruby</tt> directory. -<a name="n40"></a> -<a name="n40"></a><H3>23.6.6 Converting a Ruby array to a char **</H3> +<H3><a name="Ruby_nn40"></a>26.6.6 Converting a Ruby array to a char **</H3> A common problem in many C programs is the processing of command line @@ -1560,15 +1530,15 @@ arguments, which are usually passed in an array of <tt>NULL</tt> terminated strings. The following SWIG interface file allows a Ruby Array instance to be used as a <tt>char **</tt> object. -<p></p> -<p></p> + + <blockquote> <pre>%module argv<br><br>// This tells SWIG to treat char ** as a special case<br>%typemap(in) char ** {<br> /* Get the length of the array */<br> int size = RARRAY($input)->len; <br> int i;<br> $1 = (char **) malloc((size+1)*sizeof(char *));<br> /* Get the first element in memory */<br> VALUE *ptr = RARRAY($input)->ptr; <br> for (i=0; i < size; i++, ptr++)<br> /* Convert Ruby Object String to char* */<br> $1[i]= STR2CSTR(*ptr); <br> $1[i]=NULL; /* End of list */<br>}<br><br>// This cleans up the char ** array created before <br>// the function call<br><br>%typemap(freearg) char ** {<br> free((char *) $1);<br>}<br><br>// Now a test function<br>%inline %{<br>int print_args(char **argv) {<br> int i = 0;<br> while (argv[i]) {<br> printf("argv[%d] = %s\n", i,argv[i]);<br> i++;<br> }<br> return i;<br>}<br>%}<br><br></pre> </blockquote> When this module is compiled, the wrapped C function now operates as follows : -<p></p> -<p></p> + + <blockquote> <pre>require 'Argv'<br>Argv.print_args(["Dave","Mike","Mary","Jane","John"])<br>argv[0] = Dave<br>argv[1] = Mike<br>argv[2] = Mary<br>argv[3] = Jane<br>argv[4] = John<br></pre> </blockquote> @@ -1580,7 +1550,7 @@ allocation is used to allocate memory for the array, the "freearg" typemap is used to later release this memory after the execution of the C function. <a name="n41"></a> -<a name="n41"></a><H3>23.6.7 Collecting arguments in a hash</H3> +<H3><a name="Ruby_nn41"></a>26.6.7 Collecting arguments in a hash</H3> Ruby's solution to the "keyword arguments" capability of some other @@ -1736,8 +1706,7 @@ uses the extension, can be found in the <tt>Examples/ruby/hashargs</tt> directory of the SWIG distribution. -<a name="n42"></a> -<a name="n42"></a><H3>23.6.8 Pointer handling</H3> +<H3><a name="Ruby_nn42"></a>26.6.8 Pointer handling</H3> Occasionally, it might be necessary to convert pointer values that have @@ -1797,8 +1766,7 @@ typemap variable <tt>$1_descriptor</tt>. For example: <blockquote> <pre>%typemap(in) Foo * {<br> SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor, 1);<br>}<br></pre> </blockquote> -<a name="n43"></a> -<a name="n43"></a><H4>23.6.8.1 Ruby Datatype Wrapping</H4> +<H4><a name="Ruby_nn43"></a>26.6.8.1 Ruby Datatype Wrapping</H4> <p> @@ -1822,8 +1790,7 @@ from the data object <i>obj</i> and assigns that pointer to <i>ptr</i>. </blockquote> <hr> -<a name="n44"></a> -<a name="n44"></a><H2>23.7 Operator overloading</H2> +<H2><a name="ruby_operator_overloading"></a>26.7 Operator overloading</H2> SWIG allows operator overloading with, by using the <tt>%extend</tt> @@ -1838,8 +1805,7 @@ Note that although SWIG supports the <tt>__eq__</tt> magic method name for defining an equivalence operator, there is no separate method for handling <i>inequality</i> since Ruby parses the expression <i>a != b</i> as <i>!(a == b)</i>. -<a name="n45"></a> -<a name="n45"></a><H3>23.7.1 Example: STL Vector to Ruby Array</H3> +<H3><a name="Ruby_nn45"></a>26.7.1 Example: STL Vector to Ruby Array</H3> <em><b>FIXME: This example is out of place here!</b></em> @@ -1855,7 +1821,7 @@ construct this type of macro/typemap and should give insight into constructing similar typemaps for other STL structures: </p> -<p></p> + <blockquote> <pre>%define PTR_VECTOR_TO_RUBY_ARRAY(vectorclassname, classname)<br>%typemap(ruby, out) vectorclassname &, const vectorclassname & {<br> VALUE arr = rb_ary_new2($1->size());<br> vectorclassname::iterator i = $1->begin(), iend = $1->end();<br> for ( ; i!=iend; i++ )<br> rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));<br> $result = arr;<br>}<br>%typemap(ruby, out) vectorclassname, const vectorclassname {<br> VALUE arr = rb_ary_new2($1.size());<br> vectorclassname::iterator i = $1.begin(), iend = $1.end();<br> for ( ; i!=iend; i++ )<br> rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));<br> $result = arr;<br>}<br>%enddef<br></pre> </blockquote> @@ -1864,19 +1830,20 @@ preprocessor step to determine the actual object from the class name. <p>To use the macro with a class Foo, the following is used: </p> -<p></p> + <blockquote> - <pre>PTR_VECTOR_TO_RUBY_ARRAY(vector<foo *="">, Foo)<br></foo></pre> + <pre>PTR_VECTOR_TO_RUBY_ARRAY(vector<foo *="">, Foo)<br></pre> </blockquote> It is also possible to create a STL vector of Ruby objects: -<p></p> + <blockquote> <pre>%define RUBY_ARRAY_TO_PTR_VECTOR(vectorclassname, classname)<br>%typemap(ruby, in) vectorclassname &, const vectorclassname & {<br> Check_Type($input, T_ARRAY);<br> vectorclassname *vec = new vectorclassname;<br> int len = RARRAY($input)->len;<br> for (int i=0; i!=len; i++) {<br> VALUE inst = rb_ary_entry($input, i);<br> //The following _should_ work but doesn't on HPUX<br> // Check_Type(inst, T_DATA);<br> classname *element = NULL;<br> Data_Get_Struct(inst, classname, element);<br> vec->push_back(element);<br> }<br> $1 = vec;<br>}<br><br>%typemap(ruby, freearg) vectorclassname &, const vectorclassname & {<br> delete $1;<br>}<br>%enddef<br></pre> </blockquote> + It is also possible to create a Ruby array from a vector of static data types: -<p></p> -<pre><blockquote> + +<blockquote><pre> %define VECTOR_TO_RUBY_ARRAY(vectorclassname, classname) %typemap(ruby, out) vectorclassname &, const vectorclassname & { VALUE arr = rb_ary_new2($1->size()); @@ -1893,16 +1860,14 @@ types: $result = arr; } %enddef -</blockquote></pre> -<a name="n46"></a> -<a name="n46"></a><H2>23.8 Advanced Topics</H2> +</pre></blockquote> +<H2><a name="Ruby_nn46"></a>26.8 Advanced Topics</H2> -<a name="n47"></a> -<a name="n47"></a><H3>23.8.1 Creating Multi-Module Packages</H3> +<H3><a name="Ruby_nn47"></a>26.8.1 Creating Multi-Module Packages</H3> -The chapter on <a href="Advanced.html">Advanced Topics</a> discusses +The chapter on <a href="Advanced.html#Advanced">Advanced Topics</a> discusses the basics of creating multi-module extensions with SWIG, and in particular the considerations for sharing runtime type information among the @@ -1924,7 +1889,7 @@ option so that the runtime library code is omitted from the wrapper files. We'll start by building the <b>Shape</b> extension module: -<p></p> + <blockquote> <pre>$ <b>swig -c++ -ruby -c shape.i</b> </pre> @@ -1933,14 +1898,14 @@ SWIG generates a wrapper file named <tt>shape_wrap.cxx</tt>. To compile this into a dynamically loadable extension for Ruby, prepare an <tt>extconf.rb</tt> script using this template: -<p></p> + <blockquote> <pre>require 'mkmf'<br><br># Since the SWIG runtime support library for Ruby (libswigrb.so)<br># depends on the Ruby library, make sure it's in the list<br># of libraries.<br>$libs = append_library($libs, Config::CONFIG['RUBY_INSTALL_NAME'])<br><br># Now add the SWIG runtime support library<br>have_library('swigrb', 'SWIG_InitRuntime')<br><br># Create the makefile<br>create_makefile('shape')<br></pre> </blockquote> Run this script to create a <tt>Makefile</tt> and then type <tt>make</tt> to build the shared library: -<p></p> + <blockquote> <pre>$ <b>ruby extconf.rb</b> checking for SWIG_InitRuntime() in -lswigrb... yes @@ -1974,7 +1939,7 @@ to create a platform-specific <tt>Makefile</tt> for the extension; Once you've built both of these extension modules, you can test them interactively in IRB to confirm that the <tt>Shape</tt> and <tt>Circle</tt> modules are properly loaded and initialized: -<p></p> + <blockquote> <pre>$ <b>irb</b> irb(main):001:0> <b>require 'shape'</b> @@ -1989,8 +1954,7 @@ irb(main):005:0> <b>c.getX()</b> 5.0 </pre> </blockquote> -<a name="n48"></a> -<a name="n48"></a><H3>23.8.2 Defining Aliases</H3> +<H3><a name="Ruby_nn48"></a>26.8.2 Defining Aliases</H3> It's a fairly common practice in the Ruby built-ins and standard @@ -2002,14 +1966,14 @@ one of your class' instance methods, one approach is to use SWIG's <tt>%extend</tt> directive to add a new method of the aliased name that calls the original function. For example: -<p></p> + <blockquote> <pre>class MyArray {<br>public:<br> // Construct an empty array<br> MyArray();<br> <br> // Return the size of this array<br> size_t length() const;<br>};<br><br>%extend MyArray {<br> // MyArray#size is an alias for MyArray#length<br> size_t size() const {<br> return self->length();<br> }<br>}<br></pre> </blockquote> A better solution is to instead use the <tt>%alias</tt> directive (unique to SWIG's Ruby module). The previous example could then be rewritten as: -<p></p> + <blockquote> <pre>// MyArray#size is an alias for MyArray#length<br>%alias MyArray::length "size";<br><br>class MyArray {<br>public:<br> // Construct an empty array<br> MyArray();<br> <br> // Return the size of this array<br> size_t length() const;<br>};<br></pre> </blockquote> @@ -2032,11 +1996,11 @@ wrapper code that's usually associated with added methods like our "features" mechanism and so the same name matching rules used for other kinds of features -apply (see the chapter on <a href="Customization.html">"Customization +apply (see the chapter on <a href="Customization.html#Customization">"Customization Features"</a>) for more details). -<a name="n49"></a></p> -<a name="n49"></a><H3>23.8.3 Predicate Methods</H3> + +<H3><a name="Ruby_nn49"></a>26.8.3 Predicate Methods</H3> Predicate methods in Ruby are those which return either <tt>true</tt> @@ -2068,7 +2032,7 @@ A better solution is to instead use the <tt>%predicate</tt> directive to SWIG's Ruby module) to designate certain methods as predicate methods. For the previous example, this would look like: -<p></p> + <blockquote> <pre>%predicate is_it_safe();<br><br>int is_it_safe();<br></pre> </blockquote> @@ -2082,10 +2046,9 @@ Note that the <tt>%predicate</tt> directive is implemented using SWIG's "features" mechanism and so the same name matching rules used for other kinds -of features apply (see the chapter on <a href="Customization.html">"Customization +of features apply (see the chapter on <a href="Customization.html#Customization">"Customization Features"</a>) for more details). -<a name="n50"></a> -<a name="n50"></a><H3>23.8.4 Specifying Mixin Modules</H3> +<H3><a name="Ruby_nn50"></a>26.8.4 Specifying Mixin Modules</H3> The Ruby language doesn't support multiple inheritance, but it does @@ -2095,14 +2058,14 @@ method. For example, if you have a Ruby class that defines an <em>each</em> instance method, e.g. -<p></p> + <blockquote> <pre>class Set<br> def initialize<br> @members = []<br> end<br> <br> def each<br> @members.each { |m| yield m }<br> end<br>end<br></pre> </blockquote> then you can mix-in Ruby's <tt>Enumerable</tt> module to easily add a lot of functionality to your class: -<p></p> + <blockquote> <pre>class Set<br> <b>include Enumerable</b> @@ -2133,10 +2096,9 @@ module names to the <tt>%mixin</tt> directive, e.g. Note that the <tt>%mixin</tt> directive is implemented using SWIG's "features" mechanism and so the same name matching rules used for other kinds -of features apply (see the chapter on <a href="Customization.html">"Customization +of features apply (see the chapter on <a href="Customization.html#Customization">"Customization Features"</a>) for more details). -<a name="n51"></a> -<a name="n51"></a><H3>23.8.5 Interacting with Ruby's Garbage Collector</H3> +<H3><a name="Ruby_nn51"></a>26.8.5 Interacting with Ruby's Garbage Collector</H3> <b>This section is still unfinished!</b> @@ -2163,8 +2125,8 @@ models a zoo and the animals in the zoo: </p> <blockquote> - <pre>%module zoo<br><br>%{<br>#include <string> -#include <vector> + <pre>%module zoo<br><br>%{<br>#include <string> +#include <vector> #include "zoo.h" %} @@ -2185,8 +2147,7 @@ public: class Zoo { protected: - std::vector<animal - *=""> animals;<br> <br>public:<br> // Construct an empty zoo<br> Zoo() {}<br> <br> // Add a new animal to the zoo<br> void addAnimal(Animal* animal) {<br> animals.push_back(animal); <br> }<br> <br> // Return the number of animals in the zoo<br> size_t getNumAnimals() const {<br> return animals.size(); <br> }<br> <br> // Return a pointer to the ith animal<br> Animal* getAnimal(size_t i) const {<br> return animals[i]; <br> }<br>};<br><br></animal></vector></string></pre> + std::vector<animal *=""> animals;<br> <br>public:<br> // Construct an empty zoo<br> Zoo() {}<br> <br> // Add a new animal to the zoo<br> void addAnimal(Animal* animal) {<br> animals.push_back(animal); <br> }<br> <br> // Return the number of animals in the zoo<br> size_t getNumAnimals() const {<br> return animals.size(); <br> }<br> <br> // Return a pointer to the ith animal<br> Animal* getAnimal(size_t i) const {<br> return animals[i]; <br> }<br>};<br><br></pre> </blockquote> Basically, a <tt>Zoo</tt> is modeled as a "container" for animals. And we can @@ -2247,8 +2208,8 @@ of the Ruby instances associated with those C++ <tt>Animal</tt> objects: </p> <blockquote> - <pre>void Zoo_markfunc(void *ptr)<br>{<br> Animal *cppAnimal;<br> VALUE rubyAnimal;<br> Zoo *zoo;<br> <br> zoo = static_cast<zoo - *="">(ptr);<br> for (size_t i = 0; i < zoo->getNumAnimals(); i++) {<br> cppAnimal = zoo->getAnimal(i);<br> rubyAnimal = SWIG_RubyInstanceFor(cppAnimal);<br> rb_gc_mark(rubyAnimal);<br> }<br>}<br></zoo></pre> + <pre>void Zoo_markfunc(void *ptr)<br>{<br> Animal *cppAnimal;<br> VALUE rubyAnimal;<br> Zoo *zoo;<br> <br> zoo = static_cast<zoo + *="">(ptr);<br> for (size_t i = 0; i < zoo->getNumAnimals(); i++) {<br> cppAnimal = zoo->getAnimal(i);<br> rubyAnimal = SWIG_RubyInstanceFor(cppAnimal);<br> rb_gc_mark(rubyAnimal);<br> }<br>}<br></pre> </blockquote> <em>SWIG_RubyInstanceFor() is an imaginary function that takes a pointer @@ -2269,7 +2230,7 @@ are implemented using SWIG's' "features" mechanism and so the same name matching rules used for other kinds of features apply (see the chapter on -<a href="Customization.html">"Customization Features"</a>) +<a href="Customization.html#Customization">"Customization Features"</a>) for more details). <hr> <address>SWIG 1.3 - Last Modified : $Date$</address> diff --git a/Doc/Manual/SWIG.html b/Doc/Manual/SWIG.html index 3f12dc90a..619cf1ce8 100644 --- a/Doc/Manual/SWIG.html +++ b/Doc/Manual/SWIG.html @@ -5,71 +5,71 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>4 SWIG Basics</H1> +<H1><a name="SWIG"></a>5 SWIG Basics</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Running SWIG</a> +<li><a href="#SWIG_nn2">Running SWIG</a> <ul> -<li><a href="#n3">Input format</a> -<li><a href="#n4">SWIG Output</a> -<li><a href="#n5">Comments</a> -<li><a href="#n6">C Preprocessor</a> -<li><a href="#n7">SWIG Directives</a> -<li><a href="#n8">Parser Limitations</a> +<li><a href="#SWIG_nn3">Input format</a> +<li><a href="#output">SWIG Output</a> +<li><a href="#SWIG_nn5">Comments</a> +<li><a href="#SWIG_nn6">C Preprocessor</a> +<li><a href="#SWIG_nn7">SWIG Directives</a> +<li><a href="#SWIG_nn8">Parser Limitations</a> </ul> -<li><a href="#n9">Wrapping Simple C Declarations</a> +<li><a href="#SWIG_nn9">Wrapping Simple C Declarations</a> <ul> -<li><a href="#n10">Basic Type Handling</a> -<li><a href="#n11">Global Variables</a> -<li><a href="#n12">Constants</a> -<li><a href="#n13">A brief word about <tt>const</tt></a> -<li><a href="#n14">A cautionary tale of <tt>char *</tt></a> +<li><a href="#SWIG_nn10">Basic Type Handling</a> +<li><a href="#SWIG_nn11">Global Variables</a> +<li><a href="#SWIG_nn12">Constants</a> +<li><a href="#SWIG_nn13">A brief word about <tt>const</tt></a> +<li><a href="#SWIG_nn14">A cautionary tale of <tt>char *</tt></a> </ul> -<li><a href="#n15">Pointers and complex objects</a> +<li><a href="#SWIG_nn15">Pointers and complex objects</a> <ul> -<li><a href="#n16">Simple pointers</a> -<li><a href="#n17">Run time pointer type checking</a> -<li><a href="#n18">Derived types, structs, and classes</a> -<li><a href="#n19">Undefined datatypes</a> -<li><a href="#n20">Typedef</a> +<li><a href="#SWIG_nn16">Simple pointers</a> +<li><a href="#SWIG_nn17">Run time pointer type checking</a> +<li><a href="#SWIG_nn18">Derived types, structs, and classes</a> +<li><a href="#SWIG_nn19">Undefined datatypes</a> +<li><a href="#SWIG_nn20">Typedef</a> </ul> -<li><a href="#n21">Other Practicalities</a> +<li><a href="#SWIG_nn21">Other Practicalities</a> <ul> -<li><a href="#n22">Passing structures by value</a> -<li><a href="#n23">Return by value</a> -<li><a href="#n24">Linking to structure variables</a> -<li><a href="#n25">Linking to <tt>char *</tt></a> -<li><a href="#n26">Arrays</a> -<li><a href="#n27">Creating read-only variables</a> -<li><a href="#n28">Renaming and ignoring declarations</a> -<li><a href="#n29">Default/optional arguments</a> -<li><a href="#n30">Pointers to functions and callbacks</a> +<li><a href="#SWIG_nn22">Passing structures by value</a> +<li><a href="#SWIG_nn23">Return by value</a> +<li><a href="#SWIG_nn24">Linking to structure variables</a> +<li><a href="#SWIG_nn25">Linking to <tt>char *</tt></a> +<li><a href="#SWIG_nn26">Arrays</a> +<li><a href="#SWIG_nn27">Creating read-only variables</a> +<li><a href="#SWIG_nn28">Renaming and ignoring declarations</a> +<li><a href="#SWIG_nn29">Default/optional arguments</a> +<li><a href="#SWIG_nn30">Pointers to functions and callbacks</a> </ul> -<li><a href="#n31">Structures and unions</a> +<li><a href="#SWIG_nn31">Structures and unions</a> <ul> -<li><a href="#n32">Typedef and structures</a> -<li><a href="#n33">Character strings and structures</a> -<li><a href="#n34">Array members</a> -<li><a href="#n35">Structure data members</a> -<li><a href="#n36">C constructors and destructors </a> -<li><a href="#n37">Adding member functions to C structures</a> -<li><a href="#n38">Nested structures</a> -<li><a href="#n39">Other things to note about structure wrapping</a> +<li><a href="#SWIG_nn32">Typedef and structures</a> +<li><a href="#SWIG_nn33">Character strings and structures</a> +<li><a href="#SWIG_nn34">Array members</a> +<li><a href="#SWIG_nn35">Structure data members</a> +<li><a href="#SWIG_nn36">C constructors and destructors </a> +<li><a href="#SWIG_nn37">Adding member functions to C structures</a> +<li><a href="#SWIG_nn38">Nested structures</a> +<li><a href="#SWIG_nn39">Other things to note about structure wrapping</a> </ul> -<li><a href="#n40">Code Insertion</a> +<li><a href="#SWIG_nn40">Code Insertion</a> <ul> -<li><a href="#n41">The output of SWIG</a> -<li><a href="#n42">Code insertion blocks</a> -<li><a href="#n43">Inlined code blocks</a> -<li><a href="#n44">Initialization blocks</a> +<li><a href="#SWIG_nn41">The output of SWIG</a> +<li><a href="#SWIG_nn42">Code insertion blocks</a> +<li><a href="#SWIG_nn43">Inlined code blocks</a> +<li><a href="#SWIG_nn44">Initialization blocks</a> </ul> -<li><a href="#n45">An Interface Building Strategy</a> +<li><a href="#SWIG_nn45">An Interface Building Strategy</a> <ul> -<li><a href="#n46">Preparing a C program for SWIG</a> -<li><a href="#n47">The SWIG interface file</a> -<li><a href="#n48">Why use separate interface files?</a> -<li><a href="#n49">Getting the right header files</a> -<li><a href="#n50">What to do with main()</a> +<li><a href="#SWIG_nn46">Preparing a C program for SWIG</a> +<li><a href="#SWIG_nn47">The SWIG interface file</a> +<li><a href="#SWIG_nn48">Why use separate interface files?</a> +<li><a href="#SWIG_nn49">Getting the right header files</a> +<li><a href="#SWIG_nn50">What to do with main()</a> </ul> </ul> <!-- INDEX --> @@ -83,14 +83,14 @@ chapter to understand the basics. Specific details about each target language are described in later chapters. -<a name="n2"></a><H2>4.1 Running SWIG</H2> +<H2><a name="SWIG_nn2"></a>5.1 Running SWIG</H2> To run SWIG, use the <tt>swig</tt> command with one or more of the following options and a filename like this: -<p> -<blockquote><pre>swig [ <em>options</em> ] filename +<blockquote><pre> +swig [ <em>options</em> ] filename -chicken Generate CHICKEN wrappers -csharp Generate C# wrappers @@ -127,7 +127,7 @@ Additional options are also defined for each target language. A full list can be obtained by typing <tt>swig -help</tt> or <tt>swig -<em>lang</em> -help</tt>. -<a name="n3"></a><H3>4.1.1 Input format</H3> +<H3><a name="SWIG_nn3"></a>5.1.1 Input format</H3> As input, SWIG expects a file containing ANSI C/C++ declarations and @@ -140,9 +140,10 @@ do this (described later). <p> The most common format of a SWIG interface is as follows: +</p> -<p> -<blockquote><pre>%module mymodule +<blockquote><pre> +%module mymodule %{ #include "myheader.h" %} @@ -173,9 +174,9 @@ should be noted that the text enclosed in <tt>%{ ... %}</tt> is not parsed or interpreted by SWIG. The <tt>%{...%}</tt> syntax and semantics in SWIG is analogous to that of the declarations section used in input files to parser generation tools such as yacc or bison. +</p> -<a name="output"></a> -<a name="n4"></a><H3>4.1.2 SWIG Output</H3> +<H3><a name="output"></a>5.1.2 SWIG Output</H3> The output of SWIG is a C/C++ file that contains all of the wrapper @@ -191,7 +192,8 @@ language (C, C++, etc.). Therefore, you have to use the file if you want something different than the default. For example: <blockquote><pre> -$ swig -c++ -python -o example_wrap.cpp example.i</pre></blockquote> +$ swig -c++ -python -o example_wrap.cpp example.i +</pre></blockquote> <p> The C/C++ output file created by SWIG often @@ -201,12 +203,14 @@ usually necessary to edit the output file (and if you look at the output, you probably won't want to). To build the final extension module, the SWIG output file is compiled and linked with the rest of your C/C++ program to create a shared library. +</p> <p> Many target languages will also generate proxy class files in the target language. The default output directory for these language specific files is the same directory as the generated C/C++ file. This can can be modified using the <tt>-outdir</tt> option. For example: +</p> <blockquote><pre> $ swig -c++ -python -outdir pyfiles -o cppfiles/example_wrap.cpp example.i @@ -219,7 +223,7 @@ cppfiles/example_wrap.cpp pyfiles/example.py </pre></blockquote> -<a name="n5"></a><H3>4.1.3 Comments</H3> +<H3><a name="SWIG_nn5"></a>5.1.3 Comments</H3> C and C++ style comments may appear anywhere in interface files. In @@ -227,7 +231,7 @@ previous versions of SWIG, comments were used to generate documentation files. However, this feature is currently under repair and will reappear in a later SWIG release. -<a name="n6"></a><H3>4.1.4 C Preprocessor</H3> +<H3><a name="SWIG_nn6"></a>5.1.4 C Preprocessor</H3> Like C, SWIG preprocesses all input files through an enhanced version @@ -246,9 +250,10 @@ It should also be noted that the SWIG preprocessor skips all text enclosed inside a <tt>%{...%}</tt> block. In addition, the preprocessor includes a number of macro handling enhancements that make it more powerful than the normal C preprocessor. These -extensions are described in the "<a href="Preprocessor.html">Preprocessor</a>" chapter. +extensions are described in the "<a href="Preprocessor.html#Preprocessor">Preprocessor</a>" chapter. +</p> -<a name="n7"></a><H3>4.1.5 SWIG Directives</H3> +<H3><a name="SWIG_nn7"></a>5.1.5 SWIG Directives</H3> Most of SWIG's operation is controlled by special directives that are @@ -260,6 +265,7 @@ SWIG's parsing behavior in some manner. Since SWIG directives are not legal C syntax, it is generally not possible to include them in header files. However, SWIG directives can be included in C header files using conditional compilation like this: +</p> <blockquote><pre> /* header.h --- Some header file */ @@ -274,7 +280,7 @@ included in C header files using conditional compilation like this: <tt>SWIG</tt> is a special preprocessing symbol defined by SWIG when it is parsing an input file. -<a name="n8"></a><H3>4.1.6 Parser Limitations</H3> +<H3><a name="SWIG_nn8"></a>5.1.6 Parser Limitations</H3> Although SWIG can parse most C/C++ declarations, it does not @@ -283,7 +289,6 @@ limitations pertain to very complicated type declarations and certain advanced C++ features. Specifically, the following features are not currently supported: -<p> <ul> <li>Non-conventional type declarations. For example, SWIG does not support declarations such as the following @@ -303,11 +308,13 @@ void bar(Spam (Grok)(Doh)); </pre> </blockquote> +<p> In practice, few (if any) C programmers actually write code like this since this style is never featured in programming books. However, if you're feeling particularly obfuscated, you can certainly break SWIG (although why would you want to?). +</p> +</li> -<p> <li>Running SWIG on C++ source files (what would appear in a .C or .cxx file) is not recommended. Even though SWIG can parse C++ class declarations, it ignores declarations that are decoupled from their @@ -322,14 +329,17 @@ int foo::bar(int) { } </pre> </blockquote> +</li> <li>Certain advanced features of C++ such as nested classes are not yet supported. Please see the section on using SWIG with C++ for more information. -</ul> <p> +</ul> +<p> In the event of a parsing error, conditional compilation can be used to skip offending code. For example: +</p> <blockquote> <pre> @@ -353,16 +363,17 @@ parsing of more complex declarations (for the truly curious, the primary complication in the implementation is that the SWIG parser does not utilize a separate <em>typedef-name</em> terminal symbol as described on p. 234 of K&R). +</p> -<a name="n9"></a><H2>4.2 Wrapping Simple C Declarations</H2> +<H2><a name="SWIG_nn9"></a>5.2 Wrapping Simple C Declarations</H2> SWIG wraps simple C declarations by creating an interface that closely matches the way in which the declarations would be used in a C program. For example, consider the following interface file: -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example extern double sin(double x); extern int strcmp(const char *, const char *); @@ -377,8 +388,8 @@ a global variable <tt>Foo</tt>, and two constants <tt>STATUS</tt> and declarations are accessible as scripting language functions, variables, and constants respectively. For example, in Tcl: -<p> -<blockquote><pre>% sin 3 +<blockquote><pre> +% sin 3 5.2335956 % strcmp Dave Mike -1 @@ -392,17 +403,16 @@ constants respectively. For example, in Tcl: Or in Python: -<p> <blockquote><pre> ->>> example.sin(3) +>>> example.sin(3) 5.2335956 ->>> example.strcmp('Dave','Mike') +>>> example.strcmp('Dave','Mike') -1 ->>> print example.cvar.Foo +>>> print example.cvar.Foo 42 ->>> print example.STATUS +>>> print example.STATUS 50 ->>> print example.VERSION +>>> print example.VERSION 1.1 </pre></blockquote> @@ -411,7 +421,7 @@ code. However, due to subtle differences between languages, run-time environments, and semantics, it is not always possible to do so. The next few sections describes various aspects of this mapping. -<a name="n10"></a><H3>4.2.1 Basic Type Handling</H3> +<H3><a name="SWIG_nn10"></a>5.2.1 Basic Type Handling</H3> In order to build an interface, SWIG has to convert C/C++ datatypes to @@ -424,9 +434,10 @@ coercion. Most scripting languages provide a single integer type that is implemented using the <tt>int</tt> or <tt>long</tt> datatype in C. The following list shows all of the C datatypes that SWIG will convert to and from integers in the target language: +</p> -<p> -<blockquote><pre>int +<blockquote><pre> +int short long unsigned @@ -445,15 +456,16 @@ Thus, a 16 bit short in C may be promoted to a 32 bit integer. When integers ar converted in the other direction, the value is cast back into the original C type. If the value is too large to fit, it is silently truncated. <!-- Dave: Maybe we should fix this --> +</p> <p> <tt>unsigned char</tt> and <tt>signed char</tt> are special cases that are handled as small 8-bit integers. Normally, the <tt>char</tt> -datatype is mapped as a one-character ASCII string. <p> +datatype is mapped as a one-character ASCII string. </p> <p> The <tt>bool</tt> datatype is cast to and from an integer value of 0 -and 1 unless the target language provides a special boolean type.<p> +and 1 unless the target language provides a special boolean type.</p> <p> Some care is required when working with large integer values. Most @@ -465,6 +477,7 @@ variations of <tt>char</tt> and <tt>short</tt> datatypes are safe to use. For <tt>unsigned int</tt> and <tt>long</tt> datatypes, you will need to carefully check the correct operation of your program after it has been wrapped with SWIG. +</p> <p> Although the SWIG parser supports the <tt>long long</tt> datatype, not @@ -478,20 +491,21 @@ should also be noted that although <tt>long long</tt> is part of the ISO C99 standard, it is not universally supported by all C compilers. Make sure you are using a compiler that supports <tt>long long</tt> before trying to use this type with SWIG. +</p> <p> -SWIG recognizes the following floating point types :<p> +SWIG recognizes the following floating point types :</p> <blockquote><pre> float double </pre></blockquote> -<p> +<p> Floating point numbers are mapped to and from the natural representation of floats in the target language. This is almost always a C <tt>double</tt>. The rarely used datatype of <tt>long double</tt> -is not supported by SWIG.<p> +is not supported by SWIG.</p> <p> The <tt>char</tt> datatype is mapped into a NULL terminated ASCII @@ -500,7 +514,7 @@ shows up as a tiny string containing the character value. When converting the value back into C, SWIG takes a character string from the scripting language and strips off the first character as the char value. Thus if the value "foo" is assigned to a -<tt>char</tt> datatype, it gets the value `f'.<p> +<tt>char</tt> datatype, it gets the value `f'.</p> <p> The <tt>char *</tt> datatype is handled as a NULL-terminated ASCII @@ -511,7 +525,8 @@ C/C++. The default handling of these strings does not allow them to have embedded NULL bytes. Therefore, the <tt>char *</tt> datatype is not generally suitable for passing binary data. However, it is possible to change this behavior by defining a SWIG typemap. See the chapter -on <a href="Typemaps.html">Typemaps</a> for details about this. +on <a href="Typemaps.html#Typemaps">Typemaps</a> for details about this. +</p> <p> At this time, SWIG does not provide any special support for Unicode or @@ -525,23 +540,24 @@ will probably work). If the program you are wrapping uses Unicode, there is no guarantee that Unicode characters in the target language will use the same internal representation (e.g., UCS-2 vs. UCS-4). You may need to write some special conversion functions. +</p> -<a name="n11"></a><H3>4.2.2 Global Variables</H3> +<H3><a name="SWIG_nn11"></a>5.2.2 Global Variables</H3> Whenever possible, SWIG maps C/C++ global variables into scripting language variables. For example, -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example double foo; </pre></blockquote> results in a scripting language variable like this: -<p> -<blockquote><pre># Tcl +<blockquote><pre> +# Tcl set foo [3.5] ;# Set foo to 3.5 puts $foo ;# Print the value of foo @@ -575,16 +591,18 @@ Finally, if a global variable has been declared as <tt>const</tt>, it only supports read-only access. Note: this behavior is new to SWIG-1.3. Earlier versions of SWIG incorrectly handled <tt>const</tt> and created constants instead. +</p> -<a name="n12"></a><H3>4.2.3 Constants</H3> +<H3><a name="SWIG_nn12"></a>5.2.3 Constants</H3> +<p> Constants can be created using <tt>#define</tt>, enumerations, or a special <tt>%constant</tt> directive. The following -interface file shows a few valid constant declarations :<p> +interface file shows a few valid constant declarations :</p> -<p> -<blockquote><pre>#define I_CONST 5 // An integer constant +<blockquote><pre> +#define I_CONST 5 // An integer constant #define PI 3.14159 // A Floating point constant #define S_CONST "hello world" // A string constant #define NEWLINE '\n' // Character constant @@ -635,7 +653,7 @@ constant and the value is known. The use of constant expressions is allowed, but SWIG does not evaluate them. Rather, it passes them through to the output file and lets the C compiler perform the final evaluation (SWIG does perform a limited -form of type-checking however).<p> +form of type-checking however).</p> <p> For enumerations, it is critical that the original enum definition be @@ -644,6 +662,7 @@ in the <tt>%{,%}</tt> block). SWIG only translates the enumeration into code needed to add the constants to a scripting language. It needs the original enumeration declaration in order to get the correct enum values as assigned by the C compiler. +</p> <p> The <tt>%constant</tt> directive is used to more precisely create @@ -652,8 +671,9 @@ usually not needed for simple values, it is more useful when working with pointers and other more complex datatypes. Typically, <tt>%constant</tt> is only used when you want to add constants to the scripting language interface that are not defined in the original header file. +</p> -<a name="n13"></a><H3>4.2.4 A brief word about <tt>const</tt></H3> +<H3><a name="SWIG_nn13"></a>5.2.4 A brief word about <tt>const</tt></H3> A common confusion with C programming is the semantic meaning of the @@ -671,9 +691,11 @@ you need to look at the right-most occurrence of the <tt>const</tt> qualifier (that appears before the variable name). If the right-most <tt>const</tt> occurs after all other type modifiers (such as pointers), then the variable is <tt>const</tt>. Otherwise, it is not. +</p> <p> Here are some examples of <tt>const</tt> declarations. +</p> <blockquote> <pre> @@ -715,6 +737,7 @@ new interpretation of <tt>const</tt> as "read-only" is simple and exactly matches the actual semantics of <tt>const</tt> in C/C++. If you really want to create a constant as in older versions of SWIG, use the <tt>%constant</tt> directive instead. For example: +</p> <blockquote> <pre> @@ -740,7 +763,7 @@ const int spam = 42; </pre> </blockquote> -<a name="n14"></a><H3>4.2.5 A cautionary tale of <tt>char *</tt></H3> +<H3><a name="SWIG_nn14"></a>5.2.5 A cautionary tale of <tt>char *</tt></H3> Before going any further, there is one bit of caution involving @@ -755,6 +778,7 @@ receive a vast amount of wrath when you unleash your module on the world. <p> The primary source of problems are functions that might modify string data in place. A classic example would be a function like this: +</p> <blockquote> <pre> @@ -771,20 +795,23 @@ language---data that you shouldn't be touching. <p> The bottom line: don't rely on <tt>char *</tt> for anything other than read-only input values. However, it must be noted that you could change the behavior of SWIG -using <a href="Typemaps.html">typemaps</a>. +using <a href="Typemaps.html#Typemaps">typemaps</a>. +</p> -<a name="n15"></a><H2>4.3 Pointers and complex objects</H2> +<H2><a name="SWIG_nn15"></a>5.3 Pointers and complex objects</H2> Most C programs manipulate arrays, structures, and other types of objects. This section discusses the handling of these datatypes. -<a name="n16"></a><H3>4.3.1 Simple pointers</H3> +<H3><a name="SWIG_nn16"></a>5.3.1 Simple pointers</H3> -Pointers to primitive C datatypes such as <p> <p> -<blockquote><pre>int * +Pointers to primitive C datatypes such as </p> + +<blockquote><pre> +int * double *** char ** </pre></blockquote> @@ -793,17 +820,17 @@ are fully supported by SWIG. Rather than trying to convert the data being point representation, SWIG simply encodes the pointer itself into a representation that contains the actual value of the pointer and a type-tag. Thus, the SWIG representation of the above -pointers (in Tcl), might look like this:<p> +pointers (in Tcl), might look like this:</p> -<p> -<blockquote><pre>_10081012_p_int +<blockquote><pre> +_10081012_p_int _1008e124_ppp_double _f8ac_pp_char </pre></blockquote> <p> A NULL pointer is represented by the string "NULL" or the value 0 -encoded with type information.<p> +encoded with type information.</p> <p> All pointers are treated as opaque objects by SWIG. Thus, a pointer @@ -813,6 +840,7 @@ interface works in exactly the same way as you would use the pointer in a C program. The only difference is that there is no mechanism for dereferencing the pointer since this would require the target language to understand the memory layout of the underlying object. +</p> <p> The scripting language representation of a pointer value should never be @@ -823,27 +851,26 @@ Furthermore, SWIG does not normally map pointers into high-level objects such as associative arrays or lists (for example, converting an <tt>int *</tt> into an list of integers). There are several reasons -why SWIG does not do this:<p> +why SWIG does not do this:</p> -<p> <ul> <li>There is not enough information in a C declaration to properly map pointers into higher level constructs. For example, an <tt>int *</tt> may indeed be an array of integers, but if it contains ten million elements, converting it into a list object is probably a bad idea. +</li> -<p> <li>The underlying semantics associated with a pointer is not known by SWIG. For instance, an <tt>int *</tt> might not be an array at all--perhaps it is an output value! +</li> -<P> <li>By handling all pointers in a consistent manner, the implementation of SWIG is greatly simplified and less prone to error. +</li> </ul> -<p> -<a name="n17"></a><H3>4.3.2 Run time pointer type checking</H3> +<H3><a name="SWIG_nn17"></a>5.3.2 Run time pointer type checking</H3> By allowing pointers to be manipulated from a scripting language, extension modules @@ -861,14 +888,15 @@ receive a pointer. Although this has the potential to cause a crash, <tt>NULL</tt> pointers are also sometimes used as sentinel values or to denote a missing/empty value. Therefore, SWIG leaves NULL pointer checking up to the application. +</p> -<a name="n18"></a><H3>4.3.3 Derived types, structs, and classes</H3> +<H3><a name="SWIG_nn18"></a>5.3.3 Derived types, structs, and classes</H3> +<p> For everything else (structs, classes, arrays, etc...) SWIG applies a -very simple rule :<p> +very simple rule :</p> -<p> <center> <b>Everything else is a pointer</b> </center> @@ -877,14 +905,14 @@ very simple rule :<p> In other words, SWIG manipulates everything else by reference. This model makes sense because most C/C++ programs make heavy use of pointers and SWIG can use the type-checked pointer mechanism already -present for handling pointers to basic datatypes.<p> +present for handling pointers to basic datatypes.</p> <p> Although this probably sounds complicated, it's really quite -simple. Suppose you have an interface file like this :<p> +simple. Suppose you have an interface file like this :</p> -<p> -<blockquote><pre>%module fileio +<blockquote><pre> +%module fileio FILE *fopen(char *, char *); int fclose(FILE *); unsigned fread(void *ptr, unsigned size, unsigned nobj, FILE *); @@ -894,13 +922,14 @@ void free(void *); </pre></blockquote> +<p> In this file, SWIG doesn't know what a <tt>FILE</tt> is, but since it's used as a pointer, so it doesn't really matter what it is. If you wrapped this module into Python, you can use the functions just like you -expect :<p> +expect :</p> -<p> -<blockquote><pre># Copy a file +<blockquote><pre> +# Copy a file def filecopy(source,target): f1 = fopen(source,"r") f2 = fopen(target,"w") @@ -913,21 +942,22 @@ def filecopy(source,target): </pre></blockquote> +<p> In this case <tt>f1</tt>,<tt> f2</tt>, and <tt>buffer</tt> are all opaque objects containing C pointers. It doesn't matter what value -they contain--our program works just fine without this knowledge.<p> +they contain--our program works just fine without this knowledge.</p> -<a name="n19"></a><H3>4.3.4 Undefined datatypes</H3> +<H3><a name="SWIG_nn19"></a>5.3.4 Undefined datatypes</H3> +<p> When SWIG encounters an undeclared datatype, it automatically assumes that it is a structure or class. For example, suppose the following -function appeared in a SWIG input file:<p> +function appeared in a SWIG input file:</p> -<p> -<blockquote><pre>void matrix_multiply(Matrix *a, Matrix *b, Matrix *c); +<blockquote><pre> +void matrix_multiply(Matrix *a, Matrix *b, Matrix *c); </pre></blockquote> -<p> SWIG has no idea what a "<tt>Matrix</tt>" is. However, it is obviously a pointer to something so SWIG generates a wrapper using its generic pointer @@ -940,12 +970,14 @@ allows SWIG to generate interfaces from only partial or limited information. In some cases, you may not care what a <tt>Matrix</tt> really is as long as you can pass an opaque reference to one around in the scripting language interface. +</p> <p> An important detail to mention is that SWIG will gladly generate wrappers for an interface when there are unspecified type names. However, <b>all unspecified types are internally handled as pointers to structures or classes!</b> For example, consider the following declaration: +</p> <blockquote> <pre> @@ -969,13 +1001,15 @@ The only way to fix this problem is to make sure you properly declare type names <!-- We might want to add an error reporting flag to swig --> -<a name="n20"></a><H3>4.3.5 Typedef</H3> +<H3><a name="SWIG_nn20"></a>5.3.5 Typedef</H3> -Like C, <tt>typedef</tt> can be used to define new type names in SWIG. For example: <p> -<blockquote><pre>typedef unsigned int size_t; +Like C, <tt>typedef</tt> can be used to define new type names in SWIG. For example: +</p> +<blockquote><pre> +typedef unsigned int size_t; </pre></blockquote> <tt>typedef</tt> definitions appearing in a SWIG interface @@ -1022,14 +1056,14 @@ $ swig -I/usr/include -includeall example.i </pre> </blockquote> +<p> It should be noted that your mileage will vary greatly here. System headers are notoriously complicated and may rely upon a variety of non-standard C coding extensions (e.g., such as special directives to GCC). Unless you exactly specify the right include directories and preprocessor symbols, this may not work correctly (you will have to experiment). - -<p> +</p> SWIG tracks <tt>typedef</tt> declarations and uses this information for run-time type checking. For instance, if you use the above <tt>typedef</tt> and @@ -1044,7 +1078,7 @@ void foo(unsigned int *ptr); The corresponding wrapper function will accept arguments of type <tt>unsigned int *</tt> or <tt>size_t *</tt>. -<a name="n21"></a><H2>4.4 Other Practicalities</H2> +<H2><a name="SWIG_nn21"></a>5.4 Other Practicalities</H2> So far, this chapter has presented almost everything you need to know to use SWIG @@ -1052,22 +1086,23 @@ for simple interfaces. However, some C programs use idioms that are somewhat more difficult to map to a scripting language interface. This section describes some of these issues. -<a name="n22"></a><H3>4.4.1 Passing structures by value</H3> +<H3><a name="SWIG_nn22"></a>5.4.1 Passing structures by value</H3> Sometimes a C function takes structure parameters that are passed by value. For example, consider the following function: -<p> -<blockquote><pre>double dot_product(Vector a, Vector b); +<blockquote><pre> +double dot_product(Vector a, Vector b); </pre></blockquote> <p> To deal with this, SWIG transforms the function to use pointers by creating a wrapper equivalent to the following: +</p> -<p> -<blockquote><pre>double wrap_dot_product(Vector *a, Vector *b) { +<blockquote><pre> +double wrap_dot_product(Vector *a, Vector *b) { Vector x = *a; Vector y = *b; return dot_product(x,y); @@ -1078,23 +1113,26 @@ creating a wrapper equivalent to the following: In the target language, the <tt>dot_product()</tt> function now accepts pointers to Vectors instead of Vectors. For the most part, this transformation is transparent so you might not notice. +</p> -<a name="n23"></a><H3>4.4.2 Return by value</H3> - +<H3><a name="SWIG_nn23"></a>5.4.2 Return by value</H3> -C functions that return structures or classes datatypes by value are more difficult -to handle. Consider the following function:<p> <p> -<blockquote><pre>Vector cross_product(Vector v1, Vector v2); +C functions that return structures or classes datatypes by value are more difficult +to handle. Consider the following function:</p> +<blockquote><pre> +Vector cross_product(Vector v1, Vector v2); </pre></blockquote> +<p> This function wants to return <tt>Vector</tt>, but SWIG only really supports pointers. As a result, SWIG creates a wrapper like this: +</p> -<p> -<blockquote><pre>Vector *wrap_cross_product(Vector *v1, Vector *v2) { +<blockquote><pre> +Vector *wrap_cross_product(Vector *v1, Vector *v2) { Vector x = *v1; Vector y = *v2; Vector *result; @@ -1105,10 +1143,10 @@ pointers. As a result, SWIG creates a wrapper like this: </pre></blockquote> <p> -or if SWIG was run with the <tt>-c++</tt> option:<p> +or if SWIG was run with the <tt>-c++</tt> option:</p> -<p> -<blockquote><pre>Vector *wrap_cross(Vector *v1, Vector *v2) { +<blockquote><pre> +Vector *wrap_cross(Vector *v1, Vector *v2) { Vector x = *v1; Vector y = *v2; Vector *result = new Vector(cross(x,y)); // Uses default copy constructor @@ -1123,42 +1161,48 @@ in use. Clearly, this will leak memory if you are unaware of the implicit memory allocation and don't take steps to free the result. That said, it should be noted that some language modules can now automatically track newly created objects and reclaim memory for you. Consult the documentation for each language module for more details. +</p> <p> It should also be noted that the handling of pass/return by value in C++ has some special cases. For example, the above code fragments don't work correctly if <tt>Vector</tt> doesn't define a default constructor. The section on SWIG and C++ has more information about this case. +</p> -<a name="n24"></a><H3>4.4.3 Linking to structure variables</H3> +<H3><a name="SWIG_nn24"></a>5.4.3 Linking to structure variables</H3> +<p> When global variables or class members involving structures are encountered, SWIG handles them as pointers. For example, a global -variable like this<p> +variable like this</p> <blockquote><pre> Vector unit_i; </pre></blockquote> + <p> -gets mapped to an underlying pair of set/get functions like this :<p> -<p> -<blockquote><pre>Vector *unit_i_get() { +gets mapped to an underlying pair of set/get functions like this :</p> + +<blockquote><pre> +Vector *unit_i_get() { return &unit_i; } void unit_i_set(Vector *value) { unit_i = *value; } </pre></blockquote> -<p> +<p> Again some caution is in order. A global variable created in this manner will show up as a pointer in the target scripting language. It would be an extremely bad idea to free or destroy such a pointer. Also, C++ classes must supply a properly defined copy constructor in order for assignment to work correctly. +</p> -<a name="n25"></a><H3>4.4.4 Linking to <tt>char *</tt></H3> +<H3><a name="SWIG_nn25"></a>5.4.4 Linking to <tt>char *</tt></H3> When a global variable of type <tt>char *</tt> appears, SWIG uses <tt>malloc()</tt> or @@ -1211,7 +1255,7 @@ like a variable). For example, in Python you will have to write: <blockquote> <pre> ->>> set_foo("Hello World") +>>> set_foo("Hello World") </pre> </blockquote> @@ -1269,24 +1313,26 @@ value is not released. -<a name="n26"></a><H3>4.4.5 Arrays</H3> +<H3><a name="SWIG_nn26"></a>5.4.5 Arrays</H3> +<p> Arrays are fully supported by SWIG, but they are always handled as pointers instead of mapping them to a special array object or list in the target language. Thus, the -following declarations :<p> +following declarations :</p> -<p> -<blockquote><pre>int foobar(int a[40]); +<blockquote><pre> +int foobar(int a[40]); void grok(char *argv[]); void transpose(double a[20][20]); </pre></blockquote> <p> are processed as if they were really declared like this: +</p> -<p> -<blockquote><pre>int foobar(int *a); +<blockquote><pre> +int foobar(int *a); void grok(char **argv); void transpose(double (*a)[20]); </pre></blockquote> @@ -1298,6 +1344,7 @@ user to make sure the pointer points a suitably allocated region of memory. <p> Multi-dimensional arrays are transformed into a pointer to an array of one less dimension. For example: +</p> <blockquote> <pre> @@ -1317,6 +1364,7 @@ section on arrays before using them with SWIG. <p> Array variables are supported, but are read-only by default. For example: +</p> <blockquote> <pre> @@ -1325,7 +1373,7 @@ int a[100][200]; </blockquote> In this case, reading the variable 'a' returns a pointer of type <tt>int (*)[200]</tt> -that points to the first element of the array <tt>&a[0][0]</tt>. Trying to modify 'a' results +that points to the first element of the array <tt>&a[0][0]</tt>. Trying to modify 'a' results in an error. This is because SWIG does not know how to copy data from the target language into the array. To work around this limitation, you may want to write a few simple assist functions like this: @@ -1387,11 +1435,12 @@ void pathname_set(char *value) { In the target language, the value can be set like a normal variable. -<a name="n27"></a><H3>4.4.6 Creating read-only variables</H3> +<H3><a name="SWIG_nn27"></a>5.4.6 Creating read-only variables</H3> +<p> A read-only variable can be created by using the <tt>%immutable</tt> -directive as shown :<p> +directive as shown :</p> <blockquote><pre> // File : interface.i @@ -1408,6 +1457,7 @@ The <tt>%immutable</tt> directive enables read-only mode until it is explicitly disabled using the <tt>%mutable</tt> directive. As an alternative to turning read-only mode off and on like this, individual declarations can also be tagged as immutable. For example: +</p> <blockquote><pre> %immutable x; // Make x read-only @@ -1433,18 +1483,20 @@ char * const version="1.0"; /* Read only variable */ <tt>%readonly</tt> and <tt>%readwrite</tt>. Although these directives still work, they generate a warning message. Simply change the directives to <tt>%immutable;</tt> and <tt>%mutable;</tt> to silence the warning. Don't forget the extra semicolon! +</p> -<a name="n28"></a><H3>4.4.7 Renaming and ignoring declarations</H3> +<H3><a name="SWIG_nn28"></a>5.4.7 Renaming and ignoring declarations</H3> +<p> Normally, the name of a C declaration is used when that declaration is wrapped into the target language. However, this may generate a conflict with a keyword or already existing function in the scripting language. To resolve a name conflict, you can use the <tt>%rename</tt> -directive as shown :<p> +directive as shown :</p> -<p> -<blockquote><pre>// interface.i +<blockquote><pre> +// interface.i %rename(my_print) print; extern void print(char *); @@ -1454,17 +1506,19 @@ extern int a_really_long_and_annoying_name; </pre></blockquote> +<p> SWIG still calls the correct C function, but in this case the function <tt>print()</tt> will really be called "<tt>my_print()</tt>" -in the target language. <p> +in the target language. </p> <p> The placement of the <tt>%rename</tt> directive is arbitrary as long as it appears before the declarations to be renamed. A common technique is to write code for wrapping a header file like this: +</p> -<p> -<blockquote><pre>// interface.i +<blockquote><pre> +// interface.i %rename(my_print) print; %rename(foo) a_really_long_and_annoying_name; @@ -1478,20 +1532,22 @@ occurrences of a name. The renaming applies to functions, variables, class and structure names, member functions, and member data. For example, if you had two-dozen C++ classes, all with a member function named `print' (which is a keyword in Python), you could rename them -all to `output' by specifying :<p> +all to `output' by specifying :</p> -<p> -<blockquote><pre>%rename(output) print; // Rename all `print' functions to `output' +<blockquote><pre> +%rename(output) print; // Rename all `print' functions to `output' </pre></blockquote> <p> SWIG does not normally perform any checks to see if the functions it wraps are already defined in the target scripting language. However, if you are careful about namespaces and your use of modules, you can usually -avoid these problems.<p> +avoid these problems.</p> +<p> Closely related to <tt>%rename</tt> is the <tt>%ignore</tt> directive. <tt>%ignore</tt> instructs SWIG to ignore declarations that match a given identifier. For example: +</p> <blockquote> <pre> @@ -1507,13 +1563,15 @@ One use of <tt>%ignore</tt> is to selectively remove certain declarations from a to add conditional compilation to the header. However, it should be stressed that this only works for simple declarations. If you need to remove a whole section of problematic code, the SWIG preprocessor should be used instead. -<P> +<p> More powerful variants of <tt>%rename</tt> and <tt>%ignore</tt> directives can be used to help wrap C++ overloaded functions and methods. This is described in the C++ chapter. +</p> <p> <b>Compatibility note: </b> Older versions of SWIG provided a special <tt>%name</tt> directive for renaming declarations. For example: +</p> <blockquote> <pre> @@ -1524,20 +1582,24 @@ For example: This directive is still supported, but it is deprecated and should probably be avoided. The <tt>%rename</tt> directive is more powerful and better supports wrapping of raw header file information. -<a name="n29"></a><H3>4.4.8 Default/optional arguments</H3> +<H3><a name="SWIG_nn29"></a>5.4.8 Default/optional arguments</H3> -SWIG supports default arguments in both C and C++ code. For example: <p> -<blockquote><pre>int plot(double x, double y, int color=WHITE); +SWIG supports default arguments in both C and C++ code. For example: +</p> +<blockquote><pre> +int plot(double x, double y, int color=WHITE); </pre></blockquote> + +<p> In this case, SWIG generates wrapper code where the default arguments are optional in the target language. For example, this function could be -used in Tcl as follows :<p> +used in Tcl as follows :</p> -<p> -<blockquote><pre>% plot -3.4 7.5 # Use default value +<blockquote><pre> +% plot -3.4 7.5 # Use default value % plot -3.4 7.5 10 # set color to 10 instead </pre></blockquote> @@ -1552,8 +1614,9 @@ arguments are used, the default values are emitted into the wrappers and the function is invoked with a full set of arguments. This behavior is not 100% compatible with all uses of default arguments in C++. Please refer to the C++ chapter for further details. +</p> -<a name="n30"></a><H3>4.4.9 Pointers to functions and callbacks</H3> +<H3><a name="SWIG_nn30"></a>5.4.9 Pointers to functions and callbacks</H3> Occasionally, a C library may include functions that expect to receive @@ -1565,20 +1628,19 @@ consider a function like this: <blockquote><pre> int binary_op(int a, int b, int (*op)(int,int)); </pre></blockquote> -<p> When you first wrap something like this into an extension module, you may find the function to be impossible to use. For instance, in Python: <blockquote><pre> ->>> def add(x,y): +>>> def add(x,y): ... return x+y ... ->>> binary_op(3,4,add) +>>> binary_op(3,4,add) Traceback (most recent call last): - File "<stdin>", line 1, in ? + File "<stdin>", line 1, in ? TypeError: Type error. Expected _p_f_int_int__int ->>> +>>> </pre> </blockquote> @@ -1602,11 +1664,11 @@ constants in the target scripting language. This allows you to use them as foll <blockquote> <pre> ->>> binary_op(3,4,add) +>>> binary_op(3,4,add) 7 ->>> binary_op(3,4,mul) +>>> binary_op(3,4,mul) 12 ->>> +>>> </pre> </blockquote> @@ -1615,11 +1677,11 @@ as functions. For example: <blockquote> <pre> ->>> add(3,4) +>>> add(3,4) Traceback (most recent call last): - File "<stdin>", line 1, in ? + File "<stdin>", line 1, in ? TypeError: object is not callable: '_ff020efc_p_f_int_int__int' ->>> +>>> </pre> </blockquote> @@ -1646,13 +1708,13 @@ disabled using <tt>%nocallback</tt>. When you do this, the interface now works <blockquote> <pre> ->>> binary_op(3,4,add_cb) +>>> binary_op(3,4,add_cb) 7 ->>> binary_op(3,4,mul_cb) +>>> binary_op(3,4,mul_cb) 12 ->>> add(3,4) +>>> add(3,4) 7 ->>> mul(3,4) +>>> mul(3,4) 12 </pre> </blockquote> @@ -1666,6 +1728,7 @@ SWIG provides a number of extensions to standard C printf formatting that may be useful in this context. For instance, the following variation installs the callbacks as all upper-case constants such as <tt>ADD</tt>, <tt>SUB</tt>, and <tt>MUL</tt>: +</p> <blockquote><pre> /* Some callback functions */ @@ -1685,8 +1748,9 @@ And now, a final note about function pointer support. Although SWIG does not normally allow callback functions to be written in the target language, this can be accomplished with the use of typemaps and other advanced SWIG features. This is described in a later chapter. +</p> -<a name="n31"></a><H2>4.5 Structures and unions</H2> +<H2><a name="SWIG_nn31"></a>5.5 Structures and unions</H2> This section describes the behavior of SWIG when processing ANSI C structures and union declarations. Extensions to @@ -1698,19 +1762,20 @@ creates a set of accessor functions. Although SWIG does not need structure definitions to build an interface, providing definitions make it possible to access structure members. The accessor functions generated by SWIG simply take a pointer to an object and allow access -to an individual member. For example, the declaration :<p> +to an individual member. For example, the declaration :</p> -<p> -<blockquote><pre>struct Vector { +<blockquote><pre> +struct Vector { double x,y,z; } </pre></blockquote> -gets transformed into the following set of accessor functions :<p> - <p> -<blockquote><pre>double Vector_x_get(struct Vector *obj) { +gets transformed into the following set of accessor functions :</p> + +<blockquote><pre> +double Vector_x_get(struct Vector *obj) { return obj->x; } double Vector_y_get(struct Vector *obj) { @@ -1759,14 +1824,15 @@ delete_Vector(v) However, most of SWIG's language modules also provide a high-level interface that is more convenient. Keep reading. -<a name="n32"></a><H3>4.5.1 Typedef and structures</H3> +<H3><a name="SWIG_nn32"></a>5.5.1 Typedef and structures</H3> +<p> SWIG supports the following construct which is quite common in C -programs :<p> +programs :</p> -<p> -<blockquote><pre>typedef struct { +<blockquote><pre> +typedef struct { double x,y,z; } Vector; @@ -1785,10 +1851,11 @@ double Vector_x_get(Vector *obj) { </pre> </blockquote> -If two different names are used like this :<p> - <p> -<blockquote><pre>typedef struct vector_struct { +If two different names are used like this :</p> + +<blockquote><pre> +typedef struct vector_struct { double x,y,z; } Vector; @@ -1799,17 +1866,18 @@ this is more typical C programming style. If declarations defined later in the i vector_struct</tt>, SWIG knows that this is the same as <tt>Vector</tt> and it generates the appropriate type-checking code. -<a name="n33"></a><H3>4.5.2 Character strings and structures</H3> +<H3><a name="SWIG_nn33"></a>5.5.2 Character strings and structures</H3> +<p> Structures involving character strings require some care. SWIG assumes that all members of type <tt>char *</tt> have been dynamically allocated using <tt>malloc()</tt> and that they are NULL-terminated ASCII strings. When such a member is modified, the previously contents -will be released, and the new contents allocated. For example :<p> +will be released, and the new contents allocated. For example :</p> -<p> -<blockquote><pre>%module mymodule +<blockquote><pre> +%module mymodule ... struct Foo { char *name; @@ -1818,10 +1886,11 @@ struct Foo { </pre></blockquote> -This results in the following accessor functions :<p> - <p> -<blockquote><pre>char *Foo_name_get(Foo *obj) { +This results in the following accessor functions :</p> + +<blockquote><pre> +char *Foo_name_get(Foo *obj) { return Foo->name; } @@ -1837,32 +1906,34 @@ char *Foo_name_set(Foo *obj, char *c) { If this behavior differs from what you need in your applications, the SWIG "memberin" typemap can be used to change it. See the typemaps chapter for further details. +</p> <p> Note: If the <tt>-c++</tt> option is used, <tt>new</tt> and <tt>delete</tt> are used to perform memory allocation. +</p> -<a name="n34"></a><H3>4.5.3 Array members</H3> +<H3><a name="SWIG_nn34"></a>5.5.3 Array members</H3> +<p> Arrays may appear as the members of structures, but they will be read-only. SWIG will write an accessor function that returns the pointer to the first element of the array, but will not write a function to change the contents of the array itself. When this situation is detected, SWIG may generate a warning message such as the -following :<p> - -<p> -<blockquote><pre>interface.i:116. Warning. Array member will be read-only +following :</p> +<blockquote><pre> +interface.i:116. Warning. Array member will be read-only </pre></blockquote> To eliminate the warning message, typemaps can be used, but this is discussed in a later chapter. In many cases, the warning message is harmless. -<a name="n35"></a><H3>4.5.4 Structure data members</H3> +<H3><a name="SWIG_nn35"></a>5.5.4 Structure data members</H3> Occasionally, a structure will contain data members that are themselves structures. For example: @@ -1886,10 +1957,10 @@ For example: <blockquote> <pre> Foo *Bar_f_get(Bar *b) { - return &b->f; + return &b->f; } void Bar_f_set(Bar *b, Foo *value) { - b->f = *value; + b->f = *value; } </pre> </blockquote> @@ -1902,7 +1973,7 @@ of a <tt>Bar</tt> object like this: <blockquote> <pre> Bar *b; -b->f.x = 37; +b->f.x = 37; </pre> </blockquote> @@ -1923,6 +1994,7 @@ the data member <tt>f</tt> itself. Clearly that's not what you want! <p> It should be noted that this transformation to pointers only occurs if SWIG knows that a data member is a structure or class. For instance, if you had a structure like this, +</p> <blockquote> <pre> @@ -1938,10 +2010,10 @@ like this: <blockquote> <pre> WORD Foo_w_get(Foo *f) { - return f->w; + return f->w; } void Foo_w_set(FOO *f, WORD value) { - f->w = value; + f->w = value; } </pre> </blockquote> @@ -1951,7 +2023,7 @@ to pointers. Starting in SWIG-1.3.12, this transformation <em>only</em> occurs class, or union. This is unlikely to break existing code. However, if you need to tell SWIG that an undeclared datatype is really a struct, simply use a forward struct declaration such as <tt>"struct Foo;"</tt>. -<a name="n36"></a><H3>4.5.5 C constructors and destructors </H3> +<H3><a name="SWIG_nn36"></a>5.5.5 C constructors and destructors </H3> When wrapping structures, it is generally useful to have a mechanism @@ -1966,13 +2038,14 @@ differently. If you don't want SWIG to generate constructors and destructors, you can use the <tt>%nodefault</tt> directive or the <tt>-no_default</tt> command line option. For example: -<p> -<blockquote><pre>swig -no_default example.i +</p> +<blockquote><pre> +swig -no_default example.i </pre></blockquote> or -<p> -<blockquote><pre>%module foo +<blockquote><pre> +%module foo ... %nodefault; // Don't create default constructors/destructors ... declarations ... @@ -1999,9 +2072,10 @@ or destructors unless you explicitly turned them on using <tt>-make_default</tt> However, it appears that most users want to have constructor and destructor functions so it has now been enabled as the default behavior. -<a name="n37"></a><H3>4.5.6 Adding member functions to C structures</H3> +<H3><a name="SWIG_nn37"></a>5.5.6 Adding member functions to C structures</H3> +<p> Most languages provide a mechanism for creating classes and supporting object oriented programming. From a C standpoint, object oriented programming really just boils down to the process of @@ -2012,9 +2086,10 @@ for utilizing it with C code. However, SWIG provides a special <tt>%extend</tt> directive that makes it possible to attach methods to C structures for purposes of building an object oriented interface. Suppose you have a C header file with -the following declaration :<p> -<p> -<blockquote><pre>/* file : vector.h */ +the following declaration :</p> + +<blockquote><pre> +/* file : vector.h */ ... typedef struct { double x,y,z; @@ -2024,8 +2099,8 @@ typedef struct { You can make a <tt>Vector</tt> look alot like a class by writing a SWIG interface like this: -<p> -<blockquote><pre>// file : vector.i +<blockquote><pre> +// file : vector.i %module mymodule %{ #include "vector.h" @@ -2054,23 +2129,25 @@ You can make a <tt>Vector</tt> look alot like a class by writing a SWIG interfac </pre></blockquote> +<p> Now, when used with shadow classes in Python, you can do things like -this :<p> +this :</p> -<p> -<blockquote><pre>>>> v = Vector(3,4,0) # Create a new vector +<blockquote><pre> +>>> v = Vector(3,4,0) # Create a new vector >>> print v.magnitude() # Print magnitude 5.0 >>> v.print() # Print it out [ 3, 4, 0 ] >>> del v # Destroy it </pre></blockquote> -<p> +<p> The <tt>%extend</tt> directive can also be used inside the definition -of the Vector structure. For example:<p> +of the Vector structure. For example:</p> -<blockquote><pre>// file : vector.i +<blockquote><pre> +// file : vector.i %module mymodule %{ #include "vector.h" @@ -2089,10 +2166,10 @@ typedef struct { <p> Finally, <tt>%extend</tt> can be used to access externally written functions provided they follow the naming convention used in this -example :<p> +example :</p> -<p> -<blockquote><pre>/* File : vector.c */ +<blockquote><pre> +/* File : vector.c */ /* Vector methods */ #include "vector.h" Vector *new_Vector(double x, double y, double z) { @@ -2158,6 +2235,7 @@ of the object. <p> A similar technique can also be used to work with problematic data members. For example, consider this interface: +</p> <blockquote> <pre> @@ -2184,10 +2262,10 @@ struct Person { // Specific implementation of set/get functions %{ char *Person_name_get(Person *p) { - return p->name; + return p->name; } void Person_name_set(Person *p, char *val) { - strncpy(p->name,val,50); + strncpy(p->name,val,50); } %} </pre> @@ -2203,13 +2281,16 @@ be entirely synthesized from existing attributes of the structure). name for the <tt>%addmethods</tt> directive. Since <tt>%addmethods</tt> could be used to extend a structure with more than just methods, a more suitable directive name has been chosen. +</p> -<a name="n38"></a><H3>4.5.7 Nested structures</H3> +<H3><a name="SWIG_nn38"></a>5.5.7 Nested structures</H3> -Occasionally, a C program will involve structures like this :<p> <p> -<blockquote><pre>typedef struct Object { +Occasionally, a C program will involve structures like this :</p> + +<blockquote><pre> +typedef struct Object { int objtype; union { int ivalue; @@ -2221,11 +2302,13 @@ Occasionally, a C program will involve structures like this :<p> </pre></blockquote> +<p> When SWIG encounters this, it performs a structure splitting operation that transforms the declaration into the equivalent of the -following:<p> -<p> -<blockquote><pre>typedef union { +following:</p> + +<blockquote><pre> +typedef union { int ivalue; double dvalue; char *strvalue; @@ -2239,11 +2322,13 @@ typedef struct Object { </pre></blockquote> +<p> SWIG will then create an <tt>Object_intRep</tt> structure for use inside the interface file. Accessor functions will be created for both -structures. In this case, functions like this would be created :<p> -<p> -<blockquote><pre>Object_intRep *Object_intRep_get(Object *o) { +structures. In this case, functions like this would be created :</p> + +<blockquote><pre> +Object_intRep *Object_intRep_get(Object *o) { return (Object_intRep *) &o->intRep; } int Object_intRep_ivalue_get(Object_intRep *o) { @@ -2262,8 +2347,8 @@ double Object_intRep_dvalue_get(Object_intRep *o) { Although this process is a little hairy, it works like you would expect in the target scripting language--especially when shadow classes are used. For instance, in Perl: -<p> -<blockquote><pre># Perl5 script for accessing nested member +<blockquote><pre> +# Perl5 script for accessing nested member $o = CreateObject(); # Create an object somehow $o->{intRep}->{ivalue} = 7 # Change value of o.intRep.ivalue </pre></blockquote> @@ -2274,25 +2359,27 @@ advisable to double-check them after running SWIG. Although, there is a good chance that they will work, you may have to modify the interface file in certain cases. -<a name="n39"></a><H3>4.5.8 Other things to note about structure wrapping</H3> +<H3><a name="SWIG_nn39"></a>5.5.8 Other things to note about structure wrapping</H3> +<p> SWIG doesn't care if the declaration of a structure in a <tt>.i</tt> file exactly matches that used in the underlying C code (except in the case of nested structures). For this reason, there are no problems omitting problematic members or simply omitting the structure definition altogether. If you are happy passing pointers around, this can -be done without ever giving SWIG a structure definition.<p> +be done without ever giving SWIG a structure definition.</p> <p> Starting with SWIG1.3, a number of improvements have been made to SWIG's code generator. Specifically, even though structure access has been described in terms of high-level accessor functions such as this, +</p> <blockquote> <pre> double Vector_x_get(Vector *v) { - return v->x; + return v->x; } </pre> </blockquote> @@ -2313,7 +2400,7 @@ _wrap_Vector_x_get(ClientData clientData, Tcl_Interp *interp, if (SWIG_GetArgs(interp, objc, objv,"p:Vector_x_get self ",&arg0, SWIGTYPE_p_Vector) == TCL_ERROR) return TCL_ERROR; - result = (double ) (arg1->x); + result = (double ) (arg1->x); Tcl_SetObjResult(interp,Tcl_NewDoubleObj((double) result)); return TCL_OK; } @@ -2328,17 +2415,19 @@ Finally, it is important to note that most language modules may choose to build a more advanced interface. Although you may never use the low-level interface described here, most of SWIG's language modules use it in some way or another. +</p> -<a name="n40"></a><H2>4.6 Code Insertion</H2> +<H2><a name="SWIG_nn40"></a>5.6 Code Insertion</H2> +<p> Sometimes it is necessary to insert special code into the resulting wrapper file generated by SWIG. For example, you may want to include additional C code to perform initialization or other operations. There are four common ways to insert code, but it's useful to know how the -output of SWIG is structured first.<p> +output of SWIG is structured first.</p> -<a name="n41"></a><H3>4.6.1 The output of SWIG</H3> +<H3><a name="SWIG_nn41"></a>5.6.1 The output of SWIG</H3> When SWIG creates its output file, it is broken up into four sections @@ -2349,24 +2438,25 @@ initialization code (in that order). <li><b>Runtime code</b>. <br> This code is internal to SWIG and is used to include type-checking and other support functions that are used by the rest of the module. +</li> -<p> <li><b>Header section</b>. <br> This is user-defined support code that has been included by the <tt>%{ ... %}</tt> directive. Usually this consists of header files and other helper functions. +</li> -<p> <li><b>Wrapper code</b>. <br> These are the wrappers generated automatically by SWIG. +</li> -<p> <li><b>Module initialization</b>. <br> The function generated by SWIG to initialize the module upon loading. +</li> </ul> -<a name="n42"></a><H3>4.6.2 Code insertion blocks</H3> +<H3><a name="SWIG_nn42"></a>5.6.2 Code insertion blocks</H3> Code is inserted into the appropriate code section by using one @@ -2399,7 +2489,7 @@ The bare <tt>%{ ... %}</tt> directive is a shortcut that is the same as Everything in a code insertion block is copied verbatim into the output file and is not parsed by SWIG. Most SWIG input files have at least one such block to include header files and support C code. Additional code blocks may be placed anywhere in a -SWIG file as needed. <p> +SWIG file as needed. </p> <blockquote><pre> %module mymodule @@ -2419,9 +2509,10 @@ void some_extra_function() { A common use for code blocks is to write "helper" functions. These are functions that are used specifically for the purpose of building an interface, but which are generally not visible to the normal C -program. For example :<p> -<p> -<blockquote><pre>%{ +program. For example :</p> + +<blockquote><pre> +%{ /* Create a new vector */ static Vector *new_Vector() { return (Vector *) malloc(sizeof(Vector)); @@ -2432,14 +2523,16 @@ static Vector *new_Vector() { Vector *new_Vector(); </pre></blockquote> -<a name="n43"></a><H3>4.6.3 Inlined code blocks</H3> +<H3><a name="SWIG_nn43"></a>5.6.3 Inlined code blocks</H3> +<p> Since the process of writing helper functions is fairly common, there is a special inlined form of code block that is used as follows -:<p> -<p> -<blockquote><pre>%inline %{ +:</p> + +<blockquote><pre> +%inline %{ /* Create a new vector */ Vector *new_Vector() { return (Vector *) malloc(sizeof(Vector)); @@ -2448,42 +2541,47 @@ Vector *new_Vector() { </pre></blockquote> +<p> The <tt>%inline</tt> directive inserts all of the code that follows verbatim into the header portion of an interface file. The code is then parsed by both the SWIG preprocessor and parser. Thus, the above example creates a new command <tt>new_Vector</tt> using only one declaration. Since the code inside an <tt>%inline %{ ... %}</tt> block is given to both the C compiler and SWIG, it is illegal to include any -SWIG directives inside a <tt>%{ ... %}</tt> block.<p> +SWIG directives inside a <tt>%{ ... %}</tt> block.</p> -<a name="n44"></a><H3>4.6.4 Initialization blocks</H3> +<H3><a name="SWIG_nn44"></a>5.6.4 Initialization blocks</H3> +<p> When code is included in the <tt>%init</tt> section, it is copied directly into the module initialization function. For example, if you needed to perform some extra initialization on module loading, you could write this: -<p> -<blockquote><pre>%init %{ +</p> + +<blockquote><pre> +%init %{ init_variables(); %} </pre></blockquote> -<a name="n45"></a><H2>4.7 An Interface Building Strategy</H2> +<H2><a name="SWIG_nn45"></a>5.7 An Interface Building Strategy</H2> +<p> This section describes the general approach for building interface with SWIG. The specifics related to a particular scripting language -are found in later chapters.<p> +are found in later chapters.</p> -<a name="n46"></a><H3>4.7.1 Preparing a C program for SWIG</H3> +<H3><a name="SWIG_nn46"></a>5.7.1 Preparing a C program for SWIG</H3> +<p> SWIG doesn't require modifications to your C code, but if you feed it a collection of raw C header files or source code, the results might not be what you expect---in fact, they might be awful. Here's a series -of steps you can follow to make an interface for a C program :<p> +of steps you can follow to make an interface for a C program :</p> -<p> <ul> <li>Identify the functions that you want to wrap. It's probably not necessary to access every single function in a C program--thus, a @@ -2508,9 +2606,11 @@ type-information is available in the interface file. <li>Run SWIG and compile. </ul> + <p> Although this may sound complicated, the process turns out to be fairly easy once you get the hang of it. +</p> <p> In the process of building an interface, SWIG may encounter syntax errors or @@ -2518,12 +2618,14 @@ other problems. The best way to deal with this is to simply copy the offending code into a separate interface file and edit it. However, the SWIG developers have worked very hard to improve the SWIG parser--you should report parsing errors to <tt>swig-dev@cs.uchicago.edu</tt> or to the SWIG bug tracker on <tt>www.swig.org</tt>. +</p> -<a name="n47"></a><H3>4.7.2 The SWIG interface file</H3> +<H3><a name="SWIG_nn47"></a>5.7.2 The SWIG interface file</H3> +<p> The preferred method of using SWIG is to generate separate interface -file. Suppose you have the following C header file :<p> +file. Suppose you have the following C header file :</p> <blockquote><pre> /* File : header.h */ @@ -2537,8 +2639,9 @@ extern void dump(FILE *f); </pre></blockquote> +<p> A typical SWIG interface file for this header file would look like the -following :<p> +following :</p> <blockquote><pre> /* File : interface.i */ @@ -2551,24 +2654,29 @@ extern double bar(int, int); extern void dump(FILE *f); </pre></blockquote> -Of course, in this case, our header file is pretty simple so we could -have made an interface file like this as well:<p> <p> -<blockquote><pre>/* File : interface.i */ +Of course, in this case, our header file is pretty simple so we could +have made an interface file like this as well:</p> + +<blockquote><pre> +/* File : interface.i */ %module mymodule %include header.h </pre></blockquote> + <p> -Naturally, your mileage may vary.<p> +Naturally, your mileage may vary.</p> -<a name="n48"></a><H3>4.7.3 Why use separate interface files?</H3> +<H3><a name="SWIG_nn48"></a>5.7.3 Why use separate interface files?</H3> +<p> Although SWIG can parse many header files, it is more common to write a special <tt>.i</tt> file defining the interface to a package. There are several reasons why you might want to do this: -<p> +</p> + <ul> <li>It is rarely necessary to access every single function in a large package. Many C functions might have little or no use in a scripted @@ -2589,7 +2697,7 @@ and immediately see what is available without having to dig it out of header files. </ul> -<a name="n49"></a><H3>4.7.4 Getting the right header files</H3> +<H3><a name="SWIG_nn49"></a>5.7.4 Getting the right header files</H3> Sometimes, it is necessary to use certain header files in order for @@ -2607,16 +2715,17 @@ include certain header files by using a <tt>%{,%}</tt> block like this: ... </pre></blockquote> -<a name="n50"></a><H3>4.7.5 What to do with main()</H3> +<H3><a name="SWIG_nn50"></a>5.7.5 What to do with main()</H3> +<p> If your program defines a <tt>main()</tt> function, you may need to get rid of it or rename it in order to use a scripting language. Most scripting languages define their own <tt>main()</tt> procedure that is called instead. <tt>main()</tt> also makes no sense when working with dynamic loading. There are a few approaches to solving -the <tt>main()</tt> conflict :<p> -<p> +the <tt>main()</tt> conflict :</p> + <ul> <li>Get rid of <tt>main()</tt> entirely. @@ -2633,7 +2742,7 @@ problems of a program. To handle this problem, you may consider writing a special function called <tt>program_init()</tt> that initializes your program upon startup. This function could then be called either from the scripting language as the first operation, or -when the SWIG generated module is loaded.<p> +when the SWIG generated module is loaded.</p> <p> As a general note, many C programs only use the <tt>main()</tt> @@ -2641,7 +2750,7 @@ function to parse command line options and to set parameters. However, by using a scripting language, you are probably trying to create a program that is more interactive. In many cases, the old <tt>main()</tt> program can be completely replaced by a Perl, Python, -or Tcl script.<p> +or Tcl script.</p> <p> <b>Note:</b> If some cases, you might be inclined to create a @@ -2652,8 +2761,9 @@ correctly. The only trouble is that when you call your <tt>main()</tt> of the scripting language interpreter itself! This behavior is a side effect of the symbol binding mechanism used in the dynamic linker. The bottom line: don't do this. +</p> -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : August 7, 2003</address> </body> diff --git a/Doc/Manual/SWIGPlus.html b/Doc/Manual/SWIGPlus.html index 88afb3a90..3751f0534 100644 --- a/Doc/Manual/SWIGPlus.html +++ b/Doc/Manual/SWIGPlus.html @@ -5,67 +5,67 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>5 SWIG and C++</H1> +<H1><a name="SWIGPlus"></a>6 SWIG and C++</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Comments on C++ Wrapping</a> -<li><a href="#n3">Approach</a> -<li><a href="#n4">Supported C++ features</a> -<li><a href="#n5">Command line options and compilation</a> -<li><a href="#n6">Simple C++ wrapping</a> +<li><a href="#SWIGPlus_nn2">Comments on C++ Wrapping</a> +<li><a href="#SWIGPlus_nn3">Approach</a> +<li><a href="#SWIGPlus_nn4">Supported C++ features</a> +<li><a href="#SWIGPlus_nn5">Command line options and compilation</a> +<li><a href="#SWIGPlus_nn6">Simple C++ wrapping</a> <ul> -<li><a href="#n7">Constructors and destructors</a> -<li><a href="#n8">Default constructors</a> -<li><a href="#n9">When constructor wrappers aren't created</a> -<li><a href="#n10">Copy constructors</a> -<li><a href="#n11">Member functions</a> -<li><a href="#n12">Static members</a> -<li><a href="#n13">Member functions and default arguments</a> -<li><a href="#n14">Member data</a> +<li><a href="#SWIGPlus_nn7">Constructors and destructors</a> +<li><a href="#SWIGPlus_nn8">Default constructors</a> +<li><a href="#SWIGPlus_nn9">When constructor wrappers aren't created</a> +<li><a href="#SWIGPlus_nn10">Copy constructors</a> +<li><a href="#SWIGPlus_nn11">Member functions</a> +<li><a href="#SWIGPlus_nn12">Static members</a> +<li><a href="#SWIGPlus_nn13">Member functions and default arguments</a> +<li><a href="#SWIGPlus_nn14">Member data</a> </ul> -<li><a href="#n15">Protection</a> -<li><a href="#n16">Enums and constants</a> -<li><a href="#n17">Friends</a> -<li><a href="#n18">References and pointers</a> -<li><a href="#n19">Pass and return by value</a> -<li><a href="#n20">Inheritance</a> -<li><a href="#n21">A brief discussion of multiple inheritance, pointers, and type checking</a> -<li><a href="#n22">Renaming</a> -<li><a href="#n23">Wrapping Overloaded Functions and Methods</a> +<li><a href="#SWIGPlus_nn15">Protection</a> +<li><a href="#SWIGPlus_nn16">Enums and constants</a> +<li><a href="#SWIGPlus_nn17">Friends</a> +<li><a href="#SWIGPlus_nn18">References and pointers</a> +<li><a href="#SWIGPlus_nn19">Pass and return by value</a> +<li><a href="#SWIGPlus_nn20">Inheritance</a> +<li><a href="#SWIGPlus_nn21">A brief discussion of multiple inheritance, pointers, and type checking</a> +<li><a href="#SWIGPlus_nn22">Renaming</a> +<li><a href="#SWIGPlus_nn23">Wrapping Overloaded Functions and Methods</a> <ul> -<li><a href="#n24">Dispatch function generation</a> -<li><a href="#n25">Ambiguity in Overloading</a> -<li><a href="#n26">Ambiguity resolution and renaming</a> -<li><a href="#n27">Comments on overloading</a> +<li><a href="#SWIGPlus_nn24">Dispatch function generation</a> +<li><a href="#SWIGPlus_nn25">Ambiguity in Overloading</a> +<li><a href="#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> +<li><a href="#SWIGPlus_nn27">Comments on overloading</a> </ul> -<li><a href="#n28">Wrapping overloaded operators</a> -<li><a href="#n29">Class extension</a> -<li><a href="#n30">Templates</a> -<li><a href="#n31">Namespaces</a> -<li><a href="#n32">Exception specifiers</a> -<li><a href="#n33">Pointers to Members</a> -<li><a href="#n34">Smart pointers and operator->()</a> -<li><a href="#n35">Using declarations and inheritance</a> -<li><a href="#n36">Partial class definitions</a> -<li><a href="#n37">A brief rant about const-correctness</a> -<li><a href="#n38">Proxy classes</a> +<li><a href="#SWIGPlus_nn28">Wrapping overloaded operators</a> +<li><a href="#SWIGPlus_nn29">Class extension</a> +<li><a href="#SWIGPlus_nn30">Templates</a> +<li><a href="#SWIGPlus_nn31">Namespaces</a> +<li><a href="#SWIGPlus_nn32">Exception specifiers</a> +<li><a href="#SWIGPlus_nn33">Pointers to Members</a> +<li><a href="#SWIGPlus_nn34">Smart pointers and operator->()</a> +<li><a href="#SWIGPlus_nn35">Using declarations and inheritance</a> +<li><a href="#SWIGPlus_nn36">Partial class definitions</a> +<li><a href="#SWIGPlus_nn37">A brief rant about const-correctness</a> +<li><a href="#SWIGPlus_nn38">Proxy classes</a> <ul> -<li><a href="#n39">Construction of proxy classes</a> -<li><a href="#n40">Resource management in proxies</a> -<li><a href="#n41">Language specific details</a> +<li><a href="#SWIGPlus_nn39">Construction of proxy classes</a> +<li><a href="#SWIGPlus_nn40">Resource management in proxies</a> +<li><a href="#SWIGPlus_nn41">Language specific details</a> </ul> -<li><a href="#n42">Where to go for more information</a> +<li><a href="#SWIGPlus_nn42">Where to go for more information</a> </ul> <!-- INDEX --> This chapter describes SWIG's support for wrapping C++. As a prerequisite, -you should first read the chapter <a href="SWIG.html">SWIG Basics</a> to see +you should first read the chapter <a href="SWIG.html#SWIG">SWIG Basics</a> to see how SWIG wraps ANSI C. Support for C++ builds upon ANSI C wrapping and that material will be useful in understanding this chapter. -<a name="n2"></a><H2>5.1 Comments on C++ Wrapping</H2> +<H2><a name="SWIGPlus_nn2"></a>6.1 Comments on C++ Wrapping</H2> Because of its complexity and the fact that C++ can be @@ -81,6 +81,7 @@ problem of wrapping C++ multiple inheritance to a target language with no such support. Similarly, the use of overloaded operators and overloaded functions can be problematic when no such capability exists in a target language. +</p> <p> A more subtle issue with C++ has to do with the way that some C++ @@ -102,8 +103,9 @@ sometimes non-obvious ways. Although this "magic" may present few problems in a C++-only universe, it greatly complicates the problem of crossing language boundaries and provides many opportunities to shoot yourself in the foot. You will just have to be careful. +</p> -<a name="n3"></a><H2>5.2 Approach</H2> +<H2><a name="SWIGPlus_nn3"></a>6.2 Approach</H2> To wrap C++, SWIG uses a layered approach to code generation. @@ -133,6 +135,7 @@ not play sneaky tricks with the C++ type system, it doesn't mess with your class hierarchies, and it doesn't introduce new semantics. Although this approach might not provide the most seamless integration with C++, it is safe, simple, portable, and debuggable. +</p> <p> Most of this chapter focuses on the low-level procedural interface to @@ -141,12 +144,14 @@ mind that most target languages also provide a high-level OO interface via proxy classes. A few general details about proxies can be found at the end of this chapter. However, more detailed coverage can be found in the documentation for each target language. +</p> -<a name="n4"></a><H2>5.3 Supported C++ features</H2> +<H2><a name="SWIGPlus_nn4"></a>6.3 Supported C++ features</H2> -SWIG's currently supports the following C++ features :<p> <p> +SWIG's currently supports the following C++ features :</p> + <ul> <li>Classes. <li>Constructors and destructors @@ -162,9 +167,8 @@ SWIG's currently supports the following C++ features :<p> </ul> <p> -The following C++ features are not currently supported :<p> +The following C++ features are not currently supported :</p> -<p> <ul> <li>Nested classes <li>Overloaded versions of certain operators (new, delete, etc.) @@ -174,8 +178,9 @@ The following C++ features are not currently supported :<p> SWIG's C++ support is an ongoing project so some of these limitations may be lifted in future releases. However, we make no promises. Also, submitting a bug report is a very good way to get problems fixed (wink). +</p> -<a name="n5"></a><H2>5.4 Command line options and compilation</H2> +<H2><a name="SWIGPlus_nn5"></a>6.4 Command line options and compilation</H2> <p> @@ -184,11 +189,12 @@ When wrapping C++ code, it is critical that SWIG be called with the features such as memory management are handled. It also enables the recognition of C++ keywords. Without the <tt>-c++</tt> flag, SWIG will either issue a warning or a large number of syntax -errors if it encounters C++ code in an interface file.<p> +errors if it encounters C++ code in an interface file.</p> -<P> +<p> When compiling and linking the resulting wrapper file, it is normal to use the C++ compiler. For example: +</p> <blockquote> <pre> @@ -198,18 +204,21 @@ $ c++ example_wrap.o $(OBJS) -o example.so </pre> </blockquote> +<p> Unfortunately, the process varies slightly on each machine. Make sure you refer to the documentation on each target language for further details. The SWIG Wiki also has further details. +</p> -<a name="n6"></a><H2>5.5 Simple C++ wrapping</H2> +<H2><a name="SWIGPlus_nn6"></a>6.5 Simple C++ wrapping</H2> +<p> The following code shows a SWIG interface file for a simple C++ -class.<p> +class.</p> -<p> -<blockquote><pre>%module list +<blockquote><pre> +%module list %{ #include "list.h" %} @@ -233,14 +242,15 @@ To generate wrappers for this class, SWIG first reduces the class to a collectio accessor functions. The next few sections describe this process. Later parts of the chapter decribe a higher level interface based on proxy classes. -<a name="n7"></a><H3>5.5.1 Constructors and destructors</H3> +<H3><a name="SWIGPlus_nn7"></a>6.5.1 Constructors and destructors</H3> +<p> C++ constructors and destructors are translated into accessor -functions such as the following :<p> +functions such as the following :</p> -<p> -<blockquote><pre>List * new_List(void) { +<blockquote><pre> +List * new_List(void) { return new List; } void delete_List(List *l) { @@ -249,7 +259,7 @@ void delete_List(List *l) { </pre></blockquote> -<a name="n8"></a><H3>5.5.2 Default constructors</H3> +<H3><a name="SWIGPlus_nn8"></a>6.5.2 Default constructors</H3> If a C++ class does not define any public constructors or @@ -258,22 +268,23 @@ destructor. However, there are a few rules that define this behavior: <ul> <li>A default constructor is not created if a class already defines a constructor with arguments. +</li> -<p> <li>Default constructors are not generated for classes with pure virtual methods or for classes that inherit from an abstract class, but don't provide definitions for all of the pure methods. +</li> -<p> <li>A default constructor is not created unless all bases classes support a default constructor. +</li> -<p> <li>Default constructors and destructors are not created if a class defines constructors or destructors in a <tt>private</tt> or <tt>protected</tt> section. +</li> -<p> <li>Default constructors and destructors are not created if any base class defines a private default constructor or a private destructor. +</li> </ul> SWIG should never generate a constructor or destructor for a class in which @@ -314,7 +325,7 @@ However, this removal may now cause SWIG to erroneously generate constructors for classes that define a constructor in those sections. Consider restoring those sections in the interface or using <tt>%nodefault</tt> to fix the problem. -<a name="n9"></a><H3>5.5.3 When constructor wrappers aren't created</H3> +<H3><a name="SWIGPlus_nn9"></a>6.5.3 When constructor wrappers aren't created</H3> If a class defines a constructor, SWIG normally tries to generate a wrapper for it. However, SWIG will @@ -323,6 +334,7 @@ two cases where this might show up. <p> First, SWIG won't generate wrappers for protected or private constructors. For example: +</p> <blockquote> <pre> @@ -335,8 +347,10 @@ public: </pre> </blockquote> -<p>Next, SWIG won't generate wrappers for a class if it appears to be abstract--that is, it has undefined +<p> +Next, SWIG won't generate wrappers for a class if it appears to be abstract--that is, it has undefined pure virtual methods. Here are some examples: +</p> <blockquote> <pre> @@ -353,9 +367,11 @@ public: </pre> </blockquote> +<p> Some users are surprised (or confused) to find missing constructor wrappers in their interfaces. In almost all cases, this is caused when classes are determined to be abstract. To see if this is the case, run SWIG with all of its warnings turned on: +</p> <blockquote> <pre> @@ -378,9 +394,9 @@ public: </pre> </blockquote> -More information about <tt>%feature</tt> can be found in the <a href="Customization.html">Customization features</a> chapter. +More information about <tt>%feature</tt> can be found in the <a href="Customization.html#Customization">Customization features</a> chapter. -<a name="n10"></a><H3>5.5.4 Copy constructors</H3> +<H3><a name="SWIGPlus_nn10"></a>6.5.4 Copy constructors</H3> If a class defines more than one constructor, its behavior depends on the capabilities of the @@ -392,7 +408,7 @@ the normal constructor function. For example, if you have this: class List { public: List(); - List(const List &); // Copy constructor + List(const List &); // Copy constructor ... }; </pre> @@ -424,25 +440,28 @@ a copy constructor if it can be applied to an object of type <tt>X</tt> or <tt>X *</tt>. If more than one copy constructor is defined, only the first definition that appears is used as the copy constructor--other definitions will result in a name-clash. -Constructors such as <tt>X(const X &)</tt>, <tt>X(X &)</tt>, and +Constructors such as <tt>X(const X &)</tt>, <tt>X(X &)</tt>, and <tt>X(X *)</tt> are handled as copy constructors in SWIG. +</p> <p> <b>Note:</b> SWIG does <em>not</em> generate a copy constructor wrapper unless one is explicitly declared in the class. This differs from the treatment of default constructors and destructors. +</p> <p> <b>Compatibility note:</b> Special support for copy constructors was not added until SWIG-1.3.12. In previous versions, copy constructors could be wrapped, but they had to be renamed. For example: +</p> <blockquote> <pre> class Foo { public: Foo(); - %name(CopyFoo) Foo(const Foo &); + %name(CopyFoo) Foo(const Foo &); ... }; </pre> @@ -454,12 +473,14 @@ renamed. For instance, in the above example, the name of the constructor is set to <tt>new_CopyFoo()</tt>. This is the same as in older versions. -<a name="n11"></a><H3>5.5.5 Member functions</H3> +<H3><a name="SWIGPlus_nn11"></a>6.5.5 Member functions</H3> -All member functions are roughly translated into accessor functions like this :<p> <p> -<blockquote><pre>int List_search(List *obj, char *value) { +All member functions are roughly translated into accessor functions like this :</p> + +<blockquote><pre> +int List_search(List *obj, char *value) { return obj->search(value); } @@ -474,8 +495,9 @@ function in the code it generates. Instead, member access such as <tt>obj->search(value)</tt> is directly inlined into the generated wrapper functions. However, the name and calling convention of the wrappers match the accessor function prototype described above. +</p> -<a name="n12"></a><H3>5.5.6 Static members</H3> +<H3><a name="SWIGPlus_nn12"></a>6.5.6 Static members</H3> Static member functions are called directly without making any special @@ -486,8 +508,9 @@ in the generated wrapper code. <p> Usually, static members are accessed as functions with names in which the class name has been prepended with an underscore. For example, <tt>List_print</tt>. +</p> -<a name="n13"></a><H3>5.5.7 Member functions and default arguments</H3> +<H3><a name="SWIGPlus_nn13"></a>6.5.7 Member functions and default arguments</H3> SWIG allows member functions to accept default arguments. For example: @@ -538,16 +561,18 @@ There are several somewhat clumsy ways to work around this problem (which are not discussed here). However, a simpler solution may be to reconsider your design--is it really <em>that</em> critical to make the default argument private? +</p> -<a name="n14"></a><H3>5.5.8 Member data</H3> +<H3><a name="SWIGPlus_nn14"></a>6.5.8 Member data</H3> +<p> Member data is handled in exactly the same manner as for C structures. A pair of accessor functions are created. For example -:<p> +:</p> -<p> -<blockquote><pre>int List_length_get(List *obj) { +<blockquote><pre> +int List_length_get(List *obj) { return obj->length; } int List_length_set(List *obj, int value) { @@ -557,13 +582,14 @@ int List_length_set(List *obj, int value) { </pre></blockquote> +<p> A read-only member can be created using the <tt>%immutable</tt> and <tt>%mutable</tt> directives. For example, we probably wouldn't want the user to change the length of a list so we could do the following -to make the value available, but read-only.<p> +to make the value available, but read-only.</p> -<p> -<blockquote><pre>class List { +<blockquote><pre> +class List { public: ... %immutable; @@ -592,6 +618,7 @@ Similarly, all data attributes declared as <tt>const</tt> are wrapped as read-on <p> There are some subtle issues when wrapping data members that are themselves classes. For instance, if you had another class like this, +</p> <blockquote> <pre> @@ -607,27 +634,29 @@ then access to the <tt>items</tt> member actually uses pointers. For example: <blockquote> <pre> List *Foo_items_get(Foo *self) { - return &self->items; + return &self->items; } void Foo_items_set(Foo *self, List *value) { - self->items = *value; + self->items = *value; } </pre> </blockquote> More information about this can be found in the "Structure data -members" section of the <a href="SWIG.html">SWIG Basics</a> chapter. +members" section of the <a href="SWIG.html#SWIG">SWIG Basics</a> chapter. <p> <b>Compatibility note:</b> Read-only access used to be controlled by a pair of directives <tt>%readonly</tt> and <tt>%readwrite</tt>. Although these directives still work, they generate a warning message. Simply change the directives to <tt>%immutable;</tt> and <tt>%mutable;</tt> to silence the warning. Don't forget the extra semicolon! +</p> <p> <b>Compatibility note:</b> Prior to SWIG-1.3.12, all members of unknown type were wrapped into accessor functions using pointers. For example, if you had a structure like this +</p> <blockquote> <pre> @@ -646,7 +675,7 @@ involving <tt>size_t</tt>. This change is subtle, but it smooths over a few problems related to structure wrapping and some of SWIG's customization features. -<a name="n15"></a><H2>5.6 Protection</H2> +<H2><a name="SWIGPlus_nn15"></a>6.6 Protection</H2> SWIG can only wrap class members that are declared public. Anything @@ -657,27 +686,33 @@ sections so that it can properly generate code for default constructors and dest <p> By default, members of a class definition are assumed to be private until you explicitly give a `<tt>public:</tt>' declaration (This is -the same convention used by C++).<p> +the same convention used by C++). +</p> <p> A subtle access problem relates to default values of member functions. Specifically, default values must be public. Please go back to the section on default arguments for further details. +</p> -<a name="n16"></a><H2>5.7 Enums and constants</H2> +<H2><a name="SWIGPlus_nn16"></a>6.7 Enums and constants</H2> -Enumerations and constants placed in a class definition are mapped -into constants with the classname as a prefix. For example :<p> <p> -<blockquote><pre>class Swig { +Enumerations and constants placed in a class definition are mapped +into constants with the classname as a prefix. For example :</p> + +<blockquote><pre> +class Swig { public: enum {ALE, LAGER, PORTER, STOUT}; }; </pre></blockquote> -Generates the following set of constants in the target scripting language :<p> <p> -<blockquote><pre>Swig_ALE = Swig::ALE +Generates the following set of constants in the target scripting language :</p> + +<blockquote><pre> +Swig_ALE = Swig::ALE Swig_LAGER = Swig::LAGER Swig_PORTER = Swig::PORTER Swig_STOUT = Swig::STOUT @@ -686,7 +721,7 @@ Swig_STOUT = Swig::STOUT Members declared as <tt>const</tt> are wrapped as read-only members and do not create constants. -<a name="n17"></a><H2>5.8 Friends</H2> +<H2><a name="SWIGPlus_nn17"></a>6.8 Friends</H2> Friend declarations are ignored by SWIG. For example, if you have this code: @@ -723,21 +758,25 @@ declaration does not define a method that operates on an instance of an object nor does it define a declaration in the scope of the class. Therefore, it would make no sense for SWIG to create wrappers as such. -<a name="n18"></a><H2>5.9 References and pointers</H2> +<H2><a name="SWIGPlus_nn18"></a>6.9 References and pointers</H2> -C++ references are supported, but SWIG transforms them back into pointers. For example, -a declaration like this :<p> <p> -<blockquote><pre>class Foo { +C++ references are supported, but SWIG transforms them back into pointers. For example, +a declaration like this :</p> + +<blockquote><pre> +class Foo { public: double bar(double &a); } </pre></blockquote> + <p> -is accessed using a function similar to this:<p> -<p> -<blockquote><pre>double Foo_bar(Foo *obj, double *a) { +is accessed using a function similar to this:</p> + +<blockquote><pre> +double Foo_bar(Foo *obj, double *a) { obj->bar(*a); } </pre></blockquote> @@ -747,7 +786,7 @@ As a special case, most language modules pass <tt>const</tt> references to primi <blockquote> <pre> -void foo(const int &x); +void foo(const int &x); </pre> </blockquote> @@ -765,7 +804,7 @@ For example: <blockquote><pre> class Bar { public: - Foo &spam(); + Foo &spam(); }; </pre> </blockquote> @@ -775,8 +814,8 @@ Generates code like this: <blockquote> <pre> Foo *Bar_spam(Bar *obj) { - Foo &result = obj->spam(); - return &result; + Foo &result = obj->spam(); + return &result; } </pre> </blockquote> @@ -786,7 +825,7 @@ return the result as a value rather than a pointer. For example, a function lik <blockquote> <pre> -const int &bar(); +const int &bar(); </pre> </blockquote> @@ -801,12 +840,15 @@ cause your program to crash. <b>Note:</b> The special treatment for references to primitive datatypes is necessary to provide more seamless integration with more advanced C++ wrapping applications---especially related to templates and the STL. This was first added in SWIG-1.3.12. +</p> -<a name="n19"></a><H2>5.10 Pass and return by value</H2> +<H2><a name="SWIGPlus_nn19"></a>6.10 Pass and return by value</H2> +<p> Occasionally, a C++ program will pass and return class objects by value. For example, a function like this might appear: +</p> <blockquote> <pre> @@ -814,8 +856,10 @@ Vector cross_product(Vector a, Vector b); </pre> </blockquote> +<p> If no information is supplied about <tt>Vector</tt>, SWIG creates a wrapper function similar to the following: +</p> <blockquote> <pre> @@ -835,6 +879,7 @@ If <tt>Vector</tt> is defined as class in the interface, but it does not support a default constructor, SWIG changes the wrapper code by encapsulating the arguments inside a special C++ template wrapper class. This produces a wrapper that looks like this: +</p> <blockquote> <pre> @@ -858,22 +903,26 @@ wrapper around a pointer. <b>Note:</b> this transformation has no effect on typemaps or any other part of SWIG---it should be transparent except that you may see this code when reading the SWIG output file. +</p> <p> <b> Note: </b>This template transformation is new in SWIG-1.3.11 and may be refined in future SWIG releases. In practice, it is only necessary to do this for classes that don't define a default constructor. +</p> <p> <b>Note:</b> The use of this template only occurs when objects are passed or returned by value. It is not used for C++ pointers or references. +</p> <p> <b>Note:</b> The performance of pass-by-value is especially bad for large objects and should be avoided if possible (consider using references instead). +</p> -<a name="n20"></a><H2>5.11 Inheritance</H2> +<H2><a name="SWIGPlus_nn20"></a>6.11 Inheritance</H2> SWIG supports C++ public inheritance of classes and allows both @@ -887,13 +936,14 @@ use with multiple inheritance. parsed, but it has no effect on the generated code). Note: private and protected inheritance do not define an "isa" relationship between classes so it would have no effect on type-checking anyways. +</p> <p> The following example shows how SWIG handles inheritance. For clarity, -the full C++ code has been omitted.<p> +the full C++ code has been omitted.</p> -<p> -<blockquote><pre>// shapes.i +<blockquote><pre> +// shapes.i %module shapes %{ #include "shapes.h" @@ -924,10 +974,10 @@ public: <p> When wrapped into Python, we can now perform the following operations -:<p> +:</p> -<p> -<blockquote><pre>$ python +<blockquote><pre> +$ python >>> import shapes >>> circle = shapes.new_Circle(7) >>> square = shapes.new_Square(10) @@ -943,11 +993,13 @@ When wrapped into Python, we can now perform the following operations >>> </pre></blockquote> +<p> In this example, Circle and Square objects have been created. Member functions can be invoked on each object by making calls to <tt>Circle_area</tt>, <tt>Square_area</tt>, and so on. However, the same results can be accomplished by simply using the <tt>Shape_area</tt> -function on either object.<p> +function on either object. +</p> <p> One important point concerning inheritance is that the low-level @@ -963,16 +1015,19 @@ the attributes <tt>x</tt> and <tt>y</tt> are generated as <tt>Shape_y_get()</tt>, and <tt>Shape_y_set()</tt>. Functions such as <tt>Circle_x_get()</tt> are not available--instead you should use <tt>Shape_x_get()</tt>. +</p> <p> Although the low-level C-like interface is functional, most language modules also produce a higher level OO interface using proxy classes. This approach is described later and can be used to provide a more natural C++ interface. +</p> <p> <b>Note:</b> For the best results, SWIG requires all base classes to be defined in an interface. Otherwise, you may get an warning message like this: +</p> <blockquote> <pre> @@ -980,6 +1035,7 @@ example:18. Nothing known about class 'Foo'. Ignored. </pre> </blockquote> +<p> If any base class is undefined, SWIG still generates correct type relationships. For instance, a function accepting a <tt>Foo *</tt> will accept any object derived from <tt>Foo</tt> regardless of whether @@ -990,9 +1046,11 @@ directive to include the file that defines <tt>Foo</tt>. <tt>%import</tt> simply gathers type information, but doesn't generate wrappers. Alternatively, you could just define <tt>Foo</tt> as an empty class in the SWIG interface. +</p> <p> <b>Note:</b> <tt>typedef</tt>-names <em>can</em> be used as base classes. For example: +</p> <blockquote> <pre> @@ -1036,8 +1094,9 @@ every single module). It is also unnecessary to have such wrappers when advanced features like proxy classes are used. Future versions of SWIG may apply further optimizations such as not regenerating wrapper functions for virtual members that are already defined in a base class. +</p> -<a name="n21"></a><H2>5.12 A brief discussion of multiple inheritance, pointers, and type checking</H2> +<H2><a name="SWIGPlus_nn21"></a>6.12 A brief discussion of multiple inheritance, pointers, and type checking</H2> When a target scripting language refers to a C++ object, it normally @@ -1061,11 +1120,13 @@ pointers are converted into a common data representation in the target language. Typically this is the equivalent of casting a pointer to <tt>void *</tt>. This means that any C++ type information associated with the pointer is lost in the conversion. +</p> <p> The problem with losing type information is that it is needed to properly support many advanced C++ features--especially multiple inheritance. For example, suppose you had code like this: +</p> <blockquote> <pre> @@ -1083,11 +1144,11 @@ class C : public A, public B { }; int A_function(A *a) { - return a->x; + return a->x; } int B_function(B *b) { - return b->y; + return b->y; } </pre> </blockquote> @@ -1133,6 +1194,7 @@ The use of type tags marks all pointers with the real type of the underlying object. This extra information is then used by SWIG generated wrappers to correctly cast pointer values under inheritance (avoiding the above problem). +</p> <p> One might be inclined to fix this problem using some variation of @@ -1140,19 +1202,22 @@ One might be inclined to fix this problem using some variation of work with <tt>void</tt> pointers, it requires RTTI support, and it only works with polymorphic classes (i.e., classes that define one or more virtual functions). +</p> <p> The bottom line: learn to live with type-tagged pointers. +</p> -<a name="n22"></a><H2>5.13 Renaming</H2> +<H2><a name="SWIGPlus_nn22"></a>6.13 Renaming</H2> +<p> C++ member functions and data can be renamed with the <tt>%name</tt> directive. The <tt>%name</tt> directive only replaces the member -function name. For example :<p> +function name. For example :</p> -<p> -<blockquote><pre>class List { +<blockquote><pre> +class List { public: List(); %name(ListSize) List(int maxsize); @@ -1167,17 +1232,21 @@ static void print(List *l); </pre></blockquote> +<p> This will create the functions <tt>List_find</tt>, <tt>List_delete</tt>, and a function named <tt>new_ListSize</tt> for -the overloaded constructor.<p> +the overloaded constructor.</p> + <p> The <tt>%name </tt>directive can be applied to all members including constructors, destructors, static functions, data members, and -enumeration values.<p> -<p> -The class name prefix can also be changed by specifying <p> +enumeration values.</p> + <p> -<blockquote><pre>%name(newname) class List { +The class name prefix can also be changed by specifying </p> + +<blockquote><pre> +%name(newname) class List { ... } </pre></blockquote> @@ -1187,7 +1256,7 @@ overloaded methods, it really doesn't work very well because it requires a lot of additional markup in your interface. Keep reading for a better solution. -<a name="n23"></a><H2>5.14 Wrapping Overloaded Functions and Methods</H2> +<H2><a name="SWIGPlus_nn23"></a>6.14 Wrapping Overloaded Functions and Methods</H2> In many language modules, SWIG provides partial support for overloaded functions, methods, and @@ -1208,11 +1277,11 @@ The function is used in a completely natural way. For example: <blockquote> <pre> ->>> foo(3) +>>> foo(3) x is 3 ->>> foo("hello") +>>> foo("hello") x is 'hello' ->>> +>>> </pre> </blockquote> @@ -1224,7 +1293,7 @@ this code, class Foo { public: Foo(); - Foo(const Foo &); // Copy constructor + Foo(const Foo &); // Copy constructor void bar(int x); void bar(char *s, int y); }; @@ -1235,14 +1304,14 @@ it might be used like this <blockquote> <pre> ->>> f = Foo() # Create a Foo ->>> f.bar(3) ->>> g = Foo(f) # Copy Foo ->>> f.bar("hello",2) +>>> f = Foo() # Create a Foo +>>> f.bar(3) +>>> g = Foo(f) # Copy Foo +>>> f.bar("hello",2) </pre> </blockquote> -<a name="n24"></a><H3>5.14.1 Dispatch function generation</H3> +<H3><a name="SWIGPlus_nn24"></a>6.14.1 Dispatch function generation</H3> The implementation of overloaded functions and methods is somewhat @@ -1268,11 +1337,12 @@ To implement overloading for the scripting languages, SWIG generates a dispatch number of passed arguments and their types. To create this function, SWIG first examines all of the overloaded methods and ranks them according to the following rules: +</p> <ol> <li><b>Number of required arguments.</b> Methods are sorted by increasing number of required arguments. -<p> +</li> <li><b>Argument type precedence.</b> All C++ datatypes are assigned a numeric type precedence value (which is determined by the language module). @@ -1288,13 +1358,16 @@ char 80 Strings 100 (Low) </pre> </blockquote> + Using these precedence values, overloaded methods with the same number of required arguments are sorted in increased order of precedence values. +</li> </ol> <p> This may sound very confusing, but an example will help. Consider the following collection of overloaded methods: +</p> <blockquote> <pre> @@ -1349,8 +1422,9 @@ checked in the same order as they appear in this ranking. <p> If you're still confused, don't worry about it---SWIG is probably doing the right thing. +</p> -<a name="n25"></a><H3>5.14.2 Ambiguity in Overloading</H3> +<H3><a name="SWIGPlus_nn25"></a>6.14.2 Ambiguity in Overloading</H3> Regrettably, SWIG is not able to support every possible use of valid C++ overloading. Consider @@ -1389,28 +1463,30 @@ This is done as SWIG does not know how to disambiguate it from an earlier method <p> Ambiguity problems are known to arise in the following situations: +</p> <ul> <li>Integer conversions. Datatypes such as <tt>int</tt>, <tt>long</tt>, and <tt>short</tt> cannot be disambiguated in some languages. Shown above. +</li> -<p> <li>Floating point conversion. <tt>float</tt> and <tt>double</tt> can not be disambiguated in some languages. +</li> -<p> <li>Pointers and references. For example, <tt>Foo *</tt> and <tt>Foo &</tt>. +</li> -<p> <li>Pointers and arrays. For example, <tt>Foo *</tt> and <tt>Foo [4]</tt>. +</li> -<p> <li>Pointers and instances. For example, <tt>Foo</tt> and <tt>Foo *</tt>. Note: SWIG converts all instances to pointers. +</li> -<p> <li>Qualifiers. For example, <tt>const Foo *</tt> and <tt>Foo *</tt>. +</li> -<p> <li>Default vs. non default arguments. For example, <tt>foo(int a, int b)</tt> and <tt>foo(int a, int b = 3)</tt>. +</li> </ul> When an ambiguity arises, methods are checked in the same order as they appear in the interface file. @@ -1418,6 +1494,7 @@ Therefore, earlier methods will shadow methods that appear later. <p> When wrapping an overloaded function, there is a chance that you will get an error message like this: +</p> <blockquote> <pre> @@ -1434,6 +1511,7 @@ undefined. You should report this as a bug to <p> If you get an error message such as the following, +</p> <blockquote> <pre> @@ -1447,8 +1525,7 @@ foo.i:5. Previous declaration is Spam::foo(int ) it means that the target language module has not yet implemented support for overloaded functions and methods. The only way to fix the problem is to read the next section. -<a name="ambiguity_resolution_renaming"></a> -<a name="n26"></a><H3>5.14.3 Ambiguity resolution and renaming</H3> +<H3><a name="ambiguity_resolution_renaming"></a>6.14.3 Ambiguity resolution and renaming</H3> If an ambiguity in overload resolution occurs or if a module doesn't @@ -1573,6 +1650,7 @@ class prefix <tt>Spam::</tt>. <p> A special form of <tt>%rename</tt> can be used to apply a renaming just to class members (of all classes): +</p> <blockquote> <pre> @@ -1588,6 +1666,7 @@ swig-dev@cs.uchicago.edu). <p> Although this discussion has primarily focused on <tt>%rename</tt> all of the same rules also apply to <tt>%ignore</tt>. For example: +</p> <blockquote> <pre> @@ -1604,6 +1683,7 @@ to disappear. For example, <tt>%ignore Spam::foo(double)</tt> will eliminate <tt <p> <b>Notes on %rename and %ignore:</b> +</p> <ul> <li>Since, the <tt>%rename</tt> declaration is used to declare a renaming in advance, it can be @@ -1621,8 +1701,8 @@ resolution without having to modify header files. For example: %include "header.h" </pre> </blockquote> +</li> -<p> <li>The scope qualifier (::) can also be used on simple names. For example: <blockquote> <pre> @@ -1631,8 +1711,8 @@ resolution without having to modify header files. For example: %rename(bar) *::foo; // Rename foo in classes only </pre> </blockquote> +</li> -<p> <li>Name matching tries to find the most specific match that is defined. A qualified name such as <tt>Spam::foo</tt> always has higher precedence than an unqualified name <tt>foo</tt>. @@ -1643,8 +1723,8 @@ within the same scope level. However, an unparameterized name with a scope qualifier has higher precedence than a parameterized name in global scope (e.g., a renaming of <tt>Spam::foo</tt> takes precedence over a renaming of <tt>foo(int)</tt>). +</li> -<p> <li> The order in which <tt>%rename</tt> directives are defined does not matter as long as they appear before the declarations to be renamed. Thus, there is no difference @@ -1672,13 +1752,13 @@ and this importance). Of course, a repeated <tt>%rename</tt> directive will change the setting for a previous <tt>%rename</tt> directive if exactly the same name, scope, and parameters are supplied. +</li> -<p> <li>For multiple inheritance where renaming rules are defined for multiple base classes, the first renaming rule found on a depth-first traversal of the class hierarchy is used. +</li> -<p> <li>The name matching rules strictly follow member qualification rules. For example, if you have a class like this: @@ -1722,9 +1802,10 @@ above: %ignore Foo::bar() const; // Ignore bar() const, but leave other bar() alone </pre> </blockquote> +</li> </ul> -<a name="n27"></a><H3>5.14.4 Comments on overloading</H3> +<H3><a name="SWIGPlus_nn27"></a>6.14.4 Comments on overloading</H3> Support for overloaded methods was first added in SWIG-1.3.14. The implementation @@ -1737,8 +1818,9 @@ Internally, the overloading mechanism is completely configurable by the target l module. Therefore, the degree of overloading support may vary from language to language. As a general rule, statically typed languages like Java are able to provide more support than dynamically typed languages like Perl, Python, Ruby, and Tcl. +</p> -<a name="n28"></a><H2>5.15 Wrapping overloaded operators</H2> +<H2><a name="SWIGPlus_nn28"></a>6.15 Wrapping overloaded operators</H2> Starting in SWIG-1.3.10, C++ overloaded operator declarations can be wrapped. @@ -1751,19 +1833,19 @@ private: double rpart, ipart; public: Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { } - Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { } - Complex &operator=(const Complex &c) { + Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { } + Complex &operator=(const Complex &c) { rpart = c.rpart; ipart = c.ipart; return *this; } - Complex operator+(const Complex &c) const { + Complex operator+(const Complex &c) const { return Complex(rpart+c.rpart, ipart+c.ipart); } - Complex operator-(const Complex &c) const { + Complex operator-(const Complex &c) const { return Complex(rpart-c.rpart, ipart-c.ipart); } - Complex operator*(const Complex &c) const { + Complex operator*(const Complex &c) const { return Complex(rpart*c.rpart - ipart*c.ipart, rpart*c.ipart + c.rpart*ipart); } @@ -1790,6 +1872,7 @@ operators (mapping them into operators in the target language). However, the underlying implementation of this is really managed in a very general way using the <tt>%rename</tt> directive. For example, in Python a declaration similar to this is used: +</p> <blockquote> <pre> @@ -1806,7 +1889,7 @@ something like this pseudocode: <pre> _wrap_Complex___add__(args) { ... get args ... - obj->operator+(args); + obj->operator+(args); ... } </pre> @@ -1817,9 +1900,9 @@ operator normally. For example: <blockquote> <pre> ->>> a = Complex(3,4) ->>> b = Complex(5,2) ->>> c = a + b # Invokes __add__ method +>>> a = Complex(3,4) +>>> b = Complex(5,2) +>>> c = a + b # Invokes __add__ method </pre> </blockquote> @@ -1863,6 +1946,7 @@ the <tt>operator-</tt> method might be handled. <p> Handling operators in this manner is mostly straightforward. However, there are a few subtle issues to keep in mind: +</p> <ul> <li>In C++, it is fairly common to define different versions of the operators to account for @@ -1872,9 +1956,9 @@ different types. For example, a class might also include a friend function like <pre> class Complex { public: - friend Complex operator+(Complex &, double); + friend Complex operator+(Complex &, double); }; -Complex operator+(Complex &, double); +Complex operator+(Complex &, double); </pre> </blockquote> @@ -1885,30 +1969,35 @@ the class (because it's not a member of the class). <p> It's still possible to make a wrapper for this operator, but you'll have to handle it like a normal function. For example: +</p> <blockquote> <pre> -%rename(add_complex_double) operator+(Complex &, double); +%rename(add_complex_double) operator+(Complex &, double); </pre> </blockquote> +</li> -<p> <li>Certain operators are ignored by default. For instance, <tt>new</tt> and <tt>delete</tt> operators are ignored as well as conversion operators. +</li> -<p> <li>The semantics of certain C++ operators may not match those in the target language. +</li> </ul> -<a name="n29"></a><H2>5.16 Class extension</H2> +<H2><a name="SWIGPlus_nn29"></a>6.16 Class extension</H2> +<p> New methods can be added to a class using the <tt>%extend</tt> directive. This directive is primarily used in conjunction with proxy classes to add additional functionality to an existing class. For -example :<p> -<p> -<blockquote><pre>%module vector +example : +</p> + +<blockquote><pre> +%module vector %{ #include "vector.h" %} @@ -1928,15 +2017,16 @@ public: } }; </pre></blockquote> -<p> +<p> This code adds a<tt> __str__</tt> method to our class for producing a string representation of the object. In Python, such a method would allow us to print the value of an object using the <tt>print</tt> -command. <p> +command. +</p> -<p> -<blockquote><pre>>>> +<blockquote><pre> +>>> >>> v = Vector(); >>> v.x = 3 >>> v.y = 4 @@ -1948,7 +2038,7 @@ command. <p> </pre></blockquote> The<tt> %extend</tt> directive follows all of the same conventions -as its use with C structures. Please refer to the <a href="SWIG.html">SWIG Basics</a> +as its use with C structures. Please refer to the <a href="SWIG.html#SWIG">SWIG Basics</a> chapter for further details. <p> @@ -1956,8 +2046,9 @@ chapter for further details. name for the <tt>%addmethods</tt> directive. Since <tt>%addmethods</tt> could be used to extend a structure with more than just methods, a more suitable directive name has been chosen. +</p> -<a name="n30"></a><H2>5.17 Templates</H2> +<H2><a name="SWIGPlus_nn30"></a>6.17 Templates</H2> In all versions of SWIG, template type names may appear anywhere a type @@ -2007,11 +2098,12 @@ such as <tt>vector<int></tt> is generally not a valid identifier name in most target languages. Thus, you will need to give the template instantiation a more suitable name such as <tt>intvector</tt> when creating a wrapper. +</p> <p> To illustrate, consider the following template definition: +</p> -<p> <blockquote><pre> template<class T> class List { private: @@ -2048,6 +2140,7 @@ because it doesn't know how to generate any code until unless a definition of <p> One way to create wrappers for a specific template instantiation is to simply provide an expanded version of the class directly like this: +</p> <blockquote> <pre> @@ -2078,6 +2171,7 @@ Since manual expansion of templates gets old in a hurry, the <tt>%template</tt> be used to create instantiations of a template class. Semantically, <tt>%template</tt> is simply a shortcut---it expands template code in exactly the same way as shown above. Here are some examples: +</p> <blockquote> <pre> @@ -2107,7 +2201,7 @@ For example: <blockquote> <pre> // Function template -template<class T> T max(T a, T b) { return a > b ? a : b; } +template<class T> T max(T a, T b) { return a > b ? a : b; } // Make some different versions of this function %template(maxint) max<int>; @@ -2121,6 +2215,7 @@ instantiations of the function. <p> The number of arguments supplied to <tt>%template</tt> should match that in the original template definition. Template default arguments are supported. For example: +</p> <blockquote> <pre> @@ -2137,6 +2232,7 @@ template vector<typename T, int max=100> class vector { The <tt>%template</tt> directive should not be used to wrap the same template instantiation more than once in the same scope. This will generate an error. For example: +</p> <blockquote> <pre> @@ -2151,11 +2247,13 @@ identical classes with the same name. This generates a symbol table conflict. Besides, it probably more efficient to only wrap a specific instantiation only once in order to reduce the potential for code bloat. +</p> <p> Since the type system knows how to handle <tt>typedef</tt>, it is generally not necessary to instantiate different versions of a template for typenames that are equivalent. For instance, consider this code: +</p> <blockquote> <pre> @@ -2176,6 +2274,7 @@ redundant and will simply result in code bloat). When a template is instantiated using <tt>%template</tt>, information about that class is saved by SWIG and used elsewhere in the program. For example, if you wrote code like this, +</p> <blockquote> <pre> @@ -2203,6 +2302,7 @@ example.h:42. Maybe you forgot to instantiate 'List<int >' using %template If a template class inherits from another template class, you need to make sure that base classes are instantiated before derived classes. For example: +</p> <blockquote> <pre> @@ -2229,11 +2329,12 @@ properly set up the inheritance hierarchy in the resulting wrapper code (and base classes need to be wrapped before derived classes). Don't worry--if you get the order wrong, SWIG should generate a warning message. -<P> +<p> Occassionally, you may need to tell SWIG about base classes that are defined by templates, but which aren't supposed to be wrapped. Since SWIG is not able to automatically instantiate templates for this purpose, you must do it manually. To do this, simply use <tt>%template</tt> with no name. For example: +</p> <blockquote> <pre> @@ -2245,6 +2346,7 @@ use <tt>%template</tt> with no name. For example: <p> If you have to instantiate a lot of different classes for many different types, you might consider writing a SWIG macro. For example: +</p> <blockquote> <pre> @@ -2264,6 +2366,7 @@ TEMPLATE_WRAP(char *, String) <p> The SWIG template mechanism <em>does</em> support specialization. For instance, if you define a class like this, +</p> <blockquote> <pre> @@ -2292,6 +2395,7 @@ to a specialization to provide customization for specific types. <p> Partial template specialization is partially supported by SWIG. For example, this code defines a template that is applied when the template argument is a pointer. +</p> <blockquote> <pre> @@ -2328,6 +2432,7 @@ Member function templates are supported. The underlying principle is the same as for normal templates--SWIG can't create a wrapper unless you provide more information about types. For example, a class with a member template might look like this: +</p> <blockquote> <pre> @@ -2376,6 +2481,7 @@ must always appear <em>after</em> the definition of the template to be expanded. <p> When used with members, the <tt>%template</tt> directive may be placed in another template class. Here is a slightly perverse example: +</p> <blockquote> <pre> @@ -2403,6 +2509,7 @@ functions <tt>bari()</tt> and <tt>bard()</tt> added. <p> A common use of member templates is to define constructors for copies and conversions. For example: +</p> <blockquote> <pre> @@ -2434,6 +2541,7 @@ the original template definition. <p> Alternatively, you could expand the constructor template in selected instantiations. For example: +</p> <blockquote> <pre> @@ -2456,9 +2564,10 @@ If all of this isn't quite enough and you really want to make someone's head explode, SWIG directives such as <tt>%rename</tt>, <tt>%extend</tt>, and <tt>%typemap</tt> can be included directly in template definitions. For example: +</p> -<p> -<blockquote><pre>// File : list.h +<blockquote><pre> +// File : list.h template<class T> class List { ... public: @@ -2481,6 +2590,7 @@ instantiation. <p> It is also possible to separate these declarations from the template class. For example: +</p> <blockquote> <pre> @@ -2512,6 +2622,7 @@ legal to use the same template parameters as provided in the class definition. These are replaced when the template is expanded. In addition, the <tt>%extend</tt> directive can be used to add additional methods to a specific instantiation. For example: +</p> <blockquote> <pre> @@ -2536,12 +2647,11 @@ check this when it compiles the resulting wrapper file, there is no practical reason for SWIG to duplicate this functionality (besides, none of the SWIG developers are masochistic enough to want to implement this right now). +</p> -<p> Finally, there are a few limitations in SWIG's current support for templates: <ul> -<p> <li>SWIG does not support overloaded versions of a template. Some C++ programs might do this to define overloaded functions. For example: @@ -2568,6 +2678,7 @@ wrapper for the second definition, just do it manually: %name(foo2int) void foo<int>(int x, int y); </pre> </blockquote> +</li> </ul> @@ -2577,10 +2688,12 @@ macro expansion in the preprocessor. Templates have been more tightly integrate the parser and type system in SWIG-1.3.12 and the preprocessor is no longer used. Code that relied on preprocessing features in template expansion will no longer work. However, SWIG still allows the # operator to be used to generate a string from a template argument. +</p> <p> <b>Compatibility Note</b>: In earlier versions of SWIG, the <tt>%template</tt> directive introduced a new class name. This name could then be used with other directives. For example: +</p> <blockquote> <pre> @@ -2605,7 +2718,7 @@ as the class name. For example: Similar changes apply to typemaps and other customization features. -<a name="n31"></a><H2>5.18 Namespaces</H2> +<H2><a name="SWIGPlus_nn31"></a>6.18 Namespaces</H2> Support for C++ namespaces is a relatively late addition to SWIG, @@ -2721,6 +2834,7 @@ default wrapping behavior is to flatten namespaces in the target language. This means that the contents of all namespaces are merged together in the resulting scripting language module. For example, if you have code like this, +</p> <blockquote> <pre> @@ -2753,10 +2867,12 @@ with an additional namespace prefix when the module itself already serves as a namespace in the target language. Or put another way, if you want SWIG to keep namespaces separate, simply wrap each namespace with its own SWIG interface. +</p> <p> Because namespaces are flattened, it is possible for symbols defined in different namespaces to generate a name conflict in the target language. For example: +</p> <blockquote> <pre> @@ -2800,6 +2916,7 @@ Similarly, <tt>%ignore</tt> can be used to ignore declarations. code. They are ignored by SWIG language modules and they do not result in any code. However, these declarations <em>are</em> used by the internal type system to track type-names. Therefore, if you have code like this: +</p> <blockquote> <pre> @@ -2818,6 +2935,7 @@ is the same as <tt>int</tt>. Namespaces may be combined with templates. If necessary, the <tt>%template</tt> directive can be used to expand a template defined in a different namespace. For example: +</p> <blockquote> <pre> @@ -2887,6 +3005,7 @@ they should <em>also</em> appear in any header files that might have been included in a <tt>%{ ... %}</tt> section. In other words, don't insert extra <tt>using</tt> declarations into a SWIG interface unless they also appear in the underlying C++ code. +</p> <p> <b>Note:</b> Code inclusion directives such as <tt>%{ ... %}</tt> or @@ -2894,6 +3013,7 @@ in the underlying C++ code. The code emitted by these directives will not be enclosed in a namespace and you may get very strange results. If you need to use namespaces with these directives, consider the following: +</p> <blockquote> <pre> @@ -2918,6 +3038,7 @@ namespace foo { <p> <b>Note:</b> When the <tt>%extend</tt> directive is used inside a namespace, the namespace name is included in the generated functions. For example, if you have code like this, +</p> <blockquote> <pre> @@ -2939,10 +3060,12 @@ This function resides in the global namespace. <b>Note:</b> Although namespaces are flattened in the target language, the SWIG generated wrapper code observes the same namespace conventions as used in the input file. Thus, if there are no symbol conflicts in the input, there will be no conflicts in the generated code. +</p> <p> <b>Note:</b> Namespaces have a subtle effect on the wrapping of conversion operators. For instance, suppose you had an interface like this: +</p> <blockquote> <pre> @@ -2951,7 +3074,7 @@ namespace foo { class spam { public; ... - operator bar(); // Conversion of spam -> bar + operator bar(); // Conversion of spam -> bar ... }; } @@ -2982,9 +3105,10 @@ a basic namespace implementation. Since namespaces are a new addition to SWIG, none of the target language modules are currently programmed with any namespace awareness. In the future, language modules may or may not provide more advanced namespace support. +</p> -<a name="n32"></a><H2>5.19 Exception specifiers</H2> +<H2><a name="SWIGPlus_nn32"></a>6.19 Exception specifiers</H2> When C++ programs utilize exceptions, exceptional behavior is sometimes specified as @@ -3023,9 +3147,10 @@ Obviously, the exact details of how exceptions are handled depend on the target <p> Since exception specifiers are sometimes only used sparingly, this alone may not be enough to properly handle C++ exceptions. To do that, a different set of special SWIG directives are used. -Consult the "<a href="Customization.html">Customization features</a>" chapter for details. +Consult the "<a href="Customization.html#Customization">Customization features</a>" chapter for details. +</p> -<a name="n33"></a><H2>5.20 Pointers to Members</H2> +<H2><a name="SWIGPlus_nn33"></a>6.20 Pointers to Members</H2> Starting with SWIG1.3.7, there is limited parsing support for pointers to C++ class members. @@ -3035,7 +3160,7 @@ For example: <pre> double do_op(Object *o, double (Object::*callback)(double,double)); extern double (Object::*fooptr)(double,double); -%constant double (Object::*FOO)(double,double) = &Object::foo; +%constant double (Object::*FOO)(double,double) = &Object::foo; </pre> </blockquote> @@ -3048,6 +3173,7 @@ Annotated C++ Manual" for specific details. <p> When pointers to members are supported, the pointer value might appear as a special string like this: +</p> <blockquote> <pre> @@ -3066,8 +3192,9 @@ SWIG's type-checking mechanism is also more limited when working with member pointers. Normally SWIG tries to keep track of inheritance when checking types. However, no such support is currently provided for member pointers. +</p> -<a name="n34"></a><H2>5.21 Smart pointers and operator->()</H2> +<H2><a name="SWIGPlus_nn34"></a>6.21 Smart pointers and operator->()</H2> In some C++ programs, objects are often encapsulated by smart-pointers @@ -3120,8 +3247,8 @@ expressions such as these (from the previous example), <blockquote> <pre> -f->x -f->bar() +f->x +f->bar() </pre> </blockquote> @@ -3129,14 +3256,14 @@ are transparently mapped to the following <blockquote> <pre> -(f.operator->())->x; -(f.operator->())->bar(); +(f.operator->())->x; +(f.operator->())->bar(); </pre> </blockquote> When generating wrappers, SWIG tries to emulate this functionality to the extent that it is possible. To do this, whenever -<tt>operator->()</tt> is encountered in a class, SWIG looks at its +<tt>operator->()</tt> is encountered in a class, SWIG looks at its returned type and uses it to generate wrappers for accessing attributes of the underlying object. For example, wrapping the above code produces wrappers like this: @@ -3144,13 +3271,13 @@ code produces wrappers like this: <blockquote> <pre> int Foo_x_get(Foo *f) { - return (*f)->x; + return (*f)->x; } void Foo_x_set(Foo *f, int value) { - (*f)->x = value; + (*f)->x = value; } void Foo_bar(Foo *f) { - (*f)->bar(); + (*f)->bar(); } </pre> </blockquote> @@ -3164,27 +3291,28 @@ different). <p> The end result is that access looks very similar to C++. For example, you could do this in Python: +</p> <blockquote> <pre> ->>> f = make_Foo() ->>> print f.x +>>> f = make_Foo() +>>> print f.x 0 ->>> f.bar() ->>> +>>> f.bar() +>>> </pre> </blockquote> When generating wrappers through a smart-pointer, SWIG tries to generate wrappers for all methods and attributes that might be -accessible through <tt>operator->()</tt>. This includes any methods +accessible through <tt>operator->()</tt>. This includes any methods that might be accessible through inheritance. However, there are a number of restrictions: <ul> <li>Only member variables and methods are wrapped through a smart pointer. Static members, enumerations, constructors, and destructors are not wrapped. +</li> -<P> <li>If the smart-pointer class and the underlying object both define a method or variable of the same name, then the smart-pointer version has precedence. For example, if you have this code @@ -3199,13 +3327,14 @@ public: class Bar { public: int x; - Foo *operator->(); + Foo *operator->(); }; </pre> </blockquote> then the wrapper for <tt>Bar::x</tt> accesses the <tt>x</tt> defined in <tt>Bar</tt>, and not the <tt>x</tt> defined in <tt>Foo</tt>. +</li> </ul> If your intent is to only expose the smart-pointer class in the interface, it is not necessary to wrap both @@ -3221,7 +3350,7 @@ class Foo { // Ignored class Bar { public: - Foo *operator->(); + Foo *operator->(); ... }; </pre> @@ -3231,31 +3360,34 @@ Alternatively, you can import the definition of <tt>Foo</tt> from a separate fil <tt>%import</tt>. <p> -<b>Note:</b> When a class defines <tt>operator->()</tt>, the operator itself is wrapped +<b>Note:</b> When a class defines <tt>operator->()</tt>, the operator itself is wrapped as a method <tt>__deref__()</tt>. For example: +</p> <blockquote> <pre> f = Foo() # Smart-pointer -p = f.__deref__() # Raw pointer from operator-> +p = f.__deref__() # Raw pointer from operator-> </pre> </blockquote> <p> <b>Note:</b> To disable the smart-pointer behavior, use <tt>%ignore</tt> to ignore -<tt>operator->()</tt>. For example: +<tt>operator->()</tt>. For example: +</p> <blockquote> <pre> -%ignore Bar::operator->; +%ignore Bar::operator->; </pre> </blockquote> <p> <b>Note:</b> Smart pointer support was first added in SWIG-1.3.14. +</p> -<a name="n35"></a><H2>5.22 Using declarations and inheritance</H2> +<H2><a name="SWIGPlus_nn35"></a>6.22 Using declarations and inheritance</H2> <tt>using</tt> declarations are sometimes used to adjust access to members of @@ -3289,9 +3421,9 @@ derived class. For example: <blockquote> <pre> FooBar *f; -f->blah(3); // Ok. Invokes Foo::blah(int) -f->blah(3.5); // Ok. Invokes Bar::blah(double) -f->blah("hello"); // Ok. Invokes FooBar::blah(const char *); +f->blah(3); // Ok. Invokes Foo::blah(int) +f->blah(3.5); // Ok. Invokes Bar::blah(double) +f->blah("hello"); // Ok. Invokes FooBar::blah(const char *); </pre> </blockquote> @@ -3300,11 +3432,11 @@ you wrap this code in Python, the module works just like you would expect: <blockquote> <pre> ->>> import example ->>> f = example.FooBar() ->>> f.blah(3) ->>> f.blah(3.5) ->>> f.blah("hello") +>>> import example +>>> f = example.FooBar() +>>> f.blah(3) +>>> f.blah(3.5) +>>> f.blah("hello") </pre> </blockquote> @@ -3334,6 +3466,7 @@ from the base classes are copied into the derived class and wrapped normally. W copied, the declarations retain any properties that might have been attached using <tt>%rename</tt>, <tt>%ignore</tt>, or <tt>%feature</tt>. Thus, if a method is ignored in a base class, it will also be ignored by a <tt>using</tt> declaration. +</p> <p> Because a <tt>using</tt> declaration does not provide fine-grained @@ -3341,6 +3474,7 @@ control over the declarations that get imported, it may be difficult to manage such declarations in applications that make heavy use of SWIG customization features. If you can't get <tt>using</tt> to work correctly, you can always change the interface to the following: +</p> <blockquote> <pre> @@ -3403,7 +3537,7 @@ public: </blockquote> </ul> -<a name="n36"></a><H2>5.23 Partial class definitions</H2> +<H2><a name="SWIGPlus_nn36"></a>6.23 Partial class definitions</H2> Since SWIG is still limited in its support of C++, it may be necessary @@ -3432,8 +3566,9 @@ public: <p> Also, as a rule of thumb, SWIG should not be used on raw C++ source files. +</p> -<a name="n37"></a><H2>5.24 A brief rant about const-correctness</H2> +<H2><a name="SWIGPlus_nn37"></a>6.24 A brief rant about const-correctness</H2> A common issue when working with C++ programs is dealing with all @@ -3448,6 +3583,7 @@ free of const-related warnings, SWIG does not make any attempt to preserve const-correctness in the target language. Thus, it is possible to pass <tt>const</tt> qualified objects to non-const methods and functions. For example, consider the following code in C++: +</p> <blockquote> <pre> @@ -3466,8 +3602,8 @@ Now, consider the behavior when wrapped into a Python module: <blockquote> <pre> ->>> bar(foo()) # Okay ->>> +>>> bar(foo()) # Okay +>>> </pre> </blockquote> @@ -3482,8 +3618,9 @@ The bottom line is that this particular issue does not appear to be a problem for most SWIG projects. Of course, you might want to consider using another tool if maintaining constness is the most important part of your project. +</p> -<a name="n38"></a><H2>5.25 Proxy classes</H2> +<H2><a name="SWIGPlus_nn38"></a>6.25 Proxy classes</H2> In order to provide a more natural API, many of SWIG's target @@ -3493,7 +3630,7 @@ For example, if you're building a Python module, each C++ class is wrapped with Python class. Or if you're building a Java module, each C++ class is wrapped by a Java class. -<a name="n39"></a><H3>5.25.1 Construction of proxy classes</H3> +<H3><a name="SWIGPlus_nn39"></a>6.25.1 Construction of proxy classes</H3> Proxy classes are always constructed as an extra layer of wrapping that uses the low-level @@ -3568,8 +3705,9 @@ proxy classes. <p> Whenever possible, proxies try to take advantage of language features that are similar to C++. This might include operator overloading, exception handling, and other features. +</p> -<a name="n40"></a><H3>5.25.2 Resource management in proxies</H3> +<H3><a name="SWIGPlus_nn40"></a>6.25.2 Resource management in proxies</H3> A major issue with proxies concerns the memory management of wrapped objects. Consider the following @@ -3633,11 +3771,13 @@ to be destroyed. Later on, the statement <tt>del f</tt> destroys the other proxy class. Of course, there is still a reference to the original object stored inside another C++ object. What happens to it? Is it the object still valid? +</p> -<P> +<p> To deal with memory management problems, proxy classes always provide an API for controlling ownership. In C++ pseudocode, ownership control might look roughly like this: +</p> <blockquote> <pre> @@ -3677,8 +3817,8 @@ class SpamProxy { return FooPtrProxy(Spam_value_get(self)); } void value_set(FooProxy *v) { - Spam_value_set(self,v->self); - v->disown(); + Spam_value_set(self,v->self); + v->disown(); } ... }; @@ -3690,40 +3830,41 @@ Looking at this code, there are a few central features: <ul> <li>Each proxy class keeps an extra flag to indicate ownership. C++ objects are only destroyed if the ownership flag is set. +</li> -<P> <li>When new objects are created in the target language, the ownership flag is set. +</li> -<p> <li>When a reference to an internal C++ object is returned, it is wrapped by a proxy class, but the proxy class does not have ownership. +</li> -<p> <li>In certain cases, ownership is adjusted. For instance, when a value is assigned to the member of a class, ownership is lost. +</li> -<p> <li>Manual ownership control is provided by special <tt>disown()</tt> and <tt>acquire()</tt> methods. +</li> </ul> Given the tricky nature of C++ memory management, it is impossible for proxy classes to automatically handle every possible memory management problem. However, proxies do provide a mechanism for manual control that can be used (if necessary) to address some of the more tricky memory management problems. -<a name="n41"></a><H3>5.25.3 Language specific details</H3> +<H3><a name="SWIGPlus_nn41"></a>6.25.3 Language specific details</H3> Language specific details on proxy classes are contained the chapters describing each target language. This chapter has merely introduced the topic in a very general way. -<a name="n42"></a><H2>5.26 Where to go for more information</H2> +<H2><a name="SWIGPlus_nn42"></a>6.26 Where to go for more information</H2> If you're wrapping serious C++ code, you might want to pick up a copy of "The Annotated C++ Reference Manual" by Ellis and Stroustrup. This is the reference document we use to guide a lot of SWIG's C++ support. -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : April 3, 2003</address> </body> diff --git a/Doc/Manual/Scripting.html b/Doc/Manual/Scripting.html index 8dfd6e611..ee6f5f0ba 100644 --- a/Doc/Manual/Scripting.html +++ b/Doc/Manual/Scripting.html @@ -5,23 +5,23 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>3 Scripting Languages</H1> +<H1><a name="Scripting"></a>4 Scripting Languages</H1> <!-- INDEX --> <ul> -<li><a href="#n2">The two language view of the world</a> -<li><a href="#n3">How does a scripting language talk to C?</a> +<li><a href="#Scripting_nn2">The two language view of the world</a> +<li><a href="#Scripting_nn3">How does a scripting language talk to C?</a> <ul> -<li><a href="#n4">Wrapper functions</a> -<li><a href="#n5">Variable linking</a> -<li><a href="#n6">Constants</a> -<li><a href="#n7">Structures and classes</a> -<li><a href="#n8">Shadow classes</a> +<li><a href="#Scripting_nn4">Wrapper functions</a> +<li><a href="#Scripting_nn5">Variable linking</a> +<li><a href="#Scripting_nn6">Constants</a> +<li><a href="#Scripting_nn7">Structures and classes</a> +<li><a href="#Scripting_nn8">Shadow classes</a> </ul> -<li><a href="#n9">Building scripting language extensions</a> +<li><a href="#Scripting_nn9">Building scripting language extensions</a> <ul> -<li><a href="#n10">Shared libraries and dynamic loading</a> -<li><a href="#n11">Linking with shared libraries</a> -<li><a href="#n12">Static linking</a> +<li><a href="#Scripting_nn10">Shared libraries and dynamic loading</a> +<li><a href="#Scripting_nn11">Linking with shared libraries</a> +<li><a href="#Scripting_nn12">Static linking</a> </ul> </ul> <!-- INDEX --> @@ -32,16 +32,17 @@ This chapter provides a brief overview of scripting language extension programming and the mechanisms by which scripting language interpreters access C and C++ code. -<a name="n2"></a><H2>3.1 The two language view of the world</H2> +<H2><a name="Scripting_nn2"></a>4.1 The two language view of the world</H2> +<p> When a scripting language is used to control a C program, the resulting system tends to look as follows: +</p> -<p><center><img src="ch2.1.png"></center><p> -<p> -<p> +<center><img src="ch2.1.png" alt="Scripting language input - C/C++ functions output"></center> +<p> In this programming model, the scripting language interpreter is used for high level control whereas the underlying functionality of the C/C++ program is accessed through special scripting language @@ -52,6 +53,7 @@ If you have ever used a package such as MATLAB or IDL, it is a very similar model--the interpreter executes user commands and scripts. However, most of the underlying functionality is written in a low-level language like C or Fortran. +</p> <p> The two-language model of computing is extremely powerful because it @@ -59,9 +61,9 @@ exploits the strengths of each language. C/C++ can be used for maximal performance and complicated systems programming tasks. Scripting languages can be used for rapid prototyping, interactive debugging, scripting, and access to high-level data structures such associative -arrays. <p> +arrays. </p> -<a name="n3"></a><H2>3.2 How does a scripting language talk to C?</H2> +<H2><a name="Scripting_nn3"></a>4.2 How does a scripting language talk to C?</H2> Scripting languages are built around a parser that knows how @@ -82,14 +84,16 @@ and the underlying C function. Then you need to give the interpreter information about the wrapper by providing details about the name of the function, arguments, and so forth. The next few sections illustrate the process. +</p> -<a name="n4"></a><H3>3.2.1 Wrapper functions</H3> +<H3><a name="Scripting_nn4"></a>4.2.1 Wrapper functions</H3> -Suppose you have an ordinary C function like this :<p> - <p> -<blockquote><pre>int fact(int n) { +Suppose you have an ordinary C function like this :</p> + +<blockquote><pre> +int fact(int n) { if (n <= 1) return 1; else return n*fact(n-1); } @@ -99,18 +103,17 @@ Suppose you have an ordinary C function like this :<p> In order to access this function from a scripting language, it is necessary to write a special "wrapper" function that serves as the glue between the scripting language and the underlying C function. A -wrapper function must do three things :<p> +wrapper function must do three things :</p> -<p> <ul> <li>Gather function arguments and make sure they are valid. <li>Call the C function. <li>Convert the return value into a form recognized by the scripting language. </ul> -<p> +<p> As an example, the Tcl wrapper function for the <tt>fact()</tt> -function above example might look like the following : <p> +function above example might look like the following : </p> <blockquote><pre> int wrap_fact(ClientData clientData, Tcl_Interp *interp, @@ -129,14 +132,15 @@ int wrap_fact(ClientData clientData, Tcl_Interp *interp, </pre></blockquote> +<p> Once you have created a wrapper function, the final step is to tell the scripting language about the new function. This is usually done in an initialization function called by the language when the module is loaded. For example, adding the above function to the Tcl interpreter -requires code like the following :<p> +requires code like the following :</p> -<p> -<blockquote><pre>int Wrap_Init(Tcl_Interp *interp) { +<blockquote><pre> +int Wrap_Init(Tcl_Interp *interp) { Tcl_CreateCommand(interp, "fact", wrap_fact, (ClientData) NULL, (Tcl_CmdDeleteProc *) NULL); return TCL_OK; @@ -145,41 +149,42 @@ requires code like the following :<p> <p> When executed, Tcl will now have a new command called "<tt>fact</tt>" -that you can use like any other Tcl command.<p> +that you can use like any other Tcl command.</p> <p> Although the process of adding a new function to Tcl has been illustrated, the procedure is almost identical for Perl and Python. Both require special wrappers to be written and both need additional initialization code. Only the specific details are -different.<p> +different.</p> -<a name="n5"></a><H3>3.2.2 Variable linking</H3> +<H3><a name="Scripting_nn5"></a>4.2.2 Variable linking</H3> +<p> Variable linking refers to the problem of mapping a C/C++ global variable to a variable in the scripting language interpeter. For example, suppose you had the following -variable:<p> -<p> +variable:</p> -<blockquote><pre>double Foo = 3.5; +<blockquote><pre> +double Foo = 3.5; </pre></blockquote> <p> -It might be nice to access it from a script as follows (shown for Perl):<p> +It might be nice to access it from a script as follows (shown for Perl):</p> -<p> -<blockquote><pre>$a = $Foo * 2.3; # Evaluation +<blockquote><pre> +$a = $Foo * 2.3; # Evaluation $Foo = $a + 2.0; # Assignment </pre></blockquote> <p> - To provide such access, variables are commonly manipulated using a pair of get/set functions. For example, whenever the value of a variable is read, a "get" function is invoked. Similarly, whenever the value of a variable is changed, a "set" function is called. +</p> <p> In many languages, calls to the get/set functions can be attached to @@ -187,14 +192,16 @@ evaluation and assignment operators. Therefore, evaluating a variable such as <tt>$Foo</tt> might implicitly call the get function. Similarly, typing <tt>$Foo = 4</tt> would call the underlying set function to change the value. +</p> -<a name="n6"></a><H3>3.2.3 Constants</H3> +<H3><a name="Scripting_nn6"></a>4.2.3 Constants</H3> In many cases, a C program or library may define a large collection of constants. For example: -<blockquote><pre>#define RED 0xff0000 +<blockquote><pre> +#define RED 0xff0000 #define BLUE 0x0000ff #define GREEN 0x00ff00 </pre></blockquote> @@ -205,7 +212,7 @@ language variables such as <tt>$RED</tt>, <tt>$BLUE</tt>, and functions for creating variables so installing constants is usually a trivial exercise. -<a name="n7"></a><H3>3.2.4 Structures and classes</H3> +<H3><a name="Scripting_nn7"></a>4.2.4 Structures and classes</H3> Although scripting languages have no trouble accessing simple @@ -220,19 +227,20 @@ does C++ inheritance mean in a Perl interface? The most straightforward technique for handling structures is to implement a collection of accessor functions that hide the underlying representation of a structure. For example, +</p> -<p> -<blockquote><pre>struct Vector { +<blockquote><pre> +struct Vector { Vector(); ~Vector(); double x,y,z; }; </pre></blockquote> -can be transformed into the following set of functions :<p> +can be transformed into the following set of functions : -<p> -<blockquote><pre>Vector *new_Vector(); +<blockquote><pre> +Vector *new_Vector(); void delete_Vector(Vector *v); double Vector_x_get(Vector *v); double Vector_y_get(Vector *v); @@ -245,29 +253,31 @@ void Vector_z_set(Vector *v, double z); Now, from an interpreter these function might be used as follows: -<p> -<blockquote><pre>% set v [new_Vector] +<blockquote><pre> +% set v [new_Vector] % Vector_x_set $v 3.5 % Vector_y_get $v % delete_Vector $v % ... </pre></blockquote> -<p> +<p> Since accessor functions provide a mechanism for accessing the internals of an object, the interpreter does not need to know anything about the actual representation of a <tt>Vector</tt>. +</p> -<a name="n8"></a><H3>3.2.5 Shadow classes</H3> +<H3><a name="Scripting_nn8"></a>4.2.5 Shadow classes</H3> +<p> In certain cases, it is possible to use the low-level accessor functions to create something known as a "shadow" class. A "shadow 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 "shadows" the real C++ class). For example, if you -have the following C definition :<p> +have the following C definition :</p> <blockquote><pre> class Vector { @@ -277,13 +287,14 @@ public: double x,y,z; }; </pre></blockquote> -<p> +<p> A shadow classing mechanism would allow you to access the structure in a more natural manner from the interpreter. For example, in Python, you might want to do this: +</p> -<p> -<blockquote><pre>>>> v = Vector() +<blockquote><pre> +>>> v = Vector() >>> v.x = 3 >>> v.y = 4 >>> v.z = -13 @@ -292,7 +303,7 @@ a more natural manner from the interpreter. For example, in Python, you might wa </pre></blockquote> <p> -Similarly, in Perl5 you may want the interface to work like this:<p> +Similarly, in Perl5 you may want the interface to work like this:</p> <blockquote><pre> $v = new Vector; @@ -302,7 +313,7 @@ $v->{z} = -13; </pre></blockquote> -Finally, in Tcl :<p> +Finally, in Tcl : <blockquote><pre> Vector v @@ -310,14 +321,17 @@ v configure -x 3 -y 4 -z 13 </pre></blockquote> +<p> When shadow classes are used, two objects are at really 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> -<a name="n9"></a><H2>3.3 Building scripting language extensions</H2> +<H2><a name="Scripting_nn9"></a>4.3 Building scripting language extensions</H2> +<p> 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 @@ -325,16 +339,18 @@ this. The preferred technique is to build a dynamically loadable extension in the form a shared library. Alternatively, you can recompile the scripting language interpreter with your extensions added to it. +</p> -<a name="n10"></a><H3>3.3.1 Shared libraries and dynamic loading</H3> +<H3><a name="Scripting_nn10"></a>4.3.1 Shared libraries and dynamic loading</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 machines is shown below:</p> -<p> -<blockquote><pre># Build a shared library for Solaris +<blockquote><pre> +# Build a shared library for Solaris gcc -c example.c example_wrap.c -I/usr/local/include ld -G example.o example_wrap.o -o example.so @@ -348,12 +364,14 @@ ld -shared example.o example_wrap.o -o example.so </pre></blockquote> +<p> To use your shared library, you simply use the corresponding command in the scripting language (load, import, use, etc...). This will import your module and allow you to start using it. For example: +</p> -<p> -<blockquote><pre>% load ./example.so +<blockquote><pre> +% load ./example.so % fact 4 24 % @@ -364,24 +382,24 @@ When working with C++ codes, the process of building shared libraries may be more complicated--primarily due to the fact that C++ modules may need additional code in order to operate correctly. On many machines, you can build a shared C++ module by following the above procedures, but -changing the link line to the following :<p> +changing the link line to the following :</p> -<p> -<blockquote><pre>c++ -shared example.o example_wrap.o -o example.so +<blockquote><pre> +c++ -shared example.o example_wrap.o -o example.so </pre></blockquote> -<p> -<a name="n11"></a><H3>3.3.2 Linking with shared libraries</H3> +<H3><a name="Scripting_nn11"></a>4.3.2 Linking with shared libraries</H3> +<p> When building extensions as shared libraries, it is not uncommon for your extension to rely upon other shared libraries on your machine. In order for the extension to work, it needs to be able to find all of these libraries at run-time. Otherwise, you may get an error such as -the following :<p> +the following :</p> -<p> -<blockquote><pre>>>> import graph +<blockquote><pre> +>>> import graph Traceback (innermost last): File "<stdin>", line 1, in ? File "/home/sci/data1/beazley/graph/graph.py", line 2, in ? @@ -396,8 +414,8 @@ lib/libgraph.so:/lib/cmplrs/cc/libgraph.so:/usr/lib/cmplrs/cc/libgraph.so: What this error means is that the extension module created by SWIG depends upon a shared library called "<tt>libgraph.so</tt>" that the system was unable to locate. To fix this problem, there are a few -approaches you can take.<p> -<p> +approaches you can take.</p> + <ul> <li>Link your extension and explicitly tell the linker where the required libraries are located. Often times, this can be done with a @@ -417,23 +435,25 @@ the path using linker options instead. </ul> -<a name="n12"></a><H3>3.3.3 Static linking</H3> +<H3><a name="Scripting_nn12"></a>4.3.3 Static linking</H3> +<p> With static linking, you rebuild the scripting language interpreter with extensions. The process usually involves compiling a short main program that adds your customized commands to the language and starts the interpreter. You then link your program with a library to produce a new scripting language executable. +</p> <p> Although static linking is supported on all platforms, this is not the preferred technique for building scripting language extensions. In fact, there are very few practical reasons for doing this--consider using shared libraries instead. +</p> -<p><hr> - +<hr> <address>SWIG 1.3 - Last Modified : July 16, 2001</address> </body> </html> diff --git a/Doc/Manual/Tcl.html b/Doc/Manual/Tcl.html index aec76f268..64a57cb3f 100644 --- a/Doc/Manual/Tcl.html +++ b/Doc/Manual/Tcl.html @@ -5,64 +5,64 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>24 SWIG and Tcl</H1> +<H1><a name="Tcl"></a>27 SWIG and Tcl</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Preliminaries</a> +<li><a href="#Tcl_nn2">Preliminaries</a> <ul> -<li><a href="#n3">Getting the right header files</a> -<li><a href="#n4">Compiling a dynamic module</a> -<li><a href="#n5">Static linking</a> -<li><a href="#n6">Using your module</a> -<li><a href="#n7">Compilation of C++ extensions</a> -<li><a href="#n8">Compiling for 64-bit platforms</a> -<li><a href="#n9">Setting a package prefix</a> -<li><a href="#n10">Using namespaces</a> +<li><a href="#Tcl_nn3">Getting the right header files</a> +<li><a href="#Tcl_nn4">Compiling a dynamic module</a> +<li><a href="#Tcl_nn5">Static linking</a> +<li><a href="#Tcl_nn6">Using your module</a> +<li><a href="#Tcl_nn7">Compilation of C++ extensions</a> +<li><a href="#Tcl_nn8">Compiling for 64-bit platforms</a> +<li><a href="#Tcl_nn9">Setting a package prefix</a> +<li><a href="#Tcl_nn10">Using namespaces</a> </ul> -<li><a href="#n11">Building Tcl/Tk Extensions under Windows 95/NT</a> +<li><a href="#Tcl_nn11">Building Tcl/Tk Extensions under Windows 95/NT</a> <ul> -<li><a href="#n12">Running SWIG from Developer Studio</a> -<li><a href="#n13">Using NMAKE</a> +<li><a href="#Tcl_nn12">Running SWIG from Developer Studio</a> +<li><a href="#Tcl_nn13">Using NMAKE</a> </ul> -<li><a href="#n14">A tour of basic C/C++ wrapping</a> +<li><a href="#Tcl_nn14">A tour of basic C/C++ wrapping</a> <ul> -<li><a href="#n15">Modules</a> -<li><a href="#n16">Functions</a> -<li><a href="#n17">Global variables</a> -<li><a href="#n18">Constants and enums</a> -<li><a href="#n19">Pointers</a> -<li><a href="#n20">Structures</a> -<li><a href="#n21">C++ classes</a> -<li><a href="#n22">C++ inheritance</a> -<li><a href="#n23">Pointers, references, values, and arrays</a> -<li><a href="#n24">C++ overloaded functions</a> -<li><a href="#n25">C++ operators</a> -<li><a href="#n26">C++ namespaces</a> -<li><a href="#n27">C++ templates</a> -<li><a href="#n28">C++ Smart Pointers</a> +<li><a href="#Tcl_nn15">Modules</a> +<li><a href="#Tcl_nn16">Functions</a> +<li><a href="#Tcl_nn17">Global variables</a> +<li><a href="#Tcl_nn18">Constants and enums</a> +<li><a href="#Tcl_nn19">Pointers</a> +<li><a href="#Tcl_nn20">Structures</a> +<li><a href="#Tcl_nn21">C++ classes</a> +<li><a href="#Tcl_nn22">C++ inheritance</a> +<li><a href="#Tcl_nn23">Pointers, references, values, and arrays</a> +<li><a href="#Tcl_nn24">C++ overloaded functions</a> +<li><a href="#Tcl_nn25">C++ operators</a> +<li><a href="#Tcl_nn26">C++ namespaces</a> +<li><a href="#Tcl_nn27">C++ templates</a> +<li><a href="#Tcl_nn28">C++ Smart Pointers</a> </ul> -<li><a href="#n29">Further details on the Tcl class interface</a> +<li><a href="#Tcl_nn29">Further details on the Tcl class interface</a> <ul> -<li><a href="#n30">Proxy classes</a> -<li><a href="#n31">Memory management</a> +<li><a href="#Tcl_nn30">Proxy classes</a> +<li><a href="#Tcl_nn31">Memory management</a> </ul> -<li><a href="#n32">Input and output parameters</a> -<li><a href="#n33">Exception handling </a> -<li><a href="#n34">Typemaps</a> +<li><a href="#Tcl_nn32">Input and output parameters</a> +<li><a href="#Tcl_nn33">Exception handling </a> +<li><a href="#Tcl_nn34">Typemaps</a> <ul> -<li><a href="#n35">What is a typemap?</a> -<li><a href="#n36">Tcl typemaps</a> -<li><a href="#n37">Typemap variables</a> -<li><a href="#n38">Converting a Tcl list to a char ** </a> -<li><a href="#n39">Returning values in arguments</a> -<li><a href="#n40">Useful functions</a> -<li><a href="#n41">Standard typemaps</a> -<li><a href="#n42">Pointer handling</a> +<li><a href="#Tcl_nn35">What is a typemap?</a> +<li><a href="#Tcl_nn36">Tcl typemaps</a> +<li><a href="#Tcl_nn37">Typemap variables</a> +<li><a href="#Tcl_nn38">Converting a Tcl list to a char ** </a> +<li><a href="#Tcl_nn39">Returning values in arguments</a> +<li><a href="#Tcl_nn40">Useful functions</a> +<li><a href="#Tcl_nn41">Standard typemaps</a> +<li><a href="#Tcl_nn42">Pointer handling</a> </ul> -<li><a href="#n43">Turning a SWIG module into a Tcl Package.</a> -<li><a href="#n44">Building new kinds of Tcl interfaces (in Tcl)</a> +<li><a href="#Tcl_nn43">Turning a SWIG module into a Tcl Package.</a> +<li><a href="#Tcl_nn44">Building new kinds of Tcl interfaces (in Tcl)</a> <ul> -<li><a href="#n45">Shadow classes</a> +<li><a href="#Tcl_nn45">Shadow classes</a> </ul> </ul> <!-- INDEX --> @@ -75,20 +75,25 @@ This chapter discusses SWIG's support of Tcl. SWIG currently requires Tcl 8.0 or a later release. Earlier releases of SWIG supported Tcl 7.x, but this is no longer supported. +</p> -<a name="n2"></a><H2>24.1 Preliminaries</H2> +<H2><a name="Tcl_nn2"></a>27.1 Preliminaries</H2> -To build a Tcl module, run SWIG using the <tt>-tcl</tt> option :<p> - <p> -<blockquote><pre>$ swig -tcl example.i +To build a Tcl module, run SWIG using the <tt>-tcl</tt> option : +</p> + +<blockquote><pre> +$ swig -tcl example.i </pre></blockquote> +<p> If building a C++ extension, add the <tt>-c++</tt> option: +</p> -<p> -<blockquote><pre>$ swig -c++ -tcl example.i +<blockquote><pre> +$ swig -c++ -tcl example.i </pre></blockquote> <p> @@ -96,35 +101,41 @@ This creates a file <tt>example_wrap.c</tt> or <tt>example_wrap.cxx</tt> that contains all of the code needed to 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> -<a name="n3"></a><H3>24.1.1 Getting the right header files</H3> +<H3><a name="Tcl_nn3"></a>27.1.1 Getting the right header files</H3> +<p> In order to compile the wrapper code, the compiler needs the <tt>tcl.h</tt> header file. This file is usually contained in the directory +</p> -<p> -<blockquote><pre>/usr/local/include +<blockquote><pre> +/usr/local/include </pre></blockquote> Be aware that some Tcl versions install this header file with a version number attached to it. If this is the case, you should probably make a symbolic link so that <tt>tcl.h</tt> points to the correct header file. -<a name="n4"></a><H3>24.1.2 Compiling a dynamic module</H3> +<H3><a name="Tcl_nn4"></a>27.1.2 Compiling a dynamic module</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 using comands like this (shown for Linux): +</p> -<p> -<blockquote><pre>$ swig -tcl example.i +<blockquote><pre> +$ swig -tcl example.i $ gcc -c example.c $ gcc -c example_wrap.c -I/usr/local/include $ gcc -shared example.o example_wrap.o -o example.so </pre></blockquote> +<p> The exact commands for doing this vary from platform to platform. SWIG tries to guess the right options when it is installed. Therefore, you may want to start with one of the examples in the <tt>SWIG/Examples/tcl</tt> @@ -132,23 +143,28 @@ directory. If that doesn't work, you will need to read the man-pages for your compiler and linker to get the right set of options. You might also check the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">SWIG Wiki</a> for additional information. +</p> + <p> When linking the module, the name of the output file has to match the name 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.<p> +<tt> -module</tt> command line option. +</p> -<a name="n5"></a><H3>24.1.3 Static linking</H3> +<H3><a name="Tcl_nn5"></a>27.1.3 Static linking</H3> +<p> An alternative approach to dynamic linking is to rebuild the Tcl interpreter with your extension module added to it. In the past, this approach was sometimes necesssary due to limitations in dynamic loading support on certain machines. However, the situation has improved greatly over the last few years and you should not consider this approach unless there is really no other option. +</p> <p> The usual procedure for adding a new module to Tcl involves writing a @@ -156,9 +172,10 @@ special function <tt>Tcl_AppInit()</tt> and using it to initialize the interpret your module. With SWIG, the <tt>tclsh.i</tt> and <tt>wish.i</tt> library files can be used to rebuild the <tt>tclsh</tt> and <tt>wish</tt> interpreters respectively. For example: +</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example extern int fact(int); extern int mod(int, int); @@ -168,12 +185,14 @@ extern double My_variable; </pre></blockquote> +<p> The <tt>tclsh.i</tt> library file includes supporting code that contains everything needed to rebuild tclsh. To rebuild the interpreter, you simply do something like this: +</p> -<p> -<blockquote><pre>$ swig -tcl example.i +<blockquote><pre> +$ swig -tcl example.i $ gcc example.c example_wrap.c \ -Xlinker -export-dynamic \ -DHAVE_CONFIG_H -I/usr/local/include/ \ @@ -181,29 +200,34 @@ $ gcc example.c example_wrap.c \ -o mytclsh </pre></blockquote> + +<p> You will need to supply the same libraries that were used to build Tcl the first time. This may include system libraries such as <tt>-lsocket</tt>, <tt>-lnsl</tt>, and <tt>-lpthread</tt>. If this actually works, the new version of Tcl should be identical to the default version except that your extension module will be a built-in part of the interpreter. +</p> <p> - <b>Comment:</b> In practice, you should probably try to avoid static linking if possible. Some programmers may be inclined to use static linking in the interest of getting better performance. However, the performance gained by static linking tends to be rather minimal in most situations (and quite frankly not worth the extra hassle in the opinion of this author). +</p> -<a name="n6"></a><H3>24.1.4 Using your module</H3> +<H3><a name="Tcl_nn6"></a>27.1.4 Using your module</H3> +<p> To use your module, simply use the Tcl <tt>load</tt> command. If all goes well, you will be able to this: +</p> -<p> -<blockquote><pre>$ tclsh +<blockquote><pre> +$ tclsh % load ./example.so % fact 4 24 @@ -220,14 +244,17 @@ couldn't find procedure Example_Init </pre> </blockquote> +<p> This error is almost always caused when the name of the shared object file doesn't match the name of the module supplied using the SWIG <tt>%module</tt> directive. Double-check the interface to make sure the module name and the shared object file match. Another possible cause of this error is forgetting to link the SWIG-generated wrapper code with the rest of your application when creating the extension module. +</p> <p> Another common error is something similar to the following: +</p> <blockquote> <pre> @@ -237,11 +264,13 @@ couldn't load file "./example.so": ./example.so: undefined symbol: fact </pre> </blockquote> +<p> This error usually indicates that you forgot to include some object files or libraries in the linking of the shared library file. Make sure you compile both the SWIG wrapper file and your original program into a shared library file. Make sure you pass all of the required libraries to the linker. +</p> <p> Sometimes unresolved symbols occur because a wrapper has been created @@ -251,9 +280,11 @@ was never actually implemented or it was removed from a library without updating the header file. To fix this, you can either edit the SWIG input file to remove the offending declaration or you can use the <tt>%ignore</tt> directive to ignore the declaration. +</p> <p> Finally, suppose that your extension module is linked with another library like this: +</p> <blockquote> <pre> @@ -305,38 +336,45 @@ Finally, you can use a command such as <tt>ldconfig</tt> to add additional searc to the default system configuration (this requires root access and you will need to read the man pages). -<a name="n7"></a><H3>24.1.5 Compilation of C++ extensions</H3> +<H3><a name="Tcl_nn7"></a>27.1.5 Compilation of C++ extensions</H3> +<p> Compilation of C++ extensions has traditionally been a tricky problem. Since the Tcl interpreter is written in C, you need to take steps to make sure C++ is properly initialized and that modules are compiled correctly. +</p> <p> On most machines, C++ extension modules should be linked using the C++ compiler. For example: +</p> -<p> -<blockquote><pre>% swig -c++ -tcl example.i +<blockquote><pre> +% swig -c++ -tcl example.i % g++ -c example.cxx % g++ -c example_wrap.cxx -I/usr/local/include % g++ -shared example.o example_wrap.o -o example.so </pre></blockquote> +<p> In addition to this, you may need to include additional library files to make it work. For example, if you are using the Sun C++ compiler on Solaris, you often need to add an extra library <tt>-lCrun</tt> like this: +</p> -<p> -<blockquote><pre>% swig -c++ -tcl example.i +<blockquote><pre> +% swig -c++ -tcl example.i % CC -c example.cxx % CC -c example_wrap.cxx -I/usr/local/include % CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o example.so -lCrun </pre></blockquote> +<p> Of course, the extra libraries to use are completely non-portable---you will probably need to do some experimentation. +</p> <p> Sometimes people have suggested that it is necessary to relink the @@ -345,6 +383,7 @@ In the experience of this author, this has never actually appeared to be necessary. Relinking the interpreter with C++ really only includes the special run-time libraries described above---as long as you link your extension modules with these libraries, it should not be necessary to rebuild Tcl. +</p> <p> If you aren't entirely sure about the linking of a C++ extension, you @@ -352,14 +391,15 @@ might look at an existing C++ program. On many Unix machines, the <tt>ldd</tt> command will list library dependencies. This should give you some clues about what you might have to include when you link your extension module. For example: +</p> <blockquote> <pre> $ ldd swig - libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000) - libm.so.6 => /lib/libm.so.6 (0x4005b000) - libc.so.6 => /lib/libc.so.6 (0x40077000) - /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) + libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000) + libm.so.6 => /lib/libm.so.6 (0x4005b000) + libc.so.6 => /lib/libc.so.6 (0x40077000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) $ </pre> </blockquote> @@ -377,15 +417,18 @@ this probably won't matter. However, if these modules start sharing data, you will need to take steps to avoid segmentation faults and other erratic program behavior. If working with lots of software components, you might want to investigate using a more formal standard such as COM. +</p> -<a name="n8"></a><H3>24.1.6 Compiling for 64-bit platforms</H3> +<H3><a name="Tcl_nn8"></a>27.1.6 Compiling for 64-bit platforms</H3> +<p> On platforms that support 64-bit applications (Solaris, Irix, etc.), special care is required when building extension modules. On these machines, 64-bit applications are compiled and linked using a different set of compiler/linker options. In addition, it is not generally possible to mix 32-bit and 64-bit code together in the same application. +</p> <p> To utilize 64-bits, the Tcl executable will need to be recompiled @@ -393,6 +436,7 @@ as a 64-bit application. In addition, all libraries, wrapper code, and every other part of your application will need to be compiled for 64-bits. If you plan to use other third-party extension modules, they will also have to be recompiled as 64-bit extensions. +</p> <p> If you are wrapping commercial software for which you have no source @@ -400,53 +444,69 @@ code, you will be forced to use the same linking standard as used by that software. This may prevent the use of 64-bit extensions. It may also introduce problems on platforms that support more than one linking standard (e.g., -o32 and -n32 on Irix). +</p> -<a name="n9"></a><H3>24.1.7 Setting a package prefix</H3> +<H3><a name="Tcl_nn9"></a>27.1.7 Setting a package prefix</H3> +<p> To avoid namespace problems, you can instruct SWIG to append a package prefix to all of your functions and variables. This is done using the --prefix option as follows :<p> -<p> -<blockquote><pre>swig -tcl -prefix Foo example.i +-prefix option as follows : +</p> +<blockquote><pre> +swig -tcl -prefix Foo example.i </pre></blockquote> + +<p> If you have a function "<tt>bar</tt>" in the SWIG file, the prefix option will append the prefix to the name when creating a command and -call it "<tt>Foo_bar</tt>". <p> +call it "<tt>Foo_bar</tt>". +</p> -<a name="n10"></a><H3>24.1.8 Using namespaces</H3> +<H3><a name="Tcl_nn10"></a>27.1.8 Using namespaces</H3> -Alternatively, you can have SWIG install your module into a Tcl -namespace by specifying the <tt>-namespace</tt> option :<p> <p> -<blockquote><pre>swig -tcl -namespace example.i +Alternatively, you can have SWIG install your module into a Tcl +namespace by specifying the <tt>-namespace</tt> option : +</p> +<blockquote><pre> +swig -tcl -namespace example.i </pre></blockquote> + +<p> By default, the name of the namespace will be the same as the module -name, but you can override it using the <tt>-prefix</tt> option.<p> +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 are always accessed with the namespace name such as <tt>Foo::bar</tt>. +</p> -<a name="n11"></a><H2>24.2 Building Tcl/Tk Extensions under Windows 95/NT</H2> +<H2><a name="Tcl_nn11"></a>27.2 Building Tcl/Tk Extensions under Windows 95/NT</H2> +<p> Building a SWIG extension to Tcl/Tk under Windows 95/NT is roughly similar to the process used with Unix. Normally, you will want to produce a DLL that can be loaded into tclsh or wish. This section covers the process of using SWIG with Microsoft Visual C++. -although the procedure may be similar with other compilers.<p> +although the procedure may be similar with other compilers. +</p> -<a name="n12"></a><H3>24.2.1 Running SWIG from Developer Studio</H3> +<H3><a name="Tcl_nn12"></a>27.2.1 Running SWIG from Developer Studio</H3> +<p> If you are developing your application within Microsoft developer studio, SWIG can be invoked as a custom build option. The process -roughly follows these steps :<p> +roughly follows these steps : +</p> -<p> <ul> <li>Open up a new workspace and use the AppWizard to select a DLL project. @@ -478,17 +538,17 @@ to match the name of your Tcl module (ie. example.dll). <li>Build your project. </ul> + <p> Now, assuming all went well, SWIG will be automatically invoked when you build your project. Any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file. To run your new Tcl extension, simply run <tt>tclsh</tt> or <tt>wish</tt> and use the <tt>load</tt> command. -For example :<p> +For example : +</p> -<p> <blockquote><pre> - MSDOS > tclsh80 % load example.dll % fact 4 @@ -496,15 +556,18 @@ MSDOS > tclsh80 % </pre></blockquote> -<a name="n13"></a><H3>24.2.2 Using NMAKE</H3> +<H3><a name="Tcl_nn13"></a>27.2.2 Using NMAKE</H3> +<p> Alternatively, SWIG extensions can be built by writing a Makefile for NMAKE. To do this, make sure the environment variables for MSVC++ are available and the MSVC++ tools are in your path. Now, just write a -short Makefile like this :<p> -<p> -<blockquote><pre># Makefile for building various SWIG generated extensions +short Makefile like this : +</p> + +<blockquote><pre> +# Makefile for building various SWIG generated extensions SRCS = example.c IFILE = example @@ -548,33 +611,41 @@ tcl:: $(LINK) $(LOPT) -out:example.dll $(LIBS) $(TCLLIB) example.obj example_wrap.obj </pre></blockquote> + +<p> To build the extension, run NMAKE (you may need to run vcvars32 first). This is a pretty minimal Makefile, but hopefully its enough to get you started. With a little practice, you'll be making lots of -Tcl extensions.<p> +Tcl extensions. +</p> -<a name="n14"></a><H2>24.3 A tour of basic C/C++ wrapping</H2> +<H2><a name="Tcl_nn14"></a>27.3 A tour of basic C/C++ wrapping</H2> +<p> By default, SWIG tries to build a very natural Tcl interface to your C/C++ code. Functions are wrapped as functions, classes are wrapped in an interface that mimics the style of Tk widgets and [incr Tcl] classes. This section briefly covers the essential aspects of this wrapping. +</p> -<a name="n15"></a><H3>24.3.1 Modules</H3> +<H3><a name="Tcl_nn15"></a>27.3.1 Modules</H3> +<p> The SWIG <tt>%module</tt> directive specifies the name of the Tcl module. If you specify `<tt>%module example</tt>', then everything is compiled into an extension module <tt>example.so</tt>. When choosing a module name, make sure you don't use the same name as a built-in Tcl command. +</p> <p> One pitfall to watch out for is module names involving numbers. If you specify a module name like <tt>%module md5</tt>, you'll find that the load command no longer seems to work: +</p> <blockquote> <pre> @@ -591,21 +662,23 @@ To fix this, supply an extra argument to <tt>load</tt> like this: </pre> </blockquote> -<a name="n16"></a><H3>24.3.2 Functions</H3> +<H3><a name="Tcl_nn16"></a>27.3.2 Functions</H3> +<p> Global functions are wrapped as new Tcl built-in commands. For example, +</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example int fact(int n); - </pre></blockquote> +<p> creates a built-in function <tt>fact</tt> that works exactly -like you think it does:<p> +like you think it does: +</p> -<p> <blockquote><pre> % load ./example.so % fact 4 @@ -614,7 +687,7 @@ like you think it does:<p> % </pre></blockquote> -<a name="n17"></a><H3>24.3.3 Global variables</H3> +<H3><a name="Tcl_nn17"></a>27.3.3 Global variables</H3> C/C++ global variables are wrapped by Tcl global variables. For example: @@ -626,9 +699,11 @@ C/C++ global variables are wrapped by Tcl global variables. For example: extern double density; ... </pre></blockquote> + <p> -Now look at the Tcl interface:<p> -<p> +Now look at the Tcl interface: +</p> + <blockquote><pre> % puts $density # Output value of C global variable 1.0 @@ -638,6 +713,7 @@ Now look at the Tcl interface:<p> <p> If you make an error in variable assignment, you will get an error message. For example: +</p> <blockquote><pre> % set density "hello" @@ -649,9 +725,11 @@ can't set "density": Type error. expected a double. If a variable is declared as <tt>const</tt>, it is wrapped as a read-only variable. Attempts to modify its value will result in an error. +</p> <p> To make ordinary variables read-only, you can use the <tt>%immutable</tt> directive. For example: +</p> <blockquote> <pre> @@ -666,6 +744,7 @@ The <tt>%immutable</tt> directive stays in effect until it is explicitly disable <p> If you just want to make a specific variable immutable, supply a declaration name. For example: +</p> <blockquote> <pre> @@ -675,7 +754,7 @@ extern char *path; // Read-only (due to %immutable) </pre> </blockquote> -<a name="n18"></a><H3>24.3.4 Constants and enums</H3> +<H3><a name="Tcl_nn18"></a>27.3.4 Constants and enums</H3> C/C++ constants are installed as global Tcl variables containing the @@ -694,22 +773,27 @@ enum Beverage { ALE, LAGER, STOUT, PILSNER }; </pre> </blockquote> +<p> For enums, make sure that the definition of the enumeration actually appears in a header file or in the wrapper file somehow---if you just stick an enum in a SWIG interface without also telling the C compiler about it, the wrapper code won't compile. +</p> <p> Note: declarations declared as <tt>const</tt> are wrapped as read-only variables and will be accessed using the <tt>cvar</tt> object described in the previous section. They -are not wrapped as constants. For further discussion about this, see the <a href="SWIG.html">SWIG Basics</a> chapter. +are not wrapped as constants. For further discussion about this, see the <a href="SWIG.html#SWIG">SWIG Basics</a> chapter. +</p> <p> Constants are not guaranteed to remain constant in Tcl---the value of the constant could be accidentally reassigned.You will just have to be careful. +</p> <p> A peculiarity of installing constants as variables is that it is necessary to use the Tcl <tt>global</tt> statement to access constants in procedure bodies. For example: +</p> <blockquote> <pre> @@ -746,7 +830,7 @@ proc blah {} { When an identifier name is given, it is used to perform an implicit hash-table lookup of the value during argument conversion. This allows the <tt>global</tt> statement to be ommitted. -<a name="n19"></a><H3>24.3.5 Pointers</H3> +<H3><a name="Tcl_nn19"></a>27.3.5 Pointers</H3> C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with @@ -774,24 +858,28 @@ For example: </pre> </blockquote> +<p> If this makes you uneasy, rest assured that there is no deep magic involved. Underneath the covers, pointers to C/C++ objects are simply represented as opaque values--normally an encoded character string like this: +</p> -<p> <blockquote><pre> % puts $f _c0671108_p_FILE % </pre></blockquote> +<p> This pointer value can be freely passed around to different C functions that expect to receive an object of type <tt>FILE *</tt>. The only thing you can't do is dereference the pointer from Tcl. +</p> <p> The NULL pointer is represented by the string <tt>NULL</tt>. +</p> <p> As much as you might be inclined to modify a pointer value directly @@ -805,6 +893,7 @@ may not work like you expect and it is particularly dangerous when casting C++ objects. If you need to cast a pointer or change its value, consider writing some helper functions instead. For example: +</p> <blockquote> <pre> @@ -826,26 +915,32 @@ Foo *IncrFoo(Foo *f, int i) { </pre> </blockquote> +<p> Also, if working with C++, you should always try to use the new C++ style casts. For example, in the above code, the 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> -<a name="n20"></a><H3>24.3.6 Structures</H3> +<H3><a name="Tcl_nn20"></a>27.3.6 Structures</H3> +<p> If you wrap a C structure, it is wrapped by a Tcl interface that somewhat resembles a Tk widget. This provides a very natural interface. For example, +</p> -<p> -<blockquote><pre>struct Vector { +<blockquote><pre> +struct Vector { double x,y,z; }; </pre></blockquote> -is used as follows: <p> +is used as follows: +</p> + <blockquote><pre> % Vector v % v configure -x 3.5 -y 7.2 @@ -853,14 +948,16 @@ is used as follows: 3.5 7.2 0.0 % </pre></blockquote> -<p> -Similar access is provided for unions and the data members of C++ classes.<p> +<p> +Similar access is provided for unions and the data members of C++ classes. +</p> <p> In the above example, <tt>v</tt> is a name that's used for the object. However, underneath the covers, there's a pointer to a raw C structure. This can be obtained by looking at the <tt>-this</tt> attribute. For example: +</p> <blockquote> <pre> @@ -869,12 +966,15 @@ _88e31408_p_Vector </pre> </blockquote> +<p> Further details about the relationship between the Tcl and the underlying C structure are covered a little later. +</p> <p> <tt>const</tt> members of a structure are read-only. Data members can also be forced to be read-only using the <tt>%immutable</tt> directive. For example: +</p> <blockquote> <pre> @@ -895,10 +995,12 @@ dynamically allocated using <tt>malloc</tt> or <tt>new</tt> (depending on whethe SWIG is run with the -c++ option). When the structure member is set, the old contents will be released and a new value created. If this is not the behavior you want, you will have to use a typemap (described later). +</p> <p> If a structure contains arrays, access to those arrays is managed through pointers. For example, consider this: +</p> <blockquote> <pre> @@ -930,14 +1032,17 @@ another pointer. For example: </pre> </blockquote> +<p> For array assignment, SWIG copies the entire contents of the array starting with the data pointed to by <tt>b.x</tt>. In this example, 16 integers would be copied. Like C, SWIG makes no assumptions about bounds checking---if you pass a bad pointer, you may get a segmentation fault or access violation. +</p> <p> When a member of a structure is itself a structure, it is handled as a pointer. For example, suppose you have two structures like this: +</p> <blockquote> <pre> @@ -966,7 +1071,7 @@ This is the same value as generated by this C code: <blockquote> <pre> Bar b; -Foo *x = &b->f; /* Points inside b */ +Foo *x = &b->f; /* Points inside b */ </pre> </blockquote> @@ -1071,13 +1176,15 @@ or Note: Tcl only destroys the underlying object if it has ownership. See the memory management section that appears shortly. -<a name="n21"></a><H3>24.3.7 C++ classes</H3> +<H3><a name="Tcl_nn21"></a>27.3.7 C++ classes</H3> +<p> C++ classes are wrapped as an extension of structure wrapping. For example, if you have this class, +</p> -<p> -<blockquote><pre>class List { +<blockquote><pre> +class List { public: List(); ~List(); @@ -1103,11 +1210,14 @@ Stout % </pre></blockquote> +<p> Class data members are accessed in the same manner as C structures. +</p> <p> Static class members are accessed as global functions or variables. To illustrate, suppose you have a class like this: +</p> <blockquote> <pre> @@ -1129,7 +1239,7 @@ In Tcl, the static member is accessed as follows: </pre> </blockquote> -<a name="n22"></a><H3>24.3.8 C++ inheritance</H3> +<H3><a name="Tcl_nn22"></a>27.3.8 C++ inheritance</H3> SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have @@ -1170,8 +1280,9 @@ For instance: <p> It is safe to use multiple inheritance with SWIG. +</p> -<a name="n23"></a><H3>24.3.9 Pointers, references, values, and arrays</H3> +<H3><a name="Tcl_nn23"></a>27.3.9 Pointers, references, values, and arrays</H3> In C++, there are many different ways a function might receive @@ -1180,7 +1291,7 @@ and manipulate objects. For example: <blockquote> <pre> void spam1(Foo *x); // Pass by pointer -void spam2(Foo &x); // Pass by reference +void spam2(Foo &x); // Pass by reference void spam3(Foo x); // Pass by value void spam4(Foo x[]); // Array of objects </pre> @@ -1207,7 +1318,7 @@ functions like this, <blockquote> <pre> Foo *spam5(); -Foo &spam6(); +Foo &spam6(); Foo spam7(); </pre> </blockquote> @@ -1217,7 +1328,7 @@ Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Tcl will release this memory when the return value is garbage collected). -<a name="n24"></a><H3>24.3.10 C++ overloaded functions</H3> +<H3><a name="Tcl_nn24"></a>27.3.10 C++ overloaded functions</H3> C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example, @@ -1246,7 +1357,7 @@ Similarly, if you have a class like this, class Foo { public: Foo(); - Foo(const Foo &); + Foo(const Foo &); ... }; </pre> @@ -1276,7 +1387,7 @@ or <blockquote> <pre> void foo(Bar *b); -void foo(Bar &b); +void foo(Bar &b); </pre> </blockquote> @@ -1311,15 +1422,18 @@ void spam(short); // Ignored </pre> </blockquote> +<p> SWIG resolves overloaded functions and methods using a disambiguation scheme that ranks and sorts declarations according to a set of type-precedence rules. The order in which declarations appear in the input does not matter except in situations where ambiguity arises--in this case, the first declaration takes precedence. +</p> -<P> +<p> Please refer to the "SWIG and C++" chapter for more information about overloading. +</p> -<a name="n25"></a><H3>24.3.11 C++ operators</H3> +<H3><a name="Tcl_nn25"></a>27.3.11 C++ operators</H3> Certain C++ overloaded operators can be handled automatically by SWIG. For example, @@ -1332,11 +1446,11 @@ private: double rpart, ipart; public: Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { } - Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { } - Complex &operator=(const Complex &c); - Complex operator+(const Complex &c) const; - Complex operator-(const Complex &c) const; - Complex operator*(const Complex &c) const; + Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { } + Complex &operator=(const Complex &c); + Complex operator+(const Complex &c) const; + Complex operator-(const Complex &c) const; + Complex operator*(const Complex &c) const; Complex operator-() const; double re() const { return rpart; } @@ -1370,7 +1484,7 @@ method overloading facilities are used. Here is a rather odd looking example: <pre> % Complex c 3 4 % Complex d 7 8 -% set e [c - d] # operator-(const Complex &) +% set e [c - d] # operator-(const Complex &) % puts "[$e re] [$e im]" 10.0 12.0 % set f [c -] # operator-() @@ -1388,7 +1502,7 @@ For example, if you had code like this <pre> class Complex { ... -friend Complex operator+(double, const Complex &c); +friend Complex operator+(double, const Complex &c); ... }; </pre> @@ -1400,16 +1514,16 @@ but you may have to encapsulate it in a special function. For example: <blockquote> <pre> -%rename(Complex_add_dc) operator+(double, const Complex &); +%rename(Complex_add_dc) operator+(double, const Complex &); ... -Complex operator+(double, const Complex &c); +Complex operator+(double, const Complex &c); </pre> </blockquote> There are ways to make this operator appear as part of the class using the <tt>%extend</tt> directive. Keep reading. -<a name="n26"></a><H3>24.3.12 C++ namespaces</H3> +<H3><a name="Tcl_nn26"></a>27.3.12 C++ namespaces</H3> SWIG is aware of C++ namespaces, but namespace names do not appear in @@ -1465,7 +1579,7 @@ extension modules for each namespace separately. If your program utilizes thousands of small deeply nested namespaces each with identical symbol names, well, then you get what you deserve. -<a name="n27"></a><H3>24.3.13 C++ templates</H3> +<H3><a name="Tcl_nn27"></a>27.3.13 C++ templates</H3> C++ templates don't present a huge problem for SWIG. However, in order @@ -1487,7 +1601,7 @@ struct pair { T1 first; T2 second; pair(); - pair(const T1&, const T2&); + pair(const T1&, const T2&); ~pair(); }; @@ -1508,21 +1622,21 @@ In Tcl: </blockquote> Obviously, there is more to template wrapping than shown in this example. -More details can be found in the <a href="SWIGPlus.html">SWIG and C++</a> chapter. Some more complicated +More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter. Some more complicated examples will appear later. -<a name="n28"></a><H3>24.3.14 C++ Smart Pointers</H3> +<H3><a name="Tcl_nn28"></a>27.3.14 C++ Smart Pointers</H3> In certain C++ programs, it is common to use classes that have been wrapped by so-called "smart pointers." Generally, this involves the use of a template class -that implements <tt>operator->()</tt> like this: +that implements <tt>operator->()</tt> like this: <blockquote> <pre> template<class T> class SmartPtr { ... - T *operator->(); + T *operator->(); ... } </pre> @@ -1546,8 +1660,8 @@ A smart pointer would be used in C++ as follows: <pre> SmartPtr<Foo> p = CreateFoo(); // Created somehow (not shown) ... -p->x = 3; // Foo::x -int y = p->bar(); // Foo::bar +p->x = 3; // Foo::x +int y = p->bar(); // Foo::bar </pre> </blockquote> @@ -1574,7 +1688,7 @@ Now, in Tcl, everything should just "work": </pre> </blockquote> -If you ever need to access the underlying pointer returned by <tt>operator->()</tt> itself, +If you ever need to access the underlying pointer returned by <tt>operator->()</tt> itself, simply use the <tt>__deref__()</tt> method. For example: <blockquote> @@ -1583,7 +1697,7 @@ simply use the <tt>__deref__()</tt> method. For example: </pre> </blockquote> -<a name="n29"></a><H2>24.4 Further details on the Tcl class interface</H2> +<H2><a name="Tcl_nn29"></a>27.4 Further details on the Tcl class interface</H2> In the previous section, a high-level view of Tcl wrapping was @@ -1594,10 +1708,10 @@ advanced features such as operator overloading. However, a number of low-level details were omitted. This section provides a brief overview of how the proxy classes work. -<a name="n30"></a><H3>24.4.1 Proxy classes</H3> +<H3><a name="Tcl_nn30"></a>27.4.1 Proxy classes</H3> -In the <a href="SWIG.html">"SWIG basics"</a> and <a href="SWIGPlus.html">"SWIG and C++"</a> chapters, +In the <a href="SWIG.html#SWIG">"SWIG basics"</a> and <a href="SWIGPlus.html#SWIGPlus">"SWIG and C++"</a> chapters, details of low-level structure and class wrapping are described. To summarize those chapters, if you have a class like this @@ -1622,13 +1736,13 @@ void delete_Foo(Foo *f) { delete f; } int Foo_x_get(Foo *f) { - return f->x; + return f->x; } void Foo_x_set(Foo *f, int value) { - f->x = value; + f->x = value; } int Foo_spam(Foo *f, int arg1) { - return f->spam(arg1); + return f->spam(arg1); } </pre> </blockquote> @@ -1651,18 +1765,21 @@ However, in addition to this, the classname <tt>Foo</tt> is used as an object co function. This allows objects to be encapsulated objects that look a lot like Tk widgets as shown in the last section. -<a name="n31"></a><H3>24.4.2 Memory management</H3> +<H3><a name="Tcl_nn31"></a>27.4.2 Memory management</H3> +<p> Associated with each wrapped object, is an ownership flag <tt>thisown</tt> The value of this flag determines who is responsible for deleting the underlying C++ object. If set to 1, the Tcl interpreter destroys the C++ object when the proxy class is garbage collected. If set to 0 (or if the attribute is missing), then the destruction of the proxy class has no effect on the C++ object. +</p> -<P> +<p> When an object is created by a constructor or returned by value, Tcl automatically takes ownership of the result. For example: +</p> <blockquote> <pre> @@ -1711,14 +1828,17 @@ public: </pre> </blockquote> +<p> This behavior is especially important for classes that act as containers. For example, if a method returns a pointer to an object that is contained inside another object, you definitely don't want Tcl to assume ownership and destroy it! +</p> <p> Related to containers, ownership issues can arise whenever an object is assigned to a member or global variable. For example, consider this interface: +</p> <blockquote> <pre> @@ -1769,6 +1889,7 @@ Similarly, this occurs for members. For example: For the most part, memory management issues remain hidden. However, there are occasionally situations where you might have to manually change the ownership of an object. For instance, consider code like this: +</p> <blockquote> <pre> @@ -1794,15 +1915,18 @@ Now, consider the following Tcl code: </pre> </blockquote> +<p> In this case, the object <tt>n</tt> is holding a reference to <tt>v</tt> internally. However, SWIG has no way to know that this has occurred. Therefore, Tcl still thinks that it has ownership of the object. Should the proxy object be destroyed, then the C++ destructor will be invoked and <tt>n</tt> will be holding a stale-pointer. If you're lucky, you will only get a segmentation fault. +</p> <p> To work around this, it is always possible to flip the ownership flag. For example, +</p> <blockquote> <pre> @@ -1815,7 +1939,7 @@ It is also possible to deal with situations like this using typemaps--an advanced topic discussed later. -<a name="n32"></a><H2>24.5 Input and output parameters</H2> +<H2><a name="Tcl_nn32"></a>27.5 Input and output parameters</H2> A common problem in some C programs is handling parameters passed as simple pointers. For @@ -1861,12 +1985,15 @@ puts $a </pre> </blockquote> +<p> Notice how the <tt>INPUT</tt> parameters allow integer values to be passed instead of pointers and how the <tt>OUTPUT</tt> parameter creates a return result. +</p> <p> If you don't want to use the names <tt>INPUT</tt> or <tt>OUTPUT</tt>, use the <tt>%apply</tt> directive. For example: +</p> <blockquote> <pre> @@ -1883,6 +2010,7 @@ int sub(int *x, int *y); <p> If a function mutates one of its parameters like this, +</p> <blockquote> <pre> @@ -1916,6 +2044,7 @@ puts $a The most common use of these special typemap rules is to handle functions that return more than one value. For example, sometimes a function returns a result as well as a special error code: +</p> <blockquote> <pre> @@ -1976,14 +2105,16 @@ set c [lindex $dim 1] </pre> </blockquote> -<a name="n33"></a><H2>24.6 Exception handling </H2> +<H2><a name="Tcl_nn33"></a>27.6 Exception handling </H2> +<p> The <tt>%exception</tt> directive can be used to create a user-definable exception handler in charge of converting exceptions in your C/C++ program into Tcl exceptions. The chapter on customization features contains more details, but suppose you extended the array example into -a C++ class like the following :<p> +a C++ class like the following : +</p> <blockquote><pre> class RangeError {}; // Used for an exception @@ -2029,10 +2160,11 @@ class DoubleArray { <p> The functions associated with this class can throw a C++ range exception for an out-of-bounds array access. We can catch this in our -Tcl extension by specifying the following in an interface file :<p> +Tcl extension by specifying the following in an interface file : +</p> -<p> -<blockquote><pre>%exception { +<blockquote><pre> +%exception { try { $action // Gets substituted by actual function call } @@ -2041,13 +2173,13 @@ Tcl extension by specifying the following in an interface file :<p> return TCL_ERROR; } } - </pre></blockquote> <p> As shown, the exception handling code will be added to every wrapper function. Since this is somewhat inefficient. You might consider refining the exception handler to only apply to specific methods like this: +</p> <blockquote> <pre> @@ -2073,12 +2205,15 @@ exception handler to only apply to specific methods like this: </pre> </blockquote> +<p> In this case, the exception handler is only attached to methods and functions named <tt>getitem</tt> and <tt>setitem</tt>. +</p> <p> If you had a lot of different methods, you can avoid extra typing by using a macro. For example: +</p> <blockquote> <pre> @@ -2100,34 +2235,39 @@ For example: </blockquote> Since SWIG's exception handling is user-definable, you are not limited to C++ exception handling. -See the chapter on "<a href="Customization.html">Customization Features</a>" for more examples. +See the chapter on "<a href="Customization.html#Customization">Customization Features</a>" for more examples. -<a name="n34"></a><H2>24.7 Typemaps</H2> +<H2><a name="Tcl_nn34"></a>27.7 Typemaps</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 Tcl C API as well -as the material in the "<a href="Typemaps.html">Typemaps</a>" chapter. +as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. +</p> <p> Before proceeding, it should be stressed that typemaps are not a required part of using SWIG---the default wrapping behavior is enough in most cases. Typemaps are only used if you want to change some aspect of the primitive C-Tcl interface. +</p> -<a name="n35"></a><H3>24.7.1 What is a typemap?</H3> +<H3><a name="Tcl_nn35"></a>27.7.1 What is a typemap?</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 Tcl to C, you might define a typemap like this: +</p> -<p> -<blockquote><pre>%module example +<blockquote><pre> +%module example %typemap(in) int { - if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR; + if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR; printf("Received an integer : %d\n",$1); } extern int fact(int n); @@ -2141,31 +2281,37 @@ will be applied. The supplied C code is used to convert values. In this code a number of special variable prefaced by a <tt>$</tt> are used. The <tt>$1</tt> variable is placeholder for a local variable of type <tt>int</tt>. The <tt>$input</tt> variable is the input object of type <tt>Tcl_Obj *</tt>. +</p> <p> When this example is compiled into a Tcl module, it operates as follows: +</p> -<p> -<blockquote><pre>% load ./example.so +<blockquote><pre> +% load ./example.so % fact 6 Received an integer : 6 720 </pre></blockquote> -<p> +<p> In this example, the typemap is applied to all occurrences of the <tt>int</tt> datatype. You can refine this by supplying an optional parameter name. For example: +</p> -<blockquote><pre>%module example +<blockquote><pre> +%module example %typemap(in) int n { - if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR; + if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR; printf("n = %d\n",$1); } extern int fact(int n); </pre></blockquote> +<p> In this case, the typemap code is only attached to arguments that exactly match <tt>int n</tt>. +</p> <p> The application of a typemap to specific datatypes and argument names involves @@ -2173,11 +2319,12 @@ more than simple text-matching--typemaps are fully integrated into the SWIG type-system. When you define a typemap for <tt>int</tt>, that typemap applies to <tt>int</tt> and qualified variations such as <tt>const int</tt>. In addition, the typemap system follows <tt>typedef</tt> declarations. For example: +</p> <blockquote> <pre> %typemap(in) int n { - if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR; + if (Tcl_GetIntFromObj(interp,$input,&$1) == TCL_ERROR) return TCL_ERROR; printf("n = %d\n",$1); } typedef int Integer; @@ -2191,11 +2338,12 @@ type <tt>int</tt>. <p> Typemaps can also be defined for groups of consecutive arguments. For example: +</p> <blockquote> <pre> %typemap(in) (char *str, int len) { - $1 = Tcl_GetStringFromObj($input,&$2); + $1 = Tcl_GetStringFromObj($input,&$2); }; int count(char c, char *str, int len); @@ -2213,7 +2361,7 @@ parameter is ommitted): </pre> </blockquote> -<a name="n36"></a><H3>24.7.2 Tcl typemaps</H3> +<H3><a name="Tcl_nn36"></a>27.7.2 Tcl typemaps</H3> The previous section illustrated an "in" typemap for converting Tcl objects to C. @@ -2229,89 +2377,139 @@ like this: </pre> </blockquote> +<p> The following list details all of the typemap methods that can be used by the Tcl module: +</p> + <p> -<tt>%typemap(in) </tt> +<tt>%typemap(in)</tt> +</p> + <blockquote> -Converts Tcl objects to input function arguments<p> +Converts Tcl objects to input function arguments </blockquote> +<p> <tt>%typemap(out)</tt> +</p> + <blockquote> -Converts return value of a C function to a Tcl object<p> +Converts return value of a C function to a Tcl object </blockquote> +<p> <tt>%typemap(varin)</tt> +</p> + <blockquote> -Assigns a C global variable from a Tcl object<p> +Assigns a C global variable from a Tcl object </blockquote> +<p> <tt>%typemap(varout)</tt> +</p> + <blockquote> -Returns a C global variable as a Tcl object<p> +Returns a C global variable as a Tcl object </blockquote> +<p> <tt>%typemap(freearg)</tt> +</p> + <blockquote> -Cleans up a function argument (if necessary)<p> +Cleans up a function argument (if necessary) </blockquote> +<p> <tt>%typemap(argout)</tt> +</p> + <blockquote> -Output argument processing<p> +Output argument processing </blockquote> +<p> <tt>%typemap(ret)</tt> +</p> + <blockquote> -Cleanup of function return values<p> +Cleanup of function return values </blockquote> +<p> <tt>%typemap(consttab)</tt> +</p> + <blockquote> -Creation of Tcl constants (constant table)<p> +Creation of Tcl constants (constant table) </blockquote> +<p> <tt>%typemap(constcode)</tt> +</p> + <blockquote> Creation of Tcl constants (init function) </blockquote> +<p> <tt>%typemap(memberin)</tt> +</p> + <blockquote> -Setting of structure/class member data<p> +Setting of structure/class member data </blockquote> +<p> <tt>%typemap(globalin)</tt> +</p> + <blockquote> -Setting of C global variables<p> +Setting of C global variables </blockquote> +<p> <tt>%typemap(check)</tt> +</p> + <blockquote> -Checks function input values.<p> +Checks function input values. </blockquote> +<p> <tt>%typemap(default)</tt> +</p> + <blockquote> Set a default value for an argument (making it optional). </blockquote> +<p> <tt>%typemap(arginit)</tt> +</p> + <blockquote> Initialize an argument to a value before any conversions occur. </blockquote> +<p> Examples of these methods will appear shortly. +</p> -<a name="n37"></a><H3>24.7.3 Typemap variables</H3> +<H3><a name="Tcl_nn37"></a>27.7.3 Typemap variables</H3> +<p> Within typemap code, a number of special variables prefaced with a <tt>$</tt> may appear. -A full list of variables can be found in the "<a href="Typemaps.html">Typemaps</a>" chapter. +A full list of variables can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. This is a list of the most common variables: +</p> <p> <tt>$1</tt> +</p> + <blockquote> A C local variable corresponding to the actual type specified in the <tt>%typemap</tt> directive. For input values, this is a C local variable @@ -2321,30 +2519,40 @@ the raw result that's supposed to be returned to Tcl. <p> <tt>$input</tt> +</p> + <blockquote> A <tt>Tcl_Obj *</tt> holding a raw Tcl object with an argument or variable value. </blockquote> <p> <tt>$result</tt> +</p> + <blockquote> A <tt>Tcl_Obj *</tt> that holds the result to be returned to Tcl. </blockquote> -<p> +<p> <tt>$1_name</tt> +</p> + <blockquote> The parameter name that was matched. </blockquote> -<p> +<p> <tt>$1_type</tt> +</p> + <blockquote> The actual C datatype matched by the typemap. </blockquote> -<p> +<p> <tt>$1_ltype</tt> +</p> + <blockquote> An assignable version of the datatype matched by the typemap (a type that can appear on the left-hand-side of a C assignment operation). This type is stripped of qualifiers and may be an altered version of <tt>$1_type</tt>. @@ -2352,28 +2560,33 @@ All arguments and local variables in wrapper functions are declared using this t properly assigned. </blockquote> +<p> <tt>$symname</tt> +</p> + <blockquote> The Tcl name of the wrapper function being created. </blockquote> -<a name="n38"></a><H3>24.7.4 Converting a Tcl list to a char ** </H3> +<H3><a name="Tcl_nn38"></a>27.7.4 Converting a Tcl list to a char ** </H3> +<p> A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings. The following SWIG interface file allows a Tcl list to be -used as a <tt>char **</tt> object.<p> +used as a <tt>char **</tt> object. +</p> -<p> -<blockquote><pre>%module argv +<blockquote><pre> +%module argv // This tells SWIG to treat char ** as a special case %typemap(in) char ** { Tcl_Obj **listobjv; int nitems; int i; - if (Tcl_ListObjGetElements(interp, $input, &nitems, &listobjv) == TCL_ERROR) { + if (Tcl_ListObjGetElements(interp, $input, &nitems, &listobjv) == TCL_ERROR) { return TCL_ERROR; } $1 = (char **) malloc((nitems+1)*sizeof(char *)); @@ -2405,23 +2618,28 @@ int print_args(char **argv) { </pre></blockquote> -In Tcl: <p> -<blockquote><pre>% print_args {John Guido Larry} +In Tcl: +</p> + +<blockquote><pre> +% print_args {John Guido Larry} argv[0] = John argv[1] = Guido argv[2] = Larry 3 </pre></blockquote> -<a name="n39"></a><H3>24.7.5 Returning values in arguments</H3> +<H3><a name="Tcl_nn39"></a>27.7.5 Returning values in arguments</H3> +<p> The "argout" typemap can be used to return a value originating from a -function argument. For example :<p> +function argument. For example : +</p> -<p> -<blockquote><pre>// A typemap defining how to return an argument by appending it to the result +<blockquote><pre> +// A typemap defining how to return an argument by appending it to the result %typemap(argout) double *outvalue { Tcl_Obj *o = Tcl_NewDoubleObj($1); Tcl_ListObjAppendElement(interp,$result,o); @@ -2430,7 +2648,7 @@ function argument. For example :<p> // A typemap telling SWIG to ignore an argument for input // However, we still need to pass a pointer to the C function %typemap(in,numinputs=0) double *outvalue (double temp) { - $1 = &temp; + $1 = &temp; } // Now a function returning two values @@ -2439,27 +2657,32 @@ int mypow(double a, double b, double *outvalue) { *outvalue = pow(a,b); return 0; }; - </pre></blockquote> + +<p> When wrapped, SWIG matches the <tt>argout</tt> typemap to the "<tt>double *outvalue</tt>" argument. The numinputs=0 specification tells SWIG to simply ignore this argument when generating wrapper code. As a -result, a Tcl function using these typemaps will work like this :<p> -<p> +result, a Tcl function using these typemaps will work like this : +</p> -<blockquote><pre>% mypow 2 3 # Returns two values, a status value and the result +<blockquote><pre> +% mypow 2 3 # Returns two values, a status value and the result 0 8 % </pre></blockquote> -<a name="n40"></a><H3>24.7.6 Useful functions</H3> +<H3><a name="Tcl_nn40"></a>27.7.6 Useful functions</H3> +<p> The following tables provide some functions that may be useful in writing Tcl typemaps. +</p> <p> <b>Integers</b> +</p> <blockquote> <pre> @@ -2469,7 +2692,9 @@ int Tcl_GetIntFromObj(Tcl_Interp *, Tcl_Obj *obj, int *ip); </pre> </blockquote> +<p> <b>Floating Point</b> +</p> <blockquote> <pre> @@ -2479,7 +2704,9 @@ int Tcl_GetDoubleFromObj(Tcl_Interp *, Tcl_Obj *o, double *dp); </pre> </blockquote> +<p> <b>Strings</b> +</p> <blockquote> <pre> @@ -2490,7 +2717,9 @@ void Tcl_AppendToObj(Tcl_Obj *obj, char *str, int len); </pre> </blockquote> +<p> <b>Lists</b> +</p> <blockquote> <pre> @@ -2518,12 +2747,14 @@ int Tcl_IsShared(Tcl_Obj *obj); </pre> </blockquote> -<a name="n41"></a><H3>24.7.7 Standard typemaps</H3> +<H3><a name="Tcl_nn41"></a>27.7.7 Standard typemaps</H3> +<p> The following typemaps show how to convert a few common kinds of objects between Tcl and C (and to give a better idea of how typemaps -work)<p> +work) +</p> <b>Integer conversion</b> @@ -2532,14 +2763,13 @@ work)<p> <pre> %typemap(in) int, short, long { int temp; - if (Tcl_GetIntFromObj(interp, $input, &temp) == TCL_ERROR) + if (Tcl_GetIntFromObj(interp, $input, &temp) == TCL_ERROR) return TCL_ERROR; $1 = ($1_ltype) temp; } </pre> </blockquote> -<p> <blockquote> <pre> %typemap(out) int, short, long { @@ -2554,14 +2784,13 @@ work)<p> <pre> %typemap(in) float, double { double temp; - if (Tcl_GetDoubleFromObj(interp, $input, &temp) == TCL_ERROR) + if (Tcl_GetDoubleFromObj(interp, $input, &temp) == TCL_ERROR) return TCL_ERROR; $1 = ($1_ltype) temp; } </pre> </blockquote> -<p> <blockquote> <pre> %typemap(out) float, double { @@ -2576,13 +2805,12 @@ work)<p> <pre> %typemap(in) char * { int len; - $1 = Tcl_GetStringFromObj(interp, &len); + $1 = Tcl_GetStringFromObj(interp, &len); } } </pre> </blockquote> -<p> <blockquote> <pre> %typemap(out) char * { @@ -2591,18 +2819,20 @@ work)<p> </pre> </blockquote> -<a name="n42"></a><H3>24.7.8 Pointer handling</H3> +<H3><a name="Tcl_nn42"></a>27.7.8 Pointer handling</H3> +<p> SWIG pointers are mapped into Tcl strings containing the hexadecimal value and type. The following functions can be used to -create and read pointer values.<p> +create and read pointer values. +</p> <p> <tt> int SWIG_ConvertPtr(Tcl_Obj *obj, void **ptr, swig_type_info *ty, int flags)</tt> +</p> -<p> <blockquote> Converts a Tcl object <tt>obj</tt> to a C pointer. The result of the conversion is placed into the pointer located at <tt>ptr</tt>. <tt>ty</tt> is a SWIG type descriptor structure. @@ -2613,24 +2843,26 @@ reserved for future expansion. Returns 0 on success and -1 on error. <p> <tt> Tcl_Obj *SWIG_NewPointerObj(void *ptr, swig_type_info *ty, int flags)</tt> -<p> +</p> <blockquote> Creates a new Tcl pointer object. <tt>ptr</tt> is the pointer to convert, <tt>ty</tt> is the SWIG type descriptor structure that describes the type, and <tt>own</tt> is a flag reserved for future expansion. </blockquote> +<p> Both of these functions require the use of a special SWIG type-descriptor structure. This structure contains information about the mangled name of the datatype, type-equivalence information, as well as information about converting pointer values under C++ inheritance. For a type of <tt>Foo *</tt>, the type descriptor structure is usually accessed as follows: +</p> <blockquote> <pre> Foo *f; -if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, 0) == -1) return NULL; +if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, 0) == -1) return NULL; Tcl_Obj *; obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0); @@ -2643,7 +2875,7 @@ variable <tt>$1_descriptor</tt>. For example: <blockquote> <pre> %typemap(in) Foo * { - if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,0)) == -1) return NULL; + if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,0)) == -1) return NULL; } </pre> </blockquote> @@ -2651,16 +2883,17 @@ variable <tt>$1_descriptor</tt>. For example: <p> If necessary, the descriptor for any type can be obtained using the <tt>$descriptor()</tt> macro in a typemap. For example: +</p> <blockquote> <pre> %typemap(in) Foo * { - if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), 0)) == -1) return NULL; + if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), 0)) == -1) return NULL; } </pre> </blockquote> -<a name="n43"></a><H2>24.8 Turning a SWIG module into a Tcl Package.</H2> +<H2><a name="Tcl_nn43"></a>27.8 Turning a SWIG module into a Tcl Package.</H2> Tcl 7.4 introduced the idea of an extension package. By default, SWIG @@ -2673,30 +2906,36 @@ simply use the <tt>-pkgversion</tt> option. For example: </pre> </blockquote> +<p> After building the SWIG generated module, you need to execute -the "<tt>pkg_mkIndex</tt>" command inside tclsh. For example :<p> +the "<tt>pkg_mkIndex</tt>" command inside tclsh. For example : +</p> <blockquote><pre> unix > tclsh % pkg_mkIndex . example.so % exit - </pre></blockquote> -This creates a file "<tt>pkgIndex.tcl</tt>" with information about the -package. To use your<p> package, you now need to move it to its own -subdirectory which has the same name as the package. For example :<p> + <p> -<blockquote><pre>./example/ +This creates a file "<tt>pkgIndex.tcl</tt>" with information about the +package. To use your package, you now need to move it to its own +subdirectory which has the same name as the package. For example : +</p> + +<blockquote><pre> +./example/ pkgIndex.tcl # The file created by pkg_mkIndex example.so # The SWIG generated module - </pre></blockquote> + <p> Finally, assuming that you're not entirely confused at this point, make sure that the example subdirectory is visible from the directories contained in either the <tt>tcl_library</tt> or <tt>auto_path</tt> variables. At this point you're ready to use the -package as follows :<p> +package as follows : +</p> <blockquote><pre> unix > tclsh @@ -2705,32 +2944,37 @@ unix > tclsh 24 % </pre></blockquote> + <p> -If you're working with an example in the current directory and this doesn't work, do this instead :<p> -<p> -<blockquote><pre>unix > tclsh +If you're working with an example in the current directory and this doesn't work, do this instead : +</p> + +<blockquote><pre> +unix > tclsh % lappend auto_path . % package require example % fact 4 24 - </pre></blockquote> -<p> +<p> As a final note, most SWIG examples do not yet use the <tt>package</tt> commands. For simple extensions it may be easier just -to use the <tt>load</tt> command instead.<p> +to use the <tt>load</tt> command instead. +</p> -<a name="n44"></a><H2>24.9 Building new kinds of Tcl interfaces (in Tcl)</H2> +<H2><a name="Tcl_nn44"></a>27.9 Building new kinds of Tcl interfaces (in Tcl)</H2> +<p> One of the most interesting aspects of Tcl and SWIG is that you can create entirely new kinds of Tcl interfaces in Tcl using the low-level SWIG accessor functions. For example, suppose you had a library of -helper functions to access arrays :<p> +helper functions to access arrays : +</p> -<p> -<blockquote><pre>/* File : array.i */ +<blockquote><pre> +/* File : array.i */ %module array %inline %{ @@ -2761,11 +3005,14 @@ int set_int(int *a, int index, int val) { %} </pre></blockquote> -While these could be called directly, we could also write a Tcl script -like this :<p> <p> -<blockquote><pre>proc Array {type size} { +While these could be called directly, we could also write a Tcl script +like this : +</p> + +<blockquote><pre> +proc Array {type size} { set ptr [new_$type $size] set code { set method [lindex $args 0] @@ -2783,10 +3030,11 @@ like this :<p> </pre></blockquote> <p> -Our script allows easy array access as follows :<p> +Our script allows easy array access as follows : +</p> -<p> -<blockquote><pre>set a [Array double 100] ;# Create a double [100] +<blockquote><pre> +set a [Array double 100] ;# Create a double [100] for {set i 0} {$i < 100} {incr i 1} { ;# Clear the array $a set $i 0.0 } @@ -2811,19 +3059,22 @@ datatypes to our wrapper file, the Tcl code would work with those as well--without modification. If an unsupported datatype was requested, the Tcl code would simply return with an error so there is very little danger of blowing something up (although it is easily accomplished -with an out of bounds array access).<p> +with an out of bounds array access). +</p> -<a name="n45"></a><H3>24.9.1 Shadow classes</H3> +<H3><a name="Tcl_nn45"></a>27.9.1 Shadow classes</H3> +<p> A similar approach can be applied to shadow classes. The following example is provided by Erik Bierwagen and Paul Saxe. To use it, run SWIG with the <tt>-noobject</tt> option (which disables the builtin object oriented interface). When running Tcl, simply source this -file. Now, objects can be used in a more or less natural fashion.<p> +file. Now, objects can be used in a more or less natural fashion. +</p> -<p> -<blockquote><pre># swig_c++.tcl +<blockquote><pre> +# swig_c++.tcl # Provides a simple object oriented interface using # SWIG's low level interface. # @@ -2881,10 +3132,11 @@ proc delete {handle_r} { <p> To use this file, we simply source it and execute commands such as -"new" and "delete" to manipulate objects. For example :<p> +"new" and "delete" to manipulate objects. For example : +</p> -<p> -<blockquote><pre>// list.i +<blockquote><pre> +// list.i %module List %{ #include "list.h" @@ -2906,10 +3158,11 @@ static void print(List *l); // Print out the contents of the list </pre></blockquote> <p> -Now a Tcl script using the interface...<p> +Now a Tcl script using the interface... +</p> -<p> -<blockquote><pre>load ./list.so list ; # Load the module +<blockquote><pre> +load ./list.so list ; # Load the module source swig_c++.tcl ; # Source the object file new List l @@ -2920,14 +3173,16 @@ $l remove Dave puts $l length_get delete l - </pre></blockquote> + +<p> The cool thing about this example is that it works with any C++ object wrapped by SWIG and requires no special compilation. Proof that a short, but clever Tcl script can be combined with SWIG to do many -interesting things.<p> +interesting things. +</p> -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : May 28, 2002</address> </body> diff --git a/Doc/Manual/Typemaps.html b/Doc/Manual/Typemaps.html index 1a12ca056..5dc114717 100644 --- a/Doc/Manual/Typemaps.html +++ b/Doc/Manual/Typemaps.html @@ -4,68 +4,68 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>8 Typemaps</H1> +<H1><a name="Typemaps"></a>10 Typemaps</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Introduction</a> +<li><a href="#Typemaps_nn2">Introduction</a> <ul> -<li><a href="#n3">Type conversion</a> -<li><a href="#n4">Typemaps</a> -<li><a href="#n5">Pattern matching</a> -<li><a href="#n6">Reusing typemaps</a> -<li><a href="#n7">What can be done with typemaps?</a> -<li><a href="#n8">What can't be done with typemaps?</a> -<li><a href="#n9">The rest of this chapter</a> +<li><a href="#Typemaps_nn3">Type conversion</a> +<li><a href="#Typemaps_nn4">Typemaps</a> +<li><a href="#Typemaps_nn5">Pattern matching</a> +<li><a href="#Typemaps_nn6">Reusing typemaps</a> +<li><a href="#Typemaps_nn7">What can be done with typemaps?</a> +<li><a href="#Typemaps_nn8">What can't be done with typemaps?</a> +<li><a href="#Typemaps_nn9">The rest of this chapter</a> </ul> -<li><a href="#n10">Typemap specifications</a> +<li><a href="#Typemaps_nn10">Typemap specifications</a> <ul> -<li><a href="#n11">Defining a typemap</a> -<li><a href="#n12">Typemap scope</a> -<li><a href="#n13">Copying a typemap</a> -<li><a href="#n14">Deleting a typemap</a> -<li><a href="#n15">Placement of typemaps</a> +<li><a href="#Typemaps_nn11">Defining a typemap</a> +<li><a href="#Typemaps_nn12">Typemap scope</a> +<li><a href="#Typemaps_nn13">Copying a typemap</a> +<li><a href="#Typemaps_nn14">Deleting a typemap</a> +<li><a href="#Typemaps_nn15">Placement of typemaps</a> </ul> -<li><a href="#n16">Pattern matching rules</a> +<li><a href="#Typemaps_nn16">Pattern matching rules</a> <ul> -<li><a href="#n17">Basic matching rules</a> -<li><a href="#n18">Typedef reductions</a> -<li><a href="#n19">Default typemaps</a> -<li><a href="#n20">Multi-arguments typemaps</a> +<li><a href="#Typemaps_nn17">Basic matching rules</a> +<li><a href="#Typemaps_nn18">Typedef reductions</a> +<li><a href="#Typemaps_nn19">Default typemaps</a> +<li><a href="#Typemaps_nn20">Multi-arguments typemaps</a> </ul> -<li><a href="#n21">Code generation rules</a> +<li><a href="#Typemaps_nn21">Code generation rules</a> <ul> -<li><a href="#n22">Scope</a> -<li><a href="#n23">Declaring new local variables</a> -<li><a href="#n24">Special variables</a> +<li><a href="#Typemaps_nn22">Scope</a> +<li><a href="#Typemaps_nn23">Declaring new local variables</a> +<li><a href="#Typemaps_nn24">Special variables</a> </ul> -<li><a href="#n25">Common typemap methods</a> +<li><a href="#Typemaps_nn25">Common typemap methods</a> <ul> -<li><a href="#n26">"in" typemap</a> -<li><a href="#n27">"typecheck" typemap</a> -<li><a href="#n28">"out" typemap</a> -<li><a href="#n29">"arginit" typemap</a> -<li><a href="#n30">"default" typemap</a> -<li><a href="#n31">"check" typemap</a> -<li><a href="#n32">"argout" typemap</a> -<li><a href="#n33">"freearg" typemap</a> -<li><a href="#n34">"newfree" typemap</a> -<li><a href="#n35">"memberin" typemap</a> -<li><a href="#n36">"varin" typemap</a> -<li><a href="#n37">"varout" typemap</a> -<li><a href="#n38">"throws" typemap</a> +<li><a href="#Typemaps_nn26">"in" typemap</a> +<li><a href="#Typemaps_nn27">"typecheck" typemap</a> +<li><a href="#Typemaps_nn28">"out" typemap</a> +<li><a href="#Typemaps_nn29">"arginit" typemap</a> +<li><a href="#Typemaps_nn30">"default" typemap</a> +<li><a href="#Typemaps_nn31">"check" typemap</a> +<li><a href="#Typemaps_nn32">"argout" typemap</a> +<li><a href="#Typemaps_nn33">"freearg" typemap</a> +<li><a href="#Typemaps_nn34">"newfree" typemap</a> +<li><a href="#Typemaps_nn35">"memberin" typemap</a> +<li><a href="#Typemaps_nn36">"varin" typemap</a> +<li><a href="#Typemaps_nn37">"varout" typemap</a> +<li><a href="#throws_typemap">"throws" typemap</a> </ul> -<li><a href="#n39">Some typemap examples</a> +<li><a href="#Typemaps_nn39">Some typemap examples</a> <ul> -<li><a href="#n40">Typemaps for arrays</a> -<li><a href="#n41">Implementing constraints with typemaps</a> +<li><a href="#Typemaps_nn40">Typemaps for arrays</a> +<li><a href="#Typemaps_nn41">Implementing constraints with typemaps</a> </ul> -<li><a href="#n42">Multi-argument typemaps</a> -<li><a href="#n43">The run-time type checker</a> -<li><a href="#n44">Typemaps and overloading</a> -<li><a href="#n45">More about <tt>%apply</tt> and <tt>%clear</tt></a> -<li><a href="#n46">Reducing wrapper code size</a> -<li><a href="#n47">Passing data between typemaps</a> -<li><a href="#n48">Where to go for more information?</a> +<li><a href="#Typemaps_nn42">Multi-argument typemaps</a> +<li><a href="#runtime_type_checker">The run-time type checker</a> +<li><a href="#Typemaps_nn44">Typemaps and overloading</a> +<li><a href="#Typemaps_nn45">More about <tt>%apply</tt> and <tt>%clear</tt></a> +<li><a href="#Typemaps_nn46">Reducing wrapper code size</a> +<li><a href="#Typemaps_nn47">Passing data between typemaps</a> +<li><a href="#Typemaps_nn48">Where to go for more information?</a> </ul> <!-- INDEX --> @@ -73,7 +73,7 @@ <b>Disclaimer: This chapter is under construction!</b> -<a name="n2"></a><H2>8.1 Introduction</H2> +<H2><a name="Typemaps_nn2"></a>10.1 Introduction</H2> Chances are, you are reading this chapter for one of two reasons; you @@ -88,9 +88,10 @@ non-trivial topic of its own). Typemaps are generally to re-read the earlier chapters if you have found your way to this chapter with only a vaque idea of what SWIG already does by default. -<a name="n3"></a><H3>8.1.1 Type conversion</H3> +<H3><a name="Typemaps_nn3"></a>10.1.1 Type conversion</H3> +<p> One of the most important problems in wrapper code generation is the conversion of datatypes between programming languages. Specifically, for every C/C++ declaration, SWIG must somehow generate wrapper code @@ -99,9 +100,11 @@ Since every programming language represents data differently, this is not a simple of matter of simply linking code together with the C linker. Instead, SWIG has to know something about how data is represented in each language and how it can be manipulated. +</p> <p> To illustrate, suppose you had a simple C function like this: +</p> <blockquote> <pre> @@ -114,8 +117,8 @@ are used to convert integer values. For example: <blockquote> <pre> -long PyInt_AsLong(PyObject *obj); /* Python --> C */ -PyObject *PyInt_FromLong(long x); /* C --> Python */ +long PyInt_AsLong(PyObject *obj); /* Python --> C */ +PyObject *PyInt_FromLong(long x); /* C --> Python */ </pre> </blockquote> @@ -124,6 +127,7 @@ to C <tt>long</tt>. The second function is used to convert a value from C back <p> Inside the wrapper function, you might see these functions used like this: +</p> <blockquote> <pre> @@ -145,11 +149,12 @@ PyObject *wrap_factorial(PyObject *self, PyObject *args) { <p> Every target language supported by SWIG has functions that work in a similar manner. For example, in Perl, the following functions are used: +</p> <blockquote> <pre> -IV SvIV(SV *sv); /* Perl --> C */ -void sv_setiv(SV *sv, IV val); /* C --> Perl */ +IV SvIV(SV *sv); /* Perl --> C */ +void sv_setiv(SV *sv, IV val); /* C --> Perl */ </pre> </blockquote> @@ -168,7 +173,7 @@ utility functions and short bits of C code like this---you simply have to read the extension documentation for your favorite language to know how it works (an exercise left to the reader). -<a name="n4"></a><H3>8.1.2 Typemaps</H3> +<H3><a name="Typemaps_nn4"></a>10.1.2 Typemaps</H3> Since type handling is so central to wrapper code generation, SWIG @@ -177,12 +182,12 @@ a special <tt>%typemap</tt> directive is used. For example: <blockquote> <pre> -/* Convert from Python --> C */ +/* Convert from Python --> C */ %typemap(in) int { $1 = PyInt_AsLong($input); } -/* Convert from C --> Python */ +/* Convert from C --> Python */ %typemap(out) int { $result = PyInt_FromLong($1); } @@ -207,6 +212,7 @@ example). <p> A short example might make this a little more clear. If you were wrapping a function like this: +</p> <blockquote> <pre> @@ -257,7 +263,7 @@ whole idea behind typemaps--they simply let you insert arbitrary code into diffe parts of the generated wrapper functions. Because arbitrary code can be inserted, it possible to completely change the way in which values are converted. -<a name="n5"></a><H3>8.1.3 Pattern matching</H3> +<H3><a name="Typemaps_nn5"></a>10.1.3 Pattern matching</H3> As the name implies, the purpose of a typemap is to "map" C datatypes to @@ -266,7 +272,7 @@ it is applied to all future occurrences of that type in the input file. For exa <blockquote> <pre> -/* Convert from Perl --> C */ +/* Convert from Perl --> C */ %typemap(in) <b><font color="#ff0000">int</font></b> { $1 = SvIV($input); } @@ -285,7 +291,7 @@ underlying type. For example, you could have code like this: <blockquote> <pre> -/* Convert from Ruby--> C */ +/* Convert from Ruby--> C */ %typemap(in) <b><font color="#ff0000">int</font></b> { $1 = NUM2INT($input); } @@ -309,6 +315,7 @@ is never necessary to write new typemaps for typenames introduced by <tt>typedef <p> In addition to tracking typenames, typemaps may also be specialized to match against a specific argument name. For example, you could write a typemap like this: +</p> <blockquote> <pre> @@ -348,7 +355,7 @@ int count(<b><font color="#ff0000">char *str, int len</font></b>, char c); In this case, a single input object is expanded into a pair of C arguments. This example also provides a hint to the unusual variable naming scheme involving <tt>$1</tt>, <tt>$2</tt>, and so forth. -<a name="n6"></a><H3>8.1.4 Reusing typemaps</H3> +<H3><a name="Typemaps_nn6"></a>10.1.4 Reusing typemaps</H3> Typemaps are normally defined for specific type and argument name patterns. However, typemaps can also @@ -386,6 +393,7 @@ applies them to other types. Note: you can include a comma separated set of typ <p> It should be noted that it is not necessary to copy typemaps for types that are related by <tt>typedef</tt>. For example, if you have this, +</p> <blockquote> <pre> @@ -395,15 +403,16 @@ typedef int size_t; then SWIG already knows that the <tt>int</tt> typemaps apply. You don't have to do anything. -<a name="n7"></a><H3>8.1.5 What can be done with typemaps?</H3> +<H3><a name="Typemaps_nn7"></a>10.1.5 What can be done with typemaps?</H3> The primary use of typemaps is for defining wrapper generation behavior at the level of individual C/C++ datatypes. There are currently six general categories of problems that typemaps address: -<P> +<p> <b>Argument handling</b> +</p> <blockquote> <pre> @@ -411,19 +420,19 @@ int foo(<b><font color="#ff0000">int x, double y, char *s</font></b>); </pre> </blockquote> -<p> <ul> -<li>Input argument conversion ("in" typemap). -<li>Input argument type checking ("typecheck" typemap). -<li>Output argument handling ("argout" typemap). -<li>Input argument value checking ("check" typemap). -<li>Input argument initialization ("arginit" typemap). -<li>Default arguments ("default" typemap). -<li>Input argument resource management ("freearg" typemap). +<li>Input argument conversion ("in" typemap).</li> +<li>Input argument type checking ("typecheck" typemap).</li> +<li>Output argument handling ("argout" typemap).</li> +<li>Input argument value checking ("check" typemap).</li> +<li>Input argument initialization ("arginit" typemap).</li> +<li>Default arguments ("default" typemap).</li> +<li>Input argument resource management ("freearg" typemap).</li> </ul> <p> <b>Return value handling</b> +</p> <blockquote> <pre> @@ -431,30 +440,29 @@ int foo(<b><font color="#ff0000">int x, double y, char *s</font></b>); </pre> </blockquote> -<p> <ul> -<li>Function return value conversion ("out" typemap). -<li>Return value resource management ("ret" typemap). -<li>Resource management for newly allocated objects ("newfree" typemap). +<li>Function return value conversion ("out" typemap).</li> +<li>Return value resource management ("ret" typemap).</li> +<li>Resource management for newly allocated objects ("newfree" typemap).</li> </ul> -<P> +<p> <b>Exception handling</b> +</p> -<p> <blockquote> <pre> <b><font color="#ff0000">int</font></b> foo(int x, double y, char *s) throw(<b><font color="#ff0000">MemoryError, IndexError</font></b>); </pre> </blockquote> -<p> <ul> -<li>Handling of C++ exception specifiers. ("throw" typemap). +<li>Handling of C++ exception specifiers. ("throw" typemap).</li> </ul> <p> <b>Global variables</b> +</p> <blockquote> <pre> @@ -462,14 +470,14 @@ int foo(<b><font color="#ff0000">int x, double y, char *s</font></b>); </pre> </blockquote> -<p> <ul> -<li>Assignment of a global variable. ("varin" typemap). -<li>Reading a global variable. ("varout" typemap). +<li>Assignment of a global variable. ("varin" typemap).</li> +<li>Reading a global variable. ("varout" typemap).</li> </ul> <p> <b>Member variables</b> +</p> <blockquote> <pre> @@ -479,12 +487,13 @@ struct Foo { </pre> </blockquote> -<p> <ul> -<li>Assignment of data to a class/structure member. ("memberin" typemap). +<li>Assignment of data to a class/structure member. ("memberin" typemap).</li> </ul> -<p><b>Constant creation</b> +<p> +<b>Constant creation</b> +</p> <blockquote> <pre> @@ -494,16 +503,15 @@ enum { ALE, LAGER, STOUT }; </pre> </blockquote> -<p> <ul> -<li>Creation of constant values. ("consttab" or "constcode" typemap). +<li>Creation of constant values. ("consttab" or "constcode" typemap).</li> </ul> Details of each of these typemaps will be covered shortly. Also, certain language modules may define additional typemaps that expand upon this list. For example, the Java module defines a variety of typemaps for controlling additional aspects of the Java bindings. Consult language specific documentation for further details. -<a name="n8"></a><H3>8.1.6 What can't be done with typemaps?</H3> +<H3><a name="Typemaps_nn8"></a>10.1.6 What can't be done with typemaps?</H3> Typemaps can't be used to define properties that apply to C/C++ declarations as a whole. For example, @@ -521,12 +529,13 @@ management). Clearly, this property of <tt>make_Foo()</tt> is <em>not</em> a property that would be associated with the datatype <tt>Foo *</tt> by itself. Therefore, a completely different SWIG customization mechanism (<tt>%feature</tt>) is used for this purpose. Consult the <a -href="Customization.html">Customization Features</a> chapter for more +href="Customization.html#Customization">Customization Features</a> chapter for more information about that. -<P> +<p> Typemaps also can't be used to rearrange or transform the order of arguments. For example, if you had a function like this: +</p> <blockquote> <pre> @@ -557,7 +566,7 @@ void wrap_foo(char *s, int x) { </pre> </blockquote> -<a name="n9"></a><H3>8.1.7 The rest of this chapter</H3> +<H3><a name="Typemaps_nn9"></a>10.1.7 The rest of this chapter</H3> The rest of this chapter provides detailed information for people who @@ -573,13 +582,14 @@ basic details of values, pointers, references, arrays, type qualifiers management in C/C++. If not, you would be well-advised to consult a copy of "The C Programming Language" by Kernighan and Ritchie or "The C++ Programming Language" by Stroustrup before going any further. +</p> -<a name="n10"></a><H2>8.2 Typemap specifications</H2> +<H2><a name="Typemaps_nn10"></a>10.2 Typemap specifications</H2> This section describes the behavior of the <tt>%typemap</tt> directive itself. -<a name="n11"></a><H3>8.2.1 Defining a typemap</H3> +<H3><a name="Typemaps_nn11"></a>10.2.1 Defining a typemap</H3> New typemaps are defined using the <tt>%typemap</tt> declaration. The general form of @@ -598,10 +608,12 @@ these methods is described later. <p> <em>modifiers</em> is an optional comma separated list of <tt>name="value"</tt> values. These are sometimes to attach extra information to a typemap and is often target-language dependent. +</p> <p> <em>typelist</em> is a list of the C++ type patterns that the typemap will match. The general form of this list is as follows: +</p> <blockquote> <pre> @@ -620,6 +632,7 @@ variables (parms). The purpose of these variables will be explained shortly. <p><em>code</em> specifies the C code used in the typemap. It can take any one of the following forms: +</p> <blockquote> <pre> @@ -675,7 +688,7 @@ Here are some examples of valid typemap specifications: Admittedly, it's not the most readable syntax at first glance. However, the purpose of the individual pieces will become clear. -<a name="n12"></a><H3>8.2.2 Typemap scope</H3> +<H3><a name="Typemaps_nn12"></a>10.2.2 Typemap scope</H3> Once defined, a typemap remains in effect for all of the declarations that follow. A typemap may be redefined for @@ -721,7 +734,7 @@ class Foo { </pre> </blockquote> -<a name="n13"></a><H3>8.2.3 Copying a typemap</H3> +<H3><a name="Typemaps_nn13"></a>10.2.3 Copying a typemap</H3> A typemap is copied by using assignment. For example: @@ -769,7 +782,7 @@ The patterns for <tt>%apply</tt> follow the same rules as for <tt>%typemap</tt>. </pre> </blockquote> -<a name="n14"></a><H3>8.2.4 Deleting a typemap</H3> +<H3><a name="Typemaps_nn14"></a>10.2.4 Deleting a typemap</H3> A typemap can be deleted by simply defining no code. For example: @@ -796,7 +809,7 @@ For example: <tt>int</tt> will make that type unusable unless you also define a new set of typemaps immediately after the clear operation. -<a name="n15"></a><H3>8.2.5 Placement of typemaps</H3> +<H3><a name="Typemaps_nn15"></a>10.2.5 Placement of typemaps</H3> Typemap declarations can be declared in the global scope, within a C++ namespace, and within a C++ class. For @@ -866,13 +879,14 @@ types (<tt>std::string</tt> and <tt>Foo::string</tt>). <p> It should be noted that for scoping to work, SWIG has to know that <tt>string</tt> is a typename defined within a particular namespace. In this example, this is done using the class declaration <tt>class string</tt>. +</p> -<a name="n16"></a><H2>8.3 Pattern matching rules</H2> +<H2><a name="Typemaps_nn16"></a>10.3 Pattern matching rules</H2> The section describes the pattern matching rules by which C datatypes are associated with typemaps. -<a name="n17"></a><H3>8.3.1 Basic matching rules</H3> +<H3><a name="Typemaps_nn17"></a>10.3.1 Basic matching rules</H3> Typemaps are matched using both a type and a name (typically the name of a argument). For a given @@ -950,7 +964,7 @@ void F(int x[1000]); // int [ANY] rule (typemap 5) </pre> </blockquote> -<a name="n18"></a><H3>8.3.2 Typedef reductions</H3> +<H3><a name="Typemaps_nn18"></a>10.3.2 Typedef reductions</H3> If no match is found using the rules in the previous section, SWIG @@ -978,13 +992,13 @@ Integer </pre> </blockquote> -Finding no match, it then applies a reduction <tt>Integer -> int</tt> to the type and +Finding no match, it then applies a reduction <tt>Integer -> int</tt> to the type and repeats the search. <blockquote> <pre> int x -int --> match: typemap 1 +int --> match: typemap 1 </pre> </blockquote> @@ -1015,6 +1029,7 @@ match is found or until no more reductions can be made. <p> For complicated types, the reduction process can generate a long list of patterns. Consider the following: +</p> <blockquote> <pre> @@ -1086,7 +1101,7 @@ type are reductions made to other parts of the type. This behavior means that is rather esoteric--there's little practical reason to write a typemap quite like that. Of course, you could rely on this to confuse your coworkers even more. -<a name="n19"></a><H3>8.3.3 Default typemaps</H3> +<H3><a name="Typemaps_nn19"></a>10.3.3 Default typemaps</H3> Most SWIG language modules use typemaps to define the default behavior of the C primitive types. This @@ -1104,9 +1119,10 @@ is entirely straightforward. For example, a set of typemaps are written like th Since typemap matching follows all <tt>typedef</tt> declarations, any sort of type that is mapped to a primitive type through <tt>typedef</tt> will be picked up by one of these primitive typemaps. -<P> +<p> The default behavior for pointers, arrays, references, and other kinds of types are handled by specifying rules for variations of the reserved <tt>SWIGTYPE</tt> type. For example: +</p> <blockquote> <pre> @@ -1126,6 +1142,7 @@ types of pointers, you would simply redefine the rule for <tt>SWIGTYPE <p> Finally, the following typemap rule is used to match against simple types that don't match any other rules: +</p> <blockquote> <pre> @@ -1153,20 +1170,23 @@ behavior. For example, if you cleared all typemaps for <tt>SWIGTYPE</tt>, SWIG simply won't wrap any unknown datatype (which might be useful for debugging). Alternatively, you might modify SWIGTYPE to marshal objects into strings instead of converting them to pointers. +</p> <p> The best way to explore the default typemaps is to look at the ones already defined for a particular language module. Typemaps definitions are usually found in the SWIG library in a file such as <tt>python.swg</tt>, <tt>tcl8.swg</tt>, etc. +</p> -<a name="n20"></a><H3>8.3.4 Multi-arguments typemaps</H3> +<H3><a name="Typemaps_nn20"></a>10.3.4 Multi-arguments typemaps</H3> <p> When multi-argument typemaps are specified, they take precedence over any typemaps specified for a single type. For example: +</p> <blockquote> <pre> @@ -1188,13 +1208,13 @@ Currently, the first argument follows the matching rules described in the previo but all subsequent arguments must match exactly. -<a name="n21"></a><H2>8.4 Code generation rules</H2> +<H2><a name="Typemaps_nn21"></a>10.4 Code generation rules</H2> This section describes rules by which typemap code is inserted into the generated wrapper code. -<a name="n22"></a><H3>8.4.1 Scope</H3> +<H3><a name="Typemaps_nn22"></a>10.4.1 Scope</H3> When a typemap is defined like this: @@ -1230,7 +1250,7 @@ for use during typemap execution. For example: <pre> %typemap(in) short { long temp; /* Temporary value */ - if (Tcl_GetLongFromObj(interp, $input, &temp) != TCL_OK) { + if (Tcl_GetLongFromObj(interp, $input, &temp) != TCL_OK) { return TCL_ERROR; } $1 = (short) temp; @@ -1244,6 +1264,7 @@ that might use the same variable names). <p> Occasionally, typemap code will be specified using a few alternative forms. For example: +</p> <blockquote> <pre> @@ -1257,7 +1278,7 @@ $1 = PyInt_AsLong($input); These two forms are mainly used for cosmetics--the specified code is not enclosed inside a block scope when it is emitted. This sometimes results in a less complicated looking wrapper function. -<a name="n23"></a><H3>8.4.2 Declaring new local variables</H3> +<H3><a name="Typemaps_nn23"></a>10.4.2 Declaring new local variables</H3> Sometimes it is useful to declare a new local variable that exists @@ -1291,7 +1312,7 @@ then pass a pointer to the object. To do this, simply specify the typemap with char *s; s = SvPV($input,len); /* Extract string data */ temp.assign(s,len); /* Assign to temp */ - $1 = &temp; /* Set argument to point to temp */ + $1 = &temp; /* Set argument to point to temp */ } </pre> </blockquote> @@ -1323,11 +1344,10 @@ cleaned up automatically on exit. <p> It is perfectly safe to use more than one typemap involving local variables in the same declaration. For example, you could declare a -function as :<p> - -<p> -<blockquote><pre>void foo(std::string *x, std::string *y, std::string *z); +function as :</p> +<blockquote><pre> +void foo(std::string *x, std::string *y, std::string *z); </pre></blockquote> This is safely handled because SWIG actually renames all local @@ -1373,16 +1393,18 @@ wrap_foo() { <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. +</p> -<a name="n24"></a><H3>8.4.3 Special variables</H3> +<H3><a name="Typemaps_nn24"></a>10.4.3 Special variables</H3> +<p> Within all typemaps, the following special variables are expanded. +</p> -<p> <center> -<table border=1> +<table border=1 summary="Typemap special variables"> <tr><th>Variable</th><th>Meaning</th></tr> <tr> @@ -1391,6 +1413,7 @@ Within all typemaps, the following special variables are expanded. A C local variable corresponding to type <em>n</em> in the typemap pattern. </td> +</tr> <tr> <td>$argnum</td> @@ -1447,22 +1470,22 @@ run-time type checker (described later).</td> <tr> -<td>$&<em>n</em>_type</td> +<td>$&<em>n</em>_type</td> <td>Real C datatype of type <em>n</em> with one pointer added.</td> </tr> <tr> -<td>$&<em>n</em>_ltype</td> +<td>$&<em>n</em>_ltype</td> <td>ltype of type <em>n</em> with one pointer added.</td> </tr> <tr> -<td>$&<em>n</em>_mangle</td> +<td>$&<em>n</em>_mangle</td> <td>Mangled form of type <em>n</em> with one pointer added.</td> </tr> <tr> -<td>$&<em>n</em>_descriptor</td> +<td>$&<em>n</em>_descriptor</td> <td>Type descriptor structure for type <em>n</em> with one pointer added. </tr> @@ -1470,6 +1493,7 @@ run-time type checker (described later).</td> <td>$<em>n</em>_basetype</td> <td>Base typename with all pointers and qualifiers stripped. </td> +</tr> </table> </center> @@ -1477,6 +1501,7 @@ run-time type checker (described later).</td> <p> Within the table, $<em>n</em> refers to a specific type within the typemap specification. For example, if you write this +</p> <blockquote> <pre> @@ -1501,6 +1526,7 @@ then $1 refers to <tt>int argc</tt> and $2 refers to <tt>char *argv[]</tt>. <p> Substitutions related to types and names always fill in values from the actual code that was matched. This is useful when a typemap might match multiple C datatype. For example: +</p> <blockquote> <pre> @@ -1518,6 +1544,7 @@ When typemap code is emitted, the C/C++ datatype of the special variables <tt>$1 <tt>$2</tt> is always an "ltype." An "ltype" is simply a type that can legally appear on the left-hand side of a C assignment operation. Here are a few examples of types and ltypes: +</p> <blockquote> <pre> @@ -1535,19 +1562,21 @@ In most cases a ltype is simply the C datatype with qualifiers stripped off. In arrays are converted into pointers. <p> -Variables such as <tt>$&1_type</tt> and <tt>$*1_type</tt> are used to +Variables such as <tt>$&1_type</tt> and <tt>$*1_type</tt> are used to safely modify the type by removing or adding pointers. Although not needed in most typemaps, these substitutions are sometimes needed to properly work with typemaps that convert values between pointers and values. +</p> <p> If necessary, type related substitutions can also be used when declaring locals. For example: +</p> <blockquote> <pre> %typemap(in) int * ($*1_type temp) { temp = PyInt_AsLong($input); - $1 = &temp; + $1 = &temp; } </pre> </blockquote> @@ -1556,6 +1585,7 @@ If necessary, type related substitutions can also be used when declaring locals. There is one word of caution about declaring local variables in this manner. If you declare a local variable using a type substitution such as <tt>$1_ltype temp</tt>, it won't work like you expect for arrays and certain kinds of pointers. For example, if you wrote this, +</p> <blockquote> <pre> @@ -1603,13 +1633,13 @@ Another approach, which only works for arrays is to use the <tt>$1_basetype</tt> </pre> </blockquote> -<a name="n25"></a><H2>8.5 Common typemap methods</H2> +<H2><a name="Typemaps_nn25"></a>10.5 Common typemap methods</H2> The set of typemaps recognized by a language module may vary. However, the following typemap methods are nearly universal: -<a name="n26"></a><H3>8.5.1 "in" typemap</H3> +<H3><a name="Typemaps_nn26"></a>10.5.1 "in" typemap</H3> The "in" typemap is used to convert function arguments from the target language @@ -1638,12 +1668,13 @@ to implement customized conversions. <p> In addition, the "in" typemap allows the number of converted arguments to be specified. For example: +</p> <blockquote> <pre> // Ignored argument. %typemap(in, numinputs=0) int *out (int temp) { - $1 = &temp; + $1 = &temp; } </pre> </blockquote> @@ -1653,8 +1684,9 @@ At this time, only zero or one arguments may be converted. <p> <b>Compatibility note: </b> Specifying <tt>numinputs=0</tt> is the same as the old "ignore" typemap. +</p> -<a name="n27"></a><H3>8.5.2 "typecheck" typemap</H3> +<H3><a name="Typemaps_nn27"></a>10.5.2 "typecheck" typemap</H3> The "typecheck" typemap is used to support overloaded functions and methods. It merely checks an argument @@ -1674,8 +1706,9 @@ the input argument is the correct type. <p> If you define new "in" typemaps <em>and</em> your program uses overloaded methods, you should also define a collection of "typecheck" typemaps. More details about this follow in a later section on "Typemaps and Overloading." +</p> -<a name="n28"></a><H3>8.5.3 "out" typemap</H3> +<H3><a name="Typemaps_nn28"></a>10.5.3 "out" typemap</H3> The "out" typemap is used to convert function/method return values from C @@ -1697,7 +1730,7 @@ $symname - Name of function/method being wrapped </pre> </blockquote> -<a name="n29"></a><H3>8.5.4 "arginit" typemap</H3> +<H3><a name="Typemaps_nn29"></a>10.5.4 "arginit" typemap</H3> The "arginit" typemap is used to set the initial value of a function @@ -1714,7 +1747,7 @@ For example: </pre> </blockquote> -<a name="n30"></a><H3>8.5.5 "default" typemap</H3> +<H3><a name="Typemaps_nn30"></a>10.5.5 "default" typemap</H3> The "default" typemap is used to turn an argument into a default @@ -1737,8 +1770,9 @@ they aren't supported (like C). <p> Once a default typemap has been applied to an argument, all arguments that follow must have default values. +</p> -<a name="n31"></a><H3>8.5.6 "check" typemap</H3> +<H3><a name="Typemaps_nn31"></a>10.5.6 "check" typemap</H3> The "check" typemap is used to supply value checking code during argument @@ -1755,7 +1789,7 @@ converted. For example: </pre> </blockquote> -<a name="n32"></a><H3>8.5.7 "argout" typemap</H3> +<H3><a name="Typemaps_nn32"></a>10.5.7 "argout" typemap</H3> The "argout" typemap is used to return values from arguments. This @@ -1767,7 +1801,7 @@ with an "in" typemap---possibly to ignore the input value. For example: <pre> /* Set the input argument to point to a temporary variable */ %typemap(in, numinputs=0) int *out (int temp) { - $1 = &temp; + $1 = &temp; } %typemap(argout) int *out { @@ -1792,8 +1826,9 @@ return values are often appended to return value of the function. <p> See the <tt>typemaps.i</tt> library for examples. +</p> -<a name="n33"></a><H3>8.5.8 "freearg" typemap</H3> +<H3><a name="Typemaps_nn33"></a>10.5.8 "freearg" typemap</H3> The "freearg" typemap is used to cleanup argument data. It is only @@ -1822,7 +1857,7 @@ code is also placed into a special variable <tt>$cleanup</tt> that may be used in other typemaps whenever a wrapper function needs to abort prematurely. -<a name="n34"></a><H3>8.5.9 "newfree" typemap</H3> +<H3><a name="Typemaps_nn34"></a>10.5.9 "newfree" typemap</H3> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt> @@ -1835,7 +1870,7 @@ of a function. For example: delete $1; } %typemap(out) string * { - $result = PyString_FromString($1->c_str()); + $result = PyString_FromString($1->c_str()); } ... @@ -1845,7 +1880,7 @@ string *foo(); </pre> </blockquote> -<a name="n35"></a><H3>8.5.10 "memberin" typemap</H3> +<H3><a name="Typemaps_nn35"></a>10.5.10 "memberin" typemap</H3> The "memberin" typemap is used to copy data from <em>an already converted input value</em> @@ -1863,20 +1898,19 @@ cases. For example: It is rarely necessary to write "memberin" typemaps---SWIG already provides a default implementation for arrays, strings, and other objects. -<a name="n36"></a><H3>8.5.11 "varin" typemap</H3> +<H3><a name="Typemaps_nn36"></a>10.5.11 "varin" typemap</H3> The "varin" typemap is used to convert objects in the target language to C for the purposes of assigning to a C/C++ global variable. This is implementation specific. -<a name="n37"></a><H3>8.5.12 "varout" typemap</H3> +<H3><a name="Typemaps_nn37"></a>10.5.12 "varout" typemap</H3> The "varout" typemap is used to convert a C/C++ object to an object in the target language when reading a C/C++ global variable. This is implementation specific. -<a name="throws_typemap"></a> -<a name="n38"></a><H3>8.5.13 "throws" typemap</H3> +<H3><a name="throws_typemap"></a>10.5.13 "throws" typemap</H3> The "throws" typemap is only used when SWIG parses a C++ method with an exception specification. @@ -1916,13 +1950,13 @@ catch(char const *_e) { Note that if your methods do not have an exception specification yet they do throw exceptions, SWIG cannot know how to deal with them. For a neat way to handle these, see the <a href="Customization.html#exception">Exception handling with %exception</a> section. -<a name="n39"></a><H2>8.6 Some typemap examples</H2> +<H2><a name="Typemaps_nn39"></a>10.6 Some typemap examples</H2> This section contains a few examples. Consult language module documentation for more examples. -<a name="n40"></a><H3>8.6.1 Typemaps for arrays</H3> +<H3><a name="Typemaps_nn40"></a>10.6.1 Typemaps for arrays</H3> A common use of typemaps is to provide support for C arrays appearing both as @@ -1930,6 +1964,7 @@ arguments to functions and as structure members. <p> For example, suppose you had a function like this: +</p> <blockquote> <pre> @@ -1972,15 +2007,17 @@ C stack. The typemap then populates this array and passes it to the underlying <p> When used from Python, the typemap allows the following type of function call: +</p> <blockquote> <pre> ->>> set_vector(type, [ 1, 2.5, 5, 20 ]) +>>> set_vector(type, [ 1, 2.5, 5, 20 ]) </pre> </blockquote> <p> If you wanted to generalize the typemap to apply to arrays of all dimensions you might write this: +</p> <blockquote> <pre> @@ -2059,9 +2096,10 @@ Another common use of array typemaps is to provide support for array structure m Due to subtle differences between pointers and arrays in C, you can't just "assign" to a array structure member. Instead, you have to explicitly copy elements into the array. For example, suppose you had a structure like this: +</p> -<p> -<blockquote><pre>struct SomeObject { +<blockquote><pre> +struct SomeObject { float value[4]; ... }; @@ -2070,8 +2108,8 @@ For example, suppose you had a structure like this: When SWIG runs, it won't produce any code to set the <tt>vec</tt> member. You may even get a warning message like this: -<p> -<blockquote><pre>swig -python example.i +<blockquote><pre> +swig -python example.i Generating wrappers for Python example.i:10. Warning. Array member value will be read-only. </pre></blockquote> @@ -2079,9 +2117,11 @@ example.i:10. Warning. Array member value will be read-only. <p> These warning messages indicate that SWIG does not know how you want to set the <tt>vec</tt> field. +</p> <p> To fix this, you can supply a special "memberin" typemap like this: +</p> <blockquote><pre> %typemap(memberin) float [ANY] { @@ -2096,15 +2136,17 @@ To fix this, you can supply a special "memberin" typemap like this: The memberin typemap is used to set a structure member from data that has already been converted from the target language to C. In this case, <tt>$input</tt> is the local variable in which converted input data is stored. This typemap then copies this data into the structure. +</p> <p> When combined with the earlier typemaps for arrays, the combination of the "in" and "memberin" typemap allows the following usage: +</p> <blockquote> <pre> ->>> s = SomeObject() ->>> s.x = [1, 2.5, 5, 10] +>>> s = SomeObject() +>>> s.x = [1, 2.5, 5, 10] </pre> </blockquote> @@ -2112,14 +2154,15 @@ the following usage: Related to structure member input, it may be desirable to return structure members as a new kind of object. For example, in this example, you will get very odd program behavior where the structure member can be set nicely, but reading the member simply returns a pointer: +</p> <blockquote> <pre> ->>> s = SomeObject() ->>> s.x = [1, 2.5, 5. 10] ->>> print s.x +>>> s = SomeObject() +>>> s.x = [1, 2.5, 5. 10] +>>> print s.x _1008fea8_p_float ->>> +>>> </pre> </blockquote> @@ -2142,9 +2185,9 @@ Now, you will find that member access is quite nice: <blockquote> <pre> ->>> s = SomeObject() ->>> s.x = [1, 2.5, 5, 10] ->>> print s.x +>>> s = SomeObject() +>>> s.x = [1, 2.5, 5, 10] +>>> print s.x [ 1, 2.5, 5, 10] </pre> </blockquote> @@ -2152,15 +2195,17 @@ Now, you will find that member access is quite nice: <b>Compatibility Note:</b> SWIG1.1 used to provide a special "memberout" typemap. However, it was mostly useless and has since been eliminated. To return structure members, simply use the "out" typemap. -<a name="n41"></a><H3>8.6.2 Implementing constraints with typemaps</H3> +<H3><a name="Typemaps_nn41"></a>10.6.2 Implementing constraints with typemaps</H3> +<p> One particularly interesting application of typemaps is the implementation of argument constraints. This can be done with the "check" typemap. When used, this allows you to provide code for -checking the values of function arguments. For example :<p> -<p> -<blockquote><pre>%module math +checking the values of function arguments. For example :</p> + +<blockquote><pre> +%module math %typemap(check) double posdouble { if ($1 < 0) { @@ -2173,15 +2218,17 @@ double sqrt(double posdouble); </pre></blockquote> +<p> This provides a sanity check to your wrapper function. If a negative number is passed to this function, a Perl exception will be raised and -your program terminated with an error message.<p> +your program terminated with an error message.</p> <p> This kind of checking can be particularly useful when working with -pointers. For example :<p> -<p> -<blockquote><pre>%typemap(check) Vector * { +pointers. For example :</p> + +<blockquote><pre> +%typemap(check) Vector * { if ($1 == 0) { PyErr_SetString(PyExc_TypeError,"NULL Pointer not allowed"); return NULL; @@ -2190,15 +2237,17 @@ pointers. For example :<p> </pre></blockquote> +<p> will prevent any function involving a <tt>Vector *</tt> from accepting 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> +rather than blindly passing values to the underlying C/C++ program.</p> <p> Note: A more advanced constraint checking system is in development. Stay tuned. +</p> -<a name="n42"></a><H2>8.7 Multi-argument typemaps</H2> +<H2><a name="Typemaps_nn42"></a>10.7 Multi-argument typemaps</H2> So far, the typemaps presented have focused on the problem of dealing with @@ -2218,7 +2267,7 @@ list of strings like this: <blockquote> <pre> ->>> foo(["ale","lager","stout"]) +>>> foo(["ale","lager","stout"]) </pre> </blockquote> @@ -2232,6 +2281,7 @@ A multi-argument typemap is a conversion rule that specifies how to convert a <em>single</em> object in the target language to set of consecutive function arguments in C/C++. For example, the following multi-argument maps perform the conversion described for the above example: +</p> <blockquote> <pre> @@ -2277,6 +2327,7 @@ prefix on the variable name (e.g., <tt>$2_type</tt>, <tt>$1_ltype</tt>, etc.) <p> Multi-argument typemaps always have precedence over simple typemaps and SWIG always performs longest-match searching. Therefore, you will get the following behavior: +</p> <blockquote> <pre> @@ -2381,24 +2432,25 @@ scripting language object being returned to the interpreter.). <p> Now, in a script, you can write code that simply passes buffers as strings like this: +</p> <blockquote> <pre> ->>> f = example.open("Makefile") ->>> example.read(f,40) +>>> f = example.open("Makefile") +>>> example.read(f,40) 'TOP = ../..\nSWIG = $(TOP)/.' ->>> example.read(f,40) +>>> example.read(f,40) './swig\nSRCS = example.c\nTARGET ' ->>> example.close(f) +>>> example.close(f) 0 ->>> g = example.open("foo", example.O_WRONLY | example.O_CREAT, 0644) ->>> example.write(g,"Hello world\n") +>>> g = example.open("foo", example.O_WRONLY | example.O_CREAT, 0644) +>>> example.write(g,"Hello world\n") 12 ->>> example.write(g,"This is a test\n") +>>> example.write(g,"This is a test\n") 15 ->>> example.close(g) +>>> example.close(g) 0 ->>> +>>> </pre> </blockquote> @@ -2434,16 +2486,16 @@ Numeric Python. However, it should also be stressed that some care is in order. when crossing languages you may need to worry about issues such as row-major vs. column-major ordering (and perform conversions if needed). -<a name="n43"></a><H2>8.8 The run-time type checker</H2> +<H2><a name="runtime_type_checker"></a>10.8 The run-time type checker</H2> +<p> The run-time type checker is used by many, but not all, of SWIG's supported target languages. The run-time type checker features are not required and are thus not used for strongly typed languages such as Java and C#. The scripting and scheme based languages rely on it and it forms a critical part of SWIG's operation for these languages. - -<p/> +</p> When pointers, arrays, and objects are wrapped by SWIG, they are normally converted into typed pointer objects. For example, an instance of <tt>Foo *</tt> might be @@ -2504,6 +2556,7 @@ handling of pointer values (and to make adjustments when needed). In the wrapper code generated for each language, pointers are handled through the use of special type descriptors and conversion functions. For example, if you look at the wrapper code for Python, you will see code like this: +</p> <blockquote> <pre> @@ -2525,6 +2578,7 @@ function depends on the target language (see language specific chapters for deta <p> When pointers are converted in a typemap, the typemap code often looks similar to this: +</p> <blockquote> <pre> @@ -2548,12 +2602,14 @@ type-tables and type information is emitted in the wrapper file, descriptor information is only generated for those datatypes that were actually used in the interface. This greatly reduces the size of the type tables and improves efficiency. +</p> <p> Occassionally, you might need to write a typemap that needs to convert pointers of other types. To handle this, a special macro substition <tt>$descriptor(type)</tt> can be used to generate the SWIG type descriptor name for any C datatype. For example: +</p> <blockquote> <pre> @@ -2579,6 +2635,7 @@ if you are converting pointers in some non-standard way or working with an unusu combination of interface files and modules, you may find that SWIG omits information for a specific type descriptor. To fix this, you may need to use the <tt>%types</tt> directive. For example: +</p> <blockquote> <pre> @@ -2598,9 +2655,11 @@ convert a typed pointer object into a C++ pointer somewhere else in their program. The only problem is that the SWIG type descriptor objects are only defined in the wrapper code and not normally accessible. +</p> <p> To correctly deal with this situation, the following technique can be used: +</p> <blockquote> <pre> @@ -2633,7 +2692,7 @@ type-checking. This code is also included in every generated wrapped file so yo probably just look at the output of SWIG to get a better sense for how types are managed. -<a name="n44"></a><H2>8.9 Typemaps and overloading</H2> +<H2><a name="Typemaps_nn44"></a>10.9 Typemaps and overloading</H2> In many target languages, SWIG fully supports C++ overloaded methods and functions. For example, @@ -2731,11 +2790,13 @@ argument types---a task that must be performed at runtime in most of SWIG's targ The generation of the dynamic dispatch function is a relatively tricky affair. Not only must input typemaps be taken into account (these typemaps can radically change the types of arguments accepted), but overloaded methods must also be sorted and checked in a very specific order to resolve potential ambiguity. A high-level -overview of this ranking process is found in the "<a href="SWIGPlus.html">SWIG and C++</a>" chapter. What isn't mentioned in that chapter +overview of this ranking process is found in the "<a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a>" chapter. What isn't mentioned in that chapter is the mechanism by which it is implemented---as a collection of typemaps. +</p> <p> To support dynamic dispatch, SWIG first defines a general purpose type hierarchy as follows: +</p> <blockquote> <pre> @@ -2781,10 +2842,12 @@ SWIG_TYPECHECK_STRING_ARRAY 1140 In this table, the precedence-level determines the order in which types are going to be checked. Low values are always checked before higher values. For example, integers are checked before floats, single values are checked before arrays, and so forth. +</p> <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: +</p> <blockquote> <pre> @@ -2862,11 +2925,12 @@ code, and assigned each type a precedence value. <p> Finally, to generate the dynamic dispatch function, SWIG uses the following algorithm: +</p> <ul> -<li>Overloaded methods are first sorted by the number of required arguments. -<li>Methods with the same number of arguments are then sorted by precedence values of argument types. -<li>Typecheck typemaps are then emitted to produce a dispatch function that checks arguments in the correct order. +<li>Overloaded methods are first sorted by the number of required arguments.</li> +<li>Methods with the same number of arguments are then sorted by precedence values of argument types.</li> +<li>Typecheck typemaps are then emitted to produce a dispatch function that checks arguments in the correct order.</li> </ul> If you haven't written any typemaps of your own, it is unnecessary to worry about the typechecking rules. @@ -2896,28 +2960,30 @@ a guide. <p> <b>Notes:</b> +</p> <ul> <li>Typecheck typemaps are not used for non-overloaded methods. Because of this, it is still always necessary to check types in any "in" typemaps. +</li> -<p> <li>The dynamic dispatch process is only meant to be a heuristic. There are many corner cases where SWIG simply can't disambiguate types to the same degree as C++. The only way to resolve this ambiguity is to use the %rename directive to rename one of the overloaded methods (effectively eliminating overloading). +</li> -<p> <li> Typechecking may be partial. For example, if working with arrays, the typecheck code might simply check the type of the first array element and use that to dispatch to the correct function. Subsequent "in" typemaps would then perform more extensive type-checking. +</li> -<p> -<Li>Make sure you read the section on overloading in the "<a href="SWIGPlus.html">SWIG and C++</a>" chapter. +<li>Make sure you read the section on overloading in the "<a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a>" chapter. +</li> </ul> -<a name="n45"></a><H2>8.10 More about <tt>%apply</tt> and <tt>%clear</tt></H2> +<H2><a name="Typemaps_nn45"></a>10.10 More about <tt>%apply</tt> and <tt>%clear</tt></H2> In order to implement certain kinds of program behavior, it is sometimes necessary to @@ -2949,13 +3015,15 @@ then all of the <tt>int *OUTPUT</tt> typemaps are copied to <tt>int *retvalue</t <p> However, there is a subtle aspect of <tt>%apply</tt> that needs more description. Namely, <tt>%apply</tt> does not overwrite a typemap rule if it is already defined for the target datatype. This behavior allows you to do two things: +</p> <ul> <li>You can specialize parts of a complex typemap rule by first defining a few typemaps and then using <tt>%apply</tt> to incorporate the remaining pieces. +</li> -<p> <li>Sets of different typemaps can be applied to the same datatype using repeated <tt>%apply</tt> directives. +</li> </ul> For example: @@ -2990,7 +3058,7 @@ example: </pre> </blockquote> -<a name="n46"></a><H2>8.11 Reducing wrapper code size</H2> +<H2><a name="Typemaps_nn46"></a>10.11 Reducing wrapper code size</H2> Since the code supplied to a typemap is inlined directly into wrapper functions, typemaps can result @@ -3066,7 +3134,7 @@ convert_float_array(PyObject *input, int size) { </pre> </blockquote> -<a name="n47"></a><H2>8.12 Passing data between typemaps</H2> +<H2><a name="Typemaps_nn47"></a>10.12 Passing data between typemaps</H2> <p> @@ -3077,12 +3145,13 @@ allocating data on the heap). In general, the variables are not intended to pass information between different types of typemaps. However, this can be done if you realize that local names have the argument number appended to them. For example, you could do this: +</p> <blockquote> <pre> %typemap(in) int *(int temp) { temp = (int) PyInt_AsLong($input); - $1 = &temp; + $1 = &temp; } %typemap(argout) int * { @@ -3100,7 +3169,7 @@ in this manner should probably be avoided. At the very least, you should make sure that the typemaps sharing information have exactly the same types and names. -<a name="n48"></a><H2>8.13 Where to go for more information?</H2> +<H2><a name="Typemaps_nn48"></a>10.13 Where to go for more information?</H2> The @@ -3114,7 +3183,7 @@ for how to define typemaps of your own. Some of the language modules support additional typemaps and further information is available in the individual chapters for each target language. -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : July 2 , 2004</address> </body> diff --git a/Doc/Manual/Varargs.html b/Doc/Manual/Varargs.html index 9ad289bfc..08fc066f9 100644 --- a/Doc/Manual/Varargs.html +++ b/Doc/Manual/Varargs.html @@ -5,18 +5,18 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>11 Variable Length Arguments</H1> +<H1><a name="Varargs"></a>13 Variable Length Arguments</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Introduction</a> -<li><a href="#n3">The Problem</a> -<li><a href="#n4">Default varargs support</a> -<li><a href="#n5">Argument replacement using %varargs</a> -<li><a href="#n6">Varargs and typemaps</a> -<li><a href="#n7">Varargs wrapping with libffi</a> -<li><a href="#n8">Wrapping of va_list</a> -<li><a href="#n9">C++ Issues</a> -<li><a href="#n10">Discussion</a> +<li><a href="#Varargs_nn2">Introduction</a> +<li><a href="#Varargs_nn3">The Problem</a> +<li><a href="#Varargs_nn4">Default varargs support</a> +<li><a href="#Varargs_nn5">Argument replacement using %varargs</a> +<li><a href="#Varargs_nn6">Varargs and typemaps</a> +<li><a href="#Varargs_nn7">Varargs wrapping with libffi</a> +<li><a href="#Varargs_nn8">Wrapping of va_list</a> +<li><a href="#Varargs_nn9">C++ Issues</a> +<li><a href="#Varargs_nn10">Discussion</a> </ul> <!-- INDEX --> @@ -25,18 +25,19 @@ <b>(a.k.a, "The horror. The horror.")</b> <p> - This chapter describes the problem of wrapping functions that take a variable number of arguments. For instance, generating wrappers for the C <tt>printf()</tt> family of functions. +</p> <p> This topic is sufficiently advanced to merit its own chapter. In fact, support for varargs is an often requested feature that was first added in SWIG-1.3.12. Most other wrapper generation tools have wisely chosen to avoid this issue. +</p> -<a name="n2"></a><H2>11.1 Introduction</H2> +<H2><a name="Varargs_nn2"></a>13.1 Introduction</H2> Some C and C++ programs may include functions that accept a variable @@ -74,6 +75,7 @@ list of pointers into which return values are placed. However, variable length arguments are also sometimes used to write functions that accept a NULL-terminated list of pointers. A good example of this would be a function like this: +</p> <blockquote> <pre> @@ -122,7 +124,7 @@ List make_list(const char *s, ...) { </pre> </blockquote> -<a name="n3"></a><H2>11.2 The Problem</H2> +<H2><a name="Varargs_nn3"></a>13.2 The Problem</H2> Generating wrappers for a variable length argument function presents a @@ -138,10 +140,12 @@ type <tt>va_list</tt>, this is something entirely different. You can't take a <tt>va_list</tt> structure and pass it in place of the variable length arguments to another varargs function. It just doesn't work. +</p> <p> The reason this doesn't work has to do with the way that function calls get compiled. For example, suppose that your program has a function call like this: +</p> <blockquote> <pre> @@ -159,6 +163,7 @@ frame followed by a call to <tt>printf()</tt>. <p> In contrast, suppose you attempted to make some kind of wrapper around <tt>printf()</tt> using code like this: +</p> <blockquote> <pre> @@ -188,6 +193,7 @@ worse, you won't know the types and sizes of arguments until run-time as well. Needless to say, there is no obvious way to make the C compiler generate code for a function call involving an unknown number of arguments of unknown types. +</p> <p> In theory, it <em>is</em> possible to write a wrapper that does the right thing. @@ -195,6 +201,7 @@ However, this involves knowing the underlying ABI for the target platform and la as well as writing special purpose code that manually constructed the call stack before making a procedure call. Unfortunately, both of these tasks require the use of inline assembly code. Clearly, that's the kind of solution you would much rather avoid. +</p> <p> With this nastiness in mind, SWIG provides a number of solutions to the varargs @@ -202,8 +209,9 @@ wrapping problem. Most of these solutions are compromises that provide limited varargs support without having to resort to assembly language. However, SWIG can also support real varargs wrapping (with stack-frame manipulation) if you are willing to get hands dirty. Keep reading. +</p> -<a name="n4"></a><H2>11.3 Default varargs support</H2> +<H2><a name="Varargs_nn4"></a>13.3 Default varargs support</H2> When variable length arguments appear in an interface, the default @@ -239,14 +247,14 @@ instance, you could make function calls like this (in Python): <blockquote> <pre> ->>> traceprintf("Hello World") ->>> traceprintf("Hello %s. Your number is %d\n" % (name, num)) +>>> traceprintf("Hello World") +>>> traceprintf("Hello %s. Your number is %d\n" % (name, num)) </pre> </blockquote> Notice how string formatting is being done in Python instead of C. -<a name="n5"></a><H2>11.4 Argument replacement using %varargs</H2> +<H2><a name="Varargs_nn5"></a>13.4 Argument replacement using %varargs</H2> Instead of dropping the variable length arguments, an alternative approach is to replace @@ -292,13 +300,15 @@ known. When replicated argument replacement is used, at least one extra argument is added to the end of the arguments when making the function call. This argument serves as a sentinel to make sure the list is properly terminated. It has the same value as that supplied to the <tt>%varargs</tt> directive. +</p> <p> Argument replacement is not as useful when working with functions that accept mixed argument types such as <tt>printf()</tt>. Providing general purpose wrappers to such functions presents special problems (covered shortly). +</p> -<a name="n6"></a><H2>11.5 Varargs and typemaps</H2> +<H2><a name="Varargs_nn6"></a>13.5 Varargs and typemaps</H2> Variable length arguments may be used in typemap specifications. For example: @@ -326,6 +336,7 @@ default behavior of SWIG is to pass the <tt>void *</tt> value as an argument to the function. Therefore, you could use the pointer to hold a valid argument value if you wanted. <p> To illustrate, here is a safer version of wrapping <tt>printf()</tt> in Python: +</p> <blockquote> <pre> @@ -369,6 +380,7 @@ The next example illustrates a more advanced kind of varargs typemap. Disclaimer: this requires special support in the target language module and is not guaranteed to work with all SWIG modules at this time. It also starts to illustrate some of the more fundamental problems with supporting varargs in more generality. +</p> <p> If a typemap is defined for any form of <tt>(...)</tt>, many SWIG @@ -380,6 +392,7 @@ However, suppose that you wanted to create a Python wrapper for the <tt>execlp()</tt> function shown earlier. To do this using a typemap instead of using <tt>%varargs</tt>, you might first write a typemap like this: +</p> <blockquote> <pre> @@ -388,7 +401,7 @@ like this: int argc; for (i = 0; i < 10; i++) args[i] = 0; argc = PyTuple_Size(varargs); - if (argc > 10) { + if (argc > 10) { PyErr_SetString(PyExc_ValueError,"Too many arguments"); return NULL; } @@ -427,15 +440,16 @@ this: int execlp(const char *path, const char *arg, ...); </pre> </blockquote> -<p> +<p> This patches everything up and creates a function that more or less works. However, don't try explaining this to your coworkers unless you know for certain that they've had several cups of coffee. If you really want to elevate your guru status and increase your job security, continue to the next section. +</p> -<a name="n7"></a><H2>11.6 Varargs wrapping with libffi</H2> +<H2><a name="Varargs_nn7"></a>13.6 Varargs wrapping with libffi</H2> All of the previous examples have relied on features of SWIG that are @@ -446,7 +460,7 @@ with a fixed number of arguments of known types. In many cases, this works perfectly fine. However, if you want more generality than this, you need to bring out some bigger guns. -<P> +<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>). @@ -454,12 +468,14 @@ 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 distribution and are not repeated here. +</p> <p> To illustrate the use of libffi, suppose that you <em>really</em> wanted to create a wrapper for <tt>execlp()</tt> that accepted <em>any</em> number of arguments. To do this, you might make a few adjustments to the previous example. For example: +</p> <blockquote> <pre> @@ -501,21 +517,21 @@ example. For example: args = (char **) arg3; /* Set up path parameter */ - types[0] = &ffi_type_pointer; - values[0] = &arg1; + types[0] = &ffi_type_pointer; + values[0] = &arg1; /* Set up first argument */ - types[1] = &ffi_type_pointer; - values[1] = &arg2; + types[1] = &ffi_type_pointer; + values[1] = &arg2; /* Set up rest of parameters */ for (i = 0; i <= vc; i++) { - types[2+i] = &ffi_type_pointer; - values[2+i] = &args[i]; + types[2+i] = &ffi_type_pointer; + values[2+i] = &args[i]; } - if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, vc+3, - &ffi_type_uint, types) == FFI_OK) { - ffi_call(&cif, (void (*)()) execlp, &result, values); + if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, vc+3, + &ffi_type_uint, types) == FFI_OK) { + ffi_call(&cif, (void (*)()) execlp, &result, values); } else { PyErr_SetString(PyExc_RuntimeError, "Whoa!!!!!"); free(types); @@ -541,6 +557,7 @@ first place?!?" Obviously, those are questions you'll have to answer for yourse <p> As a more extreme example of libffi, here is some code that attempts to wrap <tt>printf()</tt>, +</p> <blockquote> <pre> @@ -604,32 +621,32 @@ As a more extreme example of libffi, here is some code that attempts to wrap <tt args = (vtype *) arg2; /* Set up fmt parameter */ - types[0] = &ffi_type_pointer; - values[0] = &arg1; + types[0] = &ffi_type_pointer; + values[0] = &arg1; /* Set up rest of parameters */ for (i = 0; i < vc; i++) { switch(args[i].type) { case VT_INT: - types[1+i] = &ffi_type_uint; - values[1+i] = &args[i].val.ivalue; + types[1+i] = &ffi_type_uint; + values[1+i] = &args[i].val.ivalue; break; case VT_DOUBLE: - types[1+i] = &ffi_type_double; - values[1+i] = &args[i].val.dvalue; + types[1+i] = &ffi_type_double; + values[1+i] = &args[i].val.dvalue; break; case VT_POINTER: - types[1+i] = &ffi_type_pointer; - values[1+i] = &args[i].val.pvalue; + types[1+i] = &ffi_type_pointer; + values[1+i] = &args[i].val.pvalue; break; default: abort(); /* Whoa! We're seriously hosed */ break; } } - if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, vc+1, - &ffi_type_uint, types) == FFI_OK) { - ffi_call(&cif, (void (*)()) printf, &result, values); + if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, vc+1, + &ffi_type_uint, types) == FFI_OK) { + ffi_call(&cif, (void (*)()) printf, &result, values); } else { PyErr_SetString(PyExc_RuntimeError, "Whoa!!!!!"); free(types); @@ -651,10 +668,10 @@ Much to your amazement, it even seems to work if you try it: <blockquote> <pre> ->>> import example ->>> example.printf("Grade: %s %d/60 = %0.2f%%\n", "Dave", 47, 47.0*100/60) +>>> import example +>>> example.printf("Grade: %s %d/60 = %0.2f%%\n", "Dave", 47, 47.0*100/60) Grade: Dave 47/60 = 78.33% ->>> +>>> </pre> </blockquote> @@ -662,7 +679,7 @@ Of course, there are still some limitations to consider: <blockquote> <pre> ->>> example.printf("la de da de da %s", 42) +>>> example.printf("la de da de da %s", 42) Segmentation fault (core dumped) </pre> </blockquote> @@ -674,7 +691,7 @@ module, we used the special <tt>varargs</tt> variable to get these arguments. M provide an argument number for the first extra argument. This can be used to index into an array of passed arguments to get values. Please consult the chapter on each language module for more details. -<a name="n8"></a><H2>11.7 Wrapping of va_list</H2> +<H2><a name="Varargs_nn8"></a>13.7 Wrapping of va_list</H2> Closely related to variable length argument wrapping, you may encounter functions that accept a parameter @@ -694,7 +711,7 @@ of a <tt>va_list</tt> structure are closely tied to the underlying call-stack. It's not clear that exporting a <tt>va_list</tt> would have any use or that it would work at all. -<a name="n9"></a><H2>11.8 C++ Issues</H2> +<H2><a name="Varargs_nn9"></a>13.8 C++ Issues</H2> Wrapping of C++ member functions that accept a variable number of @@ -735,17 +752,19 @@ invocation might require a table lookup to obtain the proper function address (although you might be able to obtain an address by casting a bound pointer to a pointer to function as described in the C++ ARM section 18.3.4). +</p> <p> If you do decide to change the underlying action code, be aware that SWIG always places the <tt>this</tt> pointer in <tt>arg1</tt>. Other arguments are placed in <tt>arg2</tt>, <tt>arg3</tt>, and so forth. For example: +</p> <blockquote> <pre> %feature("action") Foo::bar { ... - result = arg1->bar(arg2, arg3, etc.); + result = arg1->bar(arg2, arg3, etc.); ... } </pre> @@ -755,7 +774,7 @@ Given the potential to shoot yourself in the foot, it is probably easier to reco design or to provide an alternative interface using a helper function than it is to create a fully general wrapper to a varargs C++ member function. -<a name="n10"></a><H2>11.9 Discussion</H2> +<H2><a name="Varargs_nn10"></a>13.9 Discussion</H2> This chapter has provided a number of techniques that can be used to address the problem of variable length @@ -770,6 +789,7 @@ are a number of subtle aspects of the solution to consider--mostly concerning th problem has been decomposed. First, the example is structured in a way that tries to maintain separation between wrapper-specific information and the declaration of the function itself. The idea here is that you might structure your interface like this: +</p> <blockquote> <pre> @@ -823,8 +843,9 @@ carefully read the section "A7.3.2 Function Calls" in Kernighan and Ritchie and make sure you fully understand the parameter passing conventions used for varargs. Also, be aware of the platform dependencies and reliability issues that this will introduce. Good luck. +</p> -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : March 24, 2002</address> </body> diff --git a/Doc/Manual/Warnings.html b/Doc/Manual/Warnings.html index 5ae20e8be..441f61b86 100644 --- a/Doc/Manual/Warnings.html +++ b/Doc/Manual/Warnings.html @@ -5,33 +5,33 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>12 Warning Messages</H1> +<H1><a name="Warnings"></a>14 Warning Messages</H1> <!-- INDEX --> <ul> -<li><a href="#n2">Introduction</a> -<li><a href="#n3">Warning message suppression</a> -<li><a href="#n4">Enabling additional warnings</a> -<li><a href="#n5">Issuing a warning message</a> -<li><a href="#n6">Commentary</a> -<li><a href="#n7">Warnings as errors</a> -<li><a href="#n8">Message output format</a> -<li><a href="#n9">Warning number reference</a> +<li><a href="#Warnings_nn2">Introduction</a> +<li><a href="#Warnings_nn3">Warning message suppression</a> +<li><a href="#Warnings_nn4">Enabling additional warnings</a> +<li><a href="#Warnings_nn5">Issuing a warning message</a> +<li><a href="#Warnings_nn6">Commentary</a> +<li><a href="#Warnings_nn7">Warnings as errors</a> +<li><a href="#Warnings_nn8">Message output format</a> +<li><a href="#Warnings_nn9">Warning number reference</a> <ul> -<li><a href="#n10">Deprecated features (100-199)</a> -<li><a href="#n11">Preprocessor (200-299)</a> -<li><a href="#n12">C/C++ Parser (300-399)</a> -<li><a href="#n13">Types and typemaps (400-499) </a> -<li><a href="#n14">Code generation (500-599)</a> -<li><a href="#n15">Language module specific (800-899) </a> -<li><a href="#n16">User defined (900-999)</a> +<li><a href="#Warnings_nn10">Deprecated features (100-199)</a> +<li><a href="#Warnings_nn11">Preprocessor (200-299)</a> +<li><a href="#Warnings_nn12">C/C++ Parser (300-399)</a> +<li><a href="#Warnings_nn13">Types and typemaps (400-499) </a> +<li><a href="#Warnings_nn14">Code generation (500-599)</a> +<li><a href="#Warnings_nn15">Language module specific (800-899) </a> +<li><a href="#Warnings_nn16">User defined (900-999)</a> </ul> -<li><a href="#n17">History</a> +<li><a href="#Warnings_nn17">History</a> </ul> <!-- INDEX --> -<a name="n2"></a><H2>12.1 Introduction</H2> +<H2><a name="Warnings_nn2"></a>14.1 Introduction</H2> During compilation, SWIG may generate a variety of warning messages. For example: @@ -47,7 +47,7 @@ Typically, warning messages indicate non-fatal problems with the input where the generated wrapper code will probably compile, but it may not work like you expect. -<a name="n3"></a><H2>12.2 Warning message suppression</H2> +<H2><a name="Warnings_nn3"></a>14.2 Warning message suppression</H2> All warning messages have a numeric code that is shown in the warning message itself. @@ -125,7 +125,7 @@ There is no option to suppress all SWIG warning messages. The warning messages for a reason---to tell you that something may be <em>broken</em> in your interface. Ignore the warning messages at your own peril. -<a name="n4"></a><H2>12.3 Enabling additional warnings</H2> +<H2><a name="Warnings_nn4"></a>14.3 Enabling additional warnings</H2> Some warning messages are disabled by default and are generated only @@ -143,6 +143,7 @@ When <tt>-Wall</tt> is used, all other warning filters are disabled. <p> To selectively turn on extra warning messages, you can use the directives and options in the previous section--simply add a "+" to all warning numbers. For example: +</p> <blockquote> <pre> @@ -169,7 +170,7 @@ or Note: selective enabling of warnings with <tt>%warnfilter</tt> overrides any global settings you might have made using <tt>-w</tt> or <tt>#pragma</tt>. -<a name="n5"></a><H2>12.4 Issuing a warning message</H2> +<H2><a name="Warnings_nn5"></a>14.4 Issuing a warning message</H2> Warning messages can be issued from an interface file using a number of directives. The @@ -187,6 +188,7 @@ your own warnings, make sure you don't use numbers defined in the table at the e <p> The <tt>%ignorewarn</tt> directive is the same as <tt>%ignore</tt> except that it issues a warning message whenever a matching declaration is found. For example: +</p> <blockquote> <pre> @@ -207,7 +209,7 @@ Warning messages can be associated with typemaps using the In this case, the warning message will be printed whenever the typemap is actually used. -<a name="n6"></a><H2>12.5 Commentary</H2> +<H2><a name="Warnings_nn6"></a>14.5 Commentary</H2> The ability to suppress warning messages is really only provided for @@ -221,15 +223,16 @@ Certain types of SWIG problems are errors. These usually arise due to parsing errors (bad syntax) or semantic problems for which there is no obvious recovery. There is no mechanism for suppressing error messages. +</p> -<a name="n7"></a><H2>12.6 Warnings as errors</H2> +<H2><a name="Warnings_nn7"></a>14.6 Warnings as errors</H2> Warnings can be handled as errors by using the <tt>-Werror</tt> command line option. This will cause SWIG to exit with a non successful exit code if a warning is encountered. -<a name="n8"></a><H2>12.7 Message output format</H2> +<H2><a name="Warnings_nn8"></a>14.7 Message output format</H2> The output format for both warnings and errors can be selected for @@ -246,10 +249,10 @@ $ swig -python -Fmicrosoft example.i example.i(4): Syntax error in input. </pre></blockquote> -<a name="n9"></a><H2>12.8 Warning number reference</H2> +<H2><a name="Warnings_nn9"></a>14.8 Warning number reference</H2> -<a name="n10"></a><H3>12.8.1 Deprecated features (100-199)</H3> +<H3><a name="Warnings_nn10"></a>14.8.1 Deprecated features (100-199)</H3> <ul> @@ -275,7 +278,7 @@ example.i(4): Syntax error in input. <li>120. Deprecated command line option (-c). </ul> -<a name="n11"></a><H3>12.8.2 Preprocessor (200-299)</H3> +<H3><a name="Warnings_nn11"></a>14.8.2 Preprocessor (200-299)</H3> <ul> @@ -283,7 +286,7 @@ example.i(4): Syntax error in input. <li>202. Could not evaluate 'expr'. </ul> -<a name="n12"></a><H3>12.8.3 C/C++ Parser (300-399)</H3> +<H3><a name="Warnings_nn12"></a>14.8.3 C/C++ Parser (300-399)</H3> <ul> @@ -330,7 +333,7 @@ example.i(4): Syntax error in input. <li>368. operator/= ignored. <li>369. operator%= ignored. <li>370. operator^= ignored. -<li>371. operator&= ignored. +<li>371. operator&= ignored. <li>372. operator|= ignored. <li>373. operator<< ignored. <li>374. operator>>ignored. @@ -357,7 +360,7 @@ example.i(4): Syntax error in input. <li>395. operator delete[] ignored. </ul> -<a name="n13"></a><H3>12.8.4 Types and typemaps (400-499) </H3> +<H3><a name="Warnings_nn13"></a>14.8.4 Types and typemaps (400-499) </H3> <ul> @@ -379,7 +382,7 @@ example.i(4): Syntax error in input. <li>468. No 'throw' typemap defined for exception type 'type'. </ul> -<a name="n14"></a><H3>12.8.5 Code generation (500-599)</H3> +<H3><a name="Warnings_nn14"></a>14.8.5 Code generation (500-599)</H3> <ul> @@ -390,7 +393,7 @@ example.i(4): Syntax error in input. <li>505. Variable length arguments discarded. <li>506. Can't wrap varargs with keyword arguments enabled. <li>507. Adding native function <em>name</em> not supported (ignored). -<li>508. Declaration of '<em>name</em>' shadows declaration accessible via operator->() at <em>file:line</em>. +<li>508. Declaration of '<em>name</em>' shadows declaration accessible via operator->() at <em>file:line</em>. <li>509. Overloaded <em>declaration</em> is shadowed by <em>declaration</em> at <em>file</em>:<em>line</em>. <li>510. Friend function '<em>name</em>' ignored. <li>511. Can't use keyword arguments with overloaded functions. @@ -401,7 +404,7 @@ example.i(4): Syntax error in input. <li>516. Overloaded method <em>declaration</em> ignored. Method <em>declaration</em> at <em>file</em>:<em>line</em> used. </ul> -<a name="n15"></a><H3>12.8.6 Language module specific (800-899) </H3> +<H3><a name="Warnings_nn15"></a>14.8.6 Language module specific (800-899) </H3> <ul> @@ -440,17 +443,17 @@ example.i(4): Syntax error in input. <li>842. Covariant return types not supported in C#. Proxy method will return <em>basetype</em> (C#). </ul> -<a name="n16"></a><H3>12.8.7 User defined (900-999)</H3> +<H3><a name="Warnings_nn16"></a>14.8.7 User defined (900-999)</H3> These numbers can be used by your own application. -<a name="n17"></a><H2>12.9 History</H2> +<H2><a name="Warnings_nn17"></a>14.9 History</H2> The ability to control warning messages was first added to SWIG-1.3.12. -<p><hr> +<hr> <address>SWIG 1.3 - Last Modified : June 28, 2003</address> </body> </html> diff --git a/Doc/Manual/Windows.html b/Doc/Manual/Windows.html index 303f20256..814eb5e04 100644 --- a/Doc/Manual/Windows.html +++ b/Doc/Manual/Windows.html @@ -5,35 +5,35 @@ </head> <body bgcolor="#ffffff"> -<a name="n1"></a><H1>2 Getting started on Windows </H1> +<H1><a name="Windows"></a>3 Getting started on Windows </H1> <!-- INDEX --> <ul> -<li><a href="#n2">Installation on Windows</a> +<li><a href="#Windows_nn2">Installation on Windows</a> <ul> -<li><a href="#n3">Windows Executable</a> +<li><a href="#Windows_nn3">Windows Executable</a> </ul> -<li><a href="#n4">SWIG Windows Examples</a> +<li><a href="#examples">SWIG Windows Examples</a> <ul> -<li><a href="#n5">Instructions for using the Examples with Visual Studio</a> +<li><a href="#Windows_nn5">Instructions for using the Examples with Visual Studio</a> <ul> -<li><a href="#n6">Python</a> -<li><a href="#n7">TCL</a> -<li><a href="#n8">Perl</a> -<li><a href="#n9">Java</a> -<li><a href="#n10">Ruby</a> -<li><a href="#n11">C#</a> +<li><a href="#Windows_nn6">Python</a> +<li><a href="#Windows_nn7">TCL</a> +<li><a href="#Windows_nn8">Perl</a> +<li><a href="#Windows_nn9">Java</a> +<li><a href="#Windows_nn10">Ruby</a> +<li><a href="#Windows_nn11">C#</a> </ul> -<li><a href="#n12">Instructions for using the Examples with other compilers</a> +<li><a href="#Windows_nn12">Instructions for using the Examples with other compilers</a> </ul> -<li><a href="#n13">SWIG on Cygwin and MinGW</a> +<li><a href="#Windows_nn13">SWIG on Cygwin and MinGW</a> <ul> -<li><a href="#n14">Building swig.exe on Windows</a> +<li><a href="#swig_exe">Building swig.exe on Windows</a> <ul> -<li><a href="#n15">Building swig.exe using MinGW and MSYS</a> -<li><a href="#n16">Building swig.exe using Cygwin</a> -<li><a href="#n17">Building swig.exe alternatives</a> +<li><a href="#Windows_nn15">Building swig.exe using MinGW and MSYS</a> +<li><a href="#Windows_nn16">Building swig.exe using Cygwin</a> +<li><a href="#Windows_nn17">Building swig.exe alternatives</a> </ul> -<li><a href="#n18">Running the examples on Windows using Cygwin</a> +<li><a href="#examples_cygwin">Running the examples on Windows using Cygwin</a> </ul> </ul> <!-- INDEX --> @@ -45,7 +45,7 @@ Installing SWIG and running the examples is covered as well as building the SWIG Usage within the Unix like environments MinGW and Cygwin is also detailed. -<a name="n2"></a><H2>2.1 Installation on Windows</H2> +<H2><a name="Windows_nn2"></a>3.1 Installation on Windows</H2> SWIG does not come with the usual Windows type installation program, however it is quite easy to get started. The main steps are: @@ -54,16 +54,14 @@ SWIG does not come with the usual Windows type installation program, however it <li>Set environment variables as described in the <a href="#examples">SWIG Windows Examples</a> section in order to run examples using Visual C++. </ul> -<a name="n3"></a><H3>2.1.1 Windows Executable</H3> +<H3><a name="Windows_nn3"></a>3.1.1 Windows Executable</H3> The swigwin distribution contains the SWIG Windows executable, swig.exe, which will run on 32 bit versions of Windows, ie Windows 95/98/ME/NT/2000/XP. If you want to build your own swig.exe have a look at <a href="#swig_exe">Building swig.exe on Windows</a>. -<p> -<a name="examples"></a> -<a name="n4"></a><H2>2.2 SWIG Windows Examples</H2> +<H2><a name="examples"></a>3.2 SWIG Windows Examples</H2> Using Microsoft Visual C++ is the most common approach to compiling and linking SWIG's output. @@ -77,7 +75,7 @@ Alternatively run the <a href="#examples_cygwin">examples using Cygwin</a>. More information on each of the examples is available with the examples distributed with SWIG (Examples/index.html). -<a name="n5"></a><H3>2.2.1 Instructions for using the Examples with Visual Studio</H3> +<H3><a name="Windows_nn5"></a>3.2.1 Instructions for using the Examples with Visual Studio</H3> Ensure the SWIG executable is as supplied in the SWIG root directory in order for the examples to work. @@ -92,7 +90,7 @@ They are usually set from the Control Panel and System properties, but this depe If you don't want to use environment variables then change all occurences of the environment variables in the .dsp files with hard coded values. If you are interested in how the project files are set up there is explanatory information in some of the language module's documentation. -<a name="n6"></a><H4>2.2.1.1 Python</H4> +<H4><a name="Windows_nn6"></a>3.2.1.1 Python</H4> <b><tt>PYTHON_INCLUDE</tt></b> : Set this to the directory that contains python.h<br> @@ -103,7 +101,7 @@ PYTHON_INCLUDE: d:\python21\include<br> PYTHON_LIB: d:\python21\libs\python21.lib<br> </tt> -<a name="n7"></a><H4>2.2.1.2 TCL</H4> +<H4><a name="Windows_nn7"></a>3.2.1.2 TCL</H4> <b><tt>TCL_INCLUDE</tt></b> : Set this to the directory containing tcl.h<br> @@ -114,7 +112,7 @@ TCL_INCLUDE: d:\tcl\include<br> TCL_LIB: d:\tcl\lib\tcl83.lib<br> </tt> -<a name="n8"></a><H4>2.2.1.3 Perl</H4> +<H4><a name="Windows_nn8"></a>3.2.1.3 Perl</H4> <b><tt>PERL5_INCLUDE</tt></b> : Set this to the directory containing perl.h<br> @@ -125,7 +123,7 @@ PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE<br> PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib<br> </tt> -<a name="n9"></a><H4>2.2.1.4 Java</H4> +<H4><a name="Windows_nn9"></a>3.2.1.4 Java</H4> <b><tt>JAVA_INCLUDE</tt></b> : Set this to the directory containing jni.h<br> @@ -136,7 +134,7 @@ JAVA_INCLUDE: d:\jdk1.3\include<br> JAVA_BIN: d:\jdk1.3\bin<br> </tt> -<a name="n10"></a><H4>2.2.1.5 Ruby</H4> +<H4><a name="Windows_nn10"></a>3.2.1.5 Ruby</H4> <b><tt>RUBY_INCLUDE</tt></b> : Set this to the directory containing ruby.h<br> @@ -147,25 +145,24 @@ RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32<br> RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib<br> </tt> -<a name="n11"></a><H4>2.2.1.6 C#</H4> +<H4><a name="Windows_nn11"></a>3.2.1.6 C#</H4> The C# examples do not require any environment variables to be set as a C# project file is included. Just open up the .sln solution file in Visual Studio .NET 2003 and do a Rebuild All from the Build menu. The accompanying C# and C++ project file are automatically used by the solution file. -<a name="n12"></a><H3>2.2.2 Instructions for using the Examples with other compilers</H3> +<H3><a name="Windows_nn12"></a>3.2.2 Instructions for using the Examples with other compilers</H3> 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. -<a name="n13"></a><H2>2.3 SWIG on Cygwin and MinGW</H2> +<H2><a name="Windows_nn13"></a>3.3 SWIG on Cygwin and MinGW</H2> 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. -<a name="swig_exe"></a> -<a name="n14"></a><H3>2.3.1 Building swig.exe on Windows</H3> +<H3><a name="swig_exe"></a>3.3.1 Building swig.exe on Windows</H3> If you want to replicate the build of swig.exe that comes with the download, follow the MinGW instructions below. @@ -173,7 +170,7 @@ This is not necessary to use the supplied swig.exe. This information is provided for those that want to modify the SWIG source code in a Windows environment. Normally this is not needed, so most people will want to ignore this section. -<a name="n15"></a><H4>2.3.1.1 Building swig.exe using MinGW and MSYS</H4> +<H4><a name="Windows_nn15"></a>3.3.1.1 Building swig.exe using MinGW and MSYS</H4> <ul> @@ -182,7 +179,7 @@ Normally this is not needed, so most people will want to ignore this section. </ul> -<a name="n16"></a><H4>2.3.1.2 Building swig.exe using Cygwin</H4> +<H4><a name="Windows_nn16"></a>3.3.1.2 Building swig.exe using Cygwin</H4> Note that SWIG can also be built using Cygwin. @@ -190,9 +187,8 @@ However, the SWIG will then require the Cygwin DLL when executing. Follow the Unix instructions in the README file in the SWIG root directory. Note that the Cygwin environment will also allow one to regenerate the autotool generated files which are supplied with the release distribution. 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> -<a name="n17"></a><H4>2.3.1.3 Building swig.exe alternatives</H4> +<H4><a name="Windows_nn17"></a>3.3.1.3 Building swig.exe alternatives</H4> If you don't want to install Cygwin or MinGW, use a different compiler to build @@ -200,15 +196,12 @@ SWIG. For example, all the source code files can be added to a Visual C++ projec file in order to build swig.exe from the Visual C++ IDE. -<a name="examples_cygwin"></a> -<a name="n18"></a><H3>2.3.2 Running the examples on Windows using Cygwin</H3> +<H3><a name="examples_cygwin"></a>3.3.2 Running the examples on Windows using Cygwin</H3> The examples and test-suite work as successfully on Cygwin as on any other Unix operating system. 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> - </body> </html> diff --git a/Doc/Manual/index.html b/Doc/Manual/index.html index 75cd7e6c2..8560a9199 100644 --- a/Doc/Manual/index.html +++ b/Doc/Manual/index.html @@ -1,96 +1,17 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> -<title>SWIG1.3 Documentation</title> +<title>SWIG-1.3 Documentation</title> </head> <body bgcolor="#ffffff"> -<H1>SWIG1.3 Development Documentation</h1> - -Last update : SWIG-1.3.22 (?? ??? 2004) - -<p> -<b>Authors:</b> -<ul> -<li>David Beazley (beazley@cs.uchicago.edu) -<li>William Fulton (wsf@fultondesigns.co.uk) -<li>Matthias Köppe (mkoeppe@mail.math.uni-magdeburg.de) -<li>Lyle Johnson (lyle@users.sourceforge.net) -<li>Richard Palmer (richard@magicality.org) -<li>Craig Files (cfiles@ftc.agilent.com)</li> -<li>Art Yerkes (ayerkes@users.sourceforge.net)</li> -<li>Jonah Beckford (beckford@usermail.com)</li> -</ul> - -<P> -The SWIG documentation is currently being updated to reflect new SWIG -features and enhancements. However,this update process is currently -unfinished--there is a lot of old SWIG-1.1 documentation and it's going to -take some time to update all of it. Please pardon our dust (or volunteer -to help!). - -<p> -<h3><a href="Contents.html">Detailed table of contents</a></h3> - -<p> - -<H3>SWIG Core Documentation</H3> -<ul> -<li><a href="Preface.html">Preface</a> -<li><a href="Introduction.html">Introduction</a> -<li><a href="Windows.html">Getting started on Windows</a> -<li><a href="Scripting.html">Scripting</a> -<li><a href="SWIG.html">SWIG Basics</a> (Read this!) -<li><a href="SWIGPlus.html">SWIG and C++</a> -<li><a href="Preprocessor.html">The SWIG preprocessor</a>. -<li><a href="Library.html">The SWIG Library</a> -<li><a href="Arguments.html">Argument handling</a>. -<li><a href="Typemaps.html">Typemaps</a> -<li><a href="Customization.html">Customization features</a> -<li><a href="Contract.html">Contracts</a> -<li><a href="Varargs.html">Variable length arguments</a> -<li><a href="Warnings.html">Warning messages</a> -<li><a href="Modules.html">Working with Modules</a> -</ul> - -<H3>Language Module Documentation</h3> - -<ul> -<li><a href="CSharp.html">C# support</a> -<li><a href="Chicken.html">Chicken support</a> -<li><a href="Guile.html">Guile support</a> -<li><a href="Java.html">Java support</a> -<li><a href="Ocaml.html">Ocaml support</a> -<li><a href="Perl5.html">Perl5 support</a> -<li><a href="Php.html">PHP support</a> -<li><a href="Python.html">Python support</a> -<li><a href="Ruby.html">Ruby support</a> -<li><a href="Tcl.html">Tcl support</a> -</ul> - -<H3>Developer Documentation</h3> - -<ul> -<li><a href="Extending.html">Extending SWIG</a> -</ul> - -<p> -<h3>Documentation that has not yet been updated</h3> - -This documentation has not been updated, but most of the topics -still apply to the current release. Make sure you read the -<a href="SWIG.html">SWIG Basics</a> chapter before reading -any of these chapters. Also, SWIG-1.3.10 features extensive changes to the -implementation of typemaps. Make sure you read the <a href="Typemaps.html">Typemaps</a> -chapter above if you are using this feature. - -<ul> -<li><a href="Advanced.html">Advanced topics</a> (see <a href="Modules.html">Modules</a> for updated information). -</ul> - -<h3>Documentation not yet written (volunteers needed)</h3> +<H1><a name="index"></a>SWIG-1.3 Development Documentation</h1> +The SWIG documentation is available in one of the following formats. <ul> -<li>Mzscheme module +<li>HTML documentation with one chapter per page. +Please start with either the <a href="Sections.html#Sections">Sections summary</a> or the <a href="Contents.html#Contents">Detailed table of contents</a>.</li> +<li>HTML documentation on a <a href="SWIGDocumentation.html">single HTML page</a>.</li> +<li><a href="SWIGDocumentation.pdf">PDF document</a>.</li> </ul> </body> |