Blitz Lua 函数接口

wiki

BlitzLua 函数接口

“函数接口”直接将 BlitzMAX 函数映射到 Lua 对应函数。给定 BlitzMAX 模块的所有函数都驻留在一个 Lua 表中，其名称与底层模块相同：例如，在 Lua 中，BlitzMAX 函数 createWindow 位于模块 BRL.MaxGUI 中，由 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