Lua は require( modname ) で外部モジュールの機能を取り込んで、利用することができます。

ここで require は指定された外部モジュールを検索する際、次のように処理を行ないます。

• 次のローダーを使って、 modname のロードを試みます。

  • preload
  • Lua
  • C

• この ローダーに modname を渡し、そのモジュール名に合致するモジュールをロードさせます。

  • preload

    • package.preload[ modname ] の値を参照し、値が関数であった場合その関数を返します。

      • package.preload を編集しても、ローダーの変更はできません。
      • Lua から参照できるように提供されています。

  • lua

    • package.path に格納されているパスを利用して Lua スクリプトを loadfile します。

  • C

    • package.path に格納されているパスを利用して C モジュールをロードします。
    • 見つかったモジュールから関数名が "luaopen_%s", modname の関数をロードします。
    • C モジュール関数のロード方法は OS や Lua をホストしている環境によって異なります。
• 上記処理を preload, lua, C の順に行ない、modname モジュールがロードできるまで繰り返します。
• ロードした関数に対し、 modname を渡して実行します。
• 実行結果を require の戻り値とします。

C の関数は、上記で示すように preload, Lua の次に検索されロードされます。

上記で示した様に、関数名が "luaopen_%s", modname 関数がロードされコールされます。 例えば require( 'hoge' ) とした場合 hoge モジュールの luaopen_hoge() がロードされ実行されます。

ここで、 luaopen_hoge() も、上記で説明した通り次の型で定義する必要があります。

int luaopen_hoge( lua_State * pLua )

この関数が Lua VM のスタックに Push した値が、 require の戻り値になります。

例えば、フィールド(func1,func2)に関数を格納するテーブルを Push することで、Lua の標準ライブラリのように複数の関数を提供することができます。

local lib = require( 'module' )
lib.func1()
lib.func2()

static int lib_func1( lua_State * pLua );
static int lib_func2( lua_State * pLua );
static const luaL_Reg lib[] = {
  {"func1", lib_func1},
  {"func2", lib_func2},
  {NULL, NULL}
}
int luaopen_hoge( lua_State * pLua )
{
  luaL_newlib( pLua, lib );
  return 1;
}

前述した通り Lua の関数コールは、引数をスタックに Push してから関数を実行します。 また、関数の戻り値はスタックに Push します。

local function func( arg1, arg2 )
  return arg1 + 1, arg2 + 2
end
local value1, value2 = func( 10, 20 )

例えば上記の Lua の func 関数を C で書く場合、次のようになります。

static int lib_func( lua_State * pLua ) {
  int arg1 = luaL_checkinteger( pLua, 1 ); // 引数 1 の取得
  int arg2 = luaL_checkinteger( pLua, 2 ); // 引数 2 の取得
  lua_pushinteger( pLua, arg1 + 1 ); // 戻り値 1 設定
  lua_pushinteger( pLua, arg2 + 2 ); // 戻り値 2 設定
  return 2; // 戻り値 2 個
}

引数の取得、戻り値の設定は、値の型毎にアクセス関数が提供されています。

ユーザデータは Lua から生成することはできません。 必ず C で生成する必要があります。

C でユーザデータを生成するには、次の関数を実行します。

void * lua_newuserdata( lua_State * pLua, size_t size );

使い方は malloc() と似ています。 ただし、malloc() は free() で解放するのに対し、 lua_newuserdata() で生成した領域は GC によって解放されます。

なお lua_newuserdata() は、ユーザデータを生成しスタックに Push します。

Lua は、C から受け取ったユーザデータ内に何が格納されているかアクセスする関数を標準では提供していません。 ユーザデータにアクセスする関数を、ユーザデータを生成した C 側で用意する必要があります。

例えば Lua の file オブジェクトは、ファイルハンドルのユーザデータにアクセスするための file:read() や file:close() などのメソッドを提供しています。

なお、ユーザデータはメタデータを設定することが出来ます。

Lua の file オブジェクトは、メタデータを利用して file:read() や file:close() などのメソッドを提供しています。

ユーザデータにメタデータを設定することによって、C 側のデータを Lua からオブジェクト指向でアクセスすることが出来ます。

Lua の file オブジェクトの実装方法を参考に、ユーザデータの使用方法を説明していきます。

Lua の file オブジェクトのユーザデータは、次の構造体を生成しています。

typedef struct luaL_Stream {
  FILE *f;
  lua_CFunction closef;
} luaL_Stream;
typedef luaL_Stream LStream;

ここで f は、アクセス対象のファイルハンドルです。 closef は、 file:close() 時に実行する関数ポインタです。 io.open(), io.popen() で file:close() 処理が異なるため、関数ポインタで切り替えられるようにしています。

