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

Lua documentation patch on %newobject from Thomas Pollak

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@12854 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2011-12-01 20:30:21 +00:00
commit 9dda4dd3fd
1 changed files with 62 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

98
Doc/Manual/Lua.html
View file

@ -32,32 +32,33 @@
<li><a href="#Lua_nn17">C++ overloaded functions</a>
<li><a href="#Lua_nn18">C++ operators</a>
<li><a href="#Lua_nn19">Class extension with %extend</a>
<li><a href="#Lua_nn20">C++ templates</a>
<li><a href="#Lua_nn21">C++ Smart Pointers</a>
<li><a href="#Lua_nn22">C++ Exceptions</a>
<li><a href="#Lua_nn20">Using %newobject to release memory</a>
<li><a href="#Lua_nn21">C++ templates</a>
<li><a href="#Lua_nn22">C++ Smart Pointers</a>
<li><a href="#Lua_nn23">C++ Exceptions</a>
</ul>
<li><a href="#Lua_nn23">Typemaps</a>
<li><a href="#Lua_nn24">Typemaps</a>
<ul>
<li><a href="#Lua_nn24">What is a typemap?</a>
<li><a href="#Lua_nn25">Using typemaps</a>
<li><a href="#Lua_nn26">Typemaps and arrays</a>
<li><a href="#Lua_nn27">Typemaps and pointer-pointer functions</a>
<li><a href="#Lua_nn25">What is a typemap?</a>
<li><a href="#Lua_nn26">Using typemaps</a>
<li><a href="#Lua_nn27">Typemaps and arrays</a>
<li><a href="#Lua_nn28">Typemaps and pointer-pointer functions</a>
</ul>
<li><a href="#Lua_nn28">Writing typemaps</a>
<li><a href="#Lua_nn29">Writing typemaps</a>
<ul>
<li><a href="#Lua_nn29">Typemaps you can write</a>
<li><a href="#Lua_nn30">SWIG's Lua-C API</a>
<li><a href="#Lua_nn30">Typemaps you can write</a>
<li><a href="#Lua_nn31">SWIG's Lua-C API</a>
</ul>
<li><a href="#Lua_nn31">Customization of your Bindings</a>
<li><a href="#Lua_nn32">Customization of your Bindings</a>
<ul>
<li><a href="#Lua_nn32">Writing your own custom wrappers</a>
<li><a href="#Lua_nn33">Adding additional Lua code</a>
<li><a href="#Lua_nn33">Writing your own custom wrappers</a>
<li><a href="#Lua_nn34">Adding additional Lua code</a>
</ul>
<li><a href="#Lua_nn34">Details on the Lua binding</a>
<li><a href="#Lua_nn35">Details on the Lua binding</a>
<ul>
<li><a href="#Lua_nn35">Binding global data into the module.</a>
<li><a href="#Lua_nn36">Userdata and Metatables</a>
<li><a href="#Lua_nn37">Memory management</a>
<li><a href="#Lua_nn36">Binding global data into the module.</a>
<li><a href="#Lua_nn37">Userdata and Metatables</a>
<li><a href="#Lua_nn38">Memory management</a>
</ul>
</ul>
</div>
@ -1001,7 +1002,32 @@ true
<p>
Extend works with both C and C++ code, on classes and structs. It does not modify the underlying object in any way---the extensions only show up in the Lua interface. The only item to take note of is the code has to use the '$self' instead of 'this', and that you cannot access protected/private members of the code (as you are not officially part of the class).
</p>
<H3><a name="Lua_nn20"></a>25.3.13 C++ templates</H3>
<H3><a name="Lua_nn20"></a>25.3.13 Using %newobject to release memory</H3>
<p> If you have a function that allocates memory like this,</p>
<div class="code">
<pre>char *foo() {
char *result = (char *) malloc(...);
...
return result;
}
</pre>
</div>
<p> then the SWIG generated wrappers will have a memory leak--the
returned data will be copied into a string object and the old contents
ignored.</p>
<p> To fix the memory leak, use the <a href="Customization.html#Customization_ownership">%newobject directive</a>.</p>
<div class="code">
<pre>%newobject foo;
...
char *foo();
</pre>
</div>
<p> This will release the allocated memory.</p>
<H3><a name="Lua_nn21"></a>25.3.14 C++ templates</H3>
<p>
@ -1036,7 +1062,7 @@ In Lua:
<p>
Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. Some more complicated examples will appear later.
</p>
<H3><a name="Lua_nn21"></a>25.3.14 C++ Smart Pointers</H3>
<H3><a name="Lua_nn22"></a>25.3.15 C++ Smart Pointers</H3>
<p>
@ -1088,7 +1114,7 @@ If you ever need to access the underlying pointer returned by <tt>operator-&gt;(
&gt; f = p:__deref__() -- Returns underlying Foo *
</pre></div>
<H3><a name="Lua_nn22"></a>25.3.15 C++ Exceptions</H3>
<H3><a name="Lua_nn23"></a>25.3.16 C++ Exceptions</H3>
<p>
@ -1232,12 +1258,12 @@ add exception specification to functions or globally (respectively).
</p>
<H2><a name="Lua_nn23"></a>25.4 Typemaps</H2>
<H2><a name="Lua_nn24"></a>25.4 Typemaps</H2>
<p>This section explains what typemaps are and the usage of them. The default wrappering behaviour of SWIG is enough in most cases. However sometimes SWIG may need a little additional assistance to know which typemap to apply to provide the best wrappering. This section will be explaining how to use typemaps to best effect</p>
<H3><a name="Lua_nn24"></a>25.4.1 What is a typemap?</H3>
<H3><a name="Lua_nn25"></a>25.4.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 Lua to C, you might define a typemap like this:</p>
@ -1265,7 +1291,7 @@ Received an integer : 6
720
</pre></div>
<H3><a name="Lua_nn25"></a>25.4.2 Using typemaps</H3>
<H3><a name="Lua_nn26"></a>25.4.2 Using typemaps</H3>
<p>There are many ready written typemaps built into SWIG for all common types (int, float, short, long, char*, enum and more), which SWIG uses automatically, with no effort required on your part.</p>
@ -1318,7 +1344,7 @@ void swap(int *sx, int *sy);
<p>Note: C++ references must be handled exactly the same way. However SWIG will automatically wrap a <tt>const int&amp;</tt> as an input parameter (since that it obviously input).</p>
<H3><a name="Lua_nn26"></a>25.4.3 Typemaps and arrays</H3>
<H3><a name="Lua_nn27"></a>25.4.3 Typemaps and arrays</H3>
<p>Arrays present a challenge for SWIG, because like pointers SWIG does not know whether these are input or output values, nor
@ -1382,7 +1408,7 @@ and Lua tables to be 1..N, (the indexing follows the norm for the language). In
<p>Note: SWIG also can support arrays of pointers in a similar manner.</p>
<H3><a name="Lua_nn27"></a>25.4.4 Typemaps and pointer-pointer functions</H3>
<H3><a name="Lua_nn28"></a>25.4.4 Typemaps and pointer-pointer functions</H3>
<p>Several C++ libraries use a pointer-pointer functions to create its objects. These functions require a pointer to a pointer which is then filled with the pointer to the new object. Microsoft's COM and DirectX as well as many other libraries have this kind of function. An example is given below:</p>
@ -1416,7 +1442,7 @@ int Create_Math(iMath** pptr); // its creator (assume it mallocs)
ptr=nil -- the iMath* will be GC'ed as normal
</pre></div>
<H2><a name="Lua_nn28"></a>25.5 Writing typemaps</H2>
<H2><a name="Lua_nn29"></a>25.5 Writing 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 Lua C API as well as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.</p>
@ -1425,7 +1451,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
<p>Before proceeding, you should read the previous section on using typemaps, as well as read the ready written typemaps found in luatypemaps.swg and typemaps.i. These are both well documented and fairly easy to read. You should not attempt to write your own typemaps until you have read and can understand both of these files (they may well also give you a idea to base your worn on).</p>
<H3><a name="Lua_nn29"></a>25.5.1 Typemaps you can write</H3>
<H3><a name="Lua_nn30"></a>25.5.1 Typemaps you can write</H3>
<p>There are many different types of typemap that can be written, the full list can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. However the following are the most commonly used ones.</p>
@ -1438,7 +1464,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
(the syntax for the typecheck is different from the typemap, see typemaps for details).</li>
</ul>
<H3><a name="Lua_nn30"></a>25.5.2 SWIG's Lua-C API</H3>
<H3><a name="Lua_nn31"></a>25.5.2 SWIG's Lua-C API</H3>
<p>This section explains the SWIG specific Lua-C API. It does not cover the main Lua-C api, as this is well documented and not worth covering.</p>
@ -1487,7 +1513,7 @@ This macro, when called within the context of a SWIG wrappered function, will di
<div class="indent">
Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.</div>
<H2><a name="Lua_nn31"></a>25.6 Customization of your Bindings</H2>
<H2><a name="Lua_nn32"></a>25.6 Customization of your Bindings</H2>
<p>
@ -1496,7 +1522,7 @@ This section covers adding of some small extra bits to your module to add the la
<H3><a name="Lua_nn32"></a>25.6.1 Writing your own custom wrappers</H3>
<H3><a name="Lua_nn33"></a>25.6.1 Writing your own custom wrappers</H3>
<p>
@ -1515,7 +1541,7 @@ int native_function(lua_State*L) // my native code
The <tt>%native</tt> directive in the above example, tells SWIG that there is a function <tt>int native_function(lua_State*L);</tt> which is to be added into the module under the name '<tt>my_func</tt>'. SWIG will not add any wrappering for this function, beyond adding it into the function table. How you write your code is entirely up to you.
</p>
<H3><a name="Lua_nn33"></a>25.6.2 Adding additional Lua code</H3>
<H3><a name="Lua_nn34"></a>25.6.2 Adding additional Lua code</H3>
<p>
@ -1553,7 +1579,7 @@ Good uses for this feature is adding of new code, or writing helper functions to
See Examples/lua/arrays for an example of this code.
</p>
<H2><a name="Lua_nn34"></a>25.7 Details on the Lua binding</H2>
<H2><a name="Lua_nn35"></a>25.7 Details on the Lua binding</H2>
<p>
@ -1564,7 +1590,7 @@ See Examples/lua/arrays for an example of this code.
</i>
</p>
<H3><a name="Lua_nn35"></a>25.7.1 Binding global data into the module.</H3>
<H3><a name="Lua_nn36"></a>25.7.1 Binding global data into the module.</H3>
<p>
@ -1624,7 +1650,7 @@ end
<p>
That way when you call '<tt>a=example.Foo</tt>', the interpreter looks at the table 'example' sees that there is no field 'Foo' and calls __index. This will in turn check in '.get' table and find the existence of 'Foo' and then return the value of the C function call 'Foo_get()'. Similarly for the code '<tt>example.Foo=10</tt>', the interpreter will check the table, then call the __newindex which will then check the '.set' table and call the C function 'Foo_set(10)'.
</p>
<H3><a name="Lua_nn36"></a>25.7.2 Userdata and Metatables</H3>
<H3><a name="Lua_nn37"></a>25.7.2 Userdata and Metatables</H3>
<p>
@ -1704,7 +1730,7 @@ Note: Both the opaque structures (like the FILE*) and normal wrappered classes/s
<p>
Note: Operator overloads are basically done in the same way, by adding functions such as '__add' &amp; '__call' to the classes metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload.
</p>
<H3><a name="Lua_nn37"></a>25.7.3 Memory management</H3>
<H3><a name="Lua_nn38"></a>25.7.3 Memory management</H3>
<p>