Rustの堅牢性とパフォーマンス、そしてLuaの柔軟なスクリプティング能力は、多くのアプリケーションで魅力的な組み合わせを提供します。特にゲームエンジンや組み込みシステムでは、コアロジックをRustで実装し、スクリプト可能な部分をLuaで制御することが一般的です。この連携を円滑にするためには、Rustで定義された構造体や関数をLuaから透過的に操作できるようなバインディングメカニズムが必要となります。

本稿では、Rustの構造体をLua環境へ自動的に公開するための手続き型マクロを利用したアプローチについて解説します。これにより、手書きのFFIコードを最小限に抑え、開発効率を大幅に向上させることが可能になります。

目的とする機能

私たちが目指すのは、Rustの構造体をLuaから以下のように操作できる簡潔なインターフェースです。

1. インスタンスの生成: Luaからlocal item = ExportedItem.new()のような形式でRust構造体のインスタンスを生成できる。
2. インスタンスの破棄: Rustがライフタイムを管理する「ライトユーザーデータ」の場合、ExportedItem.release(item)のように明示的に破棄を指示できる。Luaが管理する通常のユーザーデータであれば、GCによって自動的に解放される。
3. プロパティのアクセス: 構造体のフィールドに対して、Luaからitem.idで値の取得、item.id = 123で値の設定ができる。また、item:get_id()やitem:set_id(123)といったメソッド形式でのアクセスも可能にする。
4. インスタンスメソッドの呼び出し: Rustの&selfまたは&mut selfメソッドを、Luaからitem:do_something()のように呼び出せる。
5. 静的メソッドの呼び出し: インスタンスを介さず、クラス名から直接ExportedItem.get_version()のように呼び出せる静的メソッドもサポートする。

実装例

上記目標を達成するための一連のコード例を以下に示します。ここでは、仮のライブラリlua_rs_bindingsとその手続き型マクロlua_rs_derive::LuaExportを使用します。

use lua_rs_derive::LuaExport;
use lua_rs_bindings as lrsb; // 仮のRust-Luaバインディングライブラリ

// Luaに公開する構造体を定義
#[derive(LuaExport, Default)]
#[lua_cfg(name = "ExportedItem")]           // Lua上でのクラス名
#[lua_cfg(lifetime_managed_by_rust)] // ライフタイムをRustが管理する場合（ライトユーザーデータ）
struct LuaExportedItem {
    #[lua_field_prop] // Luaからプロパティとしてアクセス可能にするフィールド
    id: u64,
    #[lua_field_prop]
    description: String,
}

// 構造体に関連するメソッドの実装
impl LuaExportedItem {
    // インスタンスメソッドの例
    fn check_status(&self) {
        println!("Status: OK for item ID {}", self.id);
    }

    // 可変なインスタンスメソッドの例
    fn calculate(&mut self, value: u32) -> u32 {
        self.id as u32 + value
    }
}

fn main() {
    let mut lua_vm = lrsb::LuaRuntime::new(); // Luaランタイムの初期化
    
    // 手続き型マクロによって生成されたバインディング設定関数を呼び出す
    LuaExportedItem::setup_bindings(&mut lua_vm);

    // deriveマクロで自動生成されない、あるいは手動で登録したいインスタンスメソッド
    LuaExportedItem::add_method(&mut lua_vm, "check_status", lrsb::instance_method1(LuaExportedItem::check_status));
    LuaExportedItem::add_method(&mut lua_vm, "get_id_value", lrsb::instance_method1(|obj: &LuaExportedItem| -> u64 {
        obj.id // クロージャを使ったメソッド登録
    }));
    LuaExportedItem::add_method(&mut lua_vm, "calculate_sum", lrsb::instance_method2(|obj: &mut LuaExportedItem, val: u32| -> u32 {
        obj.calculate(val)
    }));

    // 静的メソッドの登録
    LuaExportedItem::add_static_function(&mut lua_vm, "get_library_version", lrsb::static_function0(|| -> String {
        "1.2.3".to_string() // 引数なし、戻り値ありの静的関数
    }));

    // Lua標準ライブラリを開く
    lua_vm.open_default_libs(); 
    
    // Luaスクリプトの実行
    let lua_script = r#"
        print("--- Lua-Rust バインディングテスト ---");
        print("Lua型:", type(ExportedItem)); -- "table" (クラステーブル)
        local item = ExportedItem.new(); -- 新規インスタンス生成
        print("新規アイテム生成 ID:", item.id);
        item.id = 12345; -- プロパティへの値設定
        print("ID設定後:", item.id);
        print("説明取得 (プロパティ):", item.description);
        item.description = "このアイテムはテスト用です"; -- プロパティへの値設定
        print("説明設定後:", item.description);
        
        print("ステータスチェック (メソッド):", item:check_status());
        print("ID値取得 (メソッド):", item:get_id_value());
        print("合計計算 (メソッド):", item:calculate_sum(500));
        
        print("ライブラリバージョン取得 (静的メソッド):", ExportedItem.get_library_version());
        
        -- Rust側でライフタイムが管理される場合、明示的な解放が必要
        ExportedItem.release(item);
        print("アイテム解放済み");
    "#;
    let _: Result<(), lrsb::LuaError> = lua_vm.execute_string(lua_script);
}

機能実装の分解

上記の機能は、Rustの手続き型マクロを駆使して実現されます。

