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

html fixes

Browse source
This commit is contained in:
William S Fulton 2014-05-09 23:23:39 +01:00
commit 575c7a113a
2 changed files with 179 additions and 103 deletions
Download patch file Download diff file Expand all files Collapse all files

192
Doc/Manual/Javascript.html
View file

@ -6,10 +6,53 @@
</head>
<body>
<H1>SWIG and Javascript</H1>
<H1><a name="Javascript_nn1"></a>26 SWIG and Javascript</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Javascript_overview">Overview</a>
<li><a href="#Javascript_preliminaries">Preliminaries</a>
<ul>
<li><a href="#Javascript_running_swig">Running SWIG</a>
<li><a href="#Javascript_running_tests_examples">Running Tests and Examples</a>
<li><a href="#Javascript_future_work">Future work</a>
</ul>
<li><a href="#Javascript_integration">Integration</a>
<ul>
<li><a href="#Javascript_node_extensions">Creating node.js Extensions</a>
<ul>
<li><a href="#Javascript_troubleshooting">Troubleshooting</a>
</ul>
<li><a href="#Javascript_embedded_webkit">Embedded Webkit</a>
<ul>
<li><a href="#Javascript_osx">OSX</a>
<li><a href="#Javascript_gtk">GTK</a>
</ul>
<li><a href="#Javascript_applications_webkit">Creating Applications with node-webkit</a>
</ul>
<li><a href="#Javascript_nn14">Examples</a>
<ul>
<li><a href="#Javascript_simple_example">Simple</a>
<li><a href="#Javascript_class_example">Class</a>
</ul>
<li><a href="#Javascript_implementation">Implementation</a>
<ul>
<li><a href="#Javascript_source_code">Source Code</a>
<li><a href="#Javascript_code_templates">Code Templates</a>
<li><a href="#Javascript_emitter">Emitter</a>
<li><a href="#Javascript_emitter_states">Emitter states</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>This chapter describes SWIG's support of Javascript. It does not cover SWIG basics, but only information that is specific to this module.</p>
<H2>Overview</H2>
<H2><a name="Javascript_overview"></a>26.1 Overview</H2>
<p>Javascript is a prototype-based scripting language that is dynamic, weakly typed and has first-class functions. Its arguably the most popular language for web development.
Javascript has gone beyond being a browser-based scripting language and with <a href="http://nodejs.org">node.js</a>, it is also used as a backend development language.</p>
<p>Native Javascript extensions can be used for applications that embed a web-browser view or that embed a Javascript engine (such as <em>node.js</em>). Extending a general purpose web-browser is not possible as this would be a severe security issue.</p>
@ -18,9 +61,11 @@ Javascript has gone beyond being a browser-based scripting language and with <a
With <a href="https://github.com/rogerwang/node-webkit">node-webkit</a> there is a platform which uses Google's <code>Chromium</code> as Web-Browser widget and <code>node.js</code> for javascript extensions.
</p>
<H2>Preliminaries</H2>
<H2><a name="Javascript_preliminaries"></a>26.2 Preliminaries</H2>
<H3><a name="Javascript_running_swig"></a>26.2.1 Running SWIG</H3>
<H3>Running SWIG</H3>
<p>Suppose that you defined a SWIG module such as the following:</p>
<div class="code">
@ -51,13 +96,15 @@ bool example_initialize(JSGlobalContextRef context, JSObjectRef *exports)</pre>
<p>and for v8:</p>
<div class="code">
<pre>
void example_initialize(v8::Handle<v8::Object> exports)</pre>
void example_initialize(v8::Handle&lt;v8::Object&gt; exports)</pre>
</div>
<p>
<p><b>Note</b>: be aware that <code>v8</code> has a C++ API, and thus, the generated modules must be compiled as C++.</p>
<b>Note</b>: be aware that <code>v8</code> has a C++ API, and thus, the generated modules must be compiled as C++.
</p>
<H3>Running Tests and Examples</H3>
<H3><a name="Javascript_running_tests_examples"></a>26.2.2 Running Tests and Examples</H3>
<p>The configuration for tests and examples currently supports Linux and Mac only and not MinGW (Windows) yet.</p>
<p>The default interpreter is <code>node.js</code> as it is available on all platforms and convenient to use.</p>
<p>Running the examples with JavascriptCore requires <code>libjavascriptcoregtk-1.0</code> to be installed, e.g., under Ubuntu with</p>
@ -98,19 +145,24 @@ $ make check-javascript-test-suite ENGINE=jsc</pre>
- Windows 7 64bit (VS 2010)
- Node.js</pre>
</div>
<p>
<H3>Future work</H3>
<H3><a name="Javascript_future_work"></a>26.2.3 Future work</H3>
<p>The Javascript module is not yet as mature as other modules and some things are still missing. As it makes use of SWIG's Unified Typemap Library (UTL), many typemaps are inherited. We could work on that if requested:</p>
<ul>
<li><p>More typemaps: compared to other modules there are only a few typemaps implemented. For instance a lot of the <code>std_*.i</code> typemaps are missing, such as <code>std_iostream</code>, for instance.</p></li>
<li><p>Director support: this would allow to extend a C++ abstract base class in Javascript. A pragmatic intermediate step for the most important usecase would be to support Javascript callbacks as arguments.</p></li>
</ul>
<H2>Integration</H2>
<H2><a name="Javascript_integration"></a>26.3 Integration</H2>
<p>This chapter gives a short introduction how to use a native Javascript extension: as a <code>node.js</code> module, and as an extension for an embedded Webkit.</p>
<H3>Creating <code>node.js</code> Extensions</H3>
<H3><a name="Javascript_node_extensions"></a>26.3.1 Creating node.js Extensions</H3>
<p>To install <code>node.js</code> you can download an installer from their <a href="https://launchpad.net/~chris-lea/+archive/node.js">web-site</a> for OSX and Windows. For Linux you can either build the source yourself and run <code>sudo checkinstall</code> or keep to the (probably stone-age) packaged version. For Ubuntu there is a <a href="https://launchpad.net/~chris-lea/+archive/node.js/">PPA</a> available.</p>
<div class="shell">
<pre>
@ -154,7 +206,9 @@ require("./build/Release/example")</pre>
</div>
<p>A more detailed explanation is given in the <a href="#Javascript_examples">Examples</a> section.</p>
<H4>Troubleshooting</H4>
<H4><a name="Javascript_troubleshooting"></a>26.3.1.1 Troubleshooting</H4>
<ul>
<li><em>'module' object has no attribute 'script_main'</em></li>
</ul>
@ -164,10 +218,14 @@ require("./build/Release/example")</pre>
$ sudo apt-get remove gyp</pre>
</div>
<H3>Embedded Webkit</H3>
<H3><a name="Javascript_embedded_webkit"></a>26.3.2 Embedded Webkit</H3>
<p>Webkit is pre-installed on OSX and available as a library for GTK.</p>
<H4>OSX</H4>
<H4><a name="Javascript_osx"></a>26.3.2.1 OSX</H4>
<p>There is general information about programming with WebKit on <a href="https://developer.apple.com/library/mac/documentation/cocoa/conceptual/DisplayWebContent/DisplayWebContent.html">Apple Developer Documentation</a>. Details about <code>Cocoa</code> programming are not covered here.</p>
<p>An integration of a native extension 'example' would look like this:</p>
<div class="code">
@ -201,20 +259,22 @@ extern bool example_initialize(JSGlobalContextRef context);
@end</pre>
</div>
<H4>GTK</H4>
<H4><a name="Javascript_gtk"></a>26.3.2.2 GTK</H4>
<p>There is general information about programming GTK at <a href="https://developer.gnome.org/gtk2/">GTK documentation</a> and in the <a href="https://developer.gnome.org/gtk-tutorial">GTK tutorial</a>, and for Webkit there is a <a href="http://webkitgtk.org/reference/webkitgtk/stable/index.html">Webkit GTK+ API Reference</a>.</p>
<p>An integration of a native extension 'example' would look like this:</p>
<div class="code">
<pre>
#include <gtk/gtk.h>
#include <webkit/webkit.h>
#include &lt;gtk/gtk.h&gt;
#include &lt;webkit/webkit.h&gt;
extern bool example_initialize(JSGlobalContextRef context);
int main(int argc, char* argv[])
{
// Initialize GTK+
gtk_init(&argc, &argv);
gtk_init(&amp;argc, &amp;argv);
...
@ -238,8 +298,9 @@ int main(int argc, char* argv[])
}</pre>
</div>
<H3>Creating Applications with <code>node-webkit</code></H3>
<p>
<H3><a name="Javascript_applications_webkit"></a>26.3.3 Creating Applications with node-webkit</H3>
<p>To get started with <code>node-webkit</code> there is a very informative set of <a href="https://github.com/rogerwang/node-webkit/wiki">wiki pages</a>.</p>
<p>Similar to <code>node.js</code>, <code>node-webkit</code> is started from command line within a <code>node.js</code> project directory.
Native extensions are created in the very same way as for <code>node.js</code>, except that a customized <code>gyp</code> derivate has to be used: <a href="https://github.com/rogerwang/nw-gyp">nw-gyp</a>.
@ -328,10 +389,14 @@ open new windows, and many more things.
};</pre>
</div>
<H2><a name="Javascript_examples">Examples</H2>
<H2><a name="Javascript_nn14"></a>26.4 Examples</H2>
<p>Some basic examples are shown here in more detail.</p>
<H3>Simple</H3>
<H3><a name="Javascript_simple_example"></a>26.4.1 Simple</H3>
<p>The common example <code>simple</code> looks like this:</p>
<div class="code">
<pre>
@ -376,11 +441,12 @@ var f = example.Foo;
example.Foo = 3.1415926;</pre>
</div>
<p>First the module <code>example</code> is loaded from the previously built extension. Global methods and variables are available in the scope of the module.</p>
<p>
<p><b>Note</b>: ECMAScript 5, the currently implemented Javascript standard, does not have modules. <code>node.js</code> and other implementations provide this mechanism defined by the <a href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> group. For browsers this is provided by <a href="http://browserify.org">Browserify</a>, for instance.</p>
</p>
<H3>Class</H3>
<p><b>Note</b>: ECMAScript 5, the currently implemented Javascript standard, does not have modules. <code>node.js</code> and other implementations provide this mechanism defined by the <a href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> group. For browsers this is provided by <a href="http://browserify.org">Browserify</a>, for instance.</p>
<H3><a name="Javascript_class_example"></a>26.4.2 Class</H3>
<p>The common example <code>class</code> defines three classes, <code>Shape</code>, <code>Circle</code>, and <code>Square</code>:</p>
<div class="code">
<pre>
@ -455,47 +521,47 @@ new Shape();</pre>
<div class="shell">
<pre>
$ node -i
> var example = require("./build/Release/example");
&amp; var example = require("./build/Release/example");
undefined
> var Shape = example.Shape;
&amp; var Shape = example.Shape;
undefined
> var Circle = example.Circle;
&amp; var Circle = example.Circle;
undefined
> var Square = example.Square;
&amp; var Square = example.Square;
undefined
> var c = new Circle(10);
&amp; var c = new Circle(10);
undefined
> var s = new Square(10);
&amp; var s = new Square(10);
undefined
> Shape.nshapes;
&amp; Shape.nshapes;
2
> c.x = 20;
&amp; c.x = 20;
20
> c.y = 30;
&amp; c.y = 30;
30
> s.x = -10;
&amp; s.x = -10;
-10
> s.y = 5;
&amp; s.y = 5;
5
> c.area();
&amp; c.area();
314.1592653589793
> c.perimeter();
&amp; c.perimeter();
62.83185307179586
> s.area();
&amp; s.area();
100
> s.perimeter();
&amp; s.perimeter();
40
> c.move(40, 40)
&amp; c.move(40, 40)
undefined
> c.x
&amp; c.x
60
> c.y
&amp; c.y
70
> new Shape()
&amp; new Shape()
Error: Class Shape can not be instantiated
at repl:1:2
at REPLServer.self.eval (repl.js:110:21)
at Interface.<anonymous> (repl.js:239:12)
at Interface.&lt;anonymous&gt; (repl.js:239:12)
at Interface.EventEmitter.emit (events.js:95:17)
at Interface._onLine (readline.js:202:10)
at Interface._line (readline.js:531:8)
@ -505,13 +571,17 @@ at ReadStream.EventEmitter.emit (events.js:98:17)
at emitKey (readline.js:1095:12)</pre>
</div>
<p>
<p><b>Note</b>: In ECMAScript 5 there is no concept for classes. Instead each function can be used as a constructor function which is executed by the 'new' operator. Furthermore, during construction the key property <code>prototype</code> of the constructor function is used to attach a prototype instance to the created object. A prototype is essentially an object itself that is the first-class delegate of a class used whenever the access to a property of an object fails. The very same prototype instance is shared among all instances of one type. Prototypal inheritance is explained in more detail on in <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain">Inheritance and the prototype chain</a>, for instance.</p>
<b>Note</b>: In ECMAScript 5 there is no concept for classes. Instead each function can be used as a constructor function which is executed by the 'new' operator. Furthermore, during construction the key property <code>prototype</code> of the constructor function is used to attach a prototype instance to the created object. A prototype is essentially an object itself that is the first-class delegate of a class used whenever the access to a property of an object fails. The very same prototype instance is shared among all instances of one type. Prototypal inheritance is explained in more detail on in <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain">Inheritance and the prototype chain</a>, for instance.
</p>
<H2>Implementation</H2>
<H2><a name="Javascript_implementation"></a>26.5 Implementation</H2>
<p>The Javascript Module implementation has taken a very different approach compared to other language modules in order to support different Javascript interpreters.</p>
<H3>Source Code</H3>
<H3><a name="Javascript_source_code"></a>26.5.1 Source Code</H3>
<p>The Javascript module is implemented in <code>Source/Modules/javascript.cxx</code>. It dispatches the code generation to a <code>JSEmitter</code> instance, <code>V8Emitter</code> or <code>JSCEmitter</code>. Additionally there are some helpers: <code>Template</code>, for templated code generation, and <code>JSEmitterState</code>, which is used to manage state information during AST traversal. This rough map shall make it easier to find a way through this huge source file:</p>
<div class="code">
<pre>
@ -610,7 +680,9 @@ Template::Template(const String *code_) { ... }
...</pre>
</div>
<H3>Code Templates</H3>
<H3><a name="Javascript_code_templates"></a>26.5.2 Code Templates</H3>
<p>All generated code is created on the basis of code templates. The templates for <em>JavascriptCore</em> can be found in <code>Lib/javascript/jsc/javascriptcode.swg</code>, for <em>v8</em> in <code>Lib/javascript/v8/javascriptcode.swg</code>.</p>
<p>To track the originating code template for generated code you can run</p>
<div class="shell">
@ -647,7 +719,9 @@ t_register.replace("$jsparent", state.clazz(NAME_MANGLED))
</div>
<p><code>Template</code> creates a copy of that string and <code>Template::replace</code> uses Swig's <code>Replaceall</code> to replace variables in the template. <code>Template::trim</code> can be used to eliminate leading and trailing whitespaces. <code>Template::print</code> is used to write the final template string to a Swig <code>DOH</code> (based on <code>Printv</code>). All methods allow chaining.</p>
<H3>Emitter</H3>
<H3><a name="Javascript_emitter"></a>26.5.3 Emitter</H3>
<p>The Javascript module delegates code generation to a <code>JSEmitter</code> instance. The following extract shows the essential interface:</p>
<div class="code">
<pre>
@ -730,7 +804,7 @@ class JSEmitter {
*/
Template getTemplate(const String *name);
State &getState();
State &amp;getState();
...
@ -740,12 +814,12 @@ class JSEmitter {
<div class="code">
<pre>
int JAVASCRIPT::top(Node *n) {
emitter->initialize(n);
emitter-&gt;initialize(n);
Language::top(n);
emitter->dump(n);
emitter->close();
emitter-&gt;dump(n);
emitter-&gt;close();
return SWIG_OK;
}</pre>
@ -755,16 +829,18 @@ int JAVASCRIPT::top(Node *n) {
<pre>
int JAVASCRIPT::classHandler(Node *n) {
emitter->enterClass(n);
emitter-&gt;enterClass(n);
Language::classHandler(n);
emitter->exitClass(n);
emitter-&gt;exitClass(n);
return SWIG_OK;
}</pre>
</div>
<p>In <code>enterClass</code> the emitter stores state information that is necessary when processing class members. In <code>exitClass</code> the wrapper code for the whole class is generated.</p>
<H3>Emitter states</H3>
<H3><a name="Javascript_emitter_states"></a>26.5.4 Emitter states</H3>
<p>For storing information during the AST traversal the emitter provides a <code>JSEmitterState</code> with different slots to store data representing the scopes global, class, function, and variable.</p>
<div class="code">
<pre>

90
Doc/Manual/Lua.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Lua"></a>27 SWIG and Lua</H1>
<H1><a name="Lua"></a>28 SWIG and Lua</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -82,14 +82,14 @@ Lua is an extension programming language designed to support general procedural
eLua stands for Embedded Lua (can be thought of as a flavor of Lua) and offers the full implementation of the Lua programming language to the embedded world, extending it with specific features for efficient and portable software embedded development. eLua runs on smaller devices like microcontrollers and provides the full features of the regular Lua desktop version. More information on eLua can be found here: <a href="http://www.eluaproject.net">http://www.eluaproject.net</a>
</p>
<H2><a name="Lua_nn2"></a>27.1 Preliminaries</H2>
<H2><a name="Lua_nn2"></a>28.1 Preliminaries</H2>
<p>
The current SWIG implementation is designed to work with Lua 5.0.x, 5.1.x and 5.2.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. It is possible to either static link or dynamic link a Lua module into the interpreter (normally Lua static links its libraries, as dynamic linking is not available on all platforms). SWIG also has support for eLua starting from eLua 0.8. Due to substantial changes between SWIG 2.x and SWIG 3.0 and unavailability of testing platform, eLua status was downgraded to 'experimental'.
</p>
<H2><a name="Lua_nn3"></a>27.2 Running SWIG</H2>
<H2><a name="Lua_nn3"></a>28.2 Running SWIG</H2>
<p>
@ -137,7 +137,7 @@ $ swig -lua -eluac example.i
The <tt>-elua</tt> option puts all the C function wrappers and variable get/set wrappers in rotables. It also generates a metatable which will control the access to these variables from eLua. It also offers a significant amount of module size compression. On the other hand, the <tt>-eluac</tt> option puts all the wrappers in a single rotable. With this option, no matter how huge the module, it will consume no additional microcontroller SRAM (crass compression). There is a catch though: Metatables are not generated with <tt>-eluac</tt>. To access any value from eLua, one must directly call the wrapper function associated with that value.
</p>
<H3><a name="Lua_commandline"></a>27.2.1 Additional command line options</H3>
<H3><a name="Lua_commandline"></a>28.2.1 Additional command line options</H3>
<p>
@ -178,7 +178,7 @@ swig -lua -help
</tr>
</table>
<H3><a name="Lua_nn4"></a>27.2.2 Compiling and Linking and Interpreter</H3>
<H3><a name="Lua_nn4"></a>28.2.2 Compiling and Linking and Interpreter</H3>
<p>
@ -249,7 +249,7 @@ LUALIB_API int ( luaopen_mod )(lua_State *L );
More information on building and configuring eLua can be found here: <a href="http://www.eluaproject.net/doc/v0.8/en_building.html">http://www.eluaproject.net/doc/v0.8/en_building.html</a>
</p>
<H3><a name="Lua_nn5"></a>27.2.3 Compiling a dynamic module</H3>
<H3><a name="Lua_nn5"></a>28.2.3 Compiling a dynamic module</H3>
<p>
@ -317,7 +317,7 @@ Is quite obvious (Go back and consult the Lua documents on how to enable loadlib
<H3><a name="Lua_nn6"></a>27.2.4 Using your module</H3>
<H3><a name="Lua_nn6"></a>28.2.4 Using your module</H3>
<p>
@ -335,19 +335,19 @@ $ ./my_lua
&gt;
</pre></div>
<H2><a name="Lua_nn7"></a>27.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Lua_nn7"></a>28.3 A tour of basic C/C++ wrapping</H2>
<p>
By default, SWIG tries to build a very natural Lua interface to your C/C++ code. This section briefly covers the essential aspects of this wrapping.
</p>
<H3><a name="Lua_nn8"></a>27.3.1 Modules</H3>
<H3><a name="Lua_nn8"></a>28.3.1 Modules</H3>
<p>
The SWIG module directive specifies the name of the Lua module. If you specify `module example', then everything is wrapped into a Lua table 'example' containing all the functions and variables. When choosing a module name, make sure you don't use the same name as a built-in Lua command or standard module name.
</p>
<H3><a name="Lua_nn9"></a>27.3.2 Functions</H3>
<H3><a name="Lua_nn9"></a>28.3.2 Functions</H3>
<p>
@ -388,7 +388,7 @@ It is also possible to rename the module with an assignment.
24
</pre></div>
<H3><a name="Lua_nn10"></a>27.3.3 Global variables</H3>
<H3><a name="Lua_nn10"></a>28.3.3 Global variables</H3>
<p>
@ -476,7 +476,7 @@ If you have used the <tt>-eluac</tt> option for your eLua module, you will have
In general, functions of the form <tt>"variable_get()"</tt> and <tt>"variable_set()"</tt> are automatically generated by SWIG for use with <tt>-eluac</tt>.
</p>
<H3><a name="Lua_nn11"></a>27.3.4 Constants and enums</H3>
<H3><a name="Lua_nn11"></a>28.3.4 Constants and enums</H3>
<p>
@ -511,7 +511,7 @@ If you're using eLua and have used <tt>-elua</tt> or <tt>-eluac</tt> to generate
Hello World
</pre></div>
<H4><a name="Lua_nn13"></a>27.3.4.1 Constants/enums and classes/structures</H4>
<H4><a name="Lua_nn13"></a>28.3.4.1 Constants/enums and classes/structures</H4>
<p>
@ -567,7 +567,7 @@ If the <tt>-no-old-metatable-bindings</tt> option is used, then these old-style
It is worth mentioning, that <tt>example.Test.TEST1</tt> and <tt>example.Test_TEST1</tt> are different entities and changing one does not change the other.
Given the fact that these are constantes and they are not supposed to be changed, it is up to you to avoid such issues.
</p>
<H3><a name="Lua_nn12"></a>27.3.5 Pointers</H3>
<H3><a name="Lua_nn12"></a>28.3.5 Pointers</H3>
<p>
@ -605,7 +605,7 @@ Lua enforces the integrity of its userdata, so it is virtually impossible to cor
nil
</pre></div>
<H3><a name="Lua_structures"></a>27.3.6 Structures</H3>
<H3><a name="Lua_structures"></a>28.3.6 Structures</H3>
<p>
@ -709,7 +709,7 @@ For eLua with the <tt>-eluac</tt> option, structure manipulation has to be perfo
In general, functions of the form <tt>"new_struct()"</tt>, <tt>"struct_member_get()"</tt>, <tt>"struct_member_set()"</tt> and <tt>"free_struct()"</tt> are automatically generated by SWIG for each structure defined in C. (Please note: This doesn't apply for modules generated with the <tt>-elua</tt> option)
</p>
<H3><a name="Lua_nn14"></a>27.3.7 C++ classes</H3>
<H3><a name="Lua_nn14"></a>28.3.7 C++ classes</H3>
<p>
@ -784,7 +784,7 @@ Both style names are generated by default now.
However, if the <tt>-no-old-metatable-bindings</tt> option is used, then the backward compatible names are not generated in addition to ordinary ones.
</p>
<H3><a name="Lua_nn15"></a>27.3.8 C++ inheritance</H3>
<H3><a name="Lua_nn15"></a>28.3.8 C++ inheritance</H3>
<p>
@ -809,7 +809,7 @@ then the function <tt>spam()</tt> accepts a Foo pointer or a pointer to any clas
<p>
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Lua_nn16"></a>27.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Lua_nn16"></a>28.3.9 Pointers, references, values, and arrays</H3>
<p>
@ -840,7 +840,7 @@ Foo spam7();
<p>
then all three functions will return a pointer to some Foo object. Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Lua will release this memory when the return value is garbage collected). The other two are pointers which are assumed to be managed by the C code and so will not be garbage collected.
</p>
<H3><a name="Lua_nn17"></a>27.3.10 C++ overloaded functions</H3>
<H3><a name="Lua_nn17"></a>28.3.10 C++ overloaded functions</H3>
<p>
@ -926,7 +926,7 @@ Please refer to the "SWIG and C++" chapter for more information about overloadin
<p>
Dealing with the Lua coercion mechanism, the priority is roughly (integers, floats, strings, userdata). But it is better to rename the functions rather than rely upon the ordering.
</p>
<H3><a name="Lua_nn18"></a>27.3.11 C++ operators</H3>
<H3><a name="Lua_nn18"></a>28.3.11 C++ operators</H3>
<p>
@ -1058,9 +1058,9 @@ operators and pseudo-operators):</p>
<li><tt>__setitem__</tt>
<li><tt>__tostring</tt> used internally by Lua for tostring() function. __str__ is mapped to this function
</ul>
<p>No other lua metafunction is inherited. For example, __gc is not inherited and must be redefined in every class. <tt>__tostring</tt> is subject to a special handling. If absent in class and in class bases, a default one will be provided by SWIG</p>
<p>No other lua metafunction is inherited. For example, __gc is not inherited and must be redefined in every class. <tt>__tostring</tt> is subject to a special handling. If absent in class and in class bases, a default one will be provided by SWIG.
</p>
<H3><a name="Lua_nn19"></a>27.3.12 Class extension with %extend</H3>
<H3><a name="Lua_nn19"></a>28.3.12 Class extension with %extend</H3>
<p>
@ -1116,7 +1116,7 @@ true
Extend works with both C and C++ code, on classes and structs. It does not modify the underlying object in any way---the extensions only show up in the Lua interface. The only item to take note of is the code has to use the '$self' instead of 'this', and that you cannot access protected/private members of the code (as you are not officially part of the class).
</p>
<H3><a name="Lua_nn20"></a>27.3.13 Using %newobject to release memory</H3>
<H3><a name="Lua_nn20"></a>28.3.13 Using %newobject to release memory</H3>
<p> If you have a function that allocates memory like this,</p>
@ -1140,7 +1140,7 @@ char *foo();
</div>
<p> This will release the allocated memory.</p>
<H3><a name="Lua_nn21"></a>27.3.14 C++ templates</H3>
<H3><a name="Lua_nn21"></a>28.3.14 C++ templates</H3>
<p>
@ -1175,7 +1175,7 @@ In Lua:
<p>
Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. Some more complicated examples will appear later.
</p>
<H3><a name="Lua_nn22"></a>27.3.15 C++ Smart Pointers</H3>
<H3><a name="Lua_nn22"></a>28.3.15 C++ Smart Pointers</H3>
<p>
@ -1227,7 +1227,7 @@ If you ever need to access the underlying pointer returned by <tt>operator-&gt;(
&gt; f = p:__deref__() -- Returns underlying Foo *
</pre></div>
<H3><a name="Lua_nn23"></a>27.3.16 C++ Exceptions</H3>
<H3><a name="Lua_nn23"></a>28.3.16 C++ Exceptions</H3>
<p>
@ -1370,7 +1370,7 @@ and the "<a href="Customization.html#Customization_exception">Exception handling
add exception specification to functions or globally (respectively).
</p>
<H3><a name="Lua_namespaces"></a>27.3.17 Namespaces </H3>
<H3><a name="Lua_namespaces"></a>28.3.17 Namespaces </H3>
<p>
@ -1421,7 +1421,7 @@ Now, from Lua usage is as follows:
19
&gt;
</pre></div>
<H4><a name="Lua_nn27"></a>27.3.17.1 Compatibility Note </H4>
<H4><a name="Lua_nn27"></a>28.3.17.1 Compatibility Note </H4>
<p>
@ -1437,7 +1437,7 @@ If SWIG is running in a backwards compatible way, i.e. without the <tt>-no-old-m
</pre></div>
<H4><a name="Lua_nn29"></a>27.3.17.2 Names </H4>
<H4><a name="Lua_nn29"></a>28.3.17.2 Names </H4>
<p> If SWIG is launched without <tt>-no-old-metatable-bindings</tt> option, then it enters backward-compatible mode. While in this mode, it tries
@ -1481,7 +1481,7 @@ surrounding scope without any prefixing. Pretending that Test2 is a struct, not
&gt;
</pre></div>
<H4><a name="Lua_nn30"></a>27.3.17.3 Inheritance </H4>
<H4><a name="Lua_nn30"></a>28.3.17.3 Inheritance </H4>
<p> The internal organization of inheritance has changed.
@ -1522,12 +1522,12 @@ function
&gt;
</pre></div>
<H2><a name="Lua_nn24"></a>27.4 Typemaps</H2>
<H2><a name="Lua_nn24"></a>28.4 Typemaps</H2>
<p>This section explains what typemaps are and how to use them. The default wrapping behaviour of SWIG is enough in most cases. However sometimes SWIG may need a little additional assistance to know which typemap to apply to provide the best wrapping. This section will be explaining how to use typemaps to best effect</p>
<H3><a name="Lua_nn25"></a>27.4.1 What is a typemap?</H3>
<H3><a name="Lua_nn25"></a>28.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>
@ -1555,7 +1555,7 @@ Received an integer : 6
720
</pre></div>
<H3><a name="Lua_nn26"></a>27.4.2 Using typemaps</H3>
<H3><a name="Lua_nn26"></a>28.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>
@ -1608,7 +1608,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_typemap_arrays"></a>27.4.3 Typemaps and arrays</H3>
<H3><a name="Lua_typemap_arrays"></a>28.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
@ -1672,7 +1672,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_typemaps_ptr_ptr_functions"></a>27.4.4 Typemaps and pointer-pointer functions</H3>
<H3><a name="Lua_typemaps_ptr_ptr_functions"></a>28.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>
@ -1706,7 +1706,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_writing_typemaps"></a>27.5 Writing typemaps</H2>
<H2><a name="Lua_writing_typemaps"></a>28.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>
@ -1715,7 +1715,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
<p>Before proceeding, you should read the previous section on using typemaps, and look at the existing typemaps found in luatypemaps.swg and typemaps.i. These are both well documented and fairly easy to read. You should not attempt to write your own typemaps until you have read and can understand both of these files (they may well also give you an idea to base your work on).</p>
<H3><a name="Lua_typemaps_write"></a>27.5.1 Typemaps you can write</H3>
<H3><a name="Lua_typemaps_write"></a>28.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>
@ -1728,7 +1728,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
(the syntax for the typecheck is different from the typemap, see typemaps for details).</li>
</ul>
<H3><a name="Lua_nn31"></a>27.5.2 SWIG's Lua-C API</H3>
<H3><a name="Lua_nn31"></a>28.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>
@ -1777,7 +1777,7 @@ This macro, when called within the context of a SWIG wrapped function, will disp
<div class="indent">
Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.</div>
<H2><a name="Lua_nn32"></a>27.6 Customization of your Bindings</H2>
<H2><a name="Lua_nn32"></a>28.6 Customization of your Bindings</H2>
<p>
@ -1786,7 +1786,7 @@ This section covers adding of some small extra bits to your module to add the la
<H3><a name="Lua_nn33"></a>27.6.1 Writing your own custom wrappers</H3>
<H3><a name="Lua_nn33"></a>28.6.1 Writing your own custom wrappers</H3>
<p>
@ -1805,7 +1805,7 @@ int native_function(lua_State*L) // my native code
The <tt>%native</tt> directive in the above example, tells SWIG that there is a function <tt>int native_function(lua_State*L);</tt> which is to be added into the module under the name '<tt>my_func</tt>'. SWIG will not add any wrapper for this function, beyond adding it into the function table. How you write your code is entirely up to you.
</p>
<H3><a name="Lua_nn34"></a>27.6.2 Adding additional Lua code</H3>
<H3><a name="Lua_nn34"></a>28.6.2 Adding additional Lua code</H3>
<p>
@ -1843,7 +1843,7 @@ Good uses for this feature is adding of new code, or writing helper functions to
See Examples/lua/arrays for an example of this code.
</p>
<H2><a name="Lua_nn35"></a>27.7 Details on the Lua binding</H2>
<H2><a name="Lua_nn35"></a>28.7 Details on the Lua binding</H2>
<p>
@ -1854,7 +1854,7 @@ See Examples/lua/arrays for an example of this code.
</i>
</p>
<H3><a name="Lua_nn36"></a>27.7.1 Binding global data into the module.</H3>
<H3><a name="Lua_nn36"></a>28.7.1 Binding global data into the module.</H3>
<p>
@ -1914,7 +1914,7 @@ end
<p>
That way when you call '<tt>a=example.Foo</tt>', the interpreter looks at the table 'example' sees that there is no field 'Foo' and calls __index. This will in turn check in '.get' table and find the existence of 'Foo' and then return the value of the C function call 'Foo_get()'. Similarly for the code '<tt>example.Foo=10</tt>', the interpreter will check the table, then call the __newindex which will then check the '.set' table and call the C function 'Foo_set(10)'.
</p>
<H3><a name="Lua_nn37"></a>27.7.2 Userdata and Metatables</H3>
<H3><a name="Lua_nn37"></a>28.7.2 Userdata and Metatables</H3>
<p>
@ -1994,7 +1994,7 @@ Note: Both the opaque structures (like the FILE*) and normal wrapped classes/str
<p>
Note: Operator overloads are basically done in the same way, by adding functions such as '__add' &amp; '__call' to the class' metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload.
</p>
<H3><a name="Lua_nn38"></a>27.7.3 Memory management</H3>
<H3><a name="Lua_nn38"></a>28.7.3 Memory management</H3>
<p>