tolua++ reference Manual (translation)

Original address: http://www.codenix.com/~tolua/tolua++.html

Translator Note: In the online seemingly no corresponding Tolua Chinese version of the document, so whim, translated the first part: Tolua use. The first translation made a lot of mistakes. There may also be a lot of errors that are suggested to read with the original. If there are errors, I hope you crossing point out, thank you.

Tolua++ is an upgraded version of Tolua and is a tool used in combination with C + + and LUA code. tolua++ includes some new features from C + +, such as support for std::string, and support for class template as a basic type

Of course, there are some new features and bug fixes.

The use of Tolua greatly simplifies the integration of code between C + + and Lua. Based on a clean header file (or an extended header file), Tolua automatically generates the relevant code for LUA to access C + +.

Using Lua's API and tagging methods (tag method facilities), Tolua can map constants, variables, functions, classes, and methods in C + + + to Lua.

This manual is tolua++ version 1.0, for Lua5.0 and above, based on tolua5.0. If you are using an older version, see the Compatibility Details.

The following sections describe how to use Tolua. If you find errors, or have suggestions and comments, please contact us. How Tolua Works and use Tolua Basic Concepts Binding constants binding external variables binding fun Ctions binding struct fields binding classes and methods binding properties Class Templates Module definition renaming con Stants, variables and functions storing additional fields additional features exported utility functions Embedded Lua code Customizing tolua++ compatibility with older versions changes since V3 * Changes since v2.* changes since v1.* Credits Av ailability how Tolua works

To use Tolua, we need to create a package file, a clean-C + + (cleaned header file) that lists only constants, variables, functions, classes, and methods that we want to expose to Lua. Then Tolua analyzes the file and automatically creates a C + + file that automatically binds the C + + code to LUA. When our program links to this file, we are able to access the corresponding C + + code from LUA.

The package file can include regular header files, other package files, and Lua files.

Let's start with some examples. If we specify the following C header file input to Tolua:

#define FALSE 0

#define TRUE 1

enum {

Point = 100,

Line,

POLYGON

}

object* createobejct (int type);

void drawobject (object* obj, double red, double green, double blue);

int isSelected (object* obj);

This code is bound to LUA and automatically generates a C file. So, in LUA code, we have access to the corresponding C code, for example (writing, for instance:):

...

Myline = CreateObject (line)

...

If isSelected (myline) = = TRUE Then

Rawobject (Myline, 1.0, 0.0, 0.0);

Else

Rawobject (Myline, 1.0, 1.0, 1.0);

End

...

Also, consider a C + + header file:

#define FALSE 0

#define TRUE 1

Class Shape

{

void draw (void);

void Draw (double red, double green, double blue);

int isSelected (void);

};

Class Line:public Shape

{

Line (double x1, double y1, double x2, double y2);

~line (void);

};

If the file is to be loaded into Tolua, a C + + file is automatically generated, providing LUA with access to the corresponding code. Therefore, the following LUA code is valid:

...

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 ()

...

The package file passed to Tolua is not a true C + + header file, but rather a clean version (cleaned versions). Tolua does not perform a complete parsing of the C + + code, but only resolves some declarations that describe the claims exposed to LUA functionality (it understands a few declarations that is used to describe the Featu Res that is to is exported to Lua.).

Usually the header file can be included in the packages file, Tolua will extract the corresponding code to parse the corresponding header file (see Basic Concepts). How to use Tolua

Tolua consists of two parts of code: executable and static libraries (an executable and a library). The executable program is used for parsing, reading from the package file, and then outputting C + + code, which provides LUA with a way to access C + +. If the package file is code similar to C + +, such as the definition of a class, a copy of the C + + code is generated. If the package file is code similar to C (for example, excluding classes), a C code is generated. The Tolua receives a series of selections (Tolua accepts a set of options). Run "tolua-h" to display the currently available selections. For example, to resolve a bundle code named MYFILE.PKG that generates a name of myfile.c, we need to enter:

Tolua-o myfile.c myfile.pkg

The generated code must be generated and linked by the application to be available to LUA for access. Each parsed file generates a package that is exposed to LUA. By default, the name of the package is the root input file name (example of MyFile), and the user can specify a different name for the packages:

Tolua-n Pkgname-o myfile.c myfile.pkg

The package should also be explicitly initialized. We need to declare and invoke the initialization function, Conghua our C + + code to initialize the package. The initialization function is defined as:

int Tolua_pkgname_open (lua_state*);

Where Pkgname is the name of the bundled package. If we are using C + +, we can choose to initialize automatically:

Tolua-a-N pkgname-o myfile.c myfile.pkg

In this case, the initialization function is called automatically. However, if we plan to use more than one LUA, automatic initialization will not work, because the order in which static variables are initialized is not defined in C + +.

Optionally, the prototype of the Open function can be outputted to a header file, which name was given by the-h option.