1. #[derive(LuaExport)]: このderiveマクロが、構造体LuaExportedItemに必要なボイラープレートコードを自動生成します。具体的には、Lua上でのインスタンス生成(new)と破棄(release)の関数、そしてプロパティやメソッドの登録ロジックなどが含まれます。
2. #[lua_cfg(name = "ExportedItem")]: この属性は、Luaスクリプト内でこのRust構造体をどのようなグローバル名(ExportedItem)で参照するかを定義します。マクロは、この名前でLuaグローバルテーブルを作成し、そのテーブル内にnewやreleaseなどの関数を登録します。
3. #[lua_cfg(lifetime_managed_by_rust)]: この属性は、Luaでのユーザーデータの管理方法を指定します。この設定により、Rust側でオブジェクトのライフタイムが管理される「ライトユーザーデータ」として扱われます。ライトユーザーデータはLuaのGCの対象外であるため、ExportedItem.release()のような明示的な解放メカニズムが必要になります。この属性がない場合、デフォルトでLuaがGCで管理する通常のユーザーデータとして扱われます。
4. #[lua_field_prop]: 構造体の各フィールドにこの属性を付与することで、そのフィールドがLuaのプロパティとして公開されます。マクロは、対応するフィールドのゲッター (例: item.idまたはitem:get_id()) とセッター (例: item.id = 123またはitem:set_id(123)) のためのコードを自動生成し、Luaのメタテーブルに登録します。

手続き型マクロの実装概要

lua_rs_deriveライブラリの内部では、以下のような処理が行われます。

1. 入力の解析: proc_macro_derive属性を持つ関数が、対象のItemStruct（例: LuaExportedItem）のASTを受け取ります。
2. 設定の抽出: 構造体に付与された#[lua_cfg(...)]属性から、Luaクラス名やライフタイム管理に関する設定を解析します。
3. フィールド情報の処理: 各フィールドについて、#[lua_field_prop]属性が付与されているかをチェックします。この情報に基づいて、プロパティのゲッター/セッターメソッド（例: get_id(&self) -> &u64, set_id(&mut self, val: u64)）を生成するためのコードを準備します。
4. コード生成: 収集した情報と、quote!マクロを使って、最終的なRustコード（impl LuaExportedItem { ... }ブロック）を生成します。これには、setup_bindings関数、プロパティのゲッター/セッターメソッド、そしてLuaメタテーブルへの登録ロジックなどが含まれます。

例として、プロパティのゲッター/セッター生成の簡略化された概念は以下のようになります。

// ... deriveマクロの内部 ...
let property_methods: Vec<_> = fields
    .iter()
    .filter_map(|field| {
        if field.attrs.iter().any(|attr| attr.path().is_ident("lua_field_prop")) {
            let field_ident = field.ident.as_ref().unwrap();
            let ty = &field.ty;
            let getter_name = format_ident!("get_{}", field_ident);
            let setter_name = format_ident!("set_{}", field_ident);
            Some(quote! {
                pub fn #getter_name(&self) -> &#ty {
                    &self.#field_ident
                }

                pub fn #setter_name(&mut self, val: #ty) {
                    self.#field_ident = val;
                }
            })
        } else {
            None
        }
    })
    .collect();

// ... 最終的なimplブロックに挿入 ...
let gen = quote! {
    impl #ident {
        // ... 他の生成コード ...
        #(#property_methods)* // ここでゲッター/セッターが展開される
    }
};
// ...

Luaのメタテーブルによるプロパティアクセス

Luaでitem.idやitem.id = 123のようなプロパティアクセスを可能にするには、Luaのメタテーブル機能を利用します。

プロパティの取得 (__index メタメソッド)

Luaでval.keyのようなアクセスが行われた際、対象のオブジェクトに__indexメタメソッドが設定されていると、その関数が呼び出されます。Rust側のバインディングでは、この__indexメタメソッドを実装するC関数（あるいはextern "C"なRust関数）を登録します。

このC関数は、Luaのスタックからアクセス対象のオブジェクトとキー名を取得します。そして以下のロジックに従って値を返します。

1. まず、要求されたkeyが、当該Rustオブジェクトに登録されているインスタンスメソッド（例: check_status）に対応するかどうかを確認します。対応する場合、そのRustメソッドのLuaクロージャをスタックにプッシュし、Luaへ返します。
2. 次に、keyが#[lua_field_prop]でマークされたプロパティ名（例: id, description）に対応するかどうかを確認します。この判定は、バインディングシステムが内部的に管理するプロパティ名とゲッター関数のマッピングを通じて行われます。
3. プロパティに対応する場合、オブジェクトのインスタンスから実際のフィールド値を取得するために、対応するゲッターメソッド（例: get_id_value）を呼び出します。取得したRustの値をLuaの型に変換し、スタックにプッシュして返します。
4. いずれにも該当しない場合は、nilを返すか、エラーを発生させます。

プロパティの設定 (__newindex メタメソッド)

同様に、Luaでval.key = valueのような代入が行われた際、対象のオブジェクトに__newindexメタメソッドが設定されていれば、その関数が呼び出されます。Rust側では、この__newindexメタメソッドを実装するC関数を登録します。

このC関数は、Luaのスタックからアクセス対象のオブジェクト、キー名、そして設定される値を取得します。そして以下のロジックに従って処理を行います。

1. 要求されたkeyが、#[lua_field_prop]でマークされたプロパティ名に対応するかどうかを確認します。
2. プロパティに対応する場合、スタックから取得したLuaのvalueをRustの適切な型に変換し、対応するセッターメソッド（例: set_id）を呼び出して、Rustオブジェクトのフィールドを更新します。
3. 対応しない場合は、Luaエラーを発生させます。

まとめ

Rustの手続き型マクロは、複雑になりがちなFFIバインディング層の記述を大幅に簡素化する強力なツールです。本稿で紹介したアプローチにより、Rustの構造体をLuaに公開する際のボイラープレートコードを自動生成し、RustとLua間でのデータ連携を効率的かつ透過的に実現できます。これにより、両言語の強みを最大限に活かしたアプリケーション開発が可能となります。