Blitz Lua 函數介面

wiki

BlitzLua 函數介面

「函數介面」直接將 BlitzMAX 函數對應到 Lua 對應函數。給定 BlitzMAX 模組的所有函數駐留在名稱是底層模組名稱的 Lua 表格中：例如，在 Lua 中，在模組 BRL.MaxGUI 找到的 BlitzMAX 函數 createWindow 會由 brl.maxgui.createWindow 複製（其中 brl 是全域表格）。選用的「import」機制讓給定模組的所有函數變成全域變數，移除必須加上其模組名稱作為開頭的需求。

MaxGuiExample 包含兩個簡單範例展示如何使用這個介面。

命名慣例

由於 Lua 是一種大小寫敏感的語言（而 BlitzMAX 不是），因此套用以下命名慣例

• 所有模組名稱都是小寫
• 保留 BlitzMAX 函數名稱的大小寫 - 但有以下例外
  • 以動詞或形容詞開頭的名稱以小寫字母開頭
  • 所有其他名稱都以大寫字母開頭

如果有任何不確定性，只要考慮此封裝中函數參考的部分即可。

參數處理和類型轉換

Lua 函數參數等於對應 BlitzMAX 函數的參數，尊重任何預設值（例如，對應 Lua 引數可能為 nil）。類型會如下轉換

• BlitzMAX 字串會以 C 字串傳遞到 Lua - 反之亦然（這目前禁止使用 16 位元字元組，而且將來可能會變更。目前採用這種方式是為了避免出現寬字元問題，這些問題已回報至 MaxGUI）
• 數字 BlitzMAX 值總是傳遞到 Lua 做為雙精度浮點數 - 反之亦然（即使範圍在 -9007199254740994...+9007199254740994 [1] 的「長整數」也運作良好）
• 每當 BlitzMAX 預期或傳回邏輯值時，對應 Lua 值必須（或會）為「布林值」類型
• 每當 BlitzMAX 預期或傳回位元組陣列時，對應 Lua 值必須（或會）為「字串」類型
• BlitzMAX 物件會傳遞為「輕量使用者資料」（但請閱讀以下註解！）

此外,

• 「變數參數」會除了主要函數傳回值（如果存在的話）以外，接著依序（就像它們出現在參數清單中的順序一樣）傳回
• 每當 BlitzMAX 預期給定類型（除了位元組以外）的陣列時，Lua 必須提供數值編號表格與具備必要元素類型的元素
• 每當 BlitzMAX 原本傳回值陣列（不是位元組類型），對應介面函數會將「解壓縮」值清單傳遞到呼叫 Lua 腳本

請注意細節：因為 BlitzMAX 自己有「垃圾回收」，所以任何 BlitzMAX 物件都必須明指參考（在 BlitzMAX 本身內部！）才不會在建立後不久就被移除。這是由 BlitzMAX「句柄」（特定物件的一一代表）在內部執行 - 實際上，傳遞給 Lua 的是物件的句柄，而不是物件本身。因此，現在是 Lua 的責任要「摧毀」任何不再需要的 BlitzMAX 物件。所以，每個 BlitzMAX「createXXX」函式（或「loadXXX」或類似）用於建立 XXX 型別的物件，現在也都有一個「destroyXXX」對應函式（在同一個模組內）必須呼叫來移除那個物件。

任何 BlitzMAX 常數也都在定義模組所屬的表格內使用 - 它​​們的名稱以大寫保留（例如 brl.event.EVENT_WINDOWCLOSE）就像在 BlitzMAX 中一樣。

--AndreasRozek