diff options
Diffstat (limited to 'Doc/Manual/Lua.html')
| -rw-r--r-- | Doc/Manual/Lua.html | 92 |
1 files changed, 46 insertions, 46 deletions
diff --git a/Doc/Manual/Lua.html b/Doc/Manual/Lua.html index c67e08834..61f19be68 100644 --- a/Doc/Manual/Lua.html +++ b/Doc/Manual/Lua.html @@ -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 > </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> @@ -993,7 +993,7 @@ The current list of operators which can be overloaded (and the alternative funct <li><tt>__unm__</tt> unary minus <li><tt>__call__</tt> operator<tt>()</tt> (often used in functor classes) <li><tt>__pow__</tt> the exponential fn (no C++ equivalent, Lua uses <tt>^</tt>) -<li><tt>__concat__</tt> the concatenation operator (SWIG maps C++'s <tt>~</tt> to Lua's <tt>..</tt>) +<li><tt>__concat__</tt> the concatenation operator (Lua's <tt>..</tt>) <li><tt>__eq__</tt> operator<tt>==</tt> <li><tt>__lt__</tt> operator<tt><</tt> <li><tt>__le__</tt> operator<tt><=</tt> @@ -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->( > 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 > </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 > </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 > </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&</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' & '__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> |