天天看點
傳回

tolua++參考手冊(翻譯一)tolua++使用

原文位址： http://www.codenix.com/~tolua/tolua++.html

     譯者注：在網上貌似沒有對應的tolua中文版文檔，故心血來潮，翻譯了第一部分：tolua使用。第一次翻譯，出了很多錯誤。可能還潛在很多的錯誤，建議和原版一起閱讀。如果有錯誤，希望各位看官指出，謝謝。

Tolua++是tolua的更新版，是把C/C++和lua代碼結合使用的一種工具。tolua++包括一些來自C++的新功能，如：

  • 支援std::string，并将其作為一種基本類型
  • 支援class template

當然，還有一些新的特點和bug的修複。

Tolua的使用大大簡化了C/C++和lua的代碼一體化。基于幹淨的頭檔案（或者擴充的頭檔案），tolua會自動生成相關的代碼供lua通路C/C++使用。

使用Lua的API和标記方法（tag method facilities），tolua可以把C/C++裡的常數，變量，函數，類和方法映射到lua。

這本手冊是tolua++ 1.0版本，針對Lua5.0以上，基于tolua5.0。如果使用舊版本，請檢視相容性的詳細資料。

       以下各節描述如何使用tolua 。如果你發現錯誤，或者有建議和意見，請與我們聯系。

  • Howtolua works
  • How to usetolua
  • Basic Concepts
  • Binding constants
  • Binding external variables
  • Binding functions
  • Binding struct fields
  • Binding classes and methods
  • Binding properties
  • Class Templates
  • Module definition
  • Renaming constants, 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
  • Availability

How tolua works

要使用tolua，我們需要建立package檔案，C/C++幹淨的頭檔案（cleaned header file），隻列出所有我們希望暴露給lua使用的常數，變量，函數，類和方法。然後tolua剖析這個檔案，并自動建立C / C + +檔案，該檔案會自動把C/C++的代碼綁定到Lua。當我們的程式連結到這個檔案時，我們就能從Lua通路對應的C/C++代碼。

Package檔案可以包括正常頭檔案，其他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代碼裡，我們能夠通路對應的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提供通路對應代碼。是以，以下的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++頭檔案，而是一種幹淨的版本（cleanedversion）。Tolua并不執行一個完整的剖析解釋的C/C++代碼，隻是解析一些聲明，用來描述暴露給lua功能的聲明（it understands a few declarations that are used to describe the features that are to be exported to Lua.）。

通常頭檔案可以包括進packages檔案裡，tolua會提取對應的代碼用于解析對應的頭檔案(seeBasic Concepts).。

How to use toLua

Tolua由兩部分代碼組成：可執行程式和靜态庫（an executable and a library）。可執行程式用于解析，從package檔案讀入，然後輸出C/C++代碼，該代碼為lua提供通路C/C++的方法。如果package檔案是與C++類似的代碼（例如包括類的定義），就會生成一份C++代碼。如果package檔案是與C類似的代碼（例如不包括類），就會生成一份C代碼。Tolua接收一系列選擇（tolua accepts a set of options）。運作“tolua -h”顯示目前可接收的選擇。例如，要解析一個名為myfile.pkg生成一個名為myfile.c的捆綁代碼，我們需要輸入：

tolua -o myfile.c myfile.pkg

産生的代碼必須被應用程式生成和連結，才能提供給Lua進行通路。每個被解析的檔案會生成一個package暴露給Lua。預設情況下，軟體包的名稱是根輸入檔案名稱（ myfile的例子），使用者可以指定一個不同的名稱給package：

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

package還應當明确初始化。我們需要聲明和調用初始化函數，從化我們的C/C++代碼初始化package。初始化函數被定義為：

int tolua_pkgname_open (lua_State*);

其中pkgname是被綁定package的名字。如果我們使用的是C++，我們可以選擇自動初始化：

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

在這種情況下，初始化函數會自動調用。然而，如果我們計劃使用多個Lua，自動初始化就行不通了，因為靜态變量初始化的順序在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庫裡面的函數。是以，這個庫同樣需要被連結到應用程式中。同樣，tolua.h需要加入編譯生成代碼。應用程式無需綁定任何package檔案也可以使用tolua的面向對象架構(seeexported utility functions)。在這種情況下，應用程式必須調用tolua初始化函數（此函數被稱為任何package檔案初始化功能） ：

int tolua_open (void);

Basic Concepts

第一步是使用tolua建立package檔案。從真正的頭檔案開始，我們重新将想要暴露給lua的特性轉換成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還額外的可選參數後的檔案名（ifile also takes extra optional parameters after the filename），例如：

$ifile "widget.h", GUI

$ifile "vector.h", math, 3d

ifile的預設行為是包括整個檔案的原樣。但是，該檔案的内容和額外的參數在被納入package之前通過include_file_hook函數進行處理 (seeCustomizing tolua++ for more details)。

ToLua lua constants object class include string
上一篇: tolua筆記《03》- C#讀取調用Lua腳本檔案
下一篇: ToLua 筆記

繼續閱讀