tolua reference

Using Lua API and tag method facilities, tolua maps C/C++ constants, external variables, functions, classes, and methods to Lua.

How tolua works

(1)创建a package file (a C/C++ cleaned header file) listing the constants, variables, functions, classes, and methods we want to export to the Lua environment.

(2)parses this file and creates a C/C++ file that automatically binds the C/C++ code to Lua. 

(3) accesed from Lua

How to use toLua

由(1)an executable (2)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.

tolua -o myfile.c myfile.pkg

tolua -n pkgname -o myfile.c myfile.pkg

when using C++, we can opt for automatic initialization

tolua -a -n pkgname -o myfile.c myfile.pkg

automatic initialization sometimes does not work

也可以调用tolua_pkgname_close(void);解绑

可以使用-H选项将open与close操作导出到头文件中。

void tolua_restorestate (void);

Basic Concepts

package file may include other package file, use $<include_file>

Basic types

char int float double     ->       number

char*       ->              string

void*       ->              userdata

tolua ignores const modifier

Functions in C/C++ can also manipulate Lua objects explicitly.

lua_Object也是一种基本类型。

User defined types

非Basic Types均为用户自定义类型，are mapped to tagged userdata type in Lua.

Lua can only store pointers to 自定义类型。

NULL and nil

Typedefs

必须使用之前声明

typedef double real;

Including real header files

$#include "header1.h"

可以使用C/C++支持的注释方式进行注释。

Binding constants

(1) define's

#define NAME [VALUE]

(2) enum's

enum {

NAME1[=VALUE1],

NAME2[=VALUE2]

};

Binding external variables

[extern] type var;

double v[10];//Lua中下标从1开始

Binding functions

无参数时加void

Arrays

change to table

void func (int n, int m, double image[n*m]);

Overloaded functions

接受

但是只会根据参数转换后的Lua类型进行判断

Default parameters values

void func(lua_Object lo = TOLUA_NIL)

void func(int a[5] = 0);

Multiple returned values

tolua uses feature of Multiple returned values to simulate values passed by references

void swap (double* x, double* y);

or

void swap (double& x, double& y);

x, y = swap (x, y)

Binding struct fields

typdef struct [name] {

int x[10];

int y[10];

} Example;

Binding classes and methods

Specifying inheritance

class classname: public basename

{

/* class definition*/

};

Specifying exported memebers and methods

Constructors are called as static methods, named new,

Destructors are called as a conventional method called delete

virtual keyword has no effect in the package file

example:  

class Point {

static int n;

double x;

double y;

static char* className(void);

Point (void);

Point (double px, double py);

~Point(void);

Point add (Point& other);

};

overloaded operators

operator+ - * / < > <= >=

operator[]

example:

double operator[](int index);

Module definition

module name

{

#define N

extern int var;

int func (...);

}

Renaming constants, variables and functions

#define CNAME @ ivar;

void cfunc @ ifunc (...);

class cannot be renamed, because they represent types in C.

Storing additional fields

based on table

Exported utility functions

tolua uses itself to export some utility functions to Lua, including its object-oriented framework.

tolua.using(table)

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.

tolua.type(var)

returns a string representing the object type

tolua.tag("type")

returns type corresponding tag number

tolua.foreach(object)

this function filters all fields starting with a dot, not passing them to the provided callback function.

tolua.cast(object, "typename")

Returns the object "casted" to the given type. The object must represent an user type, otherwise return nil.

tolua.takeownership(object)

asks tolua 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执行错误产生。

tolua.class(table, base = nil)

the created class can inherit from a base class, previously created.

tolua.instance(table, class)

Sets the given table to be an instance of the given class.

example:

--define a Point class

classPoint = {x=0, y=0}

tolua.class(classPoint)--set as a class

--define print function

function classPoint:print()

    print (self.x, self.y)

end

-- define add method

function classPoint:add(p2)

    return Point{x=self.x+p2.x, y=self.y+p2.y}

end

-- define a Point constructor

function Point (p)

    tolua.instance(p, classPoint) -- set as an instance of classPoint

    return p

end

-- define a Color Point class

classColorPoint = {color = 'black' }

tolua.class(classColorPoint, classPoint) -- set as class inheriting from classPoint

-- define class methods

function classColorPoint:print()

    print(self.x, self.y, self.color)

end

-- define Color Point constructor

function ColorPoint(p)

    tolua.instance(p, classColorPoint) -- set as an instance of classColorPoint

    return p

end

-- some valid codes would then be

p = Point{ x= 1}

q = ColorPoint{x=2, y =3, color =2)

r = p:add(q)

r:print()

Embedded Lua code

tolua allows us to embed Lua code in the C/C++ generated code.

$[

embedded Lua code

...

$]

（想与博主一起在技术上成长，请移步 knowthendo.cn）