原文地址： http://www.codenix.com/~tolua/tolua++.html
譯者注：在網(wǎng)上貌似沒有對應(yīng)的tolua中文版文檔，故心血來潮，翻譯了第一部分：tolua使用。第一次翻譯，出了很多錯誤?？赡苓€潛在很多的錯誤，建議和原版一起閱讀。如果有錯誤，希望各位看官指出，謝謝。
Tolua++是tolua的升級版，是把C/C++和lua代碼結(jié)合使用的一種工具。tolua++包括一些來自C++的新功能，如：
- 支持std::string，并將其作為一種基本類型
- 支持class template
當(dāng)然，還有一些新的特點(diǎn)和bug的修復(fù)。
Tolua的使用大大簡化了C/C++和lua的代碼一體化?；诟蓛舻念^文件（或者擴(kuò)展的頭文件），tolua會自動生成相關(guān)的代碼供lua訪問C/C++使用。
使用Lua的API和標(biāo)記方法（tag method facilities），tolua可以把C/C++里的常數(shù)，變量，函數(shù)，類和方法映射到lua。
這本手冊是tolua++ 1.0版本，針對Lua5.0以上，基于tolua5.0。如果使用舊版本，請查看兼容性的詳細(xì)資料。
以下各節(jié)描述如何使用tolua 。如果你發(fā)現(xiàn)錯誤，或者有建議和意見，請與我們聯(lián)系。
How tolua works
要使用tolua，我們需要創(chuàng)建package文件，C/C++干凈的頭文件（cleaned header file），只列出所有我們希望暴露給lua使用的常數(shù)，變量，函數(shù)，類和方法。然后tolua剖析這個文件，并自動創(chuàng)建C / C + +文件，該文件會自動把C/C++的代碼綁定到Lua。當(dāng)我們的程序鏈接到這個文件時(shí)，我們就能從Lua訪問對應(yīng)的C/C++代碼。
Package文件可以包括常規(guī)頭文件，其他Package文件，以及lua文件。
讓我們先以一些例子。如果我們指定下列C頭文件輸入到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);
這段代碼綁定到Lua，會自動生成一個C文件。因此，在Lua代碼里，我們能夠訪問對應(yīng)的C代碼，例如（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
...
另外，考慮一個C++頭文件：
#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);
};
如果這個文件是用來加載到tolua的，一個C++文件會自動生成，為Lua提供訪問對應(yīng)代碼。因此，以下的Lua代碼是有效的：
...
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()
...
Package文件傳給tolua的不是真正的C/C++頭文件，而是一種干凈的版本（cleaned version）。Tolua并不執(zhí)行一個完整的剖析解釋的C/C++代碼，只是解析一些聲明，用來描述暴露給lua功能的聲明（it understands a few declarations that are used to describe the features that are to be exported to Lua.）。
通常頭文件可以包括進(jìn)packages文件里，tolua會提取對應(yīng)的代碼用于解析對應(yīng)的頭文件(see Basic Concepts).。
How to use toLua
Tolua由兩部分代碼組成：可執(zhí)行程序和靜態(tài)庫（an executable and a library）?？蓤?zhí)行程序用于解析，從package文件讀入，然后輸出C/C++代碼，該代碼為lua提供訪問C/C++的方法。如果package文件是與C++類似的代碼（例如包括類的定義），就會生成一份C++代碼。如果package文件是與C類似的代碼（例如不包括類），就會生成一份C代碼。Tolua接收一系列選擇（tolua accepts a set of options）。運(yùn)行“tolua -h”顯示當(dāng)前可接收的選擇。例如，要解析一個名為myfile.pkg生成一個名為myfile.c的捆綁代碼，我們需要輸入：
tolua -o myfile.c myfile.pkg
產(chǎn)生的代碼必須被應(yīng)用程序生成和鏈接，才能提供給Lua進(jìn)行訪問。每個被解析的文件會生成一個package暴露給Lua。默認(rèn)情況下，軟件包的名稱是根輸入文件名稱（ myfile的例子），用戶可以指定一個不同的名稱給package：
tolua -n pkgname -o myfile.c myfile.pkg
package還應(yīng)當(dāng)明確初始化。我們需要聲明和調(diào)用初始化函數(shù)，從化我們的C/C++代碼初始化package。初始化函數(shù)被定義為：
int tolua_pkgname_open (lua_State*);
其中pkgname是被綁定package的名字。如果我們使用的是C++，我們可以選擇自動初始化：
tolua -a -n pkgname -o myfile.c myfile.pkg
在這種情況下，初始化函數(shù)會自動調(diào)用。然而，如果我們計(jì)劃使用多個Lua，自動初始化就行不通了，因?yàn)殪o態(tài)變量初始化的順序在C++里沒有定義。
Optionally, the prototype of the open function can be outputted to a header file, which name is given by the -H option.
Tolua生成的綁定代碼使用了一系列tolua庫里面的函數(shù)。因此，這個庫同樣需要被鏈接到應(yīng)用程序中。同樣，tolua.h需要加入編譯生成代碼。應(yīng)用程序無需綁定任何package文件也可以使用tolua的面向?qū)ο罂蚣?/span>(see exported utility functions)。在這種情況下，應(yīng)用程序必須調(diào)用tolua初始化函數(shù)（此函數(shù)被稱為任何package文件初始化功能） ：
int tolua_open (void);
Basic Concepts
第一步是使用tolua創(chuàng)建package文件。從真正的頭文件開始，我們重新將想要暴露給lua的特性轉(zhuǎn)換成tolua可以理解的格式。
Including files
一個package文件可以包括其他的package文件。一般的格式是：
$pfile "include_file"
一個package文件同樣可以包括一般的C/C++頭文件，使用hfile或cfile指令：
$cfile "example.h"
在這種情況下， tolua將提取的代碼封閉之間tolua_begin和tolua_end ，或tolua_export的一條直線上。以這個C++頭為例思考：（注：這里并不是每個頭文件都需要使用這些注釋來告訴tolua要加入這些代碼，僅僅是對于package文件包括的頭文件而言）
#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 function set_number is left outside of the package that includes this header.
最后，lua文件可以被包括在package文件里，使用$lfile:
$lfile "example.lua"
新的tolua++：自1.0.4版本以來的tolua++，提供了一個額外的方式可以包括源文件，使用ifile：
$ifile "filename"
ifile還額外的可選參數(shù)后的文件名（ifile also takes extra optional parameters after the filename），例如：
$ifile "widget.h", GUI
$ifile "vector.h", math, 3d
ifile的默認(rèn)行為是包括整個文件的原樣。但是，該文件的內(nèi)容和額外的參數(shù)在被納入package之前通過include_file_hook函數(shù)進(jìn)行處理 (see Customizing tolua++ for more details)。