The binding code generated by Tolua uses a series of functions inside the Tolua library. Therefore, the library also needs to be linked to the application. Similarly, tolua.h needs to add the build code to the compilation. Applications do not have to bind any package files or use Tolua's object-oriented framework (see exported utility functions). In this case, the application must call the Tolua initialization function (This function is called any package file initialization function):

int tolua_open (void);

Basic Concepts

The first step is to use Tolua to create the package file. Starting with a real header file, we re-convert the features that we want to expose to LUA into a format that Tolua can understand. including files

A package file can include other package files. The General format is:

$pfile "Include_file"

A package file can also include a generic C + + header file, using the hfile or CFile directives:

$cfile "Example.h"

In this case, Tolua will extract the code enclosed between Tolua_begin and tolua_end, or Tolua_export on a straight line. Consider this C + + head as an example: (Note: Not every header file here needs to use these annotations to tell Tolua to add the code, just for the header file included in the package file)

#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

In this case, the code that's not supported by Tolua (The private part of the Class), along with the functionset_ Number is the left outside of the package, the includes this header.

Finally, LUA files can be included in the package file, using $lfile:

$lfile "Example.lua"

New tolua++: Since the 1.0.4 version of tolua++, provides an additional way to include source files, using ifile:

$ifile "FileName"

IFile also has additional optional parameters after the file name (IFile also takes extra optional parameters after the filename), for example:

$ifile "Widget.h", GUI
$ifile "Vector.h", Math, 3d

The default behavior of IFile is to include the entire file as is. However, the contents of the file and additional parameters are processed by the Include_file_hook function before being included in the package (see Customizing tolua++ for more details).

Basic Types

The Tolua automatically maps the basic type of C + + to the basic type of LUA. Therefore, char, int, float, and double map to the number type of LUA; char * maps to String;void * map to UserData. Types May is preceded by modifiers (unsigned,static, short, const, etc); However, it is recognized that Tolua ignores the const (be aware, this Tolua ignores the modifier const if applied to basic types) used to modify the base type. So if we pass a basic type of constant (Conston) to LUA and then Lua returns that number to C + +, then the conversion between the very constant and the constants will be done quietly in the background.

The functions of C + + can also explicitly use LUA objects. So Lua_object is also considered to be a basic type. Therefore, any LUA satisfies this requirement.

The new Tolua + +: The string type in C + + is also considered to be the basic type and will be passed as a value to LUA (using the C_str () method). This feature can be turned off using command line-S. User defined Types

All other types in the package file will be considered user-defined types. They map to the UserData type of LUA. Lua can only store pointers to user-defined types, but Tolua automatically generates the necessary arrangements to process references and values. For example, if a function or method returns a value of a user-defined type, when this value is returned to Lua, Tolua allocates a cloned object and sets the garbage collection token to be freed automatically when LUA is no longer using the object.

Constants are reserved for user-defined types. Therefore, passing the very amount of user-defined type data as a constant parameter to a function produces a type mismatch error. NULL and Nil

The null or 0 pointer for C/A + + is mapped to the nil type of LUA, whereas nil may point to any possible C/n + + pointers (Conversely, nil can specified wherever A/C + + pointer is expected .）。 Typedefs

Tolua also accepts package files with a simple typedef (Tolua also accepts easy typedef ' s inside the. Whenever a type is defined, Tolua maps it to the base type. They are useful because some of the package will re-customize the C + + type to their type. For example, a package can define type Real to represent a double type. In this case, real can be used for the package file of the specified type variable, which is parsed by LUA (real can be used to specify the variable types inside the. File interpreted B Y Tolua), but only if we include the following definitions before use:

typedef double REAL;

Otherwise, real will be interpreted as a user-defined type and not mapped to the number type of Lua. including real header files

In the package file, we must specify the corresponding header files that contain the constants, variables, functions, and classes that we want to access. Any line beginning with $ (except $[hclp]file, $[, and $] lines) in the package file will be inserted into the generated code that is bound to C + + with no repair , but will eliminate the $ Number itself. We use this feature class to introduce real header files. So, our header file will typically set $ as the start, specifying the files that correspond to the files to be referenced, those that the package needs.

/* Specify the files to be included */

$ #include "header1.h"//Include first header

$ #include "header2.h"//Include second header

As illustrated, Tolua also accepts comments, using C or C + + convention, inside the package file. Nested C-like comments can also be used.

It is also noted that the $cfile or $hfile in the file do not need to be used in this way, and this tolua is done automatically.

In the following sections, we'll show you how to specify C + + code that we want to bind to Lua. These formats are simple and conform to the declarative way of C + +. Binding Constants

Tolua supports two ways to bind constants: Define ' s and Enum's. The general format for define ' s is:

#define NAME [VALUE]

The above value can be selected (the value, as showed above, is optional). If such a code appears in the file to be parsed, Tolua will use name as the global variable for LUA, which is a C/s constant with value values. Only numeric constants are accepted.

New tolua++: all other pre-processing instructions are ignored.

The general format for enum ' s is: