Basic types

Tolua自動將C/C++的基本類型映射到lua的基本類型。因此，char, int, float, 和 double映射到Lua的number類型；char *映射到string；void *映射到userdata。Types may be preceded by modifiers (unsigned, static, short, const, etc.);然而，認識到tolua忽略了用于修飾基本類型的const（be aware that tolua ignores the modifier const if applied to basic types）。因此，如果我們傳遞一個基本類型的常數（conston）給Lua而后Lua再把該數返回給C/C++，這時非常量到常量之間的轉換會在后臺悄悄的進行。

C/C++的函數也可以明確的使用Lua的對象。因此lua_Object也被認為是一個基本類型。所以，任何的Lua都滿足這一要求。

新的tolua + + ：在C++中的string類型同樣被認為是基本類型，會被當作值創遞給lua(使用c_str()方法)。這個功能可以使用命令行-S進行關閉。

User defined types

所有在package文件里的其他類型都會被認為是用戶自定義類型。它們會映射到Lua的userdata類型。Lua只能存儲指向用戶定義類型的指針；但是，tolua會自動產生必要的安排來處理引用和值。例如，如果一個函數或方法返回一個用戶定義類型的值，當這個值返回lua的時候，tolua會分配一個克隆對象，同時會設置垃圾收集標記，用于在Lua不再使用該對象時自動釋放。

對于用戶定義類型，常量是被保留的。因此將非常量用戶定義類型數據作為常量參數傳遞給一個函數，會產生類型不匹配的錯誤。

NULL and nil

C/C++ 的NULL或0指針映射到Lua的nil類型；反之，nil可能會指向任何可能的C/C++指針（conversely, nil may be specified wherever a C/C++ pointer is expected.）。

Typedefs

Tolua還接受package文件簡單的typedef（tolua also accepts simple typedef's inside the package files.）。任何一種類型當定義的時候，tolua會將其映射到基本類型。它們是很有用的因為一些package會將C/C++類型重新定制轉為它們的類型。例如，一個package可以定義類型real來表示一個double類型。在這種情況下，real可用于被lua解析的指定類型變量的package文件（real can be used to specify the variable types inside the package file interpreted by tolua），但只有我們在使用之前包括下面的定義：

typedef double real;

否則，real將會被解釋為用戶定義類型而不會映射到Lua的number類型。

Including real header files