この構造体のユーザデータを生成し、メタデータを設定します。

static LStream *newprefile (lua_State *L) {
  LStream *p = (LStream *)lua_newuserdata(L, sizeof(LStream));
  p->closef = NULL;
  luaL_setmetatable(L, LUA_FILEHANDLE);
  return p;
}

ここで luaL_setmetatable(L, LUA_FILEHANDLE) は、スタックトップのデータにメタテーブル LUA_FILEHANDLE をセットします。

ちなみに LUA_FILEHANDLE は文字列 "FILE*" です。

メタテーブル LUA_FILEHANDLE は、次のように事前に生成しておきます。

static void createmeta (lua_State *L) {
  luaL_newmetatable(L, LUA_FILEHANDLE);
  lua_pushvalue(L, -1);
  lua_setfield(L, -2, "__index");
  luaL_setfuncs(L, flib, 0);
  lua_pop(L, 1);
}

まず luaL_newmetatable(L, LUA_FILEHANDLE) で空のメタテーブル LUA_FILEHANDLE を生成します。 次に __index フィールドに自分自身をセットします。 これは LStream ユーザデータから、このメタテーブルで定義している関数にアクセスできるようにするためです。 具体的に言うと file:close() を実現できるようにしています。 次に luaL_setfuncs(L, flib, 0) で、このメタテーブルのフィールドにメソッドを定義します。 ここで flib は、次のように定義されています。

static const luaL_Reg flib[] = {
  {"close", io_close},
  {"flush", f_flush},
  {"lines", f_lines},
  {"read", f_read},
  {"seek", f_seek},
  {"setvbuf", f_setvbuf},
  {"write", f_write},
  {"__gc", f_gc},
  {"__tostring", f_tostring},
  {NULL, NULL}
};

最後の luaL_pop() は、スタックを元の状態に戻すために実行しています。

なお、 上記 flib で重要なものがあります。 それは __gc です。

__gc は、 GC によって値を解放する前に呼び出されます。

file オブジェクトの場合は、 f_gc() で close 処理を行なっています。 これにより、ファイルの close 漏れを防止しています。

ユーザデータには、次の 2 種類あります。

• フルユーザデータ

  • luaL_newmetatable() で生成するユーザデータ

• ライトユーザデータ

  • lua_pushlightuserdata() で Push するユーザデータ

フルユーザデータにはメタテーブルを設定できますが、 ライトユーザデータにはメタテーブルを設定できません。

また、ライトユーザデータは GC の対象になりません。

これらの特徴から、ライトユーザデータは Lua がリソース管理しないデータで、フルユーザデータは Lua がリソース管理するデータであると言えるます。

なお、上記 2 種類のユーザデータは Lua 内部では異なるタイプとして扱いますが、 Lua スクリプトからは同じ "userdata" 型として扱われます。

C からは、上記 2 種類のユーザデータを別々の型として扱えますが、型名を取得する関数 lua_typename() はどちらも同じ "userdata" になります。

• ver 5.2

  • 指定インデックスの値(文字列か数値)を文字列に変換した結果を返します。
  • このとき、指定インデックスに格納されている値そのものを文字列に変換した値に書き換えます。

• ver 5.3

  • 指定インデックスの値(文字列か数値)を文字列に変換した結果を返します。
  • このとき、変換した結果をスタックに push します。
  • このとき、指定インデックスに格納されている値は元のままです。

ver 5.2 の仕様は、かなり危険な動作なので仕様変換するのも分からなくはないですが、 かなり厄介な仕様変更です。

リファレンスにも記載がありますが、 lua_next() 中のキーに対する lua_tolstring() は危険です。 ver 5.2 のでは、値が数値だった場合その値そのものを文字列に変換してしまいます。 lua_next() では、キーを次の列挙の情報に利用するので、 文字列に変換されてしまうとマトモに列挙することができなくなってしまいます。

luaL_Buffer への add 処理 ( luaL_addstring 等)は注意が必要です。 add 処理で luaL_Buffer の内部バッファを拡張する場合、add 処理内でスタックにユーザデータを積みます。 これにより、スタックが変更になります。 luaL_pushresult() を実行すると、 add 処理で Push でしたユーザデータは Pop され、 最終結果の文字列が Push されます。

このような処理であるため、例えば次のような処理を書くと、スタックの状態が保証されません。

  luaL_addstring( &buffer, "a" );
  lua_pushstring( pLua, "b" );
  luaL_addstring( &buffer, "c" );
  lua_pushstring( pLua, "d" );
  luaL_pushresult( pLua, &buffer );

上記処理を見ると、このときのスタックは次のようになることを期待していると思います。

しかし、実際にはどうなるか保証されません。