diff options
Diffstat (limited to 'ThirdParty/toluapp/doc/tolua++.html')
| -rw-r--r-- | ThirdParty/toluapp/doc/tolua++.html | 1956 |
1 files changed, 1956 insertions, 0 deletions
diff --git a/ThirdParty/toluapp/doc/tolua++.html b/ThirdParty/toluapp/doc/tolua++.html new file mode 100644 index 0000000..78cb005 --- /dev/null +++ b/ThirdParty/toluapp/doc/tolua++.html @@ -0,0 +1,1956 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <META NAME="GENERATOR" CONTENT="Textpad"> + <META NAME="Author" CONTENT="Waldemar Celes, Ariel Manzur"> + <TITLE>tolua++ reference manual</TITLE> +</HEAD> +<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000"> + +<H1> +<IMG SRC="toluapp.gif">tolua++ - Reference Manual</I></H1> +by Waldemar Celes, Ariel Manzur. + +<H1> + +</h1> + +<HR ALIGN=LEFT SIZE=5 WIDTH="100%"> + +<b>tolua++</b> is an extended version of <a href="http://www.tecgraf.puc-rio.br/~celes/tolua/">tolua</a>, a tool to integrate +C/C++ code with <A HREF="http://www.tecgraf.puc-rio.br/lua">Lua</A>. <b>tolua++</b> +includes new features oriented to c++ such as: +<p> + +<ul> +<li> Support for <b>std::string</b> as a <a href="#basics">basic type</a> (this can be turned off by a command line option).</li> +<li> Support for <a href="#templates">class templates</a></li> +</ul> +<p> + +As well as other features and bugfixes. +<p> + + +<B>tolua</B> is a tool that greatly simplifies the integration of C/C++ +code with <A HREF="http://www.tecgraf.puc-rio.br/lua">Lua</A>. Based on +a <I>cleaned</I> <I>header file</I> (or extracts from real header files), +<B>tolua</B> automatically generates +the binding code to access C/C++ features from Lua. Using Lua API and tag +method facilities, <B>tolua </B>maps C/C++ constants, external variables, +functions, classes, and methods to Lua. +<P>This manual is for <B>tolua++</B> version 1.0 and is implemented upon Lua +5.0 and based on <b>tolua 5.0</b>. See <A HREF="#changes-v30">Compatibility</A> +for details on switching from older versions. +<P>The sections below describe how to use <B>tolua</B>. Please <A HREF="mailto:tolua@codenix.com">contact us</A> +with bug reports, suggestions, and comments. +<UL> +<LI> +Shortcuts:</LI> + +<UL> +<LI> +<A HREF="#introduction">How <B>tolua</B> works</A></LI> + +<LI> +<A HREF="#using">How to use <B>tolua</B></A></LI> + +<LI> +<A HREF="#basics">Basic Concepts</A></LI> + +<LI> +<A HREF="#constants">Binding constants</A></LI> + +<LI> +<A HREF="#variables">Binding external variables</A></LI> + +<LI> +<A HREF="#functions">Binding functions</A></LI> + +<LI> +<A HREF="#structs">Binding struct fields</A></LI> + +<LI> +<A HREF="#classes">Binding classes and methods</A></LI> + +<li> +<a href="#propeties">Binding properties</a></li> + +<li> +<a href="#templates">Class Templates</a></li> + +<LI> +<A HREF="#modules">Module definition</A></LI> + +<LI> +<A HREF="#renaming">Renaming constants, variables and functions</A></LI> + +<LI> +<A HREF="#additional">Storing additional fields</A></LI> + +<li> +<a href="#additional_features">Additional features</a></li> + +<LI> +<A HREF="#utilities">Exported utility functions</A></LI> + +<LI> +<A HREF="#embedded">Embedded Lua code</A></LI> + +<LI> +<a HREF="#customizing">Customizing tolua++</a></li> + +<li> +<a href="#compatibility">Compatibility with older versions</a></li> + +<li> +<A HREF="#changes-v30">Changes since v3 *</A></li> + +<LI> +<A HREF="#changes-v2">Changes since v2.*</A></LI> + +<LI> +<A HREF="#changes-v1">Changes since v1.*</A></LI> + +<LI> +<A HREF="#credits">Credits</A></LI> + +<LI> +<A HREF="#availability">Availability</A></LI> +</UL> +</UL> + +<HR WIDTH="100%"> +<H3> +<A NAME="introduction"></A>How tolua works</H3> +To use <B>tolua</B>, we create a <I>package file</I>, a C/C++ cleaned header +file<I>,</I> listing the constants, variables, functions, classes, and +methods we want to export to the Lua environment. Then <B>tolua</B> parses +this file and creates a C/C++ file that automatically binds the C/C++ code +to Lua. If we link the created file with our application, the specified +C/C++ code can be accessed from Lua.<br> +A package file can also include regular header files, other package files, +or lua files.<br> +<P>Let's start with some examples. If we specify as input the following +C-like header file to <B>tolua</B>: +<PRE>#define FALSE 0 +#define TRUE 1 + +enum { + POINT = 100, + LINE, + POLYGON +}</PRE> + +<PRE>Object* createObejct (int type); +void drawObject (Object* obj, double red, double green, double blue); +int isSelected (Object* obj);</PRE> +A C file that binds such a code to Lua is automatically generated. Therefore, +in Lua code, we can access the C code, writing, for instance: +<PRE>... +myLine = createObject(LINE) +... +if isSelected(myLine) == TRUE then + drawObject(myLine, 1.0, 0.0, 0.0); +else + drawObject(myLine, 1.0, 1.0, 1.0); +end +...</PRE> +Also, consider a C++-like header file: +<PRE>#define FALSE 0 +#define TRUE 1</PRE> + +<PRE>class Shape +{ + void draw (void); + void draw (double red, double green, double blue); + int isSelected (void); +};</PRE> + +<PRE>class Line : public Shape +{ + Line (double x1, double y1, double x2, double y2); + ~Line (void); +};</PRE> +If this file is used as input to <B>tolua</B>, a C++ file is automatically +generated proving access to such a code from Lua. Therefore, it would be +valid to write Lua statements like: +<PRE>... +myLine = Line:new (0,0,1,1) +... +if myLine:isSelected() == TRUE then + myLine:draw(1.0,0.0,0.0) +else + myLine:draw() +end +... +myLine:delete() +...</PRE> +The package file (usually with extension <TT>.pkg</TT>) passed to <B>tolua</B> +is not the real C/C++ header file, but a <I>cleaned </I>version of it. +<B>tolua</B> +does not implement a complete parse to interpret C/C++ code, but it understands +a few declarations that are used to describe the features that are to be +exported to Lua. Regular header files can be included into packages files; <b>tolua</b> +will extract the code specified by the user to parse from the header (see <a href="#basics">Basic Concepts</a>). +<H3> +<A NAME="using"></A>How to use toLua</H3> +<B>tolua </B>is composed by two pieces of code: an executable and a library. +The executable represents the parser that reads a package file and output +a C/C++ code that implements the binding to access the C/C++ features from +Lua. If the package file is a C++ like code (i.e., includes class definitions), +a C++ code is generated. If the cleaned header file is a C like code (i.e., +without classes), a C code is generated. <B>tolua</B> accepts a set of +options. Running <TT>"tolua -h"</TT> displays the current accepted options. +For instance, to parse a file called <TT>myfile.pkg +</TT>generating the +binding code in <TT>myfile.c</TT>, we do: +<P><TT>tolua -o myfile.c myfile.pkg</TT> +<P>The generated code must be compiled and linked with the application +to provide the desired access from Lua. Each parsed file represents a package +being exported to Lua. By default, the package name is the input file root +name (<TT>myfile </TT>in the example). The user can specify a different +name for the package: +<P><TT>tolua -n pkgname -o myfile.c myfile.pkg</TT> +<P>The package should also be explicitly initialized. To initialize the +package from our C/C++ code, we must declare and call the initialization +function. The initialization function is defined as +<P><TT>int tolua_<I>pkgname</I>_open (lua_State*);</TT> +<P>where <I><TT>pkgname </TT></I>represents the name of the package being +bound. If we are using C++, we can opt for automatic initialization: +<P><TT>tolua -a -n pkgname -o myfile.c myfile.pkg</TT> +<P>In that case, the initialization function is automatically called. However, +if we are planning to use multiple Lua states, automatic initialization +does not work, because the order static variables are initialized in C++ +is not defined. +<!-- +<P>The current <B>tolua</B> version also exports a closing function, which +can be called to unbind the package. +<P><TT>void tolua_<I>pkgname</I>_close (void);</TT> +--> +<P>Optionally, the prototype of the <TT>open</TT> function +can be outputted to a header file, which name is given by the <TT>-H</TT> +option. +<P>The binding code generated by <B>tolua </B>uses a set of functions defined +in the <B>tolua </B>library. Thus, this library also has to be linked with +the application. The file <TT>tolua.h</TT> is also necessary to compile +the generated code. +<P>An application can use tolua object oriented framework (see <A HREF="#utilities">exported +utility functions</A>) without binding any package. In that case, the application +must call <B>tolua </B>initialization function (this function is called +by any package file initialization function): +<P><TT>int tolua_open (void);</TT> +<!-- +<P>If multiple Lua states are to be used, after setting a Lua state, we +need to call a function to restore <B>tolua </B>internal state: +<P><TT>void tolua_restorestate (void);</TT> +--> +<H3> +<A NAME="basics"></A>Basic Concepts</H3> +The first step in using <B>tolua</B> is to create the package file. Starting +with the real header files, we clean them by declaring the features we +want to access from Lua in a format that <B>tolua</B> can understand. The +format <B>tolua</B> understands is simple C/C++ declarations as described +below. + +<H4>Including files</h4> + +A package file may include other package file. The general format +to do that is: +<p> +<TT>$pfile "<I>include_file</I>"</TT> +<p> +A package file may also include regular C/C++ header files, using the <TT>hfile</TT> +or <TT>cfile</tt> directive: +<p> + +<tt>$cfile "example.h"</tt> +<p> +In which case, <b>tolua</b> will extract the code enclosed between <tt>tolua_begin</tt> +and <tt>tolua_end</tt>, or or <tt>tolua_export</tt> for a single line. Consider this C++ header as example: + +<PRE> + +#ifndef EXAMPLE_H +#define EXAMPLE_H + +class Example { // tolua_export + +private: + + string name; + int number; + +public: + + void set_number(int number); + + //tolua_begin + + string get_name(); + int get_number(); +}; +// tolua_end + +#endif +</pre> + +<p> +In this case, the code that's not supported by <b>tolua</b> (the +private part of the class), along with the function <tt>set_number</tt> +is left outside of the package that includes this header. +<p> + +Finally, lua files can be included on a package file, using <tt>$lfile</tt>: +<p> + +<tt>$lfile "example.lua"</tt> +<p> + +<b>New on tolua++</b>: an extra way to include source files is available since +version 1.0.4 of <b>tolua++</b>, using <tt>ifile</tt>: +<p> + +<tt>$ifile "filename"</tt> +<p> + +<tt>ifile</tt> also takes extra optional parameters after the filename, for example: +<p> + +<tt> +$ifile "widget.h", GUI<br> +$ifile "vector.h", math, 3d +</tt> +<p> + +<tt>ifile</tt>'s default behaviour is to include the whole file, untouched. However, +the contents of the file and the extra parameters are put through the <tt>include_file_hook</tt> +function before being included into the package (see <a href="#customizing">Customizing tolua++</a> +for more details). +<p> + +<H4> +Basic types</H4> +<B>tolua </B>automatically maps C/C++ basic types to Lua basic types. Thus, +<TT>char</TT>, +<TT>int</TT>, +<TT>float</TT>, and <TT>double </TT>are mapped to the Lua type <TT>number</TT>;<TT> +char*</TT> is mapped to <TT>string</TT>; and<TT> void*</TT> is mapped to +<TT>userdata</TT>. Types may be preceded by modifiers (<TT>unsigned</TT>, +<TT>static</TT>, <TT>short</TT>, <TT>const</TT>, etc.); however, be aware +that <B>tolua </B>ignores the modifier <TT>const</TT> if applied to basic +types. Thus, if we pass a constant basic type to Lua and then pass it back +to C/C++ code where a non constant is expected, the constant to non constant +conversion will be silently done. +<P>Functions in C/C++ can also manipulate Lua objects explicitly. Thus +<TT>lua_Object</TT> +is also considered a basic type. In this case, any Lua value matches it. +<p> + +<b>New on tolua++</b>: The C++ type <tt>string</tt> is also considered a basic type, and is passed as +a value to lua (using the <tt>c_str()</tt> method). This feature can be turned off +with the command line option <tt>-S</tt>. + +<H4> +User defined types</H4> +All other types that appear in the package file being processed are considered +user defined types. These are mapped to tagged userdata type in Lua. Lua +can only store pointers to user defined types; although, <B>tolua +</B>automatically +makes the necessary arrangement to deal with references and values. For +instance, if a function or method returns a value of user defined type, +<B>tolua +</B>allocates +a clone object when returning it to Lua and sets the garbage collection +tag method to automatically free the allocated object when no longer in +use by Lua. +<P>For user defined types, <tt>const</tt>ness is preserved. Thus passing a non constant +user defined type to a function that expects constant type generates an +type mismatching error. +<H4> +<TT>NULL </TT>and <TT>nil</TT></H4> +C/C++ <TT>NULL</TT> or <TT>0 </TT>pointers are mapped to Lua +<TT>nil </TT>type; +conversely, <TT>nil </TT>may be specified wherever a C/C++ pointer is expected. +This is valid for any type: <TT>char*</TT>, +<TT>void*</TT>, and pointers +to user defined types. +<H4> +Typedefs</H4> +<B>tolua </B>also accepts simple typedef<I>'s </I>inside the package files. +Any occurrence of a type after its definition is mapped by <B>tolua +</B>to +the base type. They are useful because several packages redefine the basic +C/C++ types to their own types. For instance, one can define the type <TT>real +</TT>to +represent a <TT>double</TT>. In that case, <TT>real +</TT>can be used to +specify the variable types inside the package file interpreted by <B>tolua</B>, +but only if we include the following definition before any use of the type +<TT>real</TT>. +<P><TT>typedef double real;</TT> +<P>Otherwise, <TT>real </TT>would be interpreted as a user defined type +and would not be mapped to Lua numbers. +<H4> +Including real header files</H4> +In the package file, we must specify which are the real header files that +should be included so that the generated code can access the constants, +variables, functions, and classes we are binding. Any line in the package +file beginning with a <B>$ </B>(except $[hclp]file, $[ , and $] lines) is +inserted into the generated binding C/C++ code without any change, but the +elimination of the <B>$</B> itself. We use this feature to include the +real header files. So, our package files will usually start with a set +of <B>$</B> beginning lines specifying the files that must be included, +that is, the files the package file is based on. +<PRE>/* specify the files to be included */</PRE> + +<PRE>$#include "header1.h" // include first header +$#include "header2.h" // include second header</PRE> +As illustrated, <B>tolua </B>also accepts comments, using C or C++ convention, +inside the package file. Nested C-like comments can also be used. +<p> +Also note that files included with <tt>$cfile</tt> or <tt>$hfile</tt> don't +need to be included using this method, this is done automatically by <b>tolua</b>. + +<P>In the following sections, we describe how to specify the C/C++ code +we want to bind to Lua. The formats are simplified valid C/C++ statements. + +<H3> +<A NAME="constants"></A>Binding constants</H3> +To bind constants, <B>tolua </B>accepts both define's and enum's. For define's +the general format is: +<PRE><B>#define</B> <I>NAME </I>[ <I>VALUE </I>]</PRE> +The value, as showed above, is optional. If such a code is inserted inside +the file being processed, <B>tolua </B>generates a code that allows the +use of <I><TT>NAME </TT></I>as a Lua global variable that has the corresponding +C/C++ constant value. Only numeric constants are accepted. +<p> +<b>New on tolua++</b>: All other preprocessor directives are ignored. +<P>For enum's, the general format is: +<PRE><B>enum { +</B> <I><TT>NAME1 </TT></I>[ <B>=</B> <I>VALUE1 </I>] <B>, +</B> <I>NAM</I>E2 [ <B>=</B> <I>VALUE2 </I>] <B>, +</B> ... + <I>NAMEn </I>[ <B>=</B> <I>VALUEn </I>] +<B>};</B></PRE> +Similarly, <B>tolua</B> creates a set of global variables, named <I><TT>NAMEi</TT></I>, +with their corresponding values. +<H3> +<A NAME="variables"></A>Binding external variables</H3> +Global extern variables can also be exported. In the cleaned header file +they are specified as: +<PRE><TT>[</TT><B>extern</B><TT>]</TT><B> </B><I>type var</I><B>;</B></PRE> +<B>tolua</B> binds such declarations to Lua global variables. Thus, in +Lua, we can access the C/C++ variable naturally. If the variable is non +constant, we can also assign the variable a new value from Lua. Global +variables that represent arrays of value can also be bound to Lua. Arrays +can be of any type. The corresponding Lua objects for arrays are Lua tables +indexed with numeric values; however, be aware that index 1 in Lua is mapped +to index 0 in an C/C++ array. Arrays must be pre dimensioned. For instance: +<P><TT>double v[10];</TT> + +<p> +<b>New on tolua++</b>: External variables can use the <tt>tolua_readonly</tt> modifier (see <a href="#additional_features">Additional Features</a>) + +<H3> +<A NAME="functions"></A>Binding functions</H3> +Functions are also specified as conventional C/C++ declarations: +<PRE><I>type funcname </I><B>(</B><I>type1 par1</I>[<B>,</B> <I>type2 <TT>par2</TT></I>[<B>,.</B>..<I>typeN parN</I>]]<B>);</B></PRE> +The returned type can be <TT>void</TT>, meaning no value is returned. A +function can also have no parameter. In that case, <TT>void </TT>may be +specified in the place of the list of parameters. The parameter types must +follow the rules already posted. <B>tolua </B>creates a Lua function binding +the C/C++ function. When calling a function from Lua, the parameter types +must match the corresponding C/C++ types, otherwise, <B>tolua +</B>generates +an error and reports which parameter is wrongly specified. If a parameter +name is omitted, <B>tolua </B>names it automatically, but its type should +be a basic type or user type previously used. +<H4> +Arrays</H4> +<B>tolua </B>also deals with function or method parameters that represent +arrays of values. The nice thing about arrays is that the corresponding +Lua tables have their values updated if the C/C++ function changes the +array contents. +<P>The arrays must be pre dimensioned. For instance: +<P><TT>void func (double a[3]);</TT> +<P>is a valid function declaration for <B>tolua</B> and calling this function +from Lua would be done by, for instance: +<P><TT>p = {1.0,1.5,8.6}</TT> +<BR><TT>func (p)</TT> +<P>The array dimension need not be a constant expression; the dimension +can also be specified by any expression that can be evaluated in run time. +For instance: +<P><TT>void func (int n, int m, double image[n*m]);</TT> +<P>is also valid since the expression <TT>n*m</TT> is valid in the binding +function scope. However, be aware that <B>tolua </B>uses dynamic allocation +for binding this function, what can degrade the performance. +<P>Despite the dimension specification, it is important to know that all +arrays passed to the actual C/C++ function are in the local scope of the +binding function. So, if the C/C++ function being called needs to hold +the array pointer for later use, the binding code will <I>not </I>work +properly. +<H4> +Overloaded functions</H4> +Overloaded functions are accepted. Remember that the distinction between +two functions with the same name is made based on the parameter types that +are mapped to Lua. So, although +<P><TT>void func (int a);</TT> +<BR><TT>void func (double a);</TT> +<P>represent two different functions in C++, they are the same function +for <B>tolua</B>, because both <TT>int </TT>and <TT>double </TT>are mapped +to the same Lua type: <TT>number</TT>. +<P>Another tricky situation occurs when expecting pointers. Suppose: +<PRE>void func (char* s); +void func (void* p); +void func (Object1* ptr); +void func (Object2* prt);</PRE> +Although these four functions represent different functions in C++, a Lua +statement like: +<PRE>func(nil)</PRE> +matches all of them. +<P>It is important to know that <B>tolua </B>decides which function will +be called in run-time, trying to match each provided function. <B>tolua +</B>first +tries to call the last specified function; if it fails, <B>tolua +</B>then +tries the previous one. This process is repeated until one function matches +the calling code or the first function is reached. For that reason, the +mismatching error message, when it occurs, is based on the first function +specification. When performance is important, we can specify the most used +function as the last one, because it will be tried first. +<P><B>tolua</B> allows the use of overloaded functions in C, see <A HREF="#renaming">Renaming +</A>for +details. +<H4> +Default parameter values</H4> +The last function parameters can have associated default values. In that +case, if the function is called with fewer parameters, the default values +are assumed. The format to specify the default values is the same as the +one used in C++ code: +<P><TT><I>type funcname </I><B>(</B><I>...</I><B>,</B><I> typeN-1 parN-1 +[= valueN-1]<B>,</B> typeN parN [= valueN]</I><B>);</B></TT> +<P><B>toLua </B>implements this feature without using any C++ mechanism; +so, it can be used also to bind C functions. +<P>We can also specify default values for the elements of an array (there +is no way to specify a default value for the array itself, though). For +instance: +<P><TT>void func (int a[5]=0);</TT> +<P>sets the default element values to zero, thus the function can be called +from Lua with an uninitialized table. +<P>For Lua object types (<TT>lua_Object</TT>), <B>tolua </B>defines a constant +that can be used to specify <TT>nil </TT>as default value: +<P><TT>void func (lua_Object lo = TOLUA_NIL);</TT> +<p> + +<b>New on tolua++</b>: C++ class constructors are valid +as default parameters. For example: +<p> +<tt>void set_color(const Color& color = Color(0,0,0));</tt> +<p> + +<H4> +Multiple returned values</H4> +In Lua, a function may return any number of values. <B>tolua </B>uses this +feature to simulate values passed by reference. If a function parameter +is specified as a pointer to or reference of a basic type or a pointer +to or reference of a pointer to an user defined type, <B>tolua </B>accepts +the corresponding type as input and returns, besides the conventional function +returned value, if any, the updated parameter value. +<P>For instance, consider a C function that swaps two values: +<P><TT>void swap (double* x, double* y);</TT> +<P>or +<P><TT>void swap (double& x, double& y);</TT> +<P>If such a function is declared in the package file, <B>tolua </B>binds +it as a function receiving two numbers as input and returning two numbers. +So, a valid Lua code would be: +<P><TT>x,y = swap(x,y)</TT> +<P>If the input values are not used, the use of default parameter value +allows calling the function from Lua without specifying them: +<P><TT>void getBox (double* xmin=0, double* xmax=0, double* ymin=0, double* +ymax=0);</TT> +<P>In Lua: +<P><TT>xmin, xmax, ymin, ymax = getBox()</TT> +<P>With user defined types, we would have for instance: +<P><TT>void update (Point** p);</TT> +<P>or +<P><TT>void update (Point*& p);</TT> +<H3> +<A NAME="structs"></A>Binding struct fields</H3> +User defined types are nicely bound by <B>tolua</B>. For each variable +or function type that does not correspond to a basic type, <B>tolua </B>automatically +creates a tagged userdata to represent the C/C++ type. If the type corresponds +to a struct, the struct fields can be directly accessed from Lua, indexing +a variable that holds an object of such a type. In C code, these types +are commonly defined using typedef's: +<PRE><B>typedef struct [name]</B><I> </I><B>{ +</B> <I>type1 fieldname1</I><B>; +</B> <I>type2 fieldname2</I><B>; +</B> ... + <I>typeN fieldnameN</I><B>; +} </B><I>typename</I><B>;</B></PRE> +If such a code is inserted in the package file being processed, <B>tolua +</B>allows +any variable that holds an object of type <I><TT>typename </TT></I>to access +any listed field indexing the variable by the field name. For instance, +if <TT>var </TT>holds a such object, <I><TT>var.fieldnamei</TT></I> accesses +the field named <I><TT>fieldnamei</TT></I>. +<P>Fields that represent arrays of values can also be mapped: +<P><TT>typedef struct {</TT> +<BR><TT> int x[10];</TT> +<BR><TT> int y[10];</TT> +<BR><TT>} Example;</TT> +<BR> +<H3> +<A NAME="classes"></A>Binding classes and methods</H3> +C++ class definitions are also supported by <B>tolua</B>. Actually, the +<B>tolua +</B>deals +with single inheritance and polymorphism in a natural way. The subsections +below describe what can be exported by a class definition. +<H4> +Specifying inheritance</H4> +If <TT>var </TT>is a Lua variable that holds an object of a derived class, +<TT>var +</TT>can +be used wherever its base class type is expected and <TT>var +</TT>can access +any method of its base class. For this mechanism to take effect, we must +indicate that the derived class actually inherits the base class. This +is done in the conventional way: +<PRE><B>class </B><I>classname </I><B>: public</B> <I>basename +</I><B>{</B></PRE> + +<PRE> /* class definition */</PRE> + +<PRE><B>};</B></PRE> +<p> + +In this case, the definition of <tt>basename</tt> needs to appear before <tt>classname</tt> +if the inheritance properties are to be taken advantage of from lua. + +<h4>Multiple inheritance</h4> + +<b>tolua++</b> (starting from version 1.0.4) supports multiple inheritance by allowing you +to access the extra parents 'manually'. +<p> +For example, consider the following class: +<p> + +<PRE> +class Slider : public Widget, public Range { + ... +}; +</PRE> +<p> + +An object of type 'Slider' will fully retain its inheritance with Widget, +and will contain a 'member' of type Range, which will return the object +cast to the correct base type. +<p> + +For example: +<p> + +<PRE> +slider = Slider:new() +slider:show() -- a Widget method + +slider:set_range(0, 100) -- this won't work, because + -- set_range is a method from Range + +slider.__Range__:set_range(0, 100) -- this is the correct way +</PRE> + +<p> + +This is an experimental feature. +<p> + +<H4> +Specifying exported members and methods</H4> +As for struct fields, class fields, static or not, can be exported. Class +methods and class static methods can also be exported. Of course, they +must be declared as public in the actual C++ code (the +<TT>public:</TT>keyword may appear in the package files, it will be ignored by <b>tolua</b>). +<P>For each bound class, <B>tolua </B>creates a Lua table and stores it +at a variable which name is the name of the C++ class. This tables may contain other +tables that represent other tables, the way C++ classes may contain other classes and structs. +Static exported +fields are accessed by indexing this table with the field names (similar +to struct fields). Static methods are also called using this table, with a colon. +Non static exported fields are accessed by indexing +the variable that holds the object. Class methods follow the format of +the function declaration showed above. They can be accessed from Lua code +using the conventional way Lua uses to call methods, applied of course +to a variable that holds the appropriate object or to the class table, +for static methods. +<P>There are a few special methods that are also supported by <B>tolua</B>. +Constructors are called as static methods, named <TT>new</TT>, <tt>new_local</tt> (on <b>tolua++</b>), +or calling the class name directly (also on <b>tolua++</b>, see below for the difference betwheen these methods). Destructors +are called as a conventional method called <TT>delete</TT>. +<P>Note that <B>tolua </B>does support overload. This applies even for +constructors. Also note that the <TT>virtual </TT>keyword has no effect +in the package file. +<P>The following code exemplifies class definitions that can be interpreted +by <B>tolua</B>. +<PRE>class Point { + static int n; // represents the total number of created Points + static int get_n(); // static method + + double x; // represents the x coordinate + double y; // represents the y coordinate</PRE> + +<PRE> static char* className (void); // returns the name of the class</PRE> + +<PRE> Point (void); // constructor 1 + Point (double px, double py); // constructor 2 + ~Point (void); // destructor</PRE> + +<PRE> Point add (Point& other); // add points, returning another one +};</PRE> + +<PRE>class ColorPoint : public Color { + int red; // red color component [0 - 255] + int green; // green color component [0 - 255] + int blue; // blue color component [0 - 255]</PRE> + +<PRE> ColorPoint (double px, double py, int r, int g, int b); +};</PRE> +If this segment of code is processed by <B>tolua</B>, we would be able +to write the following Lua statements: +<PRE>p1 = Point:new(0.0,1.0) +p2 = ColorPoint:new(1.5,2.2,0,0,255) +print(Point.n) -- would print 2 +print(Point:get_n()) -- would also print 2 +p3 = p1:add(p2) +local p4 = ColorPoint() +print(p3.x,p3.y) -- would print 1.5 and 3.2 +print(p2.red,p2.green,p2.blue) -- would print 0, 0, and 255 +p1:delete() -- call destructor +p2:delete() -- call destructor</PRE> + +Note that we can only explicitly delete objects that we explicitly create. +In the example above, the point <TT>p3</TT> will be garbage-collected by +<B>tolua +</B>automatically; +we cannot delete it. +<p> +<b>New on tolua++</b>: Also note that <tt>p4</tt> is created by calling the class name directly (<tt>ColorPoint()</tt>); this has the same effect as calling <tt>new_local</tt>, which +leaves the object to be deleted by the garbaje collector, and it should not be +deleted using <tt>delete</tt>. For each constructor on the pkg, one <tt>new</tt>, +<tt>new_local</tt> and <tt>.call</tt> callback for the class is created. +<P>Of course, we need to specify only the methods and members we want to +access from Lua. Sometimes, it will be necessary to declare a class with +no member or method just for the sake of not breaking a chain of inheritances. + +<h4>Using Regular functions as class methods</h4> +<p> + +<b>tolua++</b> (starting from version 1.0.5) uses the keyword <b>tolua_outside</b> to specify regular functions +as methods and static methods of a class or struct. For example: + +<PRE><tt> +/////////////// position.h: + +typedef struct { + + int x; + int y; +} Position; + +Position* position_create(); +void position_set(Position* pos, int x, int y); + +/////////////// position.pkg: + +struct Position { + + int x; + int y; + + static tolua_outside Position* position_create @ create(); + tolua_outside void position_set @ set(int x, int y); +}; + +--------------- position.lua + +local pos = Position:create() + +pos:set(10, 10) + +</tt></pre> + +Note that the <b>position_set</b> method takes a pointer to <b>Position</b> as its first parameter, +this is ommited on the <b>tolua_outside</b> declaration. Also note that we cannot name our methods +<b>new</b> or <b>new_local</b>, or as overloaded operators (see next section), this will result in +undefined behaviour. + + +<H4> +Overloaded operators</H4> +<B>tolua </B>automatically binds the following binary operators: +<UL> +<PRE>operator+ operator- operator* operator/ +operator< operator>= operator== operator[]</PRE> +</UL> +For the relational operators, <B>toLua </B>also automatically converts +a returned <TT>0</TT> value into <TT>nil</TT>, so <I>false </I>in C becomes +<I>false +</I>in +Lua. +<P>As an example, suppose that in the code above, instead of having: +<PRE> Point add (Point& other); // add points, returning another one</PRE> +we had: +<PRE> Point operator+ (Point& other); // add points, returning another one</PRE> +In that case, in Lua, we could simply write: +<PRE>p3 = p1 + p2</PRE> +The indexing operator (<TT>operator[]</TT>) when receiving a numeric parameter +can also be exported to Lua. In this case, <B>tolua </B>accepts reference +as returned value, even for basic types. Then if a reference is returned, +from Lua, the programmer can either get or set the value. If the returned +value is not a reference, the programmer can only get the value. An example +may clarify: suppose we have a vector class and bind the following operator: +<PRE> double& operator[] (int index);</PRE> +In this case, in Lua, we would be able to write: <TT>value = myVector[i]</TT> +and also <TT>myVector[i] = value</TT>, which updates the C++ object. However, +if the bound operator was: +<PRE> double operator[] (int index);</PRE> +we would only be able to write: <TT>value = myVector[i]</TT>. +<P>Free functions (i.e., not class members) that overload operators are +not supported. + +<p> + +<H4> +Cast operators</H4> + +<b>New on tolua++</b> (versions 1.0.90 and up): casting operators are also supported. +For example: + +<pre> +/////////////// node.h + +// a class that holds a value that can be of type int, double, string or Object* +class Node { // tolua_export + +private: + union { + int int_value; + double double_value; + string string_value; + Object* object_value; + }; + +// tolua_begin +public: + + enum Type { + T_INT, + T_DOUBLE, + T_STRING, + T_OBJECT, + T_MAX, + }; + + Type get_type(); + + operator int(); + operator double(); + operator string(); + operator Object*(); +}; +// tolua_end +</pre> + +<b>tolua++</b> will produce code that calls the operators by casting the object Node (using C++ <tt>static_cast</tt>), +and register them inside the class as ".typename". For example: + +<pre> +-- node.lua + +local node = list.get_node("some_node") -- returns a Node object + +if node.get_type() == Node.T_STRING then + + print("node is "..node[".string"]()) + +elseif node.get_type() == Node.T_OBJECT then + + local object = node[".Object*"]() + object:method() +end + +</pre> + +<h3><a name="properties"></a>Binding Properties</h3> + +<b>tolua++</b> (starting from version 1.0.6) supports declaration of class propeties, +using the <tt>tolua_property</tt> keyword. A +property will look like a 'field' of the class, but it's value will be retrieved +using class methods. For example: + +<pre> +/////////////// label.h + +class Label { + +public: + + string get_name(); + void set_name(string p_name); + + Widget* get_parent(); +}; + +/////////////// label.pkg +class Label { + + tolua_property string name; + + tolua_readonly tolua_property Widget* parent; +}; + +--------------- label.lua + +local label = Label() + +label.name = "hello" +print(label.name) + +label.parent:show() + +</pre> + +<h4>Property types</h4> +<p> + +A property can have differt types, which determine how it's value will be set and retrieved. +<b>tolua++</b> comes with 3 different built-in types: +<p> + +<li> <tt>default</tt> will use 'get_name' and 'set_name' methods to access a property called 'name' +<li> <tt>qt</tt> will use 'name' and 'setName' +<li> <tt>overload</tt> will use 'name' and 'name' (as in 'string name(void);' to get and 'void name(string);' to set) +<p> + +The property type can be appended at the end of the 'tolua_property' keyword on the declaration: + +<ul><tt>tolua_property__qt string name;</tt></ul> + +When no type is specified, <tt>default</tt> will be used, but this can be changed (see below). +<p> + +<h4>Changing the default property type</h4> +<p> + +The default property type can be changed using the 'TOLUA_PROPERTY_TYPE' macro. This will change the +default type from the point of its invocation, until the end of the block that contains it. For example: +<p> + +<pre> + +TOLUA_PROPERTY_TYPE(default); // default type for the 'global' scope + +namespace GUI { + + class Point { + + tolua_property int x; // will use get_x/set_x + tolua_property int y; // will use get_y/set_y + }; + + TOLUA_PROPERTY_TYPE(qt); // changes default type to 'qt' for the rest of the 'GUI' namespace + + class Label { + + tolua_property string name; // will use name/setName + }; +}; + +class Sprite { + + tolua_property GUI::Point position; // will use get_position/set_position + + tolua_property__overload string name; // will use name/name +}; + +</pre> + +<h4>Adding custom property types</h4> +<p> + +Custom property types can be added by redefining the function "get_property_methods_hook" +(see <a href="#customizing">Customizing tolua++</a> for more details). The functions takes +the property type and the name, and returns the setter and getter function names. For example: +<p> + +<pre> + +/////////////// custom.lua + +function get_property_methods_hook(ptype, name) + + if ptype == "hungarian_string" then + + return "sGet"..name, "Set"..name + end + + if ptype == "hungarian_int" then + + return "iGet"..name, "Set"..name + end + -- etc +end + +/////////////// label.pkg +class Label { + + tolua_property__hungarian_string string Name; // uses 'sGetName' and 'SetName' + + tolua_property__hungarian_int string Type; // uses 'iGetType' and 'SetType' +}; + +</pre> + +<h3><a name="templates"></a>Class Templates</h3> + +One of the additional features of <b>tolua++</b> is the support for class templates, +by using the <tt>TOLUA_TEMPLATE_BIND</tt> directive. For example: + +<pre> +class vector { + + TOLUA_TEMPLATE_BIND(T, int, string, Vector3D, double) + + void clear(); + int size() const; + + const T& operator[](int index) const; + T& operator[](int index); + void push_back(T val); + + vector(); + ~vector(); +}; +</pre> + +The <tt>TOLUA_TEMPLATE_BIND</tt> directive has to be the first thing on the class declaration, otherwise it will be ignored. +This code will create 4 versions of the class <tt>vector</tt>, one for each type +specified on the <tt>TOLUA_TEMPLATE_BIND</tt> parameters, each replacing the macro <tt>T</tt> +(specified as the first argument of <tt>TOLUA_TEMPLATE_BIND</tt>). +Thus, the functions <tt>operator[]</tt>, <tt>&operator[]</tt> and <tt>push_back</tt> +will have different signatures on each version of the object. The objects will be +recognized as <tt>vector<type></tt> on further declarations, and the name of +the table on Lua will be <tt>vector_type_</tt>. Thus, the following Lua code could be used: + +<pre> +string_vector = vector_string_:new_local() +string_vector:push_back("hello") +string_vector:push_back("world") +print(string_vector[0].." "..string_vector[1]) +</pre> + +Similarily, a template with more than 1 macro could be bound, and it could also +inherit from another template: + +<pre> +class hash_map : public map<K,V> { + + TOLUA_TEMPLATE_BIND(K V, int string, string vector<double>) + + V get_element(K key); + void set_element(K key, V value); + + hash_map(); + ~hash_map(); +}; +</tt></pre> + +In this example, one of the objects has another template as one of its types, so +it will be recognized as <tt>hash_map<string,vector<double> ></tt> while +its constructor will be on the Lua table hash_map_string_vector_double___ (see +<a href="#type_renaming">Type Renaming</a> for a better way to access these objects). +<p> + +Note that due to the complexity in the definition of some templates, you should be +careful on how you declare them. For example, if you create an object with type +<tt>hash_map<string,vector<double> ></tt> and then declare a variable +with type <tt>hash_map<string, vector<double> ></tt> (note the space +between string and vector), the type of the variable will not be recognized. The +safest way is to declare a typedef, and use that to use each type (this is also a +common practice on C++ programming). For example, using the previous declaration of +<tt>vector</tt>: +<p> + +<pre> +typedef vector<int> VectorInt; + +VectorInt variable; +</pre> + +<tt>TOLUA_TEMPLATE_BIND</tt> can be used with more than one parenthesis to open and close, +in order to be valid as a macro inside a regular .h file. The <tt>TOLUA_TEMPLATE_BIND</tt> +macro is declared on <tt>tolua.h</tt> as: +<p> +<tt>#define TOLUA_TEMPLATE_BIND(x)</tt> +<p> + +Also, the parameters can have double quotes. Thus, the following uses are valid: +<p> + +<pre> +TOLUA_TEMPLATE_BIND((T, int, float)) // to be used inside a real header file +TOLUA_TEMPLATE_BIND("K V", "string string", int double) +</pre> + +Function templates are not supported on this version. + +<H3> +<A NAME="modules"></A>Module definition</H3> +<B>tolua </B>allows us to group constants, variables, and functions in +a module. The module itself is mapped to a table in Lua, and its constants, +variables, and functions are mapped to fields in that table. The general +format to specify a module is: +<P><TT><B>module</B> name</TT> +<BR><B><TT>{</TT></B> +<BR><TT> ... // constant, variable, and function +declarations</TT> +<BR><B><TT>}</TT></B> +<P>Thus, if we bound the following module declaration: +<P><TT>module mod</TT> +<BR><TT>{</TT> +<BR><TT> #define N</TT> +<BR><TT> extern int var;</TT> +<BR><TT> int func (...):</TT> +<BR><TT>}</TT> +<P>In Lua we would be able to access such features by indexing the module: +<TT>mod.N</TT>, +<TT>mod.var</TT>, +<TT>mod.func</TT>. +<H3> +<A NAME="renaming"></A>Renaming constants, variables and functions</H3> +When exporting constants, variable, and functions (members of a class or +not), we can rename them, such that they will be bound with a different +name from their C/C++ counterparts. To do that, we write the name they +will be referenced in Lua after the character <TT>@</TT>. For instance: +<P><TT>extern int cvar @ lvar;</TT> +<P><TT>#define CNAME @ LNAME</TT> +<P><TT>enum {</TT> +<BR><TT> CITEM1 @ LITEM1,</TT> +<BR><TT> CITEM2 @ LITEM2,</TT> +<BR><TT> ...</TT> +<BR><TT>};</TT> +<P><TT>void cfunc @ lfunc (...);</TT> +<P><TT>class T</TT> +<BR><TT>{</TT> +<BR><TT> double cfield @ lfield;</TT> +<BR><TT> void cmeth @ lmeth (...);</TT> +<BR><TT> ...</TT> +<BR><TT>};</TT> +<P>In such a case, the global variable <TT>cvar </TT>would be identified +in Lua by <TT>lvar</TT>, the constant <TT>CNAME </TT>by <TT>LNAME</TT>, +and so on. Note that class cannot be renamed, because they represent types +in C. +<P>This renaming feature allows function overload in C, because we can +choose to export two different C functions with a same Lua name: +<P><TT>void glVertex3d @ glVertex (double x, double y, double z=0.0);</TT> +<BR><TT>void glVertexdv @ glVertex (double v[3]=0.0);</TT> + +<a name="type_renaming"></a><h3>Renaming Types</h3> + +Types can be renamed using the <tt>$renaming</tt> directive on pkg files, using the +format: +<p> + +<tt>$renaming real_name @ new_name</tt> +<p> + +The parameters to renaming can be Lua <i>patterns</i>. For example: +<p> + +<pre> +$renaming ^_+ @ +$renaming hash_map<string,vector<double> > @ StringHash +</pre> + +The first example will remove all underscores at the beginning of all types, +the second will rename the template type hash_map<string,vector<double> > +to StringHash. Once renamed, the Lua table for each type can be accessed only by their +new name, for example: <tt>StringHash:new()</tt> + +<A NAME="additional"></A><h3>Storing additional fields</H3> +Finally, it is important to know that even though the variables that hold +C/C++ objects are actually tagged userdata for Lua,<B> tolua</B> creates +a mechanism that allows us to store any additional field attached to these +objects. That is, these objects can be seen as conventional Lua tables. +<PRE>obj = <I>ClassName</I>:new()</PRE> + +<PRE>obj.myfield = 1 -- even though "myfield" does not represent a field of ClassName</PRE> +Such a construction is possible because, if needed, <B>tolua </B>automatically +creates a Lua table and associates it with the object. So that, the object +can store additional fields not mapped to C/C++, but actually stored in +the conjugate table. The Lua programmer accesses the C/C++ features and +these additional fields in an uniform way. Note that, in fact, these additional +fields overwrite C/C++ fields or methods when the names are the same. + + + +<a name="additional_features"></a><h3>Additional features on tolua++</h3> + +<h4>Multiple variable declarations</h4> + +Multiple variables of the same type can be declared at the same time, for example: +<p> +<tt>float x,y,z;</tt> +<p> +will create 3 different variables of type float. Make sure you don't leave any +spaces between the commas, as that will raise a parse error. +<p> + +<h4>tolua_readonly</h4> + +Any variable declaration can use the <tt>tolua_readonly</tt> modifier, to ensure +that the variable is read-only, even when its type is not <tt>const</tt>. Example: + +<pre> +class Widget { + + tolua_readonly string name; +}; +</pre> + +This feature could be used to 'hack' the support for other unsupported things like +<tt>operator-></tt>. Consider this example <tt>pkg</tt> file: + +<pre> +$hfile "node.h" +$#define __operator_arrow operator->() +$#define __get_name get_name() +</pre> + +And on the file <tt>node.h</tt>: + +<pre> +template class<T> +class Node { // tolua_export + +private: + string name; + T* value; + +public: + + T* operator->() {return value;}; + string get_name() {return name;}; + + // tolua_begin + + #if 0 + TOLUA_TEMPLATE_BIND(T, Vector3D) + + tolua_readonly __operator_arrow @ p; + tolua_readonly __get_name @ name; + #endif + + + Node* next; + Node* prev; + + void set_name(string p_name) {name = p_name;}; + + Node(); +}; +// tolua_end +</pre> + +While not a pretty thing to do to a header file, this accomplishes a number of +things: +<p> + +<li> The method <tt>operator->()</tt> can be used from Lua by calling the variable +<tt>p</tt> on the object.</li> +<li> The method <tt>get_name()</tt> can be using from Lua by calling the variable +<tt>name</tt> on the boject.</li> + +Example lua usage: + +<pre> +node = Node_Vector3D_:new_local() +-- do something with the node here -- +print("node name is "..node.name) +print("node value is ".. node.p.x ..", ".. node.p.y ..", ".. node.p.z) +</pre> + +Since <b>tolua++</b> ignores all preprocessor directives (except for #define), <tt>node.h</tt> +remains a valid C++ header file, and also a valid source for <b>tolua++</b>, +eliminating the need to maintain 2 different files, even for objects with +unusual features such as these ones. + +<p> + +The ability to rename functions as variables might be expanded on future versions. + +<h4>Defining values on command line</h4> + +Starting from version 1.0.92, the command line option <tt>-E</tt> allows +you to introduce values into to the luastate where <b>tolua++</b> runs, +similar to GCC's <tt>-D</tt>. For example: +<p> + +<pre>$ tolua++ -E VERSION=5.1 -E HAVE_ZLIB package.pkg > package_bind.cpp</pre> + +<p> +This will add 2 fields to the global table <tt>_extra_parameters</tt>: +"VERSION", with the string value "5.1", and "HAVE_ZLIB" with the boolean value +<tt>true</tt>. For the moment, there is no way to 'use' these values, except +in custom scripts defined by the user (see +<a href="#customizing">customizing tolua++</a> for details). + +<h4>Using C++ typeid</h4> + +Starting from version 1.0.92, the command line option <tt>-t</tt> is available, +which generates a list of calls to the empty macro <tt>Mtolua_typeid</tt>, with its +C++ <tt>type_info object</tt>, and the name used by tolua++ to identify the type. For example, +if you have a package that binds 2 classes, <tt>Foo</tt> and <tt>Bar</tt>, using <tt>-t</tt> +will produce the following output: + +<pre> +#ifndef Mtolua_typeid +#define Mtolua_typeid(L,TI,T) +#endif + Mtolua_typeid(tolua_S,typeid(Foo), "Foo"); + Mtolua_typeid(tolua_S,typeid(Bar), "Bar"); +</pre> + +The implementation of Mtolua_typename is left as an exercise to the user. + +<H3> +<A NAME="utilities"></A>Exported utility functions</H3> +<B>tolua </B>uses itself to export some utility functions to Lua, including +its object-oriented framework. The package file used by <B>tolua </B>is + +shown below: +<P><TT>module tolua</TT> +<BR><TT>{</TT> +<BR><TT> char* tolua_bnd_type @ type (lua_Object lo);</TT> + +<BR><TT> void tolua_bnd_takeownership @ takeownership (lua_Object lo);</TT> +<BR><TT> void tolua_bnd_releaseownership @ releaseownership (lua_Object lo);</TT> + +<BR><TT> lua_Object tolua_bnd_cast @ cast (lua_Object lo, char* type);</TT> + +<BR><TT> void tolua_bnd_inherit @ inherit (lua_Object table, lua_Object instance);</TT> +<p> +<TT>/* for lua 5.1 */</tt> +<BR><TT> void tolua_bnd_setpeer @ setpeer (lua_Object object, lua_Object peer_table);</TT> +<BR><TT> void tolua_bnd_getpeer @ getpeer (lua_Object object);</TT> + +<BR><TT>}</TT> + +<H4> +tolua.type (<I>var</I>)</H4> +Returns a string representing the object type. For instance, <TT>tolua.type(tolua)</TT> +returns the string <TT>table</TT> and <TT>tolua.type(tolua.type)</TT> +returns <TT>cfunction</TT>. Similarly, if <TT>var </TT>is a variable holding +a user defined type <TT>T</TT>, <TT>tolua.type(var)</TT> would return +<TT>const +T</TT> or <TT>T</TT>, depending whether it is a constant reference. +<p> + +<h4>tolua.takeownership (<I>var</i>)</h4> + +Takes ownership of the object referenced <i>var</i>. This means that when all references +to that object are lost, the objects itself will be deleted by lua. +<p> + +<h4>tolua.releaseownership (<i>var</i>)</h4> + +Releases ownership of the object referenced by <i>var</i>. +<p> + +<h4>tolua.cast (<i>var</i>, <i>type</i>)</h4> + +Changes the metatable of <i>var</i> in order to make it of type <i>type</i>. <i>type</i> needs +to be a string with the complete C type of the object (including namespaces, etc). + +<h4>tolua.inherit (<i>table</i>, <i>var</i>)</h4> (new on <b>tolua++</b>) + +Causes <b>tolua++</b> to recognise <i>table</i> as an object with the same type as <i>var</i>, +and to use <i>var</i> when necesary. For example, consider this method: +<p> + +<ul><tt>void set_parent(Widget* p_parent);</tt></ul> +<p> + +A lua object could be used like this: +<p> + +<pre> +local w = Widget() +local lua_widget = {} +tolua.inherit(lua_widget, w) + +set_parent(lua_widget); + +</pre> + +Remember that this will only cause the table to be recognised as type 'Widget' when +necesary. To be able to access Widget's methods, you'll have to implement your own +object system. A simple example: +<p> + +<pre> + +lua_widget.show = Widget.show + +lua_widget:show() -- this will call the 'show' method from 'Widget', using the lua + -- table as 'self'. Since lua_widget inherits from a widget instance, + -- tolua++ will recognise 'self' as a 'Widget', and call the method + +</pre> +<p> + +Of course a better way would be to add a __index metamethod for the lua object. +<p> + +Similarily, to implement virtual functions, you'll need to create a c++ object that inherits +from the desired type, implement its virtual functions, and use that to inherit from lua. The +object would have a reference to the lua table, and call its methods from the c++ virtual +methods. +<p> + +<b>Note:</b> the current implementation (as of version 1.0.6) stores the C instance +inside the lua table on the field ".c_instance", and looks that up when necesary. This +might change in the future, so it is recommended to use an alternative way to store the +C instance to use with your own object system. + +<h4>tolua.setpeer (<i>object</i>, <i>peer_table</i>) (lua 5.1 only)</h4> + +Sets the table as the object's <i>peer</i> table (can be <tt>nil</tt>). The peer table is where all the custom +lua fields for the object are stored. When compiled with lua 5.1, <b>tolua++</b> stores the +peer as the object's <i>envirnment table</i>, and uses uses <tT>lua_gettable/settable</tT> (instead of +<tt>lua_rawget/set</tt> for lua 5.0) to retrieve and store fields on it. This allows us to implement our own +object system on our table (using metatables), and use it as a way to inherit from the userdata object. +Consider an alternative to the previous example: + +<pre> +-- a 'LuaWidget' class +LuaWidget = {} +LuaWidget.__index = LuaWidget + +function LuaWidget:add_button(caption) + + -- add a button to our widget here. 'self' will be the userdata Widget +end + + +local w = Widget() +local t = {} +setmetatable(t, LuaWidget) -- make 't' an instance of LuaWidget + +tolua.setpeer(w, t) -- make 't' the peer table of 'w' + +set_parent(w) -- we use 'w' as the object now + +w:show() -- a method from 'Widget' +w:add_button("Quit") -- a method from LuaWidget (but we still use 'w' to call it) +</pre> + +When indexing our object, the peer table (if present) will be consulted first, so we +don't need to implement our own __index metamethod to call the C++ functions. + +<h4>tolua.getpeer (<i>object</i>) (lua 5.1 only)</h4> + +Retrieves the peer table from the object (can be <tt>nil</tt>). + +<!-- +<H3> +<A NAME="utilities"></A>Exported utility functions</H3> +<B>tolua </B>uses itself to export some utility functions to Lua, including +its object-oriented framework. The package file used by <B>tolua </B>is +shown below: +<P><TT>module tolua</TT> +<BR><TT>{</TT> +<BR><TT> void tolua_using @ using (lua_Table module);</TT> +<BR><TT> char* tolua_type @ type (lua_Object lo);</TT> +<BR><TT> void tolua_foreach @ foreach (lua_Object lo, lua_Function +f);</TT> +<BR><TT> void tolua_class @ class (lua_Table derived, lua_Table base=TOLUA_NIL);</TT> +<BR><TT> void tolua_instance @ instance (lua_Table instance, lua_Table +classobj);</TT> +<BR><TT> lua_Object tolua_base @ base (lua_Object lo);</TT> +<BR><TT>}</TT> +<H4> +tolua.using (<I>table</I>)</H4> +This functions receives a table and maps all its fields to the global environment. +Thus we can map an entire module and access its features without the module +prefix. For instance, if in our Lua code we do: +<P><TT>tolua.using(tolua)</TT> +<P>all <B>tolua </B>utility functions are mapped to the global environment. +<H4> +tolua.type (<I>var</I>)</H4> +Returns a string representing the object type. For instance, <TT>tolua.type(tolua)</TT> +returns the string <TT>generic module</TT> and <TT>tolua.type(tolua.type)</TT> +returns <TT>cfunction</TT>. Similarly, if <TT>var </TT>is a variable holding +a user defined type <TT>T</TT>, <TT>tolua.type(var)</TT> would return +<TT>const +T</TT> or <TT>T</TT>, depending whether it is a constant reference. +<H4> +tolua.tag (<I>"type"</I>)</H4> +Returns type corresponding tag number. +<H4> +tolua.foreach (<I>object</I>)</H4> +Allows us to traverse the conjugate table of an user defined instance. +If applied to conventional table, it has a similar behavior as the Lua +built-in <TT>foreach </TT>function. The difference is that this function +filters all fields starting with a dot, not passing them to the provided +callback function. This filter is need because <B>tolua </B>adds "hidden" +fields to the tables it manipulates, and all its "hidden" fields start +with a dot. +<H4> +tolua.cast (<I>object, "typename"</I>)</H4> +Returns the object "casted" to the given type. The object must represent +an user type, otherwise the function returns <B><TT>nil</TT></B>. +<H4> +tolua.takeownership (<I>object</I>)</H4> +Asks <B>tolua</B> to take the ownership of the given object. This means +the C/C++ object will be freed/ destructed when garbage-collected by Lua. +The object must represent an user type, otherwise an execution error is +generated. +<H4> +tolua.class (<I>table</I>, <I>base=nil</I>)</H4> +Creates a class by setting the appropriate tag methods to the given table. +The created class can inherit from a base class, previously created. +<H4> +tolua.instance (<I>table</I>, <I>class</I>)</H4> +Sets the given table to be an instance of the given class. This and the +previous utility functions allow object-oriented programming in Lua. As +an example consider: +<P><TT>-- define a Point class</TT> +<BR><TT>classPoint = { x=0, y=0 }</TT> +<BR><TT>tolua.class(classPoint) -- set as a class</TT> +<P><TT>-- define print method</TT> +<BR><TT>function classPoint:print ()</TT> +<BR><TT> print(self.x,self.y)</TT> +<BR><TT>end</TT> +<P><TT>-- define add method</TT> +<BR><TT>function classPoint:add (p2)</TT> +<BR><TT> return Point{x=self.x+p2.x,y=self.y+p2.y}</TT> +<BR><TT>end</TT> +<P><TT>-- define a Point constructor</TT> +<BR><TT>function Point (p)</TT> +<BR><TT> tolua.instance(p,classPoint) -- set as an instance +of classPoint</TT> +<BR><TT>return p end</TT> +<P><TT>-- define a Color Point class</TT> +<BR><TT>classColorPoint = { color = 'black' }</TT> +<BR><TT>tolua.class(classColorPoint,classPoint) -- set as class inheriting +from classPoint</TT> +<P><TT>-- define class methods</TT> +<BR><TT>function classColorPoint:print ()</TT> +<BR><TT> print(self.x,self.y,self.color)</TT> +<BR><TT>end</TT> +<P><TT>-- define Color Point constructor</TT> +<BR><TT>function ColorPoint (p)</TT> +<BR><TT> tolua.instance(p,classColorPoint) -- set as an instance +of classColorPoint</TT> +<BR><TT> return p</TT> +<BR><TT>end</TT> +<P><TT>-- Some valid codes would then be</TT> +<BR><TT>p = Point{x=1}</TT> +<BR><TT>q = ColorPoint{x=2,y=3,color=2}</TT> +<BR><TT>r = p:add(q)</TT> +<BR><TT>r:print() --> would print "3 3"</TT> +<BR> +--> + +<H3> +<A NAME="embedded"></A>Embedded Lua code</H3> +<B>tolua</B> allows us to embed Lua code in the C/C++ generated code. To +do that, it compiles the specified Lua code and creates a C constant string, +storing the corresponding bytecodes, in the generated code. When +the package is opened, such a string is executed. The format to embed Lua +code is: +<P><B><TT>$[</TT></B> +<P><I><TT>embedded Lua code</TT></I> +<BR><I><TT>...</TT></I> +<P><B><TT>$]</TT></B> +<P>As an example consider the following .pkg excerpt: +<P><TT>/* Bind a Point class */</TT> +<BR><TT>class Point</TT> +<BR><TT>{</TT> +<BR><TT> Point (int x, int y);</TT> +<BR><TT> ~Point ();</TT> +<BR><TT> void print ();</TT> +<BR><TT> ...</TT> +<BR><TT>} CPoint;</TT> +<P><TT>$[</TT> +<P><TT>-- Create a Point constructor</TT> +<BR><TT>function Point (self)</TT> +<BR><TT> local cobj = CPoint:new(self.x or 0, self.y or 0)</TT> +<BR><TT> tolua.takeownership(cobj)</TT> +<BR><TT> return cobj</TT> +<BR><TT>end</TT> +<P><TT>$]</TT> +<P>Binding such a code would allow us to write the following Lua code: +<P><TT>p = Point{ x=2, y=3 }</TT> +<BR><TT>p:print()</TT> +<BR><TT>...</TT> +<BR> + +<h3><a name="customizing"></a>Customizing tolua++</h3> +<p> + +<b>tolua++</b> calls empty functions at specific points of its execution. This functions +can be redefined on a separate lua file (and included using the -L command line option) +and be used to control the way <b>tolua++</b> behaves. This is the list of functions +(taken from basic.lua on the <b>tolua++</b> source): +<p> + +<PRE> + +-- called right after processing the $[ichl]file directives, +-- right before processing anything else +-- takes the package object as the parameter +function preprocess_hook(p) + -- p.code has all the input code from the pkg +end + + +-- called for every $ifile directive +-- takes a table with a string called 'code' inside, the filename, and any extra arguments +-- passed to $ifile. no return value +function include_file_hook(t, filename, ...) + +end + +-- called after processing anything that's not code (like '$renaming', comments, etc) +-- and right before parsing the actual code. +-- takes the Package object with all the code on the 'code' key. no return value +function preparse_hook(package) + +end + + +-- called after writing all the output. +-- takes the Package object +function post_output_hook(package) + +end + +-- called at the beginning of the main parser function, with the code being parsed as a parameter +-- it can return nil if nothing was foind, or the contents of 'code', modified by the function +-- Usually a parser hook will search the beginning of the string for a token, and if it finds +-- anything, return the string without that token (after doing whatever it has to do with the token). +function parser_hook(code) + +end + + +-- called from classFunction:supcode, before the call to the function is output +-- the classFunction object is passed. +function pre_call_hook(f) + +end + +-- called from classFunction:supcode, after the call to the function is output +-- the classFunction object is passed. +function post_call_hook(f) + +end + +-- called before the register code is output +function pre_register_hook(package) + +end + +-- called to output an error message +function output_error_hook(...) + return string.format(...) +end + + +</PRE> +<p> + +<h4>Handling custom types</h4> + +Starting from version 1.0.93, it is possible to specify custom functions to handle certain types. There are 3 +types of functions: a <tt>'push function'</tt>, used to push the C value onto the Lua stack, a <tt>'to function'</tt>, +used to retrieve the value from the Lua stack, and return it as a C value, and an <tt>'is function'</tt>, used to +check if the value on the stack is valid (or convertible to a C value by the <tt>to function</tt>). These functions are modelled upon +<tt>tolua_pushusertype</tt>, <tt>tolua_tousertype</tt> and <tt>tolua_isusertype</tt>, declared in <tt>tolua++.h</tt>. +<p> +A number of arrays found in <tt>basic.lua</tt> are used to specify these functions: +<p> + +<PRE> +-- for specific types +_push_functions = {} +_is_functions = {} +_to_functions = {} + +-- for base types +_base_push_functions = {} +_base_is_functions = {} +_base_to_functions = {} +</PRE> + +<b>Example (using the -L command line option):</b> +<p> + +<PRE> +_is_functions['Vector3'] = 'custom_is_vector3' -- checks for a 3d vector + -- (either userdata, or a table with 3 values) +_to_functions['Vector3'] = 'custom_to_vector3' -- convertes the eventual table to a Vector3 + +_base_push_functions['Widget'] = 'custom_push_widget' -- pushes anything that inherits from Widget +</PRE> + +The <tt>_base</tt> tables are used to lookup functions for types that are up in the inheritance chain. + +<h4>Access</h4> + +Starting from version 1.0.7, all objects have a an <tt>access</tt> flag, which determines the object's access +inside its container. Container objects also have a member called <tt>curr_member_access</tt>, which determines +the access of each child object at the moment of its addition to the container. If the <tt>access</tt> flag has +the value <tt>nil</tt> (default), <tt>false</tt> or <tt>0</tt>, the object is public. Otherwise, the object +is not public, and <b>tolua++</b> will not export any code for that object (and any objects it may contain). +<p> + +Another 'interesting' function is <tt>extract_code</tt>, defined on basic.lua, which +extracs the code from files included with $cfile and $hfile (by looking for tolua_begin/end and tolua_export). +<p> + +<h3><a name="compatibility"></a>Compatibility with older versions.</h3> + +<h4>tolua++ <1.0.90</h4> +<p> +Version 1.0.90 of <b>tolua++</b> introduces 2 small API changes the might be incompatible +with older versions on some cases: +<p> +<b>TEMPLATE_BIND</b> +<p> +<tt>TEMPLATE_BIND</tt> is deprecated. Use <tt>TOLUA_TEMPLATE_BIND</tt> instead. Also, when +declaring a template, the <tt>TOLUA_TEMPLATE_BIND</tt> statement has to be the first thing +inside the class declaration, otherwise it will be ignored. This fixes a possible problem +with nested template declarations. +<p> + +<b>Retrieving Objects</b> +<p> + +When passing a full userdata to a function that accepts light userdata parameters (void*), +the <b>tolua++</b> library function <tt>tolua_touserdata</tt> will detect the full userdata and dereference +the void** pointer if necesary. This is a change on the function's behaviour (which used to return the pointer as-is). This allows us to pass pointers to objects to a function that accepts +void* pointers. Note that this was a problem when switching from <b>toLua</b> version 4 to version 5 (and <b>tolua++</b> versions < 1.0.90). + +<h4>toLua 4</h4> +<p> + +<b>Retrieving Objects</b> +<p> + +Users switching from <b>tolua</b> v4 should know that <b>tolua++</b> stores the objects as +<tt>void**</tt> on Lua, so when retrieving an object from the luastate using <tt>lua_touserdata</tt>, +the pointer should be dereferenced. The library function <tt>tolua_tousertype</tt> +should work as expected. Example: +<p> + +<pre> +lua_pushglobal(lua_state, "get_Object"); +lua_call(lua_state, 0, 1); // calling a function that returns an Object + +Object *new_object = (Object*)(*lua_touserdata(lua_state, -1)); +<i>or</i> +Object *new_object = (Object*)tolua_tousertype(lua_state, -1, NULL); +</pre> + +<b>C++ Strings</b> +<p> + +<b>tolua++</b> binds the c++ type <tt>std::string</tt> as a basic type, passing it +to Lua as a regular string (using the method <tt>c_str()</tt>). This feature can be +turned off with the command line option <tt>-S</tt>. +<p> + +<b>Operators</b> +<p> + +The list of supported operators has changed, see <a href="#classes">Binding classes and methods</a> +for more information. +<p> + +<h4>toLua 5</h4> +<p> + +<b>Class destructors.</b> +<p> + +With every class constructor, <b>tolua++</b> exports a 'local' constructor, to create an instance +of the class that is owned by the lua state. To implement this, <b>tolua++</b> will also export +a function that will <tt>delete</tt> the class. There are 2 options to prevent this: +<p> + +Using the <b>-D</b> command line option will turn this off completely. Destructor functions will +only be exported when a destructor for the class is explicitly declared, or when there is a function +or method that returns an object of the type by value (this is compatible with <b>tolua</b>'s behaviour). +<p> + +Using the <tt>TOLUA_PROTECTED_DESTRUCTOR</tt> directive inside the class declaration, to specify that the +class has a private or protected destructor. In this case, no destructor will be exported for that class. +<p> + +<b><tt>operator[]</tt> index</b> +<p> + +Users switching from <b>tolua</b> v5 should know that <b>tolua</b> 5 substracts 1 +from the index on operator[] functions, for compatibility with lua's method for indexing arrays +(1 is the first element). This feature is turned off by default on <b>tolua++</b> +(making it compatible with <b>tolua</b> 4). It can be turned back on with the +command line option <tt>-1</tt> +<p> + +<b>C++ Strings</b> +<p> + +(see c++ strings on <b>tolua</b> 4 below) + + +<H3> +<A NAME="changes-v30"></A>Changes since v. 3.0</H3> + +<ul> + +<LI> +Support for binding arrays as variables and struct/class fields;</LI> + +<LI> +Support for embedding Lua code into the generated binding code;</LI> + +<LI> +New utility functions: <I>cast</I> and <I>takeownership</I>;</LI> + +<LI> +Option to create the corresponding header file of the binding code;</LI> + +<LI> +New "close" package function;</LI> + +<LI> +Fixed bug on cloning objects in C++;</LI> + +<LI> +Fixed bug on enum and struct parsing;</LI> +</ul> +<H3> +<A NAME="changes-v2"></A>Changes since v. 2.0</H3> +<ul> + +<LI> +There is a new executable parser;</LI> + +<LI> +Support for multiple Lua states is provided;</LI> + +<LI> +Support for module definition is provided;</LI> + +<LI> +Global variables is now directly bound to Lua global variables;</LI> + +<LI> +Constness of user defined types is preserved in Lua;</LI> + +<LI> +Support for multiple returned values from C/C++ is provided (simulating +parameters passed by reference);</LI> + +<LI> +Constants, variables, and functions bound to Lua can have different names +from their C/C++ counterparts;</LI> + +<LI> +Object-oriented framework (and other utility functions) used in <B>tolua +</B>is +now exported for Lua programmers;</LI> + +<H4> +Incompatibilities</H4> +Lua code based on <B>tolua</B> v2.* should run with no change on <B>tolua +</B>v3.0. +Although, it may be necessary to change the .pkg file in order to get the +same behavior. The following incompatibilities exist: +<UL> +<LI> +Parameters defined as pointer to basic types are no longer converted to +arrays of dimension one; they are now considered parameters passed by reference.</LI> + +<LI> +Automatic initialization for C++ code must be explicitly requested when +using the new parser;</LI> + +<LI> +Global variables are no longer mapped to a table; the definition of a module +including the global variables may be used to simulate the old behavior;</LI> + +<LI> +The initialization function is no longer toLua_<I>package</I>_open but +tolua_<I>package</I>_open, without the capital letter (sorry!).</LI> +</UL> +</ul> +<H3> +<A NAME="changes-v1"></A>Changes since v. 1.*</H3> + +<ul> +<LI> +The binding code should run much faster;</LI> + +<LI> +The <I>cleaned header file </I>extension should now be <TT>.pkg</TT> instead +of <TT>.L</TT>;</LI> + +<LI> +Type modifiers is now accepted (though the current version ignores +<TT>const</TT>'s);</LI> + +<LI> +Returning object by value is accepted and memory allocation is controlled +by Lua garbage collection;</LI> + +<LI> +Overloaded functions/methods are accepted;</LI> + +<LI> +Parameters with default values are accepted;</LI> + +<LI> +Some overloaded operators are automatically bound.</LI> +</ul> + +<H3> +<A NAME="credits"></A>Credits</H3> +Luiz Henrique de Figueiredo had the idea of creating a tool to automatically +bind C code to Lua. L.H.F. wrote the very first version of such a tool +(that bound C functions, variables, and constants) in <I>awk</I>. At that +time, Waldemar Celes (now the main author) was only responsible for the C code that supported the generated +binding code. +<p> +While working at NGD Studios, Ariel Manzur made some changes to tolua4 for their +game engine. After the release of tolua5, having left NGD, enough changes were +made to tolua to justify a separate release (with Waldemar's blessing :-) +<BR> +<H3> +<A NAME="availability"></A><B>Availability</B></H3> +<B>tolua++ </B>is freely available by <A HREF="http://www.codenix.com/~tolua/tolua++-current.tar.bz2">http</A>. +The software provided hereunder is on an "as is" basis, and the author +has no obligation to provide maintenance, support, updates, enhancements, +or modifications. +<P> +<HR WIDTH="100%">This document was created by <A HREF="http://www.tecgraf.puc-rio.br/~celes/">Waldemar Celes</A> +With modifications by <a href="http://www.codenix.com/index.php?section=contact">Ariel Manzur</a>/ +<BR>Last update: Sept 2003<BODT> +</BODY> +</HTML> |