diff options
Diffstat (limited to 'Doc/Manual/Lua.html')
| -rw-r--r-- | Doc/Manual/Lua.html | 74 |
1 files changed, 37 insertions, 37 deletions
diff --git a/Doc/Manual/Lua.html b/Doc/Manual/Lua.html index c07fe66c8..04f96f2f3 100644 --- a/Doc/Manual/Lua.html +++ b/Doc/Manual/Lua.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Lua"></a>24 SWIG and Lua</H1> +<H1><a name="Lua"></a>25 SWIG and Lua</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -67,13 +67,13 @@ <p> Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight configuration language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ANSI C and C++). Its also a <em>really</em> tiny language, less than 6000 lines of code, which compiles to <100 kilobytes of binary code. It can be found at <a href="http://www.lua.org">http://www.lua.org</a> </p> -<H2><a name="Lua_nn2"></a>24.1 Preliminaries</H2> +<H2><a name="Lua_nn2"></a>25.1 Preliminaries</H2> <p> The current SWIG implementation is designed to work with Lua 5.0.x and Lua 5.1.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. ((Currently SWIG generated code has only been tested on Windows with MingW, though given the nature of Lua, is should not have problems on other OS's)). 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). </p> -<H2><a name="Lua_nn3"></a>24.2 Running SWIG</H2> +<H2><a name="Lua_nn3"></a>25.2 Running SWIG</H2> <p> @@ -105,7 +105,7 @@ This creates a C/C++ source file <tt>example_wrap.c</tt> or <tt>example_wrap.cxx <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 -o option. The wrappered module will export one function <tt>"int luaopen_example(lua_State* L)"</tt> which must be called to register the module with the Lua interpreter. The name "luaopen_example" depends upon the name of the module. </p> -<H3><a name="Lua_nn4"></a>24.2.1 Compiling and Linking and Interpreter</H3> +<H3><a name="Lua_nn4"></a>25.2.1 Compiling and Linking and Interpreter</H3> <p> @@ -152,7 +152,7 @@ $ gcc -c example.c -o example.o $ gcc -I/usr/include/lua -L/usr/lib/lua min.o example_wrap.o example.o -o my_lua </pre></div> -<H3><a name="Lua_nn5"></a>24.2.2 Compiling a dynamic module</H3> +<H3><a name="Lua_nn5"></a>25.2.2 Compiling a dynamic module</H3> <p> @@ -220,7 +220,7 @@ Is quite obvious (Go back and consult the Lua documents on how to enable loadlib -<H3><a name="Lua_nn6"></a>24.2.3 Using your module</H3> +<H3><a name="Lua_nn6"></a>25.2.3 Using your module</H3> <p> @@ -238,19 +238,19 @@ $ ./my_lua > </pre></div> -<H2><a name="Lua_nn7"></a>24.3 A tour of basic C/C++ wrapping</H2> +<H2><a name="Lua_nn7"></a>25.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>24.3.1 Modules</H3> +<H3><a name="Lua_nn8"></a>25.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>24.3.2 Functions</H3> +<H3><a name="Lua_nn9"></a>25.3.2 Functions</H3> <p> @@ -288,7 +288,7 @@ It is also possible to rename the module with an assignment. 24 </pre></div> -<H3><a name="Lua_nn10"></a>24.3.3 Global variables</H3> +<H3><a name="Lua_nn10"></a>25.3.3 Global variables</H3> <p> @@ -362,7 +362,7 @@ nil 3.142 </pre></div> -<H3><a name="Lua_nn11"></a>24.3.4 Constants and enums</H3> +<H3><a name="Lua_nn11"></a>25.3.4 Constants and enums</H3> <p> @@ -385,7 +385,7 @@ example.SUNDAY=0 <p> Constants are not guaranteed to remain constant in Lua. 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> -<H3><a name="Lua_nn12"></a>24.3.5 Pointers</H3> +<H3><a name="Lua_nn12"></a>25.3.5 Pointers</H3> <p> @@ -423,7 +423,7 @@ Lua enforces the integrity of its userdata, so it is virtually impossible to cor nil </pre></div> -<H3><a name="Lua_nn13"></a>24.3.6 Structures</H3> +<H3><a name="Lua_nn13"></a>25.3.6 Structures</H3> <p> @@ -509,7 +509,7 @@ Because the pointer points inside the structure, you can modify the contents and > x.a = 3 -- Modifies the same structure </pre></div> -<H3><a name="Lua_nn14"></a>24.3.7 C++ classes</H3> +<H3><a name="Lua_nn14"></a>25.3.7 C++ classes</H3> <p> @@ -570,7 +570,7 @@ It is not (currently) possible to access static members of an instance: -- does NOT work </pre></div> -<H3><a name="Lua_nn15"></a>24.3.8 C++ inheritance</H3> +<H3><a name="Lua_nn15"></a>25.3.8 C++ inheritance</H3> <p> @@ -595,7 +595,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>24.3.9 Pointers, references, values, and arrays</H3> +<H3><a name="Lua_nn16"></a>25.3.9 Pointers, references, values, and arrays</H3> <p> @@ -626,7 +626,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>24.3.10 C++ overloaded functions</H3> +<H3><a name="Lua_nn17"></a>25.3.10 C++ overloaded functions</H3> <p> @@ -712,7 +712,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>24.3.11 C++ operators</H3> +<H3><a name="Lua_nn18"></a>25.3.11 C++ operators</H3> <p> @@ -824,7 +824,7 @@ It is also possible to overload the operator<tt>[]</tt>, but currently this cann }; </pre></div> -<H3><a name="Lua_nn19"></a>24.3.12 Class extension with %extend</H3> +<H3><a name="Lua_nn19"></a>25.3.12 Class extension with %extend</H3> <p> @@ -879,7 +879,7 @@ 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>24.3.13 C++ templates</H3> +<H3><a name="Lua_nn20"></a>25.3.13 C++ templates</H3> <p> @@ -914,7 +914,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>24.3.14 C++ Smart Pointers</H3> +<H3><a name="Lua_nn21"></a>25.3.14 C++ Smart Pointers</H3> <p> @@ -966,7 +966,7 @@ If you ever need to access the underlying pointer returned by <tt>operator->( > f = p:__deref__() -- Returns underlying Foo * </pre></div> -<H3><a name="Lua_nn22"></a>24.3.15 C++ Exceptions</H3> +<H3><a name="Lua_nn22"></a>25.3.15 C++ Exceptions</H3> <p> @@ -1110,12 +1110,12 @@ add exception specification to functions or globally (respectively). </p> -<H2><a name="Lua_nn23"></a>24.4 Typemaps</H2> +<H2><a name="Lua_nn23"></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>24.4.1 What is a typemap?</H3> +<H3><a name="Lua_nn24"></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> @@ -1143,7 +1143,7 @@ Received an integer : 6 720 </pre></div> -<H3><a name="Lua_nn25"></a>24.4.2 Using typemaps</H3> +<H3><a name="Lua_nn25"></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> @@ -1196,7 +1196,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&</tt> as an input parameter (since that it obviously input).</p> -<H3><a name="Lua_nn26"></a>24.4.3 Typemaps and arrays</H3> +<H3><a name="Lua_nn26"></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 @@ -1260,7 +1260,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>24.4.4 Typemaps and pointer-pointer functions</H3> +<H3><a name="Lua_nn27"></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> @@ -1294,7 +1294,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>24.5 Writing typemaps</H2> +<H2><a name="Lua_nn28"></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> @@ -1303,7 +1303,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>24.5.1 Typemaps you can write</H3> +<H3><a name="Lua_nn29"></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> @@ -1316,7 +1316,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>24.5.2 SWIG's Lua-C API</H3> +<H3><a name="Lua_nn30"></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> @@ -1365,7 +1365,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>24.6 Customization of your Bindings</H2> +<H2><a name="Lua_nn31"></a>25.6 Customization of your Bindings</H2> <p> @@ -1374,7 +1374,7 @@ This section covers adding of some small extra bits to your module to add the la -<H3><a name="Lua_nn32"></a>24.6.1 Writing your own custom wrappers</H3> +<H3><a name="Lua_nn32"></a>25.6.1 Writing your own custom wrappers</H3> <p> @@ -1393,7 +1393,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>24.6.2 Adding additional Lua code</H3> +<H3><a name="Lua_nn33"></a>25.6.2 Adding additional Lua code</H3> <p> @@ -1431,7 +1431,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>24.7 Details on the Lua binding</H2> +<H2><a name="Lua_nn34"></a>25.7 Details on the Lua binding</H2> <p> @@ -1442,7 +1442,7 @@ See Examples/lua/arrays for an example of this code. </i> </p> -<H3><a name="Lua_nn35"></a>24.7.1 Binding global data into the module.</H3> +<H3><a name="Lua_nn35"></a>25.7.1 Binding global data into the module.</H3> <p> @@ -1502,7 +1502,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>24.7.2 Userdata and Metatables</H3> +<H3><a name="Lua_nn36"></a>25.7.2 Userdata and Metatables</H3> <p> @@ -1582,7 +1582,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' & '__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>24.7.3 Memory management</H3> +<H3><a name="Lua_nn37"></a>25.7.3 Memory management</H3> <p> |