在package文件中，我們必須指定對應的頭文件，這些頭文件包含著我們要訪問的常數，變量，函數和類。在package文件里任意以$ (except $[hclp]file, $[ , and $] lines)開頭的一行會被無修過的插入到生成的綁定到C/C++的代碼，但是會消除$號本身。我們用這個特性類引入真正的頭文件。所以，我們的頭文件一般會設置$作為開始，指定對應要引用的文件，那些package需要的文件。

 /* 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.

還注意到，文件中的$cfile或$hfile不需要使用該方式，這個tolua自動完成。

在下面的章節，我們將介紹如何指定我們想要綁定到lua的C/C++代碼。這些格式簡單并且符合C/C++的聲明方式。

Binding constants

Tolua支持兩種用于綁定常數的方式：define's和enum's。對于define's的一般格式是：

 #define NAME [ VALUE ]

上面的VALUE是可以選擇的（The value, as showed above, is optional）。如果這樣的代碼出現在要被解析的文件中，tolua會將NAME作為Lua的全局變量，該全局變量是C/C++的常量，值為VALUE。只接受數字常量。

新的tolua++：所有其他預處理指令會被忽略。

對于enum's的一般格式是：

 enum {

   NAME1 [ = VALUE1 ] ,

   NAME2 [ = VALUE2 ] ,

   ...

   NAMEn [ = VALUEn ]

 };

同樣的，tolua創建一系列全局變量，命名為NAMEi，對應values。

Binding external variables

全局外部變量同樣可以暴露出來。在已清理的頭文件（cleaned header file），他們都指定為：

 [extern] type var;

Tolua將這種聲明綁定到Lua的全局變量中。因此，在Lua里，我們可以很自然的訪問C/C++變量。如果變量不是常數，我們還可以在Lua賦予該變量新的值。全局數組同樣可以被綁定到Lua里。數組可以是任意類型。數組對應的Lua類型是table，對應以數字作為下標（indexed with numeric values）；但是，要注意的是Lua中下標1對應C/C++中的下標0。數組一定要定長（be pre dimensioned）。例如

double v[10];

新的tolua++：外部變量可以使用tolua_readonly修飾。(see Additional Features)

Binding functions

函數也指定為傳統的C/C++聲明：

 type funcname (type1 par1[, type2 par2[,...typeN parN]]);

返回類型可以是void，表示沒有返回值。函數也可以沒有參數。在這種情況下，void可能被指定到函數的參數列表里（specified in the place of the list of parameters.）。參數類型必須遵循發布（posted）的規則。Tolua創建一個Lua函數綁定C/C++函數。當Lua調用函數時，參數類型必須對應C/C++的類型，否則tolua會產生一個錯誤并報告錯誤參數。如果參數名是省略的，tolua會自定命名，但是類型必須是基本類型或者是以前使用過的用戶定義類型。

Arrays

Tolua同時支持以數組作為參數的函數或方法。最每秒的事情是，當數組映射到lua的table后，當C/C++函數改變了數組里面的值，會實時更新到lua的table中。

數組的大小必須是事先定義好多。例如：

void func (double a[3]);

在tolua里這是一個合法的函數聲明，在lua里調用這個函數方法如：

p = {1.0,1.5,8.6}
func (p)

數組長度不一定是一個常數表達式；還可以是在運行過程中能計算出結果的表達式。例如：

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

這個是合法的。因為表達式n*m在函數的綁定范圍（expression n*m is valid in the binding function scope）。但是必須考慮到，tolua使用動態分配的方式綁定函數，這一方式會降低性能。

盡管尺寸匹配是必須的，但是更重要的是意識到，所有數組傳遞給實際C/C++函數是，是使用局部變量的方式進行傳遞。因此，如果C/C++函數想要保留這個數組供以后使用，這段代碼可能不會如想象那樣工作。

Overloaded functions

Tolua還支持重載函數。區分兩個同名函數的方法是基于映射到lua的參數類型。因此

void func (int a);
void func (double a);

在C/C++中這代表兩個不同的函數，然而在tolua里它們是同一個函數，因為int和double類型都映射到number。

另一個棘手的情況時，當遇到指針時。假設：

void func (char* s);

 void func (void* p);

 void func (Object1* ptr);

void func (Object2* prt);

盡管在C++中這是4個不同的函數，但是映射到Lua里面的聲明：

func(nil)

重要的是，運行的時候tolua決定那個函數被調用，嘗試映射到那些提供的函數。Tolua第一次嘗試調用最后一個指定的函數；如果失敗，tolua接著嘗試前一個函數。這個過程一直持續到找到一個能成功運行的代碼或者到第一個函數。因為這個原因，不匹配的錯誤信息的發出，總是基于第一個函數的規格（the mismatching error message, when it occurs, is based on the first function specification）。當性能很重要時，我們應該把最常用的函數放在最后一個。

Tolua支持C的重載函數。（see Renaming for details.）

Default parameter values

最后的函數參數可以帶有默認值。因此，如果函數調用時提供的參數不足，默認值會自動使用。該格式指定的默認值與C++里面的是一致的。

type funcname (..., typeN-1 parN-1 [= valueN-1], typeN parN [= valueN]);

toLua執行此功能無需使用任何C++的機制;因此，同樣支持綁定C的函數。

我們同樣可以指定數組的默認值（沒有辦法指定一個默認值為數組本身）。例如：

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

把數組的所有值設為0.因此，這個函數可以直接在lua調用無需初始化table。

對于lua對象類型(lua_Object)，tolua定義了一個常量用來指定nil為默認值：

void func (lua_Object lo = TOLUA_NIL);

新的tolua++ ：C++類的構造是有效的默認參數。例如：

void set_color(const Color& color = Color(0,0,0));

Multiple returned values

在lua中函數可以返回任意個數的值。Tolua使用這個特性來模擬值傳遞。如果一個函數的參數指定為一個指針或引用的一個基本類型或一個指針或引用的一個指針一個用戶定義的類型，tolua接受對應類型的傳入和返回，除了常規的函數返回，還可以通過參數更新的形式。

例如，考慮用于交換數值的C函數：

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

or

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

如果這函數在package文件中聲明，tolue綁定該函數為輸入兩個參數，返回兩個值。所以，正確的Lua代碼為：

x,y = swap(x,y)

如果輸入值不使用，lua會自動使用默認參數值調用函數而不需要指定它們。

void getBox (double* xmin=0, double* xmax=0, double* ymin=0, double* ymax=0);

In Lua:

xmin, xmax, ymin, ymax = getBox()

如果是用戶定義類型，則以下面為例：

void update (Point** p);

or

void update (Point*& p);

Binding struct fields

用戶定義類型可以很好的被tolua綁定。對于每一個變量或函數類型，不符合基本類型， tolua自動創建一個標簽的用戶數據代表的C/C++類型。

如果類型對應結構，Lua可以通過下標直接訪問結構里面的內容，indexing a variable that holds an object of such a type. 在C代碼，這些類型通常是用typedef定義的：

 typedef struct [name] {

    type1 fieldname1;

    type2 fieldname2;

    ...

    typeN fieldnameN;

 } typename;

如果這段代碼正在被插入到package文件中，tolua允許任何擁有類型對象名的對象反問任何索引列出的變量的字段名字（If such a code is inserted in the package file being processed, tolua allows any variable that holds an object of type typename to access any listed field indexing the variable by the field name.）。例如，如果var持有對象, var.fieldnamei可以訪問fieldnamei里面的東西。

塊內的數組同樣被映射。

typedef struct {
int x[10];
int y[10];
} Example;

Binding classes and methods

Tolua支持C++的類定義。事實上，tolua能很自然的處理單一繼承和多態性。以下各小節將會介紹什么可以暴露給lua，在類定義的時候（The subsections below describe what can be exported by a class definition.